Skip to content

feat: self-describing syntax feature registry for LLM-friendly help discovery#252

Merged
ako merged 6 commits intomainfrom
fix/172-syntax-feature-registry
Apr 22, 2026
Merged

feat: self-describing syntax feature registry for LLM-friendly help discovery#252
ako merged 6 commits intomainfrom
fix/172-syntax-feature-registry

Conversation

@ako
Copy link
Copy Markdown
Collaborator

@ako ako commented Apr 22, 2026

Summary

  • Rebased PR RFC: Self-describing syntax feature registry for LLM-friendly help discovery #172 (originally by @engalar / wengao liu) onto main after contributor could not address merge conflicts
  • Adds a cmd/mxcli/syntax/ package with a SyntaxFeature registry covering ~80 feature paths across domain-model, microflow, page, security, workflow, integration, navigation, settings, and misc
  • Replaces the flat help_topics/*.txt files with structured registry entries — each feature has Path, Summary, Keywords, Syntax, Example, and SeeAlso
  • Adds mxcli syntax [topic...] command with --json output for LLM-friendly one-shot discovery
  • Adds HELP [topic words...] MDL command with registry-backed topic lookup from the REPL
  • Topic aliases (e.g. entity → domain-model.entity) shared between CLI and REPL via syntax.ResolveAlias()

Conflict resolution notes

  • ANTLR-generated files: regenerated via make grammar at each conflict
  • executor_dispatch.go: kept HEAD's registry-based dispatch (replaced PR's switch statement)
  • cmd_misc.go: merged PR's topic-handling into HEAD's ctx *ExecContext pattern; execHelp(ctx, s) now accepts statement
  • register_stubs.go: updated HelpStmt registration to pass statement to execHelp
  • help.go Phase 4/5: topicAliases moved to syntax.ResolveAlias() in registry; added agents aliases to both
  • New feature (not in PR): Added agents / agents.model / agents.knowledge-base / agents.mcp-service / agents.agent registry entries for AI agent documents (from help_topics/agents.txt which was added to main after the PR was created)

Closes #172

Test plan

  • make build && make test pass
  • mxcli syntax --json outputs full registry
  • mxcli syntax workflow user-task targeting drills down correctly
  • mxcli syntax agents shows AI agent syntax
  • HELP workflow user task; in REPL returns registry entry
  • mxcli syntax entity resolves alias → domain-model.entity

🤖 Generated with Claude Code

@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 22, 2026

AI Code Review

Approve

This PR replaces the fragmented help system with a structured, LLM-friendly syntax registry while maintaining backward compatibility through topic aliases. Key strengths include eliminating duplication, adding JSON output for machine consumption, enabling drill-down topic navigation, and sharing aliases between CLI and REPL. The implementation follows the project's architectural patterns and updates the help system comprehensively.

Moderate concerns about test coverage visibility and full-stack verification are mitigated by:

  1. The PR's explicit test plan covering all new functionality
  2. Conflict resolution notes confirming ANTLR regeneration and proper integration
  3. The structured nature of changes reducing risk of missing components

The new HELP MDL command appropriately follows documentation/querying patterns (similar to SHOW) and reads as English. Code quality improvements from removing redundant help files outweigh minor help text phrasing issues. Recommend approval with standard verification of test additions and pipeline completion.

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

engalar and others added 6 commits April 22, 2026 09:57
@engalar @ako
docs: propose self-describing syntax feature registry for LLM-friendl…
58ebd67 
…y help discovery

Current help system is flat (26 monolithic .txt topics) with no drill-down,
no structured output, and no way for LLMs to bridge from business concepts
to MDL syntax. Proposes a SyntaxFeature registry where each syntax construct
self-registers with metadata (path, summary, keywords, example), enabling:
- `mxcli syntax --json` for one-shot LLM discovery
- Hierarchical drill-down (workflow → user-task → targeting)
- Single-file changes when adding new features
@claude @ako
feat: implement syntax feature registry (Phase 1)
680e7a9 
Registry core with workflow (12) and security (8) features registered,
--json output, hierarchical drill-down, legacy .txt fallback.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude @ako
feat: migrate all help topics to syntax feature registry (Phase 2)
a3569fa 
95 features registered across 7 domain files: domain-model (18),
microflow (13), page/snippet/fragment (16), navigation/settings/misc (12),
integration/odata/rest/sql/xpath (20), workflow (12), security (8).
Legacy topic aliases map old names to new registry paths.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude @ako
feat: HELP command with topic parameters (Phase 3)
e7ba2cb 
HELP WORKFLOW; HELP WORKFLOW USER TASK; HELP SECURITY ENTITY ACCESS;
all now query the syntax feature registry. Greedy path resolver
merges space-separated words into hyphenated registry paths.

Grammar extended: helpStatement accepts optional identifierOrKeyword*.
AST HelpStmt gains Topic []string field.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude @ako
refactor: remove help_topics/ and legacy code (Phase 4)
53c11b3 
Delete 25 .txt files, embedded FS, switch statement, showKeywords/
showTypes/showDeleteBehaviors functions, and reservedKeywords/
attributeTypes/deleteBehaviors data. All topics now served from
the syntax feature registry with full alias map for backward compat.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude @ako
fix: share topic aliases between CLI and REPL, add tests and missing …
8f7533b 
…help topic

- Move topicAliases to syntax package so HELP <topic> works in REPL (was broken: HELP entity returned "No syntax help found")
- Add duplicate path detection in Register() (panic on duplicate)
- Register missing 'test' help topic (replaced deleted test.txt)
- Fix capitalize() for UTF-8 safety
- Add unit tests for resolveHelpPath and ResolveAlias
- Add TestAliasTargetsExist to verify all aliases point to valid paths
- Add doctype-test for HELP command

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@ako ako force-pushed the fix/172-syntax-feature-registry branch from 42ab5db to 8f7533b Compare April 22, 2026 11:49
@ako ako merged commit 52eff3c into main Apr 22, 2026
4 of 6 checks passed
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 22, 2026

AI Code Review

Critical Issues

  • None found

Moderate Issues

  • Missing test coverage for new package: The PR introduces a new package cmd/mxcli/syntax but no test files are visible in the diff. New packages should have corresponding test files to validate registry functionality, alias resolution, and hierarchical lookup.

Minor Issues

  • None found

What Looks Good

  • Clean replacement of legacy help system: Replaces static help_topics/*.txt files with a structured registry, improving maintainability and enabling programmatic access.
  • LLM-friendly design: The --json flag and hierarchical topic drilling (e.g., mxcli syntax workflow user-task targeting) provide machine-readable output optimized for AI consumption.
  • Unified help experience: Shares topic aliases between CLI (mxcli syntax) and REPL (HELP command) via syntax.ResolveAlias(), ensuring consistency.
  • Proper conflict resolution: Correctly handled ANTLR regeneration and merges (e.g., keeping HEAD's executor dispatch, integrating topic handling into existing ExecContext pattern).
  • Thoughtful feature inclusion: Added AI agent documentation topics (agents.*) that were recently added to main branch, demonstrating awareness of evolving features.
  • Cleanup of dead code: Removed 13 help topic files and associated legacy handling logic, reducing maintenance burden.

Recommendation

Request changes to add unit tests for the new cmd/mxcli/syntax package. Specifically:

  • Test registry population from all feature paths
  • Verify alias resolution (e.g., entity → domain-model.entity)
  • Test hierarchical prefix matching (workflow user-task)
  • Validate JSON and text output formats

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

@hjotha hjotha mentioned this pull request Apr 22, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@ako @engalar