@codapult/guard 0.2.0 → 0.4.0

package/dist/cli/commands/guard.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { relative, resolve } from 'node:path';
-import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, findGuardRoot, discoverProjectWithMetrics, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, updateBaseline, loadGuardConfig, loadGuardProposals, writeGuardConfig, writeGuardProposals, recordGuardProposalDecision, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardContracts, writeProjectModel, writeGuardMemory, writeProjectSnapshot, } from '../../core/guard.js';
+import { GUARD_BASELINE_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_CONVENTIONS_FILE, GUARD_AGENT_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_HISTORY_DIR, GUARD_RULES_FILE, findGuardRoot, discoverProjectWithMetrics, clearDiscoveryCache, buildGuardReviewPacket, buildGuardProposals, buildGeneratedGuardConfig, discoverProject, GuardAlreadyInitializedError, initializeGuard, loadBaseline, updateBaseline, loadGuardConfig, loadGuardProposals, applyGuardProposalDecision, writeGuardProposals, validateGuardProposalApproval, getGuardProposalFreshness, scanGuard, classifyGuardOutcome, validateGuardPolicy, writeProjectState, } from '../../core/guard.js';
+import { guardErrorPayload } from '../../core/errors.js';
 import { runGuardVerification, } from '../../core/verification/verify.js';
 import { diagnoseGuard } from '../../core/analysis/doctor.js';
 import { diffGuardSnapshots, listGuardSnapshots } from '../../core/history/history.js';
@@ -13,11 +14,33 @@ function renderFindings(findings) {
         const printer = finding.severity === 'error' ? fail : finding.severity === 'warning' ? warn : info;
         printer(`${finding.file}:${finding.line} [${finding.ruleId}] ${finding.message}`);
         dim(`  import: ${finding.importPath}`);
+        if (finding.resolvedPath)
+            dim(`  resolved: ${finding.resolvedPath}`);
     }
 }
 function getRoot() {
     return findGuardRoot();
 }
+function loadConfigSafely(root, options = {}) {
+    try {
+        return { config: loadGuardConfig(root), invalid: false };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'Guard configuration is invalid.';
+        const payload = guardErrorPayload('GUARD_CONFIG_INVALID', message, {
+            configured: false,
+            outcome: 'error',
+            recoverable: true,
+            hint: 'Repair or remove the invalid Guard artifact, then run `codapult-guard doctor`.',
+        });
+        if (options.json || options.machine)
+            console.log(JSON.stringify(payload, null, 2));
+        else
+            fail(`${payload.message} Run \`codapult-guard doctor\` for details.`);
+        process.exitCode = 1;
+        return { invalid: true };
+    }
+}
 function readRequirement(root, file) {
     if (!file)
         return undefined;
@@ -47,7 +70,7 @@ export function guardInitCommand(options = {}) {
     const root = getRoot();
     let initialized;
     try {
-        initialized = initializeGuard(root, { force: options.force });
+        initialized = initializeGuard(root, options.wait === false ? { force: options.force, noWait: true } : { force: options.force });
     }
     catch (error) {
         if (error instanceof GuardAlreadyInitializedError) {
@@ -74,14 +97,12 @@ export function guardInitCommand(options = {}) {
     info(`${config.rules.length} rule(s) generated (${proposedRules} proposed); ${report.scannedFiles} source file(s) scanned.`);
     dim('Existing findings are baselined. New violations will be reported by `codapult-guard check`.');
 }
-export function guardAnalyzeCommand() {
+export function guardAnalyzeCommand(options = {}) {
     const root = getRoot();
     const { model: projectModel, metrics } = discoverProjectWithMetrics(root, {
         persistCache: true,
     });
-    writeProjectModel(root, projectModel);
-    writeGuardMemory(root, projectModel);
-    const revision = writeProjectSnapshot(root, projectModel);
+    const revision = writeProjectState(root, projectModel, options.wait === false ? { noWait: true } : undefined);
     heading('Codapult Guard Analyze');
     success(`Updated ${GUARD_PROJECT_FILE}, ${GUARD_ARCHITECTURE_FILE}, and ${GUARD_CONVENTIONS_FILE}`);
     info(`${projectModel.files.length} file(s), ${projectModel.modules.length} module(s), ${projectModel.insights.cycles.length} cycle(s) recorded as project context.`);
@@ -91,7 +112,10 @@ export function guardAnalyzeCommand() {
 export function guardProposeCommand(options = {}) {
     const root = getRoot();
     const model = discoverProject(root);
-    const config = loadGuardConfig(root) ?? buildGeneratedGuardConfig(model);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config ?? buildGeneratedGuardConfig(model);
     const proposals = buildGuardProposals(model, config);
     const previous = loadGuardProposals(root);
     writeGuardProposals(root, {
@@ -135,9 +159,12 @@ export function guardInstallAgentCommand(target = 'generic', options = {}) {
     process.exitCode = 0;
 }
 export function guardDoctorCommand(options = {}) {
+    if (options.fixCache)
+        clearDiscoveryCache(getRoot());
     const report = diagnoseGuard(getRoot());
+    const result = options.fixCache ? { ...report, cacheFixed: true } : report;
     if (options.json) {
-        console.log(JSON.stringify(report, null, 2));
+        console.log(JSON.stringify(result, null, 2));
     }
     else {
         heading('Codapult Guard Doctor');
@@ -154,7 +181,7 @@ export function guardDoctorCommand(options = {}) {
         else
             success('Guard state is healthy.');
     }
-    process.exitCode = report.status === 'fail' ? 1 : 0;
+    process.exitCode = result.status === 'fail' ? 1 : 0;
 }
 export function guardHistoryCommand() {
     const snapshots = listGuardSnapshots(getRoot());
@@ -174,7 +201,10 @@ export function guardImpactCommand(files, options = {}) {
         process.exitCode = 1;
         return;
     }
-    const result = analyzeProjectImpact(discoverProject(root), files, loadGuardConfig(root)?.contracts ?? []);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const result = analyzeProjectImpact(discoverProject(root), files, loaded.config?.contracts ?? []);
     if (options.json) {
         console.log(JSON.stringify({ status: 'ok', ...result }, null, 2));
         return;
@@ -268,10 +298,20 @@ export function guardVerifyCommand(options = {}) {
 }
 export function guardCheckCommand(options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root, { ...options, machine: options.json || options.sarif });
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         if (options.json) {
-            console.log(JSON.stringify({ configured: false, error: 'Guard is not initialized' }));
+            console.log(JSON.stringify({
+                status: 'error',
+                outcome: 'not-configured',
+                configured: false,
+                errorCode: 'GUARD_NOT_CONFIGURED',
+                message: 'Guard is not initialized.',
+                recoverable: true,
+            }));
             process.exitCode = 1;
             return;
         }
@@ -284,7 +324,7 @@ export function guardCheckCommand(options = {}) {
         baseline: loadBaseline(root),
         includeArchitectureInsights: true,
     });
-    const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+    const contractIssues = validateGuardPolicy(root, config);
     const errors = report.findings.filter((finding) => finding.severity === 'error').length;
     const warnings = report.findings.filter((finding) => finding.severity === 'warning').length;
     const contractFindings = contractIssues.map((issue) => ({
@@ -328,10 +368,20 @@ export function guardCheckCommand(options = {}) {
 }
 export function guardAuditCommand(options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         if (options.json) {
-            console.log(JSON.stringify({ configured: false, error: 'Guard is not initialized' }));
+            console.log(JSON.stringify({
+                status: 'error',
+                outcome: 'not-configured',
+                configured: false,
+                errorCode: 'GUARD_NOT_CONFIGURED',
+                message: 'Guard is not initialized.',
+                recoverable: true,
+            }));
             process.exitCode = 1;
             return;
         }
@@ -340,7 +390,7 @@ export function guardAuditCommand(options = {}) {
         return;
     }
     const report = scanGuard(root, config, { includeArchitectureInsights: true });
-    const contractIssues = validateGuardContracts(root, config.contracts ?? []);
+    const contractIssues = validateGuardPolicy(root, config);
     const errors = report.findings.filter((finding) => finding.severity === 'error').length;
     const warnings = report.findings.filter((finding) => finding.severity === 'warning').length;
     if (options.json) {
@@ -388,9 +438,12 @@ export function guardBaselineCommand(action, ids, options = {}) {
         process.exitCode = 0;
         return;
     }
+    const loaded = options.all ? loadConfigSafely(root, options) : { invalid: false };
+    if (loaded.invalid)
+        return;
     const selected = options.all
         ? [
-            ...scanGuard(root, loadGuardConfig(root) ?? buildGeneratedGuardConfig(discoverProject(root)), {
+            ...scanGuard(root, loaded.config ?? buildGeneratedGuardConfig(discoverProject(root)), {
                 includeArchitectureInsights: true,
             }).findings.map((finding) => finding.fingerprint),
         ]
@@ -415,7 +468,10 @@ export function guardBaselineCommand(action, ids, options = {}) {
 }
 export function guardRulesApproveCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -433,18 +489,69 @@ export function guardRulesApproveCommand(ids, options = {}) {
         return;
     }
     const selectedIds = new Set(selected.map((rule) => rule.id));
-    writeGuardConfig(root, {
+    const approvalError = validateGuardProposalApproval(config.approval, loadGuardProposals(root));
+    if (approvalError) {
+        fail(approvalError);
+        process.exitCode = 1;
+        return;
+    }
+    applyGuardProposalDecision(root, {
         ...config,
         rules: config.rules.map((rule) => selectedIds.has(rule.id) ? { ...rule, status: 'active' } : rule),
-    });
-    recordGuardProposalDecision(root, selected.map((rule) => ({ id: rule.id, type: 'rule', decision: 'approved' })));
+    }, selected.map((rule) => ({ id: rule.id, type: 'rule', decision: 'approved' })), { source: 'cli' });
     for (const rule of selected)
         success(`Activated ${rule.id}`);
     process.exitCode = 0;
 }
+export function guardPolicyExplainCommand(id, options = {}) {
+    const root = getRoot();
+    const loaded = loadConfigSafely(root, options);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
+    const proposals = loadGuardProposals(root);
+    if (!config) {
+        fail('Guard is not initialized. Run `codapult-guard init` first.');
+        process.exitCode = 1;
+        return;
+    }
+    const item = [...config.rules, ...(config.contracts ?? [])].find((entry) => entry.id === id);
+    const proposed = [...(proposals?.rules ?? []), ...(proposals?.contracts ?? [])].find((entry) => entry.id === id);
+    if (!item && !proposed) {
+        fail(`Policy item not found: ${id}`);
+        process.exitCode = 1;
+        return;
+    }
+    const result = {
+        id,
+        active: item?.status !== 'proposed' && item !== undefined,
+        definition: item ?? proposed,
+        proposal: proposed,
+        decisions: proposals?.decisions?.filter((decision) => decision.id === id) ?? [],
+    };
+    if (options.json)
+        console.log(JSON.stringify(result, null, 2));
+    else {
+        heading(`Guard Policy: ${id}`);
+        info(`Status: ${result.active ? 'active' : 'proposed'}`);
+        const definition = result.definition;
+        if (definition && 'description' in definition)
+            dim(definition.description);
+        if (definition && 'statement' in definition)
+            dim(definition.statement);
+        if ((definition?.evidence?.length ?? 0) > 0)
+            dim(`Evidence: ${definition?.evidence?.join(', ')}`);
+        if (result.decisions.length > 0)
+            dim(`Decisions: ${result.decisions.length}`);
+    }
+    process.exitCode = 0;
+}
 export function guardContractsApproveCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -462,22 +569,30 @@ export function guardContractsApproveCommand(ids, options = {}) {
         return;
     }
     const selectedIds = new Set(selected.map((contract) => contract.id));
-    writeGuardConfig(root, {
+    const approvalError = validateGuardProposalApproval(config.approval, loadGuardProposals(root));
+    if (approvalError) {
+        fail(approvalError);
+        process.exitCode = 1;
+        return;
+    }
+    applyGuardProposalDecision(root, {
         ...config,
         contracts: (config.contracts ?? []).map((contract) => selectedIds.has(contract.id) ? { ...contract, status: 'active' } : contract),
-    });
-    recordGuardProposalDecision(root, selected.map((contract) => ({
+    }, selected.map((contract) => ({
         id: contract.id,
         type: 'contract',
         decision: 'approved',
-    })));
+    })), { source: 'cli' });
     for (const contract of selected)
         success(`Activated ${contract.id}`);
     process.exitCode = 0;
 }
 export function guardContractsRejectCommand(ids, options = {}) {
     const root = getRoot();
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail('Guard is not initialized. Run `codapult-guard init` first.');
         process.exitCode = 1;
@@ -494,15 +609,20 @@ export function guardContractsRejectCommand(ids, options = {}) {
         process.exitCode = 1;
         return;
     }
-    writeGuardConfig(root, {
+    const approvalError = validateGuardProposalApproval(config.approval, loadGuardProposals(root));
+    if (approvalError) {
+        fail(approvalError);
+        process.exitCode = 1;
+        return;
+    }
+    applyGuardProposalDecision(root, {
         ...config,
         contracts: config.contracts ?? [],
-    });
-    recordGuardProposalDecision(root, selected.map((contract) => ({
+    }, selected.map((contract) => ({
         id: contract.id,
         type: 'contract',
         decision: 'rejected',
-    })));
+    })), { source: 'cli' });
     for (const contract of selected)
         success(`Rejected ${contract.id}`);
     process.exitCode = 0;
@@ -512,7 +632,10 @@ export function guardReviewCommand(options = {}) {
     const requirement = readRequirement(root, options.requirement);
     if (options.requirement && !requirement)
         return;
-    const config = loadGuardConfig(root);
+    const loaded = loadConfigSafely(root);
+    if (loaded.invalid)
+        return;
+    const config = loaded.config;
     if (!config) {
         fail(`Guard is not initialized. Run \`codapult-guard init\` first.`);
         process.exitCode = 1;

package/dist/cli/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import pc from 'picocolors';
-import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
+import { guardAnalyzeCommand, guardAuditCommand, guardBaselineCommand, guardCheckCommand, guardContractsApproveCommand, guardContractsRejectCommand, guardDoctorCommand, guardHistoryCommand, guardHistoryDiffCommand, guardImpactCommand, guardInitCommand, guardInstallAgentCommand, guardPolicyExplainCommand, guardProposeCommand, guardReviewCommand, guardRulesApproveCommand, guardVerifyCommand, } from './commands/guard.js';
 import { config } from '../core/config.js';
+import { GuardBaselineReasonError, GuardConfigError, GuardStateBusyError, GuardStateStaleError, } from '../core/guard.js';
+import { guardErrorPayload } from '../core/errors.js';
 const program = new Command()
     .name(config.commandName)
     .description('Local-first architecture guardrails for JavaScript and TypeScript projects')
@@ -14,11 +16,11 @@ const program = new Command()
 // Guard is the standalone product, so its commands live at the package root:
 // `codapult-guard init`, not `codapult-guard guard init`.
 const guard = program;
-guard.command('init').option('--force').action(guardInitCommand);
-guard.command('analyze').action(guardAnalyzeCommand);
+guard.command('init').option('--force').option('--no-wait').action(guardInitCommand);
+guard.command('analyze').option('--refresh').option('--no-wait').action(guardAnalyzeCommand);
 guard.command('propose').option('--json').action(guardProposeCommand);
 guard.command('install-agent [target]').option('--json').action(guardInstallAgentCommand);
-guard.command('doctor').option('--json').action(guardDoctorCommand);
+guard.command('doctor').option('--json').option('--fix-cache').action(guardDoctorCommand);
 guard.command('history').action(guardHistoryCommand);
 guard.command('history-diff <from> <to>').option('--json').action(guardHistoryDiffCommand);
 guard.command('impact <files...>').option('--json').action(guardImpactCommand);
@@ -47,6 +49,8 @@ guard
     .action(guardReviewCommand);
 const rules = guard.command('rules');
 rules.command('approve [ids]').option('--all').action(guardRulesApproveCommand);
+const policy = guard.command('policy');
+policy.command('explain <id>').option('--json').action(guardPolicyExplainCommand);
 const contracts = guard.command('contracts');
 contracts.command('approve [ids]').option('--all').action(guardContractsApproveCommand);
 contracts.command('reject [ids]').option('--all').action(guardContractsRejectCommand);
@@ -73,4 +77,36 @@ program
     .action(async () => {
     await import('../mcp/server.js');
 });
-program.parse();
+try {
+    program.parse();
+}
+catch (error) {
+    if (error instanceof GuardConfigError ||
+        error instanceof GuardBaselineReasonError ||
+        error instanceof GuardStateBusyError ||
+        error instanceof GuardStateStaleError) {
+        const isBusy = error instanceof GuardStateBusyError;
+        const isStale = error instanceof GuardStateStaleError;
+        const isInvalidInput = error instanceof GuardBaselineReasonError;
+        console.error(JSON.stringify(guardErrorPayload(isBusy
+            ? 'GUARD_STATE_BUSY'
+            : isStale
+                ? 'GUARD_STATE_STALE'
+                : isInvalidInput
+                    ? 'GUARD_INVALID_INPUT'
+                    : 'GUARD_CONFIG_INVALID', error.message, {
+            configured: !isBusy && !isStale,
+            outcome: 'error',
+            recoverable: true,
+            hint: isBusy || isStale
+                ? 'Re-read Guard state and retry the operation.'
+                : isInvalidInput
+                    ? 'Provide a written reason for the baseline decision.'
+                    : 'Repair the invalid Guard artifact, then run codapult-guard doctor.',
+        }), null, 2));
+        process.exitCode = 1;
+    }
+    else {
+        throw error;
+    }
+}

package/dist/core/analysis/doctor.d.ts

@@ -7,6 +7,6 @@ export interface GuardDoctorReport {
     status: 'ok' | 'warning' | 'fail';
     initialized: boolean;
     items: GuardDoctorItem[];
-    recommendation?: string;
+    recommendation?: string | undefined;
 }
 export declare function diagnoseGuard(root: string): GuardDoctorReport;

package/dist/core/analysis/doctor.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { GUARD_AGENT_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_BASELINE_FILE, GUARD_CONVENTIONS_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_RULES_FILE, loadGuardConfig, loadProjectModel, isGuardAgentConfig, isGuardContractsFile, isGuardProposalFile, validateGuardContracts, } from '../guard.js';
+import { GUARD_AGENT_FILE, GUARD_BASELINE_META_FILE, GUARD_ARCHITECTURE_FILE, GUARD_BASELINE_FILE, GUARD_CONVENTIONS_FILE, GUARD_CONTRACTS_FILE, GUARD_PROPOSALS_FILE, GUARD_PROJECT_FILE, GUARD_RULES_FILE, loadGuardConfig, loadProjectModel, isGuardAgentConfig, isGuardContractsFile, isGuardProposalFile, validateGuardPolicy, } from '../guard.js';
 const requiredArtifacts = [
     GUARD_BASELINE_FILE,
     GUARD_RULES_FILE,
@@ -22,12 +22,18 @@ function parseJson(root, path) {
 export function diagnoseGuard(root) {
     const initialized = existsSync(resolve(root, GUARD_BASELINE_FILE));
     const items = requiredArtifacts.map((path) => {
-        const guardConfig = path === GUARD_CONTRACTS_FILE ? loadGuardConfig(root) : undefined;
         if (!existsSync(resolve(root, path))) {
             return { path, status: 'missing', message: 'Artifact is missing.' };
         }
-        if (path === GUARD_RULES_FILE && !loadGuardConfig(root)) {
-            return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+        if (path === GUARD_RULES_FILE) {
+            try {
+                if (!loadGuardConfig(root)) {
+                    return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+                }
+            }
+            catch {
+                return { path, status: 'invalid', message: 'Guard rules are invalid or unsupported.' };
+            }
         }
         if (path === GUARD_PROJECT_FILE && !loadProjectModel(root)) {
             return { path, status: 'invalid', message: 'Project model is invalid or unsupported.' };
@@ -39,8 +45,15 @@ export function diagnoseGuard(root) {
             return { path, status: 'invalid', message: 'Guard contracts are invalid or unsupported.' };
         }
         if (path === GUARD_CONTRACTS_FILE &&
-            guardConfig &&
-            validateGuardContracts(root, guardConfig.contracts).length > 0) {
+            (() => {
+                try {
+                    const guardConfig = loadGuardConfig(root);
+                    return guardConfig !== undefined && validateGuardPolicy(root, guardConfig).length > 0;
+                }
+                catch {
+                    return true;
+                }
+            })()) {
             return { path, status: 'invalid', message: 'Guard contract scopes or references are stale.' };
         }
         if (path === GUARD_PROPOSALS_FILE && !isGuardProposalFile(parseJson(root, path))) {

package/dist/core/discovery/discovery.d.ts

@@ -11,6 +11,7 @@ export interface ModuleRecord {
     exports: string[];
     calls: string[];
     resolvedImports: string[];
+    resolvedImportMap?: Record<string, string> | undefined;
     dynamicImports: string[];
     declarations: {
         classes: number;
@@ -32,18 +33,20 @@ export interface CapabilitySignal {
 export interface ProjectModel {
     version: 1;
     project: {
-        name?: string;
-        packageManager?: string;
+        name?: string | undefined;
+        packageManager?: string | undefined;
         frameworks: string[];
         scripts: Record<string, string>;
         dependencies: Record<string, string>;
         devDependencies: Record<string, string>;
         workspacePackages: {
             path: string;
-            name?: string;
+            name?: string | undefined;
             private: boolean;
             scripts: Record<string, string>;
             dependencies: string[];
+            exports?: string[] | undefined;
+            projectReferences?: string[] | undefined;
         }[];
     };
     files: ProjectFileRecord[];
@@ -56,7 +59,7 @@ export interface ProjectModel {
     };
     git: {
         repository: boolean;
-        branch?: string;
+        branch?: string | undefined;
         dirty: boolean;
         changedFiles: string[];
         status: string[];
@@ -122,6 +125,24 @@ export interface DiscoveryMetrics {
     changedFiles: number;
     reusedModules: number;
 }
+export interface DiscoveryResult {
+    model: ProjectModel;
+    metrics: DiscoveryMetrics;
+}
+export interface DiscoveryOptions {
+    persistCache?: boolean | undefined;
+    /** Maximum number of files included in one model. */
+    maxFiles?: number | undefined;
+    /** Maximum size of one included file in bytes. */
+    maxFileBytes?: number | undefined;
+}
+export declare class DiscoveryLimitError extends Error {
+    constructor(message: string);
+}
+export declare class DiscoveryStaleError extends Error {
+    constructor();
+}
+export declare function clearDiscoveryCache(root: string): void;
 export declare function findGuardRoot(from?: string): string;
 /** Build the internal module graph from AST resolution plus conservative fallback resolution.
  *
@@ -130,12 +151,5 @@ export declare function findGuardRoot(from?: string): string;
  * no resolved imports silently drops unresolved edges from mixed projects.
  */
 export declare function buildModuleTargetGraph(modules: ModuleRecord[]): Map<string, string[]>;
-export declare function discoverProject(root: string, options?: {
-    persistCache?: boolean;
-}): ProjectModel;
-export declare function discoverProjectWithMetrics(root: string, options?: {
-    persistCache?: boolean;
-}): {
-    model: ProjectModel;
-    metrics: DiscoveryMetrics;
-};
+export declare function discoverProject(root: string, options?: DiscoveryOptions): ProjectModel;
+export declare function discoverProjectWithMetrics(root: string, options?: DiscoveryOptions): DiscoveryResult;