@ghostlygawd/codeweb 0.9.0

package/scripts/version-sync.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Propagate the canonical version (package.json) and the canonical MCP tool count
+ * (scripts/mcp-server.mjs) out to every place they would otherwise drift:
+ * the plugin manifest and the skill frontmatter. Run after bumping package.json.
+ *
+ *   node scripts/version-sync.mjs        (or: npm run version-sync)
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getVersion, mcpToolCount, applySync } from './release-utils.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const version = getVersion(ROOT);
+const count = mcpToolCount(ROOT);
+const changed = applySync(ROOT, version, count);
+
+process.stdout.write(`version-sync: v${version}, ${count} MCP tools.\n`);
+process.stdout.write(changed.length ? `  updated: ${changed.join(', ')}\n` : '  all targets already in sync.\n');

package/skills/codebase-anatomy/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: codebase-anatomy
+description: Dissect a codebase to atomic nodes (functions, classes, symbols), wire the call/import web, tag each node's domain, and build a cross-domain overlap graph that ranks consolidation/de-duplication opportunities, then render an interactive HTML map. Use to restructure your own codebase into well-defined non-duplicative systems, OR to fully map and review an external repo (git URL / owner-repo) before adopting it. Triggers include "map this codebase", "dependency/relationship graph", "find duplication/overlap", "atomic dissection", "review this repo before I use it", and the /codeweb command.
+version: 0.9.0
+metadata:
+  origin: community
+---
+
+# Codebase Anatomy (codeweb)
+
+Build a "biological web" of a system: every atomic part (function, class, method, exported
+symbol) is a node; calls/imports/inheritance are the edges; each node belongs to a domain; and
+an **overlap graph** shows where separate parts do the same work — the simplification targets.
+
+The goal is not a pretty picture. It is an **evidence-backed restructure plan**: which
+duplicated logic should collapse into one well-defined system, and who should depend on it.
+
+## When to Use
+
+- Restructuring your own codebase and you need to *see* the real dependency web and where it's
+  duplicative before moving code.
+- Onboarding to a large/legacy system at symbol resolution, not just folder-level.
+- Reviewing an **external** repo (a plugin, library, or template you found on GitHub) end-to-end
+  before adopting it — what it does, how it's wired, and whether it's worth committing to.
+- Hunting cross-cutting duplication that file/module tools miss (the same check coded N times in
+  N domains).
+
+## Two Modes
+
+- **internal** — analyze the current project; produce a domain map + overlap graph + restructure
+  recommendations.
+- **external** — `target` is a git URL or `owner/repo`. Clone it **read-only** to a temp dir,
+  map it the same way, and add an **adoption review** (risk, dependencies, architecture verdict,
+  "should you adopt this?").
+
+Auto-detect: a URL or `owner/repo` ⇒ external; a path or `.` ⇒ internal. `--mode` overrides.
+
+## Non-Negotiable Rules
+
+- **Never execute the target.** No build, run, test, install, or entrypoint — for internal or
+  external code. Only read files and invoke read-only static-analysis tools that inspect files
+  already on disk. This is absolute for external repos (their toolchain can run their code).
+- **Evidence over guesswork.** Every node, edge, domain, and overlap must trace to code you read
+  or a tool emitted. When unsure of an edge or an overlap, omit it or mark it `low` — never
+  inflate. A report that cries wolf is worse than no report.
+- **No silent truncation.** If you cap depth, sample, or skip files, say so in the report and in
+  `meta`. Coverage gaps must be visible.
+- **One graph, one schema.** Everything conforms to `references/graph-schema.md`. The HTML
+  renderer and all agents depend on it.
+- **Reuse, don't reinvent.** Hand off to `repo-scan` (file/library classification),
+  `codebase-onboarding` (guides), `refactor-cleaner` (acting on the list) rather than redoing
+  their jobs.
+
+## Outputs (under `<target>/.codeweb/`)
+
+1. `graph.json` — the web: `nodes`, `edges`, `domains`, `overlaps`, plus `meta` (roles,
+   staleness stamps, stats).
+2. `report.html` — self-contained interactive map (force graph, domain tree, node details,
+   ranked overlap tab; product-only filter by default). No network/CDN.
+3. `report.md` — the same map as plain markdown (mermaid domain graph + overlaps).
+4. `overlap.md` — the ranked consolidation opportunities in plain markdown.
+5. `optimize.md` — the consolidation advisory (ready / blocked / review tiers).
+6. `fragment.json` — the raw extractor output (pipeline stage 1).
+7. (external mode) an adoption review section appended to `overlap.md` and your final summary.
+
+## References
+
+- `references/graph-schema.md` — the exact JSON shape and merge rules. **Read before dissecting.**
+- `references/engine-detection.md` — the hybrid engine: which analysis tool per language, how to
+  probe for it, and depth/scaling rules.
+- `references/overlap-heuristics.md` — the four overlap kinds and the severity rubric.
+
+## Core Workflow
+
+### 0 — Scope & acquire
+
+- Parse `target`, `--depth`, `--engine`, `--focus`, `--mode`, `--open`.
+- internal: resolve the path (default `.`). external: `git clone --depth 1 <url>` into a temp
+  dir (e.g. `${TMPDIR}/codeweb-<repo>`); **do not** run anything inside it.
+- Detect languages, package managers, and repo size (`rg --files | wc -l`). Choose effective
+  depth: `auto` ⇒ module-level overview, then symbol-level on the densest/most-overlapping
+  subsystems. Probe for analysis tools per `engine-detection.md`; record the engine.
+
+### Fast path (default) — one-command deterministic engine
+
+For languages the bundled extractor handles (**JavaScript, TypeScript, Python, Rust, Go, Java, C#, Ruby, PHP, Kotlin, Swift**), run the whole
+pipeline in a single command instead of dissecting by hand. It is faster, cheaper, and
+reproducible, and emits the same `graph.json` schema:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/run.mjs" "<target>" --target "<label>" --out-dir "<target>/.codeweb"
+```
+
+It chains extract → cluster (directory-anchored domains) → overlap (body-confirmed duplication)
+→ optimize (consolidation advisory) → render, writing `fragment.json`, `graph.json`, `overlap.md`, `optimize.md`, `report.html`, `report.md` into the
+workspace (defaults to `<plugin>/.codeweb/runs/<slug>/` when `--out-dir` is omitted). The script is
+read-only over the target and resolves its own paths, so it works from any cwd. **When it
+succeeds, skip steps 1–5 and go to step 6.** Use the agent-based passes below only as a
+**fallback** — for languages the extractor can't parse, an explicit `--engine read`, or to enrich
+findings the scripts left `low`-confidence.
+
+### 1 — Survey & partition (agent-based fallback; skip if the fast path ran)
+
+- Build the subsystem map: top-level source dirs / packages, excluding vendored and build dirs
+  (lean on `repo-scan`'s classification idea — project vs third-party vs artifact).
+- Partition the project code into ~4–12 scopes of comparable size. These are the parallel units.
+
+### 2 — Dissect (parallel `codeweb-dissector`)
+
+- Spawn one `codeweb-dissector` per scope **in parallel** (single message, multiple agents).
+  Pass each: its scope, the engine mode, the detected tools, and the node/edge schema.
+- Each returns `{nodes, edges}` for its slice. They may reference ids outside their scope.
+- If subagents aren't available, run the passes sequentially with the same instructions.
+
+### 3 — Merge
+
+- Union all nodes (dedupe by `id`) and edges (unique by `from,to,kind`; sum `weight`).
+- Drop edges whose endpoints aren't in the node set (dangling refs to skipped code).
+
+### 4 — Domain-map & overlap (`codeweb-domain-mapper`)
+
+- Pass the merged `{nodes, edges}` to one `codeweb-domain-mapper` with `overlap-heuristics.md`.
+- It returns per-node `domain`, a `domains[]` summary, and ranked `overlaps[]`. Merge `domain`
+  back onto each node by `id`; attach `domains` and `overlaps` to the graph.
+
+### 5 — Stamp & render
+
+- Write `.codeweb/graph.json`.
+- Run the renderer:
+  ```bash
+  node "${CLAUDE_PLUGIN_ROOT}/scripts/build-report.mjs" "<target>/.codeweb/graph.json"
+  ```
+  (add `--open` to launch it). It computes `meta.stats`, stamps `generatedAt`, drops any
+  remaining dangling edges, writes the normalized graph back to `graph.json`, and writes
+  `report.html` + `report.md` beside it.
+
+### 6 — Overlap.md + summary
+
+- Write `overlap.md`: the ranked overlaps as a checklist — title, kind, severity, the symbols
+  involved, evidence, and the named consolidation target. This is the restructure plan.
+- Report to the user: artifact paths, the domain count, and the **top 3–5 consolidation
+  opportunities** with their recommendations.
+
+### 7 — External adoption review (external mode only)
+
+Append an adoption verdict: what the repo is and does (from the domain map), notable
+dependencies and risk surface (lean on `security-review` / `repo-scan` signals), architecture
+quality (cohesion vs the overlap graph), and a clear **adopt / adapt / avoid** recommendation
+with reasons. Then clean up the temp clone.
+
+## Scaling
+
+Follow `engine-detection.md`: module depth for first pass and huge repos; expand to symbol depth
+on the top subsystems by size and cross-domain edge density. If total nodes would exceed ~2000,
+cap symbol expansion to the focus area and state it. The HTML renderer auto-starts in
+domain-aggregated view above ~600 nodes and lets the user expand.
+
+## Handoffs
+
+- `refactor-cleaner` — execute the consolidation list.
+- `codebase-onboarding` — turn the domain map into an onboarding guide.
+- `code-tour` — anchor a guided tour to the symbol index.
+- `repo-scan` — deeper file-level / third-party classification.
+
+## Output Format
+
+```text
+TARGET   — path/url · mode · languages · engine · depth
+WEB      — nodes / edges / domains  (+ coverage caveats)
+DOMAINS  — each domain: name · node count · one-line role
+OVERLAPS — ranked: severity · kind · title · → consolidation target
+ARTIFACTS— .codeweb/graph.json · report.html · overlap.md
+VERDICT  — (external only) adopt / adapt / avoid, with reasons
+```

package/skills/codebase-anatomy/references/engine-detection.md

@@ -0,0 +1,49 @@
+# Hybrid engine — tool detection & fallback
+
+codeweb prefers **precise edges from static-analysis tools** when they are installed, and falls
+back to **agent reading** otherwise. Per subsystem, detect what's available, use it, and record
+the chosen engine in `meta.engine`.
+
+> **Native fast path (no tools required):** JavaScript, TypeScript, Python, Rust, and Go are parsed
+> directly by the bundled regex extractor (`scripts/extract-symbols.mjs`). The table below is the
+> *optional* sharpening / agent-fallback path — for these languages it only refines edges, and for
+> the others it is the primary route.
+
+## Detection order (per language)
+
+| Language | Preferred tool(s) | Detect with | Emits |
+|---|---|---|---|
+| JS/TS | `madge` (imports), `ts-morph`/`tsc --listFiles` | `npx --no-install madge -V`; `tsconfig.json` present | import graph, modules |
+| Python | `pydeps`, `pyan3`, stdlib `ast` via a one-off script | `python -c "import ast"`; `pip show pydeps` | import + call graph |
+| Go | `go list -deps`, `callgraph` (golang.org/x/tools) | `go version` | package + call graph |
+| Rust | `cargo modules`, `cargo-call-stack` | `cargo --version` | module tree, calls |
+| Java/Kotlin | `jdeps` (JDK), tree-sitter | `jdeps -version` | class/package deps |
+| C/C++ | `clangd`/`clang -emit-ast`, `cscope`, `ctags` | `clang --version`; `ctags --version` | symbols, includes |
+| Any | **universal-ctags** (symbols), **tree-sitter** (AST), `ripgrep` (call sites) | `ctags --version`; `tree-sitter --version` | symbol index |
+
+`universal-ctags` + `ripgrep` is the broad fallback spine: ctags gives the symbol list with
+locations; ripgrep finds call sites to draw edges. Both are read-only and cross-language.
+
+## Rules
+
+- **Probe, don't install.** Check for a tool with a version/`--help` call. If it's missing,
+  do **not** `npm install` / `pip install` / `cargo install` it — drop to reading. (Especially
+  for external repos: installing their toolchain can execute their code.)
+- **Tool output is the spine, reading fills the flesh.** Even with a tool, read representative
+  files to populate `summary`, `kind`, `loc`, and to confirm call edges the tool can't resolve
+  (dynamic dispatch, reflection, DI).
+- **Record per-subsystem engine.** A repo can be `tools` for its Go service and `read` for its
+  shell scripts. Set `meta.engine` to the dominant mode, and note mixed coverage in the report.
+- **Never execute the target.** No build, no run, no test, no entrypoint. Only invoke analysis
+  tools that statically inspect files already on disk.
+
+## Scaling / depth
+
+- `module` depth: stop at file/module nodes and import edges — fast, good for first pass and
+  huge repos. Default top-level view.
+- `symbol` depth: expand to function/class/method nodes and call edges — run it on the densest
+  or most-overlapping subsystems rather than the whole repo when node counts get large.
+- `auto`: module-level everywhere, then symbol-level on the top subsystems by size and by
+  cross-domain edge density (where overlap is most likely).
+- If total nodes would exceed ~2000, cap symbol expansion to the focus area and say so in the
+  report — never silently truncate.

package/skills/codebase-anatomy/references/graph-schema.md

@@ -0,0 +1,120 @@
+# codeweb graph schema (`graph.json`)
+
+The single source of truth that flows between dissectors, the domain-mapper, and the HTML
+renderer. All examples below use synthetic values.
+
+```json
+{
+  "meta": {
+    "target": "src/ or https://github.com/owner/repo",
+    "mode": "internal | external",
+    "engine": "hybrid | tools | read",
+    "complexityEngine": "tree-sitter(...)",  // present ONLY under --engine tree-sitter; signals exact
+                                             // complexity + class-qualified method ids + dispatch edges
+    "depth": "module | symbol | auto",
+    "languages": ["typescript", "python"],
+    "generatedAt": "ISO-8601 string, stamped by the renderer (not by agents)",
+    "stats": { "files": 0, "nodes": 0, "edges": 0, "domains": 0, "overlaps": 0 }
+  },
+
+  "nodes": [
+    {
+      "id": "src/auth/login.ts:loginUser",   // <repo-relative-path>:<symbol>  (path alone for file/module nodes).
+                                             // Under --engine tree-sitter a METHOD's <symbol> is class-qualified
+                                             // (`Class.method`) so same-named methods don't collide; bare otherwise.
+      "label": "loginUser",                  // display name — a method label stays BARE (`method`, never `Class.method`)
+      "kind": "function",                     // function | class | method | module | file
+      "file": "src/auth/login.ts",
+      "line": 42,
+      "loc": 120,                              // size of the symbol body, for node radius
+      "exports": true,
+      "domain": "auth",                        // assigned by domain-mapper (empty from dissectors)
+      "summary": "Authenticates a user and issues a session token.",
+      "complexity": 7,                         // F4: approximate cyclomatic complexity (function|method only; absent on class/module)
+      "maxDepth": 3                            // F4: max control-flow nesting depth (function|method only)
+    }
+  ],
+
+  "edges": [
+    {
+      "from": "src/auth/login.ts:loginUser",
+      "to": "src/db/query.ts:runQuery",
+      "kind": "call",                          // call | import | inherit | ref | test (emitted) · dataflow (reserved)
+      "weight": 1                              // number of occurrences; optional, default 1
+    }
+  ],
+
+  "domains": [
+    {
+      "name": "auth",
+      "nodes": 12,
+      "summary": "Authentication, session issuance, and authorization checks.",
+      "files": ["src/auth/"]                   // optional, representative paths
+    }
+  ],
+
+  "overlaps": [
+    {
+      "id": "ov1",
+      "title": "User validation duplicated across auth, billing, and api",
+      "kind": "duplicate-logic",               // duplicate-logic | parallel-impl | shared-responsibility | tangled-domain
+      "severity": "high",                      // high | medium | low
+      "domains": ["auth", "billing", "api"],
+      "nodes": [
+        "src/auth/login.ts:validateUser",
+        "src/billing/charge.ts:checkUser",
+        "src/api/guard.ts:assertUser"
+      ],
+      "evidence": "All three re-implement the same email + password + active-role check.",
+      "recommendation": "Extract a single auth.validateUser; have billing and api depend on it."
+    }
+  ]
+}
+```
+
+## Edge kinds
+
+- **`call`** — a function/method invokes another, OR passes it by name as a higher-order argument
+  (`arr.map(fn)`, `rl.on('x', fn)`). The deterministic extractor resolves the target by import alias,
+  same-file definition, or a unique global definition, and DROPS ambiguous multi-definition names
+  rather than guess (precision over recall). A method call `obj.fn()` is NOT wired to a top-level `fn`
+  by the regex engine. Under `--engine tree-sitter`, dynamic-dispatch calls DO resolve: `this.m()`
+  (within a class) and typed-receiver `x.m()` (where `x: T` is a known class) wire to the
+  class-qualified method id (`<path>:T.m`); untyped/array/generic receivers are still dropped.
+- **`import`** — a module imports a symbol from another module.
+- **`inherit`** — a class extends/subclasses another (`class X extends Y`, `class X(Y):`), resolved
+  with the same precision gate as calls. Counts toward reachability: an extended base is not a
+  dead-code orphan, and `--impact` of a base includes its subclasses.
+- **`ref`** — a symbol references a CLASS by identity without invoking it directly: `obj instanceof X`
+  or a static-method call `X.from(...)` (where `X` is an imported class or a same-file class). The
+  `.from()` site ALSO emits a `call` edge to the static method; the `ref` edge records the dependency on
+  the class itself so `--dependents <class>` surfaces every user (an `instanceof`/static-factory user is
+  not a `call`-edge caller). Precision-safe: an object-default alias (`import utils from './utils'`)
+  emits no `ref` — `utils` is not a class. Counts toward `--dependents` and reachability (not an orphan).
+- **`test`** — a `call`/`ref` originating in a test file (`*.test.*`, `tests/` …) to a production
+  symbol, reclassified so production caller/orphan queries can exclude test-only usage while
+  `--dependents`/`--tests` still surface it.
+- **`dataflow`** — RESERVED, not emitted by any stage today. Precise value/taint tracking
+  (source→sink) needs type/dispatch resolution and alias awareness the deterministic regex extractor
+  does not have; a noisy approximation would undermine the precision the other edge kinds guarantee
+  (codeweb's whole contract is "don't guess"). Reserved for a future optional type-resolution tier —
+  the schema lists it so consumers can forward-handle it, but no code produces it. Use an external
+  analyzer (Semgrep/CodeQL) for taint until then.
+
+## Merge rules (orchestrator)
+
+- Dissectors emit `nodes` + `edges` per scope. Deduplicate by node `id`; an edge is unique by
+  `(from, to, kind)` — sum `weight` on collision.
+- Edges may reference node ids owned by another scope. After merging all dissectors, drop any
+  edge whose `from` or `to` id does not exist as a node (dangling reference to skipped code).
+- The domain-mapper returns `{nodes:[{id,domain}], domains, overlaps}`. Merge each `domain`
+  back onto the matching full node by `id`.
+- The renderer (`build-report.mjs`) computes `meta.stats`, stamps `meta.generatedAt`, and persists
+  both back into `graph.json` (along with the dangling-edge drop), so the on-disk graph matches the
+  rendered report.
+
+## Minimum viable graph
+
+A graph is renderable with just `nodes` and `edges`. `domains` and `overlaps` enrich the
+report; if absent, the renderer treats every node as domain `"unassigned"` and shows an empty
+overlap tab.

package/skills/codebase-anatomy/references/overlap-heuristics.md

@@ -0,0 +1,52 @@
+# Overlap detection heuristics
+
+The overlap graph is the payoff of codeweb: it shows where the system does the **same work in
+more than one place**, so it can be restructured into well-defined, non-duplicative systems.
+
+## The four overlap kinds
+
+| Kind | Signal | Example |
+|---|---|---|
+| `duplicate-logic` | The same algorithm/validation/transform appears in 2+ symbols with near-identical bodies or behaviour. | Three modules each parse the same date format by hand. |
+| `parallel-impl` | Two or more competing implementations of one capability, often with diverging behaviour. | A `fetch` wrapper and an `axios` wrapper both used for API calls. |
+| `shared-responsibility` | One concern is smeared across many domains with no single owner. | Retry/backoff logic copy-pasted into every network call site. |
+| `tangled-domain` | A single symbol mixes responsibilities from multiple domains and should be split. | `saveOrder()` that also sends email, writes audit logs, and charges a card. |
+
+## How to find them
+
+1. **Name + signature clustering.** Group symbols whose names/params suggest the same job
+   (`validateUser`, `checkUser`, `assertUser`). Read the bodies to confirm they overlap.
+2. **Edge-pattern clustering.** Symbols in different domains that call the same downstream set,
+   or that are called from the same set of callers, are candidates for consolidation.
+3. **Structural similarity.** Similar control flow / similar literal sets (regexes, status
+   codes, field names) across symbols signals copy-paste drift.
+4. **Cross-domain fan-in.** A utility imported by many domains may be fine (good reuse) — but a
+   *behaviour* re-implemented in many domains is overlap. Distinguish "one shared function used
+   widely" (healthy) from "the same idea coded N times" (overlap).
+
+## Severity rubric
+
+Score each overlap on three axes, then take the max-weighted band:
+
+- **Duplication count** — 2 places = low, 3–4 = medium, 5+ = high.
+- **Blast radius** — how many domains / how much traffic flows through the duplicated path.
+  Touches 1 domain = low, 2 = medium, 3+ or a core path = high.
+- **Divergence risk** — have the copies already drifted (different edge cases, different bug
+  fixes)? Drift present = bump one band; security/correctness-sensitive logic = high.
+
+`high` = block-worthy simplification target. `medium` = worth a refactor ticket. `low` = note.
+
+## Writing the recommendation
+
+Always name the **single well-defined system** the pieces should collapse into, and who should
+depend on it. Good: *"Extract `auth.validateUser` as the one validator; billing and api import
+it; delete the local copies."* Bad: *"Reduce duplication."* The recommendation is the bridge
+from diagnosis to a concrete restructure.
+
+## What is NOT overlap
+
+- Genuinely independent logic that merely looks similar (different domains, different invariants).
+- Intentional layering (an interface + one implementation).
+- Test doubles / fixtures mirroring production shapes.
+Flagging these erodes trust in the report — when unsure, mark `low` with explicit evidence
+rather than inflating severity.