io.github.abhiyoheswaran1/projscan

Adoption helper for new projscan users and agents. Returns ready-to-paste MCP client configs, workflow recipes, or first-run diagnostics without mutating the repo.

Create a compact next-agent context packet with prioritized focus items, repo context, guardrails, and suggested next actions.

Run a full projscan analysis of the project: languages, frameworks, dependencies, issues, and health score. Use this to understand a codebase before making changes.

Apply a mechanical fix for an open issue (1.6+). Default is dry-run; pass confirm:true to write. Every applied change records a rollback id usable via action:'rollback'. Mechanical templates only — semantic rewrites and codemods stay agent-driven.

Run a proof-first engineering assessment. Returns Proof Cards with local evidence, fix-first guidance, risk delta, verification commands, and ship-readiness wording.

Run `npm audit` and return a normalized summary of vulnerabilities (critical / high / moderate / low / info). Requires package-lock.json. Supports cursor pagination on the findings array. Pass `package` in a monorepo to scope findings to direct deps of one workspace package.

Run an agent-ready bug hunt. Combines doctor issues, preflight verdict, hotspots, and session coordination into a prioritized action queue with verification commands.

Coordinate parallel agents with advisory claims/leases over files, directories, or symbols, shared across the repo's git worktrees. action:"add" records a claim (optionally a lease with `ttl_seconds`) and returns any `contention` (another agent already holding an overlapping, non-expired claim); "list" returns claims; "release" drops a claim by `id`, by `target`, or all of an `agent`'s; "prune" removes expired-lease claims. Local-first and advisory — claiming an already-claimed target still succeeds, but surfaces contention so the swarm can coordinate.

Detect change collisions across the repo's in-flight git worktrees (parallel agents). Reports same-file edits (two worktrees changed the same file) and dependency overlaps (one worktree changed a file another's change imports, via the import graph) BEFORE the branches merge. Local-first; needs at least two worktrees. Each collision has `kind` (same-file | dependency), `severity` (high | medium), the two worktree paths, and the files at risk. Use this when coordinating multiple agents/sub-agents working the same repo.

One-call coordination read across the repo's in-flight git worktrees (parallel agents). Composes collisions, claims, and merge-risk into a `readiness` verdict (clear | caution | conflicted) plus counts (collisions by severity, contended claim targets, merge hotspots) and the recommended integration order. The single entry point for swarm coordination — use it before continuing parallel work. Local-first; needs at least two worktrees.

Long-running swarm coordination watch across the repo's in-flight git worktrees. Polls on an interval and emits a `notifications/projscan/coordination_changed` notification whenever the coordination state changes — readiness (clear/caution/conflicted), collision counts, contended claims, or merge hotspots. Pairs with projscan_coordinate (one-shot): use this when an agent wants to react to other agents' changes without re-asking. Local-first. Actions: "start" (returns the initial summary + a watchId), "stop" (by watchId), "list".

Aggregate token-cost analytics from the current session's tool-call history. action:"snapshot" (default) returns total tokens spent, top spenders, per-tool typical/p95 estimates, and a static expected-cost catalog so the agent can budget pre-call. 1.10+: action:"start_stream" / "stop_stream" / "list_streams" turns this into a live cost dashboard — the server polls the session log on an interval and emits notifications/projscan/cost_delta whenever new tool calls have accrued, with the per-tool deltas and the new cumulative totals inline. Pairs with the `_cost` sidecar attached to every tool result. Read-only. Note: the session event log is bounded at 500 entries — for long-running sessions, older calls are dropped from the snapshot.

Per-file coupling metrics (fan-in, fan-out, instability) and circular-import cycles, derived from the AST code graph. Use `direction` to focus the result: "all" returns every file sorted by fan-in; "high_fan_in" / "high_fan_out" sort accordingly; "cycles_only" returns just the files participating in import cycles. Cycles are reported separately as strongly-connected components of size >= 2.

Join test coverage with hotspot risk. Returns files ranked by "risk × uncovered fraction" - the scariest untested files. Requires a coverage file at coverage/lcov.info, coverage/coverage-final.json, or coverage/coverage-summary.json.

Return v3 dataflow risks over the function graph. Includes legacy direct/propagated taint projections plus bridge-helper risks where a wrapper calls both a source reader and a dangerous sink.

Analyze package.json dependencies and return counts and risks (deprecated packages, wildcard versions, etc.). In a monorepo, returns aggregated totals plus a `byWorkspace` breakdown; pass `package` to scope to one workspace.

Run a health check on the project. Returns a 0-100 score, letter grade, and the list of issues (linting, formatting, tests, security, architecture). Pass `max_cost_tokens` (1.5+) for adaptive shaping: <3000 returns verdict-only (score + counts), <7000 returns a summary (top issues), otherwise full.

Assemble one approval packet from product planning, bug-hunt, workplan, and preflight evidence.

Deep-dive on a single open issue: severity, surrounding code excerpt, other issues touching the same file, similar fixes from git log (commit messages that mention this rule), and the structured fix-action prompt. Use when an agent needs more context than projscan_doctor gives - typically before applying a fix.

Drill into a single file: purpose, imports, exports, churn/risk/ownership, related health issues, AST cyclomatic complexity, coupling (fan-in / fan-out), and per-function CC ranked by complexity. Use this after projscan_hotspots when deciding how to approach a specific risky file.

Given an issue id (from projscan_doctor / projscan_analyze) OR a file + rule pair, return a structured action prompt: headline, why it matters, where to change, one-paragraph instruction the agent can execute, optional suggested test. Rule-driven; no LLM inside projscan. Use this to close the diagnose -> fix loop.

Rank files by risk using git churn × AST cyclomatic complexity × open issues. Returns the most dangerous files to touch. Each hotspot includes `cyclomaticComplexity` (null for non-AST languages, where line count is used as fallback). Supports cursor-based pagination: pass the `nextCursor` from a previous response back as `cursor` to fetch the next page. Pass `view: "functions"` to flatten results into the top-N riskiest individual functions across all hotspots, ranked by per-function CC.

Transitive blast-radius analysis. Given a `file` (repo-relative path), returns every file that transitively imports it, ranked by BFS distance (1 = direct importer). Given a `symbol` (export name), returns the symbol's definition file(s), the files that directly call it, and their transitive importers. Use this BEFORE renaming or deleting to see what breaks. Cycle-safe; depth-bounded by `max_distance` (default 10).

Inspect or prune the local Project Memory: which analyzer rules have been surfacing repeatedly without being addressed, and what to do about them. Use when an agent wants to know "what is this project tolerating and could quiet down via .projscanrc?"

Merge-risk preflight across the repo's in-flight git worktrees (parallel agents). Given each worktree's changes and the collisions between them, returns `integrationOrder` (merge the least-entangled branch first, each with a risk score) and `hotFiles` (files changed by two or more worktrees — where merge conflict risk concentrates). Builds on projscan_collision; local-first; needs at least two worktrees.

Compare declared vs installed versions of every package. Reports drift (patch/minor/major). Workspace-aware in monorepos: each package.json is scanned, and each entry is tagged with the workspace it came from. Pass `package` to scope to a single workspace. Offline - does not hit the npm registry. Supports cursor pagination.

Create a local Agent Change Passport for reviewer handoff. Returns Proof Contract boundary, changed-file scope, proof replay, proof sufficiency, reviewer action, next commands, and optional Baseframe assessment paths without executing proof commands.

Discover and validate stable local analyzer and reporter plugins under .projscan-plugins/. Execution is opt-in via the PROJSCAN_PLUGINS_PREVIEW=1 env flag AND each module must be approved with trust-on-first-use; the list reports a per-plugin `trust` status (trusted / untrusted / changed). Approving a plugin is a deliberate human action via the `projscan plugin trust <name>` CLI — it is intentionally not exposed here. Use action:"list" to see what is discoverable and whether it would run, action:"validate" to check a manifest before committing it.

Structural (AST) diff between two refs - what changed in exports, imports, call sites, cyclomatic complexity, and fan-in. Not a text diff: this surfaces the symbols and edges that an agent reviewing a PR actually cares about. Defaults: base=origin/main (falls back to main/master/HEAD~1), head=HEAD. Spins up a throwaway git worktree at the base ref to get a clean second graph.

Answer whether an agent can safely proceed before edits, commit, or merge. Returns proceed, caution, or block with evidence and suggested next tool calls.

Run the local Proof Broker for reviewer handoff. Returns required proof, proof gaps, required reviewers, risky changed files, next commands, and PR Passport Markdown without executing proof commands.

Create, record, or replay a local Proof Contract for a change. Returns allowed files, forbidden files, proof commands, ledger evidence, scope drift, a reviewer-ready Proof Receipt, and verifiedWorkflow status for agent handoff.

Summarize quality dimensions, top risks, verification commands, and suggested next actions for agents and reviewers.

Build a smoke, focused, or full regression matrix from bug-hunt, preflight, and product risk signals.

Plan upcoming product lines with version, scope, readiness, and next-action evidence.

One-call PR review. Combines projscan_pr_diff + per-changed-file risk score + new/expanded import cycles + risky function additions + dependency changes, plus a verdict ("ok" | "review" | "block") with a one-line summary. Use when an agent is asked "is this PR safe to merge?" Defaults: base=origin/main (falls back to main/master/HEAD~1), head=HEAD. Pass `max_cost_tokens` (1.5+) to get a budget-shaped response: <3000 returns verdict-only, <7000 returns a summary, otherwise the full review. 1.9+: pass `intent` (a free-text PR description like "refactor auth middleware" or "docs: fix codex setup") to get an intent-grounded review — each finding is labelled expected / unexpected / out-of-scope against the stated intent. Verdict is unchanged; this is an extra narration layer.

Run the local Review Gate for reviewer readiness. Returns the Review Gate status, allow-review decision, proof debt, recontract guidance, required reviewers, next commands, PR-comment Markdown, and embedded Proof Broker evidence without executing proof commands.

Long-running PR review. Polls a base+head ref pair on an interval and emits a notifications/projscan/pr_changed notification whenever the review verdict, SHAs, cycle set, dep changes, taint flows, or risky-function set changes. 1.9+: the notification carries a structured `delta` describing exactly which buckets moved (verdict/baseSha/headSha/changedFiles/cycles/risky/taint/deps) and counts of newly-appearing items per bucket, so agents can skip work they do not need. Pairs with projscan_review (one-shot) — use this when an agent wants to react to pushes on a PR without re-asking. Actions: start (returns initial review + watchId) / stop / list.

Find the right projscan tool for a goal. Given `intent` (free text — e.g. "what breaks if I rename X", "coordinate parallel agents", "is it safe to commit"), returns the best-matching tool(s) with the exact call and why to use each. With no `intent`, returns the full capability catalog grouped by category. A discovery entry point over projscan's surface; deterministic keyword routing, no inference.

Ranked search across the project. Lexical (BM25) by default; optional semantic (vector) and hybrid (RRF fusion) modes available when the @xenova/transformers peer dependency is installed. Scope controls what to search: "auto"/"content" (ranked content matches with excerpts), "symbols" (exported names), "files" (path substring).

The code graph, two ways. With no `query`: returns the stable v3 semantic graph (file/function/package/symbol nodes plus imports, exports, defines, and calls edges). With `query`: answers one cheap, targeted question instead of serializing the whole graph — who imports a file, what a file imports/exports, where a symbol is defined, or which files import a package. (The targeted mode subsumes the former projscan_graph tool, removed in 4.0.)

Inspect the durable cross-invocation session: which files have been touched in this session, by what (tool result / fs watch / explicit), and the event log. Use to coordinate across multi-agent setups without re-querying git.

Simulate a proposed change plan before editing. Returns likely files, tests, contracts, rollout, proof commands, and projected risk delta from local evidence.

First-60-seconds repo orientation for agents and developers. Composes setup diagnostics, workplan, quality scorecard, adoption gaps, top risks, and next commands into one read-only workflow recommendation.

Return the project directory tree with file counts.

Source-to-sink reachability over the per-function call graph (1.6+). Surfaces "this function reads `process.env`/`req.body` and calls `exec`/`eval`/raw SQL" patterns. Defaults cover common JS / Python sources + sinks; project-specific names go in `.projscanrc.json` `taint`.

Explain repo map, runtime flows, public contracts, change readiness, and verification proof with cited file/symbol evidence.

Preview the impact of upgrading a package: npm semver drift, breaking-change markers from a local CHANGELOG, Python manifest/lockfile declarations, and files in your repo that import it. Offline by default; pass `check_registry: true` (1.3+) to fetch the actual latest npm version.

Compose preflight, review, session, hotspot, plugin, and supply-chain signals into an ordered agent execution plan with evidence, suggested tools, verification commands, and handoff text.

Cross-repo intelligence over sibling repos registered via `projscan workspace add`. Use to answer "what other repos import this file/symbol?" or "what symbols are shared across the workspace?" Read-only.