progmune-runtime 2.1.6 → 3.2.0

package/dist/frameworks/nestjs-detector.js

@@ -0,0 +1,302 @@
+"use strict";
+/**
+ * NestJS Framework Adapter Spike — Decorator-based Protocol Detection
+ *
+ * Parses NestJS decorators (@Controller, @Get/@Post/@Put/@Delete,
+ * @UseGuards, @UsePipes, @UseInterceptors) using ts-morph to determine
+ * the protocol compliance of each route.
+ *
+ * Unlike Express middleware (which requires inference from function names),
+ * NestJS decorators explicitly declare intent:
+ *   @UseGuards(AuthGuard)      → authorization step
+ *   @UsePipes(ValidationPipe)  → input validation step
+ *   @UseInterceptors(...)      → pre/post processing
+ *
+ * This detector extracts routes, determines their auth/validation status,
+ * and identifies security gaps (mutation routes without guards, etc.).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.analyzeNestJSProject = analyzeNestJSProject;
+exports.analyzeNestJSFile = analyzeNestJSFile;
+exports.formatNestJSReport = formatNestJSReport;
+const ts_morph_1 = require("ts-morph");
+// ── Core Analysis ──
+function analyzeNestJSProject(projectRoot) {
+    let project;
+    try {
+        project = new ts_morph_1.Project({
+            tsConfigFilePath: `${projectRoot}/tsconfig.json`,
+            skipAddingFilesFromTsConfig: false,
+        });
+    }
+    catch {
+        // No tsconfig — try direct file loading
+        project = new ts_morph_1.Project();
+        try {
+            project.addSourceFilesAtPaths(`${projectRoot}/**/*.ts`);
+        }
+        catch {
+            return { controllers: [], routes: [], issues: [] };
+        }
+    }
+    const analysis = {
+        controllers: [],
+        routes: [],
+        issues: [],
+    };
+    for (const file of project.getSourceFiles()) {
+        // Skip node_modules and test files
+        if (file.getFilePath().includes("node_modules"))
+            continue;
+        if (/\.(test|spec)\.ts$/.test(file.getFilePath()))
+            continue;
+        for (const cls of file.getClasses()) {
+            const ctrlDec = cls.getDecorator("Controller");
+            if (!ctrlDec)
+                continue;
+            const controllerName = cls.getName() || "UnknownController";
+            analysis.controllers.push(controllerName);
+            const basePath = getStringArg(ctrlDec, 0) || "";
+            const classGuards = extractGuardNames(cls.getDecorator("UseGuards"));
+            const classPipes = extractGuardNames(cls.getDecorator("UsePipes"));
+            for (const method of cls.getMethods()) {
+                const httpMethod = getHttpMethod(method);
+                if (!httpMethod)
+                    continue;
+                const routePath = getStringArg(method.getDecorators().find(d => isHttpDecorator(d)), 0) || "";
+                const fullPath = basePath + (routePath.startsWith("/") ? routePath : `/${routePath}`);
+                // Guards/Pipes: method-level overrides class-level
+                const methodGuards = extractGuardNames(method.getDecorator("UseGuards"));
+                const methodPipes = extractGuardNames(method.getDecorator("UsePipes"));
+                const guards = methodGuards.length > 0 ? methodGuards : classGuards;
+                const pipes = methodPipes.length > 0 ? methodPipes : classPipes;
+                const route = {
+                    method: httpMethod,
+                    path: fullPath,
+                    controller: controllerName,
+                    handler: method.getName() || "unknown",
+                    hasAuthGuard: guards.length > 0,
+                    hasValidationPipe: pipes.length > 0,
+                    guards,
+                    pipes,
+                };
+                analysis.routes.push(route);
+                // ── Security Checks ──
+                // POST/PUT/DELETE without auth guard
+                // Skip intentionally public routes (login, register, health, etc.)
+                if (["POST", "PUT", "DELETE", "PATCH"].includes(httpMethod) && !isPublicRoute(fullPath)) {
+                    if (!route.hasAuthGuard) {
+                        analysis.issues.push({
+                            type: "NESTJS_NO_AUTH",
+                            severity: "critical",
+                            route: `${httpMethod} ${fullPath}`,
+                            controller: controllerName,
+                            message: `Mutation route ${httpMethod} ${fullPath} has no @UseGuards. Anyone can call it.`,
+                            fix: `Add @UseGuards(AuthGuard) to the method or controller class.`,
+                        });
+                    }
+                    if (!route.hasValidationPipe) {
+                        analysis.issues.push({
+                            type: "NESTJS_NO_VALIDATION",
+                            severity: "medium",
+                            route: `${httpMethod} ${fullPath}`,
+                            controller: controllerName,
+                            message: `Mutation route ${httpMethod} ${fullPath} has no @UsePipes for input validation.`,
+                            fix: `Add @UsePipes(ValidationPipe) or a DTO class to validate input.`,
+                        });
+                    }
+                }
+                // Sensitive GET routes without auth
+                if (httpMethod === "GET") {
+                    const sensitiveTerms = ["admin", "private", "secret", "manage"];
+                    if (sensitiveTerms.some(t => fullPath.toLowerCase().includes(t)) && !route.hasAuthGuard) {
+                        analysis.issues.push({
+                            type: "NESTJS_SENSITIVE_PUBLIC",
+                            severity: "high",
+                            route: `${httpMethod} ${fullPath}`,
+                            controller: controllerName,
+                            message: `Sensitive GET route ${fullPath} is publicly accessible without @UseGuards.`,
+                            fix: `Add @UseGuards(AuthGuard) to protect this route.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return analysis;
+}
+// ── Helpers ──
+/** Check if a route is intentionally public (login, register, health, etc.). */
+function isPublicRoute(path) {
+    // Normalize: ensure leading slash for consistent matching
+    const normalized = path.startsWith("/") ? path : `/${path}`;
+    const publicPatterns = [
+        /\/auth\/login$/i, /\/login$/i,
+        /\/auth\/register$/i, /\/register$/i, /\/signup$/i,
+        /\/auth\/signup$/i, /\/auth\/signin$/i, /\/signin$/i,
+        /\/auth\/refresh$/i, /\/auth\/forgot/i, /\/auth\/reset/i,
+        /\/health$/i, /\/healthcheck$/i, /\/ping$/i, /\/status$/i,
+        /\/public\//i, /\/static\//i,
+    ];
+    return publicPatterns.some(p => p.test(normalized));
+}
+// ── Low-level Helpers ──
+function getHttpMethod(method) {
+    for (const dec of method.getDecorators()) {
+        const name = dec.getName();
+        if (["Get", "Post", "Put", "Delete", "Patch", "Options", "Head", "All"].includes(name)) {
+            return name.toUpperCase();
+        }
+    }
+    return null;
+}
+function isHttpDecorator(dec) {
+    return ["Get", "Post", "Put", "Delete", "Patch", "Options", "Head", "All"].includes(dec.getName());
+}
+function getStringArg(decorator, index) {
+    if (!decorator)
+        return undefined;
+    const args = decorator.getArguments();
+    if (args.length <= index)
+        return undefined;
+    const text = args[index].getText();
+    return text.replace(/^['"]|['"]$/g, "");
+}
+function extractGuardNames(decorator) {
+    if (!decorator)
+        return [];
+    const args = decorator.getArguments();
+    const result = [];
+    for (const arg of args) {
+        const text = arg.getText();
+        // Handle: @UseGuards(AuthGuard) or @UseGuards(AuthGuard, AdminGuard)
+        const matches = text.match(/\b([A-Z][a-zA-Z0-9]*(?:Guard|Pipe|Interceptor))\b/g);
+        if (matches)
+            result.push(...matches);
+    }
+    return result;
+}
+// ── File-level and Project-level Convenience ──
+/**
+ * Analyze a single TypeScript file for NestJS controllers.
+ */
+function analyzeNestJSFile(filePath) {
+    const fs = require("fs");
+    if (!fs.existsSync(filePath))
+        return null;
+    const code = fs.readFileSync(filePath, "utf-8");
+    // Quick check: does this file look like NestJS?
+    if (!/@Controller\b/.test(code) && !/@nestjs\/common/.test(code))
+        return null;
+    const project = new ts_morph_1.Project();
+    try {
+        project.addSourceFileAtPath(filePath);
+    }
+    catch {
+        return null;
+    }
+    // Parse using the same logic as analyzeNestJSProject
+    const analysis = {
+        controllers: [],
+        routes: [],
+        issues: [],
+    };
+    for (const file of project.getSourceFiles()) {
+        for (const cls of file.getClasses()) {
+            const ctrlDec = cls.getDecorator("Controller");
+            if (!ctrlDec)
+                continue;
+            // ... (same parsing logic)
+            const controllerName = cls.getName() || "UnknownController";
+            analysis.controllers.push(controllerName);
+            const basePath = getStringArg(ctrlDec, 0) || "";
+            const classGuards = extractGuardNames(cls.getDecorator("UseGuards"));
+            const classPipes = extractGuardNames(cls.getDecorator("UsePipes"));
+            for (const method of cls.getMethods()) {
+                const httpMethod = getHttpMethod(method);
+                if (!httpMethod)
+                    continue;
+                const routePath = getStringArg(method.getDecorators().find(d => isHttpDecorator(d)), 0) || "";
+                const fullPath = basePath + (routePath.startsWith("/") ? routePath : `/${routePath}`);
+                const methodGuards = extractGuardNames(method.getDecorator("UseGuards"));
+                const methodPipes = extractGuardNames(method.getDecorator("UsePipes"));
+                const guards = methodGuards.length > 0 ? methodGuards : classGuards;
+                const pipes = methodPipes.length > 0 ? methodPipes : classPipes;
+                const route = {
+                    method: httpMethod,
+                    path: fullPath,
+                    controller: controllerName,
+                    handler: method.getName() || "unknown",
+                    hasAuthGuard: guards.length > 0,
+                    hasValidationPipe: pipes.length > 0,
+                    guards,
+                    pipes,
+                };
+                analysis.routes.push(route);
+                // Security checks
+                if (["POST", "PUT", "DELETE", "PATCH"].includes(httpMethod) && !isPublicRoute(fullPath)) {
+                    if (!route.hasAuthGuard) {
+                        analysis.issues.push({
+                            type: "NESTJS_NO_AUTH",
+                            severity: "critical",
+                            route: `${httpMethod} ${fullPath}`,
+                            controller: controllerName,
+                            message: `Mutation route ${httpMethod} ${fullPath} has no @UseGuards. Anyone can call it.`,
+                            fix: `Add @UseGuards(AuthGuard) to the method or controller class.`,
+                        });
+                    }
+                    if (!route.hasValidationPipe) {
+                        analysis.issues.push({
+                            type: "NESTJS_NO_VALIDATION",
+                            severity: "medium",
+                            route: `${httpMethod} ${fullPath}`,
+                            controller: controllerName,
+                            message: `Mutation route ${httpMethod} ${fullPath} has no @UsePipes for input validation.`,
+                            fix: `Add @UsePipes(ValidationPipe) or a DTO class to validate input.`,
+                        });
+                    }
+                }
+                if (httpMethod === "GET") {
+                    const sensitiveTerms = ["admin", "private", "secret", "manage"];
+                    if (sensitiveTerms.some(t => fullPath.toLowerCase().includes(t)) && !route.hasAuthGuard) {
+                        analysis.issues.push({
+                            type: "NESTJS_SENSITIVE_PUBLIC",
+                            severity: "high",
+                            route: `${httpMethod} ${fullPath}`,
+                            controller: controllerName,
+                            message: `Sensitive GET route ${fullPath} is publicly accessible without @UseGuards.`,
+                            fix: `Add @UseGuards(AuthGuard) to protect this route.`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return analysis;
+}
+/**
+ * Format a summary report for CLI output.
+ */
+function formatNestJSReport(analysis) {
+    if (analysis.controllers.length === 0) {
+        return "Not a NestJS project (no @Controller classes found).";
+    }
+    const lines = [
+        `Controllers: ${analysis.controllers.length}`,
+        `Routes: ${analysis.routes.length}`,
+        `Issues: ${analysis.issues.length}`,
+        "",
+    ];
+    if (analysis.issues.length === 0) {
+        lines.push("✅ No NestJS security issues detected.");
+        return lines.join("\n");
+    }
+    for (const issue of analysis.issues) {
+        const emoji = issue.severity === "critical" ? "🔴" : issue.severity === "high" ? "🟠" : "🟡";
+        lines.push(`${emoji} [${issue.type}] ${issue.route}`);
+        lines.push(`   ${issue.message}`);
+        lines.push(`   Fix: ${issue.fix}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}

package/dist/frameworks/trpc-detector.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * tRPC Framework Adapter — Endpoint Input Validation Detection
+ *
+ * Detects tRPC router/procedure patterns in TypeScript projects and
+ * flags procedures that lack input schema validation:
+ *
+ *   - TRPC_MUTATION_WITHOUT_INPUT_SCHEMA (high)
+ *     Mutation procedure without .input(z.object(...)) that references
+ *     `input.` in its body or performs DB writes — unvalidated data
+ *     reaches business logic.
+ *
+ *   - TRPC_PUBLIC_MUTATION (high)
+ *     publicProcedure mutation without input schema — unauthenticated
+ *     AND unvalidated mutation endpoint.
+ *
+ *   - TRPC_PROCEDURE_USES_INPUT_WITHOUT_SCHEMA (medium)
+ *     Any procedure (query or mutation) whose body reads `input.x`
+ *     but has no .input() schema declared.
+ *
+ * Purely regex-based, no AST — follows the express-detector.ts pattern.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectTRPCApp = detectTRPCApp;
+exports.extractRouterNames = extractRouterNames;
+exports.extractProcedures = extractProcedures;
+exports.analyzeTRPCFile = analyzeTRPCFile;
+// ── Detection Patterns ──
+const PROCEDURE_TYPE_PATTERN = /\b(publicProcedure|protectedProcedure|adminProcedure)\b/g;
+const DB_WRITE_PATTERN = /\b(db\.(insert|update|delete|create|upsert|execute)|prisma\.\w+\.(create|update|delete|upsert|createMany|updateMany|deleteMany)|drizzle\.(insert|update|delete)|\.(insert|update|delete|create|upsert)\s*\()/i;
+/**
+ * Detect whether this file contains tRPC definitions.
+ */
+function detectTRPCApp(code) {
+    return (/\b(initTRPC|t\.router)\b/.test(code) ||
+        /\brouter\s*\(\s*\{/.test(code) ||
+        PROCEDURE_TYPE_PATTERN.test(code));
+}
+/**
+ * Extract tRPC router variable names (export const xxxRouter = router({...})).
+ */
+function extractRouterNames(code) {
+    const names = [];
+    const re = /(?:export\s+)?(?:const|let)\s+(\w*[Rr]outer\w*)\s*=\s*(?:t\.)?router\s*\(/g;
+    let m;
+    while ((m = re.exec(code)) !== null) {
+        names.push(m[1]);
+    }
+    return names;
+}
+/**
+ * Extract procedure definitions from a tRPC router body.
+ *
+ * Matches patterns like:
+ *   add: protectedProcedure.input(z.object({...})).mutation(async ({ctx, input}) => {...}),
+ *   list: publicProcedure.query(async ({ctx}) => {...}),
+ */
+function extractProcedures(code) {
+    const procedures = [];
+    // Match: name: <procedureType>.input(...).<kind>( or name: <procedureType>.<kind>(
+    const procRe = /([A-Za-z_][A-Za-z0-9_]*)\s*:\s*(publicProcedure|protectedProcedure|adminProcedure)((?:\.\w+\s*\([^()]*\))*)\.(query|mutation)\s*\(/g;
+    let m;
+    while ((m = procRe.exec(code)) !== null) {
+        const name = m[1];
+        const procType = m[2].replace(/Procedure$/, "");
+        const chain = m[3] || "";
+        const kind = m[4];
+        const hasInputSchema = /\.input\s*\(/.test(chain);
+        // Extract body until matching closing paren of the query/mutation call.
+        // Heuristic: scan forward for the closing paren matching the one after
+        // the .query( / .mutation( token.
+        const openIdx = procRe.lastIndex - 1; // index of '(' after query/mutation
+        let depth = 1;
+        let closeIdx = openIdx + 1;
+        while (closeIdx < code.length && depth > 0) {
+            const ch = code[closeIdx];
+            if (ch === "(")
+                depth++;
+            else if (ch === ")")
+                depth--;
+            closeIdx++;
+        }
+        const body = code.slice(openIdx + 1, Math.min(closeIdx - 1, openIdx + 2000));
+        const usesInputInBody = /input\s*\./.test(body) || /\binput\b/.test(body);
+        const doesDbWrite = DB_WRITE_PATTERN.test(body);
+        procedures.push({
+            name,
+            kind,
+            procedureType: procType,
+            hasInputSchema,
+            usesInputInBody,
+            doesDbWrite,
+            line: code.slice(0, m.index).split("\n").length,
+        });
+    }
+    return procedures;
+}
+/**
+ * Analyze a source file for tRPC security issues.
+ * Main entry point — mirrors analyzeExpressFile().
+ */
+function analyzeTRPCFile(filePath) {
+    const fs = require("fs");
+    let code;
+    try {
+        code = fs.readFileSync(filePath, "utf-8");
+    }
+    catch {
+        return { hasTRPC: false, routerNames: [], procedures: [], issues: [] };
+    }
+    if (!detectTRPCApp(code)) {
+        return { hasTRPC: false, routerNames: [], procedures: [], issues: [] };
+    }
+    const routerNames = extractRouterNames(code);
+    const procedures = extractProcedures(code);
+    const issues = [];
+    for (const p of procedures) {
+        // Rule 1: Mutation without input schema that writes to DB or uses input
+        if (p.kind === "mutation" && !p.hasInputSchema && (p.usesInputInBody || p.doesDbWrite)) {
+            issues.push({
+                severity: "high",
+                rule: "TRPC_MUTATION_WITHOUT_INPUT_SCHEMA",
+                procedure: p.name,
+                message: `tRPC mutation "${p.name}" has no .input() schema but ` +
+                    `${p.usesInputInBody ? "references `input` in its body" : "performs DB writes"}. ` +
+                    `Unvalidated payloads reach business logic.`,
+                line: p.line,
+                fix: `Add .input(z.object({...})) to "${p.name}" with a Zod schema covering every field read from input.`,
+            });
+        }
+        // Rule 2: Public (unauthenticated) mutation WITHOUT input schema that
+        // moves data (uses input or writes to DB). Pure stateless public
+        // mutations (e.g. logout clearing a cookie) are exempt.
+        if (p.kind === "mutation" && p.procedureType === "public" && !p.hasInputSchema &&
+            (p.usesInputInBody || p.doesDbWrite)) {
+            issues.push({
+                severity: "high",
+                rule: "TRPC_PUBLIC_MUTATION",
+                procedure: p.name,
+                message: `tRPC mutation "${p.name}" is public (no auth) AND has no .input() validation ` +
+                    `while ${p.usesInputInBody ? "reading `input`" : "writing to the database"}. ` +
+                    `Anyone can submit arbitrary payloads.`,
+                line: p.line,
+                fix: `Use protectedProcedure for "${p.name}", and add .input(z.object({...})) for payload validation.`,
+            });
+        }
+        // Rule 3: Any procedure reading input without a schema
+        if (p.usesInputInBody && !p.hasInputSchema && p.kind === "query") {
+            issues.push({
+                severity: "medium",
+                rule: "TRPC_PROCEDURE_USES_INPUT_WITHOUT_SCHEMA",
+                procedure: p.name,
+                message: `tRPC query "${p.name}" reads \`input\` but declares no .input() schema. ` +
+                    `Input shape is unvalidated and can drift from the contract.`,
+                line: p.line,
+                fix: `Declare .input(z.object({...})) on "${p.name}" to pin down the input contract.`,
+            });
+        }
+    }
+    return { hasTRPC: true, routerNames, procedures, issues };
+}

package/dist/frameworks/version-awareness.js

@@ -0,0 +1,179 @@
+"use strict";
+/**
+ * Framework Version-Aware Governance Rules
+ *
+ * Encodes the proxy.ts lesson (2026-08-03):
+ *   AI follows the framework version the project actually depends on.
+ *   Human reviewers follow the framework version in their training data.
+ *   When these differ, the human reviewer is usually wrong.
+ *
+ * This module reads package.json to detect framework versions,
+ * then applies version-specific conventions instead of training-data defaults.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectFrameworks = detectFrameworks;
+exports.checkFrameworkConventions = checkFrameworkConventions;
+exports.checkFileRename = checkFileRename;
+exports.generateVersionAwarenessReport = generateVersionAwarenessReport;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ── Framework Detection ──
+function detectFrameworks(projectPath) {
+    const pkgPath = path.join(projectPath, "package.json");
+    if (!fs.existsSync(pkgPath))
+        return [];
+    const frameworks = [];
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        for (const [name, version] of Object.entries(deps)) {
+            if (typeof version !== "string")
+                continue;
+            const cleanVersion = version.replace(/^[\^~]/, "");
+            const majorVersion = parseInt(cleanVersion.split(".")[0], 10);
+            if (isNaN(majorVersion))
+                continue;
+            frameworks.push({ name, version: cleanVersion, majorVersion });
+        }
+    }
+    catch {
+        // Can't parse package.json — skip
+    }
+    return frameworks;
+}
+/**
+ * Known breaking changes that AI-generated code follows correctly
+ * but human reviewers (with outdated training data) may "fix" incorrectly.
+ */
+const BREAKING_CHANGES = [
+    {
+        framework: "next",
+        sinceVersion: 16,
+        oldConvention: "middleware.ts",
+        newConvention: "proxy.ts",
+        description: "Next.js 16 deprecated `middleware.ts` in favor of `proxy.ts`. " +
+            "AI code generators using Next.js 16 will produce `proxy.ts`. " +
+            "Human reviewers with Next.js 12-15 training data will expect `middleware.ts`. " +
+            "The AI is correct — do NOT rename `proxy.ts` to `middleware.ts`.",
+        doNotRename: ["proxy.ts", "src/proxy.ts"],
+        lesson: "Framework version conventions override training data. " +
+            "When AGENTS.md warns 'This is NOT the Next.js you know', believe it. " +
+            "Check node_modules/next/dist/docs/ before 'fixing' file names.",
+    },
+    // Placeholder for future discoveries
+    // Add more entries as we encounter framework breaking changes
+];
+// ── Version-Aware Checks ──
+function checkFrameworkConventions(projectPath) {
+    const frameworks = detectFrameworks(projectPath);
+    const checks = [];
+    for (const change of BREAKING_CHANGES) {
+        const fw = frameworks.find(f => f.name === change.framework);
+        if (!fw)
+            continue;
+        const applies = fw.majorVersion >= change.sinceVersion;
+        checks.push({
+            framework: change.framework,
+            versionRange: `>=${change.sinceVersion}.0.0`,
+            appliesTo: applies,
+            rule: `FW_${change.framework.toUpperCase()}_${change.oldConvention.replace(/\./g, "_").toUpperCase()}_DEPRECATED`,
+            description: change.description,
+            trainingDataDefault: change.oldConvention,
+            actualConvention: change.newConvention,
+            affectedFiles: change.doNotRename,
+        });
+    }
+    return checks;
+}
+/**
+ * Check if a specific file rename is going against framework conventions.
+ * Returns the warning if the rename should be reverted.
+ */
+function checkFileRename(projectPath, fromFile, toFile) {
+    const checks = checkFrameworkConventions(projectPath);
+    for (const change of BREAKING_CHANGES) {
+        const fw = detectFrameworks(projectPath).find(f => f.name === change.framework);
+        if (!fw || fw.majorVersion < change.sinceVersion)
+            continue;
+        // Check if we're renaming FROM the new convention TO the old one
+        const fromBase = path.basename(fromFile);
+        const toBase = path.basename(toFile);
+        if (change.doNotRename.includes(fromBase) && toBase === change.oldConvention) {
+            return {
+                warning: `⚠️  POTENTIAL GOVERNANCE ERROR: Renaming ${fromBase} → ${toBase}\n\n` +
+                    `  Project uses ${change.framework} v${fw.version}\n` +
+                    `  ${change.description}\n\n` +
+                    `  Before renaming framework-generated files, verify the current\n` +
+                    `  version's conventions in node_modules/${change.framework}/dist/docs/`,
+                shouldRevert: true,
+                lesson: change.lesson,
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Generate a report for CLI / governance output.
+ */
+function generateVersionAwarenessReport(projectPath) {
+    const frameworks = detectFrameworks(projectPath);
+    const checks = checkFrameworkConventions(projectPath);
+    const activeChanges = checks.filter(c => c.appliesTo);
+    const lines = [
+        "═ Framework Version-Aware Governance ═",
+        "",
+        `Detected ${frameworks.length} framework(s):`,
+        ...frameworks.map(f => `  - ${f.name} v${f.version}`),
+        "",
+    ];
+    if (activeChanges.length === 0) {
+        lines.push("No version-convention conflicts detected.");
+    }
+    else {
+        lines.push(`⚠️  ${activeChanges.length} breaking change(s) apply to this project:`);
+        lines.push("");
+        for (const change of activeChanges) {
+            lines.push(`  Rule: ${change.rule}`);
+            lines.push(`  Training data (outdated): ${change.trainingDataDefault}`);
+            lines.push(`  Actual convention:       ${change.actualConvention}`);
+            lines.push(`  Affected files: ${change.affectedFiles.join(", ")}`);
+            lines.push("");
+        }
+        lines.push("  LESSON: Do not rename framework-convention files based on");
+        lines.push("  training data. Verify against the installed framework version.");
+    }
+    return lines.join("\n");
+}