Luigit
repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by admin

.system/plans/PX-PLAN-LSPCP6R4-lsp-navigation-complete/index.md

Raw
Rendered preview

id: PX-PLAN-LSPCP6R4 type: plan title: Complete LSP Navigation spec: PX-SPEC-LSP4N8Q2 status: approved depends_on:

  • PX-PLAN-LSPMV8Q2

Outcome

Complete Agent LSP Navigation: semantic navigation/discovery, one-hop calls, maintainable reviewed registry updates, and representative Go/TypeScript/C++ use. Build on MVP; preserve its usable queries, lifecycle bounds, and uncertainty contract.

Behavior dependencies

MVP queries underpin richer navigation and registry maintenance; integrated cross-server use exercises both.

flowchart TB
  M["MVP semantic queries"] --> N["Types and implementations"]
  N --> S["Discover symbols"]
  S --> C["Inspect one-hop calls"]
  M --> R["Refresh reviewed defaults"]
  C --> V["Use Go, TypeScript, and C++"]
  R --> V

Ordered behaviors

  1. Follow types and implementations. Extend extensions/lsp/src/tool.ts, client.ts, and result.ts with type definition and implementations; retain one tool and shared bounds. Check current server capabilities and applicable registrations, not a maintained per-language support matrix. Normalize supported location forms and preserve meaningful server failures; do not substitute syntactic approximations.

  2. Discover declarations without an initial source position. Add document/workspace symbols through the same tool/client/result modules; registry.ts resolves workspace-specific discovery context. Support hierarchical/flat document results and capability-appropriate workspace symbol resolution. Keep qualified names, locations, and result caps compact; disclose server completeness as unknown even when no client truncation occurred. Verify the experimentally observed case where server limits omit known symbols without a truncation marker.

  3. Inspect incoming and outgoing calls. Add two-step call hierarchy handling within tool.ts/client.ts; preserve prepared server metadata and its session/source context. Ambiguous preparation returns actionable candidates; an explicit selection continues the query, while invalidated selections are rejected or re-resolved visibly. source.ts/result.ts attribute incoming call-site ranges to returned callers and outgoing ranges to the queried caller, including cross-file edges. Bound work to one hop; distinguish preparation/no-result/empty-relationship evidence without inventing readiness or runtime completeness.

  4. Refresh supported defaults without runtime catalog coupling. Add extension-owned development helper scripts/registry.ts, explicit source/local-override policy under registry/, and registry-refresh Mise task. Fetch pinned Helix revisions as primary data; permit explicitly selected lsp-bridge supplements only where needed by supported profiles. Reuse existing repository parsing tools where suitable; upstream catalogs are data, never executable editor configuration. Normalize only launch, language/file/root, required initialization/settings, and provenance fields; reject unresolved machine paths/placeholders and preserve license notices. Compare imported changes with prior source values and local overrides; surface conflicting field changes rather than silently choosing a winner. Produce reviewable diffs; replace registry/servers.json only after successful validation, leaving previous usable data intact on fetch/parse/conflict/interruption failures. Runtime registry.ts consumes only packaged reviewed data, never importer code, upstream URLs, or checkout-relative dependencies.

  5. Use complete navigation across representative servers. Add reviewed TypeScript language-server and clangd profiles alongside gopls; preserve explicit missing-executable behavior and no runtime installation. Extend source/session tests for distinct roots, profile/config changes, URI/platform paths, non-ASCII positions, source-context races, and late responses. README.md, tool descriptions, and results explain supported operations, actionable ambiguity, unknown completeness/freshness, and native-server side-effect boundaries without adding a sandbox policy. Rebuild and verify relocated package plus live Pi sessions; registry refresh or protocol dependency updates must not silently alter public tool semantics.

Verification

  • Extend required Pi contract tests and owned protocol peers across every added operation, unsupported capabilities, registration changes, ambiguity/selection invalidation, budgets, and server-requested mutation denial.
  • Importer fixtures cover pinned sources, local overrides, simultaneous upstream/local edits, unavailable catalogs, malformed data, licensing/provenance, interrupted publication, and deterministic regeneration.
  • registry-refresh remains out of normal runtime/startup and fast test loops; importer tests use local fixtures, not live upstream availability.
  • Extend //extensions/lsp:live for built native Pi tool with real gopls, TypeScript language server, and clangd; report actual capabilities and unavailable operations, never approximate fallbacks.
  • Real-server checks cover known declarations/usages, both call directions with separate caller/callee files, UTF-8/UTF-16 conversion, edits, and clean process exits.
  • Deterministic peers cover naturally hard-to-trigger ambiguity, unsupported operations, timeouts, stale selections, and cancellation races; do not claim these replace real-server behavior.
  • Re-run extension lint, test, check, verify-package, live acceptance, and root //:check at integration; validate added Mise configuration and remeasure context impact.

Exit criteria

  • Every in-scope operation is reachable through one Pi tool, capability-dependent, bounded, and faithful to the spec's uncertainty semantics.
  • Cross-file call-site ownership and actionable ambiguous-target selection are verified without recursive graph construction.
  • Explicit registry refresh preserves reviewed local decisions and provenance, reports conflicts, and cannot publish partial/unusable defaults.
  • Packaged registry works without upstream catalog access or repository files; installed-server prerequisites remain external and explicit.
  • Representative native Pi/server queries, adversarial lifecycle cases, relocation, and existing MVP regressions pass with recorded evidence.
  • Every spec acceptance criterion has concrete verification or remains explicitly blocked; unverified behavior is not marked complete.

Scope guard

No diagnostics UI, completion integration, rename, formatting, code actions, automatic repairs, server installation, Helix runtime, generic editor-config interpreter, or automatic protocol/catalog migration.

---
id: PX-PLAN-LSPCP6R4
type: plan
title: Complete LSP Navigation
spec: PX-SPEC-LSP4N8Q2
status: approved
depends_on:
  - PX-PLAN-LSPMV8Q2
---

## Outcome

Complete [Agent LSP Navigation](../../specs/PX-SPEC-LSP4N8Q2-agent-lsp-navigation/index.md): semantic navigation/discovery, one-hop calls, maintainable reviewed registry updates, and representative Go/TypeScript/C++ use.
Build on [MVP](../PX-PLAN-LSPMV8Q2-lsp-navigation-mvp/index.md); preserve its usable queries, lifecycle bounds, and uncertainty contract.

## Behavior dependencies

MVP queries underpin richer navigation and registry maintenance; integrated cross-server use exercises both.

```mermaid
flowchart TB
  M["MVP semantic queries"] --> N["Types and implementations"]
  N --> S["Discover symbols"]
  S --> C["Inspect one-hop calls"]
  M --> R["Refresh reviewed defaults"]
  C --> V["Use Go, TypeScript, and C++"]
  R --> V
```

## Ordered behaviors

1. **Follow types and implementations.**
   Extend `extensions/lsp/src/tool.ts`, `client.ts`, and `result.ts` with type definition and implementations; retain one tool and shared bounds.
   Check current server capabilities and applicable registrations, not a maintained per-language support matrix.
   Normalize supported location forms and preserve meaningful server failures; do not substitute syntactic approximations.

2. **Discover declarations without an initial source position.**
   Add document/workspace symbols through the same tool/client/result modules; `registry.ts` resolves workspace-specific discovery context.
   Support hierarchical/flat document results and capability-appropriate workspace symbol resolution.
   Keep qualified names, locations, and result caps compact; disclose server completeness as unknown even when no client truncation occurred.
   Verify the experimentally observed case where server limits omit known symbols without a truncation marker.

3. **Inspect incoming and outgoing calls.**
   Add two-step call hierarchy handling within `tool.ts`/`client.ts`; preserve prepared server metadata and its session/source context.
   Ambiguous preparation returns actionable candidates; an explicit selection continues the query, while invalidated selections are rejected or re-resolved visibly.
   `source.ts`/`result.ts` attribute incoming call-site ranges to returned callers and outgoing ranges to the queried caller, including cross-file edges.
   Bound work to one hop; distinguish preparation/no-result/empty-relationship evidence without inventing readiness or runtime completeness.

4. **Refresh supported defaults without runtime catalog coupling.**
   Add extension-owned development helper `scripts/registry.ts`, explicit source/local-override policy under `registry/`, and `registry-refresh` Mise task.
   Fetch pinned Helix revisions as primary data; permit explicitly selected lsp-bridge supplements only where needed by supported profiles.
   Reuse existing repository parsing tools where suitable; upstream catalogs are data, never executable editor configuration.
   Normalize only launch, language/file/root, required initialization/settings, and provenance fields; reject unresolved machine paths/placeholders and preserve license notices.
   Compare imported changes with prior source values and local overrides; surface conflicting field changes rather than silently choosing a winner.
   Produce reviewable diffs; replace `registry/servers.json` only after successful validation, leaving previous usable data intact on fetch/parse/conflict/interruption failures.
   Runtime `registry.ts` consumes only packaged reviewed data, never importer code, upstream URLs, or checkout-relative dependencies.

5. **Use complete navigation across representative servers.**
   Add reviewed TypeScript language-server and clangd profiles alongside gopls; preserve explicit missing-executable behavior and no runtime installation.
   Extend source/session tests for distinct roots, profile/config changes, URI/platform paths, non-ASCII positions, source-context races, and late responses.
   `README.md`, tool descriptions, and results explain supported operations, actionable ambiguity, unknown completeness/freshness, and native-server side-effect boundaries without adding a sandbox policy.
   Rebuild and verify relocated package plus live Pi sessions; registry refresh or protocol dependency updates must not silently alter public tool semantics.

## Verification

- Extend required Pi contract tests and owned protocol peers across every added operation, unsupported capabilities, registration changes, ambiguity/selection invalidation, budgets, and server-requested mutation denial.
- Importer fixtures cover pinned sources, local overrides, simultaneous upstream/local edits, unavailable catalogs, malformed data, licensing/provenance, interrupted publication, and deterministic regeneration.
- `registry-refresh` remains out of normal runtime/startup and fast test loops; importer tests use local fixtures, not live upstream availability.
- Extend `//extensions/lsp:live` for built native Pi tool with real gopls, TypeScript language server, and clangd; report actual capabilities and unavailable operations, never approximate fallbacks.
- Real-server checks cover known declarations/usages, both call directions with separate caller/callee files, UTF-8/UTF-16 conversion, edits, and clean process exits.
- Deterministic peers cover naturally hard-to-trigger ambiguity, unsupported operations, timeouts, stale selections, and cancellation races; do not claim these replace real-server behavior.
- Re-run extension `lint`, `test`, `check`, `verify-package`, live acceptance, and root `//:check` at integration; validate added Mise configuration and remeasure context impact.

## Exit criteria

- [ ] Every in-scope operation is reachable through one Pi tool, capability-dependent, bounded, and faithful to the spec's uncertainty semantics.
- [ ] Cross-file call-site ownership and actionable ambiguous-target selection are verified without recursive graph construction.
- [ ] Explicit registry refresh preserves reviewed local decisions and provenance, reports conflicts, and cannot publish partial/unusable defaults.
- [ ] Packaged registry works without upstream catalog access or repository files; installed-server prerequisites remain external and explicit.
- [ ] Representative native Pi/server queries, adversarial lifecycle cases, relocation, and existing MVP regressions pass with recorded evidence.
- [ ] Every spec acceptance criterion has concrete verification or remains explicitly blocked; unverified behavior is not marked complete.

## Scope guard

No diagnostics UI, completion integration, rename, formatting, code actions, automatic repairs, server installation, Helix runtime, generic editor-config interpreter, or automatic protocol/catalog migration.