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.
Files changed (87) hide show
  1. package/README.md +57 -26
  2. package/dist/analyzers/supplyChainCheck.d.ts +2 -0
  3. package/dist/analyzers/supplyChainCheck.js +400 -0
  4. package/dist/analyzers/supplyChainCheck.js.map +1 -0
  5. package/dist/cli/commands/agentBrief.d.ts +1 -0
  6. package/dist/cli/commands/agentBrief.js +68 -0
  7. package/dist/cli/commands/agentBrief.js.map +1 -0
  8. package/dist/cli/commands/bugHunt.d.ts +1 -0
  9. package/dist/cli/commands/bugHunt.js +59 -0
  10. package/dist/cli/commands/bugHunt.js.map +1 -0
  11. package/dist/cli/commands/evidencePack.d.ts +1 -0
  12. package/dist/cli/commands/evidencePack.js +70 -0
  13. package/dist/cli/commands/evidencePack.js.map +1 -0
  14. package/dist/cli/commands/qualityScorecard.d.ts +1 -0
  15. package/dist/cli/commands/qualityScorecard.js +61 -0
  16. package/dist/cli/commands/qualityScorecard.js.map +1 -0
  17. package/dist/cli/commands/regressionPlan.d.ts +1 -0
  18. package/dist/cli/commands/regressionPlan.js +77 -0
  19. package/dist/cli/commands/regressionPlan.js.map +1 -0
  20. package/dist/cli/commands/releaseTrain.d.ts +1 -0
  21. package/dist/cli/commands/releaseTrain.js +58 -0
  22. package/dist/cli/commands/releaseTrain.js.map +1 -0
  23. package/dist/cli/commands/workplan.d.ts +1 -0
  24. package/dist/cli/commands/workplan.js +136 -0
  25. package/dist/cli/commands/workplan.js.map +1 -0
  26. package/dist/cli/index.js +14 -0
  27. package/dist/cli/index.js.map +1 -1
  28. package/dist/core/agentBrief.d.ts +6 -0
  29. package/dist/core/agentBrief.js +192 -0
  30. package/dist/core/agentBrief.js.map +1 -0
  31. package/dist/core/bugHunt.d.ts +6 -0
  32. package/dist/core/bugHunt.js +278 -0
  33. package/dist/core/bugHunt.js.map +1 -0
  34. package/dist/core/issueEngine.js +2 -0
  35. package/dist/core/issueEngine.js.map +1 -1
  36. package/dist/core/preflight.js +38 -4
  37. package/dist/core/preflight.js.map +1 -1
  38. package/dist/core/qualityScorecard.d.ts +6 -0
  39. package/dist/core/qualityScorecard.js +220 -0
  40. package/dist/core/qualityScorecard.js.map +1 -0
  41. package/dist/core/regressionPlan.d.ts +7 -0
  42. package/dist/core/regressionPlan.js +226 -0
  43. package/dist/core/regressionPlan.js.map +1 -0
  44. package/dist/core/releaseEvidence.d.ts +7 -0
  45. package/dist/core/releaseEvidence.js +174 -0
  46. package/dist/core/releaseEvidence.js.map +1 -0
  47. package/dist/core/releaseTrain.d.ts +5 -0
  48. package/dist/core/releaseTrain.js +348 -0
  49. package/dist/core/releaseTrain.js.map +1 -0
  50. package/dist/core/review.js +31 -2
  51. package/dist/core/review.js.map +1 -1
  52. package/dist/core/workplan.d.ts +12 -0
  53. package/dist/core/workplan.js +440 -0
  54. package/dist/core/workplan.js.map +1 -0
  55. package/dist/index.d.ts +8 -1
  56. package/dist/index.js +7 -0
  57. package/dist/index.js.map +1 -1
  58. package/dist/mcp/tools/agentBrief.d.ts +2 -0
  59. package/dist/mcp/tools/agentBrief.js +39 -0
  60. package/dist/mcp/tools/agentBrief.js.map +1 -0
  61. package/dist/mcp/tools/bugHunt.d.ts +2 -0
  62. package/dist/mcp/tools/bugHunt.js +31 -0
  63. package/dist/mcp/tools/bugHunt.js.map +1 -0
  64. package/dist/mcp/tools/evidencePack.d.ts +2 -0
  65. package/dist/mcp/tools/evidencePack.js +39 -0
  66. package/dist/mcp/tools/evidencePack.js.map +1 -0
  67. package/dist/mcp/tools/qualityScorecard.d.ts +2 -0
  68. package/dist/mcp/tools/qualityScorecard.js +26 -0
  69. package/dist/mcp/tools/qualityScorecard.js.map +1 -0
  70. package/dist/mcp/tools/regressionPlan.d.ts +2 -0
  71. package/dist/mcp/tools/regressionPlan.js +47 -0
  72. package/dist/mcp/tools/regressionPlan.js.map +1 -0
  73. package/dist/mcp/tools/releaseTrain.d.ts +2 -0
  74. package/dist/mcp/tools/releaseTrain.js +27 -0
  75. package/dist/mcp/tools/releaseTrain.js.map +1 -0
  76. package/dist/mcp/tools/workplan.d.ts +2 -0
  77. package/dist/mcp/tools/workplan.js +70 -0
  78. package/dist/mcp/tools/workplan.js.map +1 -0
  79. package/dist/mcp/tools.js +14 -0
  80. package/dist/mcp/tools.js.map +1 -1
  81. package/dist/projscan-sbom.cdx.json +4589 -0
  82. package/dist/tool-manifest.json +196 -3
  83. package/dist/types.d.ts +245 -1
  84. package/dist/utils/formatSupport.d.ts +8 -0
  85. package/dist/utils/formatSupport.js +8 -0
  86. package/dist/utils/formatSupport.js.map +1 -1
  87. 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.0.0/docs/GUIDE.md) · [Roadmap](https://github.com/abhiyoheswaran1/projscan/blob/v2.0.0/docs/ROADMAP.md)
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.0.0/docs/projscan-reporter-plugin.png" alt="projscan reporter plugin running in a macOS-style terminal window with a team health summary" width="700">
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.0.0/docs/projscan-reporter-plugin.gif" alt="projscan doctor rendered through a local reporter plugin in a macOS-style terminal window" width="700">
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.0.0/docs/npx%20projscan%20doctor.gif" alt="npx projscan doctor" width="700">
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 preflight --format json # Agent safety gate: proceed, caution, or block
65
- projscan doctor # Health check
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.0.0/docs/npx%20projscan%20--help.gif" alt="npx projscan --help" width="700">
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.0.0/docs/GUIDE.md)**.
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 doctor` | Health check - missing tooling, architecture smells, security risks |
97
- | `projscan preflight` | Agent safety gate - `proceed`, `caution`, or `block` with evidence |
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.0.0/docs/npx%20projscan%20structure.gif" alt="npx projscan structure" width="700">
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.0.0/docs/npx%20projscan%20diagram.gif" alt="npx projscan diagram" width="700">
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.0.0/docs/npx%20projscan%20dependencies.gif" alt="npx projscan dependencies" width="700">
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.0.0/docs/npx%20projscan%20explain.gif" alt="npx projscan explain" width="700">
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.0.0/docs/npx%20projscan%20badge.gif" alt="npx projscan badge" width="700">
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.0.0/docs/2.0-MIGRATION.md), then use [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v2.0.0/docs/PLUGIN-AUTHORING.md) and the [manifest schema](https://github.com/abhiyoheswaran1/projscan/blob/v2.0.0/docs/plugin.schema.json) as the stable contract.
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.0.0/docs/projscan-reporter-plugin.gif" alt="projscan local reporter plugin rendering a team health report" width="700">
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.0.0/docs/PLUGIN-AUTHORING.md) for manifest shape, `render(context)`, validation, and the trust model.
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.0.0/docs/STABILITY.md).
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.0.0/docs/npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci --min-score 70" width="700">
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.0.0/docs/GUIDE.md#configuration-projscanrc) for the full reference (field types, validation behavior, embedding config in `package.json`, monorepo `importPolicy` semantics).
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.0.0/docs/npx%20projscan%20diff%20--save-baseline.gif" alt="npx projscan diff --save-baseline" width="700">
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.0.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">
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 28 MCP tools
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.0.0/docs/PLUGIN-AUTHORING.md).
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
 
@@ -0,0 +1,2 @@
1
+ import type { FileEntry, Issue } from '../types.js';
2
+ export declare function check(rootPath: string, files: FileEntry[]): Promise<Issue[]>;