@spine-event-engine/proto-tools 2.0.0-snapshot.2

package/dist/src/generation/source-view.js

@@ -0,0 +1,298 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { createHash } from "node:crypto";
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, realpathSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import ts from "typescript";
+const maximumSourceViewDepth = 32;
+const maximumSourceViewEntries = 10_000;
+const recordFileName = ".spine-source-view-publication.json";
+const recordFormat = 1;
+const maximumRecordBytes = 16 * 1024;
+const nonRegularInputDiagnostic = "spine-proto: source view contains non-regular TypeScript input";
+/**
+ * Race-safe reads for files owned by a compiler source view.
+ */
+export const SourceViewInputs = Object.freeze({
+    // prettier-ignore
+    /**
+     * Opens without following the final symlink or waiting on a special file,
+     * validates the opened descriptor, and reads that immutable file identity.
+     *
+     * @param path Source or configuration path.
+     * @returns Exact file bytes.
+     */
+    read(path) {
+        let descriptor;
+        try {
+            descriptor = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+            if (!fstatSync(descriptor).isFile())
+                throw new Error(nonRegularInputDiagnostic);
+            return readFileSync(descriptor);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === nonRegularInputDiagnostic)
+                throw error;
+            throw new Error(nonRegularInputDiagnostic, { cause: error });
+        }
+        finally {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+        }
+    },
+});
+function projectConfig(root) {
+    const configPath = join(root, "tsconfig.json");
+    if (!existsSync(configPath))
+        return undefined;
+    const texts = new Map();
+    const host = {
+        ...ts.sys,
+        readFile: (path) => {
+            const text = SourceViewInputs.read(path).toString("utf8");
+            texts.set(resolve(path), text);
+            return text;
+        },
+    };
+    const source = ts.readJsonConfigFile(configPath, host.readFile);
+    const parsed = ts.parseJsonSourceFileConfigFileContent(source, host, root, undefined, configPath, undefined, undefined, new Map());
+    if (parsed.errors.some((diagnostic) => diagnostic.code !== 18002 && diagnostic.code !== 18003))
+        throw new Error("spine-proto: source view has invalid tsconfig.json");
+    const extended = source
+        .extendedSourceFiles ?? [];
+    const files = [source.fileName, ...extended]
+        .map((file) => resolve(file))
+        .filter((file, index, values) => values.indexOf(file) === index)
+        .sort();
+    for (const file of files)
+        if (!texts.has(file))
+            texts.set(file, SourceViewInputs.read(file).toString("utf8"));
+    return Object.freeze({
+        allowJs: parsed.options.allowJs === true,
+        configFiles: Object.freeze(files),
+    });
+}
+function hashFile(hash, category, file) {
+    const content = SourceViewInputs.read(file);
+    hash.update(`${String(category.length)}:${category}${String(file.length)}:${file}${String(content.length)}:`);
+    hash.update(content);
+}
+function inventoryDigest(files, configs = []) {
+    const hash = createHash("sha256");
+    for (const file of files)
+        hashFile(hash, "source", file);
+    for (const config of configs)
+        hashFile(hash, "config", config);
+    return hash.digest("hex");
+}
+function sourceInventory(root, generated) {
+    const generatedDirectory = dirname(generated);
+    const generatedName = basename(generated);
+    const excluded = [generated, "dist"];
+    const siblingStage = join(generatedDirectory, `.${generatedName}.stage-`);
+    const siblingRootTransaction = join(generatedDirectory, `.${generatedName}-`);
+    const siblingBackup = join(generatedDirectory, `.${generatedName}.`);
+    const config = projectConfig(root);
+    const inputs = collectAuthored(root, [...excluded, siblingStage, siblingRootTransaction, siblingBackup], config?.allowJs);
+    const authoredFiles = Object.freeze(inputs.authoredFiles);
+    const compilerFiles = Object.freeze(inputs.compilerFiles);
+    return Object.freeze({
+        authoredFiles,
+        compilerFiles,
+        digest: inventoryDigest(compilerFiles, config?.configFiles),
+    });
+}
+/**
+ * Checks that the immutable authored-source inventory is current before publication.
+ *
+ * @param sourceView Compiler input snapshot captured before generation.
+ */
+export function assertSourceViewCurrent(sourceView) {
+    try {
+        const generated = relative(sourceView.packageRoot, sourceView.liveGeneratedRoot);
+        const current = sourceInventory(sourceView.packageRoot, generated);
+        if (current.digest === sourceView.inventoryDigest)
+            return;
+    }
+    catch {
+        // Report one stable transaction diagnostic for every inventory mutation.
+    }
+    throw new Error("spine-proto: authored interface source view changed during generation");
+}
+/**
+ * Writes the fixed internal source-view handoff for an outer generation stage.
+ *
+ * @param stageRoot Outer staged model package root.
+ * @param sourceView Captured live-authored/staged-generated source view.
+ */
+export function writeViewRecord(stageRoot, sourceView) {
+    writeFileSync(join(stageRoot, recordFileName), `${JSON.stringify({
+        formatVersion: recordFormat,
+        inventoryDigest: sourceView.inventoryDigest,
+        liveGeneratedRoot: sourceView.liveGeneratedRoot,
+        livePackageRoot: sourceView.packageRoot,
+    })}\n`, "utf8");
+}
+/**
+ * Reads one bounded root-transaction source-view handoff.
+ *
+ * @param stageRoot Outer staged model package root.
+ * @param expectedLivePackageRoot Canonical selected live model package root.
+ * @param expectedLiveGeneratedRoot Canonical selected live generated root.
+ * @returns Validated immutable internal handoff.
+ */
+export function readViewRecord(stageRoot, expectedLivePackageRoot, expectedLiveGeneratedRoot) {
+    const recordPath = join(stageRoot, recordFileName);
+    const stagePath = resolve(stageRoot);
+    const candidate = resolve(recordPath);
+    let stage;
+    let regular = false;
+    try {
+        stage = realpathSync(stagePath);
+        regular = lstatSync(candidate).isFile();
+    }
+    catch {
+        throw new Error("spine-proto: invalid source-view publication record");
+    }
+    if (!candidate.startsWith(`${stagePath}/`) || !regular)
+        throw new Error("spine-proto: invalid source-view publication record");
+    const canonicalRecord = realpathSync(candidate);
+    if (!canonicalRecord.startsWith(`${stage}/`))
+        throw new Error("spine-proto: invalid source-view publication record");
+    let descriptor;
+    let raw;
+    try {
+        descriptor = openSync(canonicalRecord, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+        const metadata = fstatSync(descriptor);
+        if (!metadata.isFile() || metadata.size > maximumRecordBytes)
+            throw new Error("spine-proto: invalid source-view publication record");
+        raw = JSON.parse(readFileSync(descriptor).toString("utf8"));
+    }
+    catch {
+        throw new Error("spine-proto: invalid source-view publication record");
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+    if (raw === null || typeof raw !== "object")
+        throw new Error("spine-proto: invalid source-view publication record");
+    const record = raw;
+    const livePackageRoot = realpathSync(expectedLivePackageRoot);
+    const expectedGeneratedRelative = relative(resolve(expectedLivePackageRoot), resolve(expectedLiveGeneratedRoot));
+    const liveGeneratedRoot = resolve(livePackageRoot, expectedGeneratedRelative);
+    if (record.formatVersion !== recordFormat ||
+        record.livePackageRoot !== livePackageRoot ||
+        record.liveGeneratedRoot !== liveGeneratedRoot ||
+        expectedGeneratedRelative === "" ||
+        expectedGeneratedRelative.startsWith("..") ||
+        typeof record.inventoryDigest !== "string" ||
+        !/^[a-f0-9]{64}$/u.test(record.inventoryDigest) ||
+        Object.keys(record).sort().join(",") !==
+            "formatVersion,inventoryDigest,liveGeneratedRoot,livePackageRoot")
+        throw new Error("spine-proto: invalid source-view publication record");
+    return Object.freeze({
+        formatVersion: recordFormat,
+        inventoryDigest: record.inventoryDigest,
+        liveGeneratedRoot,
+        livePackageRoot,
+    });
+}
+/**
+ * Rejects a changed live source/configuration inventory captured in a handoff.
+ *
+ * @param record Validated internal root-transaction handoff.
+ */
+export function assertViewRecordCurrent(record) {
+    try {
+        const generated = relative(record.livePackageRoot, record.liveGeneratedRoot);
+        if (sourceInventory(record.livePackageRoot, generated).digest === record.inventoryDigest)
+            return;
+    }
+    catch {
+        // Report one stable transaction diagnostic for every inventory mutation.
+    }
+    throw new Error("spine-proto: authored interface source view changed during generation");
+}
+function collectAuthored(root, excluded, allowJs = false) {
+    const authoredFiles = [];
+    const compilerFiles = [];
+    const pending = [{ path: root, depth: 0 }];
+    let entries = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (current === undefined)
+            continue;
+        if (current.depth > maximumSourceViewDepth)
+            throw new Error("spine-proto: source view exceeds bounded traversal");
+        for (const name of readdirSync(current.path).sort().reverse()) {
+            entries += 1;
+            if (entries > maximumSourceViewEntries)
+                throw new Error("spine-proto: source view exceeds bounded traversal");
+            const path = join(current.path, name);
+            const relativePath = relative(root, path);
+            if (excluded.some((entry) => relativePath === entry ||
+                relativePath.startsWith(`${entry}${sep}`) ||
+                relativePath.startsWith(`${entry}-`) ||
+                ((entry.endsWith(".") || entry.endsWith("-")) && relativePath.startsWith(entry))))
+                continue;
+            const entry = lstatSync(path);
+            const isTypeScript = [".cts", ".mts", ".ts", ".tsx"].some((extension) => name.endsWith(extension));
+            const isAllowedJavaScript = allowJs && [".cjs", ".js", ".jsx", ".mjs"].some((extension) => name.endsWith(extension));
+            const isCompilerInput = isTypeScript || isAllowedJavaScript;
+            if (entry.isSymbolicLink()) {
+                if (isCompilerInput)
+                    throw new Error(nonRegularInputDiagnostic);
+                continue;
+            }
+            if (entry.isDirectory())
+                pending.push({ path, depth: current.depth + 1 });
+            else if (isCompilerInput) {
+                if (!entry.isFile())
+                    throw new Error(nonRegularInputDiagnostic);
+                compilerFiles.push(path);
+                if (isTypeScript &&
+                    ![".d.cts", ".d.mts", ".d.ts"].some((extension) => name.endsWith(extension)))
+                    authoredFiles.push(path);
+            }
+        }
+    }
+    return Object.freeze({
+        authoredFiles: Object.freeze(authoredFiles.sort()),
+        compilerFiles: Object.freeze(compilerFiles.sort()),
+    });
+}
+/**
+ * Creates a live-authored/staged-generated compiler source view.
+ *
+ * @param packageRoot Model package root.
+ * @param generatedRoot Configured live generated root.
+ * @param stagedGeneratedRoot Generated tree inside the current stage.
+ * @returns Authored compiler candidates and the staged generated redirect root.
+ */
+export function modelSourceView(packageRoot, generatedRoot, stagedGeneratedRoot) {
+    const root = realpathSync(resolve(packageRoot));
+    const generated = generatedRoot.replaceAll("\\", "/");
+    const liveGeneratedRoot = resolve(root, generated);
+    const inventory = sourceInventory(root, generated);
+    return Object.freeze({
+        authoredFiles: inventory.authoredFiles,
+        compilerFiles: inventory.compilerFiles,
+        inventoryDigest: inventory.digest,
+        packageRoot: root,
+        liveGeneratedRoot,
+        stagedGeneratedRoot: resolve(stagedGeneratedRoot),
+    });
+}
+//# sourceMappingURL=source-view.js.map

package/dist/src/generation/source-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-view.js","sourceRoot":"","sources":["../../../src/generation/source-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,SAAS,EACT,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAC5E,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAClC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AACxC,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAC7D,MAAM,YAAY,GAAG,CAAC,CAAC;AACvB,MAAM,kBAAkB,GAAG,EAAE,GAAG,IAAI,CAAC;AAErC,MAAM,yBAAyB,GAAG,gEAAgE,CAAC;AAEnG;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAExB,MAAM,CAAC,MAAM,CAAC;IACjB,kBAAkB;IAElB;;;;;;OAMG;IACH,IAAI,CAAC,IAAY;QACf,IAAI,UAA8B,CAAC;QACnC,IAAI,CAAC;YACH,UAAU,GAAG,QAAQ,CACnB,IAAI,EACJ,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,UAAU,GAAG,SAAS,CAAC,UAAU,CACjE,CAAC;YACF,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,MAAM,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;YAChF,OAAO,YAAY,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,IAAI,KAAK,CAAC,OAAO,KAAK,yBAAyB;gBAAE,MAAM,KAAK,CAAC;YACvF,MAAM,IAAI,KAAK,CAAC,yBAAyB,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/D,CAAC;gBAAS,CAAC;YACT,IAAI,UAAU,KAAK,SAAS;gBAAE,SAAS,CAAC,UAAU,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;CACF,CAAC,CAAC;AA6FH,SAAS,aAAa,CAAC,IAAY;IACjC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC;IAC/C,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;QAAE,OAAO,SAAS,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;IACxC,MAAM,IAAI,GAAG;QACX,GAAG,EAAE,CAAC,GAAG;QACT,QAAQ,EAAE,CAAC,IAAY,EAAE,EAAE;YACzB,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC1D,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,CAAC,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,EAAE,CAAC,oCAAoC,CACpD,MAAM,EACN,IAAI,EACJ,IAAI,EACJ,SAAS,EACT,UAAU,EACV,SAAS,EACT,SAAS,EACT,IAAI,GAAG,EAAE,CACV,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,KAAK,IAAI,UAAU,CAAC,IAAI,KAAK,KAAK,CAAC;QAC5F,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,MAAM,QAAQ,GACX,MAA0E;SACxE,mBAAmB,IAAI,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC;SACzC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;SAC5B,MAAM,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC;SAC/D,IAAI,EAAE,CAAC;IACV,KAAK,MAAM,IAAI,IAAI,KAAK;QACtB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACtF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,KAAK,IAAI;QACxC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;KAClC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,QAAQ,CAAC,IAAmC,EAAE,QAAgB,EAAE,IAAY;IACnF,MAAM,OAAO,GAAG,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC5C,IAAI,CAAC,MAAM,CACT,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CACjG,CAAC;IACF,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,eAAe,CAAC,KAAwB,EAAE,UAA6B,EAAE;IAChF,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClC,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC;IACzD,KAAK,MAAM,MAAM,IAAI,OAAO;QAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AAQD,SAAS,eAAe,CAAC,IAAY,EAAE,SAAiB;IACtD,MAAM,kBAAkB,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9C,MAAM,aAAa,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACrC,MAAM,YAAY,GAAG,IAAI,CAAC,kBAAkB,EAAE,IAAI,aAAa,SAAS,CAAC,CAAC;IAC1E,MAAM,sBAAsB,GAAG,IAAI,CAAC,kBAAkB,EAAE,IAAI,aAAa,GAAG,CAAC,CAAC;IAC9E,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,EAAE,IAAI,aAAa,GAAG,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,eAAe,CAC5B,IAAI,EACJ,CAAC,GAAG,QAAQ,EAAE,YAAY,EAAE,sBAAsB,EAAE,aAAa,CAAC,EAClE,MAAM,EAAE,OAAO,CAChB,CAAC;IACF,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAC1D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,aAAa;QACb,aAAa;QACb,MAAM,EAAE,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,WAAW,CAAC;KAC5D,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAiC;IACvE,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,QAAQ,CAAC,UAAU,CAAC,WAAW,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC;QACjF,MAAM,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;QACnE,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,CAAC,eAAe;YAAE,OAAO;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB,EAAE,UAAiC;IAClF,aAAa,CACX,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,EAC/B,GAAG,IAAI,CAAC,SAAS,CAAC;QAChB,aAAa,EAAE,YAAY;QAC3B,eAAe,EAAE,UAAU,CAAC,eAAe;QAC3C,iBAAiB,EAAE,UAAU,CAAC,iBAAiB;QAC/C,eAAe,EAAE,UAAU,CAAC,WAAW;KACxC,CAAC,IAAI,EACN,MAAM,CACP,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAiB,EACjB,uBAA+B,EAC/B,yBAAiC;IAEjC,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IACrC,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACtC,IAAI,KAAa,CAAC;IAClB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,CAAC,IAAI,CAAC,OAAO;QACpD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,MAAM,eAAe,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC;IAChD,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,IAAI,UAA8B,CAAC;IACnC,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACH,UAAU,GAAG,QAAQ,CACnB,eAAe,EACf,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,UAAU,GAAG,SAAS,CAAC,UAAU,CACjE,CAAC;QACF,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;QACvC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,QAAQ,CAAC,IAAI,GAAG,kBAAkB;YAC1D,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;YAAS,CAAC;QACT,IAAI,UAAU,KAAK,SAAS;YAAE,SAAS,CAAC,UAAU,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QACzC,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,MAAM,MAAM,GAAG,GAA2C,CAAC;IAC3D,MAAM,eAAe,GAAG,YAAY,CAAC,uBAAuB,CAAC,CAAC;IAC9D,MAAM,yBAAyB,GAAG,QAAQ,CACxC,OAAO,CAAC,uBAAuB,CAAC,EAChC,OAAO,CAAC,yBAAyB,CAAC,CACnC,CAAC;IACF,MAAM,iBAAiB,GAAG,OAAO,CAAC,eAAe,EAAE,yBAAyB,CAAC,CAAC;IAC9E,IACE,MAAM,CAAC,aAAa,KAAK,YAAY;QACrC,MAAM,CAAC,eAAe,KAAK,eAAe;QAC1C,MAAM,CAAC,iBAAiB,KAAK,iBAAiB;QAC9C,yBAAyB,KAAK,EAAE;QAChC,yBAAyB,CAAC,UAAU,CAAC,IAAI,CAAC;QAC1C,OAAO,MAAM,CAAC,eAAe,KAAK,QAAQ;QAC1C,CAAC,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC;QAC/C,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC;YAClC,iEAAiE;QAEnE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,aAAa,EAAE,YAAY;QAC3B,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,iBAAiB;QACjB,eAAe;KAChB,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAmC;IACzE,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,CAAC,eAAe,EAAE,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAC7E,IAAI,eAAe,CAAC,MAAM,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,eAAe;YACtF,OAAO;IACX,CAAC;IAAC,MAAM,CAAC;QACP,yEAAyE;IAC3E,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;AAC3F,CAAC;AAED,SAAS,eAAe,CACtB,IAAY,EACZ,QAA2B,EAC3B,OAAO,GAAG,KAAK;IAEf,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,MAAM,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IAC3C,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;QAC9B,IAAI,OAAO,KAAK,SAAS;YAAE,SAAS;QACpC,IAAI,OAAO,CAAC,KAAK,GAAG,sBAAsB;YACxC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC;YAC9D,OAAO,IAAI,CAAC,CAAC;YACb,IAAI,OAAO,GAAG,wBAAwB;gBACpC,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;YACxE,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACtC,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC1C,IACE,QAAQ,CAAC,IAAI,CACX,CAAC,KAAK,EAAE,EAAE,CACR,YAAY,KAAK,KAAK;gBACtB,YAAY,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,GAAG,EAAE,CAAC;gBACzC,YAAY,CAAC,UAAU,CAAC,GAAG,KAAK,GAAG,CAAC;gBACpC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,YAAY,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CACnF;gBAED,SAAS;YACX,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;YAC9B,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CACtE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CACzB,CAAC;YACF,MAAM,mBAAmB,GACvB,OAAO,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;YAC3F,MAAM,eAAe,GAAG,YAAY,IAAI,mBAAmB,CAAC;YAC5D,IAAI,KAAK,CAAC,cAAc,EAAE,EAAE,CAAC;gBAC3B,IAAI,eAAe;oBAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;gBAChE,SAAS;YACX,CAAC;YACD,IAAI,KAAK,CAAC,WAAW,EAAE;gBAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;iBACrE,IAAI,eAAe,EAAE,CAAC;gBACzB,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;oBAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;gBAChE,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACzB,IACE,YAAY;oBACZ,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;oBAE5E,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;QAClD,aAAa,EAAE,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC;KACnD,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,WAAmB,EACnB,aAAqB,EACrB,mBAA2B;IAE3B,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;IAChD,MAAM,SAAS,GAAG,aAAa,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtD,MAAM,iBAAiB,GAAG,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACnD,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,eAAe,EAAE,SAAS,CAAC,MAAM;QACjC,WAAW,EAAE,IAAI;QACjB,iBAAiB;QACjB,mBAAmB,EAAE,OAAO,CAAC,mBAAmB,CAAC;KAClD,CAAC,CAAC;AACL,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Published manifest JSON revision.
+ */
+export declare const manifestFormatVersion = 2;
+/**
+ * Configures an independently published Proto model package.
+ */
+export interface ModelConfig {
+    /**
+     * Declares the version of this configuration contract.
+     */
+    readonly formatVersion: 1;
+    /**
+     * Selects an independently published model package.
+     */
+    readonly mode: "model";
+    /**
+     * Names the owning npm package.
+     */
+    readonly packageName: string;
+    /**
+     * Locates the package-contained canonical Proto sources.
+     */
+    readonly protoRoot: string;
+    /**
+     * Locates the package-contained generated TypeScript files.
+     */
+    readonly generatedRoot: string;
+    /**
+     * Names the generated import subpath root.
+     */
+    readonly exportRoot: string;
+    /**
+     * Lists direct model packages from the npm registry.
+     */
+    readonly dependencies: readonly string[];
+    /**
+     * Names the generated model-module export.
+     */
+    readonly moduleExport: string;
+}
+/**
+ * Configures an application that composes published Proto model packages.
+ */
+export interface ApplicationConfig {
+    /**
+     * Declares the version of this configuration contract.
+     */
+    readonly formatVersion: 1;
+    /**
+     * Selects application model composition.
+     */
+    readonly mode: "application";
+    /**
+     * Lists direct model packages from the npm registry.
+     */
+    readonly modelPackages: readonly string[];
+    /**
+     * Locates the generated package registry source file.
+     */
+    readonly registryOutput: string;
+}
+/**
+ * Version-one model or application configuration selected by mode.
+ */
+export type SpineProtoConfig = ModelConfig | ApplicationConfig;
+/**
+ * Describes the Proto sources and generated exports owned by a model package.
+ */
+export interface ProtoManifest {
+    /**
+     * Declares the version of this manifest contract.
+     */
+    readonly formatVersion: 2;
+    /**
+     * Stores the opaque identifier shared with the generated-root marker.
+     */
+    readonly generationId: string;
+    /**
+     * Names the package that owns every listed Proto source.
+     */
+    readonly packageName: string;
+    /**
+     * States the declared version from the owning package.json file.
+     */
+    readonly packageVersion: string;
+    /**
+     * Lists canonical package-relative Proto paths owned by the package.
+     */
+    readonly protoFiles: readonly string[];
+    /**
+     * Maps each Proto path to its generated package-relative import subpath.
+     */
+    readonly generatedExports: Readonly<Record<string, string>>;
+    /**
+     * Lists direct model-package dependencies.
+     */
+    readonly dependencies: readonly string[];
+    /**
+     * Names the generated ProtoModule export.
+     */
+    readonly moduleExport: string;
+}
+/**
+ * Provides access to the versioned Proto package configuration.
+ */
+export declare const ProtoConfig: Readonly<{
+    /**
+     * Reads and validates `spine-proto.json` at a package root.
+     *
+     * @param packageRoot The package root that contains the configuration.
+     * @returns The validated model or application configuration.
+     */
+    read(packageRoot: string): SpineProtoConfig;
+}>;
+/**
+ * Provides access to deterministic Proto package manifests.
+ */
+export declare const ProtoManifest: Readonly<{
+    /**
+     * Reads and validates a package manifest.
+     *
+     * @param packageRoot The package root that owns the manifest.
+     * @param manifestPath The optional manifest path within the package root.
+     * @returns The validated manifest.
+     */
+    read(packageRoot: string, manifestPath?: string): ProtoManifest;
+    /**
+     * Creates a manifest from package-owned Proto paths. Without a supplied generation ID,
+     * a fresh random ID is assigned for a new generated-root marker lifecycle.
+     *
+     * @param packageRoot The model package root.
+     * @param ownedProtoFiles Optional explicit package-relative Proto paths.
+     * @param generationId Optional generation ID; a random ID is used when omitted.
+     * @returns The created manifest.
+     */
+    create(packageRoot: string, ownedProtoFiles?: readonly string[], generationId?: string): ProtoManifest;
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AA8BA;;GAEG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAiEvC;;GAEG;AACH,MAAM,WAAW,WAAW;IAG1B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B;;OAEG;IACH,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE5D;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAumBD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC;IAGjC;;;;;OAKG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAAC;CAC7C,CAYC,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,QAAQ,CAAC;IAGnC;;;;;;OAMG;IACH,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;IAEhE;;;;;;;;OAQG;IACH,MAAM,CACJ,WAAW,EAAE,MAAM,EACnB,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,EACnC,YAAY,CAAC,EAAE,MAAM,GACpB,aAAa,CAAC;CAClB,CA2CC,CAAC"}