Skip to content

Move x-demo-lang symbol semantics behind the puzzle module seam #48

Closed

Description

@e54-bot

Goal

Concentrate x-demo-lang symbol and edit semantics inside the puzzle module so that methods.rs is a pure protocol adapter: it shapes wire params and response envelopes, and asks the language module named questions instead of deriving semantics from AST fields.

Context

An architecture review of the conformance suite (2026-10-06, against b4be4d2 / release 1.5.0) found the deepest leak in the mock provider: roughly 200 LOC in methods.rs is x-demo-lang semantics, not protocol logic.

  • symbol_at_position, puzzle_symbols, and rename_edits live in the wire-adapter module.
  • The definition, references, and rename handlers each re-derive declaration-vs-reference rules from Puzzle's public fields (name, ops, solution, name_range, arg, ...), so the same language semantics exist as three private derivations.
  • puzzle exposes its whole AST — ~20 re-exported names plus public struct fields — so the seam is wide and shallow: callers do the interpreting.
  • The moved helpers are reachable only through spawned-process fixtures today, while puzzle/tests.rs is an existing unit-test surface at exactly this seam.
  • The mock is the reference implementation third-party provider authors read and copy; "language answers queries, adapter shapes wire" is the structure it should demonstrate.

Scope

  • conformance/mock-provider only: methods.rs, puzzle.rs, puzzle/*.
  • Move language-aware symbol/edit logic (document-symbol listing, declaration lookup, occurrence collection, rename-target classification and edit planning) behind the puzzle module's interface as typed query results.
  • Keep protocol-owned concerns in methods.rs: wire param shapes, response envelopes, and the method-namespaced refusal codes (definition.noSymbolAtPosition, etc.).
  • Once no caller derives semantics from AST fields, Puzzle/Op/SolutionEntry fields can stop being public.

Non-goals

  • No wire-contract, spec, or fixture changes. Zero protocol-visible behavior change.
  • No new x-demo-lang features or methods.
  • No changes to the runner or to puzzle's lex/parse correctness work.
  • Does not prescribe the exact query names/signatures — that is implementation detail, not contract.

Constraints

  • The full conformance fixture suite must pass unchanged: lpp-conformance-runner --provider ./target/release/lpp-mock-provider --fixtures conformance/fixtures/v1.
  • cargo test --workspace, cargo clippy --all-targets -- -D warnings, cargo fmt --all --check stay green.

Acceptance criteria

  • methods.rs no longer inspects Puzzle/Op/SolutionEntry fields to derive declarations, references, or rename edits; the definition/references/rename/symbols handlers obtain results through puzzle-module queries.
  • The moved semantics are covered by unit tests under puzzle/tests.rs, not only by end-to-end fixtures.
  • The fixture suite passes with zero fixture changes; refusal codes and response shapes are byte-identical on the wire.
  • Deletion test passes: removing any single moved helper no longer spreads x-demo-lang logic across methods.rs.

Dependencies / ownership

  • language-provider-protocol owns the reference mock provider; no cross-repository work.

Readiness

Ready for implementation. Internal refactor with an existing verification boundary (unit-test harness plus the unchanged conformance suite); no product, architecture, or contract decision is open.

Activity

  1. e54-bot commented on Oct 6, 2026

    @e54-bot
    ContributorAuthor

    Implemented and merged via #52 (cac0139, now in main at e78b532). Verified against the acceptance criteria:

    • methods.rs no longer inspects Puzzle/Op/SolutionEntry fields — symbols/definition/references/rename go through puzzle-module queries (document_symbols, declaration_range, occurrences, rename_collides, rename_ranges); the only remaining puzzle.* call is the simulate() interface.
    • Moved semantics are unit-tested in puzzle/tests.rs (document_symbols, symbol_at, declaration_range, occurrences, rename_ranges).
    • Zero fixture changes; the full suite passes 61/61 on the merged result.
    • Symbol semantics concentrated in the new puzzle/symbols.rs module; Puzzle's fields are now private.

    Closing as complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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