@webpieces/nx-webpieces-rules 0.4.465 → 0.4.467

package/src/lib/dep-usage-scanner.js

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Dep Usage Scanner
+ *
+ * Answers ONE question for a project: "is package X reached from production
+ * source, or ONLY from test/dev files?"
+ *
+ * WHY this exists: nx derives graph edges from ALL TypeScript sources, specs
+ * included. Without this scan, a package imported only by `*.spec.ts` looks
+ * identical to a package imported by a controller, so the validator forces it
+ * into `dependencies` — and `pnpm deploy --prod` then ships test machinery
+ * (auth-bypass hooks, canned credentials, fakes) into the production image.
+ * Splitting the scan by file kind lets `devDependencies` be the REQUIRED home
+ * for test-only packages.
+ *
+ * The scan is deliberately conservative: a package is "test-only" ONLY when it
+ * is imported by at least one test/dev file and by ZERO production files. Any
+ * doubt (no import found at all, e.g. a runtime-only/reflection dependency)
+ * resolves to "production", so this can never push a runtime-required package
+ * out of `dependencies`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DepUsageScanner = exports.DepUsage = void 0;
+const tslib_1 = require("tslib");
+const fs = tslib_1.__importStar(require("fs"));
+const path = tslib_1.__importStar(require("path"));
+const toError_1 = require("../toError");
+/** Directories never worth scanning (build output, vendored code, VCS). */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    'dist',
+    'build',
+    'out-tsc',
+    'coverage',
+    '.nx',
+    '.git',
+    'tmp',
+    '.angular',
+]);
+/** Source extensions whose imports we understand. */
+const SOURCE_EXTENSIONS = new Set([
+    '.ts',
+    '.tsx',
+    '.mts',
+    '.cts',
+    '.js',
+    '.jsx',
+    '.mjs',
+    '.cjs',
+]);
+/**
+ * Directory names that make everything below them test/dev-only.
+ * Kept tight on purpose — a false "this is a test dir" would let a real
+ * production import be classified as test-only.
+ */
+const TEST_DIR_NAMES = new Set([
+    '__tests__',
+    '__mocks__',
+    '__fixtures__',
+    'test',
+    'tests',
+    'e2e',
+    'e2e-tests',
+]);
+/** `foo.spec.ts`, `foo.test.tsx`, `foo-e2e.spec.mts`, `foo.testkit.ts`, ... */
+const TEST_FILE_RE = /[.-](spec|test|e2e|testkit|mock|mocks|fixture|fixtures)\.[cm]?[jt]sx?$/;
+/** Tooling config/bootstrap files: dev-time by definition. */
+const DEV_CONFIG_RE = /^(vitest|vite|jest|playwright|cypress|karma|webpack|rollup|eslint|prettier)\.[\w.-]*config\.[cm]?[jt]s$/;
+/** `jest.setup.ts`, `vitest.setup.ts`, `test-setup.ts`, ... */
+const DEV_SETUP_RE = /^([\w-]*[.-])?(setup|test-setup)\.[cm]?[jt]s$/;
+/** Bare-import extraction: `from 'x'`, `import 'x'`, `import('x')`, `require('x')`. */
+const IMPORT_RE = /(?:\bfrom\s*|\bimport\s*|\brequire\s*\(\s*|\bimport\s*\(\s*)['"]([^'"]+)['"]/g;
+/**
+ * Which packages a project reaches from production code vs. only from test/dev code.
+ * Data-only: no logic lives here (see CLAUDE.md — data structures are classes).
+ */
+class DepUsage {
+    prodPackages;
+    testPackages;
+    constructor(prodPackages, testPackages) {
+        this.prodPackages = prodPackages;
+        this.testPackages = testPackages;
+    }
+    /** True when the package is imported by tests and by no production file. */
+    isTestOnly(packageName) {
+        return this.testPackages.has(packageName) && !this.prodPackages.has(packageName);
+    }
+    /** True when we saw the package in NO file at all (kind is unknown → treat as prod). */
+    isUnseen(packageName) {
+        return !this.testPackages.has(packageName) && !this.prodPackages.has(packageName);
+    }
+}
+exports.DepUsage = DepUsage;
+class DepUsageScanner {
+    /**
+     * Walk a project directory and record every bare import specifier, bucketed
+     * by whether the importing file is production or test/dev.
+     */
+    scan(absProjectDir) {
+        const usage = new DepUsage(new Set(), new Set());
+        if (!fs.existsSync(absProjectDir))
+            return usage;
+        this.walk(absProjectDir, absProjectDir, usage);
+        return usage;
+    }
+    /**
+     * Is this path a test/dev file? Path is relative to the project root and
+     * uses either separator.
+     */
+    isDevFile(relPath) {
+        const normalized = relPath.split(path.sep).join('/');
+        const segments = normalized.split('/');
+        const fileName = segments[segments.length - 1];
+        for (const dir of segments.slice(0, -1)) {
+            if (TEST_DIR_NAMES.has(dir))
+                return true;
+        }
+        if (TEST_FILE_RE.test(fileName))
+            return true;
+        if (DEV_CONFIG_RE.test(fileName))
+            return true;
+        if (DEV_SETUP_RE.test(fileName))
+            return true;
+        return false;
+    }
+    /**
+     * The package a bare specifier belongs to, or null for relative/absolute
+     * paths and node: builtins. `@scope/pkg/sub` → `@scope/pkg`; `pkg/sub` → `pkg`.
+     */
+    toPackageName(specifier) {
+        if (specifier.length === 0)
+            return null;
+        if (specifier.startsWith('.') || specifier.startsWith('/'))
+            return null;
+        if (specifier.startsWith('node:'))
+            return null;
+        const parts = specifier.split('/');
+        if (specifier.startsWith('@')) {
+            if (parts.length < 2)
+                return null;
+            return `${parts[0]}/${parts[1]}`;
+        }
+        return parts[0];
+    }
+    walk(absDir, projectRoot, usage) {
+        const entries = fs.readdirSync(absDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const absPath = path.join(absDir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                this.walk(absPath, projectRoot, usage);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (!SOURCE_EXTENSIONS.has(path.extname(entry.name)))
+                continue;
+            this.scanFile(absPath, projectRoot, usage);
+        }
+    }
+    scanFile(absPath, projectRoot, usage) {
+        const source = this.readFile(absPath);
+        if (source === null)
+            return;
+        const relPath = path.relative(projectRoot, absPath);
+        const bucket = this.isDevFile(relPath) ? usage.testPackages : usage.prodPackages;
+        for (const packageName of this.extractPackageNames(source)) {
+            bucket.add(packageName);
+        }
+    }
+    extractPackageNames(source) {
+        const names = [];
+        IMPORT_RE.lastIndex = 0;
+        let match = IMPORT_RE.exec(source);
+        while (match !== null) {
+            const packageName = this.toPackageName(match[1]);
+            if (packageName !== null)
+                names.push(packageName);
+            match = IMPORT_RE.exec(source);
+        }
+        return names;
+    }
+    readFile(absPath) {
+        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions
+        try {
+            return fs.readFileSync(absPath, 'utf-8');
+        }
+        catch (err) {
+            const error = (0, toError_1.toError)(err);
+            // An unreadable file cannot change the classification of a package; skipping it
+            // only ever makes the scan MORE conservative (fewer test-only classifications).
+            console.warn(`Could not read ${absPath} while classifying deps: ${error.message}`);
+            return null;
+        }
+    }
+}
+exports.DepUsageScanner = DepUsageScanner;
+//# sourceMappingURL=dep-usage-scanner.js.map

package/src/lib/dep-usage-scanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dep-usage-scanner.js","sourceRoot":"","sources":["../../../../../../packages/tooling/nx-webpieces-rules/src/lib/dep-usage-scanner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Dep Usage Scanner\n *\n * Answers ONE question for a project: \"is package X reached from production\n * source, or ONLY from test/dev files?\"\n *\n * WHY this exists: nx derives graph edges from ALL TypeScript sources, specs\n * included. Without this scan, a package imported only by `*.spec.ts` looks\n * identical to a package imported by a controller, so the validator forces it\n * into `dependencies` — and `pnpm deploy --prod` then ships test machinery\n * (auth-bypass hooks, canned credentials, fakes) into the production image.\n * Splitting the scan by file kind lets `devDependencies` be the REQUIRED home\n * for test-only packages.\n *\n * The scan is deliberately conservative: a package is \"test-only\" ONLY when it\n * is imported by at least one test/dev file and by ZERO production files. Any\n * doubt (no import found at all, e.g. a runtime-only/reflection dependency)\n * resolves to \"production\", so this can never push a runtime-required package\n * out of `dependencies`.\n */\n\nimport * as fs from 'fs';\nimport * as path from 'path';\nimport { toError } from '../toError';\n\n/** Directories never worth scanning (build output, vendored code, VCS). */\nconst SKIP_DIRS = new Set([\n    'node_modules',\n    'dist',\n    'build',\n    'out-tsc',\n    'coverage',\n    '.nx',\n    '.git',\n    'tmp',\n    '.angular',\n]);\n\n/** Source extensions whose imports we understand. */\nconst SOURCE_EXTENSIONS = new Set([\n    '.ts',\n    '.tsx',\n    '.mts',\n    '.cts',\n    '.js',\n    '.jsx',\n    '.mjs',\n    '.cjs',\n]);\n\n/**\n * Directory names that make everything below them test/dev-only.\n * Kept tight on purpose — a false \"this is a test dir\" would let a real\n * production import be classified as test-only.\n */\nconst TEST_DIR_NAMES = new Set([\n    '__tests__',\n    '__mocks__',\n    '__fixtures__',\n    'test',\n    'tests',\n    'e2e',\n    'e2e-tests',\n]);\n\n/** `foo.spec.ts`, `foo.test.tsx`, `foo-e2e.spec.mts`, `foo.testkit.ts`, ... */\nconst TEST_FILE_RE = /[.-](spec|test|e2e|testkit|mock|mocks|fixture|fixtures)\\.[cm]?[jt]sx?$/;\n\n/** Tooling config/bootstrap files: dev-time by definition. */\nconst DEV_CONFIG_RE =\n    /^(vitest|vite|jest|playwright|cypress|karma|webpack|rollup|eslint|prettier)\\.[\\w.-]*config\\.[cm]?[jt]s$/;\n\n/** `jest.setup.ts`, `vitest.setup.ts`, `test-setup.ts`, ... */\nconst DEV_SETUP_RE = /^([\\w-]*[.-])?(setup|test-setup)\\.[cm]?[jt]s$/;\n\n/** Bare-import extraction: `from 'x'`, `import 'x'`, `import('x')`, `require('x')`. */\nconst IMPORT_RE =\n    /(?:\\bfrom\\s*|\\bimport\\s*|\\brequire\\s*\\(\\s*|\\bimport\\s*\\(\\s*)['\"]([^'\"]+)['\"]/g;\n\n/**\n * Which packages a project reaches from production code vs. only from test/dev code.\n * Data-only: no logic lives here (see CLAUDE.md — data structures are classes).\n */\nexport class DepUsage {\n    prodPackages: Set<string>;\n    testPackages: Set<string>;\n\n    constructor(prodPackages: Set<string>, testPackages: Set<string>) {\n        this.prodPackages = prodPackages;\n        this.testPackages = testPackages;\n    }\n\n    /** True when the package is imported by tests and by no production file. */\n    isTestOnly(packageName: string): boolean {\n        return this.testPackages.has(packageName) && !this.prodPackages.has(packageName);\n    }\n\n    /** True when we saw the package in NO file at all (kind is unknown → treat as prod). */\n    isUnseen(packageName: string): boolean {\n        return !this.testPackages.has(packageName) && !this.prodPackages.has(packageName);\n    }\n}\n\nexport class DepUsageScanner {\n    /**\n     * Walk a project directory and record every bare import specifier, bucketed\n     * by whether the importing file is production or test/dev.\n     */\n    scan(absProjectDir: string): DepUsage {\n        const usage = new DepUsage(new Set<string>(), new Set<string>());\n        if (!fs.existsSync(absProjectDir)) return usage;\n        this.walk(absProjectDir, absProjectDir, usage);\n        return usage;\n    }\n\n    /**\n     * Is this path a test/dev file? Path is relative to the project root and\n     * uses either separator.\n     */\n    isDevFile(relPath: string): boolean {\n        const normalized = relPath.split(path.sep).join('/');\n        const segments = normalized.split('/');\n        const fileName = segments[segments.length - 1];\n\n        for (const dir of segments.slice(0, -1)) {\n            if (TEST_DIR_NAMES.has(dir)) return true;\n        }\n        if (TEST_FILE_RE.test(fileName)) return true;\n        if (DEV_CONFIG_RE.test(fileName)) return true;\n        if (DEV_SETUP_RE.test(fileName)) return true;\n        return false;\n    }\n\n    /**\n     * The package a bare specifier belongs to, or null for relative/absolute\n     * paths and node: builtins. `@scope/pkg/sub` → `@scope/pkg`; `pkg/sub` → `pkg`.\n     */\n    toPackageName(specifier: string): string | null {\n        if (specifier.length === 0) return null;\n        if (specifier.startsWith('.') || specifier.startsWith('/')) return null;\n        if (specifier.startsWith('node:')) return null;\n        const parts = specifier.split('/');\n        if (specifier.startsWith('@')) {\n            if (parts.length < 2) return null;\n            return `${parts[0]}/${parts[1]}`;\n        }\n        return parts[0];\n    }\n\n    private walk(absDir: string, projectRoot: string, usage: DepUsage): void {\n        const entries = fs.readdirSync(absDir, { withFileTypes: true });\n        for (const entry of entries) {\n            const absPath = path.join(absDir, entry.name);\n            if (entry.isDirectory()) {\n                if (SKIP_DIRS.has(entry.name)) continue;\n                this.walk(absPath, projectRoot, usage);\n                continue;\n            }\n            if (!entry.isFile()) continue;\n            if (!SOURCE_EXTENSIONS.has(path.extname(entry.name))) continue;\n            this.scanFile(absPath, projectRoot, usage);\n        }\n    }\n\n    private scanFile(absPath: string, projectRoot: string, usage: DepUsage): void {\n        const source = this.readFile(absPath);\n        if (source === null) return;\n        const relPath = path.relative(projectRoot, absPath);\n        const bucket = this.isDevFile(relPath) ? usage.testPackages : usage.prodPackages;\n        for (const packageName of this.extractPackageNames(source)) {\n            bucket.add(packageName);\n        }\n    }\n\n    private extractPackageNames(source: string): string[] {\n        const names: string[] = [];\n        IMPORT_RE.lastIndex = 0;\n        let match = IMPORT_RE.exec(source);\n        while (match !== null) {\n            const packageName = this.toPackageName(match[1]);\n            if (packageName !== null) names.push(packageName);\n            match = IMPORT_RE.exec(source);\n        }\n        return names;\n    }\n\n    private readFile(absPath: string): string | null {\n        // eslint-disable-next-line @webpieces/no-unmanaged-exceptions\n        try {\n            return fs.readFileSync(absPath, 'utf-8');\n        } catch (err: unknown) {\n            const error = toError(err);\n            // An unreadable file cannot change the classification of a package; skipping it\n            // only ever makes the scan MORE conservative (fewer test-only classifications).\n            console.warn(`Could not read ${absPath} while classifying deps: ${error.message}`);\n            return null;\n        }\n    }\n}\n"]}

package/src/lib/package-validator.d.ts

@@ -1,50 +1,186 @@
 /**
  * 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.
  */
+import { DepUsage } from './dep-usage-scanner';
+/**
+ * How hard to push back when a test-only package sits in `dependencies`
+ * (i.e. inside the production deploy closure).
+ *
+ *  - 'error' (default): fails the build. This is the guardrail the security bug asked for.
+ *  - 'warn': reports it without failing — the migration setting for a repo that needs a
+ *    few releases to clean up its package.json files.
+ *  - 'off': skip the check entirely.
+ *
+ * Missing deps, and production imports declared only in `devDependencies`, ALWAYS error:
+ * their fix is unambiguous and the alternative is a broken runtime.
+ */
+export type TestOnlyDepMode = 'error' | 'warn' | 'off';
+/**
+ * Options for {@link validatePackageJsonDependencies}. Data-only (CLAUDE.md: data
+ * structures are classes, never anonymous object literals).
+ */
+export declare class PackageValidatorOptions {
+    testOnlyDepMode: TestOnlyDepMode;
+    constructor(testOnlyDepMode?: TestOnlyDepMode);
+}
 /**
  * Validation result for a single project
  */
-export interface ProjectValidationResult {
+export declare class ProjectValidationResult {
     project: string;
     valid: boolean;
     missingInPackageJson: string[];
     extraInPackageJson: string[];
+    /** Graph deps that are test-only but declared in `dependencies` (production closure). */
+    testOnlyInProdDependencies: string[];
+    constructor(project: string, valid: boolean, missingInPackageJson: string[], extraInPackageJson: string[], testOnlyInProdDependencies: string[]);
 }
 /**
  * Overall validation result
  *
- * `errors` fail the build; their only fix is ADDITIVE ("add to package.json"), so they can
- * never push a user toward removing a runtime-required dependency.
+ * `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.
+ * `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.
  */
-export interface ValidationResult {
+export declare class ValidationResult {
     valid: boolean;
     errors: string[];
     warnings: string[];
     projectResults: ProjectValidationResult[];
+    constructor(valid: boolean, errors: string[], warnings: string[], projectResults: ProjectValidationResult[]);
 }
 /**
- * Validate that package.json dependencies match the dependency graph
- *
- * For each project in the graph:
- * - Check that all graph dependencies exist in package.json
- * - Maps project names to package names for accurate comparison
- *
- * @param graph - Enhanced graph with project dependencies (uses project names)
- * @param workspaceRoot - Absolute path to workspace root
- * @returns Validation result with errors if any
+ * 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).
+ */
+export declare class DeclaredDeps {
+    dependencies: string[];
+    devDependencies: string[];
+    peerDependencies: string[];
+    constructor(dependencies: string[], devDependencies: string[], peerDependencies: string[]);
+    /** Every declared package name, deduped and sorted (all three sections). */
+    all(): string[];
+    /** Declared somewhere that survives `pnpm deploy --prod`. */
+    isProductionDeclared(packageName: string): boolean;
+    isDevDeclared(packageName: string): boolean;
+    isDeclared(packageName: string): boolean;
+}
+/**
+ * Graph shape produced by graph-sorter (an input contract we never construct here).
  */
 interface GraphEntry {
     level: number;
     dependsOn: string[];
 }
-export declare function validatePackageJsonDependencies(graph: Record<string, GraphEntry>, workspaceRoot: string): Promise<ValidationResult>;
+/**
+ * Per-project classification of graph deps against what package.json declares.
+ */
+declare class DepClassification {
+    /** Production-reached deps absent from `dependencies`/`peerDependencies`. */
+    missingInPackageJson: string[];
+    /** Production-reached deps declared ONLY in `devDependencies` (runtime would break). */
+    prodDepsOnlyInDev: string[];
+    /** Test-only deps declared in no section at all. */
+    missingTestOnlyDeps: string[];
+    /** Test-only deps sitting in `dependencies` — i.e. shipped to production. */
+    testOnlyInProdDependencies: string[];
+    /** Non-workspace (third-party) package.json entries — informational only. */
+    extraInPackageJson: string[];
+    /** Workspace entries the graph cannot reach at all — warn-only drift. */
+    extraWorkspaceDeps: string[];
+}
+declare class SingleProjectValidation {
+    result: ProjectValidationResult;
+    errors: string[];
+    warnings: string[];
+    constructor(result: ProjectValidationResult, errors: string[], warnings: string[]);
+}
+/**
+ * The per-workspace lookups a single-project validation needs, passed as one object
+ * so method signatures stay readable.
+ */
+declare class ValidationContext {
+    graph: Record<string, GraphEntry>;
+    projectToPackage: Map<string, string>;
+    packageToProject: Map<string, string>;
+    options: PackageValidatorOptions;
+    constructor(graph: Record<string, GraphEntry>, projectToPackage: Map<string, string>, packageToProject: Map<string, string>, options: PackageValidatorOptions);
+}
+export declare class PackageValidator {
+    private readonly scanner;
+    /**
+     * 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: string, projectRoot: string): DeclaredDeps | null;
+    private namesOf;
+    /**
+     * Build map of project names to their package names
+     * e.g., "core-util" → "@webpieces/core-util"
+     */
+    buildProjectToPackageMap(workspaceRoot: string, projectsConfig: any): Map<string, string>;
+    private readPackageName;
+    /**
+     * 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: string, graph: Record<string, GraphEntry>): Set<string>;
+    /**
+     * 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: DeclaredDeps, usage: DepUsage, entry: GraphEntry, transitiveClosure: Set<string>, context: ValidationContext): DepClassification;
+    /**
+     * 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`.
+     */
+    private classifyOneDep;
+    validateSingleProject(projectName: string, entry: GraphEntry, projectRoot: string, declared: DeclaredDeps, usage: DepUsage, context: ValidationContext): SingleProjectValidation;
+    private buildErrors;
+    private buildWarnings;
+    private testOnlyInProdMessage;
+    validate(graph: Record<string, GraphEntry>, workspaceRoot: string, options: PackageValidatorOptions): Promise<ValidationResult>;
+}
+/**
+ * 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
+ */
+export declare function validatePackageJsonDependencies(graph: Record<string, GraphEntry>, workspaceRoot: string, options?: PackageValidatorOptions): Promise<ValidationResult>;
 export {};