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

package/dist/tooling/linter/implementations/source/workflows.js

@@ -0,0 +1,240 @@
+import ts from 'typescript';
+import { propertyChain, unwrap, visit } from '../../adapters/typescript/index.js';
+import { ambiguity, calls, production, staticId, violation } from './shared.js';
+const STEP_METHODS = new Set(['run']);
+export const workflowRules = [
+    {
+        id: 'FNC-INT-TYPES',
+        ruleRevision: 'd7f9733e3724ff3c449203551012b7c37bf7af7d2e0bc5b2642308822601a119',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'functions')) {
+                if (workflowDefinitions(file).length === 0)
+                    continue;
+                for (const statement of file.source.statements) {
+                    if (ts.isInterfaceDeclaration(statement) &&
+                        (statement.name.text.endsWith('Integrations') ||
+                            statement.name.text.endsWith('Clients'))) {
+                        evidence.push(violation(file, statement, `Workflow ${statement.name.text} manually redeclares Integration clients; reference declared Integration definitions.`));
+                    }
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'FNC-STEP-IDS',
+        ruleRevision: '98f082909d0df405d36e17218d266cd7eacbfb8ce6dd42efa565fa02df64d43c',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'functions')) {
+                for (const definition of workflowDefinitions(file)) {
+                    if (definition.origin === 'ambiguous') {
+                        evidence.push(ambiguity(file, definition.call, 'Workflow definition resolves through a local facade whose ultimate public constructor origin is unknown.'));
+                        continue;
+                    }
+                    const { call, run } = definition;
+                    if (!run) {
+                        evidence.push(ambiguity(file, call, 'Workflow run is not a static function.'));
+                        continue;
+                    }
+                    const roots = stepRoots(run);
+                    if (roots.length === 0) {
+                        evidence.push(ambiguity(file, run, 'Workflow step binding cannot be identified from its context parameter.'));
+                        continue;
+                    }
+                    const ids = new Set();
+                    visitOwnBody(run, (node) => {
+                        if (!ts.isCallExpression(node))
+                            return;
+                        const method = stepMethod(node, roots);
+                        if (!method)
+                            return;
+                        const id = staticId(node.arguments[0]);
+                        if (!id || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(id)) {
+                            evidence.push(violation(file, node.arguments[0] ?? node, `Workflow ${method} step ID is not a non-empty kebab-case literal.`));
+                        }
+                        else if (ids.has(id)) {
+                            evidence.push(violation(file, node.arguments[0], `Workflow duplicates step ID ${id}.`));
+                        }
+                        else
+                            ids.add(id);
+                    });
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'FNC-NO-NEST',
+        ruleRevision: 'f2d818d1da69830c9ccaf183c5eb0310c795ab5da1a67871952aef1c2ef7600c',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'functions')) {
+                const helpers = localFunctions(file.source);
+                for (const definition of workflowDefinitions(file)) {
+                    if (definition.origin === 'ambiguous') {
+                        evidence.push(ambiguity(file, definition.call, 'Workflow definition resolves through a local facade whose ultimate public constructor origin is unknown.'));
+                        continue;
+                    }
+                    const { run } = definition;
+                    if (!run)
+                        continue;
+                    const roots = stepRoots(run);
+                    visitOwnBody(run, (node) => {
+                        if (!ts.isCallExpression(node) || stepMethod(node, roots) !== 'run')
+                            return;
+                        const callbackValue = node.arguments[1] && unwrap(node.arguments[1]);
+                        if (!callbackValue) {
+                            evidence.push(ambiguity(file, node, 'step.run callback is absent.'));
+                            return;
+                        }
+                        if (ts.isArrowFunction(callbackValue) || ts.isFunctionExpression(callbackValue)) {
+                            traceNestedSteps(file, callbackValue, run, roots, helpers, evidence, new Set());
+                            return;
+                        }
+                        if (ts.isIdentifier(callbackValue)) {
+                            const candidates = helpers.get(callbackValue.text) ?? [];
+                            if (candidates.length !== 1) {
+                                evidence.push(ambiguity(file, callbackValue, `step.run callback ${callbackValue.text} does not resolve to one local function.`));
+                                return;
+                            }
+                            traceNestedSteps(file, candidates[0], run, [], helpers, evidence, new Set());
+                            return;
+                        }
+                        evidence.push(ambiguity(file, callbackValue, 'step.run callback is not statically callable.'));
+                    });
+                }
+            }
+            return evidence;
+        },
+    },
+];
+function workflowDefinitions(file) {
+    return calls(file, 'defineWorkflow').map(({ call: factory, origin }) => {
+        const call = ts.isCallExpression(factory.parent) && factory.parent.expression === factory
+            ? factory.parent
+            : factory;
+        const candidate = call.arguments.length === 2
+            ? call.arguments[1]
+            : call.arguments.length === 3
+                ? call.arguments[2]
+                : undefined;
+        const run = candidate && unwrap(candidate);
+        return {
+            call,
+            origin,
+            ...(run && (ts.isArrowFunction(run) || ts.isFunctionExpression(run)) ? { run } : {}),
+        };
+    });
+}
+function stepRoots(run) {
+    const parameter = run.parameters[0]?.name;
+    if (!parameter)
+        return [];
+    if (ts.isIdentifier(parameter))
+        return [[parameter.text, 'step']];
+    if (!ts.isObjectBindingPattern(parameter))
+        return [];
+    return parameter.elements.flatMap((element) => {
+        const property = element.propertyName;
+        const sourceName = property && ts.isIdentifier(property)
+            ? property.text
+            : ts.isIdentifier(element.name)
+                ? element.name.text
+                : undefined;
+        return sourceName === 'step' && ts.isIdentifier(element.name) ? [[element.name.text]] : [];
+    });
+}
+function stepMethod(call, roots) {
+    const chain = propertyChain(call.expression);
+    if (!chain || !STEP_METHODS.has(chain.at(-1) ?? ''))
+        return undefined;
+    return roots.some((root) => root.every((part, index) => chain[index] === part) && chain.length === root.length + 1)
+        ? chain.at(-1)
+        : undefined;
+}
+function visitOwnBody(fn, callback) {
+    if (!fn.body)
+        return;
+    const walk = (node) => {
+        callback(node);
+        if (node !== fn.body && ts.isFunctionLike(node))
+            return;
+        node.forEachChild(walk);
+    };
+    walk(fn.body);
+}
+function localFunctions(source) {
+    const result = new Map();
+    const add = (name, fn) => {
+        result.set(name, [...(result.get(name) ?? []), fn]);
+    };
+    visit(source, (node) => {
+        if (ts.isFunctionDeclaration(node) && node.name)
+            add(node.name.text, node);
+        if (ts.isVariableDeclaration(node) &&
+            ts.isIdentifier(node.name) &&
+            node.initializer &&
+            (ts.isArrowFunction(unwrap(node.initializer)) ||
+                ts.isFunctionExpression(unwrap(node.initializer)))) {
+            add(node.name.text, unwrap(node.initializer));
+        }
+    });
+    return result;
+}
+function traceNestedSteps(file, fn, workflowRun, roots, helpers, evidence, active) {
+    if (!fn.body || active.has(fn))
+        return;
+    active.add(fn);
+    const walk = (node) => {
+        if (node !== fn.body && ts.isFunctionLike(node))
+            return;
+        if (ts.isCallExpression(node)) {
+            const nested = stepMethod(node, roots);
+            if (nested === 'run') {
+                evidence.push(violation(file, node, `step.run callback reaches nested step.${nested}.`));
+                return;
+            }
+            const target = unwrap(node.expression);
+            if (ts.isIdentifier(target)) {
+                const candidates = helpers.get(target.text) ?? [];
+                const mapped = mappedStepRoots(node.arguments, candidates[0]?.parameters ?? [], roots);
+                if (candidates.length === 1) {
+                    const closedRoots = functionNestedInside(candidates[0], workflowRun) ? roots : [];
+                    traceNestedSteps(file, candidates[0], workflowRun, [...closedRoots, ...mapped], helpers, evidence, active);
+                }
+                else if (mapped.length > 0) {
+                    evidence.push(ambiguity(file, node, `Helper ${target.text} receives the step binding but does not resolve to one local function.`));
+                }
+            }
+        }
+        node.forEachChild(walk);
+    };
+    walk(fn.body);
+    active.delete(fn);
+}
+function mappedStepRoots(arguments_, parameters, roots) {
+    const mapped = [];
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const chain = propertyChain(arguments_[index]);
+        if (!chain || !roots.some((root) => sameChain(root, chain)))
+            continue;
+        const parameter = parameters[index]?.name;
+        if (parameter && ts.isIdentifier(parameter))
+            mapped.push([parameter.text]);
+    }
+    return mapped;
+}
+function sameChain(left, right) {
+    return left.length === right.length && left.every((part, index) => part === right[index]);
+}
+function functionNestedInside(candidate, owner) {
+    let current = candidate.parent;
+    while (current) {
+        if (current === owner)
+            return true;
+        current = current.parent;
+    }
+    return false;
+}

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

@@ -0,0 +1,9 @@
+export { LinterToolError } from './diagnostics/index.js';
+export { lintDomain } from './lint.js';
+export { formatLintResult } from './report/index.js';
+export type { DiagnosticKind, DiagnosticAnalysisKind, DiagnosticLocation, DiagnosticSeverity, DiagnosticSource, AmbiguityReason, LintDiagnostic, LinterToolErrorCode, } from './diagnostics/index.js';
+export type { LintCoverage, RuleAvailability, RuleAvailabilityReason, RuleEvaluationOutcome, RuleEvaluationStatus, RuleImplementationIdentity, } from './evaluation/index.js';
+export type { LintDomainOptions, LintResult } from './lint.js';
+export type { DisabledRule, DomainLintConfiguration, DomainLintLayerConfiguration, } from './policy/index.js';
+export type { LintReportFormat } from './report/index.js';
+export type { SuppressedDiagnostic } from './suppression/index.js';

package/dist/tooling/linter/index.js

@@ -0,0 +1,3 @@
+export { LinterToolError } from './diagnostics/index.js';
+export { lintDomain } from './lint.js';
+export { formatLintResult } from './report/index.js';

package/dist/tooling/linter/lint.d.ts

@@ -0,0 +1,25 @@
+import { type LintDiagnostic } from './diagnostics/index.js';
+import { type LintCoverage, type RuleEvaluationOutcome } from './evaluation/index.js';
+import { type DisabledRule } from './policy/index.js';
+import { type SuppressedDiagnostic } from './suppression/index.js';
+export interface LintDomainOptions {
+    readonly root?: string;
+    readonly signal?: AbortSignal;
+    readonly requiredRuleIds?: readonly string[];
+    readonly generic?: boolean;
+    readonly fix?: boolean;
+}
+export interface LintResult {
+    readonly root: string;
+    readonly policyDigest: string;
+    readonly sourceSnapshotDigest: string;
+    readonly diagnostics: readonly LintDiagnostic[];
+    readonly disabled: readonly DisabledRule[];
+    readonly suppressed: readonly SuppressedDiagnostic[];
+    readonly coverage: LintCoverage;
+    readonly outcomes: readonly RuleEvaluationOutcome[];
+    readonly files: number;
+    readonly durationMs: number;
+    readonly exitCode: 0 | 1;
+}
+export declare function lintDomain(options?: LintDomainOptions): Promise<LintResult>;

package/dist/tooling/linter/lint.js

@@ -0,0 +1,70 @@
+import { resolve } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { assertSingleTypeUniverse, collectSuppressionDirectives, discoverProject, sourceEvidenceAdmission, } from './adapters/typescript/index.js';
+import { LinterToolError, sortDiagnostics } from './diagnostics/index.js';
+import { bindEvaluation, } from './evaluation/index.js';
+import { sourceRuleImplementations } from './implementations/source/index.js';
+import { runOxlint } from './oxlint/index.js';
+import { domainRulePack } from './packs/index.js';
+import { compileProjectDomainLint } from './policy/index.js';
+import { applySuppressions } from './suppression/index.js';
+async function lintAstraleDomain(options) {
+    const started = performance.now();
+    const root = resolve(options.root ?? process.cwd());
+    ensureActive(options.signal);
+    const configured = await compileProjectDomainLint(root, options.signal);
+    const policy = configured.policy;
+    const evaluation = bindEvaluation(policy.catalog, domainRulePack, Object.freeze({
+        available: sourceRuleImplementations,
+        unavailable: Object.freeze([]),
+        evidenceAdmission: sourceEvidenceAdmission,
+    }), { disabledRuleIds: configured.disabled.map(({ ruleId }) => ruleId) });
+    evaluation.assertAvailable(options.requiredRuleIds ?? []);
+    await assertSingleTypeUniverse(root, options.signal);
+    const project = await discoverProject(root, policy, options.signal);
+    const evaluated = await evaluation.evaluate(project, options.signal);
+    const suppression = applySuppressions(collectSuppressionDirectives(project), evaluated.diagnostics);
+    const diagnostics = sortDiagnostics(suppression.diagnostics);
+    return {
+        root: project.root,
+        policyDigest: policy.digest,
+        sourceSnapshotDigest: project.sourceSnapshotDigest,
+        diagnostics,
+        disabled: configured.disabled,
+        suppressed: suppression.suppressed,
+        coverage: evaluation.coverage,
+        outcomes: evaluated.outcomes,
+        files: project.files.length,
+        durationMs: Math.max(0, Math.round(performance.now() - started)),
+        exitCode: diagnostics.some(({ severity }) => severity === 'error') ||
+            evaluated.outcomes.some(({ status }) => status === 'error')
+            ? 1
+            : 0,
+    };
+}
+function ensureActive(signal) {
+    if (signal?.aborted) {
+        throw new LinterToolError('Domain lint was cancelled.', {
+            code: 'LINTER_CANCELLED',
+            cause: signal.reason,
+        });
+    }
+}
+export async function lintDomain(options = {}) {
+    const started = performance.now();
+    const domain = await lintAstraleDomain(options);
+    if (options.generic === false)
+        return domain;
+    const generic = await runOxlint(domain.root, options.fix ?? false, { signal: options.signal });
+    const diagnostics = sortDiagnostics([...domain.diagnostics, ...generic.diagnostics]);
+    return {
+        ...domain,
+        diagnostics,
+        files: Math.max(domain.files, generic.files),
+        durationMs: Math.max(0, Math.round(performance.now() - started)),
+        exitCode: diagnostics.some(({ severity }) => severity === 'error') ||
+            domain.outcomes.some(({ status }) => status === 'error')
+            ? 1
+            : 0,
+    };
+}

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

@@ -0,0 +1,3 @@
+export { runOxlint } from './run.js';
+export type { OxlintResult } from './run.js';
+export type { OxlintProcessOptions } from './process.js';

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

@@ -0,0 +1 @@
+export { runOxlint } from './run.js';

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

@@ -0,0 +1,18 @@
+export interface OxlintProcessOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+    readonly outputLimitBytes?: number;
+    readonly terminationGraceMs?: number;
+}
+export type OxlintProcessResult = {
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+};
+/**
+ * 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 declare function runOxlintProcess(bin: string, args: readonly string[], cwd: string, options?: OxlintProcessOptions): Promise<OxlintProcessResult>;

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>;