@vmz/vmz 0.3.12 → 0.3.13

package/dist/workspace/pack-native.js

@@ -0,0 +1,273 @@
+/**
+ * TS consumption layer for the Rust `vmz-pack` plan (frozen v0 contract).
+ *
+ * The N-API binding exports two synchronous functions:
+ *   packPlan(requestJson: string): string
+ *   packWrite(requestJson: string, outDir: string): string
+ * Both return the same response JSON shape. The interfaces below are a verbatim
+ * mirror of that contract: no renames, no guessed defaults, no dual-format
+ * tolerance, and diagnostics always propagate explicitly.
+ *
+ * This slice is the integration layer: `pack.ts` runs the delivery path
+ * through `buildPackRequest` / `runPackWrite` against this contract; real-build
+ * evidence closes the switch (see the toolchain plan's delivery-path design).
+ */
+import path from 'node:path';
+import { requireNativeAddon } from './native-addon.js';
+/** Error carrying the full diagnostic set — never swallowed, never summarized away. */
+export class PackNativeError extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = []) {
+        super(`[${code}] ${message}`);
+        this.name = 'PackNativeError';
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requestInvalid(message) {
+    return new PackNativeError('pack.native.request-invalid', message);
+}
+function responseShape(message) {
+    return new PackNativeError('pack.native.response-shape', message);
+}
+function requireString(value, where) {
+    if (typeof value !== 'string')
+        throw responseShape(`${where} must be a string`);
+    return value;
+}
+function requireStringArray(value, where) {
+    if (!Array.isArray(value))
+        throw responseShape(`${where} must be an array of strings`);
+    return value.map((item, i) => requireString(item, `${where}[${i}]`));
+}
+/** Contract mirror: fields outside the frozen shape are rejected, not ignored. */
+function rejectUnknownKeys(obj, allowed, where) {
+    const extra = Object.keys(obj).filter((k) => !allowed.includes(k));
+    if (extra.length)
+        throw responseShape(`${where} has unknown field(s): ${extra.join(', ')}`);
+}
+function parsePackDiagnostic(value, where) {
+    if (!isPlainObject(value))
+        throw responseShape(`${where} must be an object`);
+    rejectUnknownKeys(value, ['code', 'message', 'path', 'span'], where);
+    const out = {
+        code: requireString(value.code, `${where}.code`),
+        message: requireString(value.message, `${where}.message`),
+    };
+    if (value.path !== undefined)
+        out.path = requireString(value.path, `${where}.path`);
+    if (value.span !== undefined) {
+        if (!Array.isArray(value.span) ||
+            value.span.length !== 2 ||
+            !value.span.every((n) => typeof n === 'number' && Number.isFinite(n))) {
+            throw responseShape(`${where}.span must be [number, number]`);
+        }
+        out.span = [value.span[0], value.span[1]];
+    }
+    return out;
+}
+function parseChunkArtifact(value, where) {
+    if (!isPlainObject(value))
+        throw responseShape(`${where} must be an object`);
+    rejectUnknownKeys(value, ['chunkId', 'fileName', 'code', 'modules', 'imports', 'dynamic', 'sourceMapFileName'], where);
+    return {
+        chunkId: requireString(value.chunkId, `${where}.chunkId`),
+        fileName: requireString(value.fileName, `${where}.fileName`),
+        code: requireString(value.code, `${where}.code`),
+        modules: requireStringArray(value.modules, `${where}.modules`),
+        imports: requireStringArray(value.imports, `${where}.imports`),
+        dynamic: requireStringArray(value.dynamic, `${where}.dynamic`),
+        sourceMapFileName: requireString(value.sourceMapFileName, `${where}.sourceMapFileName`),
+    };
+}
+function parseAssetArtifact(value, where) {
+    if (!isPlainObject(value))
+        throw responseShape(`${where} must be an object`);
+    rejectUnknownKeys(value, ['modulePath', 'specifier', 'fileName', 'url', 'sourcePath'], where);
+    return {
+        modulePath: requireString(value.modulePath, `${where}.modulePath`),
+        specifier: requireString(value.specifier, `${where}.specifier`),
+        fileName: requireString(value.fileName, `${where}.fileName`),
+        url: requireString(value.url, `${where}.url`),
+        sourcePath: requireString(value.sourcePath, `${where}.sourcePath`),
+    };
+}
+function parseStyleArtifact(value, where) {
+    if (!isPlainObject(value))
+        throw responseShape(`${where} must be an object`);
+    rejectUnknownKeys(value, ['fileName', 'url', 'modules', 'sourcePaths'], where);
+    return {
+        fileName: requireString(value.fileName, `${where}.fileName`),
+        url: requireString(value.url, `${where}.url`),
+        modules: requireStringArray(value.modules, `${where}.modules`),
+        sourcePaths: requireStringArray(value.sourcePaths, `${where}.sourcePaths`),
+    };
+}
+function parseEntryFile(value, where) {
+    if (!isPlainObject(value))
+        throw responseShape(`${where} must be an object`);
+    rejectUnknownKeys(value, ['logical', 'file'], where);
+    return { logical: requireString(value.logical, `${where}.logical`), file: requireString(value.file, `${where}.file`) };
+}
+function parseDynamicFile(value, where) {
+    if (!isPlainObject(value))
+        throw responseShape(`${where} must be an object`);
+    rejectUnknownKeys(value, ['from', 'to'], where);
+    return { from: requireString(value.from, `${where}.from`), to: requireString(value.to, `${where}.to`) };
+}
+function parsePackPlan(value) {
+    if (!isPlainObject(value))
+        throw responseShape('response.plan must be an object');
+    rejectUnknownKeys(value, ['artifacts', 'styles', 'assets', 'entryFiles', 'dynamicFiles', 'manifestJson'], 'response.plan');
+    if (!Array.isArray(value.artifacts))
+        throw responseShape('response.plan.artifacts must be an array');
+    if (!Array.isArray(value.styles))
+        throw responseShape('response.plan.styles must be an array');
+    if (!Array.isArray(value.assets))
+        throw responseShape('response.plan.assets must be an array');
+    if (!Array.isArray(value.entryFiles))
+        throw responseShape('response.plan.entryFiles must be an array');
+    if (!Array.isArray(value.dynamicFiles))
+        throw responseShape('response.plan.dynamicFiles must be an array');
+    return {
+        artifacts: value.artifacts.map((a, i) => parseChunkArtifact(a, `response.plan.artifacts[${i}]`)),
+        styles: value.styles.map((s, i) => parseStyleArtifact(s, `response.plan.styles[${i}]`)),
+        assets: value.assets.map((a, i) => parseAssetArtifact(a, `response.plan.assets[${i}]`)),
+        entryFiles: value.entryFiles.map((e, i) => parseEntryFile(e, `response.plan.entryFiles[${i}]`)),
+        dynamicFiles: value.dynamicFiles.map((d, i) => parseDynamicFile(d, `response.plan.dynamicFiles[${i}]`)),
+        manifestJson: requireString(value.manifestJson, 'response.plan.manifestJson'),
+    };
+}
+/**
+ * Strictly parse one binding response. `ok:false` never returns — it throws a
+ * `PackNativeError` carrying every diagnostic from the response.
+ */
+function parsePackResponse(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        throw new PackNativeError('pack.native.response-json', `binding returned invalid JSON: ${msg}`);
+    }
+    if (!isPlainObject(parsed))
+        throw responseShape('response must be a JSON object');
+    rejectUnknownKeys(parsed, ['ok', 'plan', 'diagnostics'], 'response');
+    if (typeof parsed.ok !== 'boolean')
+        throw responseShape('response.ok must be a boolean');
+    if (!Array.isArray(parsed.diagnostics))
+        throw responseShape('response.diagnostics must be an array');
+    const diagnostics = parsed.diagnostics.map((d, i) => parsePackDiagnostic(d, `response.diagnostics[${i}]`));
+    if (parsed.ok === false) {
+        if (parsed.plan !== undefined)
+            throw responseShape('response.plan must be absent when ok is false');
+        const summary = diagnostics.length
+            ? diagnostics.map((d) => `${d.code}: ${d.message}`).join(' | ')
+            : 'binding reported failure without diagnostics';
+        throw new PackNativeError('pack.native.plan-failed', summary, diagnostics);
+    }
+    if (parsed.plan === undefined)
+        throw responseShape('response.plan is required when ok is true');
+    return { ok: true, plan: parsePackPlan(parsed.plan), diagnostics };
+}
+/** Assemble the request JSON. Every gap is an explicit error — nothing is guessed. */
+export function buildPackRequest(input) {
+    if (!isPlainObject(input))
+        throw requestInvalid('input must be an object');
+    const logicals = Object.keys(input.entries ?? {});
+    if (!logicals.length)
+        throw requestInvalid('entries must contain at least one logical entry');
+    const entries = logicals.map((logical) => {
+        const entryPath = input.entries[logical];
+        if (typeof entryPath !== 'string' || !entryPath) {
+            throw requestInvalid(`entries["${logical}"] must be a non-empty path string`);
+        }
+        if (!path.isAbsolute(entryPath)) {
+            throw requestInvalid(`entries["${logical}"] must be an absolute path: ${entryPath}`);
+        }
+        return { logical, path: entryPath };
+    });
+    if (input.target !== 'browser' && input.target !== 'node') {
+        throw new PackNativeError('pack.native.request-target', `target must be "browser" or "node", got ${JSON.stringify(input.target)}`);
+    }
+    if (typeof input.root !== 'string' || !input.root)
+        throw requestInvalid('root must be a non-empty string');
+    if (!path.isAbsolute(input.root))
+        throw requestInvalid(`root must be an absolute path: ${input.root}`);
+    if (typeof input.publicBase !== 'string' || !input.publicBase) {
+        throw requestInvalid('publicBase must be a non-empty string');
+    }
+    if (!Array.isArray(input.uses))
+        throw requestInvalid('uses must be an array');
+    const useLogicals = new Set();
+    const uses = [];
+    for (const use of input.uses) {
+        if (!use || typeof use !== 'object' || typeof use.logical !== 'string' || !use.logical) {
+            throw requestInvalid('uses[] items must be { logical, execution, exports } objects');
+        }
+        if (use.execution !== 'full' && use.execution !== 'side-effects') {
+            throw new PackNativeError('pack.native.request-uses', `uses["${use.logical}"].execution must be "full" or "side-effects", got ${JSON.stringify(use.execution)}`);
+        }
+        const exports = use.exports;
+        if (!exports || typeof exports !== 'object' || typeof exports.kind !== 'string') {
+            throw new PackNativeError('pack.native.request-uses', `uses["${use.logical}"].exports must be a tagged object { kind: "all" | "named" | "unconsumed" }`);
+        }
+        if (exports.kind === 'named') {
+            if (!Array.isArray(exports.names) || !exports.names.every((name) => typeof name === 'string' && name)) {
+                throw new PackNativeError('pack.native.request-uses', `uses["${use.logical}"].exports.names must be an array of non-empty export names`);
+            }
+        }
+        else if (exports.kind !== 'all' && exports.kind !== 'unconsumed') {
+            throw new PackNativeError('pack.native.request-uses', `uses["${use.logical}"].exports.kind must be "all", "named" or "unconsumed"`);
+        }
+        if (useLogicals.has(use.logical)) {
+            throw new PackNativeError('pack.native.request-uses', `uses duplicates logical "${use.logical}"`);
+        }
+        useLogicals.add(use.logical);
+        uses.push({ logical: use.logical, execution: use.execution, exports: use.exports });
+    }
+    const missing = logicals.filter((logical) => !useLogicals.has(logical));
+    if (missing.length) {
+        throw new PackNativeError('pack.native.request-uses', `uses must cover every entries[].logical — missing: ${missing.join(', ')}`);
+    }
+    let origins;
+    if (input.origins !== undefined) {
+        if (!isPlainObject(input.origins))
+            throw requestInvalid('origins must be a record of absolute paths');
+        origins = {};
+        for (const [emitted, source] of Object.entries(input.origins)) {
+            if (!path.isAbsolute(emitted) || typeof source !== 'string' || !path.isAbsolute(source)) {
+                throw requestInvalid(`origins must map absolute emitted paths to absolute source paths: ${JSON.stringify(emitted)}`);
+            }
+            origins[emitted] = source;
+        }
+        if (!Object.keys(origins).length)
+            origins = undefined;
+    }
+    const request = { entries, target: input.target, root: input.root, uses, publicBase: input.publicBase, ...(origins ? { origins } : {}) };
+    return JSON.stringify(request);
+}
+function resolveBinding(opts, fn) {
+    const binding = (opts.binding ?? requireNativeAddon());
+    if (typeof binding[fn] !== 'function') {
+        throw new PackNativeError('pack.native.binding-missing', `native binding missing ${fn} — run \`pnpm napi:build\` with a vmz-pack build`);
+    }
+    return binding;
+}
+/** Compute the pack plan via the native binding (synchronous, contract v0). */
+export function runPackPlan(requestJson, opts = {}) {
+    const binding = resolveBinding(opts, 'packPlan');
+    return parsePackResponse(binding.packPlan(requestJson));
+}
+/** Compute the pack plan and write artifacts under `outDir` via the native binding. */
+export function runPackWrite(requestJson, outDir, opts = {}) {
+    if (typeof outDir !== 'string' || !outDir)
+        throw requestInvalid('outDir must be a non-empty string');
+    const binding = resolveBinding(opts, 'packWrite');
+    return parsePackResponse(binding.packWrite(requestJson, outDir));
+}

package/dist/workspace/pack.d.ts

@@ -1,42 +1,67 @@
 /**
- * Pack stage: consume Deployment IR (VPG-owned units), emit pack manifest,
- * and lower browser-unreachable bare package imports to `dist/vendor/**`.
+ * Pack stage: run the browser delivery graph through the Rust `vmz-pack`
+ * binding (N-API `packPlan`/`packWrite`, frozen v0 contract) and record the
+ * resulting chunk/asset mapping in `_vmz/pack-manifest.json`.
  *
- * Current status: a thin module-moving slice — reachable module closure
- * materialization, specifier rewriting, and TypeScript `transpileModule` type
- * erasure. Linking, dead-code elimination, chunk splitting, and minification
- * are NOT implemented in this stage; the manifest reports that honestly.
- * (Any compaction of compile-emitted modules happens upstream in the compiler,
- * not here — pack never rewrites bytes beyond specifier lowering.)
+ * Browser graph roots are the bootstrap modules (`entry-client.js` /
+ * `entry-event.js`) emitted by the compiler / static delivery path; page and
+ * island modules enter the graph through the bootstrap's literal dynamic
+ * import tables, never as pack entries. Bootstrap entries declare
+ * `execution: 'full'` + `exports: { kind: 'all' }` (script-tag load,
+ * whole-module execution).
+ *
+ * SSR/Node is a separate graph: every deployment unit's `clientEntry` is a
+ * Node entry (logical = `chunkId`), packed under `_vmz/pack-node/` and indexed
+ * by `_vmz/pack-node-manifest.json`. Node consumers never fall back to the
+ * unpacked root `${chunkId}.client.js`; browser bootstrap modules are not Node
+ * entries because they bind `dom.browser` / `document`.
+ *
+ * No vendor materialization, no specifier lowering, and no second hashing
+ * pass happen here: `packWrite` emits the final browser JS set under
+ * `_vmz/pack/` with content-hashed names, and consumers resolve logical
+ * entries through `packEntryHref()` against this manifest.
  */
+import type { DeploymentIr } from './bundler-adapter.js';
+import type { PackNativeBinding } from './pack-native.js';
 export declare const PACK_MANIFEST_SCHEMA = "vmz.pack.manifest.v0";
+/** Directory (relative to outDir) where `packWrite` emits the final browser JS set. */
+export declare const PACK_OUTPUT_DIR_REL = "_vmz/pack";
+/** Site root base — VMZ static delivery has no configurable base (see delivery-profile). */
+export declare const PACK_PUBLIC_BASE = "/";
+/**
+ * Projection provenance for the pack graph: each deployment unit's emitted
+ * client entry maps back to its source `.vmz`. Bare-specifier package discovery
+ * then walks up from the source location — dependency components (e.g. a
+ * `@vmz/ui` component importing its own peer) keep their source package's
+ * node_modules visibility, matching Node realpath semantics. Relative
+ * specifiers keep resolving against the emitted tree.
+ */
+export declare function deploymentUnitOrigins(absOut: string, ir: DeploymentIr): Record<string, string>;
 /**
  * Ensure dom split companions sit next to vmz-dom.js (barrel imports ./dom-core.js).
  * Always refresh from `@vmz/core` when present so SSR/runtime fixes are not sticky in outDir.
+ * Document surfaces (Node-side document layout mount) consume this; browser delivery
+ * runtime files reach the pack graph through `@vmz/core` bare imports in the Rust graph.
  * @param {string} outDir
  * @param {string | null | undefined} coreDist `@vmz/core` dist root
  * @returns {string[]} copied relative names
  */
 export declare function ensureRuntimeCompanions(outDir: any, coreDist: any): any[];
-/**
- * @param {string} outDir
- * @param {{
- *   release?: boolean,
- *   profileId?: string,
- *   assembly?: string,
- *   preferredClientFace?: string,
- *   coreDist?: string | null,
- *   projectRoot?: string | null,
- * }} [opts]
- */
 interface PackFromDeploymentIrOpts {
     release?: boolean;
     profileId?: string;
     assembly?: string;
     preferredClientFace?: string;
-    coreDist?: string | null;
     projectRoot?: string | null;
+    /** Test seam: inject a fake binding. Defaults to the loaded N-API addon. */
+    binding?: PackNativeBinding;
 }
+/**
+ * Pack the browser delivery graph via the Rust `vmz-pack` binding and write
+ * `_vmz/pack-manifest.json` (v0). Entries are the bootstrap modules that
+ * already exist in `outDir` — an empty bootstrap set is an explicit request
+ * error, never a silently skipped stage.
+ */
 export declare function packFromDeploymentIr(outDir: string, opts?: PackFromDeploymentIrOpts): {
     manifest: {
         schema: string;
@@ -45,22 +70,77 @@ export declare function packFromDeploymentIr(outDir: string, opts?: PackFromDepl
         release: boolean;
         preferredClientFace: string;
         deploymentSchema: unknown;
-        unitCount: number;
-        units: unknown[];
+        target: "browser";
+        publicBase: string;
+        entries: Array<{
+            logical: string;
+            file: string;
+        }>;
+        entryFiles: unknown[];
+        dynamicFiles: unknown[];
+        styles: unknown[];
+        assets: unknown[];
+        chunks: unknown[];
+        chunkCount: number;
+        styleCount: number;
+        entryCount: number;
         minify: string;
-        treeShakeBasis: string;
-        bundler: string;
-        clientPackageLowering: Record<string, unknown>;
+        treeShake: string;
+        sourceMaps: string;
+        nativeManifest: unknown;
         packDigest?: string;
     };
     path: string;
-    clientPackages: {
-        rewrittenFiles: number;
-        vendoredModules: string[];
-        bareSpecs: any[];
-        unresolvedBareSpecs: any[];
-        skippedVmzExports: any[];
-        remainingBareSpecs: any[];
+};
+export declare const PACK_NODE_MANIFEST_SCHEMA = "vmz.pack.node-manifest.v0";
+/** Directory (relative to outDir) where `packWrite` emits the Node JS set. */
+export declare const PACK_NODE_OUTPUT_DIR_REL = "_vmz/pack-node";
+/** Node pack manifest (relative to outDir); `entryFiles` maps logical → chunk file. */
+export declare const PACK_NODE_MANIFEST_REL = "_vmz/pack-node-manifest.json";
+interface PackSsrFromDeploymentIrOpts {
+    projectRoot?: string | null;
+    /** Test seam: inject a fake binding. Defaults to the loaded N-API addon. */
+    binding?: PackNativeBinding;
+}
+/**
+ * Pack the SSR/Node graph via the Rust `vmz-pack` binding and write
+ * `_vmz/pack-node-manifest.json` (v0). Entries are the deployment units'
+ * compiled client modules (`clientEntry`, empty → mirrors `vmz-artifacts`
+ * `component_entries`: `${chunkId}.client.js`). Node consumers only read
+ * `default`, but the import itself is evaluated, hence `side-effects` +
+ * named default rather than `all` / `full` / `unconsumed`.
+ */
+export declare function packSsrFromDeploymentIr(outDir: string, opts?: PackSsrFromDeploymentIrOpts): {
+    manifest: {
+        schema: string;
+        target: "node";
+        deploymentSchema: unknown;
+        entries: Array<{
+            logical: string;
+            file: string;
+        }>;
+        entryFiles: unknown[];
+        dynamicFiles: unknown[];
+        chunks: unknown[];
+        chunkCount: number;
+        entryCount: number;
+        nativeManifest: unknown;
+        packDigest?: string;
     };
+    path: string;
 };
+/**
+ * Resolve a Node logical entry (`chunkId`) to its packed absolute file from
+ * `_vmz/pack-node-manifest.json`. Missing manifest, missing logical, or a
+ * missing chunk file is an explicit error — never a fallback to the unpacked
+ * root `${chunkId}.client.js`.
+ */
+export declare function packNodeEntryFile(outDir: string, chunkId: string): string;
+/**
+ * Resolve the final browser URL of a packed logical entry from
+ * `_vmz/pack-manifest.json` (`entryFiles` is the only logical→physical map).
+ * Missing manifest or missing logical entry is an explicit error — no
+ * fallback to unpacked root bytes.
+ */
+export declare function packEntryHref(outDir: string, logical: string): string;
 export {};