assistgraph 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Williamson
+
+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

@@ -0,0 +1,321 @@
+# assistgraph
+
+> File-level dependency knowledge graph for JavaScript, TypeScript, and Python codebases. Produces a JSON graph, an Obsidian vault, and an MCP server so agents like Claude and Codex can query your repo without grepping.
+
+## What it does
+
+Run `assistgraph build` in any repo (or subfolder) and you get:
+
+- **`assistgraph/graph.json`** — a machine-readable dependency graph of every file and every import
+- **`assistgraph/vault/`** — an Obsidian-compatible knowledge vault with wiki links, pre-configured colour groups, and community pages
+- **`assistgraph/audit.md`** (via `assistgraph audit`) — cycles, orphans, hubs, and cross-folder coupling
+- **An MCP stdio server** (via `assistgraph mcp`) — 11 tools so Claude Code / Codex can query the graph directly
+
+All parsing is deterministic and offline. Zero LLM calls, zero databases, zero Python runtime required.
+
+## Why
+
+Large codebases burn agent tokens fast. "Who imports `UserService`?" normally means opening dozens of files and grepping each. With assistgraph, that same question is a single MCP call returning a few hundred tokens — O(1) graph lookup instead of O(N) file reads.
+
+The same structural view also powers migrations: feature boundaries, blast-radius of a change, dead code, cycles, and cross-folder coupling are all one call away.
+
+## Features
+
+- **Languages:** TypeScript, TSX, JavaScript, JSX, MJS, CJS, Python
+- **Strict `.gitignore` enforcement:** anything in `.gitignore` is invisible to assistgraph, including wildcard patterns
+- **CWD is the scan root:** run it anywhere — at the repo root for the full picture, or in a subfolder for a focused graph
+- **Works in monorepos:** respects the topmost `tsconfig.json` above the scan root, stopping at parent project boundaries
+- **Folder-based communities:** folders become feature communities automatically, mirroring your codebase structure
+- **Cycle detection:** iterative Tarjan SCC — doesn't blow the JS stack on deep dependency chains
+- **Hub/bloat metrics:** top imported files, top bloat candidates
+- **Cross-folder coupling:** shows you exactly how tangled up `ui/` and `app/` really are
+- **Orphan detection with entrypoint heuristics:** dead code is separated from legitimate entrypoints (`index.ts`, `main.py`, `manage.py`, etc.)
+- **Content hashing:** every node has a stable hash for future incremental builds
+- **Obsidian colour groups:** each top-level folder gets its own colour automatically so your graph view pops from the first click
+
+## Requirements
+
+- **Node 18+** or **Bun 1.0+**
+- No Python runtime required even for Python projects — parsing is pure JavaScript
+
+## Install
+
+The fastest way to run assistgraph is via `npx` — no install needed:
+
+```bash
+cd your-project
+npx -y assistgraph build
+```
+
+Or install a persistent global binary:
+
+```bash
+# Node / npm
+npm install -g assistgraph
+
+# Bun
+bun install -g assistgraph
+```
+
+`oxc-parser` ships platform-specific native bindings that npm picks automatically on install. Once installed globally, drop the `npx -y` prefix from every command below.
+
+## Quick start
+
+```bash
+# Build the graph + Obsidian vault in any repo
+cd your-project
+npx -y assistgraph build
+
+# Peek at the stats
+npx -y assistgraph stats
+
+# Show what a file imports and who imports it
+npx -y assistgraph query src/features/auth/Login.tsx
+
+# Full audit: cycles, orphans, hubs, coupling → also writes assistgraph/audit.md
+npx -y assistgraph audit
+
+# Install Claude + Codex skills so agents know to prefer the graph
+npx -y assistgraph install-skills
+
+# Start the MCP server (for Claude Code / Codex)
+npx -y assistgraph mcp
+```
+
+Then point Obsidian at `./assistgraph/vault/` to see the graph visually.
+
+## CLI reference
+
+```
+assistgraph build [--root <dir>] [--no-vault]     Scan CWD → assistgraph/graph.json + vault/
+assistgraph query <path>                          Deps + dependents for a file
+assistgraph stats                                 Graph stats
+assistgraph audit [--out <path>]                  Cycles, orphans, hubs, coupling (+ audit.md)
+assistgraph mcp                                   Start MCP stdio server
+assistgraph install-skills [--force] [--claude-only] [--codex-only]
+                                                  Install Claude + Codex skill files
+assistgraph init                                  Create assistgraph.config.json
+```
+
+## Output layout
+
+```
+<cwd>/
+├── assistgraph.config.json              ← optional, check into git
+└── assistgraph/                         ← generated, add to .gitignore
+    ├── graph.json                       ← canonical graph
+    ├── audit.md                         ← generated by `assistgraph audit`
+    └── vault/                           ← Obsidian-compatible vault
+        ├── .obsidian/graph.json         ← pre-configured colour groups
+        ├── README.md                    ← entry MOC
+        ├── _communities/                ← one MOC per folder community
+        ├── _externals/                  ← one stub per external package
+        └── <mirror of your source tree>/*.md
+```
+
+## Claude Code / Codex integration
+
+### MCP server config
+
+Add one of the following to your Claude Code / Codex / Cursor MCP config. The `npx` / `bunx` variants require **no pre-install** — the package is fetched on first run and cached for subsequent launches.
+
+**Node / npm (recommended):**
+
+```json
+{
+  "mcpServers": {
+    "assistgraph": {
+      "command": "npx",
+      "args": ["-y", "assistgraph", "mcp"]
+    }
+  }
+}
+```
+
+**Bun:**
+
+```json
+{
+  "mcpServers": {
+    "assistgraph": {
+      "command": "bunx",
+      "args": ["assistgraph", "mcp"]
+    }
+  }
+}
+```
+
+**Globally installed binary:**
+
+```json
+{
+  "mcpServers": {
+    "assistgraph": {
+      "command": "assistgraph",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The MCP server reads `./assistgraph/graph.json` from the agent's current working directory and holds it in memory. Re-run `assistgraph build` whenever you want the graph to reflect new or moved files — the server picks up the new file on its next spawn.
+
+### One-time skill install
+
+```bash
+npx -y assistgraph install-skills
+```
+
+Writes:
+- `~/.claude/skills/assistgraph/SKILL.md`
+- `~/.codex/skills/assistgraph/SKILL.md`
+
+The Claude skill tells Claude Code when to prefer `mcp__assistgraph__*` tools over grepping imports.
+
+### Tools exposed by the MCP server
+
+| Tool | Purpose |
+|---|---|
+| `graph_stats` | Node/edge/language counts |
+| `list_files` | Paginated file summaries, optional language filter |
+| `get_file` | Full metadata for one file |
+| `get_dependencies` | Transitive deps with optional depth |
+| `get_dependents` | Transitive dependents with optional depth |
+| `find_path` | Shortest dependency path between two files |
+| `search_files` | Fuzzy file search by basename or path |
+| `list_communities` | All folder communities |
+| `get_community` | Members of a community |
+| `find_cycles` | All dependency cycles (Tarjan SCC) |
+| `find_orphans` | Orphan files, with `isLikelyEntrypoint` flag |
+
+## Obsidian integration
+
+Point Obsidian at `./assistgraph/vault/` and open the graph view. Colour groups are pre-configured so each top-level folder gets its own colour, with language colours as a fallback.
+
+To customise colours manually: **Graph view → Settings (gear) → Groups**. Your changes are preserved on subsequent `assistgraph build` runs — the default config is only written when no custom colour groups exist.
+
+Each file note contains:
+- YAML frontmatter (path, language, community, loc, exports, tags)
+- `## Exports` — named + default exports
+- `## Imports` — wiki-linked to sibling files + external stubs
+- `## Imported By` — reverse index
+- `## Metrics` — LOC, size, import/dependent counts, content hash
+
+## Configuration
+
+Optional `assistgraph.config.json` at the scan root:
+
+```json
+{
+  "include": ["**/*"],
+  "exclude": [
+    "assistgraph/**",
+    "node_modules/**",
+    "dist/**",
+    "build/**",
+    "__pycache__/**",
+    ".venv/**"
+  ],
+  "resolver": {
+    "tsconfig": null,
+    "pythonRoots": ["."]
+  },
+  "output": {
+    "dir": "assistgraph"
+  }
+}
+```
+
+Everything has sensible defaults. You only need this file if the defaults don't fit your project.
+
+## Running in a subfolder
+
+```bash
+cd src/features/auth
+npx -y assistgraph build
+```
+
+The scan root becomes the current folder. Imports that leave the scan root become external leaf nodes (with their absolute path preserved). This lets you build a focused graph for a single feature or component folder.
+
+When scanning a subfolder, assistgraph still walks up to find the nearest `tsconfig.json`, stopping at any parent `package.json` — so `@/...` and `@shared/...` aliases keep resolving correctly.
+
+## Graph schema
+
+```ts
+interface Graph {
+  version: '1.0';
+  generatedAt: string;
+  scanRoot: string;
+  stats: { nodes; edges; orphans; cycles; languages };
+  nodes: Record<string, GraphNode>;
+  edges: GraphEdge[];
+  communities: Record<string, GraphCommunity>;
+  cycles: GraphCycle[];
+}
+
+interface GraphNode {
+  id: string;            // scan-root-relative path
+  name: string;          // basename
+  path: string;
+  absolutePath: string;
+  language: 'ts' | 'tsx' | 'js' | 'jsx' | 'mjs' | 'cjs' | 'py' | 'external';
+  isExternal: boolean;
+  loc: number;
+  sizeBytes: number;
+  exports: string[];
+  imports: ImportRef[];
+  community: string;
+  contentHash: string;
+}
+
+interface ImportRef {
+  raw: string;           // the literal specifier, e.g. "./foo" or "@/lib/bar"
+  resolved: string | null;
+  symbols: string[];     // named bindings pulled in — symbol-aware, migration-ready
+  kind: 'static' | 'dynamic' | 'type' | 'require' | 'reexport' | 'python';
+}
+
+interface GraphEdge {
+  from: string;
+  to: string;
+  kind: ImportRef['kind'];
+}
+
+interface GraphCommunity {
+  id: string;            // folder path, e.g. "src/features/auth"
+  members: string[];
+  parent: string | null;
+}
+
+interface GraphCycle {
+  members: string[];
+  length: number;
+}
+```
+
+## What assistgraph does NOT do
+
+- Function- or class-level resolution — file-level imports only
+- Runtime analysis — static AST parsing only
+- Type inference beyond what's declared in imports
+- HTML or Vue SFC or Astro parsing
+- Call graph construction
+- LLM-based enrichment (roadmap)
+
+## FAQ
+
+**Why are all the files the same colour in Obsidian's graph view?**
+Obsidian starts every vault with no colour groups. `assistgraph build` writes `.obsidian/graph.json` with sensible defaults (one colour per top-level folder). If you already had the vault open, quit Obsidian fully (⌘Q), re-run `assistgraph build`, then reopen — Obsidian caches the settings in memory and overwrites the file on close.
+
+**Why aren't my `ui/` and `app/` folders visually split?**
+Obsidian uses a force-directed layout; folder structure isn't an input. If `ui/` and `app/` are intermingled, they're geometrically intertwined because of edges between them. Run `assistgraph audit` and check the "Cross-folder Coupling" section to see exactly how many edges cross the boundary.
+
+**Does this work in a monorepo?**
+Yes. Run `assistgraph build` at the repo root for a unified view, or in a specific package for a focused view. The resolver stops at parent `package.json` boundaries so a nested package's `tsconfig.json` takes priority over the monorepo root.
+
+**Does this replace `dependency-cruiser` / `madge`?**
+No — those are richer JS-only tools. assistgraph trades depth for breadth: one tool across JS/TS + Python, an Obsidian vault for humans, and an MCP server for agents.
+
+## License
+
+MIT.