@astrale-os/sdk 0.5.0-beta.138 → 0.5.0-beta.139

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

@@ -1,6 +1,7 @@
-import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { existsSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { admitPackageImports, resolvePackageImport } from './imports.js';
+import { confined, resolveImportTarget, resolveLocal, runtimeSpecifier } from './paths.js';
 import { declarationReferences } from './references.js';
 import { declarationEdits, declarationFacade } from './transform.js';
 /** Normalize emitted declarations without re-emitting or re-typechecking their source program. */
@@ -87,42 +88,6 @@ export function reachableDeclarations(root, requested, imports = {}) {
     }
     return [...seen].sort();
 }
-function resolveImportTarget(root, target) {
-    return resolveLocal(join(root, 'entry.d.ts'), `./${target.slice('./dist/'.length)}`);
-}
-function resolveLocal(containing, specifier) {
-    const base = resolve(dirname(containing), specifier);
-    const candidates = [
-        base.endsWith('.mjs') ? base.replace(/\.mjs$/u, '.d.mts') : '',
-        base.endsWith('.cjs') ? base.replace(/\.cjs$/u, '.d.cts') : '',
-        base.endsWith('.js') ? base.replace(/\.js$/u, '.d.ts') : '',
-        /\.d\.(?:ts|mts|cts)$/u.test(base) ? base : '',
-        `${base}.d.ts`,
-        join(base, 'index.d.ts'),
-    ];
-    const file = candidates.find((candidate) => candidate && existsSync(candidate));
-    if (!file)
-        throw new TypeError(`Cannot resolve declaration reference ${specifier} from ${containing}.`);
-    return file;
-}
-/** Point a local declaration reference at the emitted ESM module that owns it. */
-function runtimeSpecifier(containing, declaration) {
-    const runtime = declaration
-        .replace(/\.d\.mts$/u, '.mjs')
-        .replace(/\.d\.cts$/u, '.cjs')
-        .replace(/\.d\.ts$/u, '.js');
-    const path = relative(dirname(containing), runtime).replaceAll('\\', '/');
-    return path.startsWith('./') || path.startsWith('../') ? path : `./${path}`;
-}
-function confined(root, file) {
-    const path = relative(realpathSync(root), realpathSync(file));
-    if (path === '..' ||
-        path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
-        isAbsolute(path)) {
-        throw new TypeError(`Declaration reference escapes package root: ${file}.`);
-    }
-    return file;
-}
 function apply(source, edits) {
     let result = source;
     for (const edit of [...edits].sort((left, right) => right.start - left.start)) {

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

@@ -0,0 +1,5 @@
+export declare function resolveImportTarget(root: string, target: string): string;
+export declare function resolveLocal(containing: string, specifier: string): string;
+/** Point a local declaration reference at the emitted ESM module that owns it. */
+export declare function runtimeSpecifier(containing: string, declaration: string): string;
+export declare function confined(root: string, file: string): string;

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

@@ -0,0 +1,38 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+export function resolveImportTarget(root, target) {
+    return resolveLocal(join(root, 'entry.d.ts'), `./${target.slice('./dist/'.length)}`);
+}
+export function resolveLocal(containing, specifier) {
+    const base = resolve(dirname(containing), specifier);
+    const candidates = [
+        base.endsWith('.mjs') ? base.replace(/\.mjs$/u, '.d.mts') : '',
+        base.endsWith('.cjs') ? base.replace(/\.cjs$/u, '.d.cts') : '',
+        base.endsWith('.js') ? base.replace(/\.js$/u, '.d.ts') : '',
+        /\.d\.(?:ts|mts|cts)$/u.test(base) ? base : '',
+        `${base}.d.ts`,
+        join(base, 'index.d.ts'),
+    ];
+    const file = candidates.find((candidate) => candidate && existsSync(candidate));
+    if (!file)
+        throw new TypeError(`Cannot resolve declaration reference ${specifier} from ${containing}.`);
+    return file;
+}
+/** Point a local declaration reference at the emitted ESM module that owns it. */
+export function runtimeSpecifier(containing, declaration) {
+    const runtime = declaration
+        .replace(/\.d\.mts$/u, '.mjs')
+        .replace(/\.d\.cts$/u, '.cjs')
+        .replace(/\.d\.ts$/u, '.js');
+    const path = relative(dirname(containing), runtime).replaceAll('\\', '/');
+    return path.startsWith('./') || path.startsWith('../') ? path : `./${path}`;
+}
+export function confined(root, file) {
+    const path = relative(realpathSync(root), realpathSync(file));
+    if (path === '..' ||
+        path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) ||
+        isAbsolute(path)) {
+        throw new TypeError(`Declaration reference escapes package root: ${file}.`);
+    }
+    return file;
+}

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

@@ -0,0 +1,13 @@
+import type { PackageImports } from './declarations/imports.js';
+export interface FinalizeDomainPackageInput {
+    readonly projectDir: string;
+    /** Additional emitted type-closure mappings supplied by the SDK compiler. */
+    readonly imports?: PackageImports;
+}
+export interface FinalizeDomainPackageResult {
+    readonly declarations: number;
+    readonly replacements: number;
+    readonly packages: readonly string[];
+}
+/** Finalize already-compiled Schema, Runtime, and Application exports through one SDK boundary. */
+export declare function finalizeDomainPackage(input: FinalizeDomainPackageInput): Promise<FinalizeDomainPackageResult>;

package/dist/tooling/packaging/finalize.js

@@ -0,0 +1,62 @@
+import { readFileSync, rmSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { normalizeDeclarations, verifyDeclarationPackage } from './declarations/index.js';
+import { verifyPublishedJavaScript } from './exports.js';
+import { normalizeJavaScript, verifyContractJavaScript } from './javascript.js';
+import { admitSelfPackage } from './self.js';
+/** Finalize already-compiled Schema, Runtime, and Application exports through one SDK boundary. */
+export async function finalizeDomainPackage(input) {
+    const projectDir = resolve(input.projectDir);
+    const root = resolve(projectDir, 'dist');
+    try {
+        const manifest = JSON.parse(readFileSync(resolve(projectDir, 'package.json'), 'utf8'));
+        const published = manifest.publishConfig ?? manifest;
+        const exports = published.exports ?? manifest.exports ?? {};
+        const targets = new Set();
+        const collect = (value, types = false) => {
+            if (typeof value === 'string') {
+                if (types)
+                    targets.add(value);
+            }
+            else if (value !== null && typeof value === 'object') {
+                for (const [condition, nested] of Object.entries(value))
+                    collect(nested, types || condition === 'types');
+            }
+        };
+        collect(published.types, true);
+        collect(exports);
+        if (targets.size === 0)
+            throw new TypeError('Published Domain package declares no type export.');
+        const entrypoints = [...targets].sort().map((target) => {
+            if (!target.startsWith('./dist/') || !/\.d\.(?:ts|mts|cts)$/u.test(target)) {
+                throw new TypeError(`Published Domain type export must target a declaration under ./dist: ${target}.`);
+            }
+            return target.slice('./dist/'.length);
+        });
+        const imports = { ...manifest.publishConfig?.imports, ...input.imports };
+        const self = admitSelfPackage(manifest.name, Object.keys(exports).filter((key) => key !== './package.json'));
+        verifyPublishedJavaScript(projectDir, manifest);
+        const javascriptReplacements = normalizeJavaScript(root, imports);
+        const javascriptPackages = verifyContractJavaScript(root, self);
+        const normalized = await normalizeDeclarations({ root, entrypoints, imports });
+        const verified = await verifyDeclarationPackage({ root, packageRoot: projectDir, entrypoints });
+        const packages = [...new Set([...javascriptPackages, ...verified.packages])].sort();
+        const declared = new Set([
+            ...Object.keys(manifest.dependencies ?? {}),
+            ...Object.keys(manifest.optionalDependencies ?? {}),
+            ...Object.keys(manifest.peerDependencies ?? {}),
+        ]);
+        const missing = packages.filter((name) => !declared.has(name));
+        if (missing.length > 0)
+            throw new TypeError(`Published Domain contract references undeclared packages: ${missing.join(', ')}.`);
+        return Object.freeze({
+            declarations: verified.files.length,
+            replacements: javascriptReplacements + normalized.replacements,
+            packages: Object.freeze(packages),
+        });
+    }
+    catch (cause) {
+        rmSync(root, { recursive: true, force: true });
+        throw cause;
+    }
+}

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

@@ -1,2 +1,4 @@
 export type { PackageDomainInput, PackageDomainResult } from './packaging.js';
 export { packageDomain } from './packaging.js';
+export type { FinalizeDomainPackageInput, FinalizeDomainPackageResult } from './finalize.js';
+export { finalizeDomainPackage } from './finalize.js';

package/dist/tooling/packaging/index.js

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

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

@@ -1,3 +1,6 @@
+import { type PackageImports } from './declarations/imports.js';
 import { type SelfPackage } from './self.js';
 /** Verify emitted Schema JavaScript and return its complete external package set. */
 export declare function verifyContractJavaScript(root: string, self?: SelfPackage): readonly string[];
+/** Normalize local runtime imports with the same package mappings as declarations. */
+export declare function normalizeJavaScript(root: string, imports: PackageImports): number;

package/dist/tooling/packaging/javascript.js

@@ -1,6 +1,8 @@
-import { readFileSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { extname, join } from 'node:path';
 import ts from 'typescript';
+import { admitPackageImports, resolvePackageImport, } from './declarations/imports.js';
+import { confined, resolveImportTarget, resolveLocal, runtimeSpecifier, } from './declarations/paths.js';
 import { isSelfPackageReference, packageName } from './self.js';
 /** Verify emitted Schema JavaScript and return its complete external package set. */
 export function verifyContractJavaScript(root, self) {
@@ -69,3 +71,44 @@ function moduleSpecifier(node) {
         ? argument.text
         : undefined;
 }
+/** Normalize local runtime imports with the same package mappings as declarations. */
+export function normalizeJavaScript(root, imports) {
+    const mappings = admitPackageImports(imports);
+    const output = new Map();
+    let replacements = 0;
+    for (const file of javascriptFiles(root)) {
+        const source = readFileSync(file, 'utf8');
+        const document = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
+        const edits = [];
+        const visit = (node) => {
+            const specifier = moduleSpecifier(node);
+            if (specifier !== undefined &&
+                (specifier.startsWith('#') || (specifier.startsWith('.') && extname(specifier) === ''))) {
+                const target = specifier.startsWith('#')
+                    ? resolveImportTarget(root, resolvePackageImport(specifier, mappings))
+                    : resolveLocal(file, specifier);
+                confined(root, target);
+                const literal = ts.isImportDeclaration(node) || ts.isExportDeclaration(node)
+                    ? node.moduleSpecifier
+                    : node.arguments[0];
+                edits.push({
+                    start: literal.getStart(document) + 1,
+                    end: literal.getEnd() - 1,
+                    replacement: runtimeSpecifier(file, target),
+                });
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(document);
+        let normalized = source;
+        for (const edit of edits.sort((left, right) => right.start - left.start)) {
+            normalized = `${normalized.slice(0, edit.start)}${edit.replacement}${normalized.slice(edit.end)}`;
+        }
+        if (edits.length > 0)
+            output.set(file, normalized);
+        replacements += edits.length;
+    }
+    for (const [file, source] of output)
+        writeFileSync(file, source);
+    return replacements;
+}

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

@@ -1,10 +1,7 @@
+import { type FinalizeDomainPackageResult } from './finalize.js';
 export interface PackageDomainInput {
     readonly projectDir: string;
 }
-export interface PackageDomainResult {
-    readonly declarations: number;
-    readonly replacements: number;
-    readonly packages: readonly string[];
-}
+export type PackageDomainResult = FinalizeDomainPackageResult;
 /** Compile, normalize, and verify every public Schema contract in one Domain package. */
 export declare function packageDomain(input: PackageDomainInput): Promise<PackageDomainResult>;

package/dist/tooling/packaging/packaging.js

@@ -3,10 +3,7 @@ import { rm } from 'node:fs/promises';
 import { posix, 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 { verifyContractJavaScript } from './javascript.js';
-import { admitSelfPackage } from './self.js';
+import { finalizeDomainPackage } from './finalize.js';
 /** Compile, normalize, and verify every public Schema contract in one Domain package. */
 export async function packageDomain(input) {
     const projectDir = resolve(input.projectDir);
@@ -16,29 +13,13 @@ export async function packageDomain(input) {
         const manifest = JSON.parse(await readFile(resolve(projectDir, 'package.json'), 'utf8'));
         admitDomainPackage(projectDir, manifest);
         const contracts = admitContractManifest(manifest);
-        const self = admitSelfPackage(manifest.name, contracts.map(({ subpath }) => subpath));
         const { typeClosure } = compileDomainPackage(projectDir, contracts.map(({ source }) => source));
-        const entrypoints = contracts.map(({ declaration }) => declaration);
-        const declarationEntrypoints = entrypoints;
-        verifyPublishedJavaScript(projectDir, manifest);
-        const javascriptPackages = verifyContractJavaScript(root, self);
-        const normalized = await normalizeDeclarations({
-            root,
+        const result = await finalizeDomainPackage({
+            projectDir,
             imports: declarationImports(manifest, typeClosure),
-            entrypoints: declarationEntrypoints,
-        });
-        const verified = await verifyDeclarationPackage({
-            root,
-            packageRoot: projectDir,
-            entrypoints: declarationEntrypoints,
-        });
-        const packages = Object.freeze([...new Set([...javascriptPackages, ...verified.packages])].sort());
-        verifyDependencies(manifest, packages);
-        return Object.freeze({
-            declarations: verified.files.length,
-            replacements: normalized.replacements,
-            packages,
         });
+        verifyUsedDependencies(manifest, result.packages);
+        return result;
     }
     catch (cause) {
         await rm(root, { recursive: true, force: true });
@@ -98,7 +79,6 @@ function admitContractManifest(manifest) {
         return Object.freeze({
             subpath,
             source: source.types.slice(2),
-            declaration: expected.types.slice('./dist/'.length),
         });
     });
     if (new Set(contracts.map(({ source }) => source)).size !== contracts.length) {
@@ -177,17 +157,13 @@ function publishedTargets(source) {
         import: `./dist/${stem}.js`,
     });
 }
-function verifyDependencies(manifest, packages) {
+function verifyUsedDependencies(manifest, packages) {
     const declared = new Set([
         ...Object.keys(manifest.dependencies ?? {}),
         ...Object.keys(manifest.optionalDependencies ?? {}),
         ...Object.keys(manifest.peerDependencies ?? {}),
     ]);
     const used = new Set(packages);
-    const missing = packages.filter((name) => !declared.has(name));
-    if (missing.length > 0) {
-        throw new TypeError(`Published Domain contract references undeclared packages: ${missing.join(', ')}.`);
-    }
     const unused = [...declared].filter((name) => !used.has(name)).sort();
     if (unused.length > 0) {
         throw new TypeError(`Domain contract declares unused production packages: ${unused.join(', ')}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/sdk",
-  "version": "0.5.0-beta.138",
+  "version": "0.5.0-beta.139",
   "description": "Schema-first SDK for defining, composing, and deploying Astrale domains",
   "keywords": [
     "astrale",