assistgraph 0.1.0

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "assistgraph",
+  "version": "0.1.0",
+  "description": "File-level dependency knowledge graph CLI for JS/TS/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.",
+  "type": "module",
+  "bin": {
+    "assistgraph": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "bun run ./src/cli/index.ts",
+    "build": "bun build ./src/cli/index.ts --outfile ./dist/cli.js --target node --format esm --minify --external oxc-parser --banner \"#!/usr/bin/env node\"",
+    "prepublishOnly": "bun run typecheck && bun run build",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test tests/unit",
+    "test:all": "bun run typecheck && bun test tests/unit",
+    "smoke:mcp": "cd tests/fixtures/cycles-app && bun run ../../../src/cli/index.ts build > /dev/null && cd ../../.. && bun run tests/mcp-smoke.ts tests/fixtures/cycles-app",
+    "clean:fixtures": "rm -rf tests/fixtures/*/assistgraph",
+    "prepack:inspect": "bun run build && npm pack --dry-run"
+  },
+  "keywords": [
+    "dependency",
+    "graph",
+    "cli",
+    "obsidian",
+    "knowledge-graph",
+    "mcp",
+    "claude",
+    "codex",
+    "typescript",
+    "python",
+    "bun"
+  ],
+  "author": "Andy Williamson",
+  "license": "MIT",
+  "dependencies": {
+    "oxc-parser": "^0.124.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@types/bun": "latest",
+    "citty": "^0.2.2",
+    "graphology": "^0.26.0",
+    "graphology-types": "^0.24.8",
+    "ignore": "^7.0.5",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}

package/skills/claude/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: assistgraph
+description: Query the dependency graph of the current repo or folder. Use for any question about file dependencies, what imports what, where a symbol is defined, feature boundaries, circular imports, orphan files, HTTP routes, module hierarchies — BEFORE reaching for grep.
+---
+
+# assistgraph
+
+`assistgraph` is a file-level dependency knowledge graph for JS/TS/Python codebases. If the current repo has a graph (`./assistgraph/graph.json`), querying it via the MCP tools is much cheaper than reading source files and grepping imports.
+
+## When to use
+
+Use the `mcp__assistgraph__*` tools whenever the user asks:
+
+- "What does X depend on?" / "Who imports X?"
+- "Where is Y defined?" / "Where is Y used?"
+- "What files are in the auth feature?" / "Show me the feature boundary"
+- "Is there a dependency cycle?"
+- "What are the orphan/dead files?"
+- "How tightly coupled are the ui and app folders?"
+- "What's the architectural backbone of this codebase?" (top hubs)
+- "Show me how X and Y are connected"
+
+## Before using the tools
+
+1. Check that `./assistgraph/graph.json` exists in the user's cwd.
+2. If not, tell the user to run `assistgraph build` at the repo root (or in whatever folder they want scoped).
+3. The MCP server auto-loads `assistgraph/graph.json` from the cwd where it was started.
+
+## Tool cheat sheet
+
+| Tool | Use when |
+|---|---|
+| `graph_stats` | Before doing anything else, to understand the scale of the repo |
+| `list_files` | Enumerate files, optionally filtered by language |
+| `get_file` | Full metadata for a known file path |
+| `get_dependencies` | "What does X import?" — supports transitive depth |
+| `get_dependents` | "Who imports X?" — supports transitive depth |
+| `find_path` | "How does X reach Y?" (shortest dep path) |
+| `search_files` | Find a file by basename or path substring |
+| `list_communities` | Enumerate folder-based feature communities |
+| `get_community` | All files in a community |
+| `find_cycles` | All circular dependencies (Tarjan SCC) |
+| `find_orphans` | Files with no dependents; each is flagged `isLikelyEntrypoint` so you can ignore legitimate entrypoints |
+
+## Policy
+
+- **Prefer the MCP tools over grepping imports manually.** Reading source files for import statements is wasteful when the graph already has the answer.
+- **Only fall back to reading file contents** when you need the actual code (function bodies, comments, implementation details) — the graph has file-level metadata, not source.
+- **Use `get_dependencies` with a `depth` > 1** to trace transitive dependencies (max depth 0 = unlimited).
+- **Use `find_path`** when the user wants to know how two files are connected.
+- **Before making architectural recommendations**, call `list_communities` and `find_cycles` to understand the existing structure.

package/skills/codex/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: assistgraph
+description: Query the dependency graph of the current repo for file-level imports, feature boundaries, cycles, hubs, and orphan files. Prefer this over grep for any import-graph question.
+---
+
+# assistgraph (Codex)
+
+This repo may contain a pre-built dependency graph at `./assistgraph/graph.json`. When it exists, use it before grepping or reading files one by one.
+
+## How to use
+
+If the assistgraph MCP server is connected, prefer calls to `mcp__assistgraph__*` tools for any import-graph question:
+
+- `mcp__assistgraph__graph_stats` — size + language breakdown
+- `mcp__assistgraph__get_file` — full metadata for one file
+- `mcp__assistgraph__get_dependencies` — what does this file import?
+- `mcp__assistgraph__get_dependents` — who imports this file?
+- `mcp__assistgraph__find_path` — shortest dependency path between two files
+- `mcp__assistgraph__search_files` — fuzzy locate a file
+- `mcp__assistgraph__list_communities` / `get_community` — feature boundaries
+- `mcp__assistgraph__find_cycles` — dependency cycles
+- `mcp__assistgraph__find_orphans` — files with no dependents (entrypoints flagged)
+
+If the MCP server is not connected, use the CLI directly:
+
+```bash
+assistgraph build              # refresh the graph
+assistgraph query <file>       # deps + dependents
+assistgraph stats              # summary
+assistgraph audit              # cycles, coupling, hubs, orphans
+```
+
+## Workflow
+
+1. `assistgraph build` at the repo root if `./assistgraph/graph.json` is missing or stale.
+2. Use the MCP tools (or CLI) to answer structural questions.
+3. Fall back to `rg`/`grep` only for code content, not import structure.
+
+## What assistgraph does NOT know
+
+- Function-level calls (file-level imports only)
+- Runtime behaviour
+- Type information beyond what's declared in imports
+
+Use the graph for structure, read source files for semantics.