Internal out-of-process analyzer protocol over stdio JSON

[serge-ivo]

Summary

Define the internal out-of-process analyzer protocol before exposing any public plugin SDK. This is needed for built-in non-TypeScript analyzers and external tools such as graphify, Flutter/Dart, .NET, and Java analyzers.

Implementation spec: cli/docs/out-of-process-analyzers.md.

Why

The roadmap says the CLI is the single analyzer engine, but not every analyzer should be TypeScript in-process code. A .NET analyzer may be written in .NET, a Java analyzer may use JVM parsers, Flutter can shell out to Dart tools, and graphify already runs externally. The boundary should be process-isolated and JSON-based before it is public.

v0 framing

v0 uses one JSON request on stdin and one JSON response on stdout. Streaming events are separate scan-stream/tool-log work.

vcqa cli core
  starts analyzer process
    -> AnalyzerProcessRequest JSON on stdin
    <- AnalyzerProcessResult JSON on stdout
  captures stderr as diagnostic output/provenance

Tasks

• Define AnalyzerProcessRequest JSON: cwd, stack, workspace, active language profiles, settings, ignore paths, scan id.
• Define AnalyzerProcessResult JSON: check result, metrics, artifacts, warnings, effective settings.
• Decide framing: v0 is one JSON request on stdin and one JSON response on stdout.
• Add timeout, crash, stderr, and malformed-output handling.
• Attribute errors to the analyzer without crashing the whole scan.
• Add a local fixture analyzer process for conformance tests.
• Keep this internal: no remote registry, no marketplace, no third-party trust prompts yet.

Acceptance criteria

• CLI can run a toy analyzer out of process and merge its output into a normal VibeReport.
• Crashes/timeouts produce auditable skipped/error check results.
• Tool output/provenance is preserved.
• The protocol is documented as internal/experimental.

Related

• Umbrella: Tracking: analyzer-platform groundwork (schema, stack-gating, fixtures, engine decision) #24
• Spec: cli/docs/out-of-process-analyzers.md
• Internal analyzer contract: Internal analyzer contract: replace hardcoded runner registry with typed analyzers #28
• Vision doc Phase 6, with note that protocol work comes before public SDK work

[serge-ivo]

Implementation spec drafted: cli/docs/out-of-process-analyzers.md.

The v0 protocol is intentionally internal: one JSON request on stdin, one JSON response on stdout, captured stderr/provenance, and explicit timeout/malformed-output/crash handling. Public plugin SDK and marketplace concerns remain deferred.