@codapult/guard 0.2.0 → 0.3.0

package/dist/core/discovery/discovery.js

@@ -1,9 +1,17 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, renameSync, statSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, extname, join, normalize, relative, resolve } from 'node:path';
 import { Project, SyntaxKind } from 'ts-morph';
 import { config } from '../config.js';
+export class DiscoveryLimitError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DiscoveryLimitError';
+    }
+}
+const DEFAULT_MAX_FILES = 100_000;
+const DEFAULT_MAX_FILE_BYTES = 25 * 1024 * 1024;
 const IGNORED_DIRECTORIES = new Set([
     '.git',
     '.next',
@@ -40,12 +48,16 @@ const CONFIG_NAMES = new Set([
 ]);
 const discoveryCache = new Map();
 const discoveryReuse = new Map();
+const discoveryCacheHits = new Map();
 // Bump when the persisted model shape changes; old cache entries must never
 // bypass discovery and return an incomplete ProjectModel.
 const DISCOVERY_CACHE_VERSION = 3;
 function discoveryCachePath(root) {
     return resolve(root, `.${config.appName}/guard/cache.json`);
 }
+export function clearDiscoveryCache(root) {
+    rmSync(discoveryCachePath(root), { force: true });
+}
 function contentHash(root, path) {
     return createHash('sha256')
         .update(readFileSync(resolve(root, path)))
@@ -121,20 +133,45 @@ function workspacePackages(root, files) {
                 ...asStringRecord(manifest.devDependencies),
                 ...asStringRecord(manifest.peerDependencies),
             }).sort(),
+            ...(manifest.exports !== undefined
+                ? {
+                    exports: Array.isArray(manifest.exports)
+                        ? manifest.exports.filter((item) => typeof item === 'string')
+                        : manifest.exports !== null && typeof manifest.exports === 'object'
+                            ? Object.keys(manifest.exports)
+                            : [],
+                }
+                : {}),
+            ...(Array.isArray(readJsonObject(resolve(root, dirname(path), 'tsconfig.json')).references)
+                ? {
+                    projectReferences: readJsonObject(resolve(root, dirname(path), 'tsconfig.json'))
+                        .references
+                        .filter((reference) => reference !== null &&
+                        typeof reference === 'object' &&
+                        typeof reference.path === 'string')
+                        .map((reference) => reference.path)
+                        .sort(),
+                }
+                : {}),
         };
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
-function listFiles(root, directory = root) {
+function listFiles(root, directory = root, maxFiles = DEFAULT_MAX_FILES) {
     const result = [];
     for (const entry of readdirSync(directory, { withFileTypes: true })) {
         if (entry.isDirectory() && IGNORED_DIRECTORIES.has(entry.name))
             continue;
         const path = resolve(directory, entry.name);
         if (entry.isDirectory())
-            result.push(...listFiles(root, path));
-        else if (entry.isFile() && !ignoredFile(path))
+            result.push(...listFiles(root, path, maxFiles - result.length));
+        else if (entry.isFile() && !ignoredFile(path)) {
             result.push(relative(root, path));
+            if (result.length > maxFiles) {
+                throw new DiscoveryLimitError(`Project contains more than ${maxFiles} files; discovery limit was reached. ` +
+                    'Use an ignore file or raise maxFiles deliberately.');
+            }
+        }
     }
     return result.sort();
 }
@@ -169,7 +206,54 @@ function resolveInternalImport(from, importPath, modules) {
     ];
     return candidates.find((candidate) => modules.has(candidate));
 }
-function parseModule(project, root, path, projectFiles) {
+function pathAliases(root) {
+    return listFiles(root)
+        .filter((path) => basename(path) === 'tsconfig.json' || basename(path) === 'jsconfig.json')
+        .flatMap((path) => {
+        const tsconfigJson = readJsonObject(resolve(root, path));
+        const compilerOptions = tsconfigJson.compilerOptions !== null && typeof tsconfigJson.compilerOptions === 'object'
+            ? tsconfigJson.compilerOptions
+            : {};
+        const paths = compilerOptions.paths;
+        if (paths === null || typeof paths !== 'object')
+            return [];
+        const baseUrl = typeof compilerOptions.baseUrl === 'string' ? compilerOptions.baseUrl : '.';
+        return Object.entries(paths).flatMap(([pattern, value]) => {
+            if (!Array.isArray(value))
+                return [];
+            const targets = value.filter((item) => typeof item === 'string');
+            return targets.length > 0
+                ? [{ pattern, baseDirectory: resolve(root, dirname(path), baseUrl), targets }]
+                : [];
+        });
+    });
+}
+function resolveAliasedImport(root, importPath, aliases, modules) {
+    for (const alias of aliases) {
+        const wildcard = alias.pattern.indexOf('*');
+        const prefix = wildcard >= 0 ? alias.pattern.slice(0, wildcard) : alias.pattern;
+        const suffix = wildcard >= 0 ? alias.pattern.slice(wildcard + 1) : '';
+        if (!importPath.startsWith(prefix) || (suffix && !importPath.endsWith(suffix)))
+            continue;
+        const replacement = importPath.slice(prefix.length, importPath.length - suffix.length);
+        for (const target of alias.targets) {
+            const targetPath = target.replace('*', replacement);
+            const absoluteBase = resolve(alias.baseDirectory, targetPath);
+            const relativeBase = relative(root, absoluteBase);
+            const normalizedBase = relativeBase.replace(/^\.\//, '').replaceAll('\\', '/');
+            const candidates = [
+                normalizedBase,
+                ...[...SOURCE_EXTENSIONS].map((extension) => `${normalizedBase}${extension}`),
+                ...[...SOURCE_EXTENSIONS].map((extension) => `${normalizedBase}/index${extension}`),
+            ];
+            const projectCandidate = candidates.find((candidate) => modules.has(candidate));
+            if (projectCandidate)
+                return projectCandidate;
+        }
+    }
+    return undefined;
+}
+function parseModule(project, root, path, projectFiles, aliases) {
     if (!SOURCE_EXTENSIONS.has(extname(path)))
         return undefined;
     let sourceFile;
@@ -187,6 +271,7 @@ function parseModule(project, root, path, projectFiles) {
     const dynamicImports = [];
     const declarations = { classes: 0, functions: 0, interfaces: 0, types: 0, variables: 0 };
     const resolvedImports = new Set();
+    const resolvedImportMap = {};
     for (const declaration of sourceFile.getImportDeclarations()) {
         const importPath = declaration.getModuleSpecifierValue();
         imports.push(importPath);
@@ -200,9 +285,12 @@ function parseModule(project, root, path, projectFiles) {
             importedSymbols.push(namedImport.getAliasNode()?.getText() ?? namedImport.getName());
         }
         const resolved = declaration.getModuleSpecifierSourceFile();
-        const resolvedPath = resolved && sourceFilePath(root, resolved, projectFiles);
-        if (resolvedPath)
+        const resolvedPath = (resolved && sourceFilePath(root, resolved, projectFiles)) ??
+            resolveAliasedImport(root, importPath, aliases, projectFiles);
+        if (resolvedPath) {
             resolvedImports.add(resolvedPath);
+            resolvedImportMap[importPath] = resolvedPath;
+        }
     }
     for (const declaration of sourceFile.getExportDeclarations()) {
         const moduleSpecifier = declaration.getModuleSpecifierValue();
@@ -210,9 +298,12 @@ function parseModule(project, root, path, projectFiles) {
             continue;
         exports.push(moduleSpecifier);
         const resolved = declaration.getModuleSpecifierSourceFile();
-        const resolvedPath = resolved && sourceFilePath(root, resolved, projectFiles);
-        if (resolvedPath)
+        const resolvedPath = (resolved && sourceFilePath(root, resolved, projectFiles)) ??
+            resolveAliasedImport(root, moduleSpecifier, aliases, projectFiles);
+        if (resolvedPath) {
             resolvedImports.add(resolvedPath);
+            resolvedImportMap[moduleSpecifier] = resolvedPath;
+        }
     }
     declarations.classes = sourceFile.getClasses().length;
     declarations.functions = sourceFile.getFunctions().length;
@@ -234,9 +325,12 @@ function parseModule(project, root, path, projectFiles) {
         if (!importPath)
             continue;
         dynamicImports.push(importPath);
-        const resolvedPath = resolveInternalImport(path, importPath, projectFiles);
-        if (resolvedPath)
+        const resolvedPath = resolveInternalImport(path, importPath, projectFiles) ??
+            resolveAliasedImport(root, importPath, aliases, projectFiles);
+        if (resolvedPath) {
             resolvedImports.add(resolvedPath);
+            resolvedImportMap[importPath] = resolvedPath;
+        }
     }
     const directives = sourceFile
         .getStatements()
@@ -257,6 +351,7 @@ function parseModule(project, root, path, projectFiles) {
         exports: [...new Set(exports)].sort(),
         calls: [...new Set(calls)].sort(),
         resolvedImports: [...resolvedImports].sort(),
+        resolvedImportMap,
         dynamicImports: [...new Set(dynamicImports)].sort(),
         declarations,
         directives,
@@ -645,9 +740,23 @@ function buildInsights(root, files, modules, sourceFiles, dependencies, astProje
 function createAstProject(root) {
     const tsConfigPath = resolve(root, 'tsconfig.json');
     try {
-        return existsSync(tsConfigPath)
+        const project = existsSync(tsConfigPath)
             ? new Project({ tsConfigFilePath: tsConfigPath })
             : new Project({ skipAddingFilesFromTsConfig: true });
+        // Monorepos commonly keep compiler options and path aliases per package.
+        // Load those projects as well; files still remain bounded by listFiles().
+        for (const configPath of listFiles(root).filter((path) => basename(path) === 'tsconfig.json')) {
+            const absolutePath = resolve(root, configPath);
+            if (absolutePath === tsConfigPath)
+                continue;
+            try {
+                project.addSourceFilesFromTsConfig(absolutePath);
+            }
+            catch {
+                // A package config can be partial or reference an unavailable project.
+            }
+        }
+        return project;
     }
     catch {
         return new Project({ skipAddingFilesFromTsConfig: true });
@@ -658,19 +767,42 @@ export function discoverProject(root, options = {}) {
     const dependencies = asStringRecord(packageJson.dependencies);
     const devDependencies = asStringRecord(packageJson.devDependencies);
     const scripts = asStringRecord(packageJson.scripts);
-    const allFiles = listFiles(root);
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES;
+    if (!Number.isInteger(maxFiles) || maxFiles < 1) {
+        throw new DiscoveryLimitError('Discovery maxFiles must be a positive integer.');
+    }
+    if (!Number.isInteger(maxFileBytes) || maxFileBytes < 1) {
+        throw new DiscoveryLimitError('Discovery maxFileBytes must be a positive integer.');
+    }
+    const allFiles = listFiles(root, root, maxFiles);
+    if (allFiles.length > maxFiles) {
+        throw new DiscoveryLimitError(`Project contains ${allFiles.length} files; discovery limit is ${maxFiles}. ` +
+            'Use an ignore file or raise maxFiles deliberately.');
+    }
+    for (const path of allFiles) {
+        const bytes = statSync(resolve(root, path)).size;
+        if (bytes > maxFileBytes) {
+            throw new DiscoveryLimitError(`File ${path} is ${bytes} bytes; discovery limit is ${maxFileBytes}. ` +
+                'Ignore the file or raise maxFileBytes deliberately.');
+        }
+    }
     const signature = JSON.stringify([
         JSON.stringify(packageJson),
         allFiles.map((path) => {
             const stat = statSync(resolve(root, path));
-            return [path, stat.size, stat.mtimeMs];
+            // Size/mtime alone can miss an in-place edit that preserves both values.
+            // The model is a correctness boundary, so include content in the cache key.
+            return [path, stat.size, stat.mtimeMs, contentHash(root, path)];
         }),
         runGit(root, ['rev-parse', 'HEAD']),
         runGit(root, ['status', '--porcelain']),
     ]);
     const cacheKey = resolve(root);
+    discoveryCacheHits.set(cacheKey, false);
     const cached = discoveryCache.get(cacheKey);
     if (cached?.signature === signature) {
+        discoveryCacheHits.set(cacheKey, true);
         discoveryReuse.set(cacheKey, cached.model.modules.length);
         return cached.model;
     }
@@ -683,6 +815,7 @@ export function discoverProject(root, options = {}) {
             persisted.model.version === 1) {
             previousModel = persisted.model;
             if (persisted.signature === signature) {
+                discoveryCacheHits.set(cacheKey, true);
                 discoveryCache.set(cacheKey, { signature, model: previousModel });
                 discoveryReuse.set(cacheKey, previousModel.modules.length);
                 return previousModel;
@@ -699,6 +832,7 @@ export function discoverProject(root, options = {}) {
     }));
     const projectFiles = new Set(files.map((file) => file.path));
     const astProject = createAstProject(root);
+    const aliases = pathAliases(root);
     const previousModules = new Map(previousModel?.modules.map((module) => [module.path, module]));
     const currentShape = files
         .filter((file) => file.kind === 'source' || file.kind === 'test')
@@ -723,7 +857,7 @@ export function discoverProject(root, options = {}) {
             reusedModules += 1;
             return previous;
         }
-        return parseModule(astProject, root, file.path, projectFiles);
+        return parseModule(astProject, root, file.path, projectFiles, aliases);
     })
         .filter((module) => module !== undefined);
     const sourceFiles = files.filter((file) => file.kind === 'source').map((file) => file.path);
@@ -806,7 +940,6 @@ export function discoverProject(root, options = {}) {
 }
 export function discoverProjectWithMetrics(root, options = {}) {
     const startedAt = Date.now();
-    const cacheHit = discoveryCache.has(resolve(root));
     const model = discoverProject(root, options);
     return {
         model,
@@ -815,7 +948,7 @@ export function discoverProjectWithMetrics(root, options = {}) {
             files: model.files.length,
             modules: model.modules.length,
             cacheAvailable: existsSync(discoveryCachePath(root)),
-            cacheHit,
+            cacheHit: discoveryCacheHits.get(resolve(root)) ?? false,
             changedFiles: model.git.changedFiles.length,
             reusedModules: discoveryReuse.get(resolve(root)) ?? 0,
         },

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+export type GuardErrorCode = 'GUARD_NOT_CONFIGURED' | 'GUARD_CONFIG_INVALID' | 'GUARD_STATE_BUSY' | 'GUARD_INVALID_INPUT';
+export interface GuardErrorPayload {
+    status: 'error';
+    outcome: 'not-configured' | 'error';
+    configured: boolean;
+    errorCode: GuardErrorCode;
+    message: string;
+    recoverable: boolean;
+    hint?: string;
+}
+export declare function guardErrorPayload(errorCode: GuardErrorCode, message: string, options: Pick<GuardErrorPayload, 'configured' | 'recoverable' | 'outcome'> & Partial<Pick<GuardErrorPayload, 'hint'>>): GuardErrorPayload;

package/dist/core/errors.js

@@ -0,0 +1,11 @@
+export function guardErrorPayload(errorCode, message, options) {
+    return {
+        status: 'error',
+        outcome: options.outcome,
+        configured: options.configured,
+        errorCode,
+        message,
+        recoverable: options.recoverable,
+        ...(options.hint ? { hint: options.hint } : {}),
+    };
+}

package/dist/core/guard.d.ts

@@ -1,5 +1,5 @@
-import type { ProjectModel } from './discovery/discovery.js';
-import { discoverProject, discoverProjectWithMetrics, findGuardRoot } from './discovery/discovery.js';
+import { type ProjectModel } from './discovery/discovery.js';
+import { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot } from './discovery/discovery.js';
 import { type GuardImpactAnalysis } from './analysis/impact.js';
 export type GuardSeverity = 'error' | 'warning' | 'info';
 export type GuardOutcomeStatus = 'pass' | 'fail' | 'warning' | 'needs-review' | 'not-configured';
@@ -11,7 +11,7 @@ export declare function classifyGuardOutcome(input: {
 }): GuardOutcomeStatus;
 export type GuardRuleKind = 'forbidden-import' | 'client-forbidden-import';
 export type GuardRuleStatus = 'active' | 'proposed';
-export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call';
+export type GuardContractKind = 'guidance' | 'import-boundary' | 'required-call' | 'package-boundary';
 export interface GuardContract {
     id: string;
     statement: string;
@@ -25,6 +25,8 @@ export interface GuardContract {
     mustImport?: string[];
     mustNotImport?: string[];
     mustCall?: string[];
+    fromPackages?: string[];
+    mustNotImportPackages?: string[];
     status?: GuardRuleStatus;
     confidence?: 'high' | 'medium' | 'low';
     evidence?: string[];
@@ -89,6 +91,7 @@ export interface GuardFinding {
     file: string;
     line: number;
     importPath: string;
+    resolvedPath?: string;
     message: string;
     fingerprint: string;
 }
@@ -148,6 +151,12 @@ export declare const defaultGuardAgentConfig: GuardAgentConfig;
 export declare class GuardAlreadyInitializedError extends Error {
     constructor();
 }
+export declare class GuardConfigError extends Error {
+    constructor(path: string);
+}
+export declare class GuardStateBusyError extends Error {
+    constructor(path: string);
+}
 export declare function isGuardContractsFile(value: unknown): value is {
     version: 1;
     contracts: GuardContract[];
@@ -160,7 +169,6 @@ export declare function loadGuardProposals(root: string): GuardProposalFile | un
 export declare function isGuardAgentConfig(value: unknown): value is GuardAgentConfig;
 export declare function loadGuardAgentConfig(root: string): GuardAgentConfig;
 export declare function writeGuardAgentConfig(root: string, agentConfig?: GuardAgentConfig): void;
-export declare function loadGuardArtifact(root: string, relativePath: string): unknown;
 export declare function loadBaseline(root: string): Set<string>;
 export declare function updateBaseline(root: string, options?: {
     add?: string[];
@@ -170,6 +178,10 @@ export declare function updateBaseline(root: string, options?: {
 export declare function writeGuardConfig(root: string, guardConfig: GuardConfig): void;
 export declare function writeGuardProposals(root: string, proposals: GuardProposalFile): void;
 export declare function recordGuardProposalDecision(root: string, decisions: Pick<GuardProposalDecision, 'id' | 'type' | 'decision'>[]): void;
+export declare function getPendingGuardProposals(proposals: GuardProposalFile | undefined): {
+    id: string;
+    type: 'rule' | 'contract';
+}[];
 export declare function buildGuardProposals(model: ProjectModel, guardConfig: GuardConfig): GuardProposalFile;
 export declare function buildArchitectureMemory(model: ProjectModel): Record<string, unknown>;
 export declare function buildConventionsMemory(model: ProjectModel): Record<string, unknown>;
@@ -179,6 +191,7 @@ export declare function writeBaseline(root: string, findings: GuardFinding[], mo
 export declare function loadProjectModel(root: string): ProjectModel | undefined;
 export declare function writeProjectModel(root: string, model: ProjectModel): void;
 export declare function writeProjectSnapshot(root: string, model: ProjectModel): string;
+export declare function loadGuardArtifact(root: string, relativePath: string): unknown;
 export declare function validateGuardContracts(root: string, contracts?: GuardContract[]): GuardContractIssue[];
 /** @internal Redacts common credential shapes before a diff enters an AI review packet. */
 export declare function redactSensitiveText(value: string): {
@@ -194,4 +207,4 @@ export declare function initializeGuard(root: string, options?: {
     config: GuardConfig;
     report: GuardReport;
 };
-export { discoverProject, discoverProjectWithMetrics, findGuardRoot };
+export { clearDiscoveryCache, discoverProject, discoverProjectWithMetrics, findGuardRoot };