@ykdz/template 0.0.3 → 0.0.5

package/dist/src/package-linking.d.ts

@@ -0,0 +1,55 @@
+export type PackageRole = "runtime-service" | "shared-library";
+export type PackageSourcePreset = "hono-api" | "ts-lib" | "vue-app";
+export type PackageDefinition = {
+    readonly name: string;
+    readonly path: string;
+    readonly role?: PackageRole;
+    readonly sourcePreset?: PackageSourcePreset;
+};
+export type PackageLinkIntent = {
+    readonly consumerPackagePath: string;
+    readonly providerPackagePath: string;
+};
+export type JitSourcePackageExposure = {
+    readonly kind: "jit-source";
+    readonly entrypoint: string;
+    readonly packageLocalImportPattern: string;
+    readonly packageLocalImportTarget: string;
+};
+export type CompiledPackageExposure = {
+    readonly kind: "compiled";
+    readonly entrypoint: string;
+    readonly sourceTypes: string;
+    readonly packageLocalImportPattern: string;
+    readonly packageLocalImportRuntimeTarget: string;
+    readonly packageLocalImportTypesTarget: string;
+};
+export type PackageExposure = CompiledPackageExposure | JitSourcePackageExposure;
+export type PackageLinkPlan = {
+    readonly exposuresByPackagePath: ReadonlyMap<string, PackageExposure>;
+    readonly manifestDependenciesByPackagePath: ReadonlyMap<string, Readonly<Record<string, "workspace:*">>>;
+    readonly turboTasks: TurboTaskGraph;
+};
+export type PackageManifestExposureFields = {
+    readonly exports: Record<string, unknown>;
+    readonly imports: Record<string, unknown>;
+    readonly types?: string;
+};
+export type PackageLinkBoundaryDirection = "consumer" | "provider";
+export type TurboTaskDefinition = {
+    readonly dependsOn?: readonly string[];
+    readonly outputs?: readonly string[];
+    readonly cache?: boolean;
+};
+export type TurboTaskGraph = Readonly<Record<string, TurboTaskDefinition>>;
+export type PackageTurboTaskOptions = {
+    readonly dependencyBuildsRequired: boolean;
+};
+export declare function derivePackageExposure(definition: PackageDefinition): PackageExposure;
+export declare function assertTypeScriptPackageBoundaryForLinkIntent(definition: PackageDefinition, direction: PackageLinkBoundaryDirection): asserts definition is PackageDefinition & {
+    readonly role: PackageRole;
+    readonly sourcePreset: PackageSourcePreset;
+};
+export declare function planPackageLinks(definitions: readonly PackageDefinition[], intents?: readonly PackageLinkIntent[]): PackageLinkPlan;
+export declare function packageTurboTasks({ dependencyBuildsRequired, }: PackageTurboTaskOptions): TurboTaskGraph;
+export declare function packageManifestExposureFields(exposure: PackageExposure): PackageManifestExposureFields;

package/dist/src/package-linking.js

@@ -0,0 +1,116 @@
+export function derivePackageExposure(definition) {
+    if (definition.role === "shared-library" &&
+        definition.sourcePreset === "ts-lib") {
+        return {
+            kind: "jit-source",
+            entrypoint: "./src/index.ts",
+            packageLocalImportPattern: "#/*",
+            packageLocalImportTarget: "./src/*.ts",
+        };
+    }
+    if (definition.role === "runtime-service" &&
+        definition.sourcePreset === "hono-api") {
+        return {
+            kind: "compiled",
+            entrypoint: "./dist/index.js",
+            sourceTypes: "./src/index.ts",
+            packageLocalImportPattern: "#/*",
+            packageLocalImportRuntimeTarget: "./dist/*.js",
+            packageLocalImportTypesTarget: "./src/*.ts",
+        };
+    }
+    throw new Error(`Unsupported Package Exposure for ${definition.name} at ${definition.path}`);
+}
+export function assertTypeScriptPackageBoundaryForLinkIntent(definition, direction) {
+    if (definition.role !== undefined && definition.sourcePreset !== undefined) {
+        return;
+    }
+    const relationship = direction === "consumer" ? "from native package" : "to native package";
+    throw new Error(`Package Link Intent ${relationship} ${definition.path} is unsupported in V1 TypeScript-only Project Linking`);
+}
+export function planPackageLinks(definitions, intents = []) {
+    const definitionsByPath = new Map(definitions.map((definition) => [definition.path, definition]));
+    const manifestDependenciesByPackagePath = new Map();
+    for (const intent of intents) {
+        const consumer = definitionsByPath.get(intent.consumerPackagePath);
+        const provider = definitionsByPath.get(intent.providerPackagePath);
+        if (consumer !== undefined) {
+            assertTypeScriptPackageBoundaryForLinkIntent(consumer, "consumer");
+        }
+        if (provider === undefined) {
+            throw new Error(`Package Link Intent references unknown provider package at ${intent.providerPackagePath}`);
+        }
+        assertTypeScriptPackageBoundaryForLinkIntent(provider, "provider");
+    }
+    const exposuresByPackagePath = new Map(definitions.map((definition) => [
+        definition.path,
+        derivePackageExposure(definition),
+    ]));
+    let dependencyBuildsRequired = false;
+    for (const intent of intents) {
+        const provider = definitionsByPath.get(intent.providerPackagePath);
+        if (provider === undefined) {
+            throw new Error(`Package Link Intent references unknown provider package at ${intent.providerPackagePath}`);
+        }
+        if (exposuresByPackagePath.get(provider.path)?.kind === "compiled") {
+            dependencyBuildsRequired = true;
+        }
+        const dependencies = manifestDependenciesByPackagePath.get(intent.consumerPackagePath) ?? {};
+        dependencies[provider.name] = "workspace:*";
+        manifestDependenciesByPackagePath.set(intent.consumerPackagePath, dependencies);
+    }
+    return {
+        exposuresByPackagePath,
+        manifestDependenciesByPackagePath,
+        turboTasks: packageTurboTasks({ dependencyBuildsRequired }),
+    };
+}
+export function packageTurboTasks({ dependencyBuildsRequired, }) {
+    return {
+        typecheck: { dependsOn: ["^typecheck"] },
+        build: dependencyBuildsRequired
+            ? { dependsOn: ["^build"], outputs: ["dist/**"] }
+            : { outputs: ["dist/**"] },
+        test: { dependsOn: ["^typecheck"] },
+        "test:e2e": {
+            dependsOn: dependencyBuildsRequired ? ["build", "^build"] : ["build"],
+        },
+        check: { dependsOn: ["typecheck", "build", "test", "test:e2e"] },
+        fix: { cache: false },
+    };
+}
+export function packageManifestExposureFields(exposure) {
+    switch (exposure.kind) {
+        case "jit-source":
+            return {
+                imports: {
+                    [exposure.packageLocalImportPattern]: {
+                        default: exposure.packageLocalImportTarget,
+                        types: exposure.packageLocalImportTarget,
+                    },
+                },
+                exports: {
+                    ".": {
+                        default: exposure.entrypoint,
+                        types: exposure.entrypoint,
+                    },
+                },
+            };
+        case "compiled":
+            return {
+                types: exposure.sourceTypes,
+                imports: {
+                    [exposure.packageLocalImportPattern]: {
+                        default: exposure.packageLocalImportRuntimeTarget,
+                        types: exposure.packageLocalImportTypesTarget,
+                    },
+                },
+                exports: {
+                    ".": {
+                        default: exposure.entrypoint,
+                        types: exposure.sourceTypes,
+                    },
+                },
+            };
+    }
+}

package/dist/src/preset-projection.d.ts

@@ -2,6 +2,7 @@ import type { BuiltInPreset, ProjectBlueprint } from "./declarations.js";
 import type { GenerationContext } from "./generation-context.js";
 import { type CheckPlan, type FixPlan } from "./module-graph.js";
 import { type NextStepInstruction } from "./next-step-instructions.js";
+import type { PackageRole, PackageSourcePreset } from "./package-linking.js";
 import type { DependencyMaintenancePolicy } from "./project-github.js";
 import type { RenderOperation } from "./renderer.js";
 export type PresetPackageAdditionOptions = {
@@ -9,12 +10,14 @@ export type PresetPackageAdditionOptions = {
     readonly blueprint: ProjectBlueprint;
     readonly packageLeafName: string;
     readonly packageName: string;
+    readonly packagePath: string;
     readonly nodeVersion: string;
 };
 export type PresetPackageAdditionPlan = {
     readonly packagePath: string;
     readonly workspacePackageGlob: string;
-    readonly rootTsconfigReferences: readonly string[];
+    readonly packageRole: PackageRole;
+    readonly packageSourcePreset: PackageSourcePreset;
     readonly sourceRoot: string;
     readonly sourceRoots?: Record<string, string>;
     readonly operations: readonly RenderOperation[];
@@ -63,4 +66,3 @@ export declare function planNextStepInstructionsForProjection(options: {
     readonly targetDir: string;
     readonly plan: PresetProjectionPlan;
 }): readonly NextStepInstruction[];
-//# sourceMappingURL=preset-projection.d.ts.map

package/dist/src/project-github.d.ts

@@ -12,9 +12,11 @@ export type PnpmTaskLayer = {
     readonly installCommand: "pnpm install";
     readonly checkCommand: "pnpm run check";
 };
-export type DependencyEcosystem = "npm" | "cargo" | "github-actions";
+export type DependencyEcosystem = "npm" | "cargo" | "github-actions" | "docker" | "rust-toolchain";
+export type DependabotDirectory = `/${string}`;
 export type DependencyMaintenancePolicy = {
     readonly ecosystems: DependencyEcosystem[];
+    readonly directories?: Partial<Record<DependencyEcosystem, DependabotDirectory>>;
     readonly interval: "weekly";
 };
 type ProjectCheckWorkflowOptions = {
@@ -26,4 +28,3 @@ type ProjectCheckWorkflowOptions = {
 export declare function projectCheckWorkflow(options: ProjectCheckWorkflowOptions): string;
 export declare function projectDependabotConfig(policy: DependencyMaintenancePolicy): string;
 export {};
-//# sourceMappingURL=project-github.d.ts.map

package/dist/src/project-github.js

@@ -44,16 +44,34 @@ export function projectCheckWorkflow(options) {
 export function projectDependabotConfig(policy) {
     return [
         "version: 2",
+        "",
         "updates:",
-        ...policy.ecosystems.flatMap((ecosystem) => [
-            `  - package-ecosystem: ${ecosystem}`,
-            "    directory: /",
-            "    schedule:",
-            `      interval: ${policy.interval}`,
-        ]),
+        ...policy.ecosystems.flatMap((ecosystem) => renderDependabotUpdate(ecosystem, policy.directories?.[ecosystem] ??
+            defaultDependabotDirectory(ecosystem), policy.interval)),
         "",
     ].join("\n");
 }
+function renderDependabotUpdate(ecosystem, directory, interval) {
+    const lines = [
+        `  - package-ecosystem: ${ecosystem}`,
+        `    directory: ${renderDependabotDirectory(ecosystem, directory)}`,
+        "    schedule:",
+        `      interval: ${interval}`,
+    ];
+    if (ecosystem === "npm") {
+        lines.push("    ignore:", '      - dependency-name: "@types/node"', "        update-types:", "          - version-update:semver-major");
+    }
+    if (ecosystem === "docker") {
+        lines.push("    ignore:", "      - dependency-name: mcr.microsoft.com/devcontainers/typescript-node", "        update-types:", "          - version-update:semver-major");
+    }
+    return lines;
+}
+function renderDependabotDirectory(ecosystem, directory) {
+    return ecosystem === "cargo" ? JSON.stringify(directory) : directory;
+}
+function defaultDependabotDirectory(ecosystem) {
+    return ecosystem === "docker" ? "/.devcontainer" : "/";
+}
 function renderCiEnvironmentNeedCommand(need) {
     if (need.kind === "playwright-browser-assets" &&
         need.owner.path === "apps/web") {

package/dist/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/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)) {
@@ -81,6 +82,7 @@ const packageJsonRootKeyOrder = [
     "files",
     "type",
     "types",
+    "imports",
     "exports",
     "scripts",
     "dependencies",
@@ -88,7 +90,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 +109,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 +162,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 +173,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 +195,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 +207,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 +297,7 @@ async function findTypeScriptAnchorRanges(sourceText) {
             anchors.push({
                 name,
                 start: comment.pos,
-                end: comment.end
+                end: comment.end,
             });
         }
         ts.forEachChild(node, collectNodeAnchors);
@@ -296,7 +369,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 +399,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

@@ -1,2 +1 @@
 export declare function packageTemplateRoot(moduleDir: string, ...segments: string[]): string;
-//# sourceMappingURL=runtime-paths.d.ts.map

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>;