{
  "markdown": "# Weavatrix JS\n\n[![CI](https://github.com/Weavatrix/weavatrix-js/actions/workflows/ci.yml/badge.svg)](https://github.com/Weavatrix/weavatrix-js/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/weavatrix-js.svg)](https://www.npmjs.com/package/weavatrix-js)\n[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nPart of the [Weavatrix ecosystem](https://weavatrix.com/ecosystem). This repository preserves the explicit JavaScript engine line.\n\n> This is the JavaScript engine of Weavatrix, continued as `weavatrix-js`.\n> The [`weavatrix`](https://www.npmjs.com/package/weavatrix) npm package ships\n> the native Rust engine from\n> [weavatrix-rust](https://github.com/Weavatrix/weavatrix-rust) starting\n> with 1.0.0; pin `weavatrix@0.3.14` or install `weavatrix-js` to stay on the\n> JavaScript implementation (including its LSP-assisted TypeScript path).\n\n**Local repository intelligence for AI coding agents — understand an application fast, then change it with evidence.**\n\nWeavatrix builds a reusable living graph of any local repository — files, symbols, imports, calls,\ninheritance, Health findings, clone families and Git-history coupling — and gives Claude Code, Codex\nor any MCP client a bounded map for fast understanding and low repeated context. The same graph then\nanswers change impact, Health, dead-code review, duplicates, history and intended-architecture\nquestions. **34 network-free tools. No repository data leaves your machine.**\n\n- Website: [weavatrix.com](https://weavatrix.com)\n- Source: [github.com/Weavatrix/weavatrix-js](https://github.com/Weavatrix/weavatrix-js)\n- npm: [`weavatrix-js`](https://www.npmjs.com/package/weavatrix-js) — `npx -y weavatrix-js <repoRoot>`\n\n## Primary native Rust engine\n\n[`weavatrix-rust`](https://github.com/Weavatrix/weavatrix-rust) is the\npure-Rust read-only MCP and library implementation. Its default build exposes\n39 tools, covers the 34 read-only capabilities of this JavaScript line and adds cross-repository Git, vector\nsearch, semantic/SEO linking, and temporal-memory context through independent\nMIT crates.\n\n```sh\ncargo install weavatrix-rust\nweavatrix mcp <repoRoot> --profile=code\n```\n\nThe Rust engine does not invoke `git`, `rg`, Node.js, Python, a language server,\nor code from the analyzed repository. Use `--profile=all`, `code`, or `seo` to\nexpose one bounded view without running duplicate MCP servers. Same-revision\nbenchmarks and limitations are published in its\n[benchmark report](https://github.com/Weavatrix/weavatrix-rust/blob/main/docs/benchmarks.md).\n\nThis package is the complete offline engine under the MIT license: it reads and analyzes your code,\ninitiates no outbound HTTP, and never edits your source. It is the read-only base of a layered stack —\nadd [`weavatrix-refactor`](https://github.com/Weavatrix/weavatrix-refactor) (Apache-2.0) to apply\nhash-verified, reversible edits, or [`weavatrix-online`](https://github.com/Weavatrix/weavatrix-online)\nfor authorized Cloud or self-hosted sync. Each is an optional superset that depends on this core through\na supported extension API; the offline/online split is documented in\n[docs/adr/0001-v0.3-offline-online-split.md](docs/adr/0001-v0.3-offline-online-split.md).\n\n## Install\n\nRequires Node ≥ 18.\n\n```sh\n# Claude Code\nclaude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot>\n\n# Codex CLI\ncodex mcp add weavatrix-js -- npx -y weavatrix-js <repoRoot>\n```\n\n```toml\n# or in ~/.codex/config.toml\n[mcp_servers.weavatrix-js]\ncommand = \"npx\"\nargs = [\"-y\", \"weavatrix-js\", \"C:/path/to/repo\"]\nstartup_timeout_sec = 20\ntool_timeout_sec = 60\n```\n\nOr run from a clone:\n\n```sh\ngit clone https://github.com/Weavatrix/weavatrix-js\ncd weavatrix-js && npm install\nclaude mcp add -s user weavatrix-js -- node <path-to>/weavatrix-js/bin/weavatrix-mcp.mjs <repoRoot>\n```\n\n`<repoRoot>` is the repository to start with. Graphs are derived data and never live in your repo:\nthey are stored in the per-user registry at `~/.weavatrix/graphs/<repository-storage-key>/graph.json`\n(with a stable `.repository-id` beside them). No graph yet? Ask the agent to call `rebuild_graph`, or\njust use a tool — graph and Health reads auto-reconcile the working graph before answering.\n\nAn agent skill with recipes ships in [skill/SKILL.md](skill/SKILL.md) — install it as\n`~/.claude/skills/weavatrix-js/SKILL.md` (Claude Code) or\n`~/.codex/skills/weavatrix-js/SKILL.md` (Codex).\n\n## Configure\n\n**Local capability profile** — pass a profile as the final positional argument (omitted = `offline`):\n\n| Profile | Local repository switching | Cross-repo graph reads | Network requests | Tools |\n|---|---:|---:|---:|---:|\n| `offline` (default) | Yes, only via `open_repo` | Yes, only via `trace_api_contract` | None | 34 |\n| `pinned` | No | No | None | 31 |\n\n```sh\n# hard-pin one repository and expose no cross-repo tools:\nclaude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot> pinned\n```\n\nAdvanced registrations may pass an exact comma-separated capability set instead:\n`graph,search,source,health,build,retarget,crossrepo`. A custom list must include `crossrepo` to\nexpose `trace_api_contract`. Legacy `online`/`osv`/`hosted`/`full` names fail loudly and point to\n`weavatrix-online`.\n\n**Semantic precision** — a bounded, read-only TypeScript/JavaScript language-server overlay is on by\ndefault for new graphs and upgrades confirmed references to `EXACT_LSP`. Turn it off for parser-only\noperation with `WEAVATRIX_PRECISION=off` (env), `precision:\"off\"` on `rebuild_graph`/`open_repo`, or\nthe MCPB installer's precision choice. Java and Rust have no bundled language server; their edges stay\nparser-derived.\n\nThe startup prewarm queries 32 ranked symbols (never more than 64) by default. For a deliberate\nhigh-budget pass, set `WEAVATRIX_PRECISION_MAX_SYMBOLS` above 64 or `WEAVATRIX_PRECISION_PREWARM=full`\nto cover every eligible target up to a 10,000-symbol ceiling; `WEAVATRIX_PRECISION_MAX_REFERENCES`,\n`WEAVATRIX_PRECISION_MAX_LINKS` and `WEAVATRIX_PRECISION_TIMEOUT_MS` tune the budgets. Repositories\nthat exceed a hard ceiling stay honestly `PARTIAL`.\n\n**Repository config files** (all optional, repository-root):\n\n- `.weavatrixignore` — analysis-only exclusions that should stay tracked in Git (`*`, `**`, `?`,\n  root-anchored `/patterns`, directory suffixes, ordered `!` re-includes).\n- `.weavatrix.json` — cross-repository HTTP client/wrapper contracts (`httpContracts`) and\n  `classify.product` overrides.\n- `.weavatrix-deps.json` — `entrypoints`, `nonRuntimeRoots`, and Python `managedDependencies` /\n  `ignoreDependencies` for conventions that cannot be inferred safely.\n\n**Test execution** — `verified_change` is read-only by default. Running an existing package\ntest/check/verify script requires both `run_tests:true` and `WEAVATRIX_ALLOW_TEST_RUNS=1`; arbitrary\ncommands are always rejected.\n\nAfter an upgrade, reconnect the MCP server or start a new agent task before checking the tool list —\nmany clients snapshot `tools/list` for the lifetime of a connection. `graph_stats` reports the running\nversion, enabled capabilities and registered-tool count so a cached process is distinguishable from\nthe installed package.\n\n## Tools\n\nThe 34 methods project the same reusable graph into the smallest view a task needs.\n\n- **graph** — `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`, `shortest_path`,\n  `get_community`, `list_communities`, `module_map`, `get_dependents`, `change_impact`,\n  `verified_change`, `git_history`, `graph_diff`, `get_architecture_contract`, `prepare_change`.\n  Runtime, TypeScript type-only and language compile-only edges are reported separately; every edge\n  carries versioned provenance (`EXTRACTED` / `RESOLVED` / `INFERRED`, upgraded to `EXACT_LSP` only by\n  the bundled TS/JS overlay, `CONFLICT` when evidence disagrees).\n- **search / source** — `search_code` (ripgrep-backed with a pure-Node fallback and\n  repository-relative path globs), `read_source`, `context_bundle`, `inspect_symbol`,\n  `list_endpoints` (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum & actix-web/Spring),\n  `trace_endpoint`.\n- **health** — `find_dead_code`, `run_audit` (capability matrix + unused files/exports/dependencies,\n  missing/duplicate deps, typosquats and lockfile drift; `base_ref` +\n  `debt: new|existing|all` for review-scoped results), `find_duplicates` (MOSS winnowing, catches\n  renamed clones), `coverage_map`, `hot_path_review`, `verify_architecture`,\n  `explain_architecture_violation`, `propose_architecture_exception`.\n- **build** — `rebuild_graph` (reports the structural delta, keeps the prior state as `graph.prev.json`).\n- **retarget** *(in `offline`, absent from `pinned`)* — `open_repo`, `list_known_repos`.\n- **crossrepo** *(in `offline`, absent from `pinned`)* — `trace_api_contract` (joins routes to client\n  call-sites across registered local graphs; reads no source). Results are compact and paginated by\n  default (`page_size`, opaque `cursor`, and bounded `per_item_limit` samples); `response_detail=\"full\"`\n  is an explicit opt-in and remains paginated.\n\nEvery finding is review evidence, never an auto-delete verdict: `find_dead_code` /\n`run_audit category=unused` always return `REVIEW_REQUIRED` with `autoDelete:false`. Typecheck, tests\nand runtime checks remain the release authority.\n\n## Always-fresh graph\n\nThere is no watcher daemon to run and no manual refresh step: every graph/health call reconciles the\ngraph before answering. A Git-token freshness probe (HEAD + dirty/untracked content, debounced 2 s)\ndecides whether anything changed; when it did, a bounded incremental refresh reparses only the changed\nfiles plus their reverse importers (≤ 24 changed / ≤ 80 reparsed JS/TS files) and merges the scoped\nresult into the previous graph under a file lock. Config/lockfile edits, export-surface changes,\nbarrel files and non-JS/TS languages fall back to a full rebuild — correctness always wins over speed.\nOutside a Git working tree there is no probe to read, so freshness cannot be proven and the debounce\nwindow alone bounds the work: one rebuild per window rather than one per call.\nEach refreshed answer carries a structured `refresh` record (`none` / `incremental` / `full`, changed\nfile count), so an agent can tell exactly which repository state it is reasoning about. The same\nguarantees hold across concurrent MCP clients sharing one canonical graph.\n\n## Benchmarks\n\nTwo gates ship in the repository:\n\n- `npm run benchmark` — a reproducible golden suite for TypeScript, JavaScript, Python, Go, Java and\n  Rust, plus cross-repository HTTP matching, framework conventions and the MCP graph lifecycle.\n- `npm run benchmark:real` — compares revision-pinned local snapshots against the checked-in 0.2.1\n  relation baseline; it fails on unexplained signal loss (`MISSING`/`STALE`/`UNBASELINED` stay\n  incomplete, not green).\n\nRepresentative local regression run (Windows x64, Node 24.15.0):\n\n| Gate | Result | Selected evidence |\n|---|---:|---|\n| Six language fixtures | 6/6 PASS | exact symbols/edges and complete edge provenance |\n| Cross-repo fixture | PASS, ~432 ms cold | endpoint match, typed wrapper, external use |\n| Lifecycle | PASS | `full → incremental → none → reconnect/none` |\n| Total fixture cold build | ~1.31 s | all six language graphs |\n| Real-repository baseline | 6/6 PASS | TS, JS, Python, Go, Java and Rust snapshots |\n\nReal snapshots ranged from 473 nodes / 1,165 edges in 0.22 s (Go) to 8,192 nodes / 21,814 edges in\n9.44 s (TypeScript). These are regression measurements on one machine, not competitor benchmarks. See\n[benchmark/cases.mjs](benchmark/cases.mjs) and [docs/benchmarking.md](docs/benchmarking.md).\n\n## Security model\n\nSocket capability alerts describe the expected powers of a local code-analysis tool; they are not\nvulnerability findings. Where each comes from and how it is bounded:\n\n| Capability alert | Why it exists | Activation and boundary |\n|---|---|---|\n| Network access | None in the MIT core | `offline`/`pinned` expose only local tools; online integration is a separate package |\n| Shell access | Local `git` (staleness/impact), `rg` (search), the bundled tsserver for JS/TS semantics, Windows child-tree termination, optional `verified_change` test scripts | The semantic provider never runs repository code; test execution needs `run_tests:true` + `WEAVATRIX_ALLOW_TEST_RUNS=1` and rejects arbitrary commands |\n| Debug / dynamic loading | Cache-busted `import()` hot-reloads watched MCP tool modules; `createRequire` loads package metadata and parser deps | Loads files from the installed package only; no `eval` |\n| Environment access | Reads local `WEAVATRIX_*` settings; children inherit a credential-stripped env | Connector secrets are removed; tsserver receives only allowlisted OS/temp/locale values |\n| Filesystem access | Reads the active repository, graph, lockfiles and coverage; writes derived graphs and caches | Realpath containment blocks traversal and symlink escapes; `pinned` removes `open_repo` |\n`read_source` accepts repo-relative regular files only, caps a read at 2 MB, and refuses lexical or\nrealpath escapes. Report suspected vulnerabilities privately as described in [SECURITY.md](SECURITY.md).\n\nDependency vulnerability matching, advisory refresh and installed-package malware review are not\npart of this package. Those networked/security-review workflows live in\n[`weavatrix-online`](https://github.com/Weavatrix/weavatrix-online), so the local JS engine does\nnot advertise a security verdict it cannot establish.\n\n## Languages\n\nJavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · Solidity · HTML · CSS — parsed with\n[web-tree-sitter](https://github.com/tree-sitter/tree-sitter) WASM grammars; no Python install and no\nnative compilation.\n\nSQL is indexed without a grammar: `.sql` files contribute tables, views, columns, functions, indexes\nand triggers as first-class graph symbols, and SQL found in string literals of any other language\nlinks the enclosing function to the table it queries. That makes schema objects visible to\n`change_impact`/`get_dependents` (who touches this table?) and lets the dead-code check flag columns\nno statement references — conservatively: verdicts require literal-SQL evidence in the repo, and\n`SELECT *`-consumed tables never have their columns judged by name (ORM-generated SQL stays invisible\nand is therefore never judged either).\n\nTest surfaces are classified per file (path conventions plus `.weavatrix.json` overrides) and, for\nRust, per symbol: `#[cfg(test)]` modules and `#[test]`/`#[bench]` items inside production `.rs` files\ncarry a node-level `test_surface` flag, so dead-code, query, hot-path and hub tools treat them as\ntests rather than production code.\n\n## Development\n\n```sh\nnpm install\nnpm test                 # unit/integration tests plus the quick golden benchmark\nnpm run benchmark        # full TS/JS/Python/Go/Java/Rust + MCP lifecycle gate\nnpm run benchmark:real   # locally available real repos vs source-free 0.2.1 baselines\n```\n\nMaintained JavaScript/TypeScript under `src`, `bin`, `scripts`, `test` has a hard 300-line physical\nceiling enforced by the release suite; larger concerns split into owner-focused modules behind slim\nfacades. The weavatrix.com landing site lives in its own repository (`weavatrix-site`).\n\n## Release history\n\nPer-version patch notes live in [docs/releases/](docs/releases/) — start with the newest entry there.\nThe release process and gates are in [scripts/verify-release.mjs](scripts/verify-release.mjs).\n\n## License\n\nThe Weavatrix source in this repository is [MIT licensed](LICENSE) © 2026 Sergii Ziborov.\nThird-party dependencies retain their own licenses. See the public\n[license page](https://weavatrix.com/license) for the same notice.\n",
  "bytes": 15776,
  "sha": "adca8a044ccae10d7ffdcf79b2416f484b6686c9461d127f601abe090fa92a08",
  "repo_slug": "sergii-ziborov/weavatrix-js",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sergii_ziborov_weavatrix_js_9f5c3ce7/readme"
}