projscan 2.1.0 → 2.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -26
- package/dist/analyzers/supplyChainCheck.d.ts +2 -0
- package/dist/analyzers/supplyChainCheck.js +400 -0
- package/dist/analyzers/supplyChainCheck.js.map +1 -0
- package/dist/cli/commands/agentBrief.d.ts +1 -0
- package/dist/cli/commands/agentBrief.js +68 -0
- package/dist/cli/commands/agentBrief.js.map +1 -0
- package/dist/cli/commands/bugHunt.d.ts +1 -0
- package/dist/cli/commands/bugHunt.js +59 -0
- package/dist/cli/commands/bugHunt.js.map +1 -0
- package/dist/cli/commands/evidencePack.d.ts +1 -0
- package/dist/cli/commands/evidencePack.js +70 -0
- package/dist/cli/commands/evidencePack.js.map +1 -0
- package/dist/cli/commands/qualityScorecard.d.ts +1 -0
- package/dist/cli/commands/qualityScorecard.js +61 -0
- package/dist/cli/commands/qualityScorecard.js.map +1 -0
- package/dist/cli/commands/regressionPlan.d.ts +1 -0
- package/dist/cli/commands/regressionPlan.js +77 -0
- package/dist/cli/commands/regressionPlan.js.map +1 -0
- package/dist/cli/commands/releaseTrain.d.ts +1 -0
- package/dist/cli/commands/releaseTrain.js +58 -0
- package/dist/cli/commands/releaseTrain.js.map +1 -0
- package/dist/cli/commands/workplan.d.ts +1 -0
- package/dist/cli/commands/workplan.js +136 -0
- package/dist/cli/commands/workplan.js.map +1 -0
- package/dist/cli/index.js +14 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/core/agentBrief.d.ts +6 -0
- package/dist/core/agentBrief.js +192 -0
- package/dist/core/agentBrief.js.map +1 -0
- package/dist/core/bugHunt.d.ts +6 -0
- package/dist/core/bugHunt.js +278 -0
- package/dist/core/bugHunt.js.map +1 -0
- package/dist/core/issueEngine.js +2 -0
- package/dist/core/issueEngine.js.map +1 -1
- package/dist/core/preflight.js +38 -4
- package/dist/core/preflight.js.map +1 -1
- package/dist/core/qualityScorecard.d.ts +6 -0
- package/dist/core/qualityScorecard.js +220 -0
- package/dist/core/qualityScorecard.js.map +1 -0
- package/dist/core/regressionPlan.d.ts +7 -0
- package/dist/core/regressionPlan.js +226 -0
- package/dist/core/regressionPlan.js.map +1 -0
- package/dist/core/releaseEvidence.d.ts +7 -0
- package/dist/core/releaseEvidence.js +174 -0
- package/dist/core/releaseEvidence.js.map +1 -0
- package/dist/core/releaseTrain.d.ts +5 -0
- package/dist/core/releaseTrain.js +348 -0
- package/dist/core/releaseTrain.js.map +1 -0
- package/dist/core/review.js +31 -2
- package/dist/core/review.js.map +1 -1
- package/dist/core/workplan.d.ts +12 -0
- package/dist/core/workplan.js +440 -0
- package/dist/core/workplan.js.map +1 -0
- package/dist/index.d.ts +8 -1
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/mcp/tools/agentBrief.d.ts +2 -0
- package/dist/mcp/tools/agentBrief.js +39 -0
- package/dist/mcp/tools/agentBrief.js.map +1 -0
- package/dist/mcp/tools/bugHunt.d.ts +2 -0
- package/dist/mcp/tools/bugHunt.js +31 -0
- package/dist/mcp/tools/bugHunt.js.map +1 -0
- package/dist/mcp/tools/evidencePack.d.ts +2 -0
- package/dist/mcp/tools/evidencePack.js +39 -0
- package/dist/mcp/tools/evidencePack.js.map +1 -0
- package/dist/mcp/tools/qualityScorecard.d.ts +2 -0
- package/dist/mcp/tools/qualityScorecard.js +26 -0
- package/dist/mcp/tools/qualityScorecard.js.map +1 -0
- package/dist/mcp/tools/regressionPlan.d.ts +2 -0
- package/dist/mcp/tools/regressionPlan.js +47 -0
- package/dist/mcp/tools/regressionPlan.js.map +1 -0
- package/dist/mcp/tools/releaseTrain.d.ts +2 -0
- package/dist/mcp/tools/releaseTrain.js +27 -0
- package/dist/mcp/tools/releaseTrain.js.map +1 -0
- package/dist/mcp/tools/workplan.d.ts +2 -0
- package/dist/mcp/tools/workplan.js +70 -0
- package/dist/mcp/tools/workplan.js.map +1 -0
- package/dist/mcp/tools.js +14 -0
- package/dist/mcp/tools.js.map +1 -1
- package/dist/projscan-sbom.cdx.json +4589 -0
- package/dist/tool-manifest.json +196 -3
- package/dist/types.d.ts +245 -1
- package/dist/utils/formatSupport.d.ts +8 -0
- package/dist/utils/formatSupport.js +8 -0
- package/dist/utils/formatSupport.js.map +1 -1
- package/package.json +9 -6
package/README.md
CHANGED
|
@@ -9,9 +9,9 @@
|
|
|
9
9
|
|
|
10
10
|
**Agent-first code intelligence.** An MCP server that lets AI coding agents (Claude Code, Codex, Cursor, Gemini, Windsurf, Cline, Continue, Zed — any MCP-aware client) query your codebase — with a CLI for humans and a local plugin layer for team-specific policy and reporting.
|
|
11
11
|
|
|
12
|
-
[AI Agent Quick Start](#ai-agent-integration-mcp) · [CLI Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v2.
|
|
12
|
+
[AI Agent Quick Start](#ai-agent-integration-mcp) · [CLI Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/GUIDE.md) · [Roadmap](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/ROADMAP.md)
|
|
13
13
|
|
|
14
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
14
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/projscan-reporter-plugin.png" alt="projscan reporter plugin running in a macOS-style terminal window with a team health summary" width="700">
|
|
15
15
|
|
|
16
16
|
</div>
|
|
17
17
|
|
|
@@ -21,7 +21,7 @@
|
|
|
21
21
|
|
|
22
22
|
AI coding agents are becoming the primary interface to code. Today, when you ask your agent *"which files implement auth?"* or *"what breaks if I bump React from 18 to 19?"* - it either guesses from names, or it shells out to grep and reads raw output not built for it.
|
|
23
23
|
|
|
24
|
-
**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through structured MCP tools. It can run a preflight safety gate before edits or merge, query the import graph, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, surface coupling/cycle hotspots, get an **intent-grounded** one-call PR review (now with new-taint-flow detection that *blocks* unsafe merges, plus an optional natural-language intent arg that labels each finding expected / unexpected / out-of-scope), request structured fix-action prompts for any open issue and **mechanically apply** the safe ones with rollback, ask "what breaks if I change this?" via transitive blast-radius analysis (across registered sibling repos too), surface source-to-sink taint flows, share a durable session across multiple agent invocations, and learn from how you use it — quieting accumulated noise on this specific repo over time without ever phoning home.
|
|
24
|
+
**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through structured MCP tools. It can run a preflight safety gate before edits or merge, including supply-chain IOC evidence, query the import graph, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, surface coupling/cycle hotspots, get an **intent-grounded** one-call PR review (now with new-taint-flow detection that *blocks* unsafe merges, plus an optional natural-language intent arg that labels each finding expected / unexpected / out-of-scope), request structured fix-action prompts for any open issue and **mechanically apply** the safe ones with rollback, ask "what breaks if I change this?" via transitive blast-radius analysis (across registered sibling repos too), surface source-to-sink taint flows, share a durable session across multiple agent invocations, and learn from how you use it — quieting accumulated noise on this specific repo over time without ever phoning home.
|
|
25
25
|
|
|
26
26
|
The stable local plugin platform turns that same pipeline into a team substrate: analyzer plugins add project-specific findings, and reporter plugins render `doctor`, `analyze`, and `ci` in your team's own voice without changing the underlying scan.
|
|
27
27
|
|
|
@@ -33,7 +33,7 @@ Humans get the same thing through the CLI.
|
|
|
33
33
|
npx projscan
|
|
34
34
|
```
|
|
35
35
|
|
|
36
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
36
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/projscan-reporter-plugin.gif" alt="projscan doctor rendered through a local reporter plugin in a macOS-style terminal window" width="700">
|
|
37
37
|
|
|
38
38
|
Run `projscan doctor` for a focused health check:
|
|
39
39
|
|
|
@@ -41,7 +41,7 @@ Run `projscan doctor` for a focused health check:
|
|
|
41
41
|
npx projscan doctor
|
|
42
42
|
```
|
|
43
43
|
|
|
44
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
44
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20doctor.gif" alt="npx projscan doctor" width="700">
|
|
45
45
|
|
|
46
46
|
## Install
|
|
47
47
|
|
|
@@ -61,8 +61,16 @@ Run inside any repository:
|
|
|
61
61
|
|
|
62
62
|
```bash
|
|
63
63
|
projscan # Full project analysis
|
|
64
|
-
projscan
|
|
65
|
-
projscan
|
|
64
|
+
projscan workplan --mode bug_hunt # Prioritized agent execution plan
|
|
65
|
+
projscan bug-hunt --format json # Bug-hunt fix queue with verification commands
|
|
66
|
+
projscan agent-brief --intent bug_hunt # Compact next-agent context packet
|
|
67
|
+
projscan quality-scorecard --format json # Dimensioned quality view
|
|
68
|
+
projscan release-train --format json # Product readiness plan
|
|
69
|
+
projscan evidence-pack --website-prompt # Approval packet with product evidence
|
|
70
|
+
projscan regression-plan --level full # Risk-based verification matrix
|
|
71
|
+
projscan handoff # Concise next-agent handoff
|
|
72
|
+
projscan preflight --format json # Agent safety gate with supply-chain evidence
|
|
73
|
+
projscan doctor # Health check, including security and supply-chain risks
|
|
66
74
|
projscan hotspots # Rank files by risk (churn × complexity × issues × ownership)
|
|
67
75
|
projscan search <query> # BM25-ranked search (content + symbols + path)
|
|
68
76
|
projscan file <path> # Drill into a file - purpose, risk, ownership, issues
|
|
@@ -84,17 +92,25 @@ projscan plugin test .projscan-plugins/policy.projscan-plugin.json
|
|
|
84
92
|
PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar
|
|
85
93
|
```
|
|
86
94
|
|
|
87
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
95
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20--help.gif" alt="npx projscan --help" width="700">
|
|
88
96
|
|
|
89
|
-
For a comprehensive walkthrough, see the **[Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v2.
|
|
97
|
+
For a comprehensive walkthrough, see the **[Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/GUIDE.md)**.
|
|
90
98
|
|
|
91
99
|
## Commands
|
|
92
100
|
|
|
93
101
|
| Command | Description |
|
|
94
102
|
|---------|-------------|
|
|
95
103
|
| `projscan analyze` | Full analysis - languages, frameworks, dependencies, issues |
|
|
96
|
-
| `projscan
|
|
97
|
-
| `projscan
|
|
104
|
+
| `projscan workplan` | Agent execution plan - prioritized tasks with evidence, tools, verification, and handoff text |
|
|
105
|
+
| `projscan bug-hunt` | Prioritized bug-hunt fix queue from doctor, preflight, hotspot, and session evidence |
|
|
106
|
+
| `projscan agent-brief` | Compact next-agent context packet with focus items, guardrails, repo context, and next actions |
|
|
107
|
+
| `projscan quality-scorecard` | Dimensioned quality view with health, security, tests, maintainability, coordination, and top risks |
|
|
108
|
+
| `projscan release-train` | Plan upcoming product lines with readiness evidence |
|
|
109
|
+
| `projscan evidence-pack` | Assemble approval evidence from planning, bug-hunt, workplan, and preflight signals |
|
|
110
|
+
| `projscan regression-plan` | Build a smoke, focused, or full regression matrix from product risk signals |
|
|
111
|
+
| `projscan handoff` | Concise next-agent handoff from the current workplan |
|
|
112
|
+
| `projscan doctor` | Health check - missing tooling, architecture smells, security and supply-chain risks |
|
|
113
|
+
| `projscan preflight` | Agent safety gate - `proceed`, `caution`, or `block` with health, change, plugin, and supply-chain evidence |
|
|
98
114
|
| `projscan hotspots` | Rank files by risk - churn × complexity × issues × ownership |
|
|
99
115
|
| `projscan search <query>` | **BM25-ranked search** - content + symbols + path, with excerpts |
|
|
100
116
|
| `projscan file <path>` | Drill into a file - purpose, risk, ownership, related issues |
|
|
@@ -129,31 +145,31 @@ projscan --help
|
|
|
129
145
|
<details>
|
|
130
146
|
<summary><strong>projscan structure</strong> - Directory tree with file counts</summary>
|
|
131
147
|
|
|
132
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
148
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20structure.gif" alt="npx projscan structure" width="700">
|
|
133
149
|
</details>
|
|
134
150
|
|
|
135
151
|
<details>
|
|
136
152
|
<summary><strong>projscan diagram</strong> - Architecture visualization</summary>
|
|
137
153
|
|
|
138
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
154
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20diagram.gif" alt="npx projscan diagram" width="700">
|
|
139
155
|
</details>
|
|
140
156
|
|
|
141
157
|
<details>
|
|
142
158
|
<summary><strong>projscan dependencies</strong> - Dependency analysis</summary>
|
|
143
159
|
|
|
144
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
160
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20dependencies.gif" alt="npx projscan dependencies" width="700">
|
|
145
161
|
</details>
|
|
146
162
|
|
|
147
163
|
<details>
|
|
148
164
|
<summary><strong>projscan explain</strong> - File explanation</summary>
|
|
149
165
|
|
|
150
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
166
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20explain.gif" alt="npx projscan explain" width="700">
|
|
151
167
|
</details>
|
|
152
168
|
|
|
153
169
|
<details>
|
|
154
170
|
<summary><strong>projscan badge</strong> - Health badge generation</summary>
|
|
155
171
|
|
|
156
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
172
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20badge.gif" alt="npx projscan badge" width="700">
|
|
157
173
|
</details>
|
|
158
174
|
|
|
159
175
|
### Output Formats
|
|
@@ -175,7 +191,7 @@ Run `projscan help` for the generated command-by-command support matrix.
|
|
|
175
191
|
|
|
176
192
|
projscan can load local plugins from `.projscan-plugins/` when `PROJSCAN_PLUGINS_PREVIEW=1` is set. The environment flag is kept for explicit local-code opt-in. Analyzer plugins emit normal projscan issues; reporter plugins render supported CLI commands with team-specific output.
|
|
177
193
|
|
|
178
|
-
**2.0 upgrade notes:** migrating from 1.x or authoring plugins? Start with the [2.0 Migration Guide](https://github.com/abhiyoheswaran1/projscan/blob/v2.
|
|
194
|
+
**2.0 upgrade notes:** migrating from 1.x or authoring plugins? Start with the [2.0 Migration Guide](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/2.0-MIGRATION.md), then use [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/PLUGIN-AUTHORING.md) and the [manifest schema](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/plugin.schema.json) as the stable contract.
|
|
179
195
|
|
|
180
196
|
```bash
|
|
181
197
|
projscan plugin list
|
|
@@ -184,9 +200,9 @@ PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar
|
|
|
184
200
|
PROJSCAN_PLUGINS_PREVIEW=1 projscan ci --reporter team-radar --min-score 80
|
|
185
201
|
```
|
|
186
202
|
|
|
187
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
203
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/projscan-reporter-plugin.gif" alt="projscan local reporter plugin rendering a team health report" width="700">
|
|
188
204
|
|
|
189
|
-
Reporter plugins are intentionally CLI-only. MCP tools keep returning structured JSON-compatible payloads so agents can reason over stable data, while humans can get a polished local report for their team. Custom presentation, team-branded summaries, and white-label reports belong in reporter plugins rather than new core HTML theming flags. See [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v2.
|
|
205
|
+
Reporter plugins are intentionally CLI-only. MCP tools keep returning structured JSON-compatible payloads so agents can reason over stable data, while humans can get a polished local report for their team. Custom presentation, team-branded summaries, and white-label reports belong in reporter plugins rather than new core HTML theming flags. See [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/PLUGIN-AUTHORING.md) for manifest shape, `render(context)`, validation, and the trust model.
|
|
190
206
|
|
|
191
207
|
### Options
|
|
192
208
|
|
|
@@ -330,6 +346,7 @@ projscan reads your source code so it can be useful; it does not send your sourc
|
|
|
330
346
|
| Read source files | every command | no | parses with tree-sitter / Babel; results cached at `.projscan-cache/` |
|
|
331
347
|
| Spawn `git` | `hotspots`, `pr-diff`, `review`, `diff` | git itself may fetch if you run `git fetch` separately; **projscan never invokes `git fetch`** | `env: process.env` is passed so `git` can find its config |
|
|
332
348
|
| Spawn `npm audit` | `audit` only | yes — by `npm`, not by projscan | runs against your local lockfile |
|
|
349
|
+
| Scan supply-chain IOCs | `doctor`, `preflight`, release validation | no | checks manifests, lockfiles, hidden editor hooks, and suspicious install-time payloads against bundled indicators |
|
|
333
350
|
| Load local plugins | only with `PROJSCAN_PLUGINS_PREVIEW=1` | no | imports local JS modules declared in `.projscan-plugins/`; only enable plugins you trust |
|
|
334
351
|
| Load wasm grammars | first parse of a non-JS file | no | served from `dist/grammars/` inside the package; no fetch |
|
|
335
352
|
| Build embeddings | semantic search opt-in only | yes — by `@xenova/transformers`, on first use | model cached locally after first download; remove the peer dep to remove this code path entirely |
|
|
@@ -346,7 +363,7 @@ If you read projscan's [Socket report](https://socket.dev/npm/package/projscan),
|
|
|
346
363
|
### Audit it yourself
|
|
347
364
|
|
|
348
365
|
- **Source is open** at [github.com/abhiyoheswaran1/projscan](https://github.com/abhiyoheswaran1/projscan). The npm tarball matches the `dist/` produced by `npm run build` at the matching tag.
|
|
349
|
-
- **Public API surface is locked** by `scripts/check-stability.mjs`, which runs in CI on every PR and fails on any rename or removal of an MCP tool, CLI command, or exit code. See [`docs/STABILITY.md`](https://github.com/abhiyoheswaran1/projscan/blob/v2.
|
|
366
|
+
- **Public API surface is locked** by `scripts/check-stability.mjs`, which runs in CI on every PR and fails on any rename or removal of an MCP tool, CLI command, or exit code. See [`docs/STABILITY.md`](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/STABILITY.md).
|
|
350
367
|
- **Run it offline:** `npm install -g projscan` followed by anything except `audit` and `--mode semantic` works without network.
|
|
351
368
|
- **Drop privilege further:** in CI, run projscan in a sandbox that disallows network egress; everything except `audit` will pass.
|
|
352
369
|
|
|
@@ -384,7 +401,7 @@ projscan ci --changed-only # Gate only on this PR's diff
|
|
|
384
401
|
projscan ci --format sarif > projscan.sarif # SARIF for Code Scanning
|
|
385
402
|
```
|
|
386
403
|
|
|
387
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
404
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci --min-score 70" width="700">
|
|
388
405
|
|
|
389
406
|
### GitHub Action (recommended)
|
|
390
407
|
|
|
@@ -453,7 +470,7 @@ Fields:
|
|
|
453
470
|
- `hotspots.limit` / `hotspots.since` - defaults for the `hotspots` command
|
|
454
471
|
- `monorepo.importPolicy` - cross-package import allow/deny rules in monorepos *(0.14+)*
|
|
455
472
|
|
|
456
|
-
See [`docs/GUIDE.md` → Configuration](https://github.com/abhiyoheswaran1/projscan/blob/v2.
|
|
473
|
+
See [`docs/GUIDE.md` → Configuration](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/GUIDE.md#configuration-projscanrc) for the full reference (field types, validation behavior, embedding config in `package.json`, monorepo `importPolicy` semantics).
|
|
457
474
|
|
|
458
475
|
## Tracking Health Over Time
|
|
459
476
|
|
|
@@ -466,7 +483,7 @@ projscan diff # Compare against baseline
|
|
|
466
483
|
projscan diff --format markdown # Markdown diff for PRs
|
|
467
484
|
```
|
|
468
485
|
|
|
469
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
486
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/npx%20projscan%20diff%20--save-baseline.gif" alt="npx projscan diff --save-baseline" width="700">
|
|
470
487
|
|
|
471
488
|
## Hotspots - Where to Fix First
|
|
472
489
|
|
|
@@ -555,7 +572,7 @@ Coverage is also automatically joined into `projscan hotspots` when one of those
|
|
|
555
572
|
|
|
556
573
|
**This is the primary way to use projscan.** `projscan mcp` starts an [MCP](https://modelcontextprotocol.io) server over stdio so AI coding agents can query your codebase with real structural accuracy - not regex, not grep.
|
|
557
574
|
|
|
558
|
-
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.
|
|
575
|
+
<img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v2.8.0/docs/projscan-agent-demo.gif" alt="projscan answering two agent questions: what breaks if I rename buildCodeGraph (impact analysis with definitions, direct callers, transitive reach), and where should I fix first (ranked hotspots with cyclomatic complexity)" width="700">
|
|
559
576
|
|
|
560
577
|
Two questions an agent asks; structural answers in milliseconds. *"What breaks if I rename `buildCodeGraph`?"* → 31 direct callers, 97 files reachable. *"Where should I fix first?"* → ranked hotspots with AST cyclomatic complexity, churn, and ownership signals.
|
|
561
578
|
|
|
@@ -688,8 +705,15 @@ Capability is advertised under `experimental.fileChanged` on `initialize` so cli
|
|
|
688
705
|
- *"What are the scariest untested files?"* → `projscan_coverage`
|
|
689
706
|
- *"What breaks if I bump chalk to 6?"* → `projscan_upgrade { package: "chalk" }`
|
|
690
707
|
- *"Where should I refactor first?"* → `projscan_hotspots`
|
|
708
|
+
- *"What should my agent do next?"* → `projscan_workplan { mode: "bug_hunt" }`
|
|
709
|
+
- *"Give the next agent a compact brief."* → `projscan_agent_brief { intent: "bug_hunt" }`
|
|
710
|
+
- *"Show the product quality picture."* → `projscan_quality_scorecard`
|
|
711
|
+
- *"What should I fix before a big release?"* → `projscan_bug_hunt`
|
|
712
|
+
- *"What evidence do I need before approval?"* → `projscan_evidence_pack { website_prompt: true }`
|
|
713
|
+
- *"Which checks prove this bigger product update?"* → `projscan_regression_plan { level: "full" }`
|
|
714
|
+
- *"How do I plan the next six product lines?"* → `projscan_release_train`
|
|
691
715
|
|
|
692
|
-
### The
|
|
716
|
+
### The 36 MCP tools
|
|
693
717
|
|
|
694
718
|
**Structural (0.6.0 / 0.11 / 0.13 / 0.14 / 0.15 - agent-native):**
|
|
695
719
|
- **`projscan_graph`** - query the AST-based code graph. Directions: `imports`, `exports`, `importers`, `symbol_defs`, `package_importers`. Millisecond responses on a warm cache.
|
|
@@ -697,6 +721,13 @@ Capability is advertised under `experimental.fileChanged` on `initialize` so cli
|
|
|
697
721
|
- **`projscan_coupling`** *(0.11)* - per-file fan-in / fan-out / instability + circular-import cycles (Tarjan SCC). Filter by `direction: cycles_only | high_fan_in | high_fan_out`.
|
|
698
722
|
- **`projscan_pr_diff`** *(0.11)* - structural diff between two git refs. Returns added/removed/modified files with explicit lists of exports, imports, and call sites that changed, plus ΔCC and Δfan-in.
|
|
699
723
|
- **`projscan_review`** *(0.13)* - one-call PR review. Composes `pr_diff` + per-changed-file risk + new/expanded import cycles + risky function additions + dependency changes + a verdict (`ok` / `review` / `block`).
|
|
724
|
+
- **`projscan_workplan`** *(2.3)* - agent mission-control plan. Composes preflight, review, session, hotspot, plugin, and supply-chain evidence into prioritized tasks with verification commands and handoff text.
|
|
725
|
+
- **`projscan_bug_hunt`** *(2.3)* - ranked bug-hunt queue. Composes doctor issues, preflight, hotspots, and session coordination into fix targets with verification commands.
|
|
726
|
+
- **`projscan_release_train`** *(2.3)* - product-line readiness planner. Reads version, scope, readiness evidence, and next actions.
|
|
727
|
+
- **`projscan_evidence_pack`** *(2.3)* - approval packet. Composes planning, bug-hunt, workplan, preflight, changelog, and optional website prompt evidence.
|
|
728
|
+
- **`projscan_regression_plan`** *(2.3)* - smoke/focused/full regression matrix. Turns bug-hunt, preflight, and product risk into deduplicated verification commands.
|
|
729
|
+
- **`projscan_agent_brief`** *(2.3)* - compact next-agent context packet with focus items, repo context, guardrails, and suggested next actions.
|
|
730
|
+
- **`projscan_quality_scorecard`** *(2.3)* - dimensioned quality view across health, security, tests, maintainability, coordination, top risks, and verification commands.
|
|
700
731
|
- **`projscan_fix_suggest`** *(0.14)* - structured action prompt for any open issue: headline, why it matters, where, one-paragraph instruction, optional suggested test. Closes the diagnose → fix loop.
|
|
701
732
|
- **`projscan_explain_issue`** *(0.14)* - deep dive on one issue: code excerpt, related issues in the same file, similar past commits via `git log --grep`, plus the structured FixSuggestion.
|
|
702
733
|
- **`projscan_impact`** *(0.15)* - transitive blast-radius for a file or symbol. BFS over reverse imports + symbol callsites. Use BEFORE renaming or deleting to see what breaks.
|
|
@@ -730,7 +761,7 @@ Capability is advertised under `experimental.fileChanged` on `initialize` so cli
|
|
|
730
761
|
- **`projscan_apply_fix`** *(1.6)* - mechanically execute the safe fix templates. Default is dry-run; pass `confirm: true` to write. Atomic writes, per-apply rollback record at `.projscan-cache/rollbacks/<id>.json`. Reverse with `action: "rollback", rollback_id: ...`. Six templates supported at this release: `unused-dependency-*`, `missing-test-framework`, `missing-eslint`, `missing-prettier`, `missing-editorconfig`, `missing-readme`.
|
|
731
762
|
- **`projscan_taint`** *(1.6)* - source-to-sink reachability over the per-function call graph. Built-in defaults cover common JS / Python sources (`process.env`, `req.body`, etc.) and sinks (`exec`, `eval`, `db.query`, etc.). Project-specific names go in `.projscanrc.json` `taint`. `projscan_review` automatically diffs taint flows between base and head and **blocks any PR that introduces a new flow**.
|
|
732
763
|
|
|
733
|
-
For analyzer and reporter plugin authoring, manifest validation, `--reporter <name>`, and the trust model, see [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v2.
|
|
764
|
+
For analyzer and reporter plugin authoring, manifest validation, `--reporter <name>`, and the trust model, see [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v2.8.0/docs/PLUGIN-AUTHORING.md).
|
|
734
765
|
|
|
735
766
|
### Context-window budgeting
|
|
736
767
|
|