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

package/dist/tooling/packaging/declarations/transform.js

@@ -0,0 +1,78 @@
+import ts from 'typescript';
+import { admitDeclarationFacade } from './admission.js';
+/** Locate only TypeScript declaration module specifiers; returned edits preserve all other bytes. */
+export function declarationEdits(file, source, resolveFacade = declarationFacade) {
+    const document = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const edits = [];
+    visit(document);
+    return Object.freeze(edits);
+    function visit(node) {
+        if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+            append(node.moduleSpecifier);
+        }
+        else if (ts.isExportDeclaration(node) &&
+            node.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(node.moduleSpecifier)) {
+            append(node.moduleSpecifier);
+        }
+        else if (ts.isImportTypeNode(node) &&
+            ts.isLiteralTypeNode(node.argument) &&
+            ts.isStringLiteral(node.argument.literal)) {
+            append(node.argument.literal);
+        }
+        ts.forEachChild(node, visit);
+    }
+    function append(literal) {
+        if (!literal.text.startsWith(KERNEL_PREFIX))
+            return;
+        const symbols = importedSymbols(literal);
+        const replacement = resolveFacade(literal.text, symbols);
+        if (replacement === undefined || replacement === literal.text)
+            return;
+        const start = literal.getStart(document) + 1;
+        const end = literal.getEnd() - 1;
+        edits.push(Object.freeze({
+            start,
+            end,
+            replacement,
+        }));
+    }
+}
+function importedSymbols(literal) {
+    const owner = literal.parent;
+    if (ts.isImportDeclaration(owner)) {
+        const clause = owner.importClause;
+        if (!clause ||
+            clause.name ||
+            !clause.namedBindings ||
+            ts.isNamespaceImport(clause.namedBindings)) {
+            throw new TypeError(`Kernel declaration imports must use explicit named symbols: ${literal.text}.`);
+        }
+        return clause.namedBindings.elements.map((element) => (element.propertyName ?? element.name).text);
+    }
+    if (ts.isExportDeclaration(owner)) {
+        if (!owner.exportClause || ts.isNamespaceExport(owner.exportClause)) {
+            throw new TypeError(`Kernel declaration exports must use explicit named symbols: ${literal.text}.`);
+        }
+        return owner.exportClause.elements.map((element) => (element.propertyName ?? element.name).text);
+    }
+    if (ts.isLiteralTypeNode(owner) && ts.isImportTypeNode(owner.parent)) {
+        const qualifier = owner.parent.qualifier;
+        if (!qualifier) {
+            throw new TypeError(`Kernel declaration import types must select an explicit symbol: ${literal.text}.`);
+        }
+        let selected = qualifier;
+        while (ts.isQualifiedName(selected))
+            selected = selected.left;
+        return [selected.text];
+    }
+    throw new TypeError(`Unsupported Kernel declaration reference: ${literal.text}.`);
+}
+const KERNEL_PREFIX = '@astrale-os/kernel-';
+/** Canonical SDK facade for one Kernel module emitted into a Domain declaration. */
+export function declarationFacade(specifier, symbols) {
+    if (specifier.startsWith(KERNEL_PREFIX)) {
+        return admitDeclarationFacade({ source: specifier, symbols });
+    }
+    return undefined;
+}

package/dist/tooling/packaging/declarations/verify.d.ts

@@ -0,0 +1,11 @@
+export interface DeclarationPackageInput {
+    readonly root: string;
+    readonly packageRoot: string;
+    readonly entrypoints?: readonly string[];
+}
+export interface DeclarationPackageResult {
+    readonly files: readonly string[];
+    readonly packages: readonly string[];
+}
+/** Verify the complete public declaration graph against one published package manifest. */
+export declare function verifyDeclarationPackage(input: DeclarationPackageInput): Promise<DeclarationPackageResult>;

package/dist/tooling/packaging/declarations/verify.js

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { reachableDeclarations } from './normalize.js';
+import { declarationReferences } from './references.js';
+/** Verify the complete public declaration graph against one published package manifest. */
+export async function verifyDeclarationPackage(input) {
+    const manifest = JSON.parse(readFileSync(resolve(input.packageRoot, 'package.json'), 'utf8'));
+    const files = reachableDeclarations(resolve(input.root), input.entrypoints, manifest.publishConfig?.imports ?? manifest.imports);
+    const packages = new Set();
+    for (const file of files) {
+        for (const reference of declarationReferences(file, readFileSync(file, 'utf8'))) {
+            const specifier = reference.specifier;
+            if (reference.kind !== 'path' &&
+                !specifier.startsWith('.') &&
+                !specifier.startsWith('#') &&
+                !specifier.startsWith('node:')) {
+                packages.add(packageName(specifier));
+            }
+        }
+    }
+    const declared = new Set([
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.peerDependencies ?? {}),
+    ]);
+    const missing = [...packages].filter((name) => !declared.has(name)).sort();
+    if (missing.length > 0) {
+        throw new TypeError(`Published declarations reference undeclared packages: ${missing.join(', ')}.`);
+    }
+    return Object.freeze({
+        files: Object.freeze(files),
+        packages: Object.freeze([...packages].sort()),
+    });
+}
+function packageName(specifier) {
+    const parts = specifier.split('/');
+    return specifier.startsWith('@') ? `${parts[0]}/${parts[1]}` : parts[0];
+}

package/dist/tooling/packaging/exports.d.ts

@@ -0,0 +1,11 @@
+interface PackageManifest {
+    readonly main?: string;
+    readonly exports?: unknown;
+    readonly publishConfig?: {
+        readonly main?: string;
+        readonly exports?: unknown;
+    };
+}
+/** Verify that every JavaScript target exposed by the published manifest was emitted. */
+export declare function verifyPublishedJavaScript(projectDir: string, manifest: PackageManifest): void;
+export {};

package/dist/tooling/packaging/exports.js

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+/** Verify that every JavaScript target exposed by the published manifest was emitted. */
+export function verifyPublishedJavaScript(projectDir, manifest) {
+    const project = resolve(projectDir);
+    const targets = new Set();
+    collectRuntimeTarget(manifest.publishConfig?.main ?? manifest.main, targets, false);
+    collectExports(manifest.publishConfig?.exports ?? manifest.exports, targets);
+    if (targets.size === 0) {
+        throw new TypeError('Published Domain package declares no JavaScript runtime export.');
+    }
+    for (const target of [...targets].sort()) {
+        if (!target.startsWith('./dist/') || !/\.(?:c|m)?js$/u.test(target)) {
+            throw new TypeError(`Published runtime export must target emitted JavaScript under ./dist: ${target}.`);
+        }
+        const file = resolve(project, target);
+        const path = relative(project, file);
+        if (path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+            throw new TypeError(`Published JavaScript export target escapes the package: ${target}.`);
+        }
+        if (!existsSync(file)) {
+            throw new TypeError(`Published JavaScript export target is absent: ${target}.`);
+        }
+    }
+}
+function collectRuntimeTarget(value, targets, types) {
+    if (typeof value === 'string') {
+        if (!types)
+            targets.add(value);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const nested of value)
+            collectRuntimeTarget(nested, targets, types);
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    for (const [condition, nested] of Object.entries(value)) {
+        collectRuntimeTarget(nested, targets, types || condition === 'types');
+    }
+}
+function collectExports(value, targets) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        collectRuntimeTarget(value, targets, false);
+        return;
+    }
+    const entries = Object.entries(value);
+    const subpaths = entries.filter(([key]) => key.startsWith('.'));
+    if (subpaths.length === 0) {
+        collectRuntimeTarget(value, targets, false);
+        return;
+    }
+    if (subpaths.length !== entries.length) {
+        throw new TypeError('Published exports cannot mix package subpaths and runtime conditions.');
+    }
+    for (const [subpath, target] of subpaths) {
+        if (subpath !== './package.json')
+            collectRuntimeTarget(target, targets, false);
+    }
+}

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

@@ -0,0 +1,2 @@
+export type { PackageDomainInput, PackageDomainResult } from './packaging.js';
+export { packageDomain } from './packaging.js';

package/dist/tooling/packaging/index.js

@@ -0,0 +1 @@
+export { packageDomain } from './packaging.js';

package/dist/tooling/packaging/packaging.d.ts

@@ -0,0 +1,10 @@
+export interface PackageDomainInput {
+    readonly projectDir: string;
+}
+export interface PackageDomainResult {
+    readonly declarations: number;
+    readonly replacements: number;
+    readonly packages: readonly string[];
+}
+/** Compile, normalize, and verify one publishable Domain runtime package. */
+export declare function packageDomain(input: PackageDomainInput): Promise<PackageDomainResult>;

package/dist/tooling/packaging/packaging.js

@@ -0,0 +1,92 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { admitDomainPackage } from './admission.js';
+import { compileDomainPackage } from './compile.js';
+import { normalizeDeclarations, verifyDeclarationPackage } from './declarations/index.js';
+import { verifyPublishedJavaScript } from './exports.js';
+import { verifyRuntimeFacades, writeRuntimeDeclaration } from './runtime.js';
+/** Compile, normalize, and verify one publishable Domain runtime package. */
+export async function packageDomain(input) {
+    const projectDir = resolve(input.projectDir);
+    const manifest = JSON.parse(await readFile(resolve(projectDir, 'package.json'), 'utf8'));
+    admitDomainPackage(projectDir, manifest);
+    const publishedEntrypoints = declarationEntrypoints(manifest);
+    const publishedRuntime = runtimeDeclarationEntrypoint(manifest);
+    const { root } = compileDomainPackage(projectDir, {
+        declarations: publishedEntrypoints.filter((entrypoint) => entrypoint !== publishedRuntime),
+    });
+    const output = relativeOutputRoot(projectDir, root);
+    const entrypoints = publishedEntrypoints.map((entrypoint) => relativeOutput(entrypoint, output));
+    const runtimeEntrypoint = publishedRuntime === undefined ? undefined : relativeOutput(publishedRuntime, output);
+    if (runtimeEntrypoint !== undefined)
+        writeRuntimeDeclaration(root, runtimeEntrypoint);
+    verifyPublishedJavaScript(projectDir, manifest);
+    const normalized = await normalizeDeclarations({
+        root,
+        imports: manifest.publishConfig?.imports ?? manifest.imports,
+        entrypoints,
+    });
+    verifyRuntimeFacades(root);
+    const verified = await verifyDeclarationPackage({ root, packageRoot: projectDir, entrypoints });
+    return Object.freeze({
+        declarations: verified.files.length,
+        replacements: normalized.replacements,
+        packages: verified.packages,
+    });
+}
+function relativeOutputRoot(project, output) {
+    return output.slice(project.length + 1).replaceAll('\\', '/');
+}
+function declarationEntrypoints(manifest) {
+    const values = new Set();
+    const collect = (value, types = false) => {
+        if (typeof value === 'string') {
+            if (types || /\.d\.(?:ts|mts|cts)$/u.test(value))
+                values.add(normalizePath(value));
+            return;
+        }
+        if (!value || typeof value !== 'object')
+            return;
+        for (const [condition, nested] of Object.entries(value))
+            collect(nested, condition === 'types');
+    };
+    const published = manifest.publishConfig;
+    collect(published?.types ?? manifest.types, true);
+    collect(published?.exports ?? manifest.exports);
+    if (values.size === 0)
+        throw new TypeError('Published Domain package declares no TypeScript entrypoint.');
+    return Object.freeze([...values].sort());
+}
+function runtimeDeclarationEntrypoint(manifest) {
+    const exports = manifest.publishConfig?.exports ?? manifest.exports;
+    if (exports === null || typeof exports !== 'object' || Array.isArray(exports))
+        return undefined;
+    const runtime = exports['./runtime'];
+    if (runtime === undefined)
+        return undefined;
+    const values = [];
+    const collect = (value, types = false) => {
+        if (typeof value === 'string') {
+            if (types || /\.d\.(?:ts|mts|cts)$/u.test(value))
+                values.push(normalizePath(value));
+            return;
+        }
+        if (value === null || typeof value !== 'object')
+            return;
+        for (const [condition, nested] of Object.entries(value))
+            collect(nested, condition === 'types');
+    };
+    collect(runtime);
+    if (values.length !== 1) {
+        throw new TypeError('Published Domain ./runtime must declare exactly one TypeScript entrypoint.');
+    }
+    return values[0];
+}
+function normalizePath(file) {
+    return file.replace(/^\.\//u, '').replaceAll('\\', '/');
+}
+function relativeOutput(file, output) {
+    const normalized = file.replace(/^\.\//u, '');
+    const prefix = `${output.replace(/^\.\//u, '').replace(/\/$/u, '')}/`;
+    return normalized.startsWith(prefix) ? normalized.slice(prefix.length) : normalized;
+}

package/dist/tooling/packaging/runtime.d.ts

@@ -0,0 +1,4 @@
+/** Reject direct Kernel runtime imports from a packaged product Domain. */
+export declare function verifyRuntimeFacades(root: string): void;
+/** Publish only the admitted Runtime identity; handlers and providers remain package-private. */
+export declare function writeRuntimeDeclaration(root: string, entrypoint: string): void;

package/dist/tooling/packaging/runtime.js

@@ -0,0 +1,57 @@
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import ts from 'typescript';
+/** Reject direct Kernel runtime imports from a packaged product Domain. */
+export function verifyRuntimeFacades(root) {
+    for (const file of runtimeFiles(root)) {
+        const source = readFileSync(file, 'utf8');
+        const document = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+        visit(document);
+        function visit(node) {
+            const specifier = moduleSpecifier(node);
+            if (specifier?.startsWith('@astrale-os/kernel-')) {
+                throw new TypeError(`Domain runtime imports a Kernel package directly: ${specifier} in ${file}.`);
+            }
+            ts.forEachChild(node, visit);
+        }
+    }
+}
+/** Publish only the admitted Runtime identity; handlers and providers remain package-private. */
+export function writeRuntimeDeclaration(root, entrypoint) {
+    const file = resolve(root, entrypoint);
+    const path = relative(resolve(root), file);
+    if (path === '' || path === '..' || path.startsWith(`..${sep}`) || isAbsolute(path)) {
+        throw new TypeError('Runtime declaration entrypoint escapes package output.');
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, "import type { Runtime } from '@astrale-os/sdk/runtime'\n\ndeclare const runtime: Runtime\nexport default runtime\n");
+}
+function runtimeFiles(root) {
+    const files = [];
+    const visit = (directory) => {
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            const path = join(directory, entry.name);
+            if (entry.isDirectory())
+                visit(path);
+            else if (/\.(?:js|mjs|cjs)$/u.test(entry.name))
+                files.push(path);
+        }
+    };
+    visit(root);
+    return files.sort();
+}
+function moduleSpecifier(node) {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+        node.moduleSpecifier &&
+        ts.isStringLiteral(node.moduleSpecifier)) {
+        return node.moduleSpecifier.text;
+    }
+    if (!ts.isCallExpression(node) || node.arguments.length !== 1)
+        return undefined;
+    const dynamicImport = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+    const requireCall = ts.isIdentifier(node.expression) && node.expression.text === 'require';
+    const argument = node.arguments[0];
+    return (dynamicImport || requireCall) && argument && ts.isStringLiteral(argument)
+        ? argument.text
+        : undefined;
+}