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

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

@@ -0,0 +1,52 @@
+import { requirementsFor } from '../../requirements/index.js';
+const SOURCE_IMPLEMENTATION = Object.freeze({
+    id: 'astrale.sdk.typescript-source',
+    version: '1',
+});
+export function sourceImplementation(verifier) {
+    const requirements = requirementsFor(verifier.id);
+    if (!requirements)
+        throw new TypeError(`Source verifier ${verifier.id} has no requirements.`);
+    return Object.freeze({
+        ruleId: verifier.id,
+        ruleRevision: verifier.ruleRevision,
+        requiredFacts: requirements.facts,
+        implementation: SOURCE_IMPLEMENTATION,
+        evaluate(project) {
+            const evidence = verifier.evaluate(project);
+            if (evidence.length === 0)
+                return Object.freeze({ status: 'pass' });
+            const findings = evidence.map(toFinding);
+            return Object.freeze({
+                status: findings.some(({ kind }) => kind === 'fail') ? 'fail' : 'indeterminate',
+                findings: Object.freeze(findings),
+            });
+        },
+    });
+}
+export function sourceEvidence(decision) {
+    switch (decision.status) {
+        case 'pass':
+        case 'not-applicable':
+            return [];
+        case 'error':
+            throw new TypeError(decision.evidence);
+        case 'fail':
+        case 'indeterminate':
+            break;
+    }
+    return Object.freeze(decision.findings.map((finding) => Object.freeze({
+        kind: finding.kind === 'fail' ? 'violation' : 'ambiguity',
+        evidence: finding.evidence,
+        ...(finding.ambiguityReason ? { ambiguityReason: finding.ambiguityReason } : {}),
+        ...(finding.location ? { location: finding.location } : {}),
+    })));
+}
+function toFinding(evidence) {
+    return Object.freeze({
+        kind: evidence.kind === 'violation' ? 'fail' : 'indeterminate',
+        evidence: evidence.evidence,
+        ...(evidence.ambiguityReason ? { ambiguityReason: evidence.ambiguityReason } : {}),
+        ...(evidence.location ? { location: evidence.location } : {}),
+    });
+}

package/dist/tooling/linter/implementations/source/verifiers.d.ts

@@ -0,0 +1,2 @@
+import type { SourceRuleVerifier } from './verifier.js';
+export declare const sourceRuleVerifiers: readonly SourceRuleVerifier[];

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

@@ -0,0 +1,32 @@
+import { actionRules } from './actions.js';
+import { globalRules } from './global.js';
+import { integrationRules } from './integrations.js';
+import { migrationRules } from './migrations.js';
+import { mutationRules } from './mutations.js';
+import { providerRules } from './providers.js';
+import { queryRules } from './queries.js';
+import { pureRuleRules } from './rules.js';
+import { schemaRules } from './schema.js';
+import { stateRules } from './states.js';
+import { testRules } from './tests.js';
+import { uiRules } from './ui.js';
+import { utilRules } from './utility-rules.js';
+import { viewRules } from './views.js';
+import { workflowRules } from './workflows.js';
+export const sourceRuleVerifiers = Object.freeze([
+    ...globalRules,
+    ...schemaRules,
+    ...stateRules,
+    ...pureRuleRules,
+    ...queryRules,
+    ...mutationRules,
+    ...workflowRules,
+    ...migrationRules,
+    ...integrationRules,
+    ...actionRules,
+    ...providerRules,
+    ...viewRules,
+    ...uiRules,
+    ...utilRules,
+    ...testRules,
+]);

package/dist/tooling/linter/implementations/source/views.d.ts

@@ -0,0 +1,2 @@
+import type { SourceRuleVerifier } from './verifier.js';
+export declare const viewRules: readonly SourceRuleVerifier[];

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

@@ -0,0 +1,34 @@
+import { DSL_MODULES, definitionOriginAmbiguity, definitionObjects, production, violation, } from './shared.js';
+const DECLARATIONS = [
+    'defineSchema',
+    'defineClass',
+    'edgeClass',
+    'func',
+    'nodeClass',
+    'policy',
+    'property',
+    'view',
+];
+export const viewRules = [
+    {
+        id: 'VIW-SCHEMA-DECL',
+        ruleRevision: '524ca0956e1ca5ecfd0010f2973075ef9844eb3b4ccf1771d1b784508292f906',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'views')) {
+                for (const name of DECLARATIONS) {
+                    for (const definition of definitionObjects(file, name, undefined, DSL_MODULES)) {
+                        const uncertain = definitionOriginAmbiguity(file, definition, `${name} declaration`);
+                        if (uncertain) {
+                            evidence.push(uncertain);
+                            continue;
+                        }
+                        const { call } = definition;
+                        evidence.push(violation(file, call, `Views declares DSL construct ${name}; Schema owns it.`));
+                    }
+                }
+            }
+            return evidence;
+        },
+    },
+];

package/dist/tooling/linter/implementations/source/workflows.d.ts

@@ -0,0 +1,2 @@
+import type { SourceRuleVerifier } from './verifier.js';
+export declare const workflowRules: readonly SourceRuleVerifier[];

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

@@ -0,0 +1,265 @@
+import ts from 'typescript';
+import { importedSymbol, propertyChain, unwrap, visit, } from '../../adapters/typescript/index.js';
+import { ambiguity, calls, isForeignDomain, production, staticId, violation } from './shared.js';
+const STEP_METHODS = new Set(['run']);
+export const workflowRules = [
+    {
+        id: 'WFL-INT-TYPES',
+        ruleRevision: '9e170a6106bc57fe16441c6fb3d7ac4cac22c064c32eefa1118bda275f993a00',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'workflows')) {
+                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: 'WFL-STEP-IDS',
+        ruleRevision: '4f079d31de09852c7f5a8afcd5ca77959c905e76d6a771e0105f26d4bec5bc47',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'workflows')) {
+                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: 'WFL-XDOM-INT',
+        ruleRevision: 'e526868b72d44fb5d88beb61937fce9f6e90c8418381ac34e9e5a01efc1e3dee',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'workflows')) {
+                for (const sourceImport of file.imports) {
+                    if (isForeignDomain(sourceImport.specifier)) {
+                        evidence.push(violation(file, sourceImport.node, `Workflow imports foreign Domain ${sourceImport.specifier}; use an Integration.`));
+                    }
+                }
+                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;
+                    visitOwnBody(run, (node) => {
+                        if (!ts.isCallExpression(node))
+                            return;
+                        const symbol = importedSymbol(file, node.expression);
+                        if (symbol && isForeignDomain(symbol.module)) {
+                            evidence.push(violation(file, node, `Workflow invokes foreign callable ${symbol.name} directly.`));
+                        }
+                    });
+                }
+            }
+            return evidence;
+        },
+    },
+    {
+        id: 'WFL-NO-NEST',
+        ruleRevision: '1e4026f0ed8b32c9f21f0ac89fed0bd4a6eb92af1328c9781edc16edad300737',
+        evaluate(project) {
+            const evidence = [];
+            for (const file of production(project, 'workflows')) {
+                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 run = call.arguments[1] && unwrap(call.arguments[1]);
+        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 { 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,23 @@
+import { type LintDiagnostic } from './diagnostics/index.js';
+import { type LintCoverage, type RuleEvaluationOutcome } from './evaluation/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 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,69 @@
+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 { compileDomainPolicy, compileProjectDomainPolicy, domainPolicySource, } from './policy/index.js';
+import { applySuppressions } from './suppression/index.js';
+const defaultPolicy = compileDomainPolicy(domainPolicySource);
+const evaluation = bindEvaluation(defaultPolicy.catalog, domainRulePack, Object.freeze({
+    available: sourceRuleImplementations,
+    unavailable: Object.freeze([]),
+    evidenceAdmission: sourceEvidenceAdmission,
+}));
+async function lintAstraleDomain(options) {
+    const started = performance.now();
+    const root = resolve(options.root ?? process.cwd());
+    ensureActive(options.signal);
+    evaluation.assertAvailable(options.requiredRuleIds ?? []);
+    const policy = await compileProjectDomainPolicy(root, options.signal);
+    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,
+        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>;