projscan 1.11.0 → 2.0.0

package/docs/PLUGIN-AUTHORING.md

@@ -0,0 +1,209 @@
+# 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.
+
+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.
+
+## Layout
+
+Plugin manifests live under `.projscan-plugins/`:
+
+```text
+.projscan-plugins/
+  policy.projscan-plugin.json
+  policy.mjs
+  team-summary.projscan-plugin.json
+  team-summary.mjs
+```
+
+## Manifest
+
+Analyzer plugins add issues to the normal projscan issue stream:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "policy",
+  "kind": "analyzer",
+  "module": "./policy.mjs",
+  "category": "custom",
+  "description": "Project-specific policy checks"
+}
+```
+
+Reporter plugins render CLI output for selected commands:
+
+```json
+{
+  "schemaVersion": 1,
+  "name": "team-summary",
+  "kind": "reporter",
+  "module": "./team-summary.mjs",
+  "commands": ["doctor", "analyze", "ci"],
+  "description": "Compact team health summary"
+}
+```
+
+Fields:
+
+- `schemaVersion`: must be `1`.
+- `name`: stable plugin identifier. Issue ids are prefixed with `plugin:<name>:`.
+- `kind`: `analyzer` or `reporter`.
+- `module`: relative path inside the plugin directory. Absolute paths and `..` are rejected.
+- `category`: analyzer-only fallback issue category when a plugin issue omits one.
+- `commands`: reporter-only list of CLI commands the reporter supports: `doctor`, `analyze`, `ci`.
+- `description`: optional summary for humans and agents.
+
+## Schema
+
+The machine-readable manifest schema lives at
+[`docs/plugin.schema.json`](plugin.schema.json). The examples under
+[`docs/examples/plugins/`](examples/plugins/) are tested in CI.
+
+## Analyzer Module
+
+The module must export a `check(rootPath, files)` function, either as the
+default export or a named export.
+
+```js
+export default {
+  check: async (rootPath, files) => {
+    return files
+      .filter((file) => file.relativePath.endsWith('.ts'))
+      .filter((file) => file.relativePath.includes('legacy'))
+      .map((file) => ({
+        id: 'legacy-typescript-file',
+        title: 'Legacy TypeScript file',
+        description: `${file.relativePath} is under the legacy tree.`,
+        severity: 'warning',
+        category: 'custom',
+        fixAvailable: false,
+        locations: [{ file: file.relativePath, line: 1 }],
+      }));
+  },
+};
+```
+
+Required issue fields:
+
+- `id`
+- `title`
+- `description`
+- `severity`: `error`, `warning`, or `info`
+- `category`
+- `fixAvailable`
+
+Malformed issues are dropped so one bad plugin cannot poison the issue stream.
+
+## Reporter Module
+
+Reporter plugins are CLI-only. The module must export a
+`render(context)` function, either as the default export or a named export.
+
+```js
+export default {
+  render: async ({ command, payload }) => {
+    if (command === 'ci') {
+      return `CI ${payload.ci.pass ? 'passed' : 'failed'}: ${payload.ci.score}/100`;
+    }
+
+    const issues = payload.issues ?? [];
+    const score = payload.health?.score ?? 'analysis';
+    return `${command}: ${issues.length} issue(s), score ${score}`;
+  },
+};
+```
+
+`context` contains:
+
+- `command`: `doctor`, `analyze`, or `ci`.
+- `rootPath`: absolute project root.
+- `manifest`: the validated reporter manifest.
+- `payload`: the command payload.
+
+Payloads:
+
+- `doctor`: `{ health, issues }`
+- `analyze`: the same `AnalysisReport` shape returned by `--format json`
+- `ci`: `{ ci: { score, grade, pass, threshold, totalIssues, errors, warnings, info, issues } }`
+
+Renderers must return a string. They should not write directly to stdout or
+stderr; projscan writes the returned text after the renderer succeeds.
+
+## Custom Presentation
+
+Reporter plugins are the customization boundary for team-specific presentation.
+Use them for white-label reports, team-branded summaries, and output shaped for
+local workflows. The built-in HTML reporter stays the default core renderer
+instead of growing project-specific theming flags.
+
+## Validate
+
+```sh
+projscan plugin validate .projscan-plugins/policy.projscan-plugin.json
+projscan plugin validate .projscan-plugins/policy.projscan-plugin.json --format json
+```
+
+Validation reports structured diagnostics with a stable `code`, the manifest
+`field` when applicable, a `message`, and sometimes a `hint`.
+
+## List
+
+```sh
+projscan plugin list
+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.
+
+## Enable
+
+```sh
+PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor
+PROJSCAN_PLUGINS_PREVIEW=1 projscan ci
+PROJSCAN_PLUGINS_PREVIEW=1 projscan analyze
+PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-summary
+PROJSCAN_PLUGINS_PREVIEW=1 projscan analyze --reporter team-summary
+PROJSCAN_PLUGINS_PREVIEW=1 projscan ci --reporter team-summary
+```
+
+When enabled, analyzer plugin issues are merged into the same issue stream as
+built-in analyzer issues. That means they affect health scores and CI gates in
+the same way.
+
+Reporter plugins are selected with `--reporter <name>` on supported commands.
+Do not combine `--reporter` with `--format json`, `markdown`, `sarif`, or
+`html`; reporter output is its own stdout text.
+
+## MCP
+
+The `projscan_plugin` MCP tool supports:
+
+- `action: "list"`
+- `action: "validate"` with `manifest_path`
+
+Plugin execution for MCP `projscan_doctor` and `projscan_analyze` follows the
+same `PROJSCAN_PLUGINS_PREVIEW` flag as the CLI.
+
+Reporter rendering is CLI-only. MCP tools continue to return structured
+payloads.
+
+## Failure Isolation
+
+- One plugin failing to load does not stop other plugins.
+- One plugin throwing during `check` does not stop built-in analyzers.
+- Malformed issues are dropped.
+- One reporter failing to load or render exits that CLI command with a
+  diagnostic instead of falling back to a misleading built-in report.
+- Runtime plugin warnings go to stderr so JSON stdout stays parseable.
+
+## Compatibility
+
+This is the stable 2.0 plugin contract for local analyzer and reporter plugins.
+New optional manifest fields may be added in 2.x; existing required fields keep
+their names and types.

package/docs/examples/plugins/policy.mjs

@@ -0,0 +1,16 @@
+export default {
+  check: async (_rootPath, files) => {
+    return files
+      .filter((file) => file.relativePath.endsWith('.ts'))
+      .filter((file) => file.relativePath.includes('legacy'))
+      .map((file) => ({
+        id: 'legacy-typescript-file',
+        title: 'Legacy TypeScript file',
+        description: `${file.relativePath} is under the legacy tree.`,
+        severity: 'warning',
+        category: 'custom',
+        fixAvailable: false,
+        locations: [{ file: file.relativePath, line: 1 }],
+      }));
+  },
+};

package/docs/examples/plugins/policy.projscan-plugin.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "name": "policy",
+  "kind": "analyzer",
+  "module": "./policy.mjs",
+  "category": "custom",
+  "description": "Flags legacy TypeScript files for team review"
+}

package/docs/examples/plugins/team-radar.mjs

@@ -0,0 +1,17 @@
+export default {
+  render: async ({ command, payload }) => {
+    if (command === 'ci') {
+      const ci = payload.ci;
+      return `team-radar ci ${ci.pass ? 'pass' : 'fail'} ${ci.score}/100 ${ci.grade} ${ci.totalIssues} issue(s)`;
+    }
+
+    if (command === 'doctor') {
+      const health = payload.health;
+      const issues = Array.isArray(payload.issues) ? payload.issues.length : 0;
+      return `team-radar doctor ${health.score}/100 ${health.grade} ${issues} issue(s)`;
+    }
+
+    const issues = Array.isArray(payload.issues) ? payload.issues.length : 0;
+    return `team-radar analyze ${issues} issue(s)`;
+  },
+};

package/docs/examples/plugins/team-radar.projscan-plugin.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "name": "team-radar",
+  "kind": "reporter",
+  "module": "./team-radar.mjs",
+  "commands": ["doctor", "analyze", "ci"],
+  "description": "Compact team health summary"
+}

package/docs/plugin.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/abhiyoheswaran1/projscan/blob/main/docs/plugin.schema.json",
+  "title": "projscan plugin manifest",
+  "description": "Manifest schema for local projscan analyzer and reporter plugins.",
+  "oneOf": [
+    {
+      "title": "Analyzer plugin",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "name", "kind", "module", "category"],
+      "properties": {
+        "schemaVersion": {
+          "const": 1
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9._/-]{1,65}$"
+        },
+        "kind": {
+          "const": "analyzer"
+        },
+        "module": {
+          "type": "string",
+          "minLength": 1
+        },
+        "category": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    },
+    {
+      "title": "Reporter plugin",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["schemaVersion", "name", "kind", "module", "commands"],
+      "properties": {
+        "schemaVersion": {
+          "const": 1
+        },
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9._/-]{1,65}$"
+        },
+        "kind": {
+          "const": "reporter"
+        },
+        "module": {
+          "type": "string",
+          "minLength": 1
+        },
+        "commands": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": ["doctor", "analyze", "ci"]
+          },
+          "uniqueItems": true
+        },
+        "description": {
+          "type": "string"
+        }
+      }
+    }
+  ]
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "1.11.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++; 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) and long-running PR-watch mode with structured per-bucket deltas (projscan_review_watch), 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), analyzer + reporter plugin API preview (projscan_plugin, CLI --reporter, gated by 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.",
+  "version": "2.0.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++; 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) and long-running PR-watch mode with structured per-bucket deltas (projscan_review_watch), 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",
   "types": "./dist/index.d.ts",
@@ -11,7 +11,11 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "docs/2.0-MIGRATION.md",
+    "docs/PLUGIN-AUTHORING.md",
+    "docs/plugin.schema.json",
+    "docs/examples/plugins"
   ],
   "scripts": {
     "build": "tsc && node scripts/copy-wasm.mjs && node scripts/generate-tool-manifest.mjs",