projscan 3.3.0 → 3.4.1

package/dist/projscan-sbom.cdx.json

@@ -1,23 +1,23 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:e3d87bac-ad5b-4956-b8f3-d5277b890895",
+  "serialNumber": "urn:uuid:1a06c2ae-75e9-447d-a9d2-6ac19421312e",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-03T16:23:49.757Z",
+    "timestamp": "2026-06-04T06:12:24.527Z",
     "tools": [
       {
         "vendor": "projscan",
         "name": "projscan-sbom-generator",
-        "version": "3.3.0"
+        "version": "3.4.1"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/projscan@3.3.0",
+      "bom-ref": "pkg:npm/projscan@3.4.1",
       "name": "projscan",
-      "version": "3.3.0",
-      "purl": "pkg:npm/projscan@3.3.0"
+      "version": "3.4.1",
+      "purl": "pkg:npm/projscan@3.4.1"
     }
   },
   "components": [
@@ -1183,6 +1183,20 @@
         }
       ]
     },
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/%40standard-schema/spec@1.1.0",
+      "name": "@standard-schema/spec",
+      "version": "1.1.0",
+      "purl": "pkg:npm/%40standard-schema/spec@1.1.0",
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/%40types/chai@5.2.3",
@@ -1409,10 +1423,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40vitest/expect@3.2.4",
+      "bom-ref": "pkg:npm/%40vitest/expect@4.1.8",
       "name": "@vitest/expect",
-      "version": "3.2.4",
-      "purl": "pkg:npm/%40vitest/expect@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/%40vitest/expect@4.1.8",
       "licenses": [
         {
           "license": {
@@ -1423,10 +1437,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40vitest/mocker@3.2.4",
+      "bom-ref": "pkg:npm/%40vitest/mocker@4.1.8",
       "name": "@vitest/mocker",
-      "version": "3.2.4",
-      "purl": "pkg:npm/%40vitest/mocker@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/%40vitest/mocker@4.1.8",
       "licenses": [
         {
           "license": {
@@ -1437,10 +1451,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40vitest/pretty-format@3.2.4",
+      "bom-ref": "pkg:npm/%40vitest/pretty-format@4.1.8",
       "name": "@vitest/pretty-format",
-      "version": "3.2.4",
-      "purl": "pkg:npm/%40vitest/pretty-format@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/%40vitest/pretty-format@4.1.8",
       "licenses": [
         {
           "license": {
@@ -1451,10 +1465,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40vitest/runner@3.2.4",
+      "bom-ref": "pkg:npm/%40vitest/runner@4.1.8",
       "name": "@vitest/runner",
-      "version": "3.2.4",
-      "purl": "pkg:npm/%40vitest/runner@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/%40vitest/runner@4.1.8",
       "licenses": [
         {
           "license": {
@@ -1465,10 +1479,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40vitest/snapshot@3.2.4",
+      "bom-ref": "pkg:npm/%40vitest/snapshot@4.1.8",
       "name": "@vitest/snapshot",
-      "version": "3.2.4",
-      "purl": "pkg:npm/%40vitest/snapshot@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/%40vitest/snapshot@4.1.8",
       "licenses": [
         {
           "license": {
@@ -1479,10 +1493,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40vitest/spy@3.2.4",
+      "bom-ref": "pkg:npm/%40vitest/spy@4.1.8",
       "name": "@vitest/spy",
-      "version": "3.2.4",
-      "purl": "pkg:npm/%40vitest/spy@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/%40vitest/spy@4.1.8",
       "licenses": [
         {
           "license": {
@@ -1493,10 +1507,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/%40vitest/utils@3.2.4",
+      "bom-ref": "pkg:npm/%40vitest/utils@4.1.8",
       "name": "@vitest/utils",
-      "version": "3.2.4",
-      "purl": "pkg:npm/%40vitest/utils@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/%40vitest/utils@4.1.8",
       "licenses": [
         {
           "license": {
@@ -1773,24 +1787,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/cac@6.7.14",
-      "name": "cac",
-      "version": "6.7.14",
-      "purl": "pkg:npm/cac@6.7.14",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/chai@5.3.3",
+      "bom-ref": "pkg:npm/chai@6.2.2",
       "name": "chai",
-      "version": "5.3.3",
-      "purl": "pkg:npm/chai@5.3.3",
+      "version": "6.2.2",
+      "purl": "pkg:npm/chai@6.2.2",
       "licenses": [
         {
           "license": {
@@ -1813,20 +1813,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/check-error@2.1.3",
-      "name": "check-error",
-      "version": "2.1.3",
-      "purl": "pkg:npm/check-error@2.1.3",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/chownr@1.1.4",
@@ -1939,6 +1925,20 @@
         }
       ]
     },
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/convert-source-map@2.0.0",
+      "name": "convert-source-map",
+      "version": "2.0.0",
+      "purl": "pkg:npm/convert-source-map@2.0.0",
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/cross-spawn@7.0.6",
@@ -1981,20 +1981,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/deep-eql@5.0.2",
-      "name": "deep-eql",
-      "version": "5.0.2",
-      "purl": "pkg:npm/deep-eql@5.0.2",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/deep-extend@0.6.0",
@@ -2067,10 +2053,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/es-module-lexer@1.7.0",
+      "bom-ref": "pkg:npm/es-module-lexer@2.1.0",
       "name": "es-module-lexer",
-      "version": "1.7.0",
-      "purl": "pkg:npm/es-module-lexer@1.7.0",
+      "version": "2.1.0",
+      "purl": "pkg:npm/es-module-lexer@2.1.0",
       "licenses": [
         {
           "license": {
@@ -2765,20 +2751,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/js-tokens@9.0.1",
-      "name": "js-tokens",
-      "version": "9.0.1",
-      "purl": "pkg:npm/js-tokens@9.0.1",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/json-buffer@3.0.1",
@@ -2905,20 +2877,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/loupe@3.2.1",
-      "name": "loupe",
-      "version": "3.2.1",
-      "purl": "pkg:npm/loupe@3.2.1",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/magic-string@0.30.21",
@@ -3283,6 +3241,20 @@
         }
       ]
     },
+    {
+      "type": "library",
+      "bom-ref": "pkg:npm/obug@2.1.1",
+      "name": "obug",
+      "version": "2.1.1",
+      "purl": "pkg:npm/obug@2.1.1",
+      "licenses": [
+        {
+          "license": {
+            "id": "MIT"
+          }
+        }
+      ]
+    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/once@1.4.0",
@@ -3465,20 +3437,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/pathval@2.0.1",
-      "name": "pathval",
-      "version": "2.0.1",
-      "purl": "pkg:npm/pathval@2.0.1",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/picocolors@1.1.1",
@@ -3873,10 +3831,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/std-env@3.10.0",
+      "bom-ref": "pkg:npm/std-env@4.1.0",
       "name": "std-env",
-      "version": "3.10.0",
-      "purl": "pkg:npm/std-env@3.10.0",
+      "version": "4.1.0",
+      "purl": "pkg:npm/std-env@4.1.0",
       "licenses": [
         {
           "license": {
@@ -3969,20 +3927,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/strip-literal@3.1.0",
-      "name": "strip-literal",
-      "version": "3.1.0",
-      "purl": "pkg:npm/strip-literal@3.1.0",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/tar-fs@2.1.4",
@@ -4083,10 +4027,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/tinyexec@0.3.2",
+      "bom-ref": "pkg:npm/tinyexec@1.2.4",
       "name": "tinyexec",
-      "version": "0.3.2",
-      "purl": "pkg:npm/tinyexec@0.3.2",
+      "version": "1.2.4",
+      "purl": "pkg:npm/tinyexec@1.2.4",
       "licenses": [
         {
           "license": {
@@ -4111,38 +4055,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/tinypool@1.1.1",
-      "name": "tinypool",
-      "version": "1.1.1",
-      "purl": "pkg:npm/tinypool@1.1.1",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/tinyrainbow@2.0.0",
+      "bom-ref": "pkg:npm/tinyrainbow@3.1.0",
       "name": "tinyrainbow",
-      "version": "2.0.0",
-      "purl": "pkg:npm/tinyrainbow@2.0.0",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/tinyspy@4.0.4",
-      "name": "tinyspy",
-      "version": "4.0.4",
-      "purl": "pkg:npm/tinyspy@4.0.4",
+      "version": "3.1.0",
+      "purl": "pkg:npm/tinyrainbow@3.1.0",
       "licenses": [
         {
           "license": {
@@ -4459,20 +4375,6 @@
         }
       ]
     },
-    {
-      "type": "library",
-      "bom-ref": "pkg:npm/vite-node@3.2.4",
-      "name": "vite-node",
-      "version": "3.2.4",
-      "purl": "pkg:npm/vite-node@3.2.4",
-      "licenses": [
-        {
-          "license": {
-            "id": "MIT"
-          }
-        }
-      ]
-    },
     {
       "type": "library",
       "bom-ref": "pkg:npm/vite@6.4.2",
@@ -4489,10 +4391,10 @@
     },
     {
       "type": "library",
-      "bom-ref": "pkg:npm/vitest@3.2.4",
+      "bom-ref": "pkg:npm/vitest@4.1.8",
       "name": "vitest",
-      "version": "3.2.4",
-      "purl": "pkg:npm/vitest@3.2.4",
+      "version": "4.1.8",
+      "purl": "pkg:npm/vitest@4.1.8",
       "licenses": [
         {
           "license": {

package/dist/tool-manifest.json

@@ -1,9 +1,9 @@
 {
   "name": "projscan",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "mcpProtocolVersion": "2025-03-26",
-  "generatedAt": "2026-06-03T16:23:55.468Z",
-  "toolCount": 40,
+  "generatedAt": "2026-06-04T06:12:30.232Z",
+  "toolCount": 41,
   "tools": [
     {
       "name": "projscan_analyze",
@@ -792,7 +792,7 @@
           },
           "manifest_path": {
             "type": "string",
-            "description": "\"validate\" only — repo-relative or absolute path to a *.projscan-plugin.json file."
+            "description": "\"validate\" only — repo-relative path under .projscan-plugins/ to a *.projscan-plugin.json file."
           }
         }
       }
@@ -864,7 +864,7 @@
           },
           "enable_plugins": {
             "type": "boolean",
-            "description": "Enable local analyzer plugins for this run, equivalent to PROJSCAN_PLUGINS_PREVIEW=1."
+            "description": "Request local analyzer plugin evidence only when this MCP server process already has PROJSCAN_PLUGINS_PREVIEW=1. This argument never enables plugin execution by itself."
           },
           "max_tokens": {
             "type": "number",
@@ -1088,6 +1088,38 @@
           }
         }
       }
+    },
+    {
+      "name": "projscan_understand",
+      "description": "Explain repo map, runtime flows, public contracts, change readiness, and verification proof with cited file/symbol evidence.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "view": {
+            "type": "string",
+            "enum": [
+              "map",
+              "flow",
+              "contracts",
+              "change",
+              "verify"
+            ],
+            "description": "Understand view. Default: map."
+          },
+          "intent": {
+            "type": "string",
+            "description": "Planned change or question for change-readiness output."
+          },
+          "max_items": {
+            "type": "number",
+            "description": "Maximum items per section. Default: 8, max: 30."
+          },
+          "max_tokens": {
+            "type": "number",
+            "description": "Cap the response to roughly this many tokens."
+          }
+        }
+      }
     }
   ]
 }

package/dist/types.d.ts

@@ -966,6 +966,158 @@ export interface QualityScorecardReport {
     suggestedNextActions: PreflightSuggestedAction[];
     truncated?: boolean;
 }
+export type UnderstandView = 'map' | 'flow' | 'contracts' | 'change' | 'verify';
+export interface UnderstandCitation {
+    file: string;
+    symbol?: string;
+    line?: number;
+    reason: string;
+}
+export interface UnderstandClaim {
+    id: string;
+    title: string;
+    detail: string;
+    confidence: 'low' | 'medium' | 'high';
+    citations: UnderstandCitation[];
+}
+export interface UnderstandEntrypoint {
+    file: string;
+    kind: 'cli' | 'server' | 'route' | 'package-export' | 'test' | 'script' | 'module';
+    symbols: string[];
+    why: string;
+    citations: UnderstandCitation[];
+}
+export interface UnderstandBoundary {
+    name: string;
+    files: number;
+    publicExports: string[];
+    dependsOn: string[];
+    citations: UnderstandCitation[];
+}
+export interface UnderstandFlowSideEffect {
+    kind: 'database' | 'filesystem' | 'network' | 'process' | 'env' | 'unknown';
+    label: string;
+    files: string[];
+    citations: UnderstandCitation[];
+}
+export interface UnderstandFlow {
+    id: string;
+    label: string;
+    entry: UnderstandEntrypoint;
+    path: string[];
+    sideEffects: UnderstandFlowSideEffect[];
+    confidence: 'low' | 'medium' | 'high';
+    citations: UnderstandCitation[];
+}
+export interface UnderstandPublicExport {
+    name: string;
+    file: string;
+    kind: 'package' | 'symbol';
+    citations: UnderstandCitation[];
+}
+export interface UnderstandConfigContract {
+    name: string;
+    file: string;
+    kind: 'env' | 'package-script' | 'config-file';
+    required: boolean;
+    citations: UnderstandCitation[];
+}
+export interface UnderstandBreakingChangeRisk {
+    id: string;
+    title: string;
+    files: string[];
+    why: string;
+    command: string;
+}
+export interface UnderstandContracts {
+    publicExports: UnderstandPublicExport[];
+    configContracts: UnderstandConfigContract[];
+    breakingChangeRisks: UnderstandBreakingChangeRisk[];
+}
+export interface UnderstandChangeReadiness {
+    intent: string;
+    blastRadius: Array<{
+        label: string;
+        files: string[];
+        why: string;
+        command: string;
+    }>;
+    safeEdit: {
+        title: string;
+        files: string[];
+        command: string;
+        why: string;
+    };
+    owners: Array<{
+        owner: string;
+        files: string[];
+        reason: string;
+    }>;
+    rollback: {
+        command: string;
+        why: string;
+    };
+    verificationCommands: string[];
+}
+export interface UnderstandVerificationTier {
+    id: 'minimal' | 'focused' | 'full';
+    label: string;
+    commands: string[];
+    when: string;
+}
+export interface UnderstandDirectTest {
+    file: string;
+    tests: string[];
+    confidence: 'none' | 'low' | 'medium' | 'high';
+}
+export interface UnderstandVerification {
+    tiers: UnderstandVerificationTier[];
+    directTests: UnderstandDirectTest[];
+    gaps: Array<{
+        file: string;
+        reason: string;
+        command: string;
+    }>;
+}
+export interface UnderstandReadFirst {
+    file: string;
+    why: string;
+    command: string;
+    citations: UnderstandCitation[];
+}
+export interface UnderstandRisk {
+    id: string;
+    priority: WorkplanPriority;
+    title: string;
+    files: string[];
+    why: string;
+    command: string;
+}
+export interface UnderstandUnknown {
+    id: string;
+    question: string;
+    whyUnknown: string;
+    command: string;
+}
+export interface UnderstandReport {
+    schemaVersion: 1;
+    view: UnderstandView;
+    rootPath: string;
+    intent?: string;
+    summary: string;
+    claims: UnderstandClaim[];
+    entrypoints: UnderstandEntrypoint[];
+    boundaries: UnderstandBoundary[];
+    flows: UnderstandFlow[];
+    contracts: UnderstandContracts;
+    changeReadiness: UnderstandChangeReadiness;
+    verification: UnderstandVerification;
+    readFirst: UnderstandReadFirst[];
+    risks: UnderstandRisk[];
+    unknowns: UnderstandUnknown[];
+    commands: string[];
+    truncated?: boolean;
+}
 export interface SessionCoordinationHint {
     id: 'current-worktree-check' | 'remembered-session-context' | 'resolve-conflicts';
     label: string;
@@ -1023,8 +1175,15 @@ export interface PluginTestResult {
     commands: {
         validate: string;
         test: string;
+        execute: string;
         enable: string;
     };
+    execution: {
+        requested: boolean;
+        executed: boolean;
+        mode: 'static' | 'execute';
+        note: string;
+    };
     context: {
         requested: boolean;
         capabilities: Array<'semanticGraph' | 'dataflow'>;