pruneguard 0.3.1 → 0.4.0

package/configuration_schema.json

@@ -21,7 +21,10 @@
         "cycles": "warn",
         "boundaries": "warn",
         "ownership": "warn",
-        "impact": "warn"
+        "impact": "warn",
+        "unusedMembers": "warn",
+        "duplicateExports": "warn",
+        "ignoreExportsUsedInFile": false
       },
       "allOf": [
         {
@@ -34,7 +37,8 @@
       "default": {
         "auto": true,
         "includeTests": false,
-        "includeStories": false
+        "includeStories": false,
+        "includeEntryExports": false
       },
       "allOf": [
         {
@@ -63,6 +67,13 @@
         }
       ]
     },
+    "ignoreIssues": {
+      "description": "Suppress specific finding kinds from the report.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/IgnoreIssueRule"
+      }
+    },
     "ignorePatterns": {
       "description": "Glob patterns for files to ignore entirely.",
       "type": "array",
@@ -92,7 +103,18 @@
       "description": "Module resolver configuration.",
       "default": {
         "respectExports": true,
-        "preserveSymlinks": false
+        "preserveSymlinks": false,
+        "detectRequireResolve": true,
+        "detectImportMetaResolve": true,
+        "detectImportMetaGlob": true,
+        "detectRequireContext": true,
+        "detectUrlConstructor": true,
+        "detectJsdocImports": true,
+        "detectTripleSlash": true,
+        "detectImportEquals": true,
+        "detectTypeImports": true,
+        "detectWebpackAliases": true,
+        "detectBabelAliases": true
       },
       "allOf": [
         {
@@ -143,6 +165,20 @@
             }
           ]
         },
+        "duplicateExports": {
+          "description": "Report duplicate exports (same symbol re-exported from multiple paths).",
+          "default": "warn",
+          "allOf": [
+            {
+              "$ref": "#/definitions/AnalysisSeverity"
+            }
+          ]
+        },
+        "ignoreExportsUsedInFile": {
+          "description": "When true, exports consumed only within the same file are still reported as unused.",
+          "default": false,
+          "type": "boolean"
+        },
         "impact": {
           "default": "warn",
           "allOf": [
@@ -183,6 +219,15 @@
             }
           ]
         },
+        "unusedMembers": {
+          "description": "Report unused exported class/enum members (methods, properties, variants).",
+          "default": "warn",
+          "allOf": [
+            {
+              "$ref": "#/definitions/AnalysisSeverity"
+            }
+          ]
+        },
         "unusedPackages": {
           "default": "warn",
           "allOf": [
@@ -225,6 +270,11 @@
             "type": "string"
           }
         },
+        "includeEntryExports": {
+          "description": "When true, runtime entrypoint exports are eligible to be reported as unused.  By default (`false`), only public-API entrypoint exports are checked.",
+          "default": false,
+          "type": "boolean"
+        },
         "includeStories": {
           "description": "Whether to include story files as entrypoints.",
           "default": false,
@@ -421,6 +471,68 @@
         }
       }
     },
+    "IgnoreIssueRule": {
+      "description": "Rule for suppressing specific finding kinds.",
+      "type": "object",
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "codes": {
+          "description": "Additional finding codes to match (beyond the primary `kind`).",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "comment": {
+          "description": "Optional comment explaining why this is suppressed.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "files": {
+          "description": "Optional glob patterns — only suppress in matching files.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "kind": {
+          "description": "The finding kind to suppress (e.g. \"unusedExport\", \"unusedFile\", \"cycle\").",
+          "type": "string"
+        },
+        "packages": {
+          "description": "Package names to scope this rule to.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "parentSymbols": {
+          "description": "Parent symbol names to scope this rule to.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "symbols": {
+          "description": "Symbol names to scope this rule to.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "workspaces": {
+          "description": "Workspace names to scope this rule to.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
     "OverrideConfig": {
       "type": "object",
       "properties": {
@@ -554,6 +666,61 @@
             "type": "string"
           }
         },
+        "detectBabelAliases": {
+          "description": "Whether to detect Babel alias patterns.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectImportEquals": {
+          "description": "Whether to detect TypeScript `import =` statements.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectImportMetaGlob": {
+          "description": "Whether to detect `import.meta.glob()` calls.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectImportMetaResolve": {
+          "description": "Whether to detect `import.meta.resolve()` calls.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectJsdocImports": {
+          "description": "Whether to detect JSDoc `@import` tags.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectRequireContext": {
+          "description": "Whether to detect `require.context()` calls.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectRequireResolve": {
+          "description": "Whether to detect `require.resolve()` calls.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectTripleSlash": {
+          "description": "Whether to detect triple-slash reference directives.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectTypeImports": {
+          "description": "Whether to detect type-only imports.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectUrlConstructor": {
+          "description": "Whether to detect `new URL()` constructor patterns.",
+          "default": true,
+          "type": "boolean"
+        },
+        "detectWebpackAliases": {
+          "description": "Whether to detect webpack alias patterns.",
+          "default": true,
+          "type": "boolean"
+        },
         "extensions": {
           "description": "File extensions to resolve.",
           "type": "array",

package/daemon_status_report_schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "DaemonStatusReport",
+  "description": "Daemon status report for querying daemon health from JS or CLI.",
+  "type": "object",
+  "required": [
+    "running"
+  ],
+  "properties": {
+    "binaryPath": {
+      "description": "Absolute path to the daemon binary.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "configChangePending": {
+      "description": "Whether a config-level change is pending that requires full rebuild.",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "generation": {
+      "description": "Current generation (rebuild counter) of the index.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "graphEdges": {
+      "description": "Number of edges in the module graph.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint",
+      "minimum": 0.0
+    },
+    "graphNodes": {
+      "description": "Number of nodes in the module graph.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint",
+      "minimum": 0.0
+    },
+    "incrementalRebuilds": {
+      "description": "Number of incremental rebuilds since daemon start.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "indexWarm": {
+      "description": "Whether the hot index has been warmed (initial build complete).",
+      "type": [
+        "boolean",
+        "null"
+      ]
+    },
+    "initialBuildMs": {
+      "description": "Milliseconds the initial graph build took.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "lastRebuildMs": {
+      "description": "Milliseconds the last incremental rebuild took.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "lastUpdateMs": {
+      "description": "Milliseconds since the last graph update.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "pendingInvalidations": {
+      "description": "Number of files pending invalidation.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint",
+      "minimum": 0.0
+    },
+    "pid": {
+      "description": "Process ID of the running daemon, if any.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint32",
+      "minimum": 0.0
+    },
+    "port": {
+      "description": "TCP port the daemon is listening on, if any.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint16",
+      "minimum": 0.0
+    },
+    "projectRoot": {
+      "description": "Absolute path to the project root the daemon is serving.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "running": {
+      "description": "Whether a daemon process is currently running.",
+      "type": "boolean"
+    },
+    "startedAt": {
+      "description": "ISO-8601 timestamp when the daemon started.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "totalInvalidations": {
+      "description": "Total number of files invalidated since daemon start.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "uptimeSecs": {
+      "description": "Uptime of the daemon in seconds.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    },
+    "version": {
+      "description": "Version of the running daemon binary.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "watchedFiles": {
+      "description": "Number of files being watched for changes.",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint",
+      "minimum": 0.0
+    },
+    "watcherLagMs": {
+      "description": "Milliseconds of watcher lag (time since last fs event was processed).",
+      "type": [
+        "integer",
+        "null"
+      ],
+      "format": "uint64",
+      "minimum": 0.0
+    }
+  }
+}

package/dist/index.d.mts

@@ -126,6 +126,8 @@ type AnalysisReport = {
     ruleName?: string;
     primaryActionKind?: string;
     actionKinds?: string[];
+    trustNotes?: string[];
+    frameworkContext?: string[];
   }>;
   entrypoints: Array<{
     path: string;
@@ -133,6 +135,9 @@ type AnalysisReport = {
     profile: string;
     workspace?: string;
     source: string;
+    framework?: string;
+    reason?: string;
+    heuristic?: boolean;
   }>;
   stats: {
     durationMs: number;
@@ -147,6 +152,7 @@ type AnalysisReport = {
       tsconfigPathMiss: number;
       exportsConditionMiss: number;
       externalized: number;
+      workspaceExportsMiss: number;
     };
     resolvedViaExports: number;
     entrypointsDetected: number;
@@ -177,6 +183,16 @@ type AnalysisReport = {
     cacheEntriesRead: number;
     cacheEntriesWritten: number;
     affectedScopeIncomplete: boolean;
+    frameworksDetected: string[];
+    heuristicFrameworks: string[];
+    heuristicEntrypoints: number;
+    compatibilityWarnings: string[];
+    strictTrustApplied: boolean;
+    frameworkConfidenceCounts: {
+      exact: number;
+      heuristic: number;
+      unsupported: number;
+    };
     executionMode?: "oneshot" | "daemon";
     indexWarm?: boolean;
     indexAgeMs?: number;
@@ -223,6 +239,7 @@ type ReviewOptions = {
   baseRef?: string;
   noCache?: boolean;
   noBaseline?: boolean;
+  strictTrust?: boolean;
 };
 type ReviewReport = {
   baseRef?: string;
@@ -239,6 +256,7 @@ type ReviewReport = {
       medium: number;
       low: number;
     };
+    executionMode?: "oneshot" | "daemon";
   };
   recommendations: string[];
   proposedActions?: Array<{
@@ -256,6 +274,15 @@ type ReviewReport = {
     risk: "low" | "medium" | "high";
     confidence: "high" | "medium" | "low";
   }>;
+  compatibilityWarnings?: string[];
+  strictTrustApplied?: boolean;
+  recommendedActions?: Array<{
+    kind: string;
+    description: string;
+    priority: number;
+    command?: string;
+    targets?: string[];
+  }>;
   executionMode?: "oneshot" | "daemon";
   latencyMs?: number;
 };
@@ -270,20 +297,45 @@ type SafeDeleteReport = {
   targets: string[];
   safe: Array<{
     target: string;
+    classification: "safe" | "needs-review" | "blocked";
     confidence?: "high" | "medium" | "low";
     reasons: string[];
+    evidence: Array<{
+      kind: string;
+      file?: string;
+      line?: number;
+      description: string;
+    }>;
   }>;
   needsReview: Array<{
     target: string;
+    classification: "safe" | "needs-review" | "blocked";
     confidence?: "high" | "medium" | "low";
     reasons: string[];
+    evidence: Array<{
+      kind: string;
+      file?: string;
+      line?: number;
+      description: string;
+    }>;
   }>;
   blocked: Array<{
     target: string;
+    classification: "safe" | "needs-review" | "blocked";
     confidence?: "high" | "medium" | "low";
     reasons: string[];
+    evidence: Array<{
+      kind: string;
+      file?: string;
+      line?: number;
+      description: string;
+    }>;
+  }>;
+  deletionOrder: Array<{
+    target: string;
+    step: number;
+    reason?: string;
   }>;
-  deletionOrder: string[];
   evidence: Array<{
     kind: string;
     file?: string;
@@ -312,26 +364,41 @@ type SuggestRulesReport = {
     configFragment: Record<string, unknown>;
     confidence: "high" | "medium" | "low";
     evidence?: string[];
+    rationale?: string;
   }>;
   tags?: Array<{
     name: string;
     glob: string;
     rationale: string;
+    source?: string;
   }>;
   ownershipHints?: Array<{
     pathGlob: string;
     suggestedOwner: string;
     crossTeamEdges: number;
     rationale: string;
+    touchedPackages?: string[];
   }>;
   hotspots?: Array<{
     file: string;
+    workspace?: string;
+    package?: string;
     crossPackageImports: number;
     crossOwnerImports: number;
     incomingEdges: number;
     outgoingEdges: number;
+    rank: number;
+    teamsInvolved?: string[];
     suggestion: string;
   }>;
+  governanceActions?: Array<{
+    priority: number;
+    kind: string;
+    description: string;
+    effort: "low" | "medium" | "high";
+    impact: "low" | "medium" | "high";
+    configFragment?: Record<string, unknown>;
+  }>;
   rationale?: string[];
 };
 type FixPlanReport = {
@@ -351,11 +418,22 @@ type FixPlanReport = {
     verification: string[];
     risk: "low" | "medium" | "high";
     confidence: "high" | "medium" | "low";
+    rank?: number;
+    phase?: string;
+    findingIds: string[];
   }>;
   blockedBy: string[];
   verificationSteps: string[];
   riskLevel: "low" | "medium" | "high";
   confidence: "high" | "medium" | "low";
+  totalActions: number;
+  highConfidenceActions: number;
+  phaseSummary: Array<{
+    name: string;
+    order: number;
+    actionCount: number;
+    description: string;
+  }>;
 };
 type DaemonStatusReport = {
   running: boolean;
@@ -364,6 +442,72 @@ type DaemonStatusReport = {
   version?: string;
   startedAt?: string;
   projectRoot?: string;
+  indexWarm?: boolean;
+  lastUpdateMs?: number;
+  graphNodes?: number;
+  graphEdges?: number;
+  watchedFiles?: number;
+  watcherLagMs?: number;
+  pendingInvalidations?: number;
+  generation?: number;
+  uptimeSecs?: number;
+  binaryPath?: string;
+  initialBuildMs?: number;
+  lastRebuildMs?: number;
+  incrementalRebuilds?: number;
+  totalInvalidations?: number;
+  configChangePending?: boolean;
+};
+type CompatibilityReportOptions = {
+  cwd?: string;
+  config?: string;
+  profile?: Profile;
+};
+type DebugFrameworksOptions = {
+  cwd?: string;
+  config?: string;
+  profile?: Profile;
+};
+type CompatibilityReport = {
+  supportedFrameworks: string[];
+  heuristicFrameworks: string[];
+  unsupportedSignals: Array<{
+    signal: string;
+    source: string;
+    suggestion?: string;
+  }>;
+  warnings: Array<{
+    code: string;
+    message: string;
+    affectedScope?: string;
+    severity: "low" | "medium" | "high";
+  }>;
+  trustDowngrades: Array<{
+    reason: string;
+    scope: string;
+    severity: "low" | "medium" | "high";
+  }>;
+};
+type FrameworkDebugReport = {
+  detectedPacks: Array<{
+    name: string;
+    confidence: string;
+    signals: string[];
+    reasons: string[];
+  }>;
+  allEntrypoints: Array<{
+    path: string;
+    framework: string;
+    kind: string;
+    heuristic: boolean;
+    reason: string;
+  }>;
+  allIgnorePatterns: string[];
+  allClassificationRules: Array<{
+    pattern: string;
+    classification: string;
+  }>;
+  heuristicDetections: string[];
 };
 declare function scan(options?: ScanOptions): Promise<AnalysisReport>;
 declare function scanDot(options?: ScanOptions): Promise<string>;
@@ -397,5 +541,7 @@ declare function migrateDepcruise(options?: {
 declare function daemonStatus(options?: {
   cwd?: string;
 }): Promise<DaemonStatusReport>;
+declare function compatibilityReport(options?: CompatibilityReportOptions): Promise<CompatibilityReport>;
+declare function debugFrameworks(options?: DebugFrameworksOptions): Promise<FrameworkDebugReport>;
 //#endregion
-export { AnalysisReport, type CommandResult, DaemonStatusReport, DebugEntrypointsOptions, DebugResolveOptions, ExplainOptions, ExplainReport, FixPlanOptions, FixPlanReport, ImpactOptions, ImpactReport, MigrationOutput, Profile, PruneguardConfig, PruneguardExecutionError, type ResolutionInfo, type ResolutionSource, ReviewOptions, ReviewReport, SafeDeleteOptions, SafeDeleteReport, ScanOptions, SuggestRulesOptions, SuggestRulesReport, binaryPath, daemonStatus, debugEntrypoints, debugResolve, explain, fixPlan, impact, loadConfig, migrateDepcruise, migrateKnip, resolutionInfo, review, run, safeDelete, scan, scanDot, schemaPath, suggestRules };
+export { AnalysisReport, type CommandResult, CompatibilityReport, CompatibilityReportOptions, DaemonStatusReport, DebugEntrypointsOptions, DebugFrameworksOptions, DebugResolveOptions, ExplainOptions, ExplainReport, FixPlanOptions, FixPlanReport, FrameworkDebugReport, ImpactOptions, ImpactReport, MigrationOutput, Profile, PruneguardConfig, PruneguardExecutionError, type ResolutionInfo, type ResolutionSource, ReviewOptions, ReviewReport, SafeDeleteOptions, SafeDeleteReport, ScanOptions, SuggestRulesOptions, SuggestRulesReport, binaryPath, compatibilityReport, daemonStatus, debugEntrypoints, debugFrameworks, debugResolve, explain, fixPlan, impact, loadConfig, migrateDepcruise, migrateKnip, resolutionInfo, review, run, safeDelete, scan, scanDot, schemaPath, suggestRules };

package/dist/index.mjs

@@ -126,6 +126,7 @@ async function review(options = {}) {
 	if (options.baseRef) args.push("--changed-since", options.baseRef);
 	if (options.noCache) args.push("--no-cache");
 	if (options.noBaseline) args.push("--no-baseline");
+	if (options.strictTrust) args.push("--strict-trust");
 	args.push("review");
 	const result = await run$1(args, { cwd: options.cwd });
 	if (result.exitCode !== 0 && result.exitCode !== 1) requireSuccess(result);
@@ -199,5 +200,21 @@ async function daemonStatus(options) {
 	}
 	return report;
 }
+async function compatibilityReport(options = {}) {
+	const args = ["--format", "json"];
+	pushGlobalFlags(args, options);
+	args.push("compatibility-report");
+	const result = await run$1(args, { cwd: options.cwd });
+	requireSuccess(result);
+	return parseJson(result);
+}
+async function debugFrameworks(options = {}) {
+	const args = ["--format", "json"];
+	pushGlobalFlags(args, options);
+	args.push("debug", "frameworks");
+	const result = await run$1(args, { cwd: options.cwd });
+	requireSuccess(result);
+	return parseJson(result);
+}
 //#endregion
-export { PruneguardExecutionError, binaryPath, daemonStatus, debugEntrypoints, debugResolve, explain, fixPlan, impact, loadConfig, migrateDepcruise, migrateKnip, resolutionInfo, review, run, safeDelete, scan, scanDot, schemaPath, suggestRules };
+export { PruneguardExecutionError, binaryPath, compatibilityReport, daemonStatus, debugEntrypoints, debugFrameworks, debugResolve, explain, fixPlan, impact, loadConfig, migrateDepcruise, migrateKnip, resolutionInfo, review, run, safeDelete, scan, scanDot, schemaPath, suggestRules };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pruneguard",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Repo truth engine for JS/TS monorepos",
   "keywords": [
     "javascript",
@@ -29,6 +29,8 @@
     "report_schema.json",
     "review_report_schema.json",
     "safe_delete_report_schema.json",
+    "suggest_rules_report_schema.json",
+    "daemon_status_report_schema.json",
     "dist",
     "README.md",
     "bin/pruneguard"
@@ -43,14 +45,14 @@
     }
   },
   "optionalDependencies": {
-    "@pruneguard/cli-darwin-arm64": "0.3.1",
-    "@pruneguard/cli-darwin-x64": "0.3.1",
-    "@pruneguard/cli-linux-arm64-gnu": "0.3.1",
-    "@pruneguard/cli-linux-arm64-musl": "0.3.1",
-    "@pruneguard/cli-linux-x64-gnu": "0.3.1",
-    "@pruneguard/cli-linux-x64-musl": "0.3.1",
-    "@pruneguard/cli-win32-arm64-msvc": "0.3.1",
-    "@pruneguard/cli-win32-x64-msvc": "0.3.1"
+    "@pruneguard/cli-darwin-arm64": "0.4.0",
+    "@pruneguard/cli-darwin-x64": "0.4.0",
+    "@pruneguard/cli-linux-arm64-gnu": "0.4.0",
+    "@pruneguard/cli-linux-arm64-musl": "0.4.0",
+    "@pruneguard/cli-linux-x64-gnu": "0.4.0",
+    "@pruneguard/cli-linux-x64-musl": "0.4.0",
+    "@pruneguard/cli-win32-arm64-msvc": "0.4.0",
+    "@pruneguard/cli-win32-x64-msvc": "0.4.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/report_schema.json

@@ -378,16 +378,34 @@
       }
     },
     "FindingCategory": {
-      "type": "string",
-      "enum": [
-        "unused-export",
-        "unused-file",
-        "unused-package",
-        "unused-dependency",
-        "cycle",
-        "boundary-violation",
-        "ownership-violation",
-        "impact"
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": [
+            "unused-export",
+            "unused-file",
+            "unused-package",
+            "unused-dependency",
+            "cycle",
+            "boundary-violation",
+            "ownership-violation",
+            "impact"
+          ]
+        },
+        {
+          "description": "An exported class member, enum variant, or namespace member is unused.",
+          "type": "string",
+          "enum": [
+            "unused-member"
+          ]
+        },
+        {
+          "description": "The same symbol is exported from multiple paths (barrel re-export collision).",
+          "type": "string",
+          "enum": [
+            "duplicate-export"
+          ]
+        }
       ]
     },
     "FindingConfidence": {

package/suggest_rules_report_schema.json

@@ -0,0 +1,350 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SuggestRulesReport",
+  "description": "Suggested governance rules report.",
+  "type": "object",
+  "required": [
+    "suggestedRules"
+  ],
+  "properties": {
+    "governanceActions": {
+      "description": "Recommended governance actions ordered by priority.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/GovernanceAction"
+      }
+    },
+    "hotspots": {
+      "description": "Hotspot files with high edge traffic.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/Hotspot"
+      }
+    },
+    "ownershipHints": {
+      "description": "Ownership hints from cross-boundary analysis.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/OwnershipHint"
+      }
+    },
+    "rationale": {
+      "description": "Rationale explaining the suggestions.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "suggestedRules": {
+      "description": "Suggested rules inferred from graph analysis.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/SuggestedRule"
+      }
+    },
+    "tags": {
+      "description": "Suggested tags for directory grouping.",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/SuggestedTag"
+      }
+    }
+  },
+  "definitions": {
+    "EffortLevel": {
+      "description": "Estimated effort level.",
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "FindingConfidence": {
+      "type": "string",
+      "enum": [
+        "high",
+        "medium",
+        "low"
+      ]
+    },
+    "GovernanceAction": {
+      "description": "A recommended governance action with priority ordering.",
+      "type": "object",
+      "required": [
+        "description",
+        "effort",
+        "impact",
+        "kind",
+        "priority"
+      ],
+      "properties": {
+        "configFragment": {
+          "description": "Concrete configuration fragment or steps."
+        },
+        "description": {
+          "description": "Human-readable description of what to do.",
+          "type": "string"
+        },
+        "effort": {
+          "description": "Estimated effort level.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/EffortLevel"
+            }
+          ]
+        },
+        "impact": {
+          "description": "Expected impact on governance coverage.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/ImpactLevel"
+            }
+          ]
+        },
+        "kind": {
+          "description": "Kind of governance action.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/GovernanceActionKind"
+            }
+          ]
+        },
+        "priority": {
+          "description": "Priority rank (1 = most impactful).",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        }
+      }
+    },
+    "GovernanceActionKind": {
+      "description": "Kind of governance action.",
+      "type": "string",
+      "enum": [
+        "add-boundary-rule",
+        "assign-ownership",
+        "introduce-tags",
+        "split-hotspot",
+        "add-reachability-fence",
+        "enforce-layering"
+      ]
+    },
+    "Hotspot": {
+      "description": "A hotspot file with high edge traffic.",
+      "type": "object",
+      "required": [
+        "crossOwnerImports",
+        "crossPackageImports",
+        "file",
+        "incomingEdges",
+        "outgoingEdges",
+        "rank",
+        "suggestion"
+      ],
+      "properties": {
+        "crossOwnerImports": {
+          "description": "Cross-owner import count.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "crossPackageImports": {
+          "description": "Cross-package import count.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "file": {
+          "description": "File path.",
+          "type": "string"
+        },
+        "incomingEdges": {
+          "description": "Incoming edge count.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "outgoingEdges": {
+          "description": "Outgoing edge count.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "package": {
+          "description": "Package containing this file, if any.",
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "rank": {
+          "description": "Hotspot rank (1 = highest traffic).",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "suggestion": {
+          "description": "Suggestion for addressing this hotspot.",
+          "type": "string"
+        },
+        "teamsInvolved": {
+          "description": "Distinct teams that touch this file via imports (source or target).",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "workspace": {
+          "description": "Workspace containing this file, if any.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "ImpactLevel": {
+      "description": "Expected impact level.",
+      "type": "string",
+      "enum": [
+        "low",
+        "medium",
+        "high"
+      ]
+    },
+    "OwnershipHint": {
+      "description": "Ownership assignment hint.",
+      "type": "object",
+      "required": [
+        "crossTeamEdges",
+        "pathGlob",
+        "rationale",
+        "suggestedOwner"
+      ],
+      "properties": {
+        "crossTeamEdges": {
+          "description": "Number of cross-team edges.",
+          "type": "integer",
+          "format": "uint",
+          "minimum": 0.0
+        },
+        "pathGlob": {
+          "description": "Path glob to match.",
+          "type": "string"
+        },
+        "rationale": {
+          "description": "Rationale for the suggestion.",
+          "type": "string"
+        },
+        "suggestedOwner": {
+          "description": "Suggested owner identifier.",
+          "type": "string"
+        },
+        "touchedPackages": {
+          "description": "Packages touched by cross-team edges from this area.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "SuggestedRule": {
+      "description": "A single suggested rule.",
+      "type": "object",
+      "required": [
+        "confidence",
+        "configFragment",
+        "description",
+        "kind",
+        "name"
+      ],
+      "properties": {
+        "confidence": {
+          "description": "Confidence in the suggestion.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/FindingConfidence"
+            }
+          ]
+        },
+        "configFragment": {
+          "description": "Configuration fragment that implements this rule."
+        },
+        "description": {
+          "description": "Human-readable description.",
+          "type": "string"
+        },
+        "evidence": {
+          "description": "Evidence supporting the suggestion.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "kind": {
+          "description": "Kind of rule suggestion.",
+          "allOf": [
+            {
+              "$ref": "#/definitions/SuggestedRuleKind"
+            }
+          ]
+        },
+        "name": {
+          "description": "Rule name.",
+          "type": "string"
+        },
+        "rationale": {
+          "description": "Rationale explaining why this specific rule was suggested.",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "SuggestedRuleKind": {
+      "description": "Kind of suggested rule.",
+      "type": "string",
+      "enum": [
+        "forbidden",
+        "required",
+        "tag-assignment",
+        "ownership-boundary",
+        "reachability-fence",
+        "layer-enforcement"
+      ]
+    },
+    "SuggestedTag": {
+      "description": "A suggested tag for directory grouping.",
+      "type": "object",
+      "required": [
+        "glob",
+        "name",
+        "rationale"
+      ],
+      "properties": {
+        "glob": {
+          "description": "Glob pattern for the tag.",
+          "type": "string"
+        },
+        "name": {
+          "description": "Tag name.",
+          "type": "string"
+        },
+        "rationale": {
+          "description": "Why this tag is suggested.",
+          "type": "string"
+        },
+        "source": {
+          "description": "Source of the tag inference (e.g. \"directory-cluster\", \"workspace\", \"package\", \"ownership\").",
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
+}