groundzero

Local-first desktop Codebase Dependency Mapper for graph-backed blast-radius analysis.

groundzero scans a local repository, writes dependency evidence into a local Kuzu graph, answers diff-impact questions, renders evidence paths, and exports OpenCode-oriented Markdown plus JSON packets for coding agents or reviewers.

Status

MVP demo foundation. The app supports a curated polyglot fixture, local repository scans, working-tree diffs, branch diffs, graph-backed impact queries, path visualization, debug evidence, and local packet export.

Packaging, signing, installer distribution, Tree-sitter runtime selection, and a real local LLM provider are intentionally not finalized yet.

Privacy Boundary

No source code leaves the machine in the implemented default path.

The app reads local files, local Git metadata, and local graph storage only. The LLM provider boundary exists, but the default provider is a no-op and does not call any network service.

Tech Stack

• Electron and React desktop app.
• pnpm workspaces.
• Kuzu embedded graph database running in a local Node sidecar.
• Broad shallow analyzers for TypeScript, JavaScript, Express, Angular, MongoDB conventions, Kotlin, Swift, and tests.
• Graphology and Sigma for selected evidence-path rendering.

Requirements

• Node.js 24.x. Verified locally with Node 24.14.0.
• pnpm 11.x. The repo declares pnpm@11.1.1.
• Git available on PATH for diff/history analysis and fixture restoration.

Quickstart

corepack enable
pnpm install
pnpm fixture:restore
pnpm dev

In the app:

1. Select Scan Demo Fixture.
2. Open Diff Impact.
3. Compare strict, balanced, and exploratory modes.
4. Inspect graph paths, affected artifacts, debug evidence, and exported packet content.

For local repositories, use Pick Local Repo for working-tree changes or enter a base ref such as main and use Pick Repo Branch Diff for base...HEAD impact.

Common Commands

pnpm dev
pnpm build
pnpm lint
pnpm test
pnpm fixture:restore

pnpm test runs workspace package tests serially after a build because several test suites exercise Kuzu native bindings.

Demo Fixture

The demo fixture lives at fixtures/groundzero-demo-repo.

The public source tree should not commit fixtures/groundzero-demo-repo/.git. Instead, pnpm fixture:restore rebuilds the nested fixture Git history from .groundzero-demo/groundzero-demo-repo.bundle and reapplies .groundzero-demo/working-tree.patch so the fixture has an intentional uncommitted diff.

Expected restored fixture state:

• Git history with three commits.
• Intentional working-tree changes in .groundzero-demo/demo-diff.md and packages/shared/src/order.ts.
• A real local Git diff that powers the first demo question: what breaks in this diff?

Repository Layout

• apps/desktop: Electron main/preload process, React renderer, and graph/query sidecar entry.
• packages/contracts: shared graph, query, diagnostic, sidecar, and agent packet contracts.
• packages/repo: repository discovery, ignore handling, hashing, and snapshots.
• packages/analyzers: broad shallow static analyzer pack.
• packages/git: working tree, branch diff, history, churn, recency, and co-change signals.
• packages/graph: Kuzu schema, patch writes, stale deletion, and traversal primitives.
• packages/scanner: analyzer orchestration and Git scan integration.
• packages/query: template parsing, query modes, impact traversal, and result shaping.
• packages/agent: OpenCode-oriented Markdown and JSON packet export.
• packages/llm: local-only provider interface and no-op default.
• docs: architecture, demo, readiness, and performance notes.

Documentation

• docs/architecture-overview.md
• docs/demo-walkthrough.md
• docs/readiness-review.md
• docs/performance-spike.md

License

MIT. See LICENSE.