Optional bounded LSP semantic-provider layer for compiler-resolved graph evidence

[kerberosmansour]

Problem

Graphify's deterministic AST extractors provide broad, fast language coverage, but some cross-file facts only become reliable after a project's compiler or language service has resolved modules, overloads, generated metadata, and workspace configuration.

The existing LLM semantic pass is valuable for documents and higher-level concepts; it is not a substitute for compiler-reported symbol, reference, implementation, and call-hierarchy facts.

Proposed direction

Add an optional, local, bounded language-provider layer that can enrich (never replace) the native AST graph:

• a small provider contract and deterministic registry;
• a generic stdio Language Server Protocol adapter;
• argv-only process execution (shell=False), workspace confinement, time/message/file/request budgets, and explicit unavailable / failed / budget_exhausted outcomes;
• provider/run/range provenance on every imported fact;
• additive merge into a separate output by default;
• reconciliation with native nodes only when (source_file, label) has exactly one match; ambiguous symbols remain separate;
• operator-trusted JSON manifests so an additional language server is configuration rather than a new runner implementation.

Initial built-in profiles would cover mainstream application stacks through maintained language servers: Rust, TypeScript/JavaScript, Java, Kotlin, C#, Python, Go, PHP, and Ruby. No language-server binary would be bundled or required for Graphify's normal operation.

Why this complements the current architecture

• Native tree-sitter extraction remains the always-available source of structural truth.
• Language-server evidence is a typed, local, opt-in enrichment source.
• The provider layer does not change Graphify's LLM backend selection or document-semantic flow.
• It is complementary to feat: add native and automatic semantic updates #2941: that PR concerns when/how Graphify refreshes its existing semantic pipeline; this proposal concerns an additional evidence source with its own bounded execution contract.
• The same evidence contract could later admit analysis providers, but scanner findings should remain a separate provider kind with separate trust and severity semantics.

Suggested first PR boundary

1. Provider/run contracts, registry, generic bounded LSP adapter, additive merge, CLI, and documentation.
2. Protocol-level tests for all profiles, plus real-tool smoke evidence for an available subset.
3. No automatic installation, no default execution, no network fetching, no mutation of source files, and no integration into the existing graphify extract command in this first change.

Acceptance checks

• Graphify behaves byte-for-byte as before when the extension is unused.
• A missing or failing language server cannot remove AST nodes/edges.
• Explicit provider selection does not silently widen to auto-selection.
• Out-of-root locations and symlink escapes are rejected.
• Limits are visible and never silently expanded.
• Provider output records provenance without source text, environment variables, server stderr, or model reasoning.
• The full upstream test suite, lint, type check, security scan, and package/install smoke tests remain green.

If this direction fits the project, I will open a focused PR against v8 implementing only this boundary and cross-reference it here.

[kerberosmansour]

Implementation is now available in #2951. The PR keeps the proposed first boundary intact: optional/no-bundle LSP profiles, bounded local execution, provenance, additive separate-output merge, protocol coverage for all profiles, and real-tool smoke evidence for Rust, TypeScript/JavaScript, and Python.