@ykdz/template 0.0.31 → 0.0.33

package/node_modules/@ykdz/template-core/dist/project-github.js

@@ -1,112 +1,109 @@
-import { renderPlaywrightBrowserInstallCommand, } from "./module-graph.js";
+import { composeCiDiagnosticArtifacts, } from "./ci-diagnostic-artifact.js";
+function validatedDiagnosticArtifacts(options) {
+    return composeCiDiagnosticArtifacts({
+        packagePaths: options.packagePaths,
+        declarations: options.artifacts,
+    });
+}
 const defaultCiCapability = {
     workflowName: "Check",
     jobName: "check",
+    jobDisplayName: "Root Check",
     runner: "ubuntu-latest",
+    timeoutMinutes: 30,
 };
 const pnpmTaskLayer = {
-    installCommand: "pnpm install",
+    installCommand: "pnpm install --frozen-lockfile",
     checkCommand: "pnpm run check",
 };
-export function projectCheckWorkflow(options) {
+/** Capability facts for the Foundation-owned GitHub Actions Template Source. */
+export function projectCheckWorkflowPlan(options) {
     const capability = options.capability ?? defaultCiCapability;
     const environmentPreparation = {
         nodeFromPackageMetadata: true,
-        rustToolchain: false,
+        packageManagerFromPackageMetadata: true,
+        pnpmStoreCache: true,
         ...options.environmentPreparation,
     };
-    const requiresRustToolchain = environmentPreparation.rustToolchain ||
-        options.environment.needs.some((need) => need.kind === "rust-toolchain");
     const taskLayer = options.taskLayer ?? pnpmTaskLayer;
     const hasDeploymentTask = options.hasDeploymentTask === true;
     const needsDocker = (options.deploymentEnvironmentNeeds ?? []).some((need) => need.kind === "docker-engine");
-    const lines = [
-        `name: ${capability.workflowName}`,
-        "",
-        "on:",
-        "  pull_request:",
-        "  push:",
-        "    branches:",
-        "      - main",
-        "",
-        "jobs:",
-        `  ${capability.jobName}:`,
-        `    runs-on: ${capability.runner}`,
-        ...(hasDeploymentTask
-            ? ["    strategy:", "      matrix:", "        check: [root, deployment]"]
-            : []),
-        "    steps:",
-        "      - uses: actions/checkout@v7",
-    ];
-    if (environmentPreparation.nodeFromPackageMetadata) {
-        lines.push("      - uses: actions/setup-node@v7", "        with:", "          node-version-file: package.json", "      - run: corepack enable");
+    if (hasDeploymentTask && !needsDocker) {
+        throw new Error("Deployment Check requires a Docker environment need");
     }
-    if (hasDeploymentTask && needsDocker) {
-        lines.push("      - uses: docker/setup-buildx-action@v3", "        if: matrix.check == 'deployment'");
-    }
-    if (requiresRustToolchain)
-        lines.push(...rustCiPreparationLines());
-    lines.push(`      - run: ${taskLayer.installCommand}`);
-    const checkEnvironmentLines = [];
-    for (const need of options.environment.needs) {
-        if (need.kind === "rust-toolchain") {
-            continue;
-        }
-        checkEnvironmentLines.push(`      - run: ${renderCiEnvironmentNeedCommand(need)}`);
-        if (hasDeploymentTask && need.kind === "shellcheck-command") {
-            checkEnvironmentLines.push("        if: matrix.check == 'root'");
-        }
-    }
-    lines.push(...checkEnvironmentLines);
-    lines.push(`      - run: ${taskLayer.checkCommand}`);
-    if (hasDeploymentTask) {
-        lines.push("        if: matrix.check == 'root'");
+    const packagePaths = [...options.packagePaths];
+    const diagnosticArtifacts = validatedDiagnosticArtifacts({
+        packagePaths,
+        artifacts: options.diagnosticArtifacts ?? [],
+    });
+    return {
+        workflowName: capability.workflowName,
+        triggers: { pullRequest: true, pushBranches: ["main"] },
+        permissions: { contents: "read" },
+        concurrency: {
+            group: "${{ github.workflow }}-${{ github.ref }}",
+            cancelInProgress: true,
+        },
+        rootCheck: capability,
+        matrix: hasDeploymentTask
+            ? {
+                failFast: false,
+                include: [
+                    {
+                        capability: "root",
+                        jobDisplayName: capability.jobDisplayName,
+                        taskEntrypoint: taskLayer.checkCommand,
+                        timeoutMinutes: capability.timeoutMinutes,
+                        requiresDocker: false,
+                    },
+                    {
+                        capability: "deployment",
+                        jobDisplayName: "Deployment Check",
+                        taskEntrypoint: "pnpm run check:deployment",
+                        timeoutMinutes: 45,
+                        requiresDocker: true,
+                    },
+                ],
+            }
+            : undefined,
+        environmentPreparation,
+        taskLayer,
+        packagePaths,
+        diagnosticArtifacts,
+    };
+}
+/** Selects a complete Foundation-owned workflow Template Source. */
+export function projectCheckWorkflowTemplateSource(options) {
+    const hasDeploymentTask = options.hasDeploymentTask === true;
+    const needsDocker = (options.deploymentEnvironmentNeeds ?? []).some((need) => need.kind === "docker-engine");
+    if (hasDeploymentTask && !needsDocker) {
+        throw new Error("Deployment Check requires a Docker environment need");
     }
+    const hasDiagnostics = validatedDiagnosticArtifacts({
+        packagePaths: options.packagePaths,
+        artifacts: options.diagnosticArtifacts ?? [],
+    }).length > 0;
     if (hasDeploymentTask) {
-        lines.push("      - run: pnpm run check:deployment", "        if: matrix.check == 'deployment'");
+        return hasDiagnostics
+            ? ".github/workflows/check-deployment-diagnostics.yml"
+            : ".github/workflows/check-deployment.yml";
     }
-    lines.push("");
-    return lines.join("\n");
-}
-function rustCiPreparationLines() {
-    return [
-        "      - uses: dtolnay/rust-toolchain@stable",
-        "        with:",
-        "          components: rustfmt, clippy",
-        "      - uses: Swatinem/rust-cache@v2",
-    ];
+    return hasDiagnostics
+        ? ".github/workflows/check-diagnostics.yml"
+        : ".github/workflows/check.yml";
 }
-/** Limited substitutions for the Foundation-owned workflow Template Source. */
+/** Limited, validated facts for static Foundation diagnostic staging. */
 export function projectCheckWorkflowTemplateReplacements(options) {
-    const requiresRustToolchain = options.environmentPreparation?.rustToolchain === true ||
-        options.environment.needs.some((need) => need.kind === "rust-toolchain");
-    const hasDeploymentTask = options.hasDeploymentTask === true;
-    const needsDocker = (options.deploymentEnvironmentNeeds ?? []).some((need) => need.kind === "docker-engine");
-    const environmentSteps = options.environment.needs
-        .filter((need) => need.kind !== "rust-toolchain")
-        .map((need) => [
-        `      - run: ${renderCiEnvironmentNeedCommand(need)}`,
-        ...(hasDeploymentTask && need.kind === "shellcheck-command"
-            ? ["        if: matrix.check == 'root'"]
-            : []),
-    ].join("\n"));
+    const declarations = validatedDiagnosticArtifacts({
+        packagePaths: options.packagePaths,
+        artifacts: options.diagnosticArtifacts ?? [],
+    });
+    if (declarations.length === 0)
+        return {};
     return {
-        RUST_CI_PREPARATION: requiresRustToolchain
-            ? `\n${rustCiPreparationLines().join("\n")}`
-            : "",
-        CHECK_ENVIRONMENT_PREPARATION: environmentSteps.length === 0 ? "" : `\n${environmentSteps.join("\n")}`,
-        DEPLOYMENT_MATRIX: hasDeploymentTask
-            ? "\n    strategy:\n      matrix:\n        check: [root, deployment]"
-            : "",
-        DEPLOYMENT_DOCKER_PREPARATION: hasDeploymentTask && needsDocker
-            ? "\n      - uses: docker/setup-buildx-action@v3\n        if: matrix.check == 'deployment'"
-            : "",
-        ROOT_CHECK_CONDITION: hasDeploymentTask
-            ? "\n        if: matrix.check == 'root'"
-            : "",
-        DEPLOYMENT_CHECK: hasDeploymentTask
-            ? "\n      - run: pnpm run check:deployment\n        if: matrix.check == 'deployment'"
-            : "",
+        DIAGNOSTIC_OWNER_PATHS: declarations
+            .map((declaration) => declaration.owner.path)
+            .join("\n            "),
     };
 }
 export function projectDependabotConfig(policy) {
@@ -152,13 +149,3 @@ function renderDependabotDirectory(ecosystem, directory) {
 function defaultDependabotDirectory(ecosystem) {
     return ecosystem === "docker" ? "/.devcontainer" : "/";
 }
-function renderCiEnvironmentNeedCommand(need) {
-    switch (need.kind) {
-        case "playwright-browser-assets":
-            return renderPlaywrightBrowserInstallCommand(need, { withDeps: true });
-        case "shellcheck-command":
-            return need.nextStep.display;
-        case "rust-toolchain":
-            return need.nextStep.display;
-    }
-}

package/node_modules/@ykdz/template-core/dist/project-projection.d.ts

@@ -17,6 +17,15 @@ export type StructuredIdentitySetPolicy = {
     } | {
         readonly kind: "fields";
         readonly fields: readonly string[];
+    } | {
+        readonly kind: "projection";
+        readonly members: readonly {
+            readonly identity: string;
+            readonly match: Readonly<Record<string, string | number | boolean | null>>;
+        }[];
+        readonly fallback: {
+            readonly fields: readonly string[];
+        };
     };
 };
 export type ProjectProjectionReconciliation = {

package/node_modules/@ykdz/template-core/dist/project-projection.js

@@ -248,6 +248,21 @@ function memberIdentity(member, policy) {
         return scalarIdentity(member);
     if (!isStructuredObject(member))
         return undefined;
+    if (policy.identity.kind === "projection") {
+        const matches = policy.identity.members.filter(({ match }) => Object.entries(match).every(([field, value]) => Object.hasOwn(member, field) &&
+            structuredValuesEqual(member[field], value)));
+        const matchingIdentities = new Set(matches.map(({ identity }) => identity));
+        if (matchingIdentities.size > 1)
+            return undefined;
+        const [matchingIdentity] = matchingIdentities;
+        if (matchingIdentity !== undefined) {
+            return `projection:${JSON.stringify(matchingIdentity)}`;
+        }
+        const fallbackFields = policy.identity.fallback.fields.map((field) => Object.hasOwn(member, field) ? scalarIdentity(member[field]) : undefined);
+        return fallbackFields.every((field) => field !== undefined)
+            ? `fallback:${JSON.stringify(fallbackFields)}`
+            : undefined;
+    }
     const fields = policy.identity.fields.map((field) => Object.hasOwn(member, field) ? scalarIdentity(member[field]) : undefined);
     return fields.every((field) => field !== undefined)
         ? JSON.stringify(fields)
@@ -472,8 +487,52 @@ function assertProjectionContract(projection) {
     }
     return policies;
 }
-function reconciliationPoliciesEqual(left, right) {
-    return JSON.stringify(left) === JSON.stringify(right);
+function reconciliationPoliciesCompatible(left, right) {
+    if (left.path !== right.path ||
+        left.driver !== right.driver ||
+        left.driver !== "structured" ||
+        right.driver !== "structured") {
+        return JSON.stringify(left) === JSON.stringify(right);
+    }
+    const leftIdentitySets = left.identitySets ?? [];
+    const rightIdentitySets = right.identitySets ?? [];
+    if (leftIdentitySets.length !== rightIdentitySets.length)
+        return false;
+    return leftIdentitySets.every((leftPolicy, index) => {
+        const rightPolicy = rightIdentitySets[index];
+        if (rightPolicy === undefined ||
+            leftPolicy.location !== rightPolicy.location ||
+            leftPolicy.identity.kind !== rightPolicy.identity.kind) {
+            return false;
+        }
+        if (leftPolicy.identity.kind !== "projection" ||
+            rightPolicy.identity.kind !== "projection") {
+            return JSON.stringify(leftPolicy) === JSON.stringify(rightPolicy);
+        }
+        return (JSON.stringify(leftPolicy.identity.fallback) ===
+            JSON.stringify(rightPolicy.identity.fallback));
+    });
+}
+function combinedIdentitySets(before, after) {
+    const beforeIdentitySets = before?.driver === "structured" ? (before.identitySets ?? []) : [];
+    const afterIdentitySets = after?.driver === "structured" ? (after.identitySets ?? []) : [];
+    return afterIdentitySets.map((afterPolicy, index) => {
+        const beforePolicy = beforeIdentitySets[index];
+        if (beforePolicy?.identity.kind !== "projection" ||
+            afterPolicy.identity.kind !== "projection") {
+            return afterPolicy;
+        }
+        return {
+            ...afterPolicy,
+            identity: {
+                ...afterPolicy.identity,
+                members: [
+                    ...beforePolicy.identity.members,
+                    ...afterPolicy.identity.members,
+                ],
+            },
+        };
+    });
 }
 function structuredValueAtLocation(root, pathSegments) {
     let value = root;
@@ -521,6 +580,24 @@ function assertIdentitySetPolicies(entry, reconciliation) {
                 policy.identity.fields.some((field) => field.length === 0))) {
             throw new Error(`Project Projection identity-set fields must be unique non-empty names: ${entry.path} ${location}`);
         }
+        if (policy.identity.kind === "projection") {
+            const fallbackFields = policy.identity.fallback.fields;
+            if (fallbackFields.length === 0 ||
+                new Set(fallbackFields).size !== fallbackFields.length ||
+                fallbackFields.some((field) => field.length === 0)) {
+                throw new Error(`Project Projection identity-set projection fallback fields must be unique non-empty names: ${entry.path} ${location}`);
+            }
+            const memberIdentities = policy.identity.members.map((member) => member.identity);
+            if (memberIdentities.some((identity) => identity.length === 0) ||
+                new Set(memberIdentities).size !== memberIdentities.length ||
+                policy.identity.members.some((member) => Object.keys(member.match).length === 0 ||
+                    Object.values(member.match).some((value) => value !== null &&
+                        typeof value !== "string" &&
+                        typeof value !== "number" &&
+                        typeof value !== "boolean"))) {
+                throw new Error(`Project Projection identity-set projection members require unique non-empty identities and non-empty scalar matches: ${entry.path} ${location}`);
+            }
+        }
         const value = structuredValueAtLocation(parsed.value, pathSegments);
         if (!Array.isArray(value)) {
             throw new Error(`Project Projection identity-set location must reference an array: ${entry.path} ${location}`);
@@ -547,7 +624,7 @@ export async function reconcileProjectProjections(options) {
         }
         if (afterPolicy !== undefined &&
             beforePolicy !== undefined &&
-            !reconciliationPoliciesEqual(beforePolicy, afterPolicy)) {
+            !reconciliationPoliciesCompatible(beforePolicy, afterPolicy)) {
             throw new Error(`Project Projection reconciliation policy changed for ${projectionPath}`);
         }
     }
@@ -561,7 +638,9 @@ export async function reconcileProjectProjections(options) {
     for (const projectionPath of deltaPaths) {
         const before = beforeByPath.get(projectionPath);
         const after = afterByPath.get(projectionPath);
-        const policy = afterPolicies.get(projectionPath) ?? beforePolicies.get(projectionPath);
+        const beforePolicy = beforePolicies.get(projectionPath);
+        const afterPolicy = afterPolicies.get(projectionPath);
+        const policy = afterPolicy ?? beforePolicy;
         const driver = policy.driver;
         const current = await options.readCurrent(projectionPath);
         if (entriesEqual(current, after))
@@ -622,7 +701,7 @@ export async function reconcileProjectProjections(options) {
                 before,
                 current,
                 after,
-                identitySets: policy.identitySets ?? [],
+                identitySets: combinedIdentitySets(beforePolicy, afterPolicy),
             })
             : undefined;
         const text = driver === "text"

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

@@ -66,6 +66,7 @@ export type WriteTextFromFragmentsOperation = {
         from: string;
         source: TemplateSourceHandle;
     }[];
+    validation?: "development-container-dockerfile" | undefined;
     overwrite?: boolean;
     provenance?: RenderOperationProvenance;
 };

package/node_modules/@ykdz/template-core/dist/renderer.js

@@ -176,16 +176,55 @@ async function renderWriteText(operation, options) {
     await mkdir(path.dirname(to), { recursive: true });
     await writeGeneratedFile(to, operation.text);
 }
-async function renderWriteTextFromFragments(operation, options) {
-    const toPath = expandOperationPath(operation.to, options);
-    const to = resolveContainedPath(options.targetRoot, toPath);
-    const texts = await Promise.all(operation.fragments.map(async (fragment) => {
+async function loadTextFragments(operation, options) {
+    return Promise.all(operation.fragments.map(async (fragment) => {
         const fromPath = expandTemplatePath(fragment.from, options.variables ?? {});
         const from = resolveTemplateSource(fragment.source, fromPath);
-        return readFile(from, "utf8");
+        return { from: fromPath, text: await readFile(from, "utf8") };
     }));
+}
+async function validateDevelopmentContainerDockerfileOperation(operation, fragments) {
+    if (operation.validation !== "development-container-dockerfile") {
+        return;
+    }
+    const [baseFragment, ...optionalFragments] = fragments;
+    if (baseFragment === undefined) {
+        throw new Error("Development Container Dockerfile requires a base fragment.");
+    }
+    const { validateDevelopmentContainerDockerfileFragments } = await import("./development-container-tool-layer.js");
+    validateDevelopmentContainerDockerfileFragments({
+        baseFragment: {
+            identity: baseFragment.from,
+            from: baseFragment.from,
+            text: baseFragment.text,
+        },
+        fragments: optionalFragments.map((fragment) => ({
+            identity: fragment.from,
+            from: fragment.from,
+            text: fragment.text,
+        })),
+    });
+}
+async function preflightDevelopmentContainerDockerfiles(options) {
+    const loadedFragments = new Map();
+    for (const operation of options.operations) {
+        if (operation.kind !== "writeTextFromFragments" ||
+            operation.validation !== "development-container-dockerfile") {
+            continue;
+        }
+        const fragments = await loadTextFragments(operation, options);
+        await validateDevelopmentContainerDockerfileOperation(operation, fragments);
+        loadedFragments.set(operation, fragments);
+    }
+    return loadedFragments;
+}
+async function renderWriteTextFromFragments(operation, options, preloadedFragments) {
+    const toPath = expandOperationPath(operation.to, options);
+    const to = resolveContainedPath(options.targetRoot, toPath);
+    const fragments = preloadedFragments ?? (await loadTextFragments(operation, options));
+    await validateDevelopmentContainerDockerfileOperation(operation, fragments);
     await mkdir(path.dirname(to), { recursive: true });
-    await writeGeneratedFile(to, texts.map((text) => text.trimEnd()).join("\n\n") + "\n", operation.overwrite ?? false);
+    await writeGeneratedFile(to, fragments.map(({ text }) => text.trimEnd()).join("\n\n") + "\n", operation.overwrite ?? false);
 }
 function replaceTextTemplateVariables(sourceText, replacements) {
     const used = new Set();
@@ -341,6 +380,7 @@ async function writeGeneratedFile(to, text, overwrite = false) {
     }
 }
 export async function renderProject(options) {
+    const preloadedDevelopmentContainerDockerfiles = await preflightDevelopmentContainerDockerfiles(options);
     for (const operation of options.operations) {
         if (operation.kind === "copyFile") {
             await renderCopyFile(operation, options);
@@ -363,7 +403,7 @@ export async function renderProject(options) {
             continue;
         }
         if (operation.kind === "writeTextFromFragments") {
-            await renderWriteTextFromFragments(operation, options);
+            await renderWriteTextFromFragments(operation, options, preloadedDevelopmentContainerDockerfiles.get(operation));
             continue;
         }
         if (operation.kind === "writeTextTemplate") {

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

@@ -1,3 +1,4 @@
+import type { ProjectBlueprintV2 } from "./project-blueprint-v2.ts";
 import { type RenderOperation } from "./renderer.ts";
 export type TemplateBoundaryViolation = {
     readonly preset: string;
@@ -34,6 +35,19 @@ export type CheckTemplateSourceBoundaryOptions = {
     readonly projections: readonly TemplateBoundaryCheckProjection[];
     readonly templateSourceContexts?: readonly TemplateSourceContext[];
     readonly manifestReferencedSourceFiles?: readonly string[];
+    /** Complete Built-in plans whose Foundation workflow is a protected output. */
+    readonly protectedWorkflowPlans?: readonly {
+        readonly name: string;
+        readonly sourceFilePath: string;
+        readonly definitionName?: string;
+        readonly planningContribution?: string;
+        readonly generatedPath: ".github/workflows/check.yml";
+        /** The original Blueprint, before Foundation composes workflow facts. */
+        readonly blueprint: ProjectBlueprintV2;
+        /** Raw Package Contribution declarations, not the composed plan field. */
+        readonly diagnosticArtifactDeclarations: readonly unknown[];
+        readonly operations: readonly RenderOperation[];
+    }[];
 };
 /**
  * Reads each registered Template Source context before any plan is inspected.
@@ -41,4 +55,4 @@ export type CheckTemplateSourceBoundaryOptions = {
  */
 export declare function checkTemplateSourceContexts(contexts: readonly Omit<TemplateSourceContext, "checkedFiles">[]): Promise<readonly TemplateSourceContext[]>;
 export declare function isProtectedGeneratedPath(generatedPath: string): boolean;
-export declare function checkTemplateSourceBoundary({ projections, templateSourceContexts, manifestReferencedSourceFiles, }: CheckTemplateSourceBoundaryOptions): Promise<TemplateBoundaryCheckResult>;
+export declare function checkTemplateSourceBoundary({ projections, templateSourceContexts, manifestReferencedSourceFiles, protectedWorkflowPlans, }: CheckTemplateSourceBoundaryOptions): Promise<TemplateBoundaryCheckResult>;