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

package/dist/tooling/linter/adapters/typescript/type-universe.js

@@ -0,0 +1,264 @@
+import { existsSync } from 'node:fs';
+import { readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LinterToolError } from '../../diagnostics/index.js';
+const BRANDED = [
+    '@astrale-os/kernel-client',
+    '@astrale-os/kernel-core',
+    '@astrale-os/kernel-dsl',
+];
+const CONVENTIONAL_MEMBERS = ['client', 'frontend', 'schema', 'worker'];
+const MAX_MANIFESTS = 256;
+const MAX_DEPENDENCIES = 2_048;
+const MAX_MEMBER_ENTRIES = 4_096;
+const MAX_MANIFEST_BYTES = 1024 * 1024;
+const MAX_DEPENDENCY_DEPTH = 32;
+export async function assertSingleTypeUniverse(root, signal) {
+    ensureActive(signal);
+    const manifests = await consumerManifests(root, signal);
+    const consumers = [
+        ...manifests.map((path) => ({ label: relative(root, dirname(path)) || '.', path })),
+        { label: '@astrale-os/sdk/linter', path: sdkPackageJson() },
+    ];
+    for (const packageName of BRANDED) {
+        ensureActive(signal);
+        const resolutions = (await Promise.all(consumers.map(async (consumer) => ({
+            ...consumer,
+            resolved: await packageRoot(packageName, consumer.path, signal),
+        })))).filter((entry) => entry.resolved !== undefined);
+        const paths = new Set(resolutions.map(({ resolved }) => resolved));
+        if (paths.size <= 1)
+            continue;
+        const detail = [...paths]
+            .sort()
+            .map((path) => {
+            const owners = resolutions
+                .filter(({ resolved }) => resolved === path)
+                .map(({ label }) => label);
+            return `  ${path}\n    from: ${[...new Set(owners)].sort().join(', ')}`;
+        })
+            .join('\n');
+        throw new LinterToolError(`Multiple physical installations of ${packageName} among admitted discovered consumers would create incompatible Astrale types.\n${detail}\nReinstall the workspace so every admitted discovered consumer resolves one compatible package instance.`, { code: 'LINTER_PREFLIGHT_FAILED' });
+    }
+}
+async function consumerManifests(root, signal) {
+    ensureActive(signal);
+    const manifest = join(root, 'package.json');
+    if (!existsSync(manifest))
+        return [];
+    const manifests = new Set([manifest]);
+    const rootPackage = await readPackage(manifest, signal);
+    const packageWorkspaces = Array.isArray(rootPackage?.workspaces)
+        ? rootPackage.workspaces
+        : rootPackage?.workspaces?.packages;
+    const pnpmWorkspaces = await readPnpmWorkspace(root, signal);
+    const workspaces = [...(packageWorkspaces ?? []), ...pnpmWorkspaces];
+    for (const member of workspaces) {
+        ensureActive(signal);
+        if (typeof member !== 'string' || !safeMemberPattern(member))
+            continue;
+        for (const path of await expandMember(root, member, signal))
+            addManifest(manifests, path);
+    }
+    for (const member of CONVENTIONAL_MEMBERS) {
+        const path = resolveMember(root, member);
+        if (path && existsSync(path))
+            addManifest(manifests, path);
+    }
+    const pending = [...manifests].map((path) => ({ path, depth: 0 }));
+    let dependencyCount = 0;
+    for (let index = 0; index < pending.length; index += 1) {
+        ensureActive(signal);
+        const { path: consumer, depth } = pending[index];
+        const packageJson = await readPackage(consumer, signal);
+        const dependencies = { ...packageJson?.optionalDependencies, ...packageJson?.dependencies };
+        for (const name of Object.keys(dependencies).sort()) {
+            ensureActive(signal);
+            dependencyCount += 1;
+            if (dependencyCount > MAX_DEPENDENCIES)
+                preflightLimit(`dependency count ${MAX_DEPENDENCIES}`);
+            if (!name.startsWith('@astrale-domains/'))
+                continue;
+            if (depth >= MAX_DEPENDENCY_DEPTH)
+                preflightLimit(`dependency depth ${MAX_DEPENDENCY_DEPTH}`);
+            const dependency = await dependencyManifest(name, consumer, signal);
+            if (dependency && !manifests.has(dependency)) {
+                addManifest(manifests, dependency);
+                pending.push({ path: dependency, depth: depth + 1 });
+            }
+        }
+    }
+    return [...manifests].sort();
+}
+async function dependencyManifest(name, consumer, signal) {
+    ensureActive(signal);
+    const require = createRequire(consumer);
+    try {
+        const resolved = await realpath(require.resolve(`${name}/package.json`));
+        ensureActive(signal);
+        return resolved;
+    }
+    catch (cause) {
+        if (cause instanceof LinterToolError)
+            throw cause;
+        return undefined;
+    }
+}
+async function packageRoot(name, manifest, signal) {
+    ensureActive(signal);
+    if (!existsSync(manifest))
+        return undefined;
+    try {
+        const resolved = await realpath(dirname(createRequire(manifest).resolve(`${name}/package.json`)));
+        ensureActive(signal);
+        return resolved;
+    }
+    catch (cause) {
+        if (cause instanceof LinterToolError)
+            throw cause;
+        return undefined;
+    }
+}
+function addManifest(manifests, manifest) {
+    manifests.add(manifest);
+    if (manifests.size > MAX_MANIFESTS)
+        preflightLimit(`manifest count ${MAX_MANIFESTS}`);
+}
+async function readPackage(path, signal) {
+    ensureActive(signal);
+    try {
+        const metadata = await stat(path);
+        if (metadata.size > MAX_MANIFEST_BYTES)
+            preflightLimit(`manifest bytes ${MAX_MANIFEST_BYTES}`);
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        ensureActive(signal);
+        return value;
+    }
+    catch (cause) {
+        if (cause instanceof LinterToolError)
+            throw cause;
+        return undefined;
+    }
+}
+async function expandMember(root, pattern, signal) {
+    ensureActive(signal);
+    const star = pattern.indexOf('*');
+    if (star === -1) {
+        const manifest = resolveMember(root, pattern);
+        return manifest && existsSync(manifest) ? [manifest] : [];
+    }
+    const prefix = pattern.slice(0, star).replace(/\/$/, '');
+    const suffix = pattern.slice(star + 1).replace(/^\//, '');
+    const directory = resolveMemberDirectory(root, prefix);
+    if (!directory)
+        return [];
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+        ensureActive(signal);
+    }
+    catch {
+        return [];
+    }
+    if (entries.length > MAX_MEMBER_ENTRIES)
+        preflightLimit(`workspace entries ${MAX_MEMBER_ENTRIES}`);
+    const manifests = [];
+    for (const entry of entries) {
+        ensureActive(signal);
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        const member = suffix ? join(prefix, entry.name, suffix) : join(prefix, entry.name);
+        const manifest = resolveMember(root, member);
+        if (manifest && existsSync(manifest))
+            manifests.push(manifest);
+    }
+    return manifests;
+}
+async function readPnpmWorkspace(root, signal) {
+    const path = join(root, 'pnpm-workspace.yaml');
+    if (!existsSync(path))
+        return [];
+    ensureActive(signal);
+    const metadata = await stat(path);
+    if (metadata.size > MAX_MANIFEST_BYTES)
+        preflightLimit(`workspace bytes ${MAX_MANIFEST_BYTES}`);
+    const source = await readFile(path, 'utf8');
+    ensureActive(signal);
+    const members = [];
+    let packages = false;
+    for (const rawLine of source.split(/\r?\n/)) {
+        const line = rawLine.replace(/\s+#.*$/, '');
+        if (/^packages:\s*\[\s*\]\s*$/.test(line)) {
+            packages = false;
+            continue;
+        }
+        if (/^packages:\s*$/.test(line)) {
+            packages = true;
+            continue;
+        }
+        if (packages && /^\S/.test(line))
+            break;
+        if (!packages)
+            continue;
+        const match = /^\s+-\s+(.+?)\s*$/.exec(line);
+        if (!match)
+            continue;
+        const value = unquote(match[1]);
+        if (safeMemberPattern(value))
+            members.push(value);
+    }
+    return members;
+}
+function unquote(value) {
+    if (value.length >= 2 &&
+        ((value.startsWith("'") && value.endsWith("'")) ||
+            (value.startsWith('"') && value.endsWith('"')))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function safeMemberPattern(value) {
+    return (value.length > 0 &&
+        value.length <= 512 &&
+        !value.startsWith('/') &&
+        !value.includes('\\') &&
+        !value.split('/').includes('..') &&
+        !/[?[\]{}!]/u.test(value) &&
+        (value.match(/\*/g)?.length ?? 0) <= 1);
+}
+function resolveMember(root, member) {
+    const directory = resolveMemberDirectory(root, member);
+    return directory ? join(directory, 'package.json') : undefined;
+}
+function resolveMemberDirectory(root, member) {
+    const directory = resolve(root, member);
+    const child = relative(root, directory);
+    return child === '' || (!child.startsWith('..') && !child.startsWith('/')) ? directory : undefined;
+}
+function preflightLimit(limit) {
+    throw new LinterToolError(`Type-universe discovery exceeded ${limit}.`, {
+        code: 'LINTER_PREFLIGHT_FAILED',
+    });
+}
+function ensureActive(signal) {
+    if (signal?.aborted) {
+        throw new LinterToolError('Domain lint was cancelled.', {
+            code: 'LINTER_CANCELLED',
+            cause: signal.reason,
+        });
+    }
+}
+function sdkPackageJson() {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(directory, 'package.json');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return candidate;
+        directory = parent;
+    }
+}

package/dist/tooling/linter/analysis/query/decision.d.ts

@@ -0,0 +1,4 @@
+import type { RuleDecision } from '../../evaluation/index.js';
+import type { QueryDefinitionObservation } from './observation.js';
+export declare function decideCanonicalQuery(observations: readonly QueryDefinitionObservation[]): RuleDecision;
+export declare function decideSingleQuery(observations: readonly QueryDefinitionObservation[]): RuleDecision;

package/dist/tooling/linter/analysis/query/decision.js

@@ -0,0 +1,73 @@
+export function decideCanonicalQuery(observations) {
+    const findings = [];
+    for (const observation of observations) {
+        if (!isSingle(observation, findings))
+            continue;
+        const count = observation.canonicalRequestCount;
+        if (count.state === 'known') {
+            if (count.value !== 1) {
+                findings.push(finding('fail', observation, count.value === 0
+                    ? `Query ${observation.subjectId} returns a non-canonical graph request.`
+                    : `Query ${observation.subjectId} produces ${count.value} canonical QueryAST roots; expected exactly one.`));
+            }
+        }
+        else
+            findings.push(epistemicFinding(observation, 'canonical QueryAST origin', count));
+    }
+    return decision(findings);
+}
+export function decideSingleQuery(observations) {
+    const findings = [];
+    for (const observation of observations) {
+        if (!isSingle(observation, findings))
+            continue;
+        inspectCount(observation, 'build', observation.buildCallbackCount, 1, findings);
+        inspectCount(observation, 'project', observation.projectCallbackCount, 1, findings, true);
+    }
+    return decision(findings);
+}
+function isSingle(observation, findings) {
+    const constructor = observation.constructorIdentity;
+    if (constructor.state !== 'known') {
+        findings.push(epistemicFinding(observation, 'Query constructor identity', constructor));
+        return false;
+    }
+    if (constructor.value.kind !== 'sdk-query')
+        return false;
+    const kind = observation.definitionKind;
+    if (kind.state === 'known')
+        return kind.value === 'single';
+    findings.push(epistemicFinding(observation, 'Query definition kind', kind));
+    return false;
+}
+function inspectCount(observation, name, count, expected, findings, maximum = false) {
+    if (count.state !== 'known') {
+        findings.push(epistemicFinding(observation, `${name} callback cardinality`, count));
+        return;
+    }
+    const invalid = maximum ? count.value > expected : count.value !== expected;
+    if (!invalid)
+        return;
+    findings.push(finding('fail', observation, maximum
+        ? `Query ${observation.subjectId} declares ${count.value} ${name} callbacks; expected at most ${expected}.`
+        : `Query ${observation.subjectId} declares ${count.value} ${name} callbacks; expected exactly ${expected}.`));
+}
+function epistemicFinding(observation, subject, value) {
+    return finding('indeterminate', observation, `${subject} for Query ${observation.subjectId} is ${value.state}: ${value.reason}`, value.state === 'unsupported' ? 'unsupported-syntax' : 'insufficient-evidence');
+}
+function finding(kind, observation, evidence, ambiguityReason) {
+    return Object.freeze({
+        kind,
+        evidence,
+        ...(ambiguityReason ? { ambiguityReason } : {}),
+        ...(observation.location ? { location: observation.location } : {}),
+    });
+}
+function decision(findings) {
+    if (findings.length === 0)
+        return Object.freeze({ status: 'pass' });
+    return Object.freeze({
+        status: findings.some(({ kind }) => kind === 'fail') ? 'fail' : 'indeterminate',
+        findings: Object.freeze([...findings]),
+    });
+}

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

@@ -0,0 +1,3 @@
+export { decideCanonicalQuery, decideSingleQuery } from './decision.js';
+export { ambiguous, known, unknown, unsupported } from './observation.js';
+export type { Epistemic, QueryConstructorIdentity, QueryDefinitionObservation, } from './observation.js';

package/dist/tooling/linter/analysis/query/index.js

@@ -0,0 +1,2 @@
+export { decideCanonicalQuery, decideSingleQuery } from './decision.js';
+export { ambiguous, known, unknown, unsupported } from './observation.js';

package/dist/tooling/linter/analysis/query/observation.d.ts

@@ -0,0 +1,35 @@
+import type { DiagnosticLocation } from '../../diagnostics/index.js';
+export type Epistemic<T> = Readonly<{
+    state: 'known';
+    value: T;
+}> | Readonly<{
+    state: 'unknown';
+    reason: string;
+}> | Readonly<{
+    state: 'ambiguous';
+    reason: string;
+}> | Readonly<{
+    state: 'unsupported';
+    reason: string;
+}>;
+export type QueryConstructorIdentity = Readonly<{
+    kind: 'sdk-query';
+    canonicalId: 'astrale.sdk.defineQuery';
+    aliases: readonly string[];
+}> | Readonly<{
+    kind: 'other';
+    displayName: string;
+}>;
+export interface QueryDefinitionObservation {
+    readonly subjectId: string;
+    readonly location?: DiagnosticLocation;
+    readonly constructorIdentity: Epistemic<QueryConstructorIdentity>;
+    readonly definitionKind: Epistemic<'single' | 'composite' | 'other'>;
+    readonly canonicalRequestCount: Epistemic<number>;
+    readonly buildCallbackCount: Epistemic<number>;
+    readonly projectCallbackCount: Epistemic<number>;
+}
+export declare function known<T>(value: T): Epistemic<T>;
+export declare function unknown<T>(reason: string): Epistemic<T>;
+export declare function ambiguous<T>(reason: string): Epistemic<T>;
+export declare function unsupported<T>(reason: string): Epistemic<T>;

package/dist/tooling/linter/analysis/query/observation.js

@@ -0,0 +1,12 @@
+export function known(value) {
+    return Object.freeze({ state: 'known', value });
+}
+export function unknown(reason) {
+    return Object.freeze({ state: 'unknown', reason });
+}
+export function ambiguous(reason) {
+    return Object.freeze({ state: 'ambiguous', reason });
+}
+export function unsupported(reason) {
+    return Object.freeze({ state: 'unsupported', reason });
+}

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

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

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

@@ -0,0 +1,110 @@
+import { LinterToolError } from '../diagnostics/index.js';
+const HEADER = ['id', 'scope', 'kind', 'severity', 'message', 'verification', 'example'];
+const RULE_KINDS = new Set([
+    'architecture',
+    'structure',
+    'dependency',
+    'declaration',
+    'dataflow',
+    'behavior',
+    'evidence',
+]);
+const RULE_SEVERITIES = new Set(['error', 'warning']);
+const ID = /^[A-Z]+(?:-[A-Z]+)+$/;
+const SCOPE = /^[a-z][a-z0-9.-]*$/;
+const EXAMPLE = /^[a-z][a-z0-9-]*[.]md$/;
+const MAX_CATALOG_BYTES = 2 * 1024 * 1024;
+const MAX_RULES = 512;
+const MAX_CELL_BYTES = 16 * 1024;
+export function compileRuleCatalog(source) {
+    if (typeof source !== 'string')
+        invalid('Rule catalog must be a string.');
+    const bytes = Buffer.byteLength(source, 'utf8');
+    if (bytes > MAX_CATALOG_BYTES) {
+        invalid(`Rule catalog is ${bytes} bytes; maximum is ${MAX_CATALOG_BYTES}.`);
+    }
+    if (source.includes('\r'))
+        invalid('Rule catalog must use LF line endings.');
+    if (!source.endsWith('\n'))
+        invalid('Rule catalog must end with one newline.');
+    if (source.endsWith('\n\n'))
+        invalid('Rule catalog must not contain empty rows.');
+    const lines = source.slice(0, -1).split('\n');
+    const header = lines.shift()?.split('\t') ?? [];
+    if (!same(header, HEADER)) {
+        invalid(`Rule catalog header must be exactly: ${HEADER.join('\t')}`);
+    }
+    if (lines.length > MAX_RULES) {
+        invalid(`Rule catalog has ${lines.length} rows; maximum is ${MAX_RULES}.`);
+    }
+    const seen = new Set();
+    const rules = lines.map((line, index) => {
+        const number = index + 2;
+        if (!line)
+            invalid(`Rule catalog row ${number} is empty.`);
+        const cells = line.split('\t');
+        if (cells.length !== HEADER.length) {
+            invalid(`Rule catalog row ${number} has ${cells.length} cells; expected ${HEADER.length}.`);
+        }
+        for (let cell = 0; cell < cells.length; cell += 1) {
+            const value = cells[cell] ?? '';
+            if (!value)
+                invalid(`Rule catalog row ${number} has an empty ${HEADER[cell]} cell.`);
+            if (Buffer.byteLength(value, 'utf8') > MAX_CELL_BYTES) {
+                invalid(`Rule catalog row ${number} ${HEADER[cell]} exceeds ${MAX_CELL_BYTES} bytes.`);
+            }
+            if (hasControl(value)) {
+                invalid(`Rule catalog row ${number} has a control character in ${HEADER[cell]}.`);
+            }
+            if (value !== value.trim()) {
+                invalid(`Rule catalog row ${number} has surrounding whitespace in ${HEADER[cell]}.`);
+            }
+        }
+        const [id, scope, kind, severity, message, verification, example] = cells;
+        if (!ID.test(id) || id.length > 18)
+            invalid(`Rule catalog row ${number} has invalid ID ${id}.`);
+        if (seen.has(id))
+            invalid(`Rule catalog contains duplicate ID ${id}.`);
+        seen.add(id);
+        if (!SCOPE.test(scope))
+            invalid(`Rule ${id} has invalid scope ${scope}.`);
+        if (!RULE_KINDS.has(kind))
+            invalid(`Rule ${id} has invalid kind ${kind}.`);
+        if (!RULE_SEVERITIES.has(severity)) {
+            invalid(`Rule ${id} has invalid severity ${severity}.`);
+        }
+        if (!EXAMPLE.test(example))
+            invalid(`Rule ${id} has invalid example ${example}.`);
+        return Object.freeze({
+            id,
+            scope,
+            kind: kind,
+            severity: severity,
+            message,
+            verification,
+            example,
+        });
+    });
+    if (rules.length === 0)
+        invalid('Rule catalog must contain at least one rule.');
+    const byId = new Map(rules.map((rule) => [rule.id, rule]));
+    return Object.freeze({
+        size: rules.length,
+        rules: Object.freeze(rules),
+        get(id) {
+            return byId.get(id);
+        },
+    });
+}
+function hasControl(value) {
+    return Array.from(value).some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 8 || code === 11 || code === 12 || (code >= 14 && code <= 31) || code === 127;
+    });
+}
+function same(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function invalid(message) {
+    throw new LinterToolError(message, { code: 'LINTER_POLICY_INVALID' });
+}

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

@@ -0,0 +1,18 @@
+export { compileRuleCatalog } from './compile.js';
+export { ruleRevision } from './revision.js';
+export type RuleKind = 'architecture' | 'structure' | 'dependency' | 'declaration' | 'dataflow' | 'behavior' | 'evidence';
+export type RuleSeverity = 'error' | 'warning';
+export interface RuleDefinition {
+    readonly id: string;
+    readonly scope: string;
+    readonly kind: RuleKind;
+    readonly severity: RuleSeverity;
+    readonly message: string;
+    readonly verification: string;
+    readonly example: string;
+}
+export interface RuleCatalog {
+    readonly size: number;
+    readonly rules: readonly RuleDefinition[];
+    get(id: string): RuleDefinition | undefined;
+}

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

@@ -0,0 +1,2 @@
+export { compileRuleCatalog } from './compile.js';
+export { ruleRevision } from './revision.js';

package/dist/tooling/linter/catalog/revision.d.ts

@@ -0,0 +1,6 @@
+import type { RuleDefinition } from './index.js';
+/**
+ * Revision the governed evaluation meaning. Presentation policy remains in the
+ * complete policy digest and does not unnecessarily stale a compatible verifier.
+ */
+export declare function ruleRevision(definition: RuleDefinition): string;

package/dist/tooling/linter/catalog/revision.js

@@ -0,0 +1,12 @@
+import { createHash } from 'node:crypto';
+const REVISION_DOMAIN = 'astrale-domain-rule-evaluation-revision:v1\n';
+/**
+ * Revision the governed evaluation meaning. Presentation policy remains in the
+ * complete policy digest and does not unnecessarily stale a compatible verifier.
+ */
+export function ruleRevision(definition) {
+    return createHash('sha256')
+        .update(REVISION_DOMAIN)
+        .update([definition.id, definition.scope, definition.kind, definition.verification].join('\0'), 'utf8')
+        .digest('hex');
+}

package/dist/tooling/linter/diagnostics/error.d.ts

@@ -0,0 +1,9 @@
+import type { LinterToolErrorCode } from './index.js';
+export declare class LinterToolError extends Error {
+    readonly exitCode: 2;
+    readonly code: LinterToolErrorCode;
+    constructor(message: string, options: {
+        readonly code: LinterToolErrorCode;
+        readonly cause?: unknown;
+    });
+}

package/dist/tooling/linter/diagnostics/error.js

@@ -0,0 +1,9 @@
+export class LinterToolError extends Error {
+    exitCode = 2;
+    code;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'LinterToolError';
+        this.code = options.code;
+    }
+}

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

@@ -0,0 +1,28 @@
+import type { RuleKind } from '../catalog/index.js';
+export { LinterToolError } from './error.js';
+export { sortDiagnostics } from './sort.js';
+export type DiagnosticKind = 'violation' | 'ambiguity';
+export type DiagnosticSeverity = 'error' | 'warning' | 'notice';
+export type DiagnosticSource = 'domain-rule' | 'linter' | 'oxlint';
+export type DiagnosticAnalysisKind = RuleKind | 'generic';
+export type AmbiguityReason = 'analysis-limit' | 'dynamic-value' | 'external-evidence' | 'insufficient-evidence' | 'unresolved-import' | 'unresolved-symbol' | 'unsupported-syntax';
+export interface DiagnosticLocation {
+    readonly path: string;
+    readonly line: number;
+    readonly column: number;
+    readonly offset?: number;
+    readonly length?: number;
+}
+export interface LintDiagnostic {
+    readonly id: string;
+    readonly source: DiagnosticSource;
+    readonly scope: string;
+    readonly analysis: DiagnosticAnalysisKind;
+    readonly kind: DiagnosticKind;
+    readonly ambiguityReason?: AmbiguityReason;
+    readonly severity: DiagnosticSeverity;
+    readonly message: string;
+    readonly evidence?: string;
+    readonly location?: DiagnosticLocation;
+}
+export type LinterToolErrorCode = 'LINTER_CANCELLED' | 'LINTER_POLICY_INVALID' | 'LINTER_RULE_COVERAGE' | 'LINTER_RULE_FAILED' | 'LINTER_PROJECT_INVALID' | 'LINTER_PREFLIGHT_FAILED' | 'LINTER_SEMANTIC_FAILED' | 'OXLINT_CANCELLED' | 'OXLINT_FAILED' | 'OXLINT_INVALID_OUTPUT' | 'OXLINT_NOT_INSTALLED' | 'OXLINT_OUTPUT_LIMIT' | 'OXLINT_START_FAILED' | 'OXLINT_TIMEOUT';

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

@@ -0,0 +1,2 @@
+export { LinterToolError } from './error.js';
+export { sortDiagnostics } from './sort.js';

package/dist/tooling/linter/diagnostics/sort.d.ts

@@ -0,0 +1,2 @@
+import type { LintDiagnostic } from './index.js';
+export declare function sortDiagnostics(input: readonly LintDiagnostic[]): LintDiagnostic[];

package/dist/tooling/linter/diagnostics/sort.js

@@ -0,0 +1,26 @@
+export function sortDiagnostics(input) {
+    const unique = new Map();
+    for (const diagnostic of input) {
+        const location = diagnostic.location;
+        const key = [
+            diagnostic.source,
+            diagnostic.id,
+            diagnostic.kind,
+            location?.path ?? '',
+            location?.line ?? 0,
+            location?.column ?? 0,
+            diagnostic.evidence ?? '',
+        ].join('\0');
+        unique.set(key, diagnostic);
+    }
+    return [...unique.values()].sort((left, right) => {
+        const leftLocation = left.location;
+        const rightLocation = right.location;
+        return ((leftLocation?.path ?? '').localeCompare(rightLocation?.path ?? '') ||
+            (leftLocation?.line ?? 0) - (rightLocation?.line ?? 0) ||
+            (leftLocation?.column ?? 0) - (rightLocation?.column ?? 0) ||
+            left.id.localeCompare(right.id) ||
+            left.kind.localeCompare(right.kind) ||
+            (left.evidence ?? '').localeCompare(right.evidence ?? ''));
+    });
+}

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

@@ -0,0 +1,4 @@
+import type { RuleCatalog } from '../../catalog/index.js';
+import type { DomainRulePack } from '../../packs/index.js';
+import type { EvaluationBinding, RuleImplementationPlan } from '../contract/index.js';
+export declare function bindEvaluation<TInput>(catalog: RuleCatalog, pack: DomainRulePack, plan: RuleImplementationPlan<TInput>): EvaluationBinding<TInput>;