gitatlas: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

gitatlas turns a folder of git repositories into one self-contained interactive HTML architecture map (group -> repo -> module -> symbol). No server, no database, no network at runtime. Everything is local files.

Commands

npm install                        # no build step, no native deps; code runs through tsx directly
npm test                           # full suite: extractor (all 21 languages), analysis, scoper (Node built-in test runner)
npm run extract -- fixtures        # smoke test: indexes 3+ fixture repos, emits fixtures/.gitatlas/index.html
npm run check -- fixtures          # freshness check against the existing map: exit 0 fresh, 1 stale; --json for machines
npm run extract -- fixtures --if-stale   # re-extract only when source content changed (run before trusting graph data)
npm run brief -- --out fixtures/.gitatlas --budget 1500   # token-budgeted markdown digest for agent context
npm run mcp -- --out fixtures/.gitatlas                   # MCP server over stdio (brief/scope/find_symbol/module_info/check_freshness)
npm run scope -- --trace crash.txt --out fixtures/.gitatlas   # bug scoper (requires a prior extract)

Run a single test file:

npm test -- packages/extractor/test/extract.test.ts

scripts/test.mjs wires the flags for both: single-process isolation (child test processes crash compiling tree-sitter grammars on Node 24, nodejs/node#63421) plus --liftoff-only on Node 24+. The isolation flag is detected, not hardcoded: Node 22 spells it --experimental-test-isolation, Node 24 spells it --test-isolation, and the wrong spelling is a fatal node: bad option at startup.

Requires Node 22+ (22.8+ for the test suite).

Architecture

Data flows one way: extractor -> JSON graph files -> viewer HTML. The pieces communicate only through the schema.

• packages/schema/src/types.ts — the contract. RepoGraph + GroupManifest JSON shapes, SCHEMA_VERSION. Start here for any change.
• packages/extractor/ — CLI (cli.ts): repo discovery (scans for .git markers), TS/JS extraction via the TypeScript compiler API, viewer generation (embeds data + vendored d3 into the template). github.ts parses GitHub targets including the ref a /tree/<ref>/ URL carries (pure, shared with packages/site) and clone.ts resolves a target to a local directory, shallow-cloning into the cache when it names a GitHub repo. One clone per (owner, repo, ref); the clone's basename is the repo name the map carries. extract.ts holds the tree-sitter WASM engine and SITTER_LANGS, a per-language config table covering the other 19 languages. layout.ts computes node positions at extract time.
• packages/analysis/ — neighborhoods (single-level Louvain clustering) and hub detection (degree statistics).
• packages/scoper/ — resolves a stack trace or symbol name into the graph and ranks the surrounding neighborhood. scope.ts is pure functions, cli.ts is I/O only; mirror that split for new logic.
• packages/brief/ — token-budgeted markdown digest of the map for agent context (brief.ts pure, cli.ts I/O). Budget cuts are always announced in the text, never silent.
• packages/mcp/ — dependency-free MCP server over stdio (server.ts tool logic, cli.ts JSON-RPC framing). Re-verifies source fingerprints before every tool call and flags stale repos inside each result.
• packages/viewer/template.html — the entire viewer: one file, vanilla JS + d3, no framework, no build. Keep it view-source-able. packages/viewer/locales/<code>.json holds the UI catalogs the extractor bakes in; en.json is the source of truth and docs/i18n.md is the contributor guide.
• bin/gitatlas.js — global entry; re-execs with --liftoff-only on Node 24+, then dispatches to extractor or scoper CLI via tsx/cjs.
• fixtures/ — small fake repos used by tests and the smoke test; fixtures/polyglot-lab has one file per tree-sitter language.