projscan 3.4.0 → 3.5.0

package/docs/PLUGIN-AUTHORING.md

@@ -1,12 +1,24 @@
 # Plugin Authoring
 
 projscan 2.0 stabilizes the local analyzer and reporter plugin contract.
-Plugin execution is opt-in via `PROJSCAN_PLUGINS_PREVIEW=1` so repositories
-must explicitly trust local plugin code before it runs.
+Plugin execution is gated by two independent controls:
 
-Plugins are local code. Enabling the opt-in flag means you trust the plugin code in
-the repository, the same way you trust project scripts in `package.json`.
-projscan does not fetch remote plugin code.
+1. **Opt-in flag** — set `PROJSCAN_PLUGINS_PREVIEW=1` to enable the plugin system at all.
+2. **Trust-on-first-use** — even with the flag on, each plugin **module** must be
+   explicitly approved with `projscan plugin trust <name>` before projscan will
+   execute it. Approval pins the module's SHA-256; if the file later changes, it
+   reverts to untrusted and must be re-approved. Untrusted plugins are discovered
+   and listed but never run.
+
+This means setting the flag globally (e.g. in your shell profile) can't silently
+execute attacker-authored code from a repository you happen to scan — you still
+have to approve each module once. The trust store lives in your user config
+directory (`$XDG_CONFIG_HOME/projscan` or `~/.config/projscan`,
+overridable with `PROJSCAN_PLUGIN_TRUST_HOME`), never inside the scanned repo.
+
+Plugins are local code. Approving one means you trust that code in the repository,
+the same way you trust project scripts in `package.json`. projscan does not fetch
+remote plugin code.
 
 ## Layout
 
@@ -184,19 +196,18 @@ Use `plugin test` after editing a plugin:
 ```sh
 projscan plugin test .projscan-plugins/policy.projscan-plugin.json
 projscan plugin test .projscan-plugins/policy.projscan-plugin.json --format json
-projscan plugin test .projscan-plugins/policy.projscan-plugin.json --fixture ./test-fixture
+PROJSCAN_PLUGINS_PREVIEW=1 projscan plugin test .projscan-plugins/policy.projscan-plugin.json --execute
+PROJSCAN_PLUGINS_PREVIEW=1 projscan plugin test .projscan-plugins/policy.projscan-plugin.json --execute --fixture ./test-fixture
 ```
 
-For analyzer plugins, the test runner loads the module, scans the fixture root,
-runs `check(rootPath, files)`, and verifies every returned issue has the required
-shape. For reporter plugins, it renders sample `doctor`, `analyze`, and `ci`
-payloads for the commands listed in the manifest and verifies each render returns
-a string.
+By default, `plugin test` validates the manifest, checks that the module file is readable, and reports guidance without importing or running plugin code. Add `--execute` only when you intentionally want to run local plugin code, and set `PROJSCAN_PLUGINS_PREVIEW=1` in the process environment.
+
+In execute mode, analyzer plugins scan the fixture root, run `check(rootPath, files)`, and verify every returned issue has the required shape. Reporter plugins render sample `doctor`, `analyze`, and `ci` payloads for the commands listed in the manifest and verify each render returns a string.
 
 The JSON result also includes three guidance blocks:
 
 - `trust`: reminds callers that local plugins execute repository code, stay local-only, and require `PROJSCAN_PLUGINS_PREVIEW=1` before execution.
-- `commands`: gives copyable `validate`, `test`, and preview-enabled `enable` commands for the same manifest.
+- `commands`: gives copyable `validate`, static `test`, preview-enabled `execute`, and `enable` commands for the same manifest.
 - `context`: reports whether the plugin requested graph/dataflow context and lists detected capabilities such as `semanticGraph` and `dataflow`.
 
 Graph-aware analyzers should keep context access lazy. Only call `context.getSemanticGraph()` or `context.getDataflow()` when the plugin needs that evidence for its issues.
@@ -209,11 +220,28 @@ projscan plugin list --format json
 ```
 
 The list command discovers manifests whether or not execution is enabled. It
-shows `enabled:false` until the opt-in flag is set.
+shows `enabled:false` until the opt-in flag is set, and a per-plugin `trust`
+status (`trusted` / `untrusted` / `changed`) so you can see what would actually run.
+
+## Trust
+
+Approve a plugin's current module bytes before it can execute:
+
+```sh
+projscan plugin trust policy        # approve one plugin by name
+projscan plugin trust --all         # approve every valid discovered plugin
+projscan plugin untrust policy      # revoke approval
+```
+
+Trust is intentionally a human CLI action — it is not exposed over the MCP server,
+so an agent can't approve a plugin on your behalf.
 
 ## Enable
 
+Enabling requires both the opt-in flag and a trusted module:
+
 ```sh
+projscan plugin trust --all
 PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor
 PROJSCAN_PLUGINS_PREVIEW=1 projscan ci
 PROJSCAN_PLUGINS_PREVIEW=1 projscan analyze

package/docs/PLUGIN-GALLERY.md

@@ -6,10 +6,11 @@ the manifest and module into `.projscan-plugins/`, then run:
 ```bash
 projscan plugin validate .projscan-plugins/<name>.projscan-plugin.json
 projscan plugin test .projscan-plugins/<name>.projscan-plugin.json
+PROJSCAN_PLUGINS_PREVIEW=1 projscan plugin test .projscan-plugins/<name>.projscan-plugin.json --execute
 PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor
 ```
 
-Local plugins are code execution. Only enable plugins you trust. `projscan plugin test --format json` returns `trust`, `commands`, and `context` guidance so agents can validate a plugin, see the preview flag, and detect graph/dataflow context needs before execution.
+Local plugins are code execution. Only enable plugins you trust. `projscan plugin test --format json` is static by default and returns `trust`, `commands`, `execution`, and `context` guidance so agents can validate a plugin, see the preview flag, and detect graph/dataflow context needs before execution.
 
 ## Analyzer Plugins
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Agent-first code intelligence. MCP server (2025-03-26) with AST parsing for JavaScript, TypeScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++; repo understanding maps (projscan_understand), stable v3 semantic graph (projscan_semantic_graph), dataflow risk engine with bridge-helper detection (projscan_dataflow), code graph, file + per-function AST cyclomatic complexity, per-function fan-in + fan-out, coupling + cycle detection, structural PR diff with HTML reporter, coverage report with HTML reporter, intent-grounded one-call PR review (projscan_review with optional `intent` arg, new taint flows, contract changes, and newDataflowRisks) and long-running PR-watch mode with structured per-bucket deltas (projscan_review_watch), first-60-seconds workflow orientation (projscan_start), agent workplans (projscan_workplan), bug-hunt queues (projscan_bug_hunt), product-line planning (projscan_release_train), evidence packs (projscan_evidence_pack), regression planning (projscan_regression_plan), agent briefs (projscan_agent_brief), quality scorecards (projscan_quality_scorecard), and preflight with supply-chain IOC evidence, rule-driven fix suggestions + mechanical apply layer with rollback (projscan_apply_fix, projscan_fix_suggest, projscan_explain_issue), source-to-sink taint analysis (projscan_taint) with truncation reporting, transitive blast-radius analysis with cross-repo mode (projscan_impact for files and symbols), cross-repo workspace registration + intelligence (projscan_workspace_graph), per-function semantic search chunks (sub-file embeddings), per-rule confidence + severity drift + cost-summary analytics with live streaming (projscan_cost_summary), stable local analyzer + reporter plugin API (projscan_plugin, CLI --reporter, opt-in via PROJSCAN_PLUGINS_PREVIEW=1), monorepo workspace awareness with cross-package import policy + per-package dependencies / outdated / audit, BM25 + optional semantic search, cursor pagination, progress notifications, context-budgeted output, and a stable-surface CI guard. CLI on the side.",
   "type": "module",
   "main": "./dist/index.js",
@@ -112,7 +112,7 @@
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.57.0",
     "vite": "^6.4.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   },
   "overrides": {
     "protobufjs": "^7.5.9",