@astrale-os/sdk 0.5.0-beta.13 → 0.5.0-beta.131

package/dist/tooling/linter/adapters/typescript/discover.js

@@ -0,0 +1,424 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { dirname, extname, join, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { LinterToolError } from '../../diagnostics/index.js';
+import { collectDependencyIssues, collectImports } from './imports.js';
+const IGNORED = new Set([
+    '.astrale',
+    '.dist',
+    '.domain-studio',
+    '.git',
+    '.history',
+    '.output',
+    '.turbo',
+    '.wrangler',
+    'coverage',
+    'dist',
+    'dist-client',
+    'node_modules',
+]);
+const EXTENSIONS = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx']);
+const MAX_DEPTH = 32;
+const MAX_FILES = 20_000;
+const MAX_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 128 * 1024 * 1024;
+const READ_CONCURRENCY = 32;
+const MAX_CONFIG_BYTES = 1024 * 1024;
+export async function discoverProject(root, policy, signal) {
+    ensureActive(signal);
+    const requestedRoot = resolve(root);
+    let projectRoot;
+    try {
+        if ((await lstat(requestedRoot)).isSymbolicLink()) {
+            invalidProject(`Domain project root must not be a symbolic link: ${root}.`);
+        }
+        projectRoot = await realpath(requestedRoot);
+    }
+    catch (cause) {
+        throw new LinterToolError(`Cannot resolve Domain project root ${root}.`, {
+            code: 'LINTER_PROJECT_INVALID',
+            cause,
+        });
+    }
+    const configuration = await readConfiguration(projectRoot, signal);
+    const toolingPaths = new Set(policy.rootFiles.filter(({ role }) => role === 'tooling').map(({ sourcePath }) => sourcePath));
+    const layerPaths = policy.layers.map(({ sourcePath }) => sourcePath.replace(/\/$/, ''));
+    const paths = [];
+    try {
+        await collect(projectRoot, projectRoot, paths, configuration.workspacePatterns, layerPaths, toolingPaths, 0, signal);
+    }
+    catch (cause) {
+        if (cause instanceof LinterToolError)
+            throw cause;
+        throw new LinterToolError(`Cannot read Domain project at ${projectRoot}.`, {
+            code: 'LINTER_PROJECT_INVALID',
+            cause,
+        });
+    }
+    paths.sort();
+    let metadata;
+    try {
+        metadata = await mapBounded(paths, READ_CONCURRENCY, async (path) => {
+            ensureActive(signal);
+            return { path, size: (await stat(path)).size };
+        });
+    }
+    catch (cause) {
+        if (cause instanceof LinterToolError)
+            throw cause;
+        throw new LinterToolError(`Cannot inspect Domain project at ${projectRoot}.`, {
+            code: 'LINTER_PROJECT_INVALID',
+            cause,
+        });
+    }
+    const oversized = metadata.find(({ size }) => size > MAX_FILE_BYTES);
+    if (oversized) {
+        invalidProject(`Domain source ${relative(projectRoot, oversized.path)} is ${oversized.size} bytes; maximum is ${MAX_FILE_BYTES}.`);
+    }
+    const totalBytes = metadata.reduce((total, { size }) => total + size, 0);
+    if (totalBytes > MAX_TOTAL_BYTES) {
+        invalidProject(`Domain source snapshot is ${totalBytes} bytes; maximum is ${MAX_TOTAL_BYTES}.`);
+    }
+    let files;
+    try {
+        files = await mapBounded(metadata, READ_CONCURRENCY, ({ path }) => {
+            ensureActive(signal);
+            return admitFile(projectRoot, path, policy);
+        });
+    }
+    catch (cause) {
+        if (cause instanceof LinterToolError)
+            throw cause;
+        throw new LinterToolError(`Cannot read Domain source at ${projectRoot}.`, {
+            code: 'LINTER_PROJECT_INVALID',
+            cause,
+        });
+    }
+    const syntaxFailures = files.flatMap((file) => (file.source
+        .parseDiagnostics ?? []).map((diagnostic) => {
+        const position = diagnostic.start === undefined
+            ? undefined
+            : file.source.getLineAndCharacterOfPosition(diagnostic.start);
+        return `${file.path}${position ? `:${position.line + 1}:${position.character + 1}` : ''}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`;
+    }));
+    if (syntaxFailures.length > 0) {
+        throw new LinterToolError(`Domain project contains TypeScript syntax errors:\n${syntaxFailures.slice(0, 20).join('\n')}`, { code: 'LINTER_PROJECT_INVALID' });
+    }
+    return Object.freeze({
+        root: projectRoot,
+        sourceSnapshotDigest: sourceSnapshotDigest(files),
+        policy,
+        configuration,
+        files: Object.freeze(files),
+        filesByPath: new Map(files.map((file) => [file.path, file])),
+    });
+}
+function sourceSnapshotDigest(files) {
+    const hash = createHash('sha256');
+    for (const file of files) {
+        digestField(hash, Buffer.from(file.path, 'utf8'));
+        digestField(hash, Buffer.from(file.text, 'utf8'));
+    }
+    return hash.digest('hex');
+}
+function digestField(hash, value) {
+    const length = Buffer.allocUnsafe(8);
+    length.writeBigUInt64BE(BigInt(value.length));
+    hash.update(length);
+    hash.update(value);
+}
+async function collect(root, directory, output, workspacePatterns, layerPaths, toolingPaths, depth, signal) {
+    ensureActive(signal);
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        const projectPath = normalize(relative(root, path));
+        if (entry.isSymbolicLink()) {
+            if (!IGNORED.has(entry.name)) {
+                invalidProject(`Domain compilation scope contains symbolic link ${relative(root, path)}.`);
+            }
+            continue;
+        }
+        if (entry.isDirectory()) {
+            if (entry.name === '.spec') {
+                invalidProject(`Domain projects cannot own .spec directories; Kernel is the specification owner (${projectPath}).`);
+            }
+            if (!IGNORED.has(entry.name)) {
+                if (await isWorkspaceMember(path, projectPath, workspacePatterns, layerPaths, signal))
+                    continue;
+                if (depth >= MAX_DEPTH) {
+                    invalidProject(`Domain source tree exceeds maximum depth ${MAX_DEPTH} at ${path}.`);
+                }
+                await collect(root, path, output, workspacePatterns, layerPaths, toolingPaths, depth + 1, signal);
+            }
+            continue;
+        }
+        if (!entry.isFile() || !EXTENSIONS.has(extname(entry.name)) || toolingPaths.has(projectPath))
+            continue;
+        output.push(path);
+        if (output.length > MAX_FILES) {
+            invalidProject(`Domain source tree exceeds maximum file count ${MAX_FILES}.`);
+        }
+    }
+}
+async function isWorkspaceMember(directory, projectPath, workspacePatterns, layerPaths, signal) {
+    if (!workspacePatterns.some((pattern) => glob(pattern).test(projectPath)))
+        return false;
+    if (layerPaths.some((layer) => projectPath === layer || projectPath.startsWith(`${layer}/`))) {
+        return false;
+    }
+    ensureActive(signal);
+    const manifestPath = join(directory, 'package.json');
+    let metadata;
+    try {
+        metadata = await lstat(manifestPath);
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return false;
+        throw cause;
+    }
+    if (metadata.isSymbolicLink()) {
+        invalidProject(`Workspace package manifest must not be a symbolic link: ${projectPath}/package.json.`);
+    }
+    if (!metadata.isFile())
+        return false;
+    if (metadata.size > MAX_CONFIG_BYTES) {
+        invalidProject(`Workspace package manifest ${projectPath}/package.json exceeds ${MAX_CONFIG_BYTES} config bytes.`);
+    }
+    const source = await readFile(manifestPath, 'utf8');
+    parsePackage(manifestPath, source);
+    return true;
+}
+async function admitFile(root, absolutePath, policy) {
+    const path = relative(root, absolutePath).replaceAll('\\', '/');
+    const bytes = await readFile(absolutePath);
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes);
+    }
+    catch (cause) {
+        throw new LinterToolError(`Domain source ${path} is not valid UTF-8.`, {
+            code: 'LINTER_PROJECT_INVALID',
+            cause,
+        });
+    }
+    const source = ts.createSourceFile(absolutePath, text, ts.ScriptTarget.Latest, true, scriptKind(absolutePath));
+    const layer = policy.layers.find(({ sourcePath }) => path.startsWith(sourcePath));
+    const remainder = layer ? path.slice(layer.sourcePath.length) : undefined;
+    const submodule = semanticSubmodule(layer?.id, remainder);
+    const role = sourceRole(path, layer?.id);
+    return Object.freeze({
+        absolutePath,
+        path,
+        text,
+        source,
+        role,
+        ...(layer ? { layer: layer.id } : {}),
+        ...(submodule ? { submodule } : {}),
+        imports: Object.freeze(collectImports(source)),
+        dependencyIssues: Object.freeze(collectDependencyIssues(source)),
+    });
+}
+function semanticSubmodule(layer, remainder) {
+    if (!remainder)
+        return undefined;
+    const segments = remainder.split('/');
+    const first = segments[0];
+    if (!first || first === '__tests__' || segments.length < 2)
+        return undefined;
+    if (layer === 'schema' && first === 'modules' && segments.length >= 3 && segments[1]) {
+        return `modules/${segments[1]}`;
+    }
+    return first;
+}
+function sourceRole(path, layer) {
+    const segments = path.split('/');
+    if (segments.includes('__tests__') || /\.(?:test|spec|bench|perf)\.[cm]?[jt]sx?$/.test(path)) {
+        return layer === 'tests' ? 'system-test' : 'focused-test';
+    }
+    return layer === 'tests' ? 'system-test' : 'production';
+}
+async function readConfiguration(root, signal) {
+    ensureActive(signal);
+    const entries = (await readdir(root, { withFileTypes: true })).map(({ name }) => name).sort();
+    const packagePath = join(root, 'package.json');
+    const tsconfigPath = join(root, 'tsconfig.json');
+    const workspacePath = join(root, 'pnpm-workspace.yaml');
+    const packageJson = await readOptionalConfig(packagePath, signal);
+    const tsconfigText = await readOptionalConfig(tsconfigPath, signal);
+    const workspaceText = await readOptionalConfig(workspacePath, signal);
+    const packageValue = packageJson === undefined ? undefined : parsePackage(packagePath, packageJson);
+    const tsconfigValue = tsconfigText === undefined ? undefined : parseTsconfig(tsconfigPath, tsconfigText);
+    return Object.freeze({
+        rootEntries: Object.freeze(entries),
+        typescriptAliases: freezeRecord(readTypescriptAliases(tsconfigValue)),
+        packageAliases: freezeRecord(readPackageAliases(packageValue)),
+        workspacePatterns: Object.freeze([
+            ...new Set([
+                ...readWorkspacePatterns(packageValue),
+                ...readPnpmWorkspacePatterns(workspaceText),
+            ]),
+        ]),
+    });
+}
+async function readOptionalConfig(path, signal) {
+    ensureActive(signal);
+    let metadata;
+    try {
+        metadata = await stat(path);
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return undefined;
+        throw cause;
+    }
+    if (metadata.size > MAX_CONFIG_BYTES) {
+        invalidProject(`${relative(dirname(path), path)} exceeds ${MAX_CONFIG_BYTES} config bytes.`);
+    }
+    return readFile(path, 'utf8');
+}
+function parsePackage(path, text) {
+    try {
+        const value = JSON.parse(text);
+        if (!record(value))
+            throw new TypeError('package.json root must be an object');
+        return value;
+    }
+    catch (cause) {
+        throw new LinterToolError(`Cannot parse Domain package manifest ${path}.`, {
+            code: 'LINTER_PROJECT_INVALID',
+            cause,
+        });
+    }
+}
+function parseTsconfig(path, text) {
+    const parsed = ts.parseConfigFileTextToJson(path, text);
+    if (parsed.error) {
+        invalidProject(`Cannot parse Domain TypeScript configuration ${path}: ${ts.flattenDiagnosticMessageText(parsed.error.messageText, '\n')}`);
+    }
+    if (!record(parsed.config))
+        invalidProject(`Domain TypeScript configuration ${path} is not an object.`);
+    return parsed.config;
+}
+function readTypescriptAliases(config) {
+    const compilerOptions = record(config?.compilerOptions) ? config.compilerOptions : undefined;
+    const paths = record(compilerOptions?.paths) ? compilerOptions.paths : undefined;
+    if (!paths)
+        return {};
+    return Object.fromEntries(Object.entries(paths).map(([specifier, value]) => [
+        specifier,
+        Array.isArray(value) && value.every((target) => typeof target === 'string')
+            ? Object.freeze([...value])
+            : null,
+    ]));
+}
+function readPackageAliases(manifest) {
+    const imports = record(manifest?.imports) ? manifest.imports : undefined;
+    if (!imports)
+        return {};
+    return Object.fromEntries(Object.entries(imports).map(([specifier, target]) => [
+        specifier,
+        typeof target === 'string' ? target : null,
+    ]));
+}
+function readWorkspacePatterns(manifest) {
+    const workspaces = manifest?.workspaces;
+    const values = Array.isArray(workspaces)
+        ? workspaces
+        : record(workspaces) && Array.isArray(workspaces.packages)
+            ? workspaces.packages
+            : [];
+    return values.flatMap((value) => typeof value === 'string' && validWorkspacePattern(value) ? [normalize(value)] : []);
+}
+function readPnpmWorkspacePatterns(source) {
+    if (source === undefined)
+        return [];
+    const patterns = [];
+    let inPackages = false;
+    for (const rawLine of source.split(/\r?\n/)) {
+        const line = rawLine.replace(/\s+#.*$/, '');
+        if (/^packages:\s*\[\s*\]\s*$/.test(line)) {
+            inPackages = false;
+            continue;
+        }
+        if (/^packages:\s*$/.test(line)) {
+            inPackages = true;
+            continue;
+        }
+        if (inPackages && /^\S/.test(line))
+            break;
+        if (!inPackages)
+            continue;
+        const match = /^\s+-\s+(.+?)\s*$/.exec(line);
+        if (!match)
+            continue;
+        const value = unquoteYaml(match[1]);
+        if (validWorkspacePattern(value))
+            patterns.push(normalize(value));
+    }
+    return patterns;
+}
+function unquoteYaml(value) {
+    if (value.length >= 2 &&
+        ((value.startsWith("'") && value.endsWith("'")) ||
+            (value.startsWith('"') && value.endsWith('"')))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function validWorkspacePattern(value) {
+    return (value.length > 0 &&
+        value.length <= 512 &&
+        !value.startsWith('/') &&
+        !value.includes('\\') &&
+        !value.split('/').includes('..'));
+}
+function glob(pattern) {
+    const expression = pattern
+        .split('*')
+        .map((part) => part.replace(/[|\\{}()[\]^$+?.]/g, '\\$&'))
+        .join('[^/]*');
+    return new RegExp(`^${expression.replace(/\/$/, '')}$`);
+}
+function freezeRecord(value) {
+    return Object.freeze({ ...value });
+}
+function record(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function normalize(path) {
+    return path.replaceAll('\\', '/');
+}
+function scriptKind(path) {
+    if (/\.tsx$|\.jsx$/.test(path))
+        return ts.ScriptKind.TSX;
+    if (/\.js$|\.mjs$|\.cjs$/.test(path))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+async function mapBounded(values, concurrency, transform) {
+    const output = [];
+    let cursor = 0;
+    const worker = async () => {
+        while (cursor < values.length) {
+            const index = cursor;
+            cursor += 1;
+            output[index] = await transform(values[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, () => worker()));
+    return output;
+}
+function invalidProject(message) {
+    throw new LinterToolError(message, { code: 'LINTER_PROJECT_INVALID' });
+}
+function ensureActive(signal) {
+    if (signal?.aborted) {
+        throw new LinterToolError('Domain lint was cancelled.', {
+            code: 'LINTER_CANCELLED',
+            cause: signal.reason,
+        });
+    }
+}

package/dist/tooling/linter/adapters/typescript/evidence-admission.d.ts

@@ -0,0 +1,4 @@
+import type { RuleEvidenceAdmission } from '../../evaluation/index.js';
+import type { SourceProject } from './index.js';
+/** Verifies that portable evidence locations belong to the admitted TypeScript source snapshot. */
+export declare const sourceEvidenceAdmission: RuleEvidenceAdmission<SourceProject>;

package/dist/tooling/linter/adapters/typescript/evidence-admission.js

@@ -0,0 +1,21 @@
+import { LinterToolError } from '../../diagnostics/index.js';
+/** Verifies that portable evidence locations belong to the admitted TypeScript source snapshot. */
+export const sourceEvidenceAdmission = Object.freeze({
+    assertLocation(id, location, project) {
+        const file = project.filesByPath.get(location.path);
+        if (!file)
+            ruleFailure(`Implementation ${id} located evidence outside the source snapshot.`);
+        if (location.offset === undefined)
+            return;
+        if (location.offset + location.length > file.text.length) {
+            ruleFailure(`Implementation ${id} returned an out-of-range span.`);
+        }
+        const actual = file.source.getLineAndCharacterOfPosition(location.offset);
+        if (actual.line + 1 !== location.line || actual.character + 1 !== location.column) {
+            ruleFailure(`Implementation ${id} returned an incoherent span.`);
+        }
+    },
+});
+function ruleFailure(message) {
+    throw new LinterToolError(message, { code: 'LINTER_RULE_FAILED' });
+}

package/dist/tooling/linter/adapters/typescript/imports.d.ts

@@ -0,0 +1,6 @@
+import ts from 'typescript';
+import type { SourceProject, SourceDependencyIssue, SourceFile, SourceImport } from './index.js';
+export declare function collectImports(source: ts.SourceFile): SourceImport[];
+export declare function collectDependencyIssues(source: ts.SourceFile): SourceDependencyIssue[];
+export declare function resolveProjectImport(project: SourceProject, importer: SourceFile, specifier: string): SourceFile | undefined;
+export declare function isWithin(directory: string, path: string): boolean;

package/dist/tooling/linter/adapters/typescript/imports.js

@@ -0,0 +1,172 @@
+import { dirname, extname, isAbsolute, join, relative, resolve } from 'node:path';
+import ts from 'typescript';
+import { isLocallyDeclared } from './syntax.js';
+export function collectImports(source) {
+    const imports = [];
+    for (const statement of source.statements) {
+        if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+            const bindings = new Map();
+            let namespace;
+            const clause = statement.importClause;
+            if (clause?.name)
+                bindings.set('default', clause.name.text);
+            if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
+                namespace = clause.namedBindings.name.text;
+            }
+            else if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+                for (const element of clause.namedBindings.elements) {
+                    bindings.set(element.propertyName?.text ?? element.name.text, element.name.text);
+                }
+            }
+            const namedBindings = clause?.namedBindings;
+            const allNamedTypeOnly = namedBindings !== undefined &&
+                ts.isNamedImports(namedBindings) &&
+                namedBindings.elements.length > 0 &&
+                namedBindings.elements.every(({ isTypeOnly }) => isTypeOnly);
+            imports.push({
+                specifier: statement.moduleSpecifier.text,
+                typeOnly: clause?.isTypeOnly === true || allNamedTypeOnly === true,
+                dynamic: false,
+                bindings,
+                ...(namespace ? { namespace } : {}),
+                node: statement,
+            });
+            continue;
+        }
+        if (ts.isExportDeclaration(statement) &&
+            statement.moduleSpecifier &&
+            ts.isStringLiteral(statement.moduleSpecifier)) {
+            imports.push({
+                specifier: statement.moduleSpecifier.text,
+                typeOnly: statement.isTypeOnly,
+                dynamic: false,
+                bindings: new Map(),
+                node: statement,
+            });
+        }
+    }
+    const collectDynamic = (node) => {
+        if (ts.isImportTypeNode(node)) {
+            const argument = node.argument;
+            if (ts.isLiteralTypeNode(argument) &&
+                (ts.isStringLiteral(argument.literal) ||
+                    ts.isNoSubstitutionTemplateLiteral(argument.literal))) {
+                imports.push({
+                    specifier: argument.literal.text,
+                    typeOnly: true,
+                    dynamic: false,
+                    bindings: new Map(),
+                    node,
+                });
+            }
+        }
+        if (ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+            node.arguments.length === 1 &&
+            ts.isStringLiteral(node.arguments[0])) {
+            imports.push({
+                specifier: node.arguments[0].text,
+                typeOnly: false,
+                dynamic: true,
+                bindings: new Map(),
+                node,
+            });
+        }
+        node.forEachChild(collectDynamic);
+    };
+    source.forEachChild(collectDynamic);
+    return imports;
+}
+export function collectDependencyIssues(source) {
+    const issues = [];
+    visit(source, (node) => {
+        if (ts.isImportEqualsDeclaration(node)) {
+            issues.push({ kind: 'import-equals', node });
+            return;
+        }
+        if (ts.isImportTypeNode(node)) {
+            const argument = node.argument;
+            if (!ts.isLiteralTypeNode(argument) ||
+                (!ts.isStringLiteral(argument.literal) &&
+                    !ts.isNoSubstitutionTemplateLiteral(argument.literal))) {
+                issues.push({ kind: 'nonliteral-import', node });
+            }
+            return;
+        }
+        if (!ts.isCallExpression(node))
+            return;
+        if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+            if (node.arguments.length !== 1 ||
+                (!ts.isStringLiteral(node.arguments[0]) &&
+                    !ts.isNoSubstitutionTemplateLiteral(node.arguments[0]))) {
+                issues.push({ kind: 'nonliteral-import', node });
+            }
+            return;
+        }
+        if (ts.isIdentifier(node.expression) &&
+            node.expression.text === 'require' &&
+            !isLocallyDeclared(node.expression)) {
+            issues.push({ kind: 'require', node });
+        }
+    });
+    return issues;
+}
+export function resolveProjectImport(project, importer, specifier) {
+    let target;
+    if (specifier.startsWith('.')) {
+        target = normalize(relative(project.root, resolve(dirname(importer.absolutePath), specifier)));
+    }
+    else if (specifier.startsWith('#')) {
+        const exact = project.policy.aliases.find(({ specifier: candidate }) => candidate === specifier);
+        if (exact) {
+            target = exact.typescriptTarget.replace(/^\.\//, '');
+        }
+        else {
+            const wildcard = project.policy.aliases.find(({ specifier: candidate }) => {
+                if (!candidate.endsWith('/*'))
+                    return false;
+                return specifier.startsWith(candidate.slice(0, -1));
+            });
+            if (!wildcard)
+                return undefined;
+            target = wildcard.typescriptTarget
+                .replace(/^\.\//, '')
+                .replace('*', specifier.slice(wildcard.specifier.length - 1));
+        }
+    }
+    else {
+        return undefined;
+    }
+    for (const candidate of importCandidates(target)) {
+        const file = project.filesByPath.get(candidate);
+        if (file)
+            return file;
+    }
+    return undefined;
+}
+function importCandidates(path) {
+    const extension = extname(path);
+    const candidates = [path];
+    if (['.js', '.jsx', '.mjs', '.cjs'].includes(extension)) {
+        const stem = path.slice(0, -extension.length);
+        candidates.push(`${stem}.ts`, `${stem}.tsx`, `${stem}.mts`, `${stem}.cts`);
+        const declarationExtension = extension === '.mjs' ? '.d.mts' : extension === '.cjs' ? '.d.cts' : '.d.ts';
+        candidates.push(`${stem}${declarationExtension}`);
+    }
+    if (!extension) {
+        candidates.push(`${path}.ts`, `${path}.tsx`, `${path}.mts`, `${path}.cts`);
+        candidates.push(join(path, 'index.ts'), join(path, 'index.tsx'));
+    }
+    return candidates.map(normalize);
+}
+function normalize(path) {
+    return path.replaceAll('\\', '/');
+}
+function visit(node, callback) {
+    callback(node);
+    node.forEachChild((child) => visit(child, callback));
+}
+export function isWithin(directory, path) {
+    const child = relative(directory, path);
+    return child === '' || (!child.startsWith('..') && !isAbsolute(child));
+}

package/dist/tooling/linter/adapters/typescript/index.d.ts

@@ -0,0 +1,49 @@
+export { discoverProject } from './discover.js';
+export { sourceEvidenceAdmission } from './evidence-admission.js';
+export { collectDependencyIssues, resolveProjectImport } from './imports.js';
+export { importedSymbol, isLocallyDeclared, resolveImportedSymbol, location, objectProperty, propertyChain, staticText, unwrap, visit, } from './syntax.js';
+export { assertSingleTypeUniverse } from './type-universe.js';
+export { observeQueryDefinitions } from './query-observation.js';
+export { queryCollectionKind } from './query-collection-type.js';
+export { expressionType, type ExpressionType } from './type-analysis.js';
+export { collectSuppressionDirectives } from './suppression-directives.js';
+import type ts from 'typescript';
+import type { DomainPolicy } from '../../policy/index.js';
+export type SourceRole = 'production' | 'focused-test' | 'system-test';
+export interface SourceImport {
+    readonly specifier: string;
+    readonly typeOnly: boolean;
+    readonly dynamic: boolean;
+    readonly bindings: ReadonlyMap<string, string>;
+    readonly namespace?: string;
+    readonly node: ts.Node;
+}
+export interface SourceDependencyIssue {
+    readonly kind: 'require' | 'import-equals' | 'nonliteral-import';
+    readonly node: ts.Node;
+}
+export interface SourceFile {
+    readonly absolutePath: string;
+    readonly path: string;
+    readonly text: string;
+    readonly source: ts.SourceFile;
+    readonly role: SourceRole;
+    readonly layer?: string;
+    readonly submodule?: string;
+    readonly imports: readonly SourceImport[];
+    readonly dependencyIssues: readonly SourceDependencyIssue[];
+}
+export interface SourceProjectConfiguration {
+    readonly rootEntries: readonly string[];
+    readonly typescriptAliases: Readonly<Record<string, readonly string[] | null>>;
+    readonly packageAliases: Readonly<Record<string, string | null>>;
+    readonly workspacePatterns: readonly string[];
+}
+export interface SourceProject {
+    readonly root: string;
+    readonly sourceSnapshotDigest: string;
+    readonly policy: DomainPolicy;
+    readonly configuration: SourceProjectConfiguration;
+    readonly files: readonly SourceFile[];
+    readonly filesByPath: ReadonlyMap<string, SourceFile>;
+}

package/dist/tooling/linter/adapters/typescript/index.js

@@ -0,0 +1,9 @@
+export { discoverProject } from './discover.js';
+export { sourceEvidenceAdmission } from './evidence-admission.js';
+export { collectDependencyIssues, resolveProjectImport } from './imports.js';
+export { importedSymbol, isLocallyDeclared, resolveImportedSymbol, location, objectProperty, propertyChain, staticText, unwrap, visit, } from './syntax.js';
+export { assertSingleTypeUniverse } from './type-universe.js';
+export { observeQueryDefinitions } from './query-observation.js';
+export { queryCollectionKind } from './query-collection-type.js';
+export { expressionType } from './type-analysis.js';
+export { collectSuppressionDirectives } from './suppression-directives.js';