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

package/dist/tooling/linter/oxlint/process.js

@@ -0,0 +1,169 @@
+import { spawn } from 'node:child_process';
+import { LinterToolError } from '../diagnostics/index.js';
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_OUTPUT_LIMIT_BYTES = 16 * 1024 * 1024;
+const DEFAULT_TERMINATION_GRACE_MS = 1_000;
+/**
+ * Run Oxlint under the runtime it declares, independent of the SDK CLI's
+ * parent runtime. The published CLI intentionally runs under Bun, while
+ * Oxlint's executable is a Node program.
+ */
+export async function runOxlintProcess(bin, args, cwd, options = {}) {
+    const timeoutMs = positiveInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 'timeoutMs');
+    const outputLimitBytes = positiveInteger(options.outputLimitBytes, DEFAULT_OUTPUT_LIMIT_BYTES, 'outputLimitBytes');
+    const terminationGraceMs = nonNegativeInteger(options.terminationGraceMs, DEFAULT_TERMINATION_GRACE_MS, 'terminationGraceMs');
+    if (options.signal?.aborted)
+        throw cancelledError(options.signal.reason);
+    let child;
+    try {
+        child = spawn('node', [bin, ...args], {
+            cwd,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+    }
+    catch (cause) {
+        throw startError(bin, cause);
+    }
+    return await new Promise((resolve, reject) => {
+        const stdout = [];
+        const stderr = [];
+        let capturedBytes = 0;
+        let settled = false;
+        let processError;
+        let terminationReason;
+        let forceKillTimer;
+        const timeout = setTimeout(() => {
+            terminate({ kind: 'timeout', timeoutMs });
+        }, timeoutMs);
+        timeout.unref?.();
+        const onAbort = () => terminate({ kind: 'cancelled', cause: options.signal?.reason });
+        options.signal?.addEventListener('abort', onAbort, { once: true });
+        const onStdout = (chunk) => capture(stdout, chunk);
+        const onStderr = (chunk) => capture(stderr, chunk);
+        child.stdout?.on('data', onStdout);
+        child.stderr?.on('data', onStderr);
+        // `close` follows both normal exit and spawn errors. Record an error here
+        // but settle only after `close`, so the process handle and stdio are always
+        // reaped before the caller continues.
+        child.once('error', (cause) => {
+            processError = cause;
+            clearTimeout(timeout);
+        });
+        child.once('close', (status, signal) => {
+            finish(() => {
+                if (terminationReason) {
+                    reject(terminationError(terminationReason));
+                    return;
+                }
+                if (processError) {
+                    reject(startError(bin, processError));
+                    return;
+                }
+                resolve({
+                    status,
+                    signal,
+                    stdout: Buffer.concat(stdout).toString('utf8'),
+                    stderr: Buffer.concat(stderr).toString('utf8'),
+                });
+            });
+        });
+        // Close the race between the pre-spawn check and listener registration.
+        if (options.signal?.aborted)
+            onAbort();
+        function capture(target, chunk) {
+            if (terminationReason)
+                return;
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            const remaining = outputLimitBytes - capturedBytes;
+            if (remaining > 0) {
+                const accepted = Math.min(remaining, buffer.byteLength);
+                target.push(buffer.subarray(0, accepted));
+                capturedBytes += accepted;
+            }
+            if (buffer.byteLength > remaining) {
+                terminate({ kind: 'output-limit', limitBytes: outputLimitBytes });
+            }
+        }
+        function terminate(reason) {
+            if (settled || terminationReason)
+                return;
+            terminationReason = reason;
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                forceKill();
+                return;
+            }
+            forceKillTimer = setTimeout(forceKill, terminationGraceMs);
+            forceKillTimer.unref?.();
+        }
+        function forceKill() {
+            if (settled || child.exitCode !== null || child.signalCode !== null)
+                return;
+            try {
+                child.kill('SIGKILL');
+            }
+            catch {
+                // The close/error event remains the authoritative process outcome.
+            }
+        }
+        function finish(settle) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            if (forceKillTimer)
+                clearTimeout(forceKillTimer);
+            options.signal?.removeEventListener('abort', onAbort);
+            child.stdout?.off('data', onStdout);
+            child.stderr?.off('data', onStderr);
+            settle();
+        }
+    });
+}
+function startError(bin, cause) {
+    return new LinterToolError(`Could not start Oxlint with Node at ${bin}.`, {
+        code: 'OXLINT_START_FAILED',
+        cause,
+    });
+}
+function cancelledError(cause) {
+    return new LinterToolError('Oxlint was cancelled and its process was terminated.', {
+        code: 'OXLINT_CANCELLED',
+        cause,
+    });
+}
+function terminationError(reason) {
+    switch (reason.kind) {
+        case 'cancelled':
+            return cancelledError(reason.cause);
+        case 'output-limit':
+            return new LinterToolError(`Oxlint exceeded the ${formatBytes(reason.limitBytes)} output limit and was terminated.`, { code: 'OXLINT_OUTPUT_LIMIT' });
+        case 'timeout':
+            return new LinterToolError(`Oxlint exceeded the ${formatDuration(reason.timeoutMs)} timeout and was terminated.`, { code: 'OXLINT_TIMEOUT' });
+    }
+}
+function positiveInteger(value, fallback, name) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result <= 0) {
+        throw new TypeError(`${name} must be a positive integer.`);
+    }
+    return result;
+}
+function nonNegativeInteger(value, fallback, name) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 0) {
+        throw new TypeError(`${name} must be a non-negative integer.`);
+    }
+    return result;
+}
+function formatDuration(milliseconds) {
+    return milliseconds % 1_000 === 0 ? `${milliseconds / 1_000}s` : `${milliseconds}ms`;
+}
+function formatBytes(bytes) {
+    const mib = 1024 * 1024;
+    return bytes % mib === 0 ? `${bytes / mib} MiB` : `${bytes} bytes`;
+}

package/dist/tooling/linter/oxlint/run.d.ts

@@ -0,0 +1,7 @@
+import { type LintDiagnostic } from '../diagnostics/index.js';
+import { type OxlintProcessOptions } from './process.js';
+export interface OxlintResult {
+    readonly diagnostics: readonly LintDiagnostic[];
+    readonly files: number;
+}
+export declare function runOxlint(root: string, fix: boolean, options?: OxlintProcessOptions): Promise<OxlintResult>;

package/dist/tooling/linter/oxlint/run.js

@@ -0,0 +1,253 @@
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LinterToolError, } from '../diagnostics/index.js';
+import { DOMAIN_OXLINT_IGNORE_PATTERNS } from '../oxlint-config/index.js';
+import { runOxlintProcess } from './process.js';
+const MAX_DIAGNOSTICS = 100_000;
+const MAX_LABELS = 256;
+export async function runOxlint(root, fix, options = {}) {
+    const packageJson = join(root, 'package.json');
+    const projectRequire = createRequire(packageJson);
+    const sdkRequire = createRequire(import.meta.url);
+    const oxlintPackage = resolvePackage('oxlint/package.json', projectRequire, sdkRequire);
+    const bin = join(dirname(oxlintPackage), 'bin', 'oxlint');
+    const config = projectConfig(root) ?? internalConfigPath();
+    const args = ['.', '--format=json', '--no-error-on-unmatched-pattern', '--config', config];
+    // Config-file ignores are rooted at the config's own directory. Enforce the
+    // SDK's traversal boundary at the target process as well so the internal
+    // fallback config and imported presets cannot discover dependency/build trees.
+    for (const pattern of DOMAIN_OXLINT_IGNORE_PATTERNS)
+        args.push('--ignore-pattern', pattern);
+    if (fix)
+        args.push('--fix');
+    const { status, signal, stdout, stderr } = await runOxlintProcess(bin, args, root, options);
+    if (status !== 0 && status !== 1) {
+        const outcome = signal ? `signal ${signal}` : `status ${status ?? 'unknown'}`;
+        const detail = failureDetail(stderr, stdout);
+        throw new LinterToolError(`Oxlint failed with ${outcome}.${detail ? `\n${detail}` : ''}`, {
+            code: 'OXLINT_FAILED',
+        });
+    }
+    let output;
+    try {
+        const parsed = JSON.parse(stdout);
+        output = admitOxlintOutput(parsed, root);
+    }
+    catch (error) {
+        const detail = failureDetail(stderr, stdout) || `Oxlint exited with status ${status}`;
+        throw new LinterToolError(`Oxlint did not produce a diagnostic report.\n${detail}`, {
+            code: 'OXLINT_INVALID_OUTPUT',
+            cause: error,
+        });
+    }
+    return {
+        diagnostics: (output.diagnostics ?? []).map((diagnostic) => normalizeDiagnostic(root, diagnostic)),
+        files: output.number_of_files ?? 0,
+    };
+}
+function resolvePackage(id, projectRequire, sdkRequire) {
+    try {
+        return projectRequire.resolve(id);
+    }
+    catch (projectError) {
+        try {
+            return sdkRequire.resolve(id);
+        }
+        catch {
+            throw new LinterToolError('Oxlint is not installed. Add the scaffolded Oxlint dev dependency and run your package manager install.', { code: 'OXLINT_NOT_INSTALLED', cause: projectError });
+        }
+    }
+}
+function admitOxlintOutput(value, root) {
+    if (!record(value))
+        throw new TypeError('Oxlint report must be an object.');
+    const rawDiagnostics = value.diagnostics === undefined ? [] : value.diagnostics;
+    if (!Array.isArray(rawDiagnostics))
+        throw new TypeError('Oxlint diagnostics must be an array.');
+    if (rawDiagnostics.length > MAX_DIAGNOSTICS) {
+        throw new TypeError(`Oxlint returned more than ${MAX_DIAGNOSTICS} diagnostics.`);
+    }
+    const diagnostics = rawDiagnostics.map((diagnostic, index) => admitOxlintDiagnostic(diagnostic, index, root));
+    const files = value.number_of_files;
+    if (files !== undefined && !nonnegativeInteger(files)) {
+        throw new TypeError('Oxlint number_of_files must be a nonnegative safe integer.');
+    }
+    return { diagnostics, ...(files === undefined ? {} : { number_of_files: files }) };
+}
+function admitOxlintDiagnostic(value, index, root) {
+    if (!record(value))
+        throw new TypeError(`Oxlint diagnostic ${index + 1} must be an object.`);
+    for (const field of ['message', 'code', 'url', 'help', 'filename']) {
+        if (value[field] !== undefined && typeof value[field] !== 'string') {
+            throw new TypeError(`Oxlint diagnostic ${index + 1} ${field} must be a string.`);
+        }
+    }
+    if (value.severity !== undefined &&
+        value.severity !== 'error' &&
+        value.severity !== 'warning' &&
+        value.severity !== 'advice') {
+        throw new TypeError(`Oxlint diagnostic ${index + 1} has invalid severity.`);
+    }
+    const labels = value.labels === undefined ? undefined : admitLabels(value.labels, index);
+    if (typeof value.filename === 'string') {
+        admitOxlintLocation(root, value.filename, labels?.[0]?.span);
+    }
+    return {
+        ...(value.message === undefined ? {} : { message: value.message }),
+        ...(value.code === undefined ? {} : { code: value.code }),
+        ...(value.severity === undefined ? {} : { severity: value.severity }),
+        ...(value.url === undefined ? {} : { url: value.url }),
+        ...(value.help === undefined ? {} : { help: value.help }),
+        ...(value.filename === undefined ? {} : { filename: value.filename }),
+        ...(labels === undefined ? {} : { labels }),
+    };
+}
+function admitLabels(value, diagnosticIndex) {
+    if (!Array.isArray(value)) {
+        throw new TypeError(`Oxlint diagnostic ${diagnosticIndex + 1} labels must be an array.`);
+    }
+    if (value.length > MAX_LABELS) {
+        throw new TypeError(`Oxlint diagnostic ${diagnosticIndex + 1} has too many labels.`);
+    }
+    return value.map((label, labelIndex) => {
+        if (!record(label)) {
+            throw new TypeError(`Oxlint diagnostic ${diagnosticIndex + 1} label ${labelIndex + 1} must be an object.`);
+        }
+        if (label.span === undefined)
+            return {};
+        if (!record(label.span)) {
+            throw new TypeError(`Oxlint diagnostic ${diagnosticIndex + 1} label ${labelIndex + 1} span must be an object.`);
+        }
+        const span = {};
+        for (const field of ['offset', 'length']) {
+            const number = label.span[field];
+            if (number !== undefined && !nonnegativeInteger(number)) {
+                throw new TypeError(`Oxlint diagnostic ${diagnosticIndex + 1} has invalid ${field}.`);
+            }
+            if (number !== undefined)
+                span[field] = number;
+        }
+        for (const field of ['line', 'column']) {
+            const number = label.span[field];
+            if (number !== undefined && !positiveInteger(number)) {
+                throw new TypeError(`Oxlint diagnostic ${diagnosticIndex + 1} has invalid ${field}.`);
+            }
+            if (number !== undefined)
+                span[field] = number;
+        }
+        return { span };
+    });
+}
+function admitOxlintLocation(root, filename, span) {
+    if (!filename)
+        throw new TypeError('Oxlint diagnostic filename must not be empty.');
+    const absolute = isAbsolute(filename) ? resolve(filename) : resolve(root, filename);
+    const child = relative(resolve(root), absolute);
+    if (child === '..' || child.startsWith(`..${sep}`) || isAbsolute(child)) {
+        throw new TypeError(`Oxlint diagnostic path is outside the project root: ${filename}.`);
+    }
+    if (!existsSync(absolute)) {
+        throw new TypeError(`Oxlint diagnostic path does not exist: ${filename}.`);
+    }
+    const realRoot = realpathSync(root);
+    const realFile = realpathSync(absolute);
+    const realChild = relative(realRoot, realFile);
+    if (realChild === '..' || realChild.startsWith(`..${sep}`) || isAbsolute(realChild)) {
+        throw new TypeError(`Oxlint diagnostic real path is outside the project root: ${filename}.`);
+    }
+    if (!span)
+        return;
+    const source = readFileSync(realFile);
+    if ((span.offset === undefined) !== (span.length === undefined)) {
+        throw new TypeError('Oxlint diagnostic span must provide offset and length together.');
+    }
+    if (span.offset !== undefined &&
+        span.length !== undefined &&
+        span.offset + span.length > source.length) {
+        throw new TypeError(`Oxlint diagnostic span is outside ${filename}.`);
+    }
+    if (span.line !== undefined || span.column !== undefined) {
+        if (span.line === undefined || span.column === undefined) {
+            throw new TypeError('Oxlint diagnostic span must provide line and column together.');
+        }
+        const lines = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false })
+            .decode(source)
+            .split('\n');
+        if (span.line > lines.length || span.column > (lines[span.line - 1]?.length ?? 0) + 1) {
+            throw new TypeError(`Oxlint diagnostic line or column is outside ${filename}.`);
+        }
+    }
+}
+function failureDetail(stderr, stdout) {
+    const detail = stderr.trim() || stdout.trim();
+    const limit = 4_000;
+    return detail.length <= limit ? detail : `…${detail.slice(-limit)}`;
+}
+function projectConfig(root) {
+    for (const name of [
+        'oxlint.config.ts',
+        'oxlint.config.js',
+        'oxlint.config.mjs',
+        'oxlint.config.cjs',
+        '.oxlintrc.json',
+        '.oxlintrc.jsonc',
+    ]) {
+        const path = join(root, name);
+        if (existsSync(path))
+            return path;
+    }
+    return undefined;
+}
+function internalConfigPath() {
+    const current = fileURLToPath(import.meta.url);
+    const extension = current.endsWith('.ts') ? '.ts' : '.js';
+    return join(dirname(current), '..', 'oxlint-config', `index${extension}`);
+}
+function normalizeDiagnostic(root, diagnostic) {
+    const id = normalizeCode(diagnostic.code ?? 'oxlint/unknown');
+    const span = diagnostic.labels?.[0]?.span;
+    return {
+        id,
+        source: 'oxlint',
+        scope: 'generic',
+        analysis: 'generic',
+        kind: 'violation',
+        severity: normalizeSeverity(diagnostic.severity),
+        message: diagnostic.message ?? 'Oxlint reported a violation.',
+        ...(diagnostic.help ? { evidence: diagnostic.help } : {}),
+        ...(diagnostic.filename
+            ? {
+                location: {
+                    path: relativePath(root, diagnostic.filename),
+                    line: span?.line ?? 1,
+                    column: span?.column ?? 1,
+                    ...(span?.offset !== undefined ? { offset: span.offset } : {}),
+                    ...(span?.length !== undefined ? { length: span.length } : {}),
+                },
+            }
+            : {}),
+    };
+}
+function normalizeCode(code) {
+    const match = /^([^()]+)\(([^()]+)\)$/.exec(code);
+    return match ? `${match[1]}/${match[2]}` : code;
+}
+function normalizeSeverity(severity) {
+    return severity === 'error' ? 'error' : 'warning';
+}
+function relativePath(root, filename) {
+    const absolute = resolve(root, filename);
+    const path = relative(root, absolute);
+    return sep === '/' ? path : path.split(sep).join('/');
+}
+function record(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function positiveInteger(value) {
+    return Number.isSafeInteger(value) && value >= 1;
+}
+function nonnegativeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}

package/dist/tooling/linter/oxlint-config/ignore-patterns.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Process-level traversal boundary shared by the source-loaded Oxlint config
+ * and the invocation that roots these patterns in the target project.
+ */
+export declare const DOMAIN_OXLINT_IGNORE_PATTERNS: readonly string[];

package/dist/tooling/linter/oxlint-config/ignore-patterns.js

@@ -0,0 +1,9 @@
+/**
+ * Process-level traversal boundary shared by the source-loaded Oxlint config
+ * and the invocation that roots these patterns in the target project.
+ */
+export const DOMAIN_OXLINT_IGNORE_PATTERNS = Object.freeze([
+    '**/dist/**',
+    '**/node_modules/**',
+    '**/coverage/**',
+]);

package/dist/tooling/linter/oxlint-config/index.d.ts

@@ -0,0 +1,4 @@
+import { type OxlintConfig } from 'oxlint';
+export { DOMAIN_OXLINT_IGNORE_PATTERNS } from './ignore-patterns.js';
+export declare const domainOxlintConfig: OxlintConfig;
+export default domainOxlintConfig;

package/dist/tooling/linter/oxlint-config/index.js

@@ -0,0 +1,38 @@
+import { defineConfig } from 'oxlint';
+import { DOMAIN_OXLINT_IGNORE_PATTERNS } from './ignore-patterns.js';
+export { DOMAIN_OXLINT_IGNORE_PATTERNS } from './ignore-patterns.js';
+export const domainOxlintConfig = defineConfig({
+    rules: {
+        'no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+        'no-explicit-any': 'warn',
+        'consistent-type-imports': 'warn',
+        'no-console': 'warn',
+        'prefer-const': 'error',
+        eqeqeq: ['error', 'always'],
+    },
+    ignorePatterns: [
+        ...DOMAIN_OXLINT_IGNORE_PATTERNS,
+        '**/*.js',
+        '**/*.mjs',
+        '**/*.cjs',
+        '**/*.gen.ts',
+        '**/*.gen.tsx',
+    ],
+    overrides: [
+        {
+            files: [
+                '**/__tests__/**/*.ts',
+                '**/*.test.ts',
+                '**/*.perf.ts',
+                '**/*.bench.ts',
+                '**/*.spec.ts',
+            ],
+            rules: {
+                'no-explicit-any': 'off',
+                'no-unused-vars': 'off',
+                'no-console': 'off',
+            },
+        },
+    ],
+});
+export default domainOxlintConfig;

package/dist/tooling/linter/packs/domain.d.ts

@@ -0,0 +1,2 @@
+import type { DomainRulePack } from './index.js';
+export declare const domainRulePack: DomainRulePack;

package/dist/tooling/linter/packs/domain.js

@@ -0,0 +1,7 @@
+import { domainRuleRequirements } from '../requirements/index.js';
+export const domainRulePack = Object.freeze({
+    id: 'astrale.domain',
+    version: '1',
+    requirements: domainRuleRequirements,
+    ruleIds: Object.freeze(domainRuleRequirements.map(({ ruleId }) => ruleId)),
+});

package/dist/tooling/linter/packs/index.d.ts

@@ -0,0 +1,8 @@
+export { domainRulePack } from './domain.js';
+import type { RuleRequirements } from '../requirements/index.js';
+export interface DomainRulePack {
+    readonly id: 'astrale.domain';
+    readonly version: string;
+    readonly requirements: readonly RuleRequirements[];
+    readonly ruleIds: readonly string[];
+}

package/dist/tooling/linter/packs/index.js

@@ -0,0 +1 @@
+export { domainRulePack } from './domain.js';

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

@@ -0,0 +1,2 @@
+import type { DomainPolicy, DomainPolicySource } from './index.js';
+export declare function compileDomainPolicy(source: DomainPolicySource): DomainPolicy;