codedebrief 0.11.0__py3-none-any.whl

codedebrief/validation.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any, cast
+
+from codedebrief.analysis import ProjectAnalyzer
+from codedebrief.analysis.registry import supported_language_ids
+from codedebrief.artifacts import output_paths
+from codedebrief.config import CodeDebriefConfig
+from codedebrief.model import ProjectModel
+from codedebrief.quality import model_quality
+from codedebrief.util import read_json
+
+
+@dataclass(slots=True)
+class ValidationReport:
+    ok: bool = True
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    artifact: str = ""
+    quality: dict[str, Any] | None = None
+
+    def add_error(self, message: str) -> None:
+        self.ok = False
+        self.errors.append(message)
+
+    def to_dict(self) -> dict[str, Any]:
+        payload = {
+            "ok": self.ok,
+            "artifact": self.artifact,
+            "errors": self.errors,
+            "warnings": self.warnings,
+        }
+        if self.quality is not None:
+            payload["quality"] = self.quality
+        return payload
+
+
+def validate_codedebrief(
+    root: Path,
+    *,
+    config: CodeDebriefConfig | None = None,
+    check_sync: bool = False,
+    include_quality: bool = False,
+    quality_thresholds: dict[str, float | int] | None = None,
+) -> ValidationReport:
+    """Validate the persisted CodeDebrief artifact and optional source sync.
+
+    The baseline validation is read-only: it loads the JSON model, checks it against the
+    bundled JSON Schema when `jsonschema` is installed, and verifies that every language in
+    the artifact is registered by the current analyzer. `check_sync` intentionally runs the
+    analyzer to compare the current source tree against the committed model.
+    """
+    active_config = config or CodeDebriefConfig.load(root)
+    json_path, _, _ = output_paths(root, active_config)
+    report = ValidationReport(artifact=str(json_path))
+
+    try:
+        artifact = read_json(json_path)
+    except OSError as error:
+        report.add_error(f"Could not read {json_path}: {error}")
+        return report
+    except ValueError as error:
+        report.add_error(f"Malformed JSON in {json_path}: {error}")
+        return report
+
+    try:
+        model = ProjectModel.from_dict(artifact)
+    except ValueError as error:
+        report.add_error(str(error))
+        return report
+
+    _validate_languages(model, report)
+    _validate_json_schema(artifact, report)
+    active_thresholds = quality_thresholds or {}
+    if include_quality or active_thresholds:
+        report.quality = model.metadata.get("quality") or model_quality(model)
+    if active_thresholds and report.quality is not None:
+        _validate_quality_thresholds(report, report.quality, active_thresholds)
+
+    if check_sync:
+        try:
+            fresh = ProjectAnalyzer(root, active_config).analyze(full=True).model
+        except (OSError, ValueError, SyntaxError) as error:
+            report.add_error(f"Could not re-analyze sources for sync check: {error}")
+        else:
+            if _without_generated_at(fresh.to_dict()) != _without_generated_at(model.to_dict()):
+                report.add_error(
+                    "codedebrief.json is stale; run `codedebrief update` and commit the artifacts."
+                )
+
+    return report
+
+
+def schema_language_ids(schema: dict[str, Any]) -> tuple[str, ...]:
+    return _schema_language_ids(schema, "flow")
+
+
+def schema_file_language_ids(schema: dict[str, Any]) -> tuple[str, ...]:
+    return _schema_language_ids(schema, "file")
+
+
+def _schema_language_ids(schema: dict[str, Any], definition: str) -> tuple[str, ...]:
+    flow_language = (
+        schema.get("$defs", {})
+        .get(definition, {})
+        .get("properties", {})
+        .get("language", {})
+        .get("enum", [])
+    )
+    return tuple(str(item) for item in flow_language)
+
+
+def _validate_languages(model: ProjectModel, report: ValidationReport) -> None:
+    supported = set(supported_language_ids())
+    found = {flow.language for flow in model.flows} | {record.language for record in model.files}
+    unknown = sorted(found - supported)
+    if unknown:
+        report.add_error("Artifact uses unregistered language ids: " + ", ".join(unknown))
+
+
+def _validate_json_schema(artifact: dict[str, Any], report: ValidationReport) -> None:
+    try:
+        schema = _read_bundled_schema()
+    except (OSError, ValueError) as error:
+        report.add_error(f"Could not read bundled schema: {error}")
+        return
+
+    schema_languages = set(schema_language_ids(schema))
+    schema_file_languages = set(schema_file_language_ids(schema))
+    supported = set(supported_language_ids())
+    if schema_languages != supported or schema_file_languages != supported:
+        report.add_error(
+            "Schema language enums are out of sync with registry: "
+            f"flow={sorted(schema_languages)} file={sorted(schema_file_languages)} "
+            f"registry={sorted(supported)}"
+        )
+
+    try:
+        from jsonschema import Draft202012Validator  # type: ignore[import-untyped]
+    except ImportError:
+        report.warnings.append("jsonschema is not installed; skipped JSON Schema validation.")
+        return
+
+    validator = Draft202012Validator(schema)
+    errors = sorted(validator.iter_errors(artifact), key=lambda item: list(item.path))
+    for validation_error in errors:
+        location = "/".join(str(part) for part in validation_error.path) or "<root>"
+        report.add_error(f"{location}: {validation_error.message}")
+
+
+def _validate_quality_thresholds(
+    report: ValidationReport, quality: dict[str, Any], thresholds: dict[str, float | int]
+) -> None:
+    files = quality.get("files", {})
+    calls = quality.get("calls", {})
+    labels = quality.get("labels", {})
+    skipped = files.get("skipped", {}) if isinstance(files, dict) else {}
+    parse_errors = files.get("parse_errors", {}) if isinstance(files, dict) else {}
+    if "max_skipped_files" in thresholds:
+        actual_skipped = int(_number(skipped.get("total"), 0))
+        skipped_limit = int(thresholds["max_skipped_files"])
+        if actual_skipped > skipped_limit:
+            report.add_error(
+                f"quality threshold failed: skipped files {actual_skipped} > max {skipped_limit}"
+            )
+    if "max_parse_warnings" in thresholds:
+        actual_parse_warnings = int(_number(parse_errors.get("total"), 0))
+        parse_warning_limit = int(thresholds["max_parse_warnings"])
+        if actual_parse_warnings > parse_warning_limit:
+            report.add_error(
+                "quality threshold failed: parse warnings "
+                f"{actual_parse_warnings} > max {parse_warning_limit}"
+            )
+    if "min_call_resolution" in thresholds:
+        actual_resolution = _number(calls.get("resolution_rate"), 0.0)
+        resolution_limit = float(thresholds["min_call_resolution"])
+        if actual_resolution < resolution_limit:
+            report.add_error(
+                "quality threshold failed: call resolution "
+                f"{actual_resolution:.0%} < min {resolution_limit:.0%}"
+            )
+    if "max_generic_label_ratio" in thresholds:
+        actual_generic = _number(labels.get("generic_ratio"), 0.0)
+        generic_limit = float(thresholds["max_generic_label_ratio"])
+        if actual_generic > generic_limit:
+            report.add_error(
+                "quality threshold failed: generic label ratio "
+                f"{actual_generic:.0%} > max {generic_limit:.0%}"
+            )
+
+
+def _number(value: Any, default: float) -> float:
+    return float(value) if isinstance(value, (int, float)) else default
+
+
+def _without_generated_at(payload: dict[str, Any]) -> dict[str, Any]:
+    clone = dict(payload)
+    clone.pop("generated_at", None)
+    return clone
+
+
+def _read_bundled_schema() -> dict[str, Any]:
+    checkout_schema = Path(__file__).parents[2] / "schema" / "codedebrief.schema.json"
+    if checkout_schema.exists():
+        return read_json(checkout_schema)
+
+    schema_resource = (
+        resources.files("codedebrief").joinpath("schema").joinpath("codedebrief.schema.json")
+    )
+    return cast(dict[str, Any], json.loads(schema_resource.read_text(encoding="utf-8")))

codedebrief-0.11.0.dist-info/METADATA

@@ -0,0 +1,426 @@
+Metadata-Version: 2.4
+Name: codedebrief
+Version: 0.11.0
+Summary: Visual code workflow explorer for coding agents. Builds deterministic, source-grounded Mermaid flowcharts via MCP, local-first, with no API key.
+Project-URL: Homepage, https://github.com/ferdinandobons/CodeDebrief
+Project-URL: Documentation, https://github.com/ferdinandobons/CodeDebrief#readme
+Project-URL: Issues, https://github.com/ferdinandobons/CodeDebrief/issues
+Project-URL: Source, https://github.com/ferdinandobons/CodeDebrief
+Author: Ferdinando Bonsegna
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai-agents,code-comprehension,code-navigation,coding-agents,cpp,developer-tools,flowchart,javascript,local-first,mcp,mcp-server,mermaid,model-context-protocol,python,source-code-analysis,static-analysis,tree-sitter,typescript,visualization,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: tree-sitter-c-sharp<0.24,>=0.23
+Requires-Dist: tree-sitter-c<0.24,>=0.23
+Requires-Dist: tree-sitter-cpp<0.24,>=0.23
+Requires-Dist: tree-sitter-go<0.24,>=0.23
+Requires-Dist: tree-sitter-java<0.24,>=0.23
+Requires-Dist: tree-sitter-php<0.24,>=0.23
+Requires-Dist: tree-sitter-ruby<0.24,>=0.23
+Requires-Dist: tree-sitter-rust<0.24,>=0.23
+Requires-Dist: tree-sitter-typescript<0.24,>=0.23.2
+Requires-Dist: tree-sitter<0.26,>=0.25.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pytest-cov>=6; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: tomli>=2.0; extra == 'dev'
+Provides-Extra: mcp
+Description-Content-Type: text/markdown
+
+# CodeDebrief
+
+CodeDebrief turns source code into deterministic, source-grounded workflow flowcharts for
+humans and coding agents.
+
+It is a local-first code comprehension tool that builds a source-grounded workflow model
+of a codebase and exposes that model in two ways:
+
+- `codedebrief view` for manual exploration of the complete graph.
+- MCP `agent_context` for coding agents that need a bounded, source-grounded
+  `workflow_slice`.
+
+The product unit is the `workflow_slice`: a deterministic slice of the modeled code
+logic selected from a question, changed file, symbol, state, flow id, or dependency path.
+Agents can render that slice visually, explain it, expand it, or trace a path without
+inventing steps that are not in the graph.
+
+CodeDebrief is not a bug finder, a generic graph database, or an LLM enrichment service.
+The core workflow is deterministic, local, and offline. No LLM provider key is required.
+
+![Compact source-backed workflow visual generated from a CodeDebrief slice](docs/assets/codedebrief-workflow-preview.png)
+
+Example output: a compact presentation layer generated from local CodeDebrief artifacts.
+Canonical workflow visuals are vertical by default; horizontal diagrams are used when the
+user explicitly asks for a compact overview.
+
+> Status: pre-1.0 alpha. The model is versioned, but schema and MCP payloads may evolve
+> before 1.0.
+>
+> Latest release: [v0.11.0](https://github.com/ferdinandobons/CodeDebrief/releases/tag/v0.11.0)
+> · [Changelog](CHANGELOG.md)
+
+## Why It Exists
+
+Coding agents are useful only when they understand the logic they are about to explain or
+change. Reading files one by one is slow and inconsistent; asking an LLM to reconstruct a
+workflow from source often produces different diagrams for the same prompt.
+
+CodeDebrief gives agents a deterministic navigation layer:
+
+- entrypoints, decisions, branches, calls, outcomes, and source ranges;
+- domain concepts such as statuses, roles, permissions, enums, and feature flags;
+- affected-workflow context for changed files, symbols, flows, and dependency paths;
+- canonical visual slices with stable diagram hashes;
+- optional language-friendly labels derived as a presentation layer from analyzer facts.
+
+## Quick Start
+
+Install from PyPI. MCP support is included by default:
+
+```bash
+uv tool install codedebrief
+```
+
+To install a pinned GitHub release instead:
+
+```bash
+uv tool install "git+https://github.com/ferdinandobons/CodeDebrief.git@v0.11.0"
+```
+
+Or install from a source checkout:
+
+```bash
+git clone https://github.com/ferdinandobons/CodeDebrief.git codedebrief
+cd codedebrief
+uv tool install .
+```
+
+From the codebase you want to analyze:
+
+```bash
+codedebrief setup-agent codex
+```
+
+`setup-agent` creates `codedebrief.toml` when needed, installs the selected agent
+instruction file, installs a provider-native CodeDebrief skill where supported, registers
+project-scoped MCP where supported, generates initial artifacts, runs `doctor`, and
+validates the result.
+
+After setup, ask the coding agent ordinary questions:
+
+```text
+How does checkout work?
+Show me the workflow for certificate upload.
+Which workflows are affected by this change?
+Where is this status handled?
+What should I test after editing this file?
+```
+
+For manual exploration:
+
+```bash
+codedebrief view
+```
+
+For explicit refresh during development:
+
+```bash
+codedebrief update
+codedebrief validate --check-sync
+```
+
+The generated agent instructions treat CodeDebrief artifacts as part of done for
+workflow-relevant changes: after meaningful source, route, config, or agent-instruction
+edits, run `codedebrief update` and `codedebrief validate --check-sync` before finalizing
+or committing so MCP answers and `codedebrief view` use current graphs.
+
+## Ask Your Agent
+
+Once `setup-agent` has configured the project MCP server and agent instructions, ask
+ordinary code-logic questions:
+
+```text
+Show me a visual workflow for the invitation system.
+Explain this code path with a source-grounded flowchart.
+Which workflows are affected by this change?
+Where is this status handled?
+Expand the omitted branches in this workflow_slice.
+Rewrite the diagram labels in plain English.
+```
+
+The agent should use CodeDebrief first, then decide how much of the deterministic graph to
+show for the specific question.
+
+## Setup-Agent
+
+Supported targets:
+
+```bash
+codedebrief setup-agent codex
+codedebrief setup-agent claude ../my-app
+codedebrief setup-agent gemini
+codedebrief setup-agent cursor --full
+```
+
+The selected target controls which files are written:
+
+| Target | Files |
+| --- | --- |
+| `codex` | `AGENTS.md`, `.agents/skills/codedebrief/SKILL.md`, project MCP config |
+| `claude` | `CLAUDE.md`, `.claude/skills/codedebrief/SKILL.md`, project MCP config |
+| `gemini` | `GEMINI.md`, `.gemini/skills/codedebrief/SKILL.md`, `.gemini/settings.json` MCP config |
+| `cursor` | `.cursor/rules/codedebrief.mdc`, project MCP config |
+
+`setup-agent <target>` writes only that target's files. Run it separately for each agent
+surface you want to configure.
+
+The `gemini` target follows Gemini CLI / Antigravity conventions: `GEMINI.md` provides
+project context, `.gemini/skills/codedebrief/SKILL.md` provides provider-native workflow
+guidance, and `.gemini/settings.json` registers the project-scoped CodeDebrief MCP server.
+
+## Agent Workflow
+
+For natural-language questions, agents should start with MCP `agent_context`.
+
+`agent_context` returns a `workflow_slice` with:
+
+- normalized intent and task type;
+- primary and supporting flows;
+- ordered source-grounded steps;
+- decision nodes, branches, values, and outcomes;
+- calls, callers, callees, and unresolved call context;
+- domain logic for relevant state-like concepts;
+- source ranges the agent can cite;
+- visual handles for `snapshot_slice` and `codedebrief view`;
+- omissions caused by token budget, ambiguity, stale artifacts, or unsupported capability;
+- follow-up tools for expansion, path tracing, focused explanation, and snapshots.
+
+When a user asks for a visual workflow, the agent should first render the deterministic
+Mermaid visual returned by CodeDebrief:
+
+1. Render `workflow_slice.presentation.canonical_visual.diagram` exactly as returned only
+   when the client renders Mermaid inline.
+2. If the client cannot render Mermaid inline, use `snapshot_slice` with
+   `include_svg=false` and provide the returned `.mmd` or Mermaid Markdown artifact
+   before prose. Do not paste a long Mermaid code block as the primary visual unless the
+   user asks for raw or copyable Mermaid. These generated files are meant to be opened
+   with the best available local preview path, for example opening the Markdown artifact
+   in VS Code and using Markdown/Mermaid preview support.
+3. Use SVG snapshot artifacts only when the user explicitly asks for SVG or local
+   inspection; they are not the canonical chat visual.
+
+The model may choose the first visible depth, but the text inside shown blocks must come
+from CodeDebrief payloads. The answer should say that the diagram is a bounded summary and
+can be expanded. If the user wants a more language-friendly view, the agent may rewrite
+labels in the user's language as a separate presentation layer, preserving ids or source
+anchors and without adding facts.
+
+## MCP Surface
+
+Primary MCP tools:
+
+| Tool | Purpose |
+| --- | --- |
+| `agent_context` | Default entrypoint for natural-language questions and changed-code context. |
+| `expand_slice` | Widen or deepen a workflow slice from stable flow handles. |
+| `workflow_path` | Trace a deterministic path between flows, symbols, or concepts. |
+| `snapshot_slice` | Render a deterministic visual snapshot for a slice. |
+| `explain_flow` | Explain one flow with ordered steps, decisions, calls, and source anchors. |
+| `explain_node` | Explain one flowchart node with local edge and source context. |
+| `explain_edge` | Explain one modeled edge with source context. |
+| `validate_artifacts` | Check generated model validity and optional sync. |
+| `update_codedebrief` | Refresh JSON, Markdown, and HTML artifacts from local source. |
+
+Use `codedebrief view` for the manual UI. The CLI intentionally stays small:
+`setup-agent`, `update`, `view`, `validate`, `doctor`, and `mcp`.
+
+## Generated Artifacts
+
+CodeDebrief writes deterministic artifacts under `codedebrief-out/`:
+
+| File | Commit? | Purpose |
+| --- | --- | --- |
+| `codedebrief.json` | Yes | Canonical model consumed by MCP, CI, scripts, and the viewer. |
+| `codedebrief.md` | Yes | Human-readable Markdown summary with Mermaid flowcharts. |
+| `codedebrief.html` | Usually no | Local interactive viewer generated from the model. |
+
+Commit `codedebrief.json` and `codedebrief.md` when CodeDebrief is part of the project
+workflow. Regenerate HTML locally when a human needs the viewer.
+
+## Manual Viewer
+
+`codedebrief view` opens the complete interactive flowchart for a human. It is the official
+manual experience for broad exploration:
+
+```bash
+codedebrief view
+codedebrief view --render-only --no-open
+```
+
+Use the viewer when you need to inspect the whole project graph, navigate scopes, compare
+neighboring flows, or visually follow callers and callees. Use MCP when an agent should
+answer a bounded question with a focused `workflow_slice`.
+
+## Domain Logic
+
+CodeDebrief extracts and aggregates domain concepts such as:
+
+- enum members;
+- status and lifecycle states;
+- roles and permissions;
+- feature flags;
+- handled values and the decisions that branch on them.
+
+`agent_context` includes relevant domain logic inside the returned `workflow_slice`, with
+links back to flows, nodes, source ranges, snapshots, and viewer targets. Value matching
+uses modeled code facts, including enum-style suffix matches such as `PAID` for
+`Status.PAID`.
+
+## Supported Code
+
+CodeDebrief currently extracts control flow for 11 language ids:
+
+| Language | Current coverage |
+| --- | --- |
+| Python (`.py`) | AST analyzer with functions, methods, decisions, loops, calls, returns, exceptions, tests, enum harvest, and import dependencies. |
+| TypeScript / TSX (`.ts`, `.tsx`) | Tree-sitter analyzer with Next.js and React entrypoint detection, decisions, loops, calls, returns, expression-bodied arrows, tests, enum harvest, and import dependencies. |
+| JavaScript / JSX (`.js`, `.jsx`, `.mjs`, `.cjs`) | Tree-sitter analyzer with JavaScript labeling, decisions, loops, calls, returns, expression-bodied arrows, tests, and import dependencies. |
+| Go (`.go`) | Profile-driven tree-sitter analyzer with functions, methods, decisions, loops, calls, returns, tests, and import dependencies. |
+| Java (`.java`) | Profile-driven tree-sitter analyzer with methods, decisions, loops, calls, returns, exceptions, tests, imports, and Spring route annotations. |
+| C# (`.cs`) | Profile-driven tree-sitter analyzer with methods, decisions, loops, calls, returns, exceptions, and tests. |
+| PHP (`.php`) | Profile-driven tree-sitter analyzer with functions, methods, decisions, loops, calls, returns, exceptions, and tests. |
+| C (`.c`, `.h`) | Profile-driven tree-sitter analyzer with functions, decisions, loops, calls, returns, and tests. |
+| C++ (`.cc`, `.cpp`, `.cxx`, `.hh`, `.hpp`, `.hxx`, `.ipp`, `.tpp`) | Profile-driven tree-sitter analyzer with functions, methods, decisions, loops, calls, returns, exceptions, and tests. |
+| Rust (`.rs`) | Profile-driven tree-sitter analyzer with functions, decisions, loops, calls, match handling, returns, and tests. |
+| Ruby (`.rb`) | Profile-driven tree-sitter analyzer with methods, decisions, loops, calls, returns, and tests. |
+
+Generated models include `metadata.language_capabilities`, with feature flags and
+limitation notes per language. Agents should use that contract when explaining analyzer
+depth.
+
+## Configuration
+
+CodeDebrief works without config. Add `codedebrief.toml` only when defaults are not enough:
+
+```toml
+[codedebrief]
+source_roots = ["."]
+exclude = []
+exclude_dirs = []
+include_public_functions = true
+max_call_depth = 4
+output_dir = "codedebrief-out"
+self_exclude = true
+
+[codedebrief.entrypoints]
+include = []
+exclude = []
+
+[codedebrief.scopes]
+backend = ["backend/**", "services/**"]
+frontend = ["frontend/**", "web/**"]
+edge = ["edge/**", "workers/**"]
+```
+
+Defaults prune common VCS, dependency, cache, temporary, generated, and output
+directories, including `.git`, `node_modules`, virtualenv folders, `.next`, `.turbo`,
+`.svelte-kit`, `dist`, `build`, `out`, `target`, `coverage`, `vendor`, `Pods`, and
+`codedebrief-out`.
+
+## Limitations
+
+CodeDebrief does not run code, observe runtime state, perform full symbolic execution,
+prove business correctness, or reconstruct deep framework state. It statically models
+source files, control flow, selected framework conventions, and resolvable internal calls.
+
+Important practical limits:
+
+- dynamic dispatch may remain unresolved;
+- language capability varies by analyzer frontend;
+- generated or unsupported files may be skipped;
+- large slices are token-budgeted and report omissions;
+- the displayed first slice is a bounded summary and can be expanded with MCP tools.
+
+## FAQ
+
+### Is CodeDebrief an AI code review tool?
+
+No. CodeDebrief is for code comprehension and workflow navigation. It helps humans and
+coding agents understand modeled logic; it does not present possible defects as product
+output.
+
+### Does CodeDebrief require an LLM API key?
+
+No. The analyzer, artifacts, Mermaid diagrams, manual viewer, and MCP server are
+local-first and deterministic. Coding agents can use the MCP tools without any required
+provider key.
+
+### How is CodeDebrief different from a call graph?
+
+A call graph shows relationships between symbols. CodeDebrief models workflow slices with
+entrypoints, decisions, branches, ordered steps, source ranges, domain concepts, visual
+targets, and expansion tools for coding agents.
+
+### Can CodeDebrief generate Mermaid workflow diagrams from code?
+
+Yes. `agent_context` returns a canonical top-to-bottom Mermaid visual for the selected
+`workflow_slice`, and `snapshot_slice` can persist Mermaid files for clients that cannot
+render Mermaid inline.
+
+### Can I use CodeDebrief only as a manual visual explorer?
+
+Yes. Run `codedebrief view` to open the interactive local viewer. MCP is the primary agent
+surface, but the viewer remains the official manual exploration surface.
+
+## Development
+
+For local development in this repository:
+
+```bash
+uv sync --extra dev
+uv run codedebrief --help
+```
+
+Standard gates:
+
+```bash
+UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run ruff check .
+UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run ruff format --check .
+UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run mypy
+UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run pytest --cov
+UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run codedebrief validate . --check-sync --json
+```
+
+Viewer gates:
+
+```bash
+npm run viewer:typecheck
+npm run viewer:test
+npm run viewer:build
+UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run codedebrief update
+UV_CACHE_DIR=/tmp/codedebrief-uv-cache uv run codedebrief view --render-only --no-open
+```
+
+Schemas:
+
+- [schema/codedebrief.schema.json](schema/codedebrief.schema.json) documents the canonical
+  artifact model.

codedebrief-0.11.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+codedebrief/__init__.py,sha256=AX7wdOPFDwuJYbfG8VSiyc509n5WPKfhut2L0zMaXU4,375
+codedebrief/artifacts.py,sha256=BIAgDjcP2Y3GxjaIXkSR-nvpYTuZq_3FzwhYrfXEbB4,1809
+codedebrief/cli.py,sha256=LI6PK91cn9YnQhIJaWbe01vqLGb-UfMU413mg-04Uf0,19723
+codedebrief/config.py,sha256=SqWIvGm8qx8mn2n6uIy5ICC_QFHUe5LUFwDhDabnnXQ,7632
+codedebrief/doctor.py,sha256=qMKgBqZJXEzfWQ_TQxlZViTjta1fqD1YkjjNbLwFhOU,5943
+codedebrief/install.py,sha256=BacXTwP99t0RLBRgBFZacXC3AJeNMLzuiYcgPESKb9s,21243
+codedebrief/mcp_server.py,sha256=BDi_-COX7ktPGBO-wIo5JhV88a70xmZ8u1Ksm01txTs,98619
+codedebrief/model.py,sha256=VIUKL9sSVHsNn2CSB0W-Q9slgUZ1Gvfjkg9PWLF1DuA,5623
+codedebrief/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+codedebrief/quality.py,sha256=Z0LX9yR_IHaLR61Ej7FULSWmFCiXu15rz7BbkT5M1Hw,15403
+codedebrief/query.py,sha256=qpEI3jcsuswQVElzqZY63HT4wPE9b5gVRF2zQzeHMV0,23074
+codedebrief/util.py,sha256=5vTbub_uikjd6U3xpRSBYQWTC52tYVmYaRSmUJ__TqU,1970
+codedebrief/validation.py,sha256=fhhVbztDoDvdA_I5tr4QuCOH-2qrczlxgysvxsC1iHU,8315
+codedebrief/analysis/__init__.py,sha256=wSpZMiXlX6G5hU8dIk85BH4xuWwMsSRl25l9o42REog,554
+codedebrief/analysis/common.py,sha256=pQQNDrTwG0QnWWSvxOYXlBw2d240Y5UQDfR0Qub7p-I,17920
+codedebrief/analysis/discovery.py,sha256=rpTcTSMylAHb0x9w4nwcT4BlAlRR3pg69fiQOgqD6lc,4232
+codedebrief/analysis/project.py,sha256=y7dQeBKBhzloN__xQ5vON37rsf0IWw68oTT0P3wrrb4,16151
+codedebrief/analysis/python.py,sha256=kCKbomOi7GUCUd3Y-x7nerTJrOWW2Siosxt53w6Itjs,34408
+codedebrief/analysis/registry.py,sha256=5YFUbbTleyVoCLZeHAl6mzxRNSlqffIIDWASxUJJvgA,10442
+codedebrief/analysis/treesitter.py,sha256=y6KVLiuL5TzxiTg90g3E8f1g75GI70gFGGD0oriLWzo,36200
+codedebrief/analysis/typescript.py,sha256=5DOFFuHr6IB4Uc0v84r6dLZEO3jbVqdX8KxS9_IhVB4,38420
+codedebrief/analysis/languages/__init__.py,sha256=u-Fa3xrUW5AAhVGPt2bk0XiZfRFDSPDwc106bGU8noY,320
+codedebrief/analysis/languages/_common.py,sha256=7UBqj0sHJf1aaozzkrq7lNavLRTGkU04vlvdSpo3JPk,2526
+codedebrief/analysis/languages/c.py,sha256=S7PoP2T_WtnhkV9JK74-_rRJLyzCiDjVFX0NvJxoNoQ,3403
+codedebrief/analysis/languages/cpp.py,sha256=X2XlZYnYgktjwXtU1YpPyv1cLOpRDJy9ABGEBfzPJu0,5020
+codedebrief/analysis/languages/csharp.py,sha256=M_lSGjj1ZjiFOjwsRDt9V_7kRAzHUrmMDrM0CLH6fCk,5420
+codedebrief/analysis/languages/go.py,sha256=dkHPfk-6RHTkSfMBO2G7X-05AaFl0Vj-YLchFMYLYQA,5483
+codedebrief/analysis/languages/java.py,sha256=tV0uoqSD6HyrcFF8oHrfyw-szWkji6wv-8PJz5ySko8,6072
+codedebrief/analysis/languages/php.py,sha256=hzNcRhSQYoOaTofXM_XrCAAZj39wMS4LZhIbjK7A8bM,3260
+codedebrief/analysis/languages/ruby.py,sha256=48axyjdg6e7U_488y9t6ePmKJx-3xRePJ4Lre2Qhk-E,2768
+codedebrief/analysis/languages/rust.py,sha256=efn1rdCGofHuAUmTe40cbyXfVL5J9sENYQx7rXn5Zs4,3807
+codedebrief/render/__init__.py,sha256=ghDW516vY7T-nWbYvj38Ns8GR40lAYEdzUfbM7yiJM8,208
+codedebrief/render/html.py,sha256=sKUMF1UWSWkGdTtd3p_X-0LqK8gLwPENygQM2iB38FE,10640
+codedebrief/render/markdown.py,sha256=3RbXAKi6PZfp6OvK1GqvHrS-AXvdEwHW-tL1YqEJJnk,5347
+codedebrief/render/payload.py,sha256=k3u9LRDvrjXuWQ_RbnXX3cqKsS8UHzVc6lY5dWFABYE,14400
+codedebrief/render/snapshot.py,sha256=AueLKF4axnHeRibGqiBXBsthu9m2BMWFLHnm4lvNGno,25548
+codedebrief/render/assets/panels.js,sha256=nZ3PHIs0-JhyPopv126lo1OMVSVRtuSe7HiFtBe3VX4,17742
+codedebrief/render/assets/shell.js,sha256=TLZ0IQzSzs51R6FSCgiRPgBOC2QwQdzF6hqpaog30ns,69483
+codedebrief/render/assets/styles.css,sha256=kw877xa96kaUBD05yCQ1SX69KZRHhPnL3BTMCq_czX8,52278
+codedebrief/render/assets/tree.js,sha256=WYx97jOQUt3e3hcy8RELKInnO-y4J4RZQU4AhD8cnV4,24180
+codedebrief/render/assets/generated/codedebrief-viewer-runtime.iife.js,sha256=d2cmGiGqqTBgsgdQQvGV-rklXi-l2HjBh0EalZmfj1A,276745
+codedebrief/schema/codedebrief.schema.json,sha256=CJTEgEcXvS09PYvciPkqjyLR9f4vzGHaCgvQ1gNFSoM,9760
+codedebrief-0.11.0.dist-info/METADATA,sha256=ezkG6ADp0YAQHhIHEUH7pWJUaCFrbEhRFHLQPLkFynw,17493
+codedebrief-0.11.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+codedebrief-0.11.0.dist-info/entry_points.txt,sha256=NLdCH2kxaZPfdGVhtzd1uhJ7xm36IlMqUAw9hXz_sk4,53
+codedebrief-0.11.0.dist-info/licenses/LICENSE,sha256=psuoW8kuDP96RQsdhzwOqi6fyWv0ct8CR6Jr7He_P_k,10173
+codedebrief-0.11.0.dist-info/licenses/NOTICE,sha256=1SKC2iM-7PF9gSHkpbqnxUW1dI8Pt6BKddq0-0BPSb4,365
+codedebrief-0.11.0.dist-info/RECORD,,