hamehrabi/gitiviz

Purpose and Delivery Model

Gitiviz locally converts a Git comparison into an evidence-backed, offline HTML “change book.” It separates deterministic Git-derived facts from optional AI narration, validates narration against those facts, and emits a scriptless single-file report. The distributable is a Claude Code plugin with committed Node bundles, so installation does not require package installation.

Paths: plugins/claude-code/scripts/run.sh, .claude-plugin/plugin.json, build/bundle.mjs.

User and Runtime Entry Points

Claude slash-command definitions invoke plugin scripts for branch, commit, and arbitrary-range analysis; a standalone launcher supports the same flow outside Claude. The TypeScript CLI is the source-level command dispatcher and is bundled for shipment. Runtime requires Node 20+ or Docker fallback; development/CI use pinned Node-in-Docker.

Paths: commands/branch.md, commands/compare.md, packages/cli/src/main.ts, plugins/claude-code/scripts/analyze.mjs.

Git Facts Boundary

The Git package resolves refs and comparison ranges, finds merge bases, and obtains diffs through controlled Git execution. This is the boundary between hostile repository data and structured facts: callers operate on resolved inputs rather than interpolating repository strings into shell commands.

Paths: packages/git/src/refs.ts, packages/git/src/diff.ts, packages/git/src/exec.ts.

Analysis and Semantic Extraction

Analyzers enrich changed-file data for supported JS/TS structures: workspace/package relationships, imports and exported symbols, and HTTP routes. Their output feeds the core model rather than directly producing prose or HTML. Unsupported code remains represented by diff-derived evidence.

Paths: packages/analyzers/src/packageAnalyzer.ts, packages/analyzers/src/importExportAnalyzer.ts, packages/analyzers/src/routeAnalyzer.ts.

Core Evidence Model and Narration Gate

Core constructs the evidence graph and groups raw changes into semantic change units that become book chapters. It produces a facts-only narration request; a later narration response is accepted only when its claims reference known entities/change units. This preserves the structural distinction between derived facts and AI interpretation.

Paths: packages/core/src/graph.ts, packages/core/src/changeUnits.ts, packages/core/src/narration.ts, packages/cli/src/apply-narration.ts.

Schema and Persisted Interchange

Schema types and validators define the stable manifest contract for facts and books. Analysis writes validated manifests and a narration-request payload under the target repository’s .gitiviz/; narration is an explicit file-based handoff, with no backend or network service.

Paths: packages/schema/src/types.ts, packages/schema/src/validate.ts, spec/change-manifest.schema.json, spec/book-manifest.schema.json.

Rendering and Security Boundary

The renderer transforms validated book data into a self-contained HTML document with inline SVG diagrams and accessibility-oriented output. All repository-controlled text is escaped; output contains no JavaScript and is designed for a strict CSP, making the generated file safe to open locally despite hostile repository content.

Paths: packages/renderer/src/render.ts, packages/renderer/src/diagram.ts, packages/renderer/src/escape.ts.

Build, Distribution, and Integrity

This pnpm workspace builds the CLI dependency graph into dependency-free plugin bundles committed under plugins/. CI rebuilds and rejects stale artifacts, ensuring plugin execution matches source. Docker-based development avoids requiring host Node tooling; Git and Docker are the key infrastructure dependencies.

Paths: build/bundle.mjs, dev.sh, .github/workflows/ci.yml, docs/decisions/0001-committed-artifacts.md.