mocode-ai 0.7.0 → 0.7.2

package/dist/verification/index.js

@@ -0,0 +1,333 @@
+import path from 'node:path';
+import { getSandboxRoot } from '../sandbox/index.js';
+import { checkPermission } from '../permissions/index.js';
+import { beginWorkspaceMutation, endWorkspaceMutation, getCurrentTurnMutationState, } from '../rollback/index.js';
+import { formatCommandResult, runCommandRaw, runCommandTool, } from '../tools/builtins/run-command.js';
+import { resolveAffectedPackages } from './affected.js';
+import { discoverPackageValidationCommands } from './discovery.js';
+import { runChangedFileDiagnostics } from './diagnostics.js';
+import { fingerprintFiles, fingerprintValidation } from './fingerprint.js';
+import { runFilePostconditions } from './postconditions.js';
+import { discoverProjectProfile } from './profile.js';
+import { discoverTargetedTestCommands } from './targeted-tests.js';
+export { resolveAffectedPackages } from './affected.js';
+export { discoverPackageValidationCommand, discoverPackageValidationCommands, discoverValidationCommand, } from './discovery.js';
+export { clearProjectProfileCache, discoverProjectProfile } from './profile.js';
+const NON_CODE_EXTENSIONS = new Set([
+    '.md', '.mdx', '.txt', '.rst', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp',
+]);
+function isNonCodePath(file) {
+    return NON_CODE_EXTENSIONS.has(path.extname(file).toLowerCase());
+}
+function affectedSummary(affected) {
+    return affected?.packages.map((item) => ({
+        name: item.package.name,
+        root: item.package.root,
+        reasons: item.reasons,
+    })) ?? [];
+}
+function selectionOutput(affected) {
+    if (!affected || affected.packages.length === 0)
+        return '';
+    return [
+        'Affected packages:',
+        ...affected.packages.map((item) => {
+            const reasons = item.reasons.map((reason) => `${reason.kind}(${reason.changedPath})`).join(', ');
+            return `- ${item.package.name}: ${reasons}`;
+        }),
+    ].join('\n');
+}
+function stageOutput(stage) {
+    const scope = stage.packageName ? ` ${stage.packageName}` : '';
+    return `[${stage.level}${scope}] ${stage.status} (${stage.adapter})${stage.output ? `\n${stage.output}` : ''}`;
+}
+function highestLevel(stages) {
+    return stages.at(-1)?.level;
+}
+function aggregate(options) {
+    const state = getCurrentTurnMutationState();
+    const diagnostics = options.stages.flatMap((stage) => stage.diagnostics);
+    const terminal = options.stages.find((stage) => stage.status === 'failed' || stage.status === 'aborted');
+    const blockingSkip = options.stages.find((stage) => stage.status === 'skipped' && [
+        'permission_denied', 'no_validation_script', 'no_package_json',
+        'no_affected_package', 'invalid_changed_path',
+    ].includes(stage.skipReason ?? ''));
+    const v3Passed = options.stages.some((stage) => stage.level === 'V3' && stage.status === 'passed');
+    const substantivePassed = options.stages.some((stage) => stage.level !== 'V0' && stage.status === 'passed');
+    const status = terminal?.status ?? (blockingSkip || !substantivePassed ? 'skipped' : 'passed');
+    const level = terminal?.level ?? highestLevel(options.stages);
+    const output = [selectionOutput(options.affected), ...options.stages.map(stageOutput)].filter(Boolean).join('\n\n');
+    const commands = options.stages.flatMap((stage) => stage.command ? [stage.command] : []);
+    const skipReason = options.skipReason
+        ?? blockingSkip?.skipReason
+        ?? (status === 'skipped' ? 'no_applicable_validator' : undefined);
+    const fingerprint = fingerprintValidation({
+        root: options.root,
+        level,
+        status,
+        adapter: terminal?.adapter,
+        command: commands.join(' | '),
+        diagnostics,
+        output,
+    });
+    return {
+        status,
+        level,
+        script: commands.length === 1 ? options.packageResults?.[0]?.script : undefined,
+        command: commands.length > 0 ? commands.join(' | ') : undefined,
+        exitCode: terminal?.exitCode,
+        output,
+        durationMs: options.stages.reduce((sum, stage) => sum + stage.durationMs, 0),
+        skipReason,
+        diagnostics,
+        stages: options.stages,
+        verificationComplete: status === 'passed' && v3Passed && !blockingSkip,
+        fingerprint,
+        inputFingerprint: options.inputFingerprint,
+        inputMutationVersion: options.inputMutationVersion,
+        affectedPackages: affectedSummary(options.affected),
+        rejectedChangedFiles: options.affected?.rejected,
+        packageResults: options.packageResults,
+        changedFiles: state.changedFiles.map((item) => item.path),
+        mutationVersion: state.version,
+    };
+}
+function emptyResult(root, reason, inputMutationVersion, changedFiles) {
+    const inputFingerprint = fingerprintFiles(root, changedFiles);
+    return aggregate({ root, inputMutationVersion, inputFingerprint, stages: [], skipReason: reason });
+}
+function skippedStage(level, adapter, reason, output, inputFingerprint, packageName) {
+    return {
+        level,
+        status: 'skipped',
+        adapter,
+        packageName,
+        diagnostics: [],
+        output,
+        durationMs: 0,
+        skipReason: reason,
+        inputFingerprint,
+    };
+}
+function commandSource(command) {
+    return command.script;
+}
+async function executeSelectedCommand(item, root, inputFingerprint, signal, callbacks) {
+    const relativeCwd = path.relative(root, item.command.cwd) || '.';
+    const permissionArgs = { command: item.command.command, path: relativeCwd };
+    const permission = await checkPermission(runCommandTool, permissionArgs, signal, { projectRoot: root });
+    callbacks.onPermissionDecision?.({
+        decision: permission,
+        tool: runCommandTool.name,
+        arguments: permissionArgs,
+    });
+    if (signal?.aborted) {
+        return {
+            stage: {
+                level: item.level, status: 'aborted', adapter: item.adapter,
+                packageName: item.affected.package.name, command: item.command.command,
+                diagnostics: [], output: 'Validation aborted.', durationMs: 0, inputFingerprint,
+            },
+        };
+    }
+    if (permission === 'deny') {
+        return {
+            stage: skippedStage(item.level, item.adapter, 'permission_denied', 'Validation command permission was denied.', inputFingerprint, item.affected.package.name),
+        };
+    }
+    callbacks.onCommandStart?.(`[${item.level} ${item.affected.package.name}] ${item.command.command}`);
+    const capture = beginWorkspaceMutation();
+    let raw;
+    try {
+        raw = await runCommandRaw(item.command.command, 120000, signal, item.command.cwd);
+    }
+    finally {
+        endWorkspaceMutation(capture, 'automatic_validation');
+    }
+    const status = raw.status === 'passed' ? 'passed' : raw.status === 'aborted' ? 'aborted' : 'failed';
+    const output = formatCommandResult(raw);
+    const diagnostics = status === 'failed'
+        ? [{
+                level: item.level,
+                source: commandSource(item.command),
+                severity: 'error',
+                code: raw.status.toUpperCase(),
+                packageName: item.affected.package.name,
+                message: output,
+            }]
+        : [];
+    const stage = {
+        level: item.level,
+        status,
+        adapter: item.adapter,
+        packageName: item.affected.package.name,
+        command: item.command.command,
+        exitCode: raw.exitCode,
+        diagnostics,
+        output,
+        durationMs: raw.durationMs,
+        inputFingerprint,
+    };
+    stage.fingerprint = fingerprintValidation({
+        root,
+        level: stage.level,
+        status: stage.status,
+        adapter: stage.adapter,
+        command: stage.command,
+        diagnostics,
+        output,
+    });
+    return {
+        stage,
+        packageResult: {
+            packageName: item.affected.package.name,
+            packageRoot: item.affected.package.root,
+            level: item.level,
+            status,
+            script: item.command.script,
+            command: item.command.command,
+            exitCode: raw.exitCode,
+            output,
+            durationMs: raw.durationMs,
+        },
+    };
+}
+async function runCommands(selected, root, inputFingerprint, signal, callbacks, stages, packageResults) {
+    for (const item of selected) {
+        const result = await executeSelectedCommand(item, root, inputFingerprint, signal, callbacks);
+        stages.push(result.stage);
+        if (result.packageResult)
+            packageResults.push(result.packageResult);
+        if (result.stage.status !== 'passed')
+            return false;
+    }
+    return true;
+}
+function resolveProfile(root, validationPaths) {
+    try {
+        const profile = discoverProjectProfile(root);
+        return {
+            profile,
+            affected: resolveAffectedPackages(profile, validationPaths, { changedFilesBase: process.cwd() }),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/** Run V0→V3 in cost order and stop at the first actionable failure. */
+export async function runAutomaticValidation(signal, callbacks = {}) {
+    const before = getCurrentTurnMutationState();
+    const root = path.resolve(getSandboxRoot() ?? process.cwd());
+    const changedPaths = before.changedFiles.map((item) => item.path);
+    if (changedPaths.length === 0)
+        return emptyResult(root, 'no_changes', before.version, changedPaths);
+    const validationPaths = changedPaths.filter((item) => !isNonCodePath(item));
+    if (validationPaths.length === 0) {
+        return emptyResult(root, 'non_code_changes', before.version, changedPaths);
+    }
+    const inputFingerprint = fingerprintFiles(root, validationPaths);
+    const { profile, affected } = resolveProfile(root, validationPaths);
+    const stages = [];
+    const packageResults = [];
+    const finish = (skipReason) => aggregate({
+        root,
+        inputMutationVersion: before.version,
+        inputFingerprint,
+        stages,
+        affected,
+        packageResults,
+        skipReason,
+    });
+    const v0 = await runFilePostconditions(root, validationPaths, inputFingerprint);
+    stages.push(v0);
+    if (v0.status === 'failed')
+        return finish();
+    const v1 = await runChangedFileDiagnostics(root, validationPaths, inputFingerprint);
+    stages.push(v1);
+    if (v1.status === 'failed')
+        return finish();
+    if (!profile || !affected) {
+        stages.push(skippedStage('V3', 'package-scripts', 'no_package_json', 'No project package profile is available.', inputFingerprint));
+        return finish('no_package_json');
+    }
+    if (affected.rejected.length > 0) {
+        stages.push(skippedStage('V3', 'affected-packages', 'invalid_changed_path', affected.rejected.map((item) => `Rejected changed path: ${item.input} (${item.reason})`).join('\n'), inputFingerprint));
+        return finish('invalid_changed_path');
+    }
+    if (affected.packages.length === 0) {
+        stages.push(skippedStage('V3', 'affected-packages', 'no_affected_package', 'No package owns the changed files.', inputFingerprint));
+        return finish('no_affected_package');
+    }
+    const targeted = discoverTargetedTestCommands(profile, affected.packages).map((item) => ({
+        affected: item.affected,
+        command: item.command,
+        level: 'V2',
+        adapter: item.adapter,
+    }));
+    if (targeted.length === 0) {
+        stages.push(skippedStage('V2', 'targeted-tests', 'no_targeted_tests', 'No reliable targeted tests were found.', inputFingerprint));
+    }
+    else if (!await runCommands(targeted, root, inputFingerprint, signal, callbacks, stages, packageResults)) {
+        return finish(stages.at(-1)?.skipReason === 'permission_denied' ? 'permission_denied' : undefined);
+    }
+    const selected = [];
+    for (const item of affected.packages) {
+        const commands = discoverPackageValidationCommands(profile, item.package);
+        if (commands.length === 0) {
+            stages.push(skippedStage('V3', 'package-scripts', 'no_validation_script', 'Affected package has no typecheck, build, or test script.', inputFingerprint, item.package.name));
+            continue;
+        }
+        selected.push(...commands.map((command) => ({
+            affected: item,
+            command,
+            level: 'V3',
+            adapter: `package-${command.script}`,
+        })));
+    }
+    const scriptOrder = { typecheck: 0, build: 1, test: 2 };
+    selected.sort((left, right) => scriptOrder[left.command.script] - scriptOrder[right.command.script]);
+    if (selected.length === 0)
+        return finish('no_validation_script');
+    await runCommands(selected, root, inputFingerprint, signal, callbacks, stages, packageResults);
+    return finish(stages.at(-1)?.skipReason === 'permission_denied' ? 'permission_denied' : undefined);
+}
+/** Create a run-scoped verifier cache; identical content never repeats expensive validation. */
+export function createAutomaticValidator() {
+    const cache = new Map();
+    const failureCounts = new Map();
+    return async (signal, callbacks = {}) => {
+        const state = getCurrentTurnMutationState();
+        const root = path.resolve(getSandboxRoot() ?? process.cwd());
+        const changedFiles = state.changedFiles.map((item) => item.path);
+        const inputFingerprint = fingerprintFiles(root, changedFiles);
+        const cacheKey = `${root}\0${inputFingerprint}`;
+        const cached = cache.get(cacheKey);
+        if (cached) {
+            const count = cached.status === 'failed'
+                ? (failureCounts.get(cached.fingerprint) ?? 1) + 1
+                : 1;
+            if (cached.status === 'failed')
+                failureCounts.set(cached.fingerprint, count);
+            return {
+                ...cached,
+                output: `${cached.output}\n\n[validation cache] Identical inputs reused; failure occurrence ${count}.`,
+                stages: cached.stages.map((stage) => ({ ...stage, cached: true, durationMs: 0 })),
+                durationMs: 0,
+                inputMutationVersion: state.version,
+                changedFiles,
+                mutationVersion: state.version,
+            };
+        }
+        const result = await runAutomaticValidation(signal, callbacks);
+        if (result.status === 'failed') {
+            const count = (failureCounts.get(result.fingerprint) ?? 0) + 1;
+            failureCounts.set(result.fingerprint, count);
+            if (count > 1) {
+                result.output += `\n\n[validation thrashing] The same failure fingerprint occurred ${count} times; change strategy before retrying.`;
+            }
+        }
+        cache.set(cacheKey, result);
+        return result;
+    };
+}

package/dist/verification/postconditions.js

@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function diagnostic(file, code, message) {
+    return {
+        level: 'V0',
+        source: 'postcondition',
+        severity: 'error',
+        code,
+        file,
+        message,
+    };
+}
+function parseJson(file, content) {
+    if (path.extname(file).toLowerCase() !== '.json')
+        return [];
+    try {
+        JSON.parse(content);
+        return [];
+    }
+    catch (error) {
+        return [diagnostic(file, 'INVALID_JSON', error instanceof Error ? error.message : String(error))];
+    }
+}
+/** Immediate read-after-write verification used by write_file and edit_file. */
+export async function verifyWrittenFile(file, expectedContent) {
+    const expectedHash = hash(Buffer.from(expectedContent, 'utf8'));
+    let actual;
+    try {
+        actual = await readFile(file);
+    }
+    catch (error) {
+        return {
+            status: 'failed',
+            expectedHash,
+            diagnostics: [diagnostic(file, 'POSTCONDITION_READ_FAILED', error instanceof Error ? error.message : String(error))],
+        };
+    }
+    const actualHash = hash(actual);
+    const diagnostics = actualHash === expectedHash
+        ? parseJson(file, actual.toString('utf8'))
+        : [diagnostic(file, 'CONTENT_HASH_MISMATCH', 'Content read after writing differs from the requested content.')];
+    return {
+        status: diagnostics.length === 0 ? 'passed' : 'failed',
+        expectedHash,
+        actualHash,
+        diagnostics,
+    };
+}
+/** Re-check current changed files before more expensive validation layers. */
+export async function runFilePostconditions(root, changedFiles, inputFingerprint) {
+    const startedAt = Date.now();
+    const diagnostics = [];
+    const hashes = [];
+    let checked = 0;
+    for (const changedFile of changedFiles) {
+        const absolute = path.resolve(process.cwd(), changedFile);
+        const relative = path.relative(root, absolute);
+        if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+            diagnostics.push(diagnostic(changedFile, 'OUTSIDE_PROJECT', 'Changed path is outside the project root.'));
+            continue;
+        }
+        try {
+            const fileStat = await stat(absolute);
+            if (!fileStat.isFile())
+                continue;
+            const content = await readFile(absolute);
+            checked += 1;
+            hashes.push(`${relative.replace(/\\/g, '/')}: ${hash(content)}`);
+            diagnostics.push(...parseJson(relative, content.toString('utf8')));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT') {
+                diagnostics.push(diagnostic(relative, 'POSTCONDITION_READ_FAILED', error instanceof Error ? error.message : String(error)));
+            }
+        }
+    }
+    const status = diagnostics.some((item) => item.severity === 'error') ? 'failed' : checked > 0 ? 'passed' : 'skipped';
+    return {
+        level: 'V0',
+        status,
+        adapter: 'file-postconditions',
+        diagnostics,
+        output: status === 'skipped' ? 'No current files require V0 postconditions.' : hashes.join('\n'),
+        durationMs: Date.now() - startedAt,
+        skipReason: status === 'skipped' ? 'no_current_files' : undefined,
+        inputFingerprint,
+    };
+}
+export function formatPostconditionFailure(result) {
+    return result.diagnostics
+        .map((item) => `[${item.code ?? 'V0_FAILED'}] ${item.file ?? ''}: ${item.message}`)
+        .join('\n');
+}

package/dist/verification/profile.js

@@ -0,0 +1,237 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import fg from 'fast-glob';
+const cache = new Map();
+const ROOT_INPUTS = [
+    'package.json', 'pnpm-workspace.yaml', 'pnpm-workspace.yml',
+    'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb',
+];
+const SOURCE_DIRS = ['src', 'lib', 'app'];
+const TEST_DIRS = ['test', 'tests', '__tests__', 'spec', 'src/test', 'src/tests', 'src/__tests__'];
+const GENERATED_DIRS = ['generated', 'gen', 'dist', 'build', 'coverage', 'src/generated', 'src/gen'];
+const VENDOR_DIRS = ['vendor', 'vendors', 'third_party', 'third-party', 'node_modules'];
+const FIXTURE_DIRS = ['fixture', 'fixtures', '__fixtures__', 'test/fixtures', 'tests/fixtures'];
+const ALL_MARKED_DIRS = [...SOURCE_DIRS, ...TEST_DIRS, ...GENERATED_DIRS, ...VENDOR_DIRS, ...FIXTURE_DIRS];
+const TSCONFIG_GLOBS = ['tsconfig*.json', '{config,configs}/tsconfig*.json'];
+const TEST_CONFIG_GLOBS = [
+    '{vitest,jest,playwright,cypress}.config.{js,cjs,mjs,ts,cts,mts,json}',
+    '.mocharc.{js,cjs,mjs,json,yaml,yml}',
+];
+const LINT_CONFIG_GLOBS = [
+    'eslint.config.{js,cjs,mjs,ts,cts,mts}',
+    '.eslintrc',
+    '.eslintrc.{js,cjs,json,yaml,yml}',
+    'biome.json',
+    'biome.jsonc',
+];
+const GLOB_OPTIONS = {
+    absolute: true,
+    onlyFiles: true,
+    unique: true,
+    followSymbolicLinks: false,
+    suppressErrors: true,
+    ignore: ['**/node_modules/**', '**/.git/**'],
+};
+function readManifest(file) {
+    const parsed = JSON.parse(readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Invalid package manifest: ${file}`);
+    }
+    return parsed;
+}
+function packageManagerFromField(value) {
+    if (typeof value !== 'string')
+        return null;
+    const match = /^(npm|pnpm|yarn|bun)(?:@|$)/.exec(value.trim());
+    return match ? match[1] : null;
+}
+function detectPackageManager(root, field) {
+    const declared = packageManagerFromField(field);
+    if (declared)
+        return declared;
+    if (existsSync(path.join(root, 'pnpm-lock.yaml')))
+        return 'pnpm';
+    if (existsSync(path.join(root, 'yarn.lock')))
+        return 'yarn';
+    if (existsSync(path.join(root, 'bun.lock')) || existsSync(path.join(root, 'bun.lockb')))
+        return 'bun';
+    return 'npm';
+}
+function manifestWorkspacePatterns(value) {
+    const patterns = Array.isArray(value)
+        ? value
+        : value && typeof value === 'object'
+            ? value.packages
+            : [];
+    return Array.isArray(patterns)
+        ? patterns.filter((item) => typeof item === 'string' && item.trim().length > 0)
+        : [];
+}
+function cleanYamlValue(value) {
+    const withoutComment = value.replace(/\s+#.*$/, '').trim();
+    const unquoted = withoutComment.replace(/^(['"])(.*)\1$/, '$2').trim();
+    return unquoted || null;
+}
+function pnpmWorkspacePatterns(file) {
+    if (!existsSync(file))
+        return [];
+    const lines = readFileSync(file, 'utf8').split(/\r?\n/);
+    const result = [];
+    let packageIndent = null;
+    for (const line of lines) {
+        const declaration = /^(\s*)packages\s*:\s*(.*)$/.exec(line);
+        if (declaration) {
+            packageIndent = declaration[1]?.length ?? 0;
+            const inline = declaration[2]?.trim();
+            if (inline?.startsWith('[') && inline.endsWith(']')) {
+                for (const item of inline.slice(1, -1).split(',')) {
+                    const value = cleanYamlValue(item);
+                    if (value)
+                        result.push(value);
+                }
+            }
+            continue;
+        }
+        if (packageIndent === null || /^\s*(?:#.*)?$/.test(line))
+            continue;
+        const indent = /^\s*/.exec(line)?.[0].length ?? 0;
+        if (indent <= packageIndent)
+            break;
+        const item = /^\s*-\s*(.+?)\s*$/.exec(line);
+        if (item?.[1]) {
+            const value = cleanYamlValue(item[1]);
+            if (value)
+                result.push(value);
+        }
+    }
+    return result;
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function workspaceManifestGlobs(patterns) {
+    return patterns.map((raw) => {
+        const negative = raw.startsWith('!');
+        const value = (negative ? raw.slice(1) : raw).replace(/[\\/]+$/, '');
+        const manifest = value.endsWith('package.json') ? value : `${value}/package.json`;
+        return negative ? `!${manifest}` : manifest;
+    });
+}
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+function discoverManifestPaths(root, patterns) {
+    const rootManifest = path.join(root, 'package.json');
+    const matches = fg.sync(workspaceManifestGlobs(patterns), { cwd: root, ...GLOB_OPTIONS });
+    const paths = [
+        ...(existsSync(rootManifest) ? [rootManifest] : []),
+        ...matches.map((item) => path.resolve(item)),
+    ].filter((item) => isInside(root, item));
+    return uniqueSorted(paths.map((item) => path.resolve(item)));
+}
+function discoverConfigPaths(root, patterns) {
+    return uniqueSorted(fg.sync(patterns, { cwd: root, ...GLOB_OPTIONS }).map((item) => path.resolve(item)));
+}
+function existingDirectories(root, relativePaths) {
+    return relativePaths.map((item) => path.resolve(root, item)).filter((item) => {
+        try {
+            return statSync(item).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    });
+}
+function scriptsFromManifest(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === 'string'));
+}
+function createPackageProfile(manifestPath) {
+    const root = path.dirname(manifestPath);
+    const manifest = readManifest(manifestPath);
+    return {
+        name: typeof manifest.name === 'string' && manifest.name ? manifest.name : path.basename(root),
+        root,
+        scripts: scriptsFromManifest(manifest.scripts),
+        sourceRoots: existingDirectories(root, SOURCE_DIRS),
+        testRoots: existingDirectories(root, TEST_DIRS),
+        tsconfigPaths: discoverConfigPaths(root, TSCONFIG_GLOBS),
+        testConfigPaths: discoverConfigPaths(root, TEST_CONFIG_GLOBS),
+        lintConfigPaths: discoverConfigPaths(root, LINT_CONFIG_GLOBS),
+        generatedRoots: existingDirectories(root, GENERATED_DIRS),
+        vendorRoots: existingDirectories(root, VENDOR_DIRS),
+        fixtureRoots: existingDirectories(root, FIXTURE_DIRS),
+    };
+}
+function inputSignatures(root, workspacePatterns) {
+    const manifestPaths = discoverManifestPaths(root, workspacePatterns);
+    const packageRoots = uniqueSorted([root, ...manifestPaths.map((item) => path.dirname(item))]);
+    const configPaths = packageRoots.flatMap((packageRoot) => [
+        ...discoverConfigPaths(packageRoot, TSCONFIG_GLOBS),
+        ...discoverConfigPaths(packageRoot, TEST_CONFIG_GLOBS),
+        ...discoverConfigPaths(packageRoot, LINT_CONFIG_GLOBS),
+    ]);
+    const directoryPaths = packageRoots.flatMap((packageRoot) => ALL_MARKED_DIRS.map((item) => path.resolve(packageRoot, item)));
+    const candidates = uniqueSorted([
+        ...ROOT_INPUTS.map((item) => path.join(root, item)),
+        ...manifestPaths,
+        ...configPaths,
+        ...directoryPaths,
+    ]);
+    return candidates.flatMap((item) => {
+        try {
+            const stat = statSync(item);
+            return [`${item}\0${stat.isDirectory() ? 'd' : 'f'}\0${stat.size}\0${stat.mtimeMs}`];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+function sameSignatures(left, right) {
+    return left.length === right.length && left.every((item, index) => item === right[index]);
+}
+/**
+ * Build a safe, cached description of a package project. Manifests are parsed strictly as JSON;
+ * package scripts and configuration files are never imported or executed.
+ */
+export function discoverProjectProfile(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const cached = cache.get(root);
+    if (cached) {
+        const current = inputSignatures(root, cached.workspacePatterns);
+        if (sameSignatures(current, cached.signatures))
+            return cached.profile;
+    }
+    const rootManifestPath = path.join(root, 'package.json');
+    const rootManifest = existsSync(rootManifestPath) ? readManifest(rootManifestPath) : {};
+    const pnpmFiles = ['pnpm-workspace.yaml', 'pnpm-workspace.yml']
+        .map((item) => path.join(root, item))
+        .filter((item) => existsSync(item));
+    const explicitPatterns = [
+        ...manifestWorkspacePatterns(rootManifest.workspaces),
+        ...pnpmFiles.flatMap((item) => pnpmWorkspacePatterns(item)),
+    ];
+    const workspacePatterns = uniqueSorted(explicitPatterns.length > 0 ? explicitPatterns : ['packages/*']);
+    const profile = {
+        root,
+        packageManager: detectPackageManager(root, rootManifest.packageManager),
+        workspaceConfigPaths: uniqueSorted([
+            ...(manifestWorkspacePatterns(rootManifest.workspaces).length > 0 ? [rootManifestPath] : []),
+            ...pnpmFiles,
+        ]),
+        workspacePatterns,
+        packages: discoverManifestPaths(root, workspacePatterns).map(createPackageProfile),
+    };
+    cache.set(root, { profile, workspacePatterns, signatures: inputSignatures(root, workspacePatterns) });
+    return profile;
+}
+/** Clear one cached project profile, or all profiles when no root is provided. */
+export function clearProjectProfileCache(projectRoot) {
+    if (projectRoot === undefined)
+        cache.clear();
+    else
+        cache.delete(path.resolve(projectRoot));
+}