@ykdz/template 0.0.2 → 0.0.4

package/dist/{renderer.d.ts → src/renderer.d.ts}

@@ -21,6 +21,21 @@ export type WriteTextOperation = {
     to: string;
     text: string;
 };
+export type WriteTextFromFragmentsOperation = {
+    kind: "writeTextFromFragments";
+    to: string;
+    fragments: readonly {
+        from: string;
+        sourceRoot?: string;
+    }[];
+};
+export type WriteTextTemplateOperation = {
+    kind: "writeTextTemplate";
+    from: string;
+    to: string;
+    sourceRoot?: string;
+    replacements: Record<string, string>;
+};
 export type SetExecutableOperation = {
     kind: "setExecutable";
     path: string;
@@ -32,7 +47,7 @@ export type ReplaceAnchorsOperation = {
     language: "typescript";
     replacements: Record<string, string>;
 };
-export type RenderOperation = CopyFileOperation | WriteJsonOperation | MergeJsonOperation | WriteTextOperation | SetExecutableOperation | ReplaceAnchorsOperation;
+export type RenderOperation = CopyFileOperation | WriteJsonOperation | MergeJsonOperation | WriteTextOperation | WriteTextFromFragmentsOperation | WriteTextTemplateOperation | SetExecutableOperation | ReplaceAnchorsOperation;
 export type RenderProjectOptions = {
     sourceRoot: string;
     sourceRoots?: Record<string, string>;
@@ -43,4 +58,3 @@ export type RenderProjectOptions = {
 export declare function renderProject(options: RenderProjectOptions): Promise<void>;
 export declare function renderNewProject(options: RenderProjectOptions): Promise<void>;
 export {};
-//# sourceMappingURL=renderer.d.ts.map

package/dist/{renderer.js → src/renderer.js}

@@ -1,5 +1,5 @@
 import { constants } from "node:fs";
-import { chmod, copyFile, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
+import { chmod, copyFile, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, stat, writeFile, } from "node:fs/promises";
 import path from "node:path";
 function expandTemplatePath(templatePath, variables) {
     return templatePath.replaceAll(/\{\{([A-Za-z][A-Za-z0-9_]*)\}\}/g, (_, name) => {
@@ -19,7 +19,8 @@ function resolveContainedPath(root, relativePath) {
     }
     const resolvedRoot = path.resolve(root);
     const resolvedPath = path.resolve(resolvedRoot, relativePath);
-    const insideRoot = resolvedPath === resolvedRoot || resolvedPath.startsWith(`${resolvedRoot}${path.sep}`);
+    const insideRoot = resolvedPath === resolvedRoot ||
+        resolvedPath.startsWith(`${resolvedRoot}${path.sep}`);
     if (!insideRoot) {
         throw new Error(`Renderer path escapes its root: ${relativePath}`);
     }
@@ -47,7 +48,7 @@ function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isScalarJsonValue(value) {
-    return value === null || ["boolean", "number", "string"].includes(typeof value);
+    return (value === null || ["boolean", "number", "string"].includes(typeof value));
 }
 function serializeJsonValue(value, indentation, pathSegments, multilineArrays, rootKeyOrder) {
     if (Array.isArray(value)) {
@@ -88,7 +89,13 @@ const packageJsonRootKeyOrder = [
     "peerDependencies",
     "optionalDependencies",
     "engines",
-    "packageManager"
+    "packageManager",
+];
+const devcontainerJsonRootKeyOrder = [
+    "name",
+    "build",
+    "image",
+    "customizations",
 ];
 function compareJsonKeys(left, right, pathSegments, rootKeyOrder) {
     if (pathSegments.length === 0 && rootKeyOrder) {
@@ -101,10 +108,13 @@ function compareJsonKeys(left, right, pathSegments, rootKeyOrder) {
     return left.localeCompare(right);
 }
 function rootKeyOrderForPath(toPath) {
-    if (path.basename(toPath) !== "package.json") {
-        return undefined;
+    if (path.basename(toPath) === "package.json") {
+        return new Map(packageJsonRootKeyOrder.map((key, index) => [key, index]));
+    }
+    if (toPath.split(path.sep).join("/") === ".devcontainer/devcontainer.json") {
+        return new Map(devcontainerJsonRootKeyOrder.map((key, index) => [key, index]));
     }
-    return new Map(packageJsonRootKeyOrder.map((key, index) => [key, index]));
+    return undefined;
 }
 function serializeJson(value, multilineArrays = [], rootKeyOrder) {
     return `${serializeJsonValue(value, 0, [], new Set(multilineArrays), rootKeyOrder)}\n`;
@@ -151,7 +161,7 @@ const foundationTextFiles = new Set([
     "README",
     "README.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
 ]);
 function assertFoundationTextPath(relativePath) {
     const normalizedPath = relativePath.split(path.sep).join("/");
@@ -162,11 +172,20 @@ function assertFoundationTextPath(relativePath) {
     if (isRootLevel && relativePath.endsWith(".md")) {
         return;
     }
-    if (isRootLevel && (relativePath.endsWith(".yaml") || relativePath.endsWith(".yml"))) {
+    if (isRootLevel &&
+        (relativePath.endsWith(".yaml") || relativePath.endsWith(".yml"))) {
         return;
     }
     if (isRootLevel &&
-        ["Cargo.toml", "Cargo.lock", "rustfmt.toml"].includes(normalizedPath)) {
+        [
+            "Cargo.toml",
+            "Cargo.lock",
+            "rustfmt.toml",
+            "rust-toolchain.toml",
+        ].includes(normalizedPath)) {
+        return;
+    }
+    if (/^packages\/[A-Za-z0-9._-]+\/(?:Cargo\.toml|Cargo\.lock|rustfmt\.toml)$/.test(normalizedPath)) {
         return;
     }
     if (/^\.github\/workflows\/[A-Za-z0-9._-]+\.ya?ml$/.test(normalizedPath)) {
@@ -175,6 +194,9 @@ function assertFoundationTextPath(relativePath) {
     if (/^\.github\/dependabot\.ya?ml$/.test(normalizedPath)) {
         return;
     }
+    if (normalizedPath === ".devcontainer/Dockerfile") {
+        return;
+    }
     throw new Error(`Text output is limited to foundation files: ${relativePath}`);
 }
 async function renderWriteText(operation, options) {
@@ -184,6 +206,56 @@ 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);
+    assertFoundationTextPath(toPath);
+    const to = resolveContainedPath(options.targetRoot, toPath);
+    const texts = await Promise.all(operation.fragments.map(async (fragment) => {
+        const sourceRoot = fragment.sourceRoot === undefined
+            ? options.sourceRoot
+            : options.sourceRoots?.[fragment.sourceRoot];
+        if (sourceRoot === undefined) {
+            throw new Error(`Unknown renderer source root: ${fragment.sourceRoot}`);
+        }
+        const fromPath = expandTemplatePath(fragment.from, options.variables ?? {});
+        const from = resolveContainedPath(sourceRoot, fromPath);
+        return readFile(from, "utf8");
+    }));
+    await mkdir(path.dirname(to), { recursive: true });
+    await writeGeneratedFile(to, texts.map((text) => text.trimEnd()).join("\n\n") + "\n");
+}
+function replaceTextTemplateVariables(sourceText, replacements) {
+    const used = new Set();
+    const rendered = sourceText.replaceAll(/\{\{([A-Za-z][A-Za-z0-9_]*)\}\}/g, (_placeholder, name) => {
+        const replacement = replacements[name];
+        if (replacement === undefined) {
+            throw new Error(`Missing text template variable: ${name}`);
+        }
+        used.add(name);
+        return replacement;
+    });
+    for (const name of Object.keys(replacements)) {
+        if (!used.has(name)) {
+            throw new Error(`Unused text template variable: ${name}`);
+        }
+    }
+    return rendered;
+}
+async function renderWriteTextTemplate(operation, options) {
+    const sourceRoot = operation.sourceRoot === undefined
+        ? options.sourceRoot
+        : options.sourceRoots?.[operation.sourceRoot];
+    if (sourceRoot === undefined) {
+        throw new Error(`Unknown renderer source root: ${operation.sourceRoot}`);
+    }
+    const toPath = expandOperationPath(operation.to, options);
+    assertFoundationTextPath(toPath);
+    const from = resolveContainedPath(sourceRoot, expandTemplatePath(operation.from, options.variables ?? {}));
+    const to = resolveContainedPath(options.targetRoot, toPath);
+    const sourceText = await readFile(from, "utf8");
+    await mkdir(path.dirname(to), { recursive: true });
+    await writeGeneratedFile(to, replaceTextTemplateVariables(sourceText, operation.replacements));
+}
 async function renderSetExecutable(operation, options) {
     const filePath = resolveContainedPath(options.targetRoot, expandOperationPath(operation.path, options));
     const currentMode = (await stat(filePath)).mode;
@@ -224,7 +296,7 @@ async function findTypeScriptAnchorRanges(sourceText) {
             anchors.push({
                 name,
                 start: comment.pos,
-                end: comment.end
+                end: comment.end,
             });
         }
         ts.forEachChild(node, collectNodeAnchors);
@@ -296,7 +368,10 @@ async function copyGeneratedFile(from, to) {
 }
 async function writeGeneratedFile(to, text, overwrite = false) {
     try {
-        await writeFile(to, text, { encoding: "utf8", flag: overwrite ? "w" : "wx" });
+        await writeFile(to, text, {
+            encoding: "utf8",
+            flag: overwrite ? "w" : "wx",
+        });
     }
     catch (error) {
         if (isNodeError(error) && error.code === "EEXIST") {
@@ -323,6 +398,14 @@ export async function renderProject(options) {
             await renderWriteText(operation, options);
             continue;
         }
+        if (operation.kind === "writeTextFromFragments") {
+            await renderWriteTextFromFragments(operation, options);
+            continue;
+        }
+        if (operation.kind === "writeTextTemplate") {
+            await renderWriteTextTemplate(operation, options);
+            continue;
+        }
         if (operation.kind === "setExecutable") {
             await renderSetExecutable(operation, options);
             continue;

package/dist/src/runtime-paths.d.ts

@@ -0,0 +1 @@
+export declare function packageTemplateRoot(moduleDir: string, ...segments: string[]): string;

package/dist/src/runtime-paths.js

@@ -0,0 +1,11 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+export function packageTemplateRoot(moduleDir, ...segments) {
+    const candidates = [
+        path.join(moduleDir, "..", "..", "templates", ...segments),
+        path.join(moduleDir, "..", "templates", ...segments),
+        path.join(moduleDir, "..", "..", "..", "templates", ...segments),
+    ];
+    const found = candidates.find((candidate) => existsSync(candidate));
+    return found ?? candidates[0];
+}

package/dist/src/template-boundary-check.d.ts

@@ -0,0 +1,34 @@
+import type { PresetProjectionPlan } from "./preset-projection.js";
+import type { RenderOperation } from "./renderer.js";
+export type TemplateBoundaryDebt = {
+    readonly preset: string;
+    readonly generatedPath: string;
+    readonly owningFunction: string;
+    readonly reason: string;
+};
+export type TemplateBoundaryViolation = {
+    readonly preset: string;
+    readonly generatedPath: string;
+    readonly owningFunction: string;
+    readonly operationKind: RenderOperation["kind"];
+    readonly sourceFilePath: string;
+    readonly allowlistReason?: string;
+};
+export type TemplateBoundaryCheckProjection = {
+    readonly name: string;
+    readonly sourceFilePath: string;
+    readonly plan: PresetProjectionPlan;
+};
+export type TemplateBoundaryCheckResult = {
+    readonly ok: boolean;
+    readonly violations: readonly TemplateBoundaryViolation[];
+    readonly allowlistedDebt: readonly TemplateBoundaryViolation[];
+    readonly unusedAllowlistEntries: readonly TemplateBoundaryDebt[];
+};
+export type CheckTemplateSourceBoundaryOptions = {
+    readonly projections: readonly TemplateBoundaryCheckProjection[];
+    readonly allowlist?: readonly TemplateBoundaryDebt[];
+};
+export declare const templateBoundaryDebtAllowlist: readonly TemplateBoundaryDebt[];
+export declare function isProtectedGeneratedPath(generatedPath: string): boolean;
+export declare function checkTemplateSourceBoundary({ projections, allowlist, }: CheckTemplateSourceBoundaryOptions): Promise<TemplateBoundaryCheckResult>;