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

package/dist/tooling/linter/evaluation/binding/bind.js

@@ -0,0 +1,355 @@
+import { ruleRevision } from '../../catalog/index.js';
+import { LinterToolError, } from '../../diagnostics/index.js';
+import { diagnostic } from './diagnostic.js';
+const TOKEN = /^[a-z][a-z0-9.-]{0,63}$/;
+const REVISION = /^[a-f0-9]{64}$/;
+const RULE_ID = /^[A-Z]+(?:-[A-Z]+)+$/;
+const MAX_VERSION_BYTES = 128;
+const MAX_EVIDENCE_BYTES = 8 * 1024;
+const MAX_FINDINGS_PER_RULE = 128;
+const AMBIGUITY_REASONS = new Set([
+    'analysis-limit',
+    'dynamic-value',
+    'external-evidence',
+    'insufficient-evidence',
+    'unresolved-import',
+    'unresolved-symbol',
+    'unsupported-syntax',
+]);
+export function bindEvaluation(catalog, pack, plan) {
+    if (!plan || typeof plan !== 'object')
+        coverageFailure('Rule implementation plan is malformed.');
+    if (!plan.evidenceAdmission ||
+        typeof plan.evidenceAdmission !== 'object' ||
+        typeof plan.evidenceAdmission.assertLocation !== 'function') {
+        coverageFailure('Rule implementation plan has no evidence admission.');
+    }
+    const evidenceAdmission = Object.freeze({
+        assertLocation: plan.evidenceAdmission.assertLocation,
+    });
+    const definitions = admitPack(catalog, pack);
+    const registry = admitImplementations(catalog, pack, definitions, plan.available);
+    const unavailable = admitUnavailable(definitions, registry, plan.unavailable);
+    const coverage = coverageFor(definitions, registry, unavailable);
+    return Object.freeze({
+        coverage,
+        assertAvailable(requiredRuleIds) {
+            if (!Array.isArray(requiredRuleIds))
+                coverageFailure('Required rule IDs must be an array.');
+            const seen = new Set();
+            const unavailable = [];
+            for (const id of requiredRuleIds) {
+                if (typeof id !== 'string' || !RULE_ID.test(id)) {
+                    coverageFailure('Required rule IDs must contain valid rule identifiers.');
+                }
+                if (seen.has(id))
+                    coverageFailure(`Required rule ID ${id} is repeated.`);
+                seen.add(id);
+                if (!definitions.some((definition) => definition.id === id)) {
+                    coverageFailure(`Required rule ${id} is absent from pack ${pack.id}.`);
+                }
+                if (!registry.has(id))
+                    unavailable.push(id);
+            }
+            if (unavailable.length > 0) {
+                coverageFailure(`Required rules are unavailable: ${unavailable.join(', ')}.`);
+            }
+        },
+        async evaluate(input, signal) {
+            const diagnostics = [];
+            const outcomes = [];
+            for (const definition of definitions) {
+                const implementation = registry.get(definition.id);
+                if (!implementation)
+                    continue;
+                ensureActive(signal);
+                let value;
+                try {
+                    value = await implementation.evaluate(input);
+                }
+                catch (cause) {
+                    if (signal?.aborted)
+                        cancelled(signal.reason ?? cause);
+                    throw new LinterToolError(`Rule implementation failed for ${definition.id}.`, {
+                        code: 'LINTER_RULE_FAILED',
+                        cause,
+                    });
+                }
+                const decision = admitDecision(definition.id, value, input, evidenceAdmission);
+                if (decision.status === 'fail' || decision.status === 'indeterminate') {
+                    diagnostics.push(...decision.findings.map((finding) => diagnostic(definition, finding)));
+                }
+                outcomes.push(Object.freeze({
+                    id: definition.id,
+                    status: decision.status,
+                    ...(decision.evidence ? { evidence: decision.evidence } : {}),
+                    implementation: implementation.implementation,
+                }));
+            }
+            return Object.freeze({
+                diagnostics: Object.freeze(diagnostics),
+                outcomes: Object.freeze(outcomes),
+            });
+        },
+    });
+}
+function admitUnavailable(definitions, registry, input) {
+    if (!Array.isArray(input))
+        coverageFailure('Rule unavailability declarations must be an array.');
+    const inPack = new Set(definitions.map(({ id }) => id));
+    const unavailable = new Map();
+    for (const entry of input) {
+        if (!entry || typeof entry !== 'object' || !inPack.has(entry.ruleId)) {
+            coverageFailure('Rule unavailability declaration names an unknown pack rule.');
+        }
+        if (entry.reason !== 'no-compatible-implementation' &&
+            entry.reason !== 'required-facts-unavailable' &&
+            entry.reason !== 'implementation-disabled') {
+            coverageFailure(`Rule ${entry.ruleId} has an invalid unavailability reason.`);
+        }
+        if (registry.has(entry.ruleId)) {
+            coverageFailure(`Rule ${entry.ruleId} is both available and unavailable.`);
+        }
+        if (unavailable.has(entry.ruleId)) {
+            coverageFailure(`Rule ${entry.ruleId} has several unavailability declarations.`);
+        }
+        unavailable.set(entry.ruleId, entry.reason);
+    }
+    return unavailable;
+}
+function admitPack(catalog, pack) {
+    if (pack.id !== 'astrale.domain')
+        coverageFailure('Domain rule pack has an invalid ID.');
+    admitIdentity({ id: pack.id, version: pack.version }, 'Rule pack');
+    if (!Array.isArray(pack.ruleIds) || !Array.isArray(pack.requirements)) {
+        coverageFailure('Domain rule pack is malformed.');
+    }
+    const seen = new Set();
+    for (const id of pack.ruleIds) {
+        if (seen.has(id))
+            coverageFailure(`Rule pack repeats ${id}.`);
+        seen.add(id);
+        if (!catalog.get(id))
+            coverageFailure(`Rule pack names unknown catalog rule ${id}.`);
+    }
+    const missing = catalog.rules.filter(({ id }) => !seen.has(id));
+    if (missing.length > 0) {
+        coverageFailure(`Rule pack omits catalog rules: ${missing.map(({ id }) => id).join(', ')}.`);
+    }
+    if (pack.requirements.length !== pack.ruleIds.length) {
+        coverageFailure('Rule pack requirement coverage is incomplete.');
+    }
+    for (let index = 0; index < pack.requirements.length; index += 1) {
+        if (pack.requirements[index]?.ruleId !== pack.ruleIds[index]) {
+            coverageFailure('Rule pack requirements and rule IDs are not aligned.');
+        }
+    }
+    return Object.freeze(pack.ruleIds.map((id) => catalog.get(id)));
+}
+function admitImplementations(catalog, pack, definitions, implementations) {
+    if (!Array.isArray(implementations))
+        coverageFailure('Rule implementations must be an array.');
+    const inPack = new Set(definitions.map(({ id }) => id));
+    const registry = new Map();
+    for (const implementation of implementations) {
+        if (!implementation || typeof implementation !== 'object') {
+            coverageFailure('Rule implementation is malformed.');
+        }
+        if (registry.has(implementation.ruleId)) {
+            coverageFailure(`Rule ${implementation.ruleId} has several implementations.`);
+        }
+        const definition = catalog.get(implementation.ruleId);
+        if (!definition || !inPack.has(implementation.ruleId)) {
+            coverageFailure(`Implementation names unknown pack rule ${implementation.ruleId}.`);
+        }
+        admitIdentity(implementation.implementation, `Implementation ${implementation.ruleId}`);
+        if (!REVISION.test(implementation.ruleRevision)) {
+            coverageFailure(`Implementation ${implementation.ruleId} has an invalid rule revision.`);
+        }
+        const expected = ruleRevision(definition);
+        if (implementation.ruleRevision !== expected) {
+            coverageFailure(`Implementation ${implementation.ruleId} implements revision ${implementation.ruleRevision}; catalog requires ${expected}.`);
+        }
+        const requiredFacts = pack.requirements.find(({ ruleId }) => ruleId === implementation.ruleId).facts;
+        if (!Array.isArray(implementation.requiredFacts) ||
+            implementation.requiredFacts.length !== requiredFacts.length ||
+            implementation.requiredFacts.some((fact, index) => fact !== requiredFacts[index])) {
+            coverageFailure(`Implementation ${implementation.ruleId} has drifted fact requirements.`);
+        }
+        if (typeof implementation.evaluate !== 'function') {
+            coverageFailure(`Implementation ${implementation.ruleId} has no evaluator.`);
+        }
+        registry.set(implementation.ruleId, Object.freeze({
+            ruleId: implementation.ruleId,
+            ruleRevision: implementation.ruleRevision,
+            requiredFacts: Object.freeze([...implementation.requiredFacts]),
+            implementation: Object.freeze({
+                id: implementation.implementation.id,
+                version: implementation.implementation.version,
+            }),
+            evaluate: implementation.evaluate,
+        }));
+    }
+    return registry;
+}
+function admitIdentity(identity, owner) {
+    if (!identity || typeof identity !== 'object' || !TOKEN.test(identity.id)) {
+        coverageFailure(`${owner} has an invalid ID.`);
+    }
+    if (typeof identity.version !== 'string' ||
+        !identity.version.trim() ||
+        Buffer.byteLength(identity.version, 'utf8') > MAX_VERSION_BYTES) {
+        coverageFailure(`${owner} has an invalid version.`);
+    }
+}
+function coverageFor(definitions, registry, unavailable) {
+    const rules = definitions.map((definition) => {
+        const implementation = registry.get(definition.id);
+        return implementation
+            ? Object.freeze({
+                id: definition.id,
+                state: 'available',
+                implementation: implementation.implementation,
+            })
+            : Object.freeze({
+                id: definition.id,
+                state: 'unavailable',
+                reason: unavailable.get(definition.id) ?? 'no-compatible-implementation',
+            });
+    });
+    const available = registry.size;
+    return Object.freeze({
+        total: definitions.length,
+        available,
+        unavailable: definitions.length - available,
+        rules: Object.freeze(rules),
+    });
+}
+function admitDecision(id, value, input, evidenceAdmission) {
+    if (!record(value))
+        ruleFailure(`Implementation ${id} returned a malformed decision.`);
+    if (value.status !== 'pass' &&
+        value.status !== 'not-applicable' &&
+        value.status !== 'fail' &&
+        value.status !== 'indeterminate' &&
+        value.status !== 'error') {
+        ruleFailure(`Implementation ${id} returned an invalid status.`);
+    }
+    const evidence = value.evidence === undefined ? undefined : boundedText(value.evidence, id);
+    if (value.status === 'error') {
+        if (!evidence)
+            ruleFailure(`Implementation ${id} error has no evidence.`);
+        if (value.findings !== undefined)
+            ruleFailure(`Implementation ${id} error contains findings.`);
+        return Object.freeze({ status: 'error', evidence });
+    }
+    if (value.status === 'pass' || value.status === 'not-applicable') {
+        if (value.findings !== undefined) {
+            ruleFailure(`Implementation ${id} ${value.status} result contains findings.`);
+        }
+        return Object.freeze({ status: value.status, ...(evidence ? { evidence } : {}) });
+    }
+    if (!Array.isArray(value.findings) || value.findings.length === 0) {
+        ruleFailure(`Implementation ${id} ${value.status} result has no findings.`);
+    }
+    if (value.findings.length > MAX_FINDINGS_PER_RULE) {
+        ruleFailure(`Implementation ${id} returned too many findings.`);
+    }
+    const findings = value.findings.map((finding) => admitFinding(id, finding, input, evidenceAdmission));
+    const derived = findings.some(({ kind }) => kind === 'fail') ? 'fail' : 'indeterminate';
+    if (value.status !== derived) {
+        ruleFailure(`Implementation ${id} status does not match its findings.`);
+    }
+    return Object.freeze({
+        status: derived,
+        findings: Object.freeze(findings),
+        ...(evidence ? { evidence } : {}),
+    });
+}
+function admitFinding(id, value, input, evidenceAdmission) {
+    if (!record(value) || (value.kind !== 'fail' && value.kind !== 'indeterminate')) {
+        ruleFailure(`Implementation ${id} returned a malformed finding.`);
+    }
+    const evidence = boundedText(value.evidence, id);
+    let ambiguityReason;
+    if (value.kind === 'fail') {
+        if (value.ambiguityReason !== undefined) {
+            ruleFailure(`Fail finding ${id} has an ambiguity reason.`);
+        }
+    }
+    else if (value.ambiguityReason === undefined) {
+        ambiguityReason = 'insufficient-evidence';
+    }
+    else if (typeof value.ambiguityReason !== 'string' ||
+        !AMBIGUITY_REASONS.has(value.ambiguityReason)) {
+        ruleFailure(`Indeterminate finding ${id} has an invalid reason.`);
+    }
+    else
+        ambiguityReason = value.ambiguityReason;
+    const location = value.location === undefined
+        ? undefined
+        : admitLocation(id, value.location, input, evidenceAdmission);
+    return Object.freeze({
+        kind: value.kind,
+        evidence,
+        ...(ambiguityReason ? { ambiguityReason } : {}),
+        ...(location ? { location } : {}),
+    });
+}
+function admitLocation(id, value, input, evidenceAdmission) {
+    if (!record(value) ||
+        typeof value.path !== 'string' ||
+        !positive(value.line) ||
+        !positive(value.column)) {
+        ruleFailure(`Implementation ${id} returned an invalid location.`);
+    }
+    const hasOffset = value.offset !== undefined;
+    const hasLength = value.length !== undefined;
+    if (hasOffset !== hasLength)
+        ruleFailure(`Implementation ${id} location has an incomplete span.`);
+    if (hasOffset) {
+        if (!nonnegative(value.offset) || !positive(value.length)) {
+            ruleFailure(`Implementation ${id} returned an invalid span.`);
+        }
+    }
+    const location = Object.freeze({
+        path: value.path,
+        line: value.line,
+        column: value.column,
+        ...(hasOffset ? { offset: value.offset, length: value.length } : {}),
+    });
+    evidenceAdmission.assertLocation(id, location, input);
+    return location;
+}
+function boundedText(value, id) {
+    if (typeof value !== 'string' || !value.trim()) {
+        ruleFailure(`Implementation ${id} returned empty evidence.`);
+    }
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > MAX_EVIDENCE_BYTES) {
+        ruleFailure(`Implementation ${id} evidence is ${bytes} bytes; maximum is ${MAX_EVIDENCE_BYTES}.`);
+    }
+    return value;
+}
+function ensureActive(signal) {
+    if (signal?.aborted)
+        cancelled(signal.reason);
+}
+function record(value) {
+    return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+function positive(value) {
+    return Number.isSafeInteger(value) && value >= 1;
+}
+function nonnegative(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function coverageFailure(message) {
+    throw new LinterToolError(message, { code: 'LINTER_RULE_COVERAGE' });
+}
+function ruleFailure(message) {
+    throw new LinterToolError(message, { code: 'LINTER_RULE_FAILED' });
+}
+function cancelled(cause) {
+    throw new LinterToolError('Domain lint was cancelled.', { code: 'LINTER_CANCELLED', cause });
+}

package/dist/tooling/linter/evaluation/binding/diagnostic.d.ts

@@ -0,0 +1,4 @@
+import type { RuleDefinition } from '../../catalog/index.js';
+import type { LintDiagnostic } from '../../diagnostics/index.js';
+import type { RuleEvidence } from '../contract/index.js';
+export declare function diagnostic(definition: RuleDefinition, finding: RuleEvidence): LintDiagnostic;

package/dist/tooling/linter/evaluation/binding/diagnostic.js

@@ -0,0 +1,16 @@
+export function diagnostic(definition, finding) {
+    return Object.freeze({
+        id: definition.id,
+        source: 'domain-rule',
+        scope: definition.scope,
+        analysis: definition.kind,
+        kind: finding.kind === 'fail' ? 'violation' : 'ambiguity',
+        ...(finding.kind === 'indeterminate'
+            ? { ambiguityReason: finding.ambiguityReason ?? 'insufficient-evidence' }
+            : {}),
+        severity: finding.kind === 'indeterminate' ? 'notice' : definition.severity,
+        message: definition.message,
+        evidence: finding.evidence,
+        ...(finding.location ? { location: finding.location } : {}),
+    });
+}

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

@@ -0,0 +1 @@
+export { bindEvaluation } from './bind.js';

package/dist/tooling/linter/evaluation/binding/index.js

@@ -0,0 +1 @@
+export { bindEvaluation } from './bind.js';

package/dist/tooling/linter/evaluation/contract/availability.d.ts

@@ -0,0 +1,27 @@
+import type { EvaluationResult } from './decision.js';
+import type { RuleImplementationIdentity } from './implementation.js';
+export type RuleAvailabilityReason = 'no-compatible-implementation' | 'required-facts-unavailable' | 'implementation-disabled';
+export interface RuleUnavailableImplementation {
+    readonly ruleId: string;
+    readonly reason: RuleAvailabilityReason;
+}
+export type RuleAvailability = Readonly<{
+    id: string;
+    state: 'available';
+    implementation: RuleImplementationIdentity;
+}> | Readonly<{
+    id: string;
+    state: 'unavailable';
+    reason: RuleAvailabilityReason;
+}>;
+export interface LintCoverage {
+    readonly total: number;
+    readonly available: number;
+    readonly unavailable: number;
+    readonly rules: readonly RuleAvailability[];
+}
+export interface EvaluationBinding<TInput> {
+    readonly coverage: LintCoverage;
+    assertAvailable(requiredRuleIds: readonly string[]): void;
+    evaluate(input: TInput, signal?: AbortSignal): Promise<EvaluationResult>;
+}

package/dist/tooling/linter/evaluation/contract/availability.js

@@ -0,0 +1 @@
+export {};

package/dist/tooling/linter/evaluation/contract/decision.d.ts

@@ -0,0 +1,25 @@
+import type { LintDiagnostic } from '../../diagnostics/index.js';
+import type { RuleEvidence } from './evidence.js';
+import type { RuleImplementationIdentity } from './implementation.js';
+export type RuleDecision = Readonly<{
+    status: 'pass' | 'not-applicable';
+    evidence?: string;
+}> | Readonly<{
+    status: 'fail' | 'indeterminate';
+    findings: readonly RuleEvidence[];
+    evidence?: string;
+}> | Readonly<{
+    status: 'error';
+    evidence: string;
+}>;
+export type RuleEvaluationStatus = RuleDecision['status'];
+export interface RuleEvaluationOutcome {
+    readonly id: string;
+    readonly status: RuleEvaluationStatus;
+    readonly evidence?: string;
+    readonly implementation: RuleImplementationIdentity;
+}
+export interface EvaluationResult {
+    readonly diagnostics: readonly LintDiagnostic[];
+    readonly outcomes: readonly RuleEvaluationOutcome[];
+}

package/dist/tooling/linter/evaluation/contract/decision.js

@@ -0,0 +1 @@
+export {};

package/dist/tooling/linter/evaluation/contract/evidence.d.ts

@@ -0,0 +1,11 @@
+import type { AmbiguityReason, DiagnosticLocation } from '../../diagnostics/index.js';
+export interface RuleEvidence {
+    readonly kind: 'fail' | 'indeterminate';
+    readonly evidence: string;
+    readonly ambiguityReason?: AmbiguityReason;
+    readonly location?: DiagnosticLocation;
+}
+/** Host-owned admission for locations returned against one exact evaluation input. */
+export interface RuleEvidenceAdmission<TInput> {
+    assertLocation(ruleId: string, location: DiagnosticLocation, input: TInput): void;
+}

package/dist/tooling/linter/evaluation/contract/evidence.js

@@ -0,0 +1 @@
+export {};

package/dist/tooling/linter/evaluation/contract/implementation.d.ts

@@ -0,0 +1,21 @@
+import type { RuleFactRequirement } from '../../requirements/index.js';
+import type { RuleUnavailableImplementation } from './availability.js';
+import type { RuleDecision } from './decision.js';
+import type { RuleEvidenceAdmission } from './evidence.js';
+export interface RuleImplementationIdentity {
+    readonly id: string;
+    readonly version: string;
+}
+export interface RuleImplementation<TInput> {
+    readonly ruleId: string;
+    readonly ruleRevision: string;
+    readonly requiredFacts: readonly RuleFactRequirement[];
+    readonly implementation: RuleImplementationIdentity;
+    evaluate(input: TInput): RuleDecision | Promise<RuleDecision>;
+}
+/** Complete generation-specific implementation input admitted by evaluation binding. */
+export interface RuleImplementationPlan<TInput> {
+    readonly available: readonly RuleImplementation<TInput>[];
+    readonly unavailable: readonly RuleUnavailableImplementation[];
+    readonly evidenceAdmission: RuleEvidenceAdmission<TInput>;
+}

package/dist/tooling/linter/evaluation/contract/implementation.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,4 @@
+export type { EvaluationBinding, LintCoverage, RuleAvailability, RuleAvailabilityReason, RuleUnavailableImplementation, } from './availability.js';
+export type { EvaluationResult, RuleDecision, RuleEvaluationOutcome, RuleEvaluationStatus, } from './decision.js';
+export type { RuleEvidence, RuleEvidenceAdmission } from './evidence.js';
+export type { RuleImplementation, RuleImplementationIdentity, RuleImplementationPlan, } from './implementation.js';

package/dist/tooling/linter/evaluation/contract/index.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,2 @@
+export { bindEvaluation } from './binding/index.js';
+export type { EvaluationBinding, EvaluationResult, LintCoverage, RuleAvailability, RuleAvailabilityReason, RuleDecision, RuleEvaluationOutcome, RuleEvaluationStatus, RuleEvidence, RuleEvidenceAdmission, RuleImplementation, RuleImplementationIdentity, RuleImplementationPlan, RuleUnavailableImplementation, } from './contract/index.js';

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

@@ -0,0 +1 @@
+export { bindEvaluation } from './binding/index.js';

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

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