repograph-cli 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,194 @@
-# Temporary Holding Version
+# RepoGraph
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Turn any codebase into an interactive architecture map in 2 seconds. Zero server, full privacy, built for Claude & Claude Code.
+
+![RepoGraph demo: click a file for its blast radius, double-click a directory to collapse it](assets/hero-demo.gif)
+
+[![npm version](https://img.shields.io/npm/v/repograph-cli.svg)](https://www.npmjs.com/package/repograph-cli) [![MIT license](https://img.shields.io/badge/license-MIT-e879f9)](LICENSE) [![Node >=18](https://img.shields.io/badge/node-%3E%3D18-84cc16)](https://nodejs.org/) ![Languages](https://img.shields.io/badge/languages-JS%20%7C%20TS%20%7C%20Python%20%7C%20Go%20%7C%20Rust-fbbf24)
+
+👉 **[Try the interactive live demo](https://karry1123.github.io/repograph/)** (zustand's architecture, generated with one command)
+
+Find the files that matter before changing the code. RepoGraph scans local imports, groups source files by directory and likely architectural layer, and writes an interactive HTML map. Directory clustering and utility folding help keep shared helpers from turning the view into a spiderweb. Three MCP tools let Claude inspect architecture and trace the impact of a proposed change.
+
+“2 seconds” describes the quickstart experience, not a measured performance guarantee. Scan time and HTML size depend on the repository; a small map can be ~40 KB. No account, server, or configuration file is required.
+
+## Quickstart
+
+```sh
+npx repograph-cli .
+```
+
+Open the printed `file:///.../repograph.html` link. Click a file to see its incoming callers in cyan and outgoing dependencies in red. Double-click directory boxes to collapse or expand them. Press `f` to fit the graph to the viewport. Search matches subsequences in full file paths; the minimap lets you jump around large graphs.
+
+Node.js 18 or newer is required. Scanning stays on your machine. The HTML embeds your file paths and graph data, so treat it as repository information when sharing. Opening the interactive map downloads pinned Cytoscape/layout scripts from public CDNs; no source or graph data is sent by RepoGraph. The CDN scripts must be reachable on first opening. SVG, JSON, and Mermaid exports need no browser CDN scripts.
+
+## CLI reference
+
+```text
+repograph [path] [options]
+repograph mcp
+
+Options:
+  -o, --output <file>       Write to a file
+  --theme <theme>           dark | light | matrix (default: dark)
+  --max-depth <n>           Maximum directory nesting (default: 6)
+  --no-collapse-utils      Show utility candidates immediately
+  --format <format>        html | json | mermaid | svg (default: html)
+  -V, --version            Show version
+  -h, --help               Show help
+```
+
+The path defaults to `.`. HTML defaults to `./repograph.html` in your current working directory and prints its absolute file URL after writing. Other formats print to stdout unless `--output` is supplied. Output directories are created automatically. `--max-depth 0` scans only root files.
+
+```sh
+npx repograph-cli ./my-app --output ./architecture.html --theme matrix
+npx repograph-cli . --format json > graph.json
+npx repograph-cli . --format mermaid --output architecture.mmd
+npx repograph-cli . --format svg --output architecture.svg
+npx repograph-cli . --max-depth 10 --no-collapse-utils
+```
+
+The static SVG arranges files in entry → business → unknown → data → util columns. Mermaid exports preserve nested directory subgraphs. Both include utility candidates; HTML initially hides folded utilities and their edges.
+
+## Use with Claude
+
+### Install from the MCP Registry
+
+Registry metadata is prepared under the name `io.github.Karry1123/repograph`. After publication to the [official MCP Registry](https://registry.modelcontextprotocol.io), look up that name in a registry-compatible client; the manual Claude setup below also works.
+
+### Claude Desktop
+
+Add this entry to `claude_desktop_config.json`, merging it with existing servers:
+
+```json
+{
+  "mcpServers": {
+    "repograph": {
+      "command": "npx",
+      "args": ["-y", "repograph-cli", "mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, then ask: “Scan my repository at `/absolute/path/to/project` and show the impact of changing `src/core/graph.ts`.” Use an absolute repository path; the MCP server may start with a different working directory. Windows paths work too, for example `F:\\RepoGraph` in JSON.
+
+### Claude Code
+
+```sh
+claude mcp add repograph -- npx -y repograph-cli mcp
+```
+
+Ask Claude to generate an architecture map before a refactor, or find all transitive callers of a module before editing it. MCP mode uses stdio for the protocol and writes errors only to stderr.
+
+### Tools
+
+| Tool | Arguments | Result |
+| --- | --- | --- |
+| `scan_repository_graph` | `path` (required string), `maxDepth` (integer, default `6`), `collapseUtils` (boolean, default `true`) | ArchitectureGraph JSON with nodes, edges, nested clusters, and metrics |
+| `generate_architecture_html` | `path` (required string), `outputPath` (default `"./repograph.html"`), `theme` (`dark`, `light`, or `matrix`, default `dark`) | `{ success: true, filePath, nodeCount }` |
+| `query_impact_path` | `path` (required string), `changedFile` (required relative file ID or absolute path) | Normalized changed file, direct dependents, transitive dependents with BFS depth, affected clusters, and blast radius |
+
+For HTML generation, a relative `outputPath` is resolved against the repository path. An absolute output path is used directly. The tools use a utility fan-in threshold of 15. Missing changed files return an error with the closest matching IDs. `transitiveDependents` includes direct callers at depth 1; `blastRadius` counts unique affected files and excludes the changed file itself.
+
+## How the map works
+
+### Imports become edges
+
+Each source file becomes a node with a forward-slash relative ID. Local imports become directed edges from importer to dependency. JavaScript and TypeScript use Babel, with a regex fallback for unsupported syntax. Repeated references of the same type are combined with an edge weight. External packages are dropped. Class inheritance through an imported binding gets an `inheritance` edge; `import()` gets a `dynamic` edge.
+
+RepoGraph tries source extensions, directory index files, NodeNext `.js` → `.ts` equivalents, and a heuristic `@/` → `src/` alias. It does not execute code or load project-specific compiler plugins. Computed imports and custom aliases can be missed.
+
+### Layers give the graph meaning
+
+| Layer | File or directory clues | Colour |
+| --- | --- | --- |
+| Entry | controller, route, router, handler, api, endpoint, cli, app, server, main; root index | Cyan |
+| Business | service, usecase, core, domain, logic, manager | Magenta |
+| Data | repo, repository, model, schema, entity, store, db, dao, migration | Amber |
+| Util | util, utils, helpers, common, shared, lib, constants, types, config; high fan-in | Slate |
+| Unknown | Everything else | Indigo |
+
+Classification checks entry, business, data, then utility clues. It is an explainable filename heuristic, not a semantic judgement about your design. Clusters reflect the first two directory levels and retain nested parents.
+
+### Utility folding reduces noise
+
+Files with more than 12 incoming callers and at most two outgoing dependencies, or utility-like names, are folding candidates. CLI/API default to 12; MCP defaults to 15. Folded nodes and their edges stay in the graph data and impact analysis but disappear from the initial HTML view. “Show utilities” reveals them. Degree counts use unique neighboring files, not repeated imports.
+
+### Blast radius follows callers
+
+Impact analysis performs a breadth-first search over reverse edges. It handles cycles, visits each file once, and records the shortest caller depth. The inspector lists direct callers and dependencies; the highlight traces both full transitive chains. If a cycle belongs to both chains, the dependency highlight takes precedence.
+
+Dead-code warnings count files with no incoming local edges that do not look like entry points. Treat these as review hints: frameworks, reflection, external consumers, and dynamic loading can all create valid files with no static callers. Coupling factor is average unique out-degree; density is edges divided by `n * (n - 1)` (zero for fewer than two files). LOC counts nonblank source lines, including comments.
+
+## Supported languages and scan rules
+
+| Language | Resolution |
+| --- | --- |
+| JavaScript / TypeScript | ESM imports/re-exports, `require()`, dynamic imports, imported superclass bindings; JS/JSX/MJS/CJS/TS/TSX/MTS/CTS |
+| Python | `import a.b`, absolute and relative `from` imports, `.py` modules and `__init__.py` packages |
+| Go | Single imports and import blocks; paths under the root `go.mod` module resolve to every scanned `.go` file in the target directory |
+| Rust | `mod x;` resolves to `x.rs` or `x/mod.rs`; `use crate::...` resolves modules under `src/` |
+
+Root and nested `.gitignore` rules are respected. RepoGraph skips dependency, build, cache, and editor directories, including `node_modules`, `.git`, `dist`, `build`, `out`, `coverage`, `__pycache__`, `.venv`, `venv`, `.next`, `.nuxt`, `target`, `vendor`, `.idea`, `.vscode`, and `.cache`. Symlinks are skipped to prevent cycles. Files larger than 1.5 MB and `*.min.js` are excluded. Test/spec files are excluded from the main graph, with their count retained as `metrics.excludedTestFiles`.
+
+Python, Go, and Rust resolution is intentionally static and heuristic: workspace manifests, build tags, Python import hooks, Rust macros, and non-root Go modules are not evaluated. Only files included in the scan can become nodes or targets.
+
+## Where it fits
+
+This table describes the tools' focus rather than a feature-completeness or performance benchmark. Check each project's current documentation for its full capabilities.
+
+| | RepoGraph | Madge | CodeSee | Gitingest |
+| --- | --- | --- | --- | --- |
+| Primary output | Local interactive HTML architecture map | Module dependency graphs | Code exploration and mapping platform | Repository text context |
+| Workflow | CLI + three MCP tools | Dependency analysis CLI/API | Platform workflow | Ingest code for LLM context |
+| Main emphasis | Layers, utility folding, caller impact | Module relationships and cycles | Collaborative code understanding | Shareable code context |
+| RepoGraph's approach | No server; embedded graph snapshot | Complementary dependency tooling | Different platform model | Complementary text-first tooling |
+
+## Programmatic use
+
+```ts
+import { analyzeRepository } from 'repograph-cli/dist/src/api.js';
+import { impactPath } from 'repograph-cli/dist/src/core/graph.js';
+import { renderToHtml } from 'repograph-cli/dist/src/renderer/htmlTemplate.js';
+
+const graph = await analyzeRepository('.', {
+  maxDepth: 6,
+  collapseUtils: true,
+  utilThreshold: 12,
+});
+const impact = impactPath(graph, 'src/api.ts');
+const html = renderToHtml(graph, { theme: 'dark' });
+```
+
+`createServer()` and `startMcpServer()` are exported from `dist/src/index.js`; importing the module does not start a transport. The graph data model lives in `src/types.ts` and ships with generated TypeScript declarations.
+
+## Contributing
+
+```sh
+npm install
+npm run build
+node dist/bin/cli.js . --output demo/self.html
+node dist/bin/cli.js . --format json
+node dist/bin/cli.js . --format mermaid
+```
+
+During development, use `npm run dev -- .`. On Windows PowerShell installations that block `npm.ps1`, use `npm.cmd`. Keep path IDs portable, avoid executing scanned code, and test resolution changes against a small repository containing the relevant imports. Include reproduction steps and the expected edges in bug reports or contributions.
+
+## License
+
+MIT © 2026 Karry. See [LICENSE](LICENSE).
+
+## Roadmap · star to vote
+
+- [x] TypeScript/JavaScript
+- [x] Python
+- [x] Go
+- [x] Rust
+- [ ] Java/Kotlin (unlocks at 200 ⭐)
+- [ ] C# (300 ⭐)
+- [ ] PHP/Ruby (500 ⭐)
+- [ ] Monorepo workspace + tsconfig paths alias resolution (200 ⭐)
+- [ ] VS Code extension (1000 ⭐)
+
+Star to vote, open a [Language Support Request issue](https://github.com/Karry1123/repograph/issues/new?template=language_support_request.yml), and share the imports and project layout you need supported. These thresholds guide priorities rather than promise delivery dates.

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { Command, InvalidArgumentError } from 'commander';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { analyzeRepository } from '../src/api.js';
+import { renderToHtml } from '../src/renderer/htmlTemplate.js';
+import { renderToMermaid, renderToSvg } from '../src/renderer/svgExport.js';
+import { startMcpServer } from '../src/index.js';
+const program = new Command();
+program.name('repograph-cli').version('0.1.1').description('Turn a local codebase into an interactive architecture map')
+    .argument('[path]', 'Repository directory', '.')
+    .option('-o, --output <file>', 'Output file (HTML defaults to repograph.html)')
+    .option('--theme <theme>', 'dark, light, or matrix', 'dark')
+    .option('--max-depth <n>', 'Maximum directory depth', value => {
+    if (!/^\d+$/.test(value))
+        throw new InvalidArgumentError('Expected a nonnegative integer');
+    return Number(value);
+}, 6)
+    .option('--no-collapse-utils', 'Show utility nodes initially')
+    .option('--format <format>', 'html, json, mermaid, or svg', 'html')
+    .action(async (directory, options) => {
+    if (!['dark', 'light', 'matrix'].includes(options.theme))
+        throw new Error('Theme must be dark, light, or matrix');
+    if (!['html', 'json', 'mermaid', 'svg'].includes(options.format))
+        throw new Error('Format must be html, json, mermaid, or svg');
+    const graph = await analyzeRepository(directory, options);
+    const content = options.format === 'json' ? JSON.stringify(graph, null, 2) + '\n' : options.format === 'mermaid' ? renderToMermaid(graph) : options.format === 'svg' ? renderToSvg(graph) : renderToHtml(graph, { theme: options.theme });
+    if (options.output || options.format === 'html') {
+        const output = path.resolve(options.output ?? 'repograph.html');
+        await mkdir(path.dirname(output), { recursive: true });
+        await writeFile(output, content, 'utf8');
+        if (options.format === 'html')
+            console.log(pathToFileURL(output).href);
+    }
+    else
+        process.stdout.write(content);
+});
+program.command('mcp').description('Start the MCP stdio server').action(async () => { await startMcpServer(); });
+program.parseAsync().catch(error => { console.error(error instanceof Error ? error.message : error); process.exitCode = 1; });

package/dist/src/api.d.ts

@@ -0,0 +1,7 @@
+import type { ArchitectureGraph } from './types.js';
+export interface AnalyzeOptions {
+    maxDepth?: number;
+    collapseUtils?: boolean;
+    utilThreshold?: number;
+}
+export declare function analyzeRepository(directory: string, options?: AnalyzeOptions): Promise<ArchitectureGraph>;

package/dist/src/api.js

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import { stat } from 'node:fs/promises';
+import { walkRepository } from './scanner/walker.js';
+import { extractImports } from './scanner/extractor.js';
+import { isTestFile } from './scanner/heuristics.js';
+import { buildGraph, pruneNoise } from './core/graph.js';
+export async function analyzeRepository(directory, options = {}) {
+    const root = path.resolve(directory);
+    if (!(await stat(root)).isDirectory())
+        throw new Error('Repository path must be a directory: ' + root);
+    const maxDepth = options.maxDepth ?? 6;
+    if (!Number.isInteger(maxDepth) || maxDepth < 0)
+        throw new Error('maxDepth must be a nonnegative integer');
+    const scanned = await walkRepository(root, maxDepth);
+    const testFileCount = scanned.filter(isTestFile).length;
+    const files = scanned.filter(file => !isTestFile(file));
+    const { edges, loc } = await extractImports(root, files);
+    const graph = buildGraph(root, files, edges, loc);
+    // Keep the specified public model intact while exposing the excluded count.
+    Object.assign(graph.metrics, { excludedTestFiles: testFileCount });
+    return options.collapseUtils === false ? graph : pruneNoise(graph, { threshold: options.utilThreshold ?? 12 });
+}

package/dist/src/core/cluster.d.ts

@@ -0,0 +1,3 @@
+import type { CodeNode } from '../types.js';
+export declare const LAYER_COLORS: Record<CodeNode['layer'], string>;
+export declare function classifyLayer(node: CodeNode): CodeNode['layer'];

package/dist/src/core/cluster.js

@@ -0,0 +1,13 @@
+import { isEntryLike, isUtility, nameTokens } from '../scanner/heuristics.js';
+export const LAYER_COLORS = { entry: '#22d3ee', business: '#e879f9', data: '#fbbf24', util: '#94a3b8', unknown: '#818cf8' };
+export function classifyLayer(node) {
+    if (isEntryLike(node.id))
+        return 'entry';
+    if (/(?:^|[/_.-])(?:services?|usecases?|core|domain|logic|managers?)(?:[/_.-]|$)/i.test(nameTokens(node.id)))
+        return 'business';
+    if (/(?:^|[/_.-])(?:repos?|repositories|repository|models?|schemas?|entities|entity|stores?|db|dao|migrations?)(?:[/_.-]|$)/i.test(nameTokens(node.id)))
+        return 'data';
+    if (isUtility(node))
+        return 'util';
+    return 'unknown';
+}

package/dist/src/core/graph.d.ts

@@ -0,0 +1,16 @@
+import type { ArchitectureGraph, CodeEdge } from '../types.js';
+export declare function adjacencyList(graph: ArchitectureGraph, reverse?: boolean): Map<string, Set<string>>;
+export declare function buildGraph(rootPath: string, files: string[], edges: CodeEdge[], loc: Map<string, number>): ArchitectureGraph;
+export declare function pruneNoise(graph: ArchitectureGraph, { threshold }?: {
+    threshold?: number;
+}): ArchitectureGraph;
+export declare function impactPath(graph: ArchitectureGraph, changedFile: string): {
+    changedFile: string;
+    directDependents: string[];
+    transitiveDependents: {
+        id: string;
+        depth: number;
+    }[];
+    affectedClusters: string[];
+    blastRadius: number;
+};

package/dist/src/core/graph.js

@@ -0,0 +1,76 @@
+import path from 'node:path';
+import { classifyLayer } from './cluster.js';
+import { isEntryLike, isUtility } from '../scanner/heuristics.js';
+import { normalize } from '../scanner/walker.js';
+export function adjacencyList(graph, reverse = false) {
+    const map = new Map(graph.nodes.map(node => [node.id, new Set()]));
+    for (const edge of graph.edges)
+        map.get(reverse ? edge.target : edge.source)?.add(reverse ? edge.source : edge.target);
+    return map;
+}
+export function buildGraph(rootPath, files, edges, loc) {
+    const clusters = new Map();
+    const nodes = files.map(id => {
+        const dirs = id.split('/').slice(0, -1).slice(0, 2);
+        if (!dirs.length)
+            dirs.push('(root)');
+        let parent;
+        for (let n = 1; n <= dirs.length; n++) {
+            const clusterId = 'cluster:' + dirs.slice(0, n).join('/');
+            clusters.set(clusterId, { id: clusterId, label: dirs[n - 1], ...(parent ? { parent } : {}) });
+            parent = clusterId;
+        }
+        return { id, label: path.posix.basename(id), layer: 'unknown', cluster: parent, inDegree: 0, outDegree: 0, linesOfCode: loc.get(id) ?? 0, language: /\.py$/.test(id) ? 'Python' : /\.go$/.test(id) ? 'Go' : /\.rs$/.test(id) ? 'Rust' : /\.[cm]?tsx?$/.test(id) ? 'TypeScript' : 'JavaScript' };
+    });
+    const graph = { rootPath, generatedAt: new Date().toISOString(), nodes, edges, clusters: [...clusters.values()], metrics: { totalFiles: nodes.length, totalEdges: edges.length, density: 0, couplingFactor: 0, deadCodeCount: 0, foldedUtilityCount: 0 } };
+    const outgoing = adjacencyList(graph), incoming = adjacencyList(graph, true);
+    for (const node of nodes) {
+        node.inDegree = incoming.get(node.id).size;
+        node.outDegree = outgoing.get(node.id).size;
+        node.layer = classifyLayer(node);
+    }
+    const n = nodes.length;
+    graph.metrics.density = n > 1 ? edges.length / (n * (n - 1)) : 0;
+    graph.metrics.couplingFactor = n ? nodes.reduce((sum, node) => sum + node.outDegree, 0) / n : 0;
+    graph.metrics.deadCodeCount = nodes.filter(node => node.inDegree === 0 && !isEntryLike(node.id)).length;
+    return graph;
+}
+// Preserve the full edge set for utilities toggling and impact queries. Renderers
+// exclude edges touching isFolded nodes from the initial main view.
+export function pruneNoise(graph, { threshold = 12 } = {}) {
+    for (const node of graph.nodes)
+        node.isFolded = isUtility(node, threshold);
+    graph.metrics.foldedUtilityCount = graph.nodes.filter(node => node.isFolded).length;
+    return graph;
+}
+export function impactPath(graph, changedFile) {
+    const id = normalize(path.isAbsolute(changedFile) ? path.relative(graph.rootPath, changedFile) : changedFile).replace(/^\.\//, '');
+    if (!graph.nodes.some(node => node.id === id)) {
+        const score = (candidate) => {
+            const a = id.toLowerCase(), b = candidate.toLowerCase();
+            const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+            for (let i = 1; i <= a.length; i++) {
+                let prev = row[0];
+                row[0] = i;
+                for (let j = 1; j <= b.length; j++) {
+                    const old = row[j];
+                    row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+                    prev = old;
+                }
+            }
+            return row[b.length];
+        };
+        throw new Error('File not found: ' + id + '. Closest matching ids: ' + graph.nodes.map(node => node.id).sort((a, b) => score(a) - score(b)).slice(0, 5).join(', '));
+    }
+    const reverse = adjacencyList(graph, true), visited = new Set([id]), queue = [{ id, depth: 0 }], dependents = [];
+    for (let i = 0; i < queue.length; i++)
+        for (const caller of reverse.get(queue[i].id) ?? []) {
+            if (!visited.has(caller)) {
+                visited.add(caller);
+                const item = { id: caller, depth: queue[i].depth + 1 };
+                queue.push(item);
+                dependents.push(item);
+            }
+        }
+    return { changedFile: id, directDependents: [...(reverse.get(id) ?? [])], transitiveDependents: dependents, affectedClusters: [...new Set(graph.nodes.filter(node => dependents.some(item => item.id === node.id)).map(node => node.cluster))], blastRadius: dependents.length };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+export declare function startMcpServer(): Promise<McpServer>;

package/dist/src/index.js

@@ -0,0 +1,57 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { analyzeRepository } from './api.js';
+import { impactPath } from './core/graph.js';
+import { renderToHtml } from './renderer/htmlTemplate.js';
+export function createServer() {
+    const server = new McpServer({ name: 'repograph-cli', version: '0.1.1' });
+    const result = (data) => ({ content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] });
+    const failure = (error) => ({ ...result({ error: error instanceof Error ? error.message : String(error) }), isError: true });
+    server.tool('scan_repository_graph', 'Scan a local codebase into an architecture graph. Test files and external imports are excluded.', {
+        path: z.string(), maxDepth: z.number().int().nonnegative().default(6), collapseUtils: z.boolean().default(true)
+    }, async (args) => {
+        try {
+            return result(await analyzeRepository(args.path, { ...args, utilThreshold: 15 }));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.tool('generate_architecture_html', 'Write a self-contained interactive architecture map of a local codebase.', {
+        path: z.string(), outputPath: z.string().default('./repograph.html'), theme: z.enum(['dark', 'light', 'matrix']).default('dark')
+    }, async (args) => {
+        try {
+            const graph = await analyzeRepository(args.path, { utilThreshold: 15 });
+            const filePath = path.resolve(args.path, args.outputPath);
+            await mkdir(path.dirname(filePath), { recursive: true });
+            await writeFile(filePath, renderToHtml(graph, { theme: args.theme }), 'utf8');
+            return result({ success: true, filePath, nodeCount: graph.nodes.length });
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    server.tool('query_impact_path', 'Find direct and transitive callers of a changed file, with BFS depths and affected clusters.', {
+        path: z.string(), changedFile: z.string()
+    }, async (args) => {
+        try {
+            return result(impactPath(await analyzeRepository(args.path, { utilThreshold: 15 }), args.changedFile));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    });
+    return server;
+}
+export async function startMcpServer() {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    return server;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+    startMcpServer().catch(error => { console.error(error); process.exitCode = 1; });
+}

package/dist/src/renderer/htmlTemplate.d.ts

@@ -0,0 +1,4 @@
+import type { ArchitectureGraph } from '../types.js';
+export declare function renderToHtml(graph: ArchitectureGraph, options: {
+    theme: 'dark' | 'light' | 'matrix';
+}): string;

package/dist/src/renderer/htmlTemplate.js

@@ -0,0 +1,297 @@
+import { LAYER_COLORS } from '../core/cluster.js';
+export function renderToHtml(graph, options) {
+    // HTML is shareable: retain the repository label without embedding a local path.
+    const rootLabel = graph.rootPath.replace(/\\/g, '/').replace(/\/$/, '').split('/').pop() || 'repository';
+    const json = JSON.stringify({ ...graph, rootPath: rootLabel }).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    return `<!DOCTYPE html>
+<html lang="en" data-theme="${options.theme}">
+<head>
+<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="color-scheme" content="dark light">
+<title>RepoGraph · Architecture map</title>
+<style>
+:root{--bg:#0f172a;--canvas:#090d16;--panel:#111b2d;--text:#e2e8f0;--muted:#94a3b8;--line:#29364c;--accent:#22d3ee;--pink:#e879f9;--amber:#fbbf24;--shadow:0 12px 40px #0005;--incoming:#22d3ee;--outgoing:#fb7185}
+[data-theme=light]{--bg:#f1f5f9;--canvas:#f8fafc;--panel:#fff;--text:#0f172a;--muted:#526277;--line:#cbd5e1;--accent:#0284c7;--pink:#a21caf;--amber:#b45309;--shadow:0 12px 40px #33415515;--incoming:#0284c7;--outgoing:#dc2626}
+[data-theme=matrix]{--bg:#020802;--canvas:#000;--panel:#041004;--text:#b2ffba;--muted:#6ea879;--line:#184721;--accent:#39ff6b;--pink:#aaff88;--amber:#d5ff53;--shadow:0 12px 40px #00ff1110;--incoming:#39ff6b;--outgoing:#ff6363}
+*{box-sizing:border-box}body{margin:0;height:100vh;overflow:hidden;background:var(--bg);color:var(--text);font:13px/1.5 system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif}button,input,select{font:inherit}button{cursor:pointer;color:var(--text);background:var(--panel);border:1px solid var(--line);border-radius:8px;padding:8px 12px;transition:background .15s,border-color .15s}button:hover{border-color:var(--accent)}button:focus-visible,input:focus-visible,select:focus-visible,a:focus-visible{outline:2px solid var(--accent);outline-offset:3px}button:disabled{opacity:.4;cursor:default}header{height:72px;display:flex;align-items:center;gap:24px;padding:0 24px;border-bottom:1px solid var(--line);position:relative;z-index:3;background:var(--bg)}.brand{display:flex;align-items:center;gap:10px;white-space:nowrap}.logo{display:grid;place-items:center;background:var(--accent);color:var(--canvas);width:32px;height:32px;border-radius:9px;font-size:21px;font-weight:800}.brand strong{font-size:18px;letter-spacing:-.6px}.version{font:10px monospace;color:var(--muted);border:1px solid var(--line);padding:2px 5px;border-radius:4px}.metrics{display:flex;align-items:center;gap:0;margin:auto;border:1px solid var(--line);background:var(--panel);border-radius:24px;overflow:hidden}.metric{padding:7px 17px;border-right:1px solid var(--line);white-space:nowrap}.metric:last-child{border:0}.metric b{margin-right:5px;font-variant-numeric:tabular-nums}.metric span{font-size:11px;color:var(--muted)}.metric.warning b{color:var(--amber)}.header-actions{display:flex;gap:8px;align-items:center}select{background:var(--panel);color:var(--text);border:1px solid var(--line);border-radius:8px;padding:8px}.workspace{height:calc(100vh - 72px);position:relative;display:flex}#cy{position:absolute;inset:0 320px 0 0;background:var(--canvas)}.toolbar{position:absolute;left:22px;top:22px;display:flex;gap:8px;align-items:center;z-index:2}.search-wrap{position:relative}.search-wrap:before{content:'⌕';position:absolute;left:12px;top:4px;font-size:24px;color:var(--muted)}#search{background:var(--panel);border:1px solid var(--line);color:var(--text);width:280px;padding:11px 52px 11px 38px;border-radius:10px;box-shadow:var(--shadow)}#search::placeholder{color:var(--muted)}.key{position:absolute;right:10px;top:11px;font:11px monospace;color:var(--muted);border:1px solid var(--line);padding:0 4px;border-radius:3px}.search-results{position:absolute;top:51px;left:0;background:var(--panel);border:1px solid var(--line);border-radius:10px;box-shadow:var(--shadow);width:350px;max-height:320px;overflow:auto;display:none}.search-results.open{display:block}.search-result{display:block;text-align:left;border:0;border-radius:0;width:100%;padding:10px 13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;font:11px/1.6 monospace}.search-result:hover{background:var(--bg);color:var(--accent)}.search-caption{padding:8px 13px;color:var(--muted);font-size:11px;border-bottom:1px solid var(--line)}.controls{display:flex;gap:6px}.controls button{box-shadow:var(--shadow);height:41px}.utilities{position:absolute;left:22px;top:79px;display:flex;gap:9px;align-items:center;background:var(--panel);padding:8px 12px;border:1px solid var(--line);border-radius:9px;color:var(--muted);font-size:12px;z-index:2;box-shadow:var(--shadow);cursor:pointer}.utilities input{accent-color:var(--accent);margin:0}.utilities strong{color:var(--text);font-size:11px;background:var(--bg);padding:0 5px;border-radius:4px}.legend{position:absolute;left:22px;bottom:42px;background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:13px 15px;box-shadow:var(--shadow);z-index:2;min-width:165px}.eyebrow{text-transform:uppercase;font-size:10px;letter-spacing:1.5px;color:var(--muted);margin-bottom:10px}.legend-row{display:flex;align-items:center;gap:9px;margin-top:7px;font-size:12px}.dot{width:9px;height:9px;border-radius:50%;display:inline-block;flex-shrink:0}.legend-row small{margin-left:auto;color:var(--muted);font-variant-numeric:tabular-nums}.legend-separator{border-top:1px solid var(--line);margin:12px 0 8px}.line-key{display:inline-block;width:16px;height:2px;background:var(--muted)}.line-key.in{background:var(--incoming)}.line-key.out{background:var(--outgoing)}#sidebar{position:absolute;right:0;top:0;bottom:0;width:320px;background:var(--bg);border-left:1px solid var(--line);overflow:auto;z-index:3}.side-top{padding:22px;border-bottom:1px solid var(--line)}.side-title{font-size:15px;font-weight:650;margin:0 0 7px}.side-sub{color:var(--muted);font-size:12px;margin:0}.side-body{padding:22px}.empty-icon{width:56px;height:56px;display:grid;place-items:center;margin:24px 0 20px;border-radius:15px;border:1px solid var(--line);color:var(--accent);font-size:26px}.empty-title{font-size:17px;font-weight:600}.hint{color:var(--muted);font-size:12px;line-height:1.8}.hint-list{padding-left:17px;color:var(--muted);font-size:12px;line-height:1.9}.hint-list li{padding:3px 0}.repo-path{font:11px/1.7 monospace;overflow-wrap:anywhere;color:var(--muted);margin-top:20px;padding-top:15px;border-top:1px solid var(--line)}.file-path{font:12px/1.8 monospace;overflow-wrap:anywhere;margin:0 0 15px}.badge{display:inline-flex;align-items:center;gap:6px;font-size:11px;padding:3px 8px;border-radius:6px;background:var(--panel);border:1px solid var(--line);margin:0 5px 5px 0}.stats-grid{display:grid;grid-template-columns:1fr 1fr;gap:9px;margin:18px 0}.stat-card{padding:12px;background:var(--panel);border:1px solid var(--line);border-radius:9px}.stat-card b{font-size:20px;display:block;font-weight:600;line-height:1.3}.stat-card span{font-size:10px;color:var(--muted);text-transform:uppercase;letter-spacing:.8px}.detail-heading{font-size:11px;text-transform:uppercase;letter-spacing:1px;margin:22px 0 10px;color:var(--muted);display:flex;justify-content:space-between}.file-list{display:flex;flex-direction:column;gap:5px}.file-link{display:flex;align-items:center;gap:8px;text-align:left;width:100%;font:11px/1.6 monospace;padding:7px 9px;border-radius:6px;overflow-wrap:anywhere}.file-link span:last-child{min-width:0;overflow-wrap:anywhere}.no-items{color:var(--muted);font-size:12px;font-style:italic}.selection-note{padding:10px 12px;border-left:2px solid var(--accent);background:var(--panel);color:var(--muted);font-size:11px;margin-top:18px;line-height:1.8}.radar{position:absolute;right:340px;bottom:42px;width:190px;height:135px;border:1px solid var(--line);border-radius:10px;background:var(--panel);box-shadow:var(--shadow);z-index:2;overflow:hidden}.radar-label{position:absolute;left:10px;top:7px;font-size:9px;letter-spacing:1.5px;color:var(--muted);pointer-events:none}.radar canvas{width:100%;height:100%;cursor:crosshair}.statusbar{position:absolute;bottom:0;left:0;right:320px;height:27px;border-top:1px solid var(--line);background:var(--bg);display:flex;align-items:center;gap:18px;padding:0 18px;color:var(--muted);font:10px monospace;z-index:2}.statusbar .spacer{flex:1}.status-indicator{display:inline-block;width:5px;height:5px;border-radius:50%;background:var(--accent);margin-right:6px}.toast{position:absolute;left:50%;bottom:46px;transform:translateX(-50%);max-width:500px;padding:10px 18px;background:var(--panel);color:var(--text);border:1px solid var(--line);border-radius:10px;box-shadow:var(--shadow);z-index:6;display:none;font-size:12px}.toast.open{display:block}.loading{position:absolute;inset:0 320px 0 0;display:grid;place-items:center;background:var(--canvas);z-index:5}.loading-card{max-width:460px;padding:28px;text-align:center}.loading-card strong{font-size:19px;display:block;margin:14px}.loading-card p{color:var(--muted);line-height:1.8}.spinner{width:32px;height:32px;border:2px solid var(--line);border-top-color:var(--accent);border-radius:50%;animation:spin 1s linear infinite;margin:auto}@keyframes spin{to{transform:rotate(360deg)}}dialog{color:var(--text);background:var(--panel);border:1px solid var(--line);border-radius:15px;padding:26px;max-width:540px;box-shadow:var(--shadow)}dialog::backdrop{background:#0008}dialog h2{margin:0 0 15px;font-size:20px}dialog p{color:var(--muted);line-height:1.8}dialog kbd{border:1px solid var(--line);border-radius:4px;padding:1px 5px;color:var(--text)}.help-row{display:flex;justify-content:space-between;gap:30px;padding:8px 0;border-bottom:1px solid var(--line)}.help-row span{color:var(--muted)}.help-close{margin-top:20px;float:right}.cluster-note{color:var(--amber);font-size:12px;padding:10px;background:var(--panel);border:1px solid var(--line);border-radius:8px;margin-top:14px}
+@media(max-width:1180px){header{padding:0 16px;gap:12px}.metric{padding:7px 10px}.metric span{font-size:10px}.version{display:none}.toolbar{gap:6px;left:16px}#search{width:220px}.controls button{padding:8px}.utilities{left:16px}.brand strong{font-size:16px}}
+@media(max-width:960px){.metric:nth-child(4),.metric:nth-child(5){display:none}.header-actions select{width:80px}#sidebar{width:270px}#cy,.loading{right:270px}.radar{right:286px;width:155px;height:110px}.statusbar{right:270px}.toolbar{flex-wrap:wrap;right:285px}.controls button{height:36px}.utilities{top:122px}#search{width:230px}.legend{bottom:42px;padding:10px;min-width:145px}}
+@media(max-width:700px){header{height:62px;gap:8px}.brand strong{font-size:14px}.logo{width:27px;height:27px;font-size:18px}.metrics{margin-left:auto;margin-right:0}.metric{padding:5px 9px}.metric:nth-child(n+3){display:none}.metric span{display:none}.header-actions select{width:70px;font-size:11px;padding:6px}.header-actions button{padding:6px 9px}.workspace{height:calc(100vh - 62px)}#sidebar{top:auto;bottom:27px;width:100%;height:190px;border-left:0;border-top:1px solid var(--line)}.side-top{padding:12px 16px}.side-body{padding:12px 16px}.side-body .empty-icon,.side-body .hint-list,.side-body .repo-path{display:none}.empty-title{font-size:14px}#cy,.loading{right:0;bottom:217px}.statusbar{right:0;font-size:9px;gap:8px}.radar{right:14px;bottom:232px;width:135px;height:95px}.legend{bottom:232px;font-size:10px;min-width:120px;padding:9px}.legend .legend-separator,.legend .chain-key{display:none}.legend-row{font-size:10px;margin-top:4px}.toolbar{right:14px;left:14px;top:14px;flex-wrap:nowrap}#search{width:190px;padding-right:12px}.search-wrap .key{display:none}.search-results{width:280px}.utilities{top:68px;left:14px}.controls{margin-left:auto}.controls button{font-size:11px}.stats-grid{grid-template-columns:repeat(4,1fr);margin:12px 0}.stat-card{padding:8px}.stat-card b{font-size:16px}.toast{bottom:225px;width:80%}}
+@media(prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}
+</style>
+</head>
+<body>
+<header>
+ <div class="brand"><div class="logo" aria-hidden="true">⌘</div><strong>repograph-cli</strong><span class="version">v0.1.1</span></div>
+ <div class="metrics" aria-label="Repository metrics" id="metrics"></div>
+ <div class="header-actions"><select id="theme" aria-label="Color theme"><option value="dark">Dark</option><option value="light">Light</option><option value="matrix">Matrix</option></select><button id="help-button" aria-label="Help and keyboard shortcuts">?</button></div>
+</header>
+<main class="workspace">
+ <div id="cy" role="application" aria-label="Interactive repository architecture graph"></div>
+ <div class="toolbar"><div class="search-wrap"><label for="search" hidden>Find files</label><input id="search" autocomplete="off" spellcheck="false" placeholder="Find a file or path…"><span class="key">/</span><div class="search-results" id="search-results"></div></div><div class="controls"><button id="relayout" title="Run force-directed layout again">Re-layout</button><button id="fit" title="Fit visible graph (F)">Fit</button></div></div>
+ <label class="utilities"><input type="checkbox" id="show-utils">Show utilities <strong id="folded-count">0</strong></label>
+ <div class="legend"><div class="eyebrow">Architecture layers</div><div id="layer-legend"></div><div class="legend-separator"></div><div class="legend-row chain-key"><span class="line-key in"></span>Incoming callers</div><div class="legend-row chain-key"><span class="line-key out"></span>Outgoing dependencies</div></div>
+ <aside id="sidebar" aria-label="File inspector"><div class="side-top"><h1 class="side-title">Architecture explorer</h1><p class="side-sub">Follow the connections in your code.</p></div><div class="side-body" id="details"></div></aside>
+ <div class="radar"><span class="radar-label">OVERVIEW</span><canvas id="minimap" aria-label="Graph overview; click to pan"></canvas></div>
+ <footer class="statusbar"><span><i class="status-indicator"></i><span id="status">Preparing graph</span></span><span id="zoom">100%</span><span class="spacer"></span><span id="generated"></span><span>LOCAL SNAPSHOT</span></footer>
+ <div id="loading" class="loading"><div class="loading-card"><div class="spinner"></div><strong>Mapping your codebase</strong><p id="loading-message">Loading the graph engine and arranging your architecture…</p></div></div>
+ <div id="toast" class="toast" role="status" aria-live="polite"></div>
+</main>
+<dialog id="help"><h2>Explore your architecture</h2><p>Each dot is a source file. Arrows point from a caller to its dependency. Boxes group files by their first two directory levels.</p><div class="help-row"><span>Search file paths</span><kbd>/</kbd></div><div class="help-row"><span>Fit visible graph</span><kbd>F</kbd></div><div class="help-row"><span>Reset selection and search</span><kbd>Esc</kbd></div><div class="help-row"><span>Inspect dependencies and callers</span><kbd>Click a file</kbd></div><div class="help-row"><span>Collapse or expand a directory</span><kbd>Double-click a box</kbd></div><p>Cyan shows the incoming caller chain. Red shows the outgoing dependency chain. A file can belong to both chains when imports form a cycle. Dead-code warnings are heuristic: framework entry points and dynamically loaded modules may have no static callers.</p><p>Utilities remain part of the saved graph and impact queries. Use the utilities toggle to reveal them. This page uses a frozen scan; run RepoGraph again to refresh it.</p><button class="help-close" id="help-close">Got it</button></dialog>
+<script id="graph-data" type="application/json">${json}</script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/cytoscape/3.30.4/cytoscape.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/layout-base@2.0.1/layout-base.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/cose-base@2.2.0/cose-base.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/cytoscape-fcose@2.2.0/cytoscape-fcose.js"></script>
+<script>
+(() => {
+ 'use strict';
+ const graph = JSON.parse(document.getElementById('graph-data').textContent);
+ const colors = ${JSON.stringify(LAYER_COLORS)};
+ const $ = id => document.getElementById(id);
+ const nodesById = new Map(graph.nodes.map(node => [node.id, node]));
+ const clustersById = new Map(graph.clusters.map(cluster => [cluster.id, cluster]));
+ const incoming = new Map(graph.nodes.map(node => [node.id, new Set()]));
+ const outgoing = new Map(graph.nodes.map(node => [node.id, new Set()]));
+ graph.edges.forEach(edge => { incoming.get(edge.target)?.add(edge.source); outgoing.get(edge.source)?.add(edge.target); });
+ const collapsed = new Set();
+ const savedPositions = new Map();
+ const clusterPositions = new Map();
+ let selectedId = null;
+ let cy, layout, radarTransform, framePending = false, toastTimer;
+ const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+ const css = name => getComputedStyle(document.documentElement).getPropertyValue(name).trim();
+ const element = (tag, className, text) => { const el = document.createElement(tag); if (className) el.className = className; if (text !== undefined) el.textContent = text; return el; };
+ function toast(message) { $('toast').textContent = message; $('toast').classList.add('open'); clearTimeout(toastTimer); toastTimer = setTimeout(() => $('toast').classList.remove('open'), 3000); }
+ function metric(value, label, warning) { const item = element('div', 'metric' + (warning ? ' warning' : '')); item.append(element('b', '', String(value)), element('span', '', label)); $('metrics').append(item); }
+ metric(graph.metrics.totalFiles, 'Total files'); metric(graph.metrics.totalEdges, 'Edges'); metric(graph.metrics.couplingFactor.toFixed(2), 'Coupling factor'); metric(graph.metrics.deadCodeCount, 'Dead-code warnings', true); metric(graph.metrics.foldedUtilityCount, 'Folded utilities');
+ $('folded-count').textContent = graph.metrics.foldedUtilityCount;
+ $('generated').textContent = new Date(graph.generatedAt).toLocaleString();
+ $('theme').value = document.documentElement.dataset.theme;
+ for (const [layer, color] of Object.entries(colors)) {
+   const row = element('div', 'legend-row'); const dot = element('span', 'dot'); dot.style.background = color;
+   row.append(dot, element('span', '', layer.charAt(0).toUpperCase() + layer.slice(1)), element('small', '', String(graph.nodes.filter(node => node.layer === layer).length)));
+   $('layer-legend').append(row);
+ }
+ function emptyInspector() {
+   $('details').replaceChildren();
+   $('details').append(element('div', 'empty-icon', '◎'), element('div', 'empty-title', 'Find the center of change'), element('p', 'hint', 'Select a source file to trace its callers, dependencies, and blast radius.'));
+   const list = element('ul', 'hint-list');
+   ['Search uses subsequence matching across full paths.', 'Double-click a directory box or collapsed node to collapse or expand.', 'Press F to fit the graph.', 'Drag nodes to arrange your map; scroll to zoom.', 'Click the background to clear a selection.'].forEach(text => list.append(element('li', '', text)));
+   $('details').append(list, element('div', 'repo-path', graph.rootPath + '\\n' + graph.nodes.length + ' source files · ' + (graph.metrics.excludedTestFiles || 0) + ' test files excluded'));
+ }
+ emptyInspector();
+ if (typeof cytoscape === 'undefined') { $('loading-message').textContent = 'The CDN graph engine could not load. Connect to the internet and reopen this file. All repository data is embedded in this HTML.'; document.querySelector('.spinner').style.display = 'none'; return; }
+ function styleSheet() {
+   return [
+     { selector: 'node.file', style: { 'background-color': 'data(color)', 'label': 'data(label)', 'color': css('--text'), 'font-size': 10, 'font-family': 'system-ui, sans-serif', 'text-valign': 'bottom', 'text-margin-y': 7, 'text-outline-color': css('--canvas'), 'text-outline-width': 2, 'width': 'data(size)', 'height': 'data(size)', 'border-width': 1.5, 'border-color': 'data(color)', 'border-opacity': .3, 'background-opacity': .9, 'overlay-opacity': 0, 'min-zoomed-font-size': 5 } },
+     { selector: 'node.cluster', style: { 'shape': 'round-rectangle', 'background-color': css('--panel'), 'background-opacity': .24, 'border-width': 1, 'border-color': css('--line'), 'border-style': 'solid', 'label': 'data(label)', 'color': css('--muted'), 'font-size': 12, 'font-weight': 600, 'text-valign': 'top', 'text-halign': 'left', 'text-margin-x': 12, 'text-margin-y': 9, 'padding': 28, 'compound-sizing-wrt-labels': 'include', 'overlay-opacity': 0 } },
+     { selector: 'node.meta', style: { 'shape': 'round-rectangle', 'width': 125, 'height': 48, 'background-color': css('--panel'), 'background-opacity': 1, 'border-color': css('--accent'), 'border-width': 1.5, 'label': 'data(label)', 'color': css('--text'), 'font-size': 11, 'text-wrap': 'wrap', 'text-valign': 'center', 'text-halign': 'center', 'text-margin-y': 0 } },
+     { selector: 'edge', style: { 'curve-style': 'bezier', 'width': 1.2, 'line-color': css('--muted'), 'target-arrow-color': css('--muted'), 'target-arrow-shape': 'triangle', 'arrow-scale': .65, 'opacity': .4, 'overlay-opacity': 0 } },
+     { selector: 'edge[type = "dynamic"]', style: { 'line-style': 'dashed' } },
+     { selector: 'edge[type = "inheritance"]', style: { 'width': 2.2, 'target-arrow-shape': 'triangle-backcurve' } },
+     { selector: '.dim', style: { 'opacity': .15 } },
+     { selector: '.search-dim', style: { 'opacity': .15 } },
+     { selector: 'node.incoming', style: { 'background-color': css('--incoming'), 'border-color': css('--incoming'), 'opacity': 1 } },
+     { selector: 'edge.incoming', style: { 'line-color': css('--incoming'), 'target-arrow-color': css('--incoming'), 'width': 2, 'opacity': .9 } },
+     { selector: 'node.outgoing', style: { 'background-color': css('--outgoing'), 'border-color': css('--outgoing'), 'opacity': 1 } },
+     { selector: 'edge.outgoing', style: { 'line-color': css('--outgoing'), 'target-arrow-color': css('--outgoing'), 'width': 2, 'opacity': .9 } },
+     { selector: 'node.focus', style: { 'border-width': 4, 'border-color': css('--text'), 'background-color': css('--accent'), 'width': 30, 'height': 30, 'font-weight': 700, 'font-size': 12, 'opacity': 1 } },
+     { selector: '.hidden', style: { 'display': 'none' } }
+   ];
+ }
+ const elements = graph.clusters.map(cluster => ({ data: { id: cluster.id, label: cluster.label, ...(cluster.parent ? { parent: cluster.parent } : {}) }, classes: 'cluster' }));
+ graph.nodes.forEach(node => elements.push({ data: { ...node, parent: node.cluster, color: colors[node.layer], size: Math.min(28, 14 + Math.sqrt(node.inDegree + node.outDegree) * 2) }, classes: 'file' }));
+ graph.edges.forEach((edge, i) => elements.push({ data: { ...edge, id: 'edge:' + i } }));
+ cy = cytoscape({ container: $('cy'), elements, style: styleSheet(), layout: { name: 'preset' }, wheelSensitivity: .2, minZoom: .03, maxZoom: 4, boxSelectionEnabled: false, autounselectify: true });
+ function clusterContains(clusterId, node) {
+   let current = node.cluster;
+   while (current) { if (current === clusterId) return true; current = clustersById.get(current)?.parent; }
+   return false;
+ }
+ function visibleRepresentative(nodeId) {
+   const node = nodesById.get(nodeId); if (!node || (node.isFolded && !$('show-utils').checked)) return null;
+   let current = node.cluster, representative = nodeId;
+   while (current) { if (collapsed.has(current)) representative = 'meta:' + current; current = clustersById.get(current)?.parent; }
+   return representative;
+ }
+ function refreshVisibility() {
+   cy.nodes('.meta').forEach(node => clusterPositions.set(node.data('clusterId'), { ...node.position() }));
+   cy.batch(() => {
+     cy.elements('.meta, .meta-edge').remove();
+     cy.elements().removeClass('hidden');
+     graph.nodes.forEach(node => { if (visibleRepresentative(node.id) !== node.id) cy.getElementById(node.id).addClass('hidden'); });
+     for (const cluster of graph.clusters) {
+       let ancestor = cluster.parent, hidden = collapsed.has(cluster.id);
+       while (ancestor) { hidden = hidden || collapsed.has(ancestor); ancestor = clustersById.get(ancestor)?.parent; }
+       if (hidden) cy.getElementById(cluster.id).addClass('hidden');
+     }
+     for (const id of collapsed) {
+       const cluster = clustersById.get(id); let ancestor = cluster.parent, obscured = false;
+       while (ancestor) { if (collapsed.has(ancestor)) obscured = true; ancestor = clustersById.get(ancestor)?.parent; }
+       if (obscured) continue;
+       const children = graph.nodes.filter(node => clusterContains(id, node) && (!node.isFolded || $('show-utils').checked));
+       if (!children.length) continue;
+       const position = clusterPositions.get(id) || { x: 0, y: 0 };
+       cy.add({ data: { id: 'meta:' + id, clusterId: id, label: cluster.label + ' · ' + children.length + ' files', ...(cluster.parent ? { parent: cluster.parent } : {}) }, classes: 'meta', position });
+     }
+     const metaEdges = new Set();
+     graph.edges.forEach((edge, i) => {
+       const a = visibleRepresentative(edge.source), b = visibleRepresentative(edge.target);
+       if (a !== edge.source || b !== edge.target) cy.getElementById('edge:' + i).addClass('hidden');
+       if (!a || !b || a === b || (a === edge.source && b === edge.target)) return;
+       const key = a + '\\0' + b;
+       if (!metaEdges.has(key) && cy.getElementById(a).length && cy.getElementById(b).length) { metaEdges.add(key); cy.add({ data: { id: 'meta-edge:' + i, source: a, target: b, type: edge.type }, classes: 'meta-edge' }); }
+     });
+     // Hide empty compound boxes after utility filtering.
+     [...graph.clusters].reverse().forEach(cluster => { const el = cy.getElementById(cluster.id); if (!el.descendants().nodes().filter(n => !n.hasClass('cluster') && !n.hasClass('hidden')).length) el.addClass('hidden'); });
+   });
+   if (selectedId) highlight(selectedId);
+   applySearch(); updateStatus(); scheduleRadar();
+ }
+ function runLayout() {
+   if (layout) layout.stop();
+   $('relayout').disabled = true;
+   const visible = cy.elements().filter(el => !el.hasClass('hidden'));
+   const useFcose = typeof cytoscapeFcose !== 'undefined';
+   cy.one('layoutstop', () => { cy.fit(undefined, 40); scheduleRadar(); updateStatus(); });
+   layout = visible.layout({ name: useFcose ? 'fcose' : 'cose', quality: 'default', animate: false, randomize: true, fit: false, padding: 40, nodeDimensionsIncludeLabels: true, nodeRepulsion: () => 6500, idealEdgeLength: () => 95, edgeElasticity: () => .35, gravity: .22, numIter: 2000, tile: true, packComponents: true, stop: () => { $('relayout').disabled = false; $('loading').style.display = 'none'; scheduleRadar(); updateStatus(); } });
+   try { layout.run(); } catch (error) { $('relayout').disabled = false; $('loading').style.display = 'none'; visible.layout({ name: 'grid', fit: true, padding: 65 }).run(); toast('Force layout unavailable; showing a grid.'); console.error(error); }
+ }
+ function chain(start, adjacency) {
+   const visited = new Set([start]), queue = [start];
+   for (let i = 0; i < queue.length; i++) for (const id of adjacency.get(queue[i]) || []) if (!visited.has(id)) { visited.add(id); queue.push(id); }
+   return visited;
+ }
+ function highlight(id) {
+   cy.elements().removeClass('dim incoming outgoing focus');
+   const callers = chain(id, incoming), dependencies = chain(id, outgoing);
+   cy.elements().not('.cluster').addClass('dim');
+   function mark(ids, name) {
+     ids.forEach(key => { const rep = visibleRepresentative(key); if (rep) cy.getElementById(rep).removeClass('dim').addClass(name); });
+     graph.edges.forEach((edge, i) => {
+       if (!ids.has(edge.source) || !ids.has(edge.target)) return;
+       cy.getElementById('edge:' + i).removeClass('dim').addClass(name);
+       const a = visibleRepresentative(edge.source), b = visibleRepresentative(edge.target);
+       cy.edges('.meta-edge').filter(el => el.data('source') === a && el.data('target') === b).removeClass('dim').addClass(name);
+     });
+   }
+   mark(callers, 'incoming'); mark(dependencies, 'outgoing');
+   const rep = visibleRepresentative(id); if (rep) cy.getElementById(rep).removeClass('dim').addClass('focus');
+   scheduleRadar();
+ }
+ function showNode(id, center) {
+   const node = nodesById.get(id); if (!node) return;
+   selectedId = id; highlight(id); inspector(node);
+   if (center) { const rep = visibleRepresentative(id); if (rep) cy.animate({ center: { eles: cy.getElementById(rep) }, duration: reducedMotion ? 0 : 250 }); else toast('This utility is folded. Enable Show utilities to reveal it.'); }
+ }
+ function inspector(node) {
+   const details = $('details'); details.replaceChildren();
+   details.append(element('p', 'file-path', node.id));
+   const badge = element('span', 'badge'); const dot = element('span', 'dot'); dot.style.background = colors[node.layer]; badge.append(dot, document.createTextNode(node.layer)); details.append(badge, element('span', 'badge', node.language || 'Source'));
+   const grid = element('div', 'stats-grid');
+   [[node.inDegree, 'Callers'], [node.outDegree, 'Dependencies'], [node.linesOfCode, 'LOC'], [chain(node.id, incoming).size - 1, 'Blast radius']].forEach(([value, label]) => { const card = element('div', 'stat-card'); card.append(element('b', '', String(value)), element('span', '', label)); grid.append(card); });
+   details.append(grid);
+   details.append(element('div', 'hint', 'Cluster: ' + node.cluster.replace(/^cluster:/, '')));
+   if (node.isFolded) details.append(element('div', 'cluster-note', 'Utility candidate · folded until Show utilities is enabled.'));
+   if (!node.inDegree) details.append(element('div', 'selection-note', node.layer === 'entry' ? 'Entry-like file · no static callers.' : 'No static callers found. This may be unused code or an implicit runtime entry point.'));
+   function fileList(title, ids) {
+     const heading = element('div', 'detail-heading'); heading.append(element('span', '', title), element('span', '', String(ids.size))); details.append(heading);
+     const list = element('div', 'file-list');
+     [...ids].sort().forEach(id => { const target = nodesById.get(id); const button = element('button', 'file-link'); const dot = element('span', 'dot'); dot.style.background = colors[target.layer]; button.append(dot, element('span', '', id)); button.addEventListener('click', () => showNode(id, true)); list.append(button); });
+     if (!ids.size) list.append(element('div', 'no-items', 'None found'));
+     details.append(list);
+   }
+   fileList('Incoming callers', incoming.get(node.id)); fileList('Dependencies', outgoing.get(node.id));
+   details.append(element('div', 'selection-note', 'Highlight follows the full transitive graph. Sidebar lists direct connections. Red = dependency chain; cyan = caller chain.'));
+ }
+ function reset() { selectedId = null; cy.elements().removeClass('dim incoming outgoing focus'); emptyInspector(); scheduleRadar(); }
+ function fuzzy(query, value) { let index = 0; for (const char of value.toLowerCase()) if (char === query[index]) index++; return index === query.length; }
+ function applySearch() {
+   const query = $('search').value.trim().toLowerCase();
+   cy.elements().removeClass('search-dim');
+   const results = $('search-results'); results.replaceChildren(); results.classList.toggle('open', Boolean(query));
+   if (!query) return;
+   const matches = graph.nodes.filter(node => fuzzy(query, node.id));
+   const matchIds = new Set(matches.map(node => node.id));
+   const visibleIds = new Set(matches.map(node => visibleRepresentative(node.id)).filter(Boolean));
+   cy.nodes().not('.cluster').forEach(node => { if (!visibleIds.has(node.id())) node.addClass('search-dim'); });
+   cy.edges().forEach(edge => { if (!matchIds.has(edge.data('source')) && !matchIds.has(edge.data('target'))) edge.addClass('search-dim'); });
+   results.append(element('div', 'search-caption', matches.length + ' matching files' + (matches.length > 25 ? ' · showing first 25' : '')));
+   matches.slice(0, 25).forEach(node => { const button = element('button', 'search-result', node.id + (node.isFolded && !$('show-utils').checked ? ' (folded)' : '')); button.addEventListener('click', () => { showNode(node.id, true); results.classList.remove('open'); }); results.append(button); });
+   scheduleRadar();
+ }
+ function toggleCluster(id) {
+   if (collapsed.has(id)) {
+     collapsed.delete(id);
+     refreshVisibility();
+     const positions = savedPositions.get(id);
+     if (positions) cy.batch(() => positions.forEach((position, key) => cy.getElementById(key).position(position)));
+     savedPositions.delete(id);
+   } else {
+     const children = cy.nodes('.file').filter(node => clusterContains(id, nodesById.get(node.id())));
+     savedPositions.set(id, new Map(children.map(node => [node.id(), { ...node.position() }])));
+     const visible = children.filter(node => !node.hasClass('hidden'));
+     const points = visible.length ? visible : children;
+     clusterPositions.set(id, { x: points.reduce((sum, node) => sum + node.position('x'), 0) / Math.max(points.length, 1), y: points.reduce((sum, node) => sum + node.position('y'), 0) / Math.max(points.length, 1) });
+     collapsed.add(id);
+     refreshVisibility();
+   }
+   scheduleRadar(); updateStatus(); toast((collapsed.has(id) ? 'Collapsed ' : 'Expanded ') + clustersById.get(id).label);
+ }
+ cy.on('dbltap', 'node.cluster, node.meta', event => {
+   const target = event.target;
+   toggleCluster(target.hasClass('meta') ? target.data('clusterId') : target.id());
+ });
+ cy.on('tap', 'node.file', event => {
+   showNode(event.target.id(), false); $('search-results').classList.remove('open');
+ });
+ cy.on('tap', event => { if (event.target === cy) { reset(); $('search-results').classList.remove('open'); } });
+ function updateStatus() { $('status').textContent = cy.nodes('.file').filter(node => !node.hasClass('hidden')).length + ' files visible · ' + collapsed.size + ' collapsed'; $('zoom').textContent = Math.round(cy.zoom() * 100) + '%'; }
+ function scheduleRadar() { if (framePending) return; framePending = true; requestAnimationFrame(() => { framePending = false; drawRadar(); }); }
+ function drawRadar() {
+   const canvas = $('minimap'), rect = canvas.getBoundingClientRect(), dpr = window.devicePixelRatio || 1;
+   canvas.width = Math.round(rect.width * dpr); canvas.height = Math.round(rect.height * dpr);
+   const context = canvas.getContext('2d'); context.scale(dpr, dpr); context.clearRect(0, 0, rect.width, rect.height);
+   const visible = cy.nodes().filter(node => !node.hasClass('cluster') && !node.hasClass('hidden'));
+   if (!visible.length) return;
+   const bounds = visible.boundingBox({ includeLabels: false, includeOverlays: false }), padding = 16;
+   const scale = Math.min((rect.width - padding * 2) / Math.max(bounds.w, 1), (rect.height - padding * 2 - 10) / Math.max(bounds.h, 1));
+   const offsetX = (rect.width - bounds.w * scale) / 2 - bounds.x1 * scale, offsetY = (rect.height - bounds.h * scale) / 2 - bounds.y1 * scale + 6;
+   radarTransform = { scale, offsetX, offsetY };
+   const point = node => ({ x: node.position('x') * scale + offsetX, y: node.position('y') * scale + offsetY });
+   context.strokeStyle = css('--muted'); context.globalAlpha = .18; context.lineWidth = .6;
+   cy.edges().filter(edge => !edge.hasClass('hidden')).forEach(edge => { const a = point(edge.source()), b = point(edge.target()); context.beginPath(); context.moveTo(a.x, a.y); context.lineTo(b.x, b.y); context.stroke(); });
+   visible.forEach(node => { const p = point(node); context.globalAlpha = node.hasClass('dim') || node.hasClass('search-dim') ? .2 : .9; context.fillStyle = node.hasClass('focus') ? css('--text') : node.data('color') || css('--accent'); context.beginPath(); context.arc(p.x, p.y, node.hasClass('focus') ? 2.7 : 1.8, 0, Math.PI * 2); context.fill(); });
+   const extent = cy.extent(); context.globalAlpha = .8; context.strokeStyle = css('--accent'); context.lineWidth = 1;
+   context.strokeRect(extent.x1 * scale + offsetX, extent.y1 * scale + offsetY, extent.w * scale, extent.h * scale); context.globalAlpha = 1;
+ }
+ $('minimap').addEventListener('click', event => { if (!radarTransform) return; const rect = $('minimap').getBoundingClientRect(), t = radarTransform; const x = (event.clientX - rect.left - t.offsetX) / t.scale, y = (event.clientY - rect.top - t.offsetY) / t.scale; cy.pan({ x: cy.width() / 2 - x * cy.zoom(), y: cy.height() / 2 - y * cy.zoom() }); });
+ cy.on('pan zoom position layoutstop', () => { scheduleRadar(); updateStatus(); });
+ let userAdjusted = false;
+ $('cy').addEventListener('wheel', () => { userAdjusted = true; }, { passive: true });
+ $('cy').addEventListener('pointerdown', () => { userAdjusted = true; });
+ new ResizeObserver(() => { cy.resize(); if (!userAdjusted && cy.nodes().length) cy.fit(undefined, 40); scheduleRadar(); }).observe($('cy'));
+ $('show-utils').addEventListener('change', () => { refreshVisibility(); runLayout(); });
+ $('search').addEventListener('input', applySearch);
+ $('search').addEventListener('focus', applySearch);
+ $('search').addEventListener('keydown', event => { if (event.key === 'Enter') { const first = $('search-results').querySelector('button'); if (first) first.click(); } });
+ $('relayout').addEventListener('click', runLayout);
+ function fit() { cy.fit(undefined, 40); scheduleRadar(); }
+ $('fit').addEventListener('click', fit);
+ $('theme').addEventListener('change', () => { document.documentElement.dataset.theme = $('theme').value; cy.style(styleSheet()); scheduleRadar(); });
+ $('help-button').addEventListener('click', () => $('help').showModal());
+ $('help-close').addEventListener('click', () => $('help').close());
+ document.addEventListener('keydown', event => {
+   const typing = /INPUT|TEXTAREA|SELECT/.test(document.activeElement.tagName);
+   if (event.key === '/' && !typing) { event.preventDefault(); $('search').focus(); }
+   if (event.key.toLowerCase() === 'f' && !typing) fit();
+   if (event.key === 'Escape') { $('search').value = ''; applySearch(); $('search').blur(); reset(); }
+ });
+ if (!graph.nodes.length) { $('loading').style.display = 'none'; toast('No source files found. Check the scan path, ignore rules, and maximum depth.'); }
+ refreshVisibility(); if (graph.nodes.length) runLayout();
+})();
+</script>
+</body>
+</html>`;
+}

package/dist/src/renderer/svgExport.d.ts

@@ -0,0 +1,3 @@
+import type { ArchitectureGraph } from '../types.js';
+export declare function renderToMermaid(graph: ArchitectureGraph): string;
+export declare function renderToSvg(graph: ArchitectureGraph): string;

package/dist/src/renderer/svgExport.js

@@ -0,0 +1,44 @@
+import { LAYER_COLORS } from '../core/cluster.js';
+const xml = (text) => text.replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&apos;' })[c]);
+export function renderToMermaid(graph) {
+    const ids = new Map(graph.nodes.map((node, i) => [node.id, 'n' + i]));
+    const clusters = new Map(graph.clusters.map((cluster, i) => [cluster.id, 'c' + i]));
+    const lines = ['graph LR'];
+    function group(id, depth) {
+        const cluster = graph.clusters.find(item => item.id === id);
+        const indent = '  '.repeat(depth);
+        lines.push(indent + 'subgraph ' + clusters.get(id) + '["' + xml(cluster.label) + '"]');
+        for (const child of graph.clusters.filter(item => item.parent === id))
+            group(child.id, depth + 1);
+        for (const node of graph.nodes.filter(item => item.cluster === id))
+            lines.push(indent + '  ' + ids.get(node.id) + '["' + xml(node.id) + '"]');
+        lines.push(indent + 'end');
+    }
+    for (const cluster of graph.clusters.filter(item => !item.parent))
+        group(cluster.id, 1);
+    for (const edge of graph.edges)
+        lines.push('  ' + ids.get(edge.source) + (edge.type === 'dynamic' ? ' -.-> ' : edge.type === 'inheritance' ? ' ==>|extends| ' : ' --> ') + ids.get(edge.target));
+    return lines.join('\n') + '\n';
+}
+export function renderToSvg(graph) {
+    const layers = ['entry', 'business', 'unknown', 'data', 'util'];
+    const positions = new Map();
+    let maxRows = 1;
+    for (let col = 0; col < layers.length; col++) {
+        const nodes = graph.nodes.filter(node => node.layer === layers[col]);
+        maxRows = Math.max(maxRows, nodes.length);
+        nodes.forEach((node, row) => positions.set(node.id, { x: 30 + col * 270, y: 90 + row * 70 }));
+    }
+    const width = 1390, height = maxRows * 70 + 110;
+    const elements = ['<svg xmlns="http://www.w3.org/2000/svg" width="' + width + '" height="' + height + '" viewBox="0 0 ' + width + ' ' + height + '" role="img" aria-label="Repository architecture map">', '<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto"><path d="M0 0L8 4L0 8" fill="#64748b"/></marker></defs>', '<rect width="100%" height="100%" fill="#0f172a"/>'];
+    layers.forEach((layer, i) => elements.push('<text x="' + (30 + i * 270) + '" y="35" fill="' + LAYER_COLORS[layer] + '" font-family="sans-serif" font-size="18">' + layer.toUpperCase() + '</text>'));
+    for (const edge of graph.edges) {
+        const a = positions.get(edge.source), b = positions.get(edge.target);
+        elements.push('<path d="M' + (a.x + 110) + ' ' + a.y + 'L' + (b.x + 110) + ' ' + b.y + '" stroke="#64748b" stroke-opacity=".5" fill="none" marker-end="url(#arrow)"/>');
+    }
+    for (const node of graph.nodes) {
+        const p = positions.get(node.id);
+        elements.push('<g><title>' + xml(node.id) + '</title><rect x="' + p.x + '" y="' + (p.y - 20) + '" width="225" height="40" rx="8" fill="#172033" stroke="' + LAYER_COLORS[node.layer] + '"/><text x="' + (p.x + 10) + '" y="' + (p.y + 5) + '" fill="#e2e8f0" font-family="monospace" font-size="12">' + xml(node.label.length > 28 ? node.label.slice(0, 25) + '…' : node.label) + '</text></g>');
+    }
+    return elements.join('\n') + '\n</svg>\n';
+}

package/dist/src/scanner/extractor.d.ts

@@ -0,0 +1,5 @@
+import type { CodeEdge } from '../types.js';
+export declare function extractImports(root: string, files: string[]): Promise<{
+    edges: CodeEdge[];
+    loc: Map<string, number>;
+}>;

package/dist/src/scanner/extractor.js

@@ -0,0 +1,127 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import { normalize } from './walker.js';
+const traverse = typeof traverseModule === 'function' ? traverseModule : traverseModule.default;
+const extensions = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+export async function extractImports(root, files) {
+    const known = new Set(files), edges = new Map(), loc = new Map();
+    let goModule = '';
+    try {
+        goModule = (await readFile(path.join(root, 'go.mod'), 'utf8')).match(/^\s*module\s+([^\s]+)/m)?.[1] ?? '';
+    }
+    catch { /* No Go module. */ }
+    function first(candidates) { return candidates.map(x => normalize(path.posix.normalize(normalize(x))).replace(/^\.\//, '')).find(x => known.has(x)); }
+    function jsResolve(file, spec) {
+        if (!spec.startsWith('.') && !spec.startsWith('@/'))
+            return;
+        const base = spec.startsWith('@/') ? 'src/' + spec.slice(2) : path.posix.join(path.posix.dirname(file), spec);
+        const remaps = /\.[cm]?js$/.test(base) ? [base.replace(/\.js$/, '.ts').replace(/\.mjs$/, '.mts').replace(/\.cjs$/, '.cts'), base.replace(/\.js$/, '.tsx')] : [];
+        return first([base, ...remaps, ...extensions.map(ext => base + ext), ...extensions.map(ext => base + '/index' + ext)]);
+    }
+    function add(source, target, type = 'import') {
+        if (!target || source === target)
+            return;
+        const key = source + '\0' + target + '\0' + type;
+        const prior = edges.get(key);
+        if (prior)
+            prior.weight += 1;
+        else
+            edges.set(key, { source, target, type, weight: 1 });
+    }
+    for (const file of files) {
+        const text = await readFile(path.join(root, file), 'utf8');
+        loc.set(file, text ? text.split(/\r?\n/).filter(line => line.trim()).length : 0);
+        if (/\.[cm]?[jt]sx?$/.test(file)) {
+            const bindings = new Map();
+            try {
+                const ast = parse(text, { sourceType: 'unambiguous', plugins: ['typescript', 'jsx', 'decorators-legacy'], allowReturnOutsideFunction: true });
+                traverse(ast, {
+                    ImportDeclaration(p) {
+                        const spec = p.node.source.value;
+                        add(file, jsResolve(file, spec));
+                        for (const binding of p.node.specifiers)
+                            bindings.set(binding.local.name, spec);
+                    },
+                    ExportNamedDeclaration(p) { if (p.node.source)
+                        add(file, jsResolve(file, p.node.source.value)); },
+                    ExportAllDeclaration(p) { add(file, jsResolve(file, p.node.source.value)); },
+                    CallExpression(p) {
+                        const callee = p.node.callee, arg = p.node.arguments[0];
+                        if (arg?.type === 'StringLiteral' && ((callee.type === 'Identifier' && callee.name === 'require') || callee.type === 'Import'))
+                            add(file, jsResolve(file, arg.value), callee.type === 'Import' ? 'dynamic' : 'import');
+                    }
+                });
+                traverse(ast, { ClassDeclaration(p) {
+                        const base = p.node.superClass;
+                        const name = base?.type === 'Identifier' ? base.name : base?.type === 'MemberExpression' && base.object.type === 'Identifier' ? base.object.name : undefined;
+                        if (name && bindings.has(name))
+                            add(file, jsResolve(file, bindings.get(name)), 'inheritance');
+                    } });
+            }
+            catch {
+                for (const match of text.matchAll(/(?:\b(?:import|export)\s+(?:[^;'"\n]*?\s+from\s*)?|\brequire\s*\(\s*|\bimport\s*\(\s*)['"]([^'"]+)['"]/g))
+                    add(file, jsResolve(file, match[1]), /import\s*\(/.test(match[0]) ? 'dynamic' : 'import');
+            }
+        }
+        else if (file.endsWith('.py')) {
+            const resolvePy = (module) => {
+                const dots = module.match(/^\.+/)?.[0].length ?? 0;
+                const suffix = module.slice(dots).replace(/\./g, '/');
+                let base = path.posix.dirname(file);
+                for (let n = 1; n < dots; n++)
+                    base = path.posix.dirname(base);
+                const candidates = dots ? [path.posix.join(base, suffix)] : [path.posix.join(path.posix.dirname(file), suffix), suffix];
+                return first(candidates.flatMap(x => [x + '.py', x + '/__init__.py']));
+            };
+            for (const match of text.matchAll(/^\s*import\s+([^\n#]+)/gm)) {
+                for (const part of match[1].split(','))
+                    add(file, resolvePy(part.trim().split(/\s+as\s+/)[0]));
+            }
+            for (const match of text.matchAll(/^\s*from\s+([.\w]+)\s+import\s+([^\n#]+)/gm)) {
+                const parent = resolvePy(match[1]);
+                if (parent)
+                    add(file, parent);
+                for (const part of match[2].replace(/[()]/g, '').split(',')) {
+                    const name = part.trim().split(/\s+/)[0];
+                    if (name && name !== '*')
+                        add(file, resolvePy(match[1] + (match[1].endsWith('.') ? '' : '.') + name));
+                }
+            }
+        }
+        else if (file.endsWith('.go') && goModule) {
+            const imports = [];
+            for (const match of text.matchAll(/\bimport\s*\(([\s\S]*?)\)|\bimport\s+(?:[\w.]+\s+)?"([^"\n]+)"/g)) {
+                if (match[2])
+                    imports.push(match[2]);
+                else
+                    for (const quoted of match[1].matchAll(/"([^"\n]+)"/g))
+                        imports.push(quoted[1]);
+            }
+            for (const spec of imports)
+                if (spec === goModule || spec.startsWith(goModule + '/')) {
+                    const dir = spec.slice(goModule.length).replace(/^\//, '') || '.';
+                    for (const target of files)
+                        if (target.endsWith('.go') && path.posix.dirname(target) === dir)
+                            add(file, target);
+                }
+        }
+        else if (file.endsWith('.rs')) {
+            for (const match of text.matchAll(/\bmod\s+(\w+)\s*;/g)) {
+                const dir = path.posix.dirname(file);
+                const base = /(?:^|\/)(?:lib|main|mod)\.rs$/.test(file) ? dir : file.slice(0, -3);
+                add(file, first([base + '/' + match[1] + '.rs', base + '/' + match[1] + '/mod.rs']));
+            }
+            for (const match of text.matchAll(/\buse\s+crate::([\w:]+)/g)) {
+                const parts = match[1].split('::').filter(Boolean), candidates = [];
+                for (let n = parts.length; n > 0; n--) {
+                    const base = 'src/' + parts.slice(0, n).join('/');
+                    candidates.push(base + '.rs', base + '/mod.rs');
+                }
+                add(file, first(candidates));
+            }
+        }
+    }
+    return { edges: [...edges.values()], loc };
+}

package/dist/src/scanner/heuristics.d.ts

@@ -0,0 +1,6 @@
+import type { CodeNode } from '../types.js';
+export declare const nameTokens: (id: string) => string;
+export declare const isUtilityName: (id: string) => boolean;
+export declare const isUtility: (node: CodeNode, threshold?: number) => boolean;
+export declare const isTestFile: (id: string) => boolean;
+export declare const isEntryLike: (id: string) => boolean;

package/dist/src/scanner/heuristics.js

@@ -0,0 +1,5 @@
+export const nameTokens = (id) => id.replace(/([a-z0-9])([A-Z])/g, '$1/$2');
+export const isUtilityName = (id) => /(?:^|[/_.-])(?:utils?|helpers?|common|shared|lib|constants|types|config)(?:[/_.-]|$)/i.test(nameTokens(id));
+export const isUtility = (node, threshold = 12) => (node.inDegree > threshold && node.outDegree <= 2) || isUtilityName(node.id);
+export const isTestFile = (id) => /(?:^|\/)(?:__tests__|tests?|specs?)(?:\/|\.|$)|(?:[._-](?:test|spec))\.[^/]+$|(?:^|\/)test_[^/]+\.py$/i.test(id);
+export const isEntryLike = (id) => /(?:^|[/_.-])(?:controllers?|routes?|routers?|handlers?|api|endpoints?|cli|app|server|main)(?:[/_.-]|$)/i.test(nameTokens(id)) || /^index\.[^/]+$/.test(id) || /(?:^|\/)(?:__main__|manage)\.py$/.test(id);

package/dist/src/scanner/walker.d.ts

@@ -0,0 +1,2 @@
+export declare const normalize: (value: string) => string;
+export declare function walkRepository(root: string, maxDepth?: number): Promise<string[]>;

package/dist/src/scanner/walker.js

@@ -0,0 +1,49 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import ignore from 'ignore';
+export const normalize = (value) => value.replace(/\\/g, '/');
+const skipped = new Set('node_modules .git dist build out coverage __pycache__ .venv venv .next .nuxt target vendor .idea .vscode .cache'.split(' '));
+const source = /\.(?:js|jsx|mjs|cjs|ts|tsx|mts|cts|py|go|rs)$/i;
+export async function walkRepository(root, maxDepth = 6) {
+    const files = [];
+    async function visit(dir, depth, inherited) {
+        let rules = inherited;
+        try {
+            rules = [...rules, { base: dir, matcher: ignore().add(await readFile(path.join(dir, '.gitignore'), 'utf8')) }];
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const entries = await readdir(dir, { withFileTypes: true });
+        entries.sort((a, b) => a.name.localeCompare(b.name));
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const absolute = path.join(dir, entry.name);
+            if (entry.isDirectory() && skipped.has(entry.name))
+                continue;
+            let ignored = false;
+            for (const rule of rules) {
+                const relative = normalize(path.relative(rule.base, absolute)) + (entry.isDirectory() ? '/' : '');
+                const result = rule.matcher.test(relative);
+                if (result.ignored)
+                    ignored = true;
+                else if (result.unignored)
+                    ignored = false;
+            }
+            if (ignored)
+                continue;
+            if (entry.isDirectory()) {
+                if (depth < maxDepth)
+                    await visit(absolute, depth + 1, rules);
+            }
+            else if (entry.isFile() && source.test(entry.name) && !/\.min\.js$/i.test(entry.name)) {
+                if ((await stat(absolute)).size <= 1.5 * 1024 * 1024)
+                    files.push(normalize(path.relative(root, absolute)));
+            }
+        }
+    }
+    await visit(root, 0, []);
+    return files;
+}

package/dist/src/types.d.ts

@@ -0,0 +1,36 @@
+export interface CodeNode {
+    id: string;
+    label: string;
+    layer: 'entry' | 'business' | 'data' | 'util' | 'unknown';
+    cluster: string;
+    inDegree: number;
+    outDegree: number;
+    linesOfCode: number;
+    isFolded?: boolean;
+    language?: string;
+}
+export interface CodeEdge {
+    source: string;
+    target: string;
+    type: 'import' | 'dynamic' | 'inheritance';
+    weight: number;
+}
+export interface ArchitectureGraph {
+    rootPath: string;
+    generatedAt: string;
+    nodes: CodeNode[];
+    edges: CodeEdge[];
+    clusters: Array<{
+        id: string;
+        label: string;
+        parent?: string;
+    }>;
+    metrics: {
+        totalFiles: number;
+        totalEdges: number;
+        density: number;
+        couplingFactor: number;
+        deadCodeCount: number;
+        foldedUtilityCount: number;
+    };
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "repograph-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "mcpName": "io.github.Karry1123/repograph",
+  "description": "Instant, interactive architecture maps for any codebase. Zero-config CLI + MCP server for Claude Code & Claude Desktop.",
+  "type": "module",
+  "bin": {
+    "repograph": "dist/bin/cli.js",
+    "repograph-cli": "dist/bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check:server-json": "node scripts/check-server-json.mjs",
+    "dev": "tsx bin/cli.ts",
+    "start": "node dist/src/index.js",
+    "mcp": "node dist/src/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "author": "Karry",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^13.0.0",
+    "ignore": "^7.0.0",
+    "@babel/parser": "^7.26.0",
+    "@babel/traverse": "^7.26.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
+    "@types/babel__traverse": "^7.20.0",
+    "tsx": "^4.19.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude",
+    "claude-code",
+    "architecture",
+    "code-visualization",
+    "dependency-graph",
+    "ast",
+    "codebase",
+    "cytoscape"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Karry1123/repograph.git"
+  },
+  "homepage": "https://github.com/Karry1123/repograph#readme",
+  "bugs": {
+    "url": "https://github.com/Karry1123/repograph/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}