Skip to content

grammar: render any grammar in Plotnik syntax, with single-rule retrieval #430

Description

@zharinov

Promote grammar rendering to a top-level grammar <locator> [rule] command, backed by a rewrite of the renderer. The current GrammarRenderer (crates/plotnik-cli/src/commands/lang.rs) is the v1 format this redesign explicitly replaces.

Why the v1 format is wrong

The current renderer descends into token internals as if they were children, shows inline-listed rules as queryable nodes, leaks hidden rules into supertype member lists, prints underscore-prefixed category names the query language can't even say, and is unconditionally one-item-per-line (a mid-size grammar → ~2,500 lines). It renders how text parses; query authors need how trees are shaped.

Design: three registers

Every definition body is in exactly one register, each lexically distinct so they can't be confused:

Register Definitions Body syntax Example
Pattern node shapes, hidden rules real plotnik query syntax pair = {key: (string) ":" value: (value#)}
Type categories (supertypes) bare names joined by | value# = object | array | number | string
Text tokens string literal or regex number = /-?(0|[1-9]\d*)(\.\d*)?/

This replaces v1's single overloaded notation that used the same marker ((_x ...)) for opposite things.

First-class categories

Tree-sitter supertypes become a named feature with suffix-# syntax (expression#, (expression#call_expression)), de-underscored names, and contextual-refinement semantics. Uses #, not the deprecated tree-sitter /. The dump's category section is the discovery surface for that feature.

Current state (audit)

Entirely unbuilt. The renderer uses a single uniform render_rule() (lang.rs:135-233), emits :: supertype = (not # / |-union), taps RawGrammar at the start of the pipeline (not ExtractedSyntaxGrammar + node-shapes), lives in plotnik-cli, and has no fragment API or single-rule retrieval.

Scope

Acceptance

  • plotnik grammar typescript and plotnik grammar typescript call_expression (rule + referenced shapes).
  • Native plotnik syntax with # refinements; tokens in the text register; no hidden-rule leakage; compact (not one-per-line).
  • Unknown rule → did-you-mean.
  • Diagnostics consume the same fragment API.

Companion to the grammar-based-validation issues (diagnostics consumer) and the supertype work (#417 interim reject, #423 implementation). Locator support: #429.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions