#!/usr/bin/env python3
"""
ocr_module_data.py — single source of truth for OCR's review-lifecycle stages and
per-package module descriptions. Imported by both tools/generate_architecture_html.py
(the interactive explainer) and tools/gen_module_docs.py (per-package Markdown docs) so
the same source-verified prose never has to be maintained in two places (rule 9 in the
Visa project's templates/README.md: never hand-maintain a second copy of generated
content). Edit this file, then re-run both generators.
"""

STAGES = [
 {"id":"plan","name":"Plan phase (optional)","phase":"per-file","skill":"PLAN_TASK","backend":"same LLM client as main loop",
  "simple":"For a large enough change, the model first sketches a short review plan before diving in — skipped for small diffs below a configurable line threshold.",
  "tech":"agent.executePlanPhase: one LLM call using the template's plan_task messages, only when Template.PlanTask is set and the diff's changed-line count is at/above Template.PlanModeLineThreshold. Result is interpolated into the main prompt as {{plan_guidance}}.",
  "in":"diff text, file path, sibling changed files, path-matched review rule","out":"free-text review plan (or empty if skipped/failed — the run continues either way)"},
 {"id":"main_loop","name":"Main tool-use loop","phase":"per-file","skill":"MAIN_TASK","backend":"internal/llm via internal/llmloop.Runner",
  "simple":"The model has a real conversation with the codebase: it can ask to read a file, search for a pattern, or look at another changed file's diff, as many times as it needs, before deciding what to say.",
  "tech":"llmloop.Runner.RunPerFile loops up to Template.MaxToolRequestTimes rounds, sending the growing message list plus MainToolDefs and executing whatever tool calls come back via executeToolCall. Stops on task_done, StopMaxRounds (grace round fires), StopEmptyRounds (3 consecutive rounds with no usable tool result), or StopCompression.",
  "in":"rendered main_task prompt (diff, rule, plan_guidance, background)","out":"zero or more code_comment tool calls + a terminal task_done"},
 {"id":"tool_exec","name":"Tool execution","phase":"per-round","skill":"n/a — deterministic dispatch","backend":"no model call in this step itself",
  "simple":"Whatever the model asks for — read a file, search code, leave a comment — is carried out by plain Go code, not by another AI call, and the result is handed back to the model.",
  "tech":"Runner.executeToolCall dispatches by tool.Tool: built-ins (file_read, file_find, file_read_diff, code_search) run tool.Provider.Execute synchronously; code_comment parses + resolves line numbers (diff.ResolveComment, falling back to a re-location LLM call only if the deterministic resolver fails) and can run on a background CommentWorkerPool; unknown names are looked up as dynamic MCP tools.",
  "in":"one llm.ToolCall","out":"a tool.ToolCallResult string appended to the conversation"},
 {"id":"filter","name":"Review filter (optional)","phase":"per-file, after main loop","skill":"REVIEW_FILTER_TASK","backend":"same LLM client, unless --no-filter",
  "simple":"A second pass that can drop comments the model itself, on reflection, decides are low-value or noisy — a quality gate, not a rubber stamp.",
  "tech":"Runs only if the template defines review_filter_task and --no-filter was not passed; operates on the file's collected comments after the main loop and any async CommentWorkerPool jobs for that file have drained.",
  "in":"file's collected LlmComment[]","out":"filtered LlmComment[] (subset)"},
 {"id":"persist","name":"Session persist + manifest","phase":"end of run","skill":"n/a — deterministic","backend":"no model call",
  "simple":"Every run leaves a paper trail: what was reviewed, what was skipped and why, and enough of a checkpoint that an interrupted run can pick up where it left off instead of starting over.",
  "tech":"session.ManifestBuilder registers every dispatchable diff before dispatch (registerCoverage/SealSelected), then Mark{{Completed,Reused,Failed}} per item; Agent.finalizeManifest freezes it and session.Finalize() flushes the run's JSONL. --resume replays a prior session's ResumeState to skip already-completed items.",
  "in":"per-item outcome (completed/reused/failed + reason)","out":"session JSONL + RunManifest (coverage denominator, resume lineage)"},
]

MODULES = [
 {"id":"cli","name":"CLI","layer":"1 · Entry","color":"#D2E3FC",
  "pkg":"cmd/opencodereview/",
  "in":"CLI args/flags, config.json, rule.json, environment variables",
  "out":"a fully-populated agent.Args / scan.Args, dispatched to the right package",
  "role":"Cobra command tree: review, scan, delegate, session, config, llm, rules, viewer, completion.",
  "detail":"root.go registers ten subcommands. review_cmd.go / scan_cmd.go resolve the LLM "
           "endpoint (internal/llm.ResolveEndpoint*), build the rule resolver and file filter "
           "from internal/config, construct the tool registry (registering built-ins then any "
           "configured MCP servers), and call agent.New(...).Run() or scan.NewAgent(...).Run(). "
           "config_cmd.go and provider_cmd.go/provider_tui.go drive the interactive provider/model "
           "setup wizard shown in the README's screenshot.",
  "model":"No model call in the CLI layer itself — it only resolves *which* model/provider/protocol "
          "downstream calls will use, via internal/llm.ResolveEndpointWithOptions (env var "
          "OCR_LLM_PROTOCOL, or config.json llm.protocol / provider preset).",
  "deterministic":"All of it: flag parsing, config file loading and merge, endpoint resolution, "
                   "tool registry assembly, and command dispatch are plain Go with no model call.",
  "dep":"diff, config_rules, agent, scan, delegate, session, llm, tool, mcp, viewer"},
 {"id":"diff","name":"Diff engine","layer":"2 · Change selection (deterministic)","color":"#FEF7E0",
  "pkg":"internal/diff/",
  "in":"git repository + From/To refs, a commit SHA, or nothing (workspace mode)",
  "out":"[]model.Diff — one parsed unified diff per changed file, plus resolved commit endpoints",
  "role":"Everything about turning 'what changed' into a precise, per-file diff the agent can send to the model.",
  "detail":"diff.Provider (git.go) shells out to git diff for one of three modes — workspace "
           "(all staged+unstaged+untracked), range (merge-base against a target branch), or a "
           "single commit — and gitcmd.Runner bounds concurrent git subprocesses. parser.go splits "
           "the unified diff into hunks; gitignore.go filters paths git itself would ignore; "
           "resolver.go and relocation.go are what let a later code_comment tool call be checked "
           "against real line numbers, including finding a comment's new position when a hunk "
           "shifted lines around it.",
  "model":"No model calls — pure git subprocess + text parsing.",
  "deterministic":"The entire package: diff retrieval, hunk parsing, gitignore filtering, and "
                   "line-number resolution/relocation are all deterministic. This is the "
                   "'precise file selection' and 'external positioning module' the README's "
                   "design philosophy calls out as engineering, not AI, work.",
  "dep":"gitcmd"},
 {"id":"config_rules","name":"Config, rules & allowlist","layer":"2 · Change selection (deterministic)","color":"#FEF7E0",
  "pkg":"internal/config/{rules,allowlist,template,toolsconfig}",
  "in":"rule.json (custom + project + global layers), config.json, embedded default rule/prompt/allowlist JSON",
  "out":"a rules.Resolver + rules.FileFilter (which files are reviewed and which rule text applies to each), plus loaded prompt template.Template",
  "role":"Decides which files are even eligible for review, and which review-rule text each eligible file sees.",
  "detail":"allowlist/ holds the supported-file-type and default-exclude-pattern JSON compiled "
           "into the binary. rules/system_rules.go resolves path-pattern rules (custom > project > "
           "global > system, first match wins per the resolver's own precedence) into the text "
           "injected as {{system_rule}} in the main prompt. template/ loads task_template.json / "
           "scan_template.json — the actual prompt text, tool-request budgets, and token limits — "
           "and can be overridden by a project's own template file.",
  "model":"No model calls — this package supplies the *inputs* a model call will use (prompt "
          "text, rule text), it never calls one itself.",
  "deterministic":"Path-glob rule matching, file-extension allowlisting, and template-engine "
                   "variable substitution are all deterministic — README calls this out explicitly "
                   "as 'fine-grained rule matching...more stable and predictable' than doing the "
                   "same selection purely via prompt instructions.",
  "dep":""},
 {"id":"agent","name":"Review agent","layer":"3 · Orchestration","color":"#C6F6D5",
  "pkg":"internal/agent/",
  "in":"agent.Args (repo dir, From/To/Commit, template, rules, LLM client, tool registry)",
  "out":"[]model.LlmComment + a persisted session with a coverage manifest",
  "role":"Runs ocr review end to end: load diffs, filter, dispatch one goroutine per file, finalize the manifest.",
  "detail":"Agent.Run (agent.go) parses diffs via internal/diff, builds a read-only DiffMap tool "
           "input, filters by rule/size/budget, then dispatchSubtasks fans out to up to "
           "MaxConcurrency (default 8) goroutines, each calling executeSubtask (plan phase, then "
           "llmloop.Runner.RunPerFile for the main loop). A per-run token budget "
           "(MaxTokensBudget) is checked before each new file is scheduled, so an in-flight batch "
           "can overrun the cap by at most the concurrency limit, never a whole extra batch.",
  "model":"Model/provider come from Args.Model/Args.Provider, set once by the CLI layer from the "
          "resolved LLM endpoint — every request in a run (plan, main loop, memory compression, "
          "re-location, review filter) uses that same value; there is no per-phase override.",
  "deterministic":"Diff loading/filtering, concurrency and per-file token-budget gating, manifest "
                   "coverage registration (registerCoverage/Mark*), resume matching by content "
                   "fingerprint (SHA-256 of mode+paths+diff text), and all error classification are "
                   "deterministic; only the plan phase and the main tool-use loop inside each "
                   "subtask are AI-driven (see llmloop).",
  "dep":"diff, config_rules, llmloop, tool, session, llm"},
 {"id":"scan","name":"Scan agent","layer":"3 · Orchestration","color":"#C6F6D5",
  "pkg":"internal/scan/",
  "in":"scan.Args (repo dir, optional --path, ScanTemplate)",
  "out":"[]model.LlmComment for whole files + an optional project-level Markdown summary",
  "role":"Runs ocr scan: review whole files (no git diff needed) — for auditing unfamiliar code or directories without a meaningful diff.",
  "detail":"scan.Agent enumerates files under RepoDir or --path into []model.ScanItem (whole file "
           "content, not a diff), then reuses the exact same llmloop.Runner the review agent uses "
           "(toLoopTemplate maps ScanTemplate onto the loop's template.Template fields). Adds two "
           "phases review mode doesn't have: an optional per-batch DEDUP_TASK and a post-run "
           "PROJECT_SUMMARY_TASK, both individually disableable via --no-dedup/--no-summary.",
  "model":"Same Args.Model/Provider pattern as review — one model for the whole run, set by the "
          "CLI from the resolved endpoint.",
  "deterministic":"File enumeration and size filtering (MaxFileSizeBytes, default 2 MiB), "
                   "toLoopTemplate's field mapping, and dispatch/budget gating mirror agent's — "
                   "AI involvement is the plan phase, main loop, dedup task and project-summary "
                   "task, each individually toggleable.",
  "dep":"config_rules, llmloop, tool, session, llm, agent"},
 {"id":"delegate","name":"Delegate","layer":"3 · Orchestration","color":"#FDE68A",
  "pkg":"internal/delegate/",
  "in":"the same rule/file-selection engine as review/scan (rules.Resolver, FileFilter)",
  "out":"Markdown-rendered rule groups + a resolved file list — handed to the caller, not to an LLM",
  "role":"Powers ocr delegate: OCR does file selection and rule resolution only; the user's own coding agent (Claude Code, Codex, Cursor) performs the actual review with its own model.",
  "detail":"rulegroup.go groups files by which rule text applies to them (RuleGroupsMarkdown "
           "renders each group's applicable files + rule content as a Markdown section); "
           "delegate_cmd.go exposes this as `ocr delegate preview` (file/rule discovery) and `ocr "
           "delegate rule <paths>` (rule text for specific files). This is the one review-producing "
           "code path in OCR that never constructs an llm.LLMClient or calls CompletionsWithCtx.",
  "model":"No model calls — explicitly, by design. This is the mechanism by which OCR can run "
          "with zero OCR-managed API key or LLM config: the review judgment happens inside "
          "whatever coding agent the user already has running.",
  "deterministic":"100% of this package: rule-group formation and Markdown rendering are plain "
                   "string/slice logic reusing the same deterministic resolver as review/scan.",
  "dep":"config_rules"},
 {"id":"llmloop","name":"LLM loop (Runner)","layer":"4 · Execution loop","color":"#E9D8FD",
  "pkg":"internal/llmloop/",
  "in":"a rendered message list + tool definitions for one file's conversation",
  "out":"comments collected via tool.CommentCollector; a completion/stop classification",
  "role":"The one shared tool-use loop underneath both internal/agent and internal/scan — sends messages, executes returned tool calls, manages context size.",
  "detail":"Runner.RunPerFile (loop.go) is the literal for-loop: send ChatRequest, get tool calls "
           "back, executeToolCall each one, append results, repeat until task_done, "
           "MaxToolRequestTimes rounds exhausted (triggers a final 'grace round' offering only "
           "code_comment/task_done), 3 consecutive rounds with no usable result, or context "
           "compression fails to bring the conversation back under budget. compression.go runs "
           "three-zone compression (soft 60% / warn 80% of Template.MaxTokens) synchronously or as "
           "a background job per conversation. pool.go is the CommentWorkerPool that can run "
           "code_comment's line-resolution off the critical path.",
  "model":"Model/provider/template are all passed in via Deps from the calling package (agent or "
          "scan) — llmloop itself makes no routing decision; it just calls "
          "Deps.LLMClient.CompletionsWithCtx(Model, Messages, Tools). The optional re-location call "
          "(diff.ReLocateComment, when a comment's line number can't be resolved deterministically) "
          "uses the same Deps.Model.",
  "deterministic":"Round/budget bookkeeping, empty-round detection, three-zone token-threshold "
                   "compression triggers, and tool-call dispatch routing (built-in vs. dynamic MCP) "
                   "are deterministic; only the model's own responses (what to call, what to say) "
                   "are AI-driven.",
  "dep":"llm, tool, session, model"},
 {"id":"tool","name":"Tools","layer":"5 · Tools & extensibility","color":"#FDE2E4",
  "pkg":"internal/tool/",
  "in":"a tool call's JSON arguments from the model",
  "out":"a result string appended back into the conversation",
  "role":"The fixed toolset: file_read, file_find, file_read_diff, code_search, code_comment, task_done — plus the Registry that can also hold MCP-provided tools.",
  "detail":"definitions.go defines the reserved Tool set and a Registry (Register/Get/Freeze — "
           "frozen once dispatch starts so no tool can be added mid-run). file_read.go / "
           "file_find.go / code_search.go implement local, read-only filesystem access scoped to "
           "the repo (via internal/pathutil). file_read_diff.go answers questions about *other* "
           "changed files using the DiffMap injected by agent.injectDiffMap. code_comment.go + "
           "comment_collector.go parse and accumulate the model's findings.",
  "model":"No model calls inside any tool implementation — every tool is a synchronous, local "
          "operation. (The one exception, the re-location LLM call for a comment whose line number "
          "can't be resolved deterministically, lives in internal/diff/internal/llmloop, not here.)",
  "deterministic":"Every built-in tool is fully deterministic: file reads are path-validated "
                   "(pathutil.WithinBase, both pre- and post-symlink-resolution — the same "
                   "mitigation the ASSURANCE_CASE.md cites for path traversal), code_comment "
                   "argument parsing and validation is deterministic, and the Registry's "
                   "known-name/frozen-state checks are deterministic.",
  "dep":""},
 {"id":"mcp","name":"MCP client","layer":"5 · Tools & extensibility","color":"#FDE2E4",
  "pkg":"internal/mcp/",
  "in":"user-configured MCP server definitions",
  "out":"tool.Provider adapters registered into the same Registry as built-in tools",
  "role":"Lets a review extend its available tools with external MCP servers, without the model ever seeing a difference from a built-in tool.",
  "detail":"client.go manages the MCP session (stdio transport, per client_test.go/stdio_test.go). "
           "provider.go's RegisterAll copies each MCP tool into the shared tool.Registry as a "
           "Provider whose Execute calls client.CallTool, after checking two collision rules: a "
           "tool name can't shadow a built-in (tool.IsReserved) and can't shadow an "
           "already-registered tool — either logs a warning and skips rather than silently "
           "overriding.",
  "model":"No model calls in this package — it is pure protocol/adapter plumbing between MCP "
          "servers and the tool.Registry.",
  "deterministic":"Tool-name collision resolution and JSON-schema-to-llm.ToolDef conversion "
                   "(ToToolDef) are fully deterministic.",
  "dep":"llm, tool"},
 {"id":"llm","name":"LLM transport","layer":"6 · Model transport","color":"#C6F6D5",
  "pkg":"internal/llm/",
  "in":"llm.ChatRequest (messages, tools, model, max tokens)",
  "out":"llm.ChatResponse (content, tool calls, usage) or a classified error",
  "role":"Resolves which provider/protocol/model a run uses, and speaks all three supported wire protocols with retry.",
  "detail":"resolver.go's ResolveEndpointWithOptions is the single source of truth for 'which "
           "model gets called': it checks the OCR_LLM_PROTOCOL/OCR_LLM_* environment variables "
           "first, then config.json's llm.protocol (or the legacy use_anthropic bool) or a named "
           "provider preset from providers.go's built-in registry (anthropic, openai, and any "
           "custom provider entries). client.go/responses_client.go implement the three protocols "
           "(ProtocolAnthropic, ProtocolOpenAIChatCompletions, ProtocolOpenAIResponses); "
           "retry_boundary.go/retry_observer.go/retry_report.go add exponential-backoff retry and "
           "build the per-run retry report the CLI can print.",
  "model":"This package *is* the model-selection mechanism for every other package: env var → "
          "config.json → provider preset, normalized to one of three canonical protocol names by "
          "NormalizeProtocol/ValidateProtocol. No other package re-implements this resolution.",
  "deterministic":"Protocol/endpoint resolution precedence, retry/backoff timing, and "
                   "request/response marshaling are deterministic; the model's actual reply content "
                   "is of course not.",
  "dep":"mcp"},
 {"id":"session","name":"Session & manifest","layer":"7 · Persistence & observability","color":"#C6F6D5",
  "pkg":"internal/session/",
  "in":"per-task LLM request/response records, per-item completion/failure events",
  "out":"a resumable JSONL history + an immutable RunManifest (coverage snapshot)",
  "role":"The audit trail: what was reviewed, what was skipped, why, and what a --resume run can safely reuse.",
  "detail":"history.go opens one JSONL file per run and appends TaskRecords (prompt, response, "
           "tool results) as the review progresses. manifest.go's ManifestBuilder is a strict "
           "state machine — RegisterSelected/SealSelected freezes the coverage denominator before "
           "any dispatch, then every item must transition through exactly one of "
           "MarkCompleted/MarkReused/MarkFailed before Finalize, or Finalize's validation catches "
           "the gap. resume.go matches a prior run's completed items to the current run by a "
           "content fingerprint (mode + paths + diff text, SHA-256), never by file path alone.",
  "model":"No model calls — this package only records what other packages' model calls produced.",
  "deterministic":"All of it — this is the deterministic bookkeeping layer the architecture "
                   "explicitly separates from the AI-driven review packages above it.",
  "dep":"llm"},
 {"id":"viewer","name":"Session viewer","layer":"7 · Persistence & observability","color":"#D2E3FC",
  "pkg":"internal/viewer/",
  "in":"a session's persisted JSONL + manifest",
  "out":"rendered HTML pages served over local HTTP",
  "role":"A local-only web UI (`ocr viewer`) for browsing a past review session — comments, timeline, token usage — without re-running anything.",
  "detail":"server.go starts an http.Server bound to localhost by default; hostguard.go enforces "
           "a Host-header allowlist (OCR_VIEWER_ALLOWED_HOSTS to widen it) specifically to block "
           "DNS-rebinding attacks against the local server, and securityheaders.go adds a strict "
           "CSP plus the standard clickjacking/sniffing headers to every response. handler.go / "
           "store.go load a session's JSONL and render it through html/template (auto-escaping, so "
           "no session content — including anything an LLM wrote — can inject markup).",
  "model":"No model calls — purely a read/render layer over already-persisted session data.",
  "deterministic":"The entire viewer is deterministic: host allowlist checks, header injection, "
                   "and template rendering. This is also where the ASSURANCE_CASE.md's XSS "
                   "mitigation (html/template auto-escaping + CSP) actually lives.",
  "dep":"session"},
 {"id":"telemetry","name":"Telemetry","layer":"7 · Persistence & observability","color":"#E6F4EA",
  "pkg":"internal/telemetry/",
  "in":"spans/events emitted by cli, agent, scan, llmloop, tool, diff",
  "out":"OpenTelemetry traces/metrics/logs to a configured OTLP collector",
  "role":"Opt-in observability — review duration, per-tool-call timing, token usage — layered on top of the functional code paths, never load-bearing for a review's result.",
  "detail":"config.go/provider.go set up the OTLP exporter from environment configuration (no "
           "telemetry runs unless configured); span.go/events.go/metrics.go are thin wrappers "
           "called from every other package's hot paths (StartSpan, Event, RecordToolCall, "
           "RecordLLMRequest) so instrumentation reads as ordinary function calls rather than a "
           "cross-cutting framework.",
  "model":"No model calls — and telemetry data itself must never include secrets: API keys and "
          "auth headers are explicitly excluded from every event/span per ASSURANCE_CASE.md.",
  "deterministic":"All of it — span/event emission is deterministic instrumentation code with no "
                   "influence on review outcomes.",
  "dep":"llm"},
]
