projscan 1.10.0 → 2.0.0

package/dist/reporters/jsonReporter.js

@@ -1,10 +1,15 @@
 import { calculateScore } from '../utils/scoreCalculator.js';
+export const CLI_JSON_SCHEMA_VERSION = 2;
+function emitJson(payload) {
+    console.log(JSON.stringify({ schemaVersion: CLI_JSON_SCHEMA_VERSION, ...payload }, null, 2));
+}
 export function reportAnalysisJson(report) {
-    console.log(JSON.stringify(report, null, 2));
+    emitJson(report);
 }
 export function reportHealthJson(issues) {
     const { score, grade, errors, warnings, infos } = calculateScore(issues);
     console.log(JSON.stringify({
+        schemaVersion: CLI_JSON_SCHEMA_VERSION,
         health: {
             score,
             grade,
@@ -19,6 +24,7 @@ export function reportHealthJson(issues) {
 export function reportCiJson(issues, threshold) {
     const { score, grade, errors, warnings, infos } = calculateScore(issues);
     console.log(JSON.stringify({
+        schemaVersion: CLI_JSON_SCHEMA_VERSION,
         ci: {
             score,
             grade,
@@ -33,57 +39,57 @@ export function reportCiJson(issues, threshold) {
     }, null, 2));
 }
 export function reportDiffJson(diff) {
-    console.log(JSON.stringify({ diff }, null, 2));
+    emitJson({ diff });
 }
 export function reportExplanationJson(explanation) {
-    console.log(JSON.stringify(explanation, null, 2));
+    emitJson(explanation);
 }
 export function reportDiagramJson(layers) {
-    console.log(JSON.stringify({ architecture: layers }, null, 2));
+    emitJson({ architecture: layers });
 }
 export function reportStructureJson(tree) {
-    console.log(JSON.stringify({ structure: tree }, null, 2));
+    emitJson({ structure: tree });
 }
 export function reportDependenciesJson(report) {
-    console.log(JSON.stringify(report, null, 2));
+    emitJson(report);
 }
 export function reportHotspotsJson(report) {
-    console.log(JSON.stringify({ hotspots: report }, null, 2));
+    emitJson({ hotspots: report });
 }
 export function reportFileJson(inspection) {
-    console.log(JSON.stringify({ file: inspection }, null, 2));
+    emitJson({ file: inspection });
 }
 export function reportOutdatedJson(report) {
-    console.log(JSON.stringify({ outdated: report }, null, 2));
+    emitJson({ outdated: report });
 }
 export function reportAuditJson(report) {
-    console.log(JSON.stringify({ audit: report }, null, 2));
+    emitJson({ audit: report });
 }
 export function reportUpgradeJson(preview) {
-    console.log(JSON.stringify({ upgrade: preview }, null, 2));
+    emitJson({ upgrade: preview });
 }
 export function reportCoverageJson(report) {
-    console.log(JSON.stringify({ coverage: report }, null, 2));
+    emitJson({ coverage: report });
 }
 export function reportCouplingJson(report) {
-    console.log(JSON.stringify({ coupling: report }, null, 2));
+    emitJson({ coupling: report });
 }
 export function reportPrDiffJson(report) {
-    console.log(JSON.stringify({ prDiff: report }, null, 2));
+    emitJson({ prDiff: report });
 }
 export function reportReviewJson(report) {
-    console.log(JSON.stringify({ review: report }, null, 2));
+    emitJson({ review: report });
 }
 export function reportFixSuggestJson(result) {
-    console.log(JSON.stringify({ fixSuggest: result }, null, 2));
+    emitJson({ fixSuggest: result });
 }
 export function reportExplainIssueJson(explanation) {
-    console.log(JSON.stringify({ issueExplanation: explanation }, null, 2));
+    emitJson({ issueExplanation: explanation });
 }
 export function reportImpactJson(report) {
-    console.log(JSON.stringify({ impact: report }, null, 2));
+    emitJson({ impact: report });
 }
 export function reportWorkspacesJson(info) {
-    console.log(JSON.stringify({ workspaces: info }, null, 2));
+    emitJson({ workspaces: info });
 }
 //# sourceMappingURL=jsonReporter.js.map

package/dist/reporters/jsonReporter.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsonReporter.js","sourceRoot":"","sources":["../../src/reporters/jsonReporter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"jsonReporter.js","sourceRoot":"","sources":["../../src/reporters/jsonReporter.ts"],"names":[],"mappings":"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"}

package/dist/tool-manifest.json

@@ -1,8 +1,8 @@
 {
   "name": "projscan",
-  "version": "1.10.0",
+  "version": "2.0.0",
   "mcpProtocolVersion": "2025-03-26",
-  "generatedAt": "2026-05-12T21:51:14.985Z",
+  "generatedAt": "2026-05-18T11:46:44.815Z",
   "toolCount": 28,
   "tools": [
     {
@@ -714,7 +714,7 @@
     },
     {
       "name": "projscan_plugin",
-      "description": "1.10+ preview. Discover and validate third-party analyzer plugins under .projscan-plugins/. Gated by the PROJSCAN_PLUGINS_PREVIEW=1 env flag; the schema is preview-only and may shift before 2.0. Use action:\"list\" to see what is discoverable today, action:\"validate\" to check a manifest before committing it.",
+      "description": "Discover and validate stable local analyzer and reporter plugins under .projscan-plugins/. Execution is opt-in via the PROJSCAN_PLUGINS_PREVIEW=1 env flag because plugins are local code. Use action:\"list\" to see what is discoverable today, action:\"validate\" to check a manifest before committing it.",
       "inputSchema": {
         "type": "object",
         "properties": {
@@ -724,7 +724,7 @@
               "list",
               "validate"
             ],
-            "description": "\"list\" enumerates manifests under <root>/.projscan-plugins/ with discovery status. \"validate\" lints a manifest at the given path against the 1.10 schema."
+            "description": "\"list\" enumerates manifests under <root>/.projscan-plugins/ with discovery status. \"validate\" lints a manifest at the given path against schema v1."
           },
           "manifest_path": {
             "type": "string",

package/docs/2.0-MIGRATION.md

@@ -0,0 +1,80 @@
+# Migrating to projscan 2.0
+
+projscan 2.0 stabilizes the local plugin platform and uses the major version
+boundary to clean up deferred 1.x surfaces. MCP tool names and input schemas
+remain stable; the intentional changes are concentrated in CLI JSON metadata,
+the npm TypeScript API, and plugin contract documentation.
+
+## Breaking Changes
+
+### CLI JSON has `schemaVersion: 2`
+
+Every built-in CLI JSON reporter now includes `schemaVersion: 2` at the top
+level. Existing command data keys remain present, so most consumers can migrate
+by ignoring the new field or branching on it.
+
+Before:
+
+```json
+{
+  "health": {
+    "score": 100
+  }
+}
+```
+
+After:
+
+```json
+{
+  "schemaVersion": 2,
+  "health": {
+    "score": 100
+  }
+}
+```
+
+### Deprecated regex extractors are removed
+
+The deprecated `extractImports` and `extractExports` helpers are removed from
+the npm public API. They were JS/TS-only regex helpers and could not represent
+the multi-language AST graph accurately.
+
+Use one of these instead:
+
+- `buildCodeGraph(rootPath, files)` for full graph construction.
+- `importsOf(graph, file)` for imports from one file.
+- `exportsOf(graph, file)` for exports from one file.
+- `inspectFile(rootPath, file)` for a user-facing file explanation.
+
+### Language ids are extensible
+
+Built-in language ids remain documented, but `LanguageId` is no longer a closed
+union. Consumers that need only built-ins should use `BuiltinLanguageId`.
+Consumers that accept plugin-provided languages should use `LanguageId`.
+
+## Plugin Contract
+
+Plugin manifests use `schemaVersion: 1` in 2.0. Analyzer plugins export
+`check(rootPath, files)`. Reporter plugins export `render(context)`.
+
+The stable manifest fields are:
+
+- `schemaVersion`
+- `name`
+- `kind`
+- `module`
+- analyzer-only `category`
+- reporter-only `commands`
+- optional `description`
+
+Plugin execution stays local. projscan does not fetch remote plugin code.
+
+## Compatibility Notes
+
+MCP tool names and input schemas remain stable. The major-version changes are
+limited to documented CLI JSON metadata, npm TypeScript API cleanup, and plugin
+contract stabilization.
+
+During migration, prefer MCP tools or CLI JSON over console output. Console
+format remains human-facing and may change visually between releases.

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.10.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 plugin API preview (projscan_plugin, 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",