@ykdz/template 0.0.23 → 0.0.25

package/node_modules/@ykdz/template-core/dist/template-boundary-check.js

@@ -1,12 +1,46 @@
-import { readFile } from "node:fs/promises";
+import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import ts from "@typescript/typescript6";
+import ts from "typescript";
+import { resolveTemplateSource } from "./renderer.js";
 const inlineOperationKinds = new Set([
     "writeText",
     "writeJson",
     "mergeJson",
 ]);
-export const templateBoundaryDebtAllowlist = [];
+async function listTemplateSourceFiles(root) {
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const entryPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listTemplateSourceFiles(entryPath)));
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        await readFile(entryPath);
+        files.push(path.resolve(entryPath));
+    }
+    return files;
+}
+/**
+ * Reads each registered Template Source context before any plan is inspected.
+ * The resulting file sets are an independent proof consumed by the boundary check.
+ */
+export async function checkTemplateSourceContexts(contexts) {
+    return await Promise.all(contexts.map(async (context) => {
+        const root = path.resolve(context.root);
+        const rootStats = await stat(root);
+        if (!rootStats.isDirectory()) {
+            throw new Error(`Template Source context ${context.name} root is not a directory: ${root}`);
+        }
+        return {
+            ...context,
+            root,
+            checkedFiles: await listTemplateSourceFiles(root),
+        };
+    }));
+}
 function operationTarget(operation) {
     if ("to" in operation) {
         return operation.to;
@@ -464,33 +498,46 @@ function isAllowedStructuralMachineDeclaration(sourceFile, operation) {
             return value !== undefined && isDevelopmentContainerPlanValue(value);
         }));
 }
-function allowlistKey(preset, generatedPath, owningFunction) {
-    return `${preset}\0${owningFunction}\0${generatedPath}`;
-}
-function resolveOperationSourceRoot(projection, sourceRootName) {
-    if (sourceRootName === undefined) {
-        return projection.plan.sourceRoot;
-    }
-    return projection.plan.sourceRoots?.[sourceRootName];
-}
 function sourceBackedOperationSourceFiles(projection, operation) {
     if (operation.kind === "writeTextFromFragments") {
         return operation.fragments.map((fragment) => {
-            const root = resolveOperationSourceRoot(projection, fragment.sourceRoot);
-            return root === undefined
-                ? `missing-source-root:${fragment.sourceRoot}`
-                : path.resolve(root, fragment.from);
+            try {
+                return resolveTemplateSource(fragment.source, fragment.from);
+            }
+            catch (error) {
+                return `invalid-source:${error instanceof Error ? error.message : String(error)}`;
+            }
         });
     }
-    const root = resolveOperationSourceRoot(projection, operation.sourceRoot);
-    return [
-        root === undefined
-            ? `missing-source-root:${operation.sourceRoot}`
-            : path.resolve(root, operation.from),
-    ];
+    try {
+        return [resolveTemplateSource(operation.source, operation.from)];
+    }
+    catch (error) {
+        return [
+            `invalid-source:${error instanceof Error ? error.message : String(error)}`,
+        ];
+    }
 }
-function operationUsesManifestReferencedSource(projection, operation, manifestReferencedSourceFiles) {
-    return sourceBackedOperationSourceFiles(projection, operation).every((sourceFile) => manifestReferencedSourceFiles.has(sourceFile));
+async function operationUsesCheckedTemplateSource(projection, operation, templateSourceContexts, manifestReferencedSourceFiles) {
+    const sourceFiles = sourceBackedOperationSourceFiles(projection, operation);
+    const results = await Promise.all(sourceFiles.map(async (sourceFile) => {
+        const context = templateSourceContexts.find((candidate) => {
+            const root = path.resolve(candidate.root);
+            return (sourceFile.startsWith(`${root}${path.sep}`) || sourceFile === root);
+        });
+        if (context === undefined) {
+            return manifestReferencedSourceFiles.has(sourceFile);
+        }
+        const relativePath = path.relative(path.resolve(context.root), sourceFile);
+        if (relativePath.length === 0 ||
+            relativePath === ".." ||
+            relativePath.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relativePath)) {
+            return false;
+        }
+        return context.checkedFiles?.includes(sourceFile) ?? false;
+    }));
+    return results.every(Boolean);
 }
 function pushSourceBackedOperationViolations(options) {
     const generatedPath = operationTarget(options.operation);
@@ -504,26 +551,31 @@ function pushSourceBackedOperationViolations(options) {
             generatedPath,
             owningFunction,
             operationKind: options.operation.kind,
-            sourceFilePath: options.projection.sourceFilePath,
+            sourceFilePath: options.operation.provenance?.plannerSourceFile ??
+                options.projection.sourceFilePath,
+            ...(options.operation.provenance === undefined &&
+                options.projection.definitionName === undefined
+                ? {}
+                : {
+                    definitionName: options.operation.provenance?.definitionName ??
+                        options.projection.definitionName,
+                    planningContribution: options.operation.provenance?.planningContribution ??
+                        options.projection.planningContribution,
+                    ownershipRule: options.operation.provenance?.ownershipRule ??
+                        "source-backed protected output must use declared, contained Template Source",
+                }),
         });
     }
 }
-export async function checkTemplateSourceBoundary({ projections, manifestReferencedSourceFiles = [], allowlist = [], }) {
+export async function checkTemplateSourceBoundary({ projections, templateSourceContexts = [], manifestReferencedSourceFiles = [], }) {
     const manifestReferencedSourceFileSet = new Set(manifestReferencedSourceFiles.map((sourceFile) => path.resolve(sourceFile)));
-    const allowed = new Map(allowlist.map((entry) => [
-        allowlistKey(entry.preset, entry.generatedPath, entry.owningFunction),
-        entry.reason,
-    ]));
-    const checkedPresets = new Set(projections.map((projection) => projection.name));
-    const usedAllowlistKeys = new Set();
     const violations = [];
-    const allowlistedDebt = [];
     for (const projection of projections) {
         const sourceText = await readFile(projection.sourceFilePath, "utf8");
         const sourceFile = ts.createSourceFile(projection.sourceFilePath, sourceText, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
         for (const operation of projection.plan.operations) {
             if (isProtectedSourceBackedOperation(operation)) {
-                if (!operationUsesManifestReferencedSource(projection, operation, manifestReferencedSourceFileSet)) {
+                if (!(await operationUsesCheckedTemplateSource(projection, operation, templateSourceContexts, manifestReferencedSourceFileSet))) {
                     pushSourceBackedOperationViolations({
                         projection,
                         sourceFile,
@@ -549,28 +601,26 @@ export async function checkTemplateSourceBoundary({ projections, manifestReferen
                     generatedPath: operation.to,
                     owningFunction,
                     operationKind: operation.kind,
-                    sourceFilePath: projection.sourceFilePath,
+                    sourceFilePath: operation.provenance?.plannerSourceFile ??
+                        projection.sourceFilePath,
+                    ...(operation.provenance === undefined &&
+                        projection.definitionName === undefined
+                        ? {}
+                        : {
+                            definitionName: operation.provenance?.definitionName ??
+                                projection.definitionName,
+                            planningContribution: operation.provenance?.planningContribution ??
+                                projection.planningContribution,
+                            ownershipRule: operation.provenance?.ownershipRule ??
+                                "protected generated output must be Template Source-backed",
+                        }),
                 };
-                const allowlistReason = allowed.get(allowlistKey(projection.name, operation.to, owningFunction));
-                if (allowlistReason) {
-                    usedAllowlistKeys.add(allowlistKey(projection.name, operation.to, owningFunction));
-                    allowlistedDebt.push({ ...diagnostic, allowlistReason });
-                    continue;
-                }
                 violations.push(diagnostic);
             }
         }
     }
-    const unusedAllowlistEntries = allowlist.filter((entry) => {
-        if (!checkedPresets.has(entry.preset)) {
-            return false;
-        }
-        return !usedAllowlistKeys.has(allowlistKey(entry.preset, entry.generatedPath, entry.owningFunction));
-    });
     return {
-        ok: violations.length === 0 && unusedAllowlistEntries.length === 0,
+        ok: violations.length === 0,
         violations,
-        allowlistedDebt,
-        unusedAllowlistEntries,
     };
 }

package/node_modules/@ykdz/template-core/dist/toolchain-baseline-update.d.ts

@@ -0,0 +1,45 @@
+export type ToolchainBaseline = {
+    readonly nodeLtsMajor: string;
+    readonly packageManagerPin: `pnpm@${string}`;
+};
+export type ToolchainPullRequestCandidate = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "open";
+    readonly pullRequestNumber: number;
+};
+export type ToolchainRemoteBranch = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "present";
+    readonly sha: string;
+};
+export type ToolchainUpdateCandidate = {
+    readonly pullRequest: ToolchainPullRequestCandidate;
+    readonly remoteBranch: ToolchainRemoteBranch;
+};
+export type ToolchainBaselineUpdatePlan = {
+    readonly kind: "no-drift";
+} | {
+    readonly kind: "cleanup-stale";
+    readonly pullRequestNumber?: number;
+    readonly deleteBranch: true;
+} | {
+    readonly kind: "update";
+    readonly mode: "create";
+    readonly desired: ToolchainBaseline;
+} | {
+    readonly kind: "update";
+    readonly mode: "replace";
+    readonly pullRequestNumber: number;
+    readonly desired: ToolchainBaseline;
+};
+type PlanToolchainBaselineUpdateOptions = {
+    readonly current: ToolchainBaseline & {
+        readonly materialConsistent?: boolean;
+    };
+    readonly desired: ToolchainBaseline;
+    readonly candidate: ToolchainUpdateCandidate;
+};
+export declare function planToolchainBaselineUpdate(options: PlanToolchainBaselineUpdateOptions): ToolchainBaselineUpdatePlan;
+export {};

package/node_modules/@ykdz/template-core/dist/toolchain-baseline-update.js

@@ -0,0 +1,27 @@
+export function planToolchainBaselineUpdate(options) {
+    const hasDrift = options.current.materialConsistent === false ||
+        options.current.nodeLtsMajor !== options.desired.nodeLtsMajor ||
+        options.current.packageManagerPin !== options.desired.packageManagerPin;
+    if (!hasDrift) {
+        return options.candidate.pullRequest.kind === "absent" &&
+            options.candidate.remoteBranch.kind === "absent"
+            ? { kind: "no-drift" }
+            : {
+                kind: "cleanup-stale",
+                ...(options.candidate.pullRequest.kind === "open"
+                    ? {
+                        pullRequestNumber: options.candidate.pullRequest.pullRequestNumber,
+                    }
+                    : {}),
+                deleteBranch: true,
+            };
+    }
+    return options.candidate.pullRequest.kind === "absent"
+        ? { kind: "update", mode: "create", desired: options.desired }
+        : {
+            kind: "update",
+            mode: "replace",
+            pullRequestNumber: options.candidate.pullRequest.pullRequestNumber,
+            desired: options.desired,
+        };
+}

package/node_modules/@ykdz/template-core/dist/toolchain-resolution.d.ts

@@ -18,6 +18,7 @@ export type ResolveToolchainVersionsOptions = {
     readonly fetchJson?: ((url: string) => Promise<unknown>) | undefined;
     readonly nodeReleaseIndexUrl?: string | undefined;
     readonly pnpmRegistryUrl?: string | undefined;
+    readonly now?: Date | string | undefined;
 };
 export declare const nodeReleaseIndexUrl = "https://nodejs.org/dist/index.json";
 export declare const pnpmRegistryUrl = "https://registry.npmjs.org/pnpm";

package/node_modules/@ykdz/template-core/dist/toolchain-resolution.js

@@ -2,7 +2,7 @@ export const nodeReleaseIndexUrl = "https://nodejs.org/dist/index.json";
 export const pnpmRegistryUrl = "https://registry.npmjs.org/pnpm";
 const bundledFallbackToolchain = {
     nodeLtsMajor: nodeLtsMajor("24"),
-    packageManagerPin: packageManagerPin("10.34.4"),
+    packageManagerPin: packageManagerPin("11.11.0"),
 };
 export async function resolveToolchainVersions(options = {}) {
     const source = options.source ?? "online";
@@ -14,7 +14,8 @@ export async function resolveToolchainVersions(options = {}) {
         const nodeReleases = parseNodeReleaseIndex(await fetchJson(options.nodeReleaseIndexUrl ?? nodeReleaseIndexUrl));
         const nodeMajor = latestLtsMajor(nodeReleases);
         const pnpmMetadata = parsePnpmRegistryMetadata(await fetchJson(options.pnpmRegistryUrl ?? pnpmRegistryUrl));
-        const pnpmVersion = latestCompatiblePnpmVersion(pnpmMetadata, Number(nodeMajor.value));
+        const nodeVersion = latestLtsVersion(nodeReleases, nodeMajor);
+        const pnpmVersion = latestCompatiblePnpmVersion(pnpmMetadata, nodeVersion, instant(options.now ?? new Date()));
         return {
             nodeLtsMajor: nodeMajor,
             packageManagerPin: packageManagerPin(pnpmVersion),
@@ -31,19 +32,20 @@ export async function resolveToolchainVersions(options = {}) {
 }
 export async function checkOnlineToolchainResolutionContract(options = {}) {
     const fetchJson = options.fetchJson ?? fetchOfficialJson;
-    const nodeMajor = await contractPhase("Node source parsing", async () => {
-        const nodeReleases = parseNodeReleaseIndex(await fetchJson(nodeReleaseIndexUrl));
-        return latestLtsMajor(nodeReleases);
+    const nodeSource = await contractPhase("Node source parsing", async () => {
+        const releases = parseNodeReleaseIndex(await fetchJson(nodeReleaseIndexUrl));
+        const major = latestLtsMajor(releases);
+        return { major, version: latestLtsVersion(releases, major) };
     });
     const pnpmMetadata = await contractPhase("pnpm source parsing", async () => parsePnpmRegistryMetadata(await fetchJson(pnpmRegistryUrl)));
-    const pnpmVersion = await contractPhase("compatibility selection", async () => latestCompatiblePnpmVersion(pnpmMetadata, Number(nodeMajor.value)));
+    const pnpmVersion = await contractPhase("compatibility selection", async () => latestCompatiblePnpmVersion(pnpmMetadata, nodeSource.version));
     return {
-        nodeLtsMajor: nodeMajor,
+        nodeLtsMajor: nodeSource.major,
         packageManagerPin: packageManagerPin(pnpmVersion),
         diagnostics: [
-            `Node source parsing succeeded; latest LTS major is ${nodeMajor.value}.`,
+            `Node source parsing succeeded; latest LTS major is ${nodeSource.major.value}.`,
             `pnpm source parsing succeeded; latest compatible pnpm release is ${pnpmVersion}.`,
-            `Compatibility selection succeeded for pnpm@${pnpmVersion} on Node ${nodeMajor.value}.`,
+            `Compatibility selection succeeded for pnpm@${pnpmVersion} on Node ${nodeSource.major.value}.`,
         ],
     };
 }
@@ -113,9 +115,21 @@ function latestLtsMajor(releases) {
     }
     return nodeLtsMajor(String(Math.max(...majors)));
 }
+function latestLtsVersion(releases, major) {
+    const versions = releases
+        .filter((release) => release.lts !== false)
+        .map((release) => release.version.replace(/^v/, ""))
+        .filter((version) => valid(version) !== null && version.startsWith(`${major.value}.`))
+        .toSorted(compare);
+    const latest = versions.at(-1);
+    if (!latest) {
+        throw new Error(`Node release index did not contain Node ${major.value}`);
+    }
+    return latest;
+}
 function parsePnpmRegistryMetadata(value) {
-    if (!isRecord(value) || !isRecord(value.versions)) {
-        throw new Error("pnpm registry metadata is missing versions");
+    if (!isRecord(value) || !isRecord(value.versions) || !isRecord(value.time)) {
+        throw new Error("pnpm registry metadata is missing versions or time");
     }
     const versions = {};
     for (const [version, metadata] of Object.entries(value.versions)) {
@@ -131,61 +145,45 @@ function parsePnpmRegistryMetadata(value) {
             }
             : {};
     }
-    return { versions };
+    const time = Object.fromEntries(Object.entries(value.time).filter((entry) => typeof entry[1] === "string"));
+    return { time, versions };
 }
-function latestCompatiblePnpmVersion(metadata, nodeMajor) {
+function latestCompatiblePnpmVersion(metadata, nodeVersion, now = Date.now()) {
     const candidates = Object.entries(metadata.versions)
-        .filter(([version]) => /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version))
-        .filter(([, packageMetadata]) => nodeSatisfiesRange(nodeMajor, packageMetadata.engines?.node))
+        .filter(([version]) => /^\d+\.\d+\.\d+$/.test(version))
+        .filter(([, packageMetadata]) => nodeSatisfiesRange(nodeVersion, packageMetadata.engines?.node))
+        .filter(([version]) => isMatureRelease(metadata.time[version], now))
         .map(([version]) => version)
-        .toSorted(compareSemver);
+        .toSorted(compare);
     const latest = candidates.at(-1);
     if (!latest) {
-        throw new Error(`pnpm registry metadata did not contain a release compatible with Node ${nodeMajor}`);
+        throw new Error(`pnpm registry metadata did not contain a release compatible with Node ${nodeVersion}`);
     }
     return latest;
 }
-function nodeSatisfiesRange(nodeMajor, range) {
-    if (!range) {
-        return true;
-    }
-    return range
-        .split(/\s+/)
-        .filter(Boolean)
-        .every((comparator) => nodeSatisfiesComparator(nodeMajor, comparator));
-}
-function nodeSatisfiesComparator(nodeMajor, comparator) {
-    const match = comparator.match(/^(>=|>|<=|<|=)?(\d+)(?:\.\d+){0,2}$/);
-    if (!match) {
+const pnpmMaturityWindowMilliseconds = 24 * 60 * 60 * 1_000;
+function isMatureRelease(publishedAt, now) {
+    if (publishedAt === undefined) {
         return false;
     }
-    const operator = match[1] ?? "=";
-    const major = Number(match[2]);
-    if (operator === ">=") {
-        return nodeMajor >= major;
-    }
-    if (operator === ">") {
-        return nodeMajor > major;
-    }
-    if (operator === "<=") {
-        return nodeMajor <= major;
-    }
-    if (operator === "<") {
-        return nodeMajor < major;
+    const publishedAtMilliseconds = Date.parse(publishedAt);
+    return (Number.isFinite(publishedAtMilliseconds) &&
+        now - publishedAtMilliseconds >= pnpmMaturityWindowMilliseconds);
+}
+function instant(value) {
+    const milliseconds = value instanceof Date ? value.getTime() : Date.parse(value);
+    if (!Number.isFinite(milliseconds)) {
+        throw new Error(`Invalid resolution time: ${String(value)}`);
     }
-    return nodeMajor === major;
+    return milliseconds;
 }
-function compareSemver(left, right) {
-    const leftParts = left.split(/[.-]/).slice(0, 3).map(Number);
-    const rightParts = right.split(/[.-]/).slice(0, 3).map(Number);
-    for (let index = 0; index < 3; index += 1) {
-        const difference = (leftParts[index] ?? 0) - (rightParts[index] ?? 0);
-        if (difference !== 0) {
-            return difference;
-        }
+function nodeSatisfiesRange(nodeVersion, range) {
+    if (!range) {
+        return true;
     }
-    return left.localeCompare(right);
+    return satisfies(nodeVersion, range, { includePrerelease: false });
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+import { compare, satisfies, valid } from "semver";

package/node_modules/@ykdz/template-core/package.json

@@ -8,10 +8,6 @@
   "type": "module",
   "exports": {
     "./*": {
-      "source": {
-        "types": "./src/*.ts",
-        "default": "./src/*.ts"
-      },
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"
     }
@@ -25,16 +21,22 @@
     "typecheck": "tsc -p tsconfig.json --noEmit --pretty false"
   },
   "dependencies": {
-    "@typescript/typescript6": "catalog:",
-    "@ykdz/template-shared": "workspace:*",
+    "semver": "catalog:",
+    "typescript": "catalog:",
     "valibot": "catalog:"
   },
   "devDependencies": {
     "@types/node": "catalog:",
-    "@typescript/native": "catalog:",
+    "@types/semver": "catalog:",
     "execa": "catalog:",
     "oxfmt": "catalog:",
     "oxlint": "catalog:",
-    "oxlint-tsgolint": "catalog:"
+    "oxlint-tsgolint": "catalog:",
+    "typescript-7": "catalog:"
+  },
+  "turbo": {
+    "tags": [
+      "template-core"
+    ]
   }
 }

package/node_modules/semver/LICENSE

@@ -0,0 +1,15 @@
+The ISC License
+
+Copyright (c) Isaac Z. Schlueter and Contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.