@codapult/guard 0.2.0 → 0.4.0

package/dist/core/discovery/discovery.js

@@ -1,9 +1,23 @@
 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';
+    }
+}
+export class DiscoveryStaleError extends Error {
+    constructor() {
+        super('Project changed while Guard was discovering it.');
+        this.name = 'DiscoveryStaleError';
+    }
+}
+const DEFAULT_MAX_FILES = 100_000;
+const DEFAULT_MAX_FILE_BYTES = 25 * 1024 * 1024;
 const IGNORED_DIRECTORIES = new Set([
     '.git',
     '.next',
@@ -40,12 +54,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 +139,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 +212,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 +277,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 +291,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 +304,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 +331,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 +357,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,
@@ -271,6 +372,17 @@ function runGit(root, args) {
         return stdout?.toString().trim() || undefined;
     }
 }
+function discoverySignature(root, packageJson, allFiles) {
+    return JSON.stringify([
+        JSON.stringify(packageJson),
+        allFiles.map((path) => {
+            const stat = statSync(resolve(root, path));
+            return [path, stat.size, stat.mtimeMs, contentHash(root, path)];
+        }),
+        runGit(root, ['rev-parse', 'HEAD']),
+        runGit(root, ['status', '--porcelain']),
+    ]);
+}
 function gitModel(root) {
     const branch = runGit(root, ['branch', '--show-current']);
     const status = runGit(root, ['status', '--porcelain'])?.split('\n').filter(Boolean) ?? [];
@@ -288,7 +400,7 @@ function gitModel(root) {
     });
     return {
         repository: runGit(root, ['rev-parse', '--is-inside-work-tree']) === 'true',
-        branch: branch || undefined,
+        ...(branch ? { branch } : {}),
         dirty: status.length > 0,
         changedFiles: [...changed].sort(),
         status,
@@ -645,32 +757,59 @@ 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 });
     }
 }
-export function discoverProject(root, options = {}) {
+function discoverProjectOnce(root, options = {}, attempt = 0) {
     const packageJson = readJsonObject(resolve(root, 'package.json'));
     const dependencies = asStringRecord(packageJson.dependencies);
     const devDependencies = asStringRecord(packageJson.devDependencies);
     const scripts = asStringRecord(packageJson.scripts);
-    const allFiles = listFiles(root);
-    const signature = JSON.stringify([
-        JSON.stringify(packageJson),
-        allFiles.map((path) => {
-            const stat = statSync(resolve(root, path));
-            return [path, stat.size, stat.mtimeMs];
-        }),
-        runGit(root, ['rev-parse', 'HEAD']),
-        runGit(root, ['status', '--porcelain']),
-    ]);
+    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 = discoverySignature(root, packageJson, allFiles);
     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 +822,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 +839,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 +864,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);
@@ -756,11 +897,12 @@ export function discoverProject(root, options = {}) {
         }
         return { path, methods: [...methods].sort() };
     });
+    const detectedPackageManager = packageManager(root);
     const model = {
         version: 1,
         project: {
-            name: typeof packageJson.name === 'string' ? packageJson.name : undefined,
-            packageManager: packageManager(root),
+            ...(typeof packageJson.name === 'string' ? { name: packageJson.name } : {}),
+            ...(detectedPackageManager ? { packageManager: detectedPackageManager } : {}),
             frameworks: inferFrameworks(dependencies, devDependencies),
             scripts,
             dependencies,
@@ -788,6 +930,15 @@ export function discoverProject(root, options = {}) {
         },
         insights: buildInsights(root, files, modules, sourceFiles, dependencies, astProject),
     };
+    const finalFiles = listFiles(root, root, maxFiles);
+    const finalSignature = finalFiles.length <= maxFiles
+        ? discoverySignature(root, readJsonObject(resolve(root, 'package.json')), finalFiles)
+        : undefined;
+    if (finalSignature !== signature) {
+        if (attempt < 2)
+            return discoverProjectOnce(root, options, attempt + 1);
+        throw new DiscoveryStaleError();
+    }
     discoveryCache.set(cacheKey, { signature, model });
     discoveryReuse.set(cacheKey, reusedModules);
     if (options.persistCache ?? existsSync(resolve(root, `.${config.appName}/guard`))) {
@@ -804,9 +955,11 @@ export function discoverProject(root, options = {}) {
     }
     return model;
 }
+export function discoverProject(root, options = {}) {
+    return discoverProjectOnce(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 +968,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_STATE_STALE' | 'GUARD_INVALID_INPUT';
+export interface GuardErrorPayload {
+    status: 'error';
+    outcome: 'not-configured' | 'error';
+    configured: boolean;
+    errorCode: GuardErrorCode;
+    message: string;
+    recoverable: boolean;
+    hint?: string | undefined;
+}
+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 } : {}),
+    };
+}