docscan: language-aware documentation coverage via external analyzer protocol

[jflowers]

Summary

gaze docscan today is a language-agnostic Markdown doc-quality pass (README quality, tutorial coverage, API-reference completeness). That is a reasonable first phase, but it cannot answer language-specific documentation-coverage questions because it never consults a language analyzer. This issue proposes a second, analyzer-aware mode for docscan that consumes the external analyzer protocol output so documentation can be validated against the actual API surface of a project in any supported language.

Background: two designs

Design (1) — universal doc scan (current, shipped).
Language-agnostic Markdown scan. Runs with no analyzer. Good for repo-wide doc hygiene. This is what the dev binary ships today.

Design (2) — language-aware doc coverage (requested).
A doc pass that first calls the external analyzer's discover + analyze (and optionally classify_signals) for the project's language, then cross-references documentation against the real symbol/API surface.

Capabilities enabled by Design (2)

• Embedded code-block validation — verify fenced code blocks are syntactically valid for that language (delegated to the analyzer), not just present.
• Symbol-reference validation — verify identifiers referenced in docs actually exist in the analyzed API surface (e.g. snake-eyes analyze_path() / FunctionRecord), catching drift when APIs are renamed/removed.
• Convention-aware doc coverage — "which public functions/classes/modules are undocumented?" using language conventions (Python module/class/function docstrings vs Go package/func comments). The analyzer already knows the public surface and its doc strings.

Dependency

Design (2) depends on the external analyzer protocol (#95, designed/Done) actually being wired into the gaze binary first. The current dev binary has no --analyzer flag and no JSON-RPC spawn/client for external analyzers, so it is Go-only in practice. This issue should be scheduled after external-analyzer support lands.

Reference implementation available

snake-eyes (zero-dot-force/snake-eyes) already implements the full analyzer protocol over JSON-RPC 2.0 stdio and exposes everything Design (2) needs:

• discover → source file list
• analyze → FunctionRecords (function name, package, file, line, side effects)
• docstrings via Python ast
• classify_signals → raw contractual signals

It is ready to serve as the first polyglot docscan target once gaze can drive external analyzers.

Proposed scope

• Add an analyzer-aware mode to docscan (e.g. --analyzer/language selection or .gaze.yaml analyzer config) that invokes discover/analyze and reports language-specific doc coverage.
• Keep Design (1) as the default/fallback when no analyzer is configured.

Filed while integrating snake-eyes (Python analyzer) with gaze; surfaced because docscan was the one command that appeared language-agnostic by design rather than by limitation.