@astrale-os/sdk 0.5.0-beta.2 → 0.5.0-beta.21

package/dist/tooling/linter/policy/compile.js

@@ -0,0 +1,257 @@
+import { createHash } from 'node:crypto';
+import { compileRuleCatalog } from '../catalog/index.js';
+import { LinterToolError } from '../diagnostics/index.js';
+const DEPENDENCY_KINDS = new Set(['runtime', 'type-only', 'composition', 'evidence']);
+const TOKEN = /^[a-z][a-z0-9.-]*$/;
+const MAX_LAYERS = 64;
+const MAX_DEPENDENCIES = 1_024;
+const MAX_ROOT_FILES = 64;
+const MAX_ALIASES = 128;
+const MAX_POLICY_STRING_BYTES = 4_096;
+const ROOT_FILE_ROLES = new Set(['configuration', 'composition', 'package-facade', 'tooling']);
+export function compileDomainPolicy(source) {
+    if (!record(source))
+        invalid('Domain policy source must be an object.');
+    if (typeof source.rules !== 'string')
+        invalid('Domain policy rules must be a string.');
+    const sourceLayers = array(source.layers, 'layers', MAX_LAYERS);
+    const sourceDependencies = array(source.dependencies, 'dependencies', MAX_DEPENDENCIES);
+    const catalog = compileRuleCatalog(source.rules);
+    const layerIds = new Set();
+    const sourcePaths = new Set();
+    const layers = sourceLayers.map((layer, index) => admitLayer(layer, index, layerIds, sourcePaths));
+    if (layers.length === 0)
+        invalid('Domain policy must declare at least one layer.');
+    const sourceRootFiles = array(source.rootFiles, 'root files', MAX_ROOT_FILES);
+    const rootIds = new Set();
+    const rootPaths = new Set();
+    const rootFiles = sourceRootFiles.map((rootFile, index) => admitRootFile(rootFile, index, rootIds, rootPaths));
+    if (rootFiles.filter(({ role }) => role === 'composition').length > 2) {
+        invalid('Domain policy may declare at most two composition root files.');
+    }
+    if (rootFiles.filter(({ role }) => role === 'package-facade').length !== 1) {
+        invalid('Domain policy must declare exactly one package-facade root file.');
+    }
+    const dependencyRootIds = new Set(rootFiles
+        .filter(({ role }) => role === 'composition' || role === 'package-facade')
+        .map(({ id }) => id));
+    const dependencyKeys = new Set();
+    const dependencies = sourceDependencies.map((dependency, index) => {
+        const admitted = admitDependency(dependency, index);
+        if (!layerIds.has(admitted.source) &&
+            !dependencyRootIds.has(admitted.source) &&
+            !isExternalSurface(admitted.source)) {
+            invalid(`Dependency row ${index + 1} has unknown source ${admitted.source}.`);
+        }
+        if (!layerIds.has(admitted.target) &&
+            !dependencyRootIds.has(admitted.target) &&
+            !isExternalSurface(admitted.target)) {
+            invalid(`Dependency row ${index + 1} has unknown target ${admitted.target}.`);
+        }
+        const key = `${admitted.source}\0${admitted.target}\0${admitted.kind}`;
+        if (dependencyKeys.has(key))
+            invalid(`Domain policy has duplicate dependency ${key.replaceAll('\0', ' -> ')}.`);
+        dependencyKeys.add(key);
+        return admitted;
+    });
+    const sourceAliases = array(source.aliases, 'aliases', MAX_ALIASES);
+    const aliasSpecifiers = new Set();
+    const admittedAliases = sourceAliases.map((alias, index) => admitAlias(alias, index, layerIds, layers, aliasSpecifiers));
+    requireAliasPairs(layers, admittedAliases);
+    rejectLayerCycles(layers, dependencies);
+    const payload = { layers, dependencies, rootFiles, aliases: admittedAliases };
+    return Object.freeze({
+        catalog,
+        digest: createHash('sha256')
+            .update(source.rules)
+            .update('\0')
+            .update(JSON.stringify(payload))
+            .digest('hex'),
+        layers: Object.freeze(layers),
+        dependencies: Object.freeze(dependencies),
+        rootFiles: Object.freeze(rootFiles),
+        aliases: Object.freeze(admittedAliases),
+    });
+}
+function admitLayer(layer, index, ids, paths) {
+    if (!record(layer))
+        invalid(`Layer row ${index + 1} must be an object.`);
+    string(layer.id, `Layer row ${index + 1} ID`);
+    string(layer.sourcePath, `Layer ${layer.id} source path`);
+    if (!TOKEN.test(layer.id))
+        invalid(`Layer row ${index + 1} has invalid ID ${layer.id}.`);
+    if (ids.has(layer.id))
+        invalid(`Domain policy has duplicate layer ${layer.id}.`);
+    ids.add(layer.id);
+    if (!/^[a-z][a-z0-9-]*\/$/.test(layer.sourcePath)) {
+        invalid(`Layer ${layer.id} has invalid source path ${layer.sourcePath}.`);
+    }
+    if (paths.has(layer.sourcePath))
+        invalid(`Domain policy has duplicate source path ${layer.sourcePath}.`);
+    paths.add(layer.sourcePath);
+    if (typeof layer.required !== 'boolean')
+        invalid(`Layer ${layer.id} required must be boolean.`);
+    return Object.freeze({ id: layer.id, sourcePath: layer.sourcePath, required: layer.required });
+}
+function admitDependency(dependency, index) {
+    if (!record(dependency))
+        invalid(`Dependency row ${index + 1} must be an object.`);
+    string(dependency.source, `Dependency row ${index + 1} source`);
+    string(dependency.target, `Dependency row ${index + 1} target`);
+    string(dependency.kind, `Dependency row ${index + 1} kind`);
+    string(dependency.condition, `Dependency row ${index + 1} condition`);
+    if (!TOKEN.test(dependency.source) || !TOKEN.test(dependency.target)) {
+        invalid(`Dependency row ${index + 1} has an invalid endpoint.`);
+    }
+    if (!DEPENDENCY_KINDS.has(dependency.kind)) {
+        invalid(`Dependency row ${index + 1} has invalid kind ${dependency.kind}.`);
+    }
+    if (!dependency.condition || dependency.condition !== dependency.condition.trim()) {
+        invalid(`Dependency row ${index + 1} has an invalid condition.`);
+    }
+    return Object.freeze({ ...dependency });
+}
+function admitRootFile(rootFile, index, ids, paths) {
+    if (!record(rootFile))
+        invalid(`Root file row ${index + 1} must be an object.`);
+    string(rootFile.id, `Root file row ${index + 1} ID`);
+    string(rootFile.sourcePath, `Root file ${rootFile.id} source path`);
+    string(rootFile.role, `Root file ${rootFile.id} role`);
+    if (!TOKEN.test(rootFile.id))
+        invalid(`Root file row ${index + 1} has invalid ID ${rootFile.id}.`);
+    if (ids.has(rootFile.id))
+        invalid(`Domain policy has duplicate root file ${rootFile.id}.`);
+    ids.add(rootFile.id);
+    if (!relativeFile(rootFile.sourcePath)) {
+        invalid(`Root file ${rootFile.id} has invalid source path ${rootFile.sourcePath}.`);
+    }
+    if (paths.has(rootFile.sourcePath)) {
+        invalid(`Domain policy has duplicate root path ${rootFile.sourcePath}.`);
+    }
+    paths.add(rootFile.sourcePath);
+    if (!ROOT_FILE_ROLES.has(rootFile.role)) {
+        invalid(`Root file ${rootFile.id} has invalid role ${rootFile.role}.`);
+    }
+    if (typeof rootFile.required !== 'boolean') {
+        invalid(`Root file ${rootFile.id} required must be boolean.`);
+    }
+    return Object.freeze({
+        id: rootFile.id,
+        sourcePath: rootFile.sourcePath,
+        role: rootFile.role,
+        required: rootFile.required,
+    });
+}
+function admitAlias(alias, index, layerIds, layers, specifiers) {
+    if (!record(alias))
+        invalid(`Alias row ${index + 1} must be an object.`);
+    string(alias.layer, `Alias row ${index + 1} layer`);
+    string(alias.kind, `Alias row ${index + 1} kind`);
+    string(alias.specifier, `Alias row ${index + 1} specifier`);
+    string(alias.typescriptTarget, `Alias row ${index + 1} TypeScript target`);
+    string(alias.packageTarget, `Alias row ${index + 1} package target`);
+    if (!layerIds.has(alias.layer))
+        invalid(`Alias row ${index + 1} has unknown layer ${alias.layer}.`);
+    const layer = layers.find(({ id }) => id === alias.layer);
+    if (alias.kind !== 'facade' && alias.kind !== 'submodule') {
+        invalid(`Alias row ${index + 1} has invalid kind ${alias.kind}.`);
+    }
+    const aliasPattern = alias.kind === 'facade' ? /^#[a-z][a-z0-9-]*$/ : /^#[a-z][a-z0-9-]*\/\*$/;
+    if (!aliasPattern.test(alias.specifier)) {
+        invalid(`Alias row ${index + 1} has invalid specifier ${alias.specifier}.`);
+    }
+    if (specifiers.has(alias.specifier)) {
+        invalid(`Domain policy has duplicate alias ${alias.specifier}.`);
+    }
+    specifiers.add(alias.specifier);
+    const expected = alias.kind === 'facade'
+        ? {
+            typescriptTarget: `./${layer.sourcePath}index.ts`,
+            packageTarget: `./${layer.sourcePath}index.ts`,
+        }
+        : {
+            typescriptTarget: `./${layer.sourcePath}*/index.ts`,
+            packageTarget: `./${layer.sourcePath}*/index.ts`,
+        };
+    if (alias.typescriptTarget !== expected.typescriptTarget) {
+        invalid(`Alias ${alias.specifier} TypeScript target must be ${expected.typescriptTarget}.`);
+    }
+    if (alias.packageTarget !== expected.packageTarget) {
+        invalid(`Alias ${alias.specifier} package target must be ${expected.packageTarget}.`);
+    }
+    return Object.freeze({
+        layer: alias.layer,
+        kind: alias.kind,
+        specifier: alias.specifier,
+        typescriptTarget: alias.typescriptTarget,
+        packageTarget: alias.packageTarget,
+    });
+}
+function requireAliasPairs(layers, aliases) {
+    for (const layer of layers) {
+        const layerAliases = aliases.filter(({ layer: candidate }) => candidate === layer.id);
+        const facades = layerAliases.filter(({ kind }) => kind === 'facade');
+        const submodules = layerAliases.filter(({ kind }) => kind === 'submodule');
+        if (facades.length !== 1 || submodules.length !== 1) {
+            invalid(`Domain policy layer ${layer.id} must declare one facade and one submodule alias.`);
+        }
+        if (submodules[0].specifier !== `${facades[0].specifier}/*`) {
+            invalid(`Domain policy layer ${layer.id} aliases must share one prefix.`);
+        }
+    }
+}
+function isExternalSurface(value) {
+    return value === 'foreign-domain';
+}
+function rejectLayerCycles(layers, dependencies) {
+    const layerIds = new Set(layers.map(({ id }) => id));
+    const graph = new Map(layers.map(({ id }) => [id, []]));
+    for (const dependency of dependencies) {
+        if (dependency.kind !== 'evidence' &&
+            layerIds.has(dependency.source) &&
+            layerIds.has(dependency.target)) {
+            graph.get(dependency.source)?.push(dependency.target);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id, route) => {
+        if (visiting.has(id))
+            invalid(`Domain policy dependency cycle: ${[...route, id].join(' -> ')}.`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const target of graph.get(id) ?? [])
+            visit(target, [...route, id]);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const layer of layers)
+        visit(layer.id, []);
+}
+function invalid(message) {
+    throw new LinterToolError(message, { code: 'LINTER_POLICY_INVALID' });
+}
+function array(value, name, maximum) {
+    if (!Array.isArray(value))
+        invalid(`Domain policy ${name} must be an array.`);
+    if (value.length > maximum) {
+        invalid(`Domain policy has ${value.length} ${name}; maximum is ${maximum}.`);
+    }
+    return value;
+}
+function string(value, name) {
+    if (typeof value !== 'string' || Buffer.byteLength(value, 'utf8') > MAX_POLICY_STRING_BYTES) {
+        invalid(`${name} must be a string of at most ${MAX_POLICY_STRING_BYTES} bytes.`);
+    }
+}
+function record(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function relativeFile(value) {
+    return (!value.startsWith('/') &&
+        !value.startsWith('./') &&
+        !value.includes('\\') &&
+        !value.split('/').includes('..') &&
+        !value.endsWith('/'));
+}

package/dist/tooling/linter/policy/configuration.d.ts

@@ -0,0 +1,11 @@
+import type { DomainPolicy, DomainPolicySource } from './index.js';
+export declare const DOMAIN_LINT_CONFIG = "astrale.lint.json";
+export interface DomainLintLayerConfiguration {
+    readonly sourcePath?: string;
+    readonly alias?: string;
+}
+export interface DomainLintConfiguration {
+    readonly layers?: Readonly<Record<string, DomainLintLayerConfiguration>>;
+}
+export declare function compileProjectDomainPolicy(root: string, signal?: AbortSignal): Promise<DomainPolicy>;
+export declare function configureDomainPolicySource(source: DomainPolicySource, configuration: DomainLintConfiguration): DomainPolicySource;

package/dist/tooling/linter/policy/configuration.js

@@ -0,0 +1,118 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { LinterToolError } from '../diagnostics/index.js';
+import { compileDomainPolicy } from './compile.js';
+import { domainPolicySource } from './generated.js';
+export const DOMAIN_LINT_CONFIG = 'astrale.lint.json';
+const MAX_CONFIG_BYTES = 64 * 1024;
+const SOURCE_PATH = /^[a-z][a-z0-9-]*\/$/;
+const ALIAS = /^#[a-z][a-z0-9-]*$/;
+export async function compileProjectDomainPolicy(root, signal) {
+    const configuration = await readDomainLintConfiguration(root, signal);
+    return compileDomainPolicy(configureDomainPolicySource(domainPolicySource, configuration));
+}
+export function configureDomainPolicySource(source, configuration) {
+    const configuredLayers = configuration.layers ?? {};
+    const knownLayers = new Set(source.layers.map(({ id }) => id));
+    for (const [id, configured] of Object.entries(configuredLayers)) {
+        if (!knownLayers.has(id))
+            invalid(`Unknown Domain lint layer ${id}.`);
+        if (!record(configured))
+            invalid(`Domain lint layer ${id} must be an object.`);
+        const fields = Object.keys(configured);
+        const unknown = fields.filter((field) => field !== 'sourcePath' && field !== 'alias');
+        if (unknown.length > 0) {
+            invalid(`Domain lint layer ${id} has unknown fields: ${unknown.join(', ')}.`);
+        }
+        if (fields.length === 0)
+            invalid(`Domain lint layer ${id} must configure a sourcePath or alias.`);
+        const sourcePath = configured.sourcePath;
+        if (sourcePath !== undefined &&
+            (typeof sourcePath !== 'string' || !SOURCE_PATH.test(sourcePath))) {
+            invalid(`Domain lint layer ${id} sourcePath must be a root directory ending in '/'.`);
+        }
+        const alias = configured.alias;
+        if (alias !== undefined && (typeof alias !== 'string' || !ALIAS.test(alias))) {
+            invalid(`Domain lint layer ${id} alias must be a root # alias without a wildcard.`);
+        }
+    }
+    const layers = source.layers.map((layer) => {
+        const sourcePath = configuredLayers[layer.id]?.sourcePath ?? layer.sourcePath;
+        return Object.freeze({ ...layer, sourcePath });
+    });
+    const sourcePaths = new Map(layers.map(({ id, sourcePath }) => [id, sourcePath]));
+    const aliases = source.aliases.map((alias) => {
+        const configuredPrefix = configuredLayers[alias.layer]?.alias;
+        const specifier = configuredPrefix === undefined
+            ? alias.specifier
+            : alias.kind === 'facade'
+                ? configuredPrefix
+                : `${configuredPrefix}/*`;
+        const sourcePath = sourcePaths.get(alias.layer);
+        const target = alias.kind === 'facade' ? `./${sourcePath}index.ts` : `./${sourcePath}*/index.ts`;
+        return Object.freeze({
+            ...alias,
+            specifier,
+            typescriptTarget: target,
+            packageTarget: target,
+        });
+    });
+    return Object.freeze({
+        ...source,
+        layers: Object.freeze(layers),
+        aliases: Object.freeze(aliases),
+    });
+}
+async function readDomainLintConfiguration(root, signal) {
+    ensureActive(signal);
+    const path = join(root, DOMAIN_LINT_CONFIG);
+    let metadata;
+    try {
+        metadata = await lstat(path);
+    }
+    catch (cause) {
+        if (cause.code === 'ENOENT')
+            return Object.freeze({});
+        invalid(`Cannot inspect Domain lint configuration ${path}.`, cause);
+    }
+    if (metadata.isSymbolicLink() || !metadata.isFile()) {
+        invalid(`Domain lint configuration must be a regular file: ${path}.`);
+    }
+    if (metadata.size > MAX_CONFIG_BYTES) {
+        invalid(`Domain lint configuration ${path} is ${metadata.size} bytes; maximum is ${MAX_CONFIG_BYTES}.`);
+    }
+    ensureActive(signal);
+    let value;
+    try {
+        const bytes = await readFile(path);
+        const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false }).decode(bytes);
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        invalid(`Cannot parse Domain lint configuration ${path}.`, cause);
+    }
+    if (!record(value))
+        invalid('Domain lint configuration must be an object.');
+    const unknown = Object.keys(value).filter((field) => field !== 'layers');
+    if (unknown.length > 0) {
+        invalid(`Domain lint configuration has unknown fields: ${unknown.join(', ')}.`);
+    }
+    if (value.layers !== undefined && !record(value.layers)) {
+        invalid('Domain lint configuration layers must be an object.');
+    }
+    return value;
+}
+function ensureActive(signal) {
+    if (signal?.aborted) {
+        throw new LinterToolError('Domain lint was cancelled.', {
+            code: 'LINTER_CANCELLED',
+            cause: signal.reason,
+        });
+    }
+}
+function invalid(message, cause) {
+    throw new LinterToolError(message, { code: 'LINTER_PROJECT_INVALID', cause });
+}
+function record(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}

package/dist/tooling/linter/policy/generated.d.ts

@@ -0,0 +1,4 @@
+import type { DomainPolicySource } from './index.js';
+/** Generated from the validated Domain knowledge catalog. Do not edit by hand. */
+export declare const domainPolicyDigest: string;
+export declare const domainPolicySource: DomainPolicySource;