@webpieces/nx-webpieces-rules 0.4.464 → 0.4.466

package/src/lib/package-validator.js

@@ -2,181 +2,405 @@
 /**
  * Package Validator
  *
- * Validates that package.json dependencies match the project.json build.dependsOn
- * This ensures the two sources of truth don't drift apart.
+ * Validates that package.json dependencies match the architecture graph nx derived
+ * from the source, and — critically — that each dependency is declared in the RIGHT
+ * SECTION of package.json:
+ *
+ *   - reached from production source   → `dependencies` (or `peerDependencies`)
+ *   - reached ONLY from test/dev files → `devDependencies`
+ *
+ * WHY the section matters: production images are built with
+ * `pnpm --filter=<svc> deploy --prod`, which installs exactly the `dependencies`
+ * closure. A test-support package parked in `dependencies` therefore ships test
+ * machinery (auth-bypass hooks, canned credentials, fake datastores) into the
+ * production container. Before this validator understood `devDependencies`, moving
+ * such a package to its correct home FAILED the build — the tool enforced the
+ * insecure layout. Now `devDependencies` is the required home for test-only deps,
+ * and listing one in `dependencies` is itself a violation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackageValidator = exports.DeclaredDeps = exports.ValidationResult = exports.ProjectValidationResult = exports.PackageValidatorOptions = void 0;
 exports.validatePackageJsonDependencies = validatePackageJsonDependencies;
 const tslib_1 = require("tslib");
 const fs = tslib_1.__importStar(require("fs"));
 const path = tslib_1.__importStar(require("path"));
 const devkit_1 = require("@nx/devkit");
+const dep_usage_scanner_1 = require("./dep-usage-scanner");
+const toError_1 = require("../toError");
 /**
- * Read package.json dependencies for a project
- * Returns null if package.json doesn't exist (apps often don't have one)
+ * Options for {@link validatePackageJsonDependencies}. Data-only (CLAUDE.md: data
+ * structures are classes, never anonymous object literals).
  */
-function readPackageJsonDeps(workspaceRoot, projectRoot) {
-    const packageJsonPath = path.join(workspaceRoot, projectRoot, 'package.json');
-    if (!fs.existsSync(packageJsonPath)) {
-        return null; // No package.json - skip validation for this project
-    }
-    // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-    try {
-        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-        const deps = [];
-        // Collect ALL dependencies from package.json
-        for (const depType of ['dependencies', 'peerDependencies']) {
-            const depObj = packageJson[depType] || {};
-            for (const depName of Object.keys(depObj)) {
-                if (!deps.includes(depName)) {
-                    deps.push(depName);
-                }
-            }
-        }
-        return deps.sort();
+class PackageValidatorOptions {
+    testOnlyDepMode;
+    constructor(testOnlyDepMode = 'error') {
+        this.testOnlyDepMode = testOnlyDepMode;
     }
-    catch (err) {
-        //const error = toError(err);
-        void err;
-        console.warn(`Could not read package.json at ${packageJsonPath}`);
-        return [];
+}
+exports.PackageValidatorOptions = PackageValidatorOptions;
+/**
+ * Validation result for a single project
+ */
+class ProjectValidationResult {
+    project;
+    valid;
+    missingInPackageJson;
+    extraInPackageJson;
+    /** Graph deps that are test-only but declared in `dependencies` (production closure). */
+    testOnlyInProdDependencies;
+    constructor(project, valid, missingInPackageJson, extraInPackageJson, testOnlyInProdDependencies) {
+        this.project = project;
+        this.valid = valid;
+        this.missingInPackageJson = missingInPackageJson;
+        this.extraInPackageJson = extraInPackageJson;
+        this.testOnlyInProdDependencies = testOnlyInProdDependencies;
     }
 }
+exports.ProjectValidationResult = ProjectValidationResult;
 /**
- * Build map of project names to their package names
- * e.g., "core-util" → "@webpieces/core-util"
+ * Overall validation result
+ *
+ * `errors` fail the build. Every error's fix is either ADDITIVE ("add it to package.json")
+ * or a MOVE between sections ("it belongs in devDependencies") — never "delete a
+ * dependency", so no error can push a user toward removing a runtime-required package.
+ *
+ * `warnings` never fail the build. Workspace deps in package.json that the architecture
+ * graph can't reach are reported here, NOT as errors: a transitively-reachable or even
+ * unreachable entry can still be a real runtime dependency (e.g. a peerDependency or a
+ * generated client that nx's import analysis doesn't traverse). Erroring on these is the
+ * "runtime-validity trap" that previously forced a bad package.json edit — so we only warn.
+ */
+class ValidationResult {
+    valid;
+    errors;
+    warnings;
+    projectResults;
+    constructor(valid, errors, warnings, projectResults) {
+        this.valid = valid;
+        this.errors = errors;
+        this.warnings = warnings;
+        this.projectResults = projectResults;
+    }
+}
+exports.ValidationResult = ValidationResult;
+/**
+ * The three package.json sections that matter, kept apart so the validator can say
+ * WHICH one a package belongs in (the old code merged them and lost that information —
+ * and never even read devDependencies).
  */
-function buildProjectToPackageMap(workspaceRoot, 
-// webpieces-disable no-any-unknown -- Nx devkit projectsConfig type is dynamic and not strongly typed
-projectsConfig) {
-    const map = new Map();
-    // webpieces-disable no-any-unknown -- Nx devkit projects config entries are untyped
-    for (const [projectName, config] of Object.entries(projectsConfig.projects)) {
-        const packageJsonPath = path.join(workspaceRoot, config.root, 'package.json');
-        if (fs.existsSync(packageJsonPath)) {
-            // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
-            try {
-                const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-                if (packageJson.name) {
-                    map.set(projectName, packageJson.name);
+class DeclaredDeps {
+    dependencies;
+    devDependencies;
+    peerDependencies;
+    constructor(dependencies, devDependencies, peerDependencies) {
+        this.dependencies = dependencies;
+        this.devDependencies = devDependencies;
+        this.peerDependencies = peerDependencies;
+    }
+    /** Every declared package name, deduped and sorted (all three sections). */
+    all() {
+        const merged = new Set();
+        for (const name of this.dependencies)
+            merged.add(name);
+        for (const name of this.devDependencies)
+            merged.add(name);
+        for (const name of this.peerDependencies)
+            merged.add(name);
+        return Array.from(merged).sort();
+    }
+    /** Declared somewhere that survives `pnpm deploy --prod`. */
+    isProductionDeclared(packageName) {
+        return (this.dependencies.includes(packageName) ||
+            this.peerDependencies.includes(packageName));
+    }
+    isDevDeclared(packageName) {
+        return this.devDependencies.includes(packageName);
+    }
+    isDeclared(packageName) {
+        return this.isProductionDeclared(packageName) || this.isDevDeclared(packageName);
+    }
+}
+exports.DeclaredDeps = DeclaredDeps;
+/**
+ * Per-project classification of graph deps against what package.json declares.
+ */
+class DepClassification {
+    /** Production-reached deps absent from `dependencies`/`peerDependencies`. */
+    missingInPackageJson = [];
+    /** Production-reached deps declared ONLY in `devDependencies` (runtime would break). */
+    prodDepsOnlyInDev = [];
+    /** Test-only deps declared in no section at all. */
+    missingTestOnlyDeps = [];
+    /** Test-only deps sitting in `dependencies` — i.e. shipped to production. */
+    testOnlyInProdDependencies = [];
+    /** Non-workspace (third-party) package.json entries — informational only. */
+    extraInPackageJson = [];
+    /** Workspace entries the graph cannot reach at all — warn-only drift. */
+    extraWorkspaceDeps = [];
+}
+class SingleProjectValidation {
+    result;
+    errors;
+    warnings;
+    constructor(result, errors, warnings) {
+        this.result = result;
+        this.errors = errors;
+        this.warnings = warnings;
+    }
+}
+/**
+ * The per-workspace lookups a single-project validation needs, passed as one object
+ * so method signatures stay readable.
+ */
+class ValidationContext {
+    graph;
+    projectToPackage;
+    packageToProject;
+    options;
+    constructor(graph, projectToPackage, packageToProject, options) {
+        this.graph = graph;
+        this.projectToPackage = projectToPackage;
+        this.packageToProject = packageToProject;
+        this.options = options;
+    }
+}
+class PackageValidator {
+    scanner = new dep_usage_scanner_1.DepUsageScanner();
+    /**
+     * Read the three dependency sections of a project's package.json.
+     * Returns null when there is no package.json (apps often have none) so the caller
+     * can skip the project entirely.
+     */
+    readDeclaredDeps(workspaceRoot, projectRoot) {
+        const packageJsonPath = path.join(workspaceRoot, projectRoot, 'package.json');
+        if (!fs.existsSync(packageJsonPath)) {
+            return null;
+        }
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            return new DeclaredDeps(this.namesOf(packageJson, 'dependencies'), this.namesOf(packageJson, 'devDependencies'), this.namesOf(packageJson, 'peerDependencies'));
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            console.warn(`Could not read package.json at ${packageJsonPath}: ${error.message}`);
+            return new DeclaredDeps([], [], []);
+        }
+    }
+    // webpieces-disable no-any-unknown -- parsed JSON is inherently untyped
+    namesOf(packageJson, section) {
+        const depObj = packageJson[section] || {};
+        return Object.keys(depObj).sort();
+    }
+    /**
+     * Build map of project names to their package names
+     * e.g., "core-util" → "@webpieces/core-util"
+     */
+    buildProjectToPackageMap(workspaceRoot, 
+    // webpieces-disable no-any-unknown -- Nx devkit projectsConfig type is dynamic and not strongly typed
+    projectsConfig) {
+        const map = new Map();
+        // webpieces-disable no-any-unknown -- Nx devkit projects config entries are untyped
+        for (const configEntry of Object.entries(projectsConfig.projects)) {
+            const projectName = configEntry[0];
+            const packageJsonPath = path.join(workspaceRoot, configEntry[1].root, 'package.json');
+            if (!fs.existsSync(packageJsonPath))
+                continue;
+            const packageName = this.readPackageName(packageJsonPath);
+            if (packageName !== null)
+                map.set(projectName, packageName);
+        }
+        return map;
+    }
+    readPackageName(packageJsonPath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+            return packageJson.name || null;
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            console.warn(`Could not parse ${packageJsonPath}: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * Compute the transitive closure of a project's dependencies in the graph.
+     * Example: server → [core-meta, http-server]; the closure includes http-server and
+     * everything http-server reaches.
+     *
+     * Used to allow package.json entries for transitive deps (a legitimate pattern:
+     * npm install brings the whole dependency tree, so a consumer may list any reachable
+     * package directly).
+     */
+    computeTransitiveClosure(projectName, graph) {
+        const closure = new Set();
+        const stack = [projectName];
+        while (stack.length > 0) {
+            const current = stack.pop();
+            const entry = graph[current];
+            if (!entry)
+                continue;
+            for (const dep of entry.dependsOn) {
+                if (!closure.has(dep)) {
+                    closure.add(dep);
+                    stack.push(dep);
                 }
             }
-            catch (err) {
-                //const error = toError(err);
-                void err;
-                // Ignore parse errors
+        }
+        return closure;
+    }
+    /**
+     * Split a project's graph deps into "declared correctly", "missing", and "declared in
+     * the wrong section", using the import scan to decide which section each dep belongs in.
+     */
+    classifyDeps(declared, usage, entry, transitiveClosure, context) {
+        const classification = new DepClassification();
+        for (const depProjectName of entry.dependsOn) {
+            const depPackageName = context.projectToPackage.get(depProjectName) || depProjectName;
+            this.classifyOneDep(depProjectName, depPackageName, declared, usage, classification);
+        }
+        // Workspace extras are OK if reachable via transitive closure (matches the ESLint
+        // enforce-architecture rule which also allows transitive imports). Only flag extras
+        // that are NOT reachable at all — real graph drift.
+        for (const dep of declared.all()) {
+            const depProjectName = context.packageToProject.get(dep);
+            if (depProjectName === undefined) {
+                classification.extraInPackageJson.push(dep);
+                continue;
             }
+            if (entry.dependsOn.includes(depProjectName))
+                continue;
+            if (transitiveClosure.has(depProjectName))
+                continue;
+            classification.extraWorkspaceDeps.push(dep);
         }
+        return classification;
     }
-    return map;
-}
-/**
- * Compute the transitive closure of a project's dependencies in the graph.
- * Example: server → [core-meta, http-server]; transitive closure includes
- * http-server and everything http-server reaches (http-routing,
- * core-context, core-util, http-api).
- *
- * Used to allow package.json entries for transitive deps (a legitimate pattern:
- * npm install brings the whole dependency tree, so a consumer may list any
- * reachable package directly).
- */
-function computeTransitiveClosure(projectName, graph) {
-    const closure = new Set();
-    const stack = [projectName];
-    while (stack.length > 0) {
-        const current = stack.pop();
-        const entry = graph[current];
-        if (!entry)
-            continue;
-        for (const dep of entry.dependsOn) {
-            if (!closure.has(dep)) {
-                closure.add(dep);
-                stack.push(dep);
+    /**
+     * The heart of the fix: which SECTION does this dep belong in?
+     *
+     * A dep is test-only when the scan saw it imported by test/dev files and by NO
+     * production file. Anything else — including a dep we never saw imported at all (it
+     * may be loaded reflectively at runtime) — is treated as production, so this can
+     * never push a runtime-required package out of `dependencies`.
+     */
+    classifyOneDep(depProjectName, depPackageName, declared, usage, classification) {
+        if (usage.isTestOnly(depPackageName)) {
+            if (!declared.isDeclared(depPackageName)) {
+                classification.missingTestOnlyDeps.push(depProjectName);
+                return;
             }
+            if (declared.dependencies.includes(depPackageName)) {
+                classification.testOnlyInProdDependencies.push(depProjectName);
+            }
+            return;
+        }
+        if (declared.isProductionDeclared(depPackageName))
+            return;
+        if (declared.isDevDeclared(depPackageName)) {
+            classification.prodDepsOnlyInDev.push(depProjectName);
+            return;
         }
+        classification.missingInPackageJson.push(depProjectName);
+    }
+    validateSingleProject(projectName, entry, projectRoot, declared, usage, context) {
+        const transitiveClosure = this.computeTransitiveClosure(projectName, context.graph);
+        const classification = this.classifyDeps(declared, usage, entry, transitiveClosure, context);
+        const where = `Project ${projectName} (${projectRoot}/package.json)`;
+        const errors = this.buildErrors(where, classification, context.options);
+        const warnings = this.buildWarnings(where, projectName, classification, context);
+        const missing = classification.missingInPackageJson.concat(classification.missingTestOnlyDeps);
+        const result = new ProjectValidationResult(projectName, errors.length === 0, missing, classification.extraInPackageJson, classification.testOnlyInProdDependencies);
+        return new SingleProjectValidation(result, errors, warnings);
+    }
+    buildErrors(where, classification, options) {
+        const errors = [];
+        if (classification.missingInPackageJson.length > 0) {
+            errors.push(`${where} is missing dependencies: ${classification.missingInPackageJson.join(', ')}\n` +
+                `  These are imported by PRODUCTION source files.\n` +
+                `  Fix: Add them to package.json "dependencies"`);
+        }
+        if (classification.missingTestOnlyDeps.length > 0) {
+            errors.push(`${where} is missing dependencies: ${classification.missingTestOnlyDeps.join(', ')}\n` +
+                `  These are imported ONLY by test/dev files (*.spec.ts, __tests__/, test configs).\n` +
+                `  Fix: Add them to package.json "devDependencies" — NOT "dependencies", which would ship them to production`);
+        }
+        if (classification.prodDepsOnlyInDev.length > 0) {
+            errors.push(`${where} declares production imports only in devDependencies: ${classification.prodDepsOnlyInDev.join(', ')}\n` +
+                `  Production source files import them, so \`pnpm deploy --prod\` would omit them and the runtime would break.\n` +
+                `  Fix: Move them to package.json "dependencies"`);
+        }
+        const testOnlyInProd = classification.testOnlyInProdDependencies;
+        if (options.testOnlyDepMode === 'error' && testOnlyInProd.length > 0) {
+            errors.push(this.testOnlyInProdMessage(where, testOnlyInProd));
+        }
+        return errors;
+    }
+    buildWarnings(where, projectName, classification, context) {
+        const warnings = [];
+        const testOnlyInProd = classification.testOnlyInProdDependencies;
+        if (context.options.testOnlyDepMode === 'warn' && testOnlyInProd.length > 0) {
+            warnings.push(this.testOnlyInProdMessage(where, testOnlyInProd));
+        }
+        // Unreachable workspace extras are WARN-ONLY: they may be real runtime deps that nx's
+        // import analysis can't see (peerDependency / generated client). Never error — that is
+        // the runtime-validity trap. We surface them so genuine drift is still visible.
+        for (const extraPkg of classification.extraWorkspaceDeps) {
+            const extraProject = context.packageToProject.get(extraPkg);
+            warnings.push(`${where} has "${extraPkg}" but the architecture graph has no path ${projectName} → ${extraProject}.\n` +
+                `  This is allowed (it may be a runtime-only/peer dependency). If it is genuinely unused, you may remove it.`);
+        }
+        return warnings;
+    }
+    testOnlyInProdMessage(where, deps) {
+        return (`${where} lists test-only packages in "dependencies": ${deps.join(', ')}\n` +
+            `  No production source file imports them — only test/dev files do — yet \`pnpm deploy --prod\`\n` +
+            `  installs the "dependencies" closure, so this ships test machinery (fakes, auth-bypass hooks,\n` +
+            `  canned credentials) into the production image.\n` +
+            `  Fix: Move them to package.json "devDependencies"`);
+    }
+    async validate(graph, workspaceRoot, options) {
+        const projectGraph = await (0, devkit_1.createProjectGraphAsync)();
+        const projectsConfig = (0, devkit_1.readProjectsConfigurationFromProjectGraph)(projectGraph);
+        const projectToPackage = this.buildProjectToPackageMap(workspaceRoot, projectsConfig);
+        const packageToProject = new Map();
+        for (const pair of projectToPackage.entries()) {
+            packageToProject.set(pair[1], pair[0]);
+        }
+        const context = new ValidationContext(graph, projectToPackage, packageToProject, options);
+        const errors = [];
+        const warnings = [];
+        const projectResults = [];
+        for (const graphPair of Object.entries(graph)) {
+            const projectName = graphPair[0];
+            const entry = graphPair[1];
+            const projectConfig = projectsConfig.projects[projectName];
+            if (!projectConfig)
+                continue;
+            const declared = this.readDeclaredDeps(workspaceRoot, projectConfig.root);
+            if (declared === null)
+                continue;
+            const usage = this.scanner.scan(path.join(workspaceRoot, projectConfig.root));
+            const validation = this.validateSingleProject(projectName, entry, projectConfig.root, declared, usage, context);
+            projectResults.push(validation.result);
+            errors.push(...validation.errors);
+            warnings.push(...validation.warnings);
+        }
+        return new ValidationResult(errors.length === 0, errors, warnings, projectResults);
     }
-    return closure;
-}
-function classifyDeps(packageJsonDeps, entry, transitiveClosure, projectToPackage, packageToProject) {
-    const missingInPackageJson = [];
-    for (const depProjectName of entry.dependsOn) {
-        const depPackageName = projectToPackage.get(depProjectName) || depProjectName;
-        if (!packageJsonDeps.includes(depPackageName)) {
-            missingInPackageJson.push(depProjectName);
-        }
-    }
-    // Workspace extras are OK if reachable via transitive closure (matches the
-    // ESLint enforce-architecture rule which also allows transitive imports).
-    // Only flag extras that are NOT reachable at all — real graph drift.
-    const extraInPackageJson = [];
-    const extraWorkspaceDeps = [];
-    for (const dep of packageJsonDeps) {
-        const depProjectName = packageToProject.get(dep);
-        if (depProjectName === undefined) {
-            extraInPackageJson.push(dep);
-            continue;
-        }
-        if (entry.dependsOn.includes(depProjectName))
-            continue;
-        if (transitiveClosure.has(depProjectName))
-            continue;
-        extraWorkspaceDeps.push(dep);
-    }
-    return { missingInPackageJson, extraInPackageJson, extraWorkspaceDeps };
-}
-function validateSingleProject(projectName, entry, projectRoot, packageJsonDeps, graph, projectToPackage, packageToProject) {
-    const transitiveClosure = computeTransitiveClosure(projectName, graph);
-    const classification = classifyDeps(packageJsonDeps, entry, transitiveClosure, projectToPackage, packageToProject);
-    const errors = [];
-    if (classification.missingInPackageJson.length > 0) {
-        errors.push(`Project ${projectName} (${projectRoot}/package.json) is missing dependencies: ${classification.missingInPackageJson.join(', ')}\n` +
-            `  Fix: Add these to package.json dependencies`);
-    }
-    // Unreachable workspace extras are WARN-ONLY: they may be real runtime deps that nx's
-    // import analysis can't see (peerDependency / generated client). Never error — that is
-    // the runtime-validity trap. We surface them so genuine drift is still visible.
-    const warnings = [];
-    for (const extraPkg of classification.extraWorkspaceDeps) {
-        const extraProject = packageToProject.get(extraPkg);
-        warnings.push(`Project ${projectName} (${projectRoot}/package.json) has "${extraPkg}" but the architecture graph has no path ${projectName} → ${extraProject}.\n` +
-            `  This is allowed (it may be a runtime-only/peer dependency). If it is genuinely unused, you may remove it.`);
-    }
-    // extraWorkspaceDeps do NOT affect validity — only missing (additive-fix) errors do.
-    const valid = classification.missingInPackageJson.length === 0;
-    return {
-        result: {
-            project: projectName,
-            valid,
-            missingInPackageJson: classification.missingInPackageJson,
-            extraInPackageJson: classification.extraInPackageJson,
-        },
-        errors,
-        warnings,
-    };
 }
-async function validatePackageJsonDependencies(graph, workspaceRoot) {
-    const projectGraph = await (0, devkit_1.createProjectGraphAsync)();
-    const projectsConfig = (0, devkit_1.readProjectsConfigurationFromProjectGraph)(projectGraph);
-    const projectToPackage = buildProjectToPackageMap(workspaceRoot, projectsConfig);
-    const packageToProject = new Map();
-    for (const [projName, pkgName] of projectToPackage.entries()) {
-        packageToProject.set(pkgName, projName);
-    }
-    const errors = [];
-    const warnings = [];
-    const projectResults = [];
-    for (const [projectName, entry] of Object.entries(graph)) {
-        const projectConfig = projectsConfig.projects[projectName];
-        if (!projectConfig)
-            continue;
-        const packageJsonDeps = readPackageJsonDeps(workspaceRoot, projectConfig.root);
-        if (packageJsonDeps === null)
-            continue;
-        const validation = validateSingleProject(projectName, entry, projectConfig.root, packageJsonDeps, graph, projectToPackage, packageToProject);
-        projectResults.push(validation.result);
-        errors.push(...validation.errors);
-        warnings.push(...validation.warnings);
-    }
-    return { valid: errors.length === 0, errors, warnings, projectResults };
+exports.PackageValidator = PackageValidator;
+/**
+ * Validate that package.json dependencies cover the dependency graph AND that each dep
+ * is declared in the correct section (dependencies vs devDependencies).
+ *
+ * @param graph - Enhanced graph with project dependencies (uses project names)
+ * @param workspaceRoot - Absolute path to workspace root
+ * @param options - Strictness of the "test-only dep in the production closure" check
+ */
+// webpieces-disable no-function-outside-class -- stable module entry point imported by the executor; it only delegates to PackageValidator
+async function validatePackageJsonDependencies(graph, workspaceRoot, options = new PackageValidatorOptions()) {
+    return new PackageValidator().validate(graph, workspaceRoot, options);
 }
 //# sourceMappingURL=package-validator.js.map