@ykdz/template 0.0.41 → 0.1.0-experimental.0

package/node_modules/@ykdz/template-workspace/dist/reference-package.js

@@ -0,0 +1,521 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isDeepStrictEqual } from "node:util";
+import { createTemplateSourceHandle, resolveTemplateSource, } from "@ykdz/template-core/renderer";
+import { prepareNativeContentArtifact, } from "@ykdz/template-workspace-authoring/content-artifact";
+import { mapPackageNamesInJson } from "@ykdz/template-workspace-authoring/package-name-projection";
+import { resourceIgnoreSnapshot } from "@ykdz/template-workspace-authoring/resource-ignore-snapshot";
+import { mapTypeScriptModuleSpecifiers } from "@ykdz/template-workspace-authoring/typescript-module-specifiers";
+import ignore, {} from "ignore";
+import { parse } from "jsonc-parser";
+const dependencyPurposeOrder = [
+    "target",
+    "template-execution",
+    "template-build",
+];
+function normalizeDependencyUses(manifest, templateDependencies) {
+    const uses = new Map();
+    for (const field of [
+        "dependencies",
+        "devDependencies",
+        "optionalDependencies",
+        "peerDependencies",
+    ]) {
+        const dependencies = manifest[field];
+        if (typeof dependencies !== "object" || dependencies === null)
+            continue;
+        for (const name of Object.keys(dependencies)) {
+            if (!uses.has(name))
+                uses.set(name, new Set(["target"]));
+        }
+    }
+    const declared = new Set();
+    const seen = new Set();
+    for (const dependency of templateDependencies) {
+        if (!dependencyPurposeOrder.includes(dependency.purpose) ||
+            typeof dependency.name !== "string" ||
+            dependency.name.length === 0) {
+            throw new Error(`模板依赖用途无效：${String(dependency.name)} (${String(dependency.purpose)})`);
+        }
+        const purposes = uses.get(dependency.name);
+        if (purposes === undefined) {
+            throw new Error(`模板依赖未在原生清单声明：${dependency.name} (${dependency.purpose})`);
+        }
+        const identity = `${dependency.name}\u0000${dependency.purpose}`;
+        if (seen.has(identity)) {
+            throw new Error(`模板依赖用途重复：${dependency.name} (${dependency.purpose})`);
+        }
+        seen.add(identity);
+        if (!declared.has(dependency.name)) {
+            purposes.clear();
+            declared.add(dependency.name);
+        }
+        purposes.add(dependency.purpose);
+    }
+    return Object.freeze([...uses].map(([name, purposes]) => Object.freeze({
+        name,
+        purposes: Object.freeze(dependencyPurposeOrder.filter((purpose) => purposes.has(purpose))),
+    })));
+}
+function contextual(value, options) {
+    return typeof value === "function"
+        ? value(options)
+        : value;
+}
+/** 原生包声明是生成事实源，描述只补充资源范围与局部差异。 */
+export function defineReferencePackage(options) {
+    const manifest = JSON.parse(readFileSync(fileURLToPath(options.resolve(`${options.packageName}/reference`)), "utf8"));
+    const normalizeOwnedResource = (resource) => {
+        const normalized = path.posix.normalize(resource);
+        if (resource.length === 0 ||
+            path.posix.isAbsolute(resource) ||
+            normalized === ".." ||
+            normalized.startsWith("../") ||
+            /[!*?{}[\]]/u.test(resource)) {
+            throw new Error(`参考包 ${options.packageName} prepare 阶段资源声明无效：${resource}`);
+        }
+        return normalized;
+    };
+    const normalizedResources = options.resources.map(normalizeOwnedResource);
+    const resourceRoot = path.resolve(fileURLToPath(options.resourceRoot));
+    const templateResources = (options.template.resources ?? []).map(normalizeOwnedResource);
+    const executionDataPaths = (options.template.executionData ?? []).map(normalizeOwnedResource);
+    const templateDependencies = Object.freeze(options.template.dependencies.map((dependency) => Object.freeze({ ...dependency })));
+    let normalizedDependencyUses;
+    const dependencyUses = () => {
+        normalizedDependencyUses ??= normalizeDependencyUses(manifest, templateDependencies);
+        return normalizedDependencyUses;
+    };
+    const targetDependencyNames = (input) => {
+        const dependencies = dependencyUses()
+            .filter((dependency) => dependency.purposes.includes("target"))
+            .map((dependency) => dependency.name);
+        const selected = options.targetDependencies?.({ ...input, dependencies }) ?? dependencies;
+        for (const name of selected)
+            if (!dependencies.includes(name))
+                throw new Error(`参考包 ${options.packageName} 选择了未声明的目标依赖：${name}`);
+        return selected;
+    };
+    const defaultPath = options.defaultPath ?? `packages/${options.defaultLeafName}`;
+    const inDeclaredResources = (file) => {
+        const normalized = path.posix.normalize(file);
+        return normalizedResources.some((resource) => resource === "." ||
+            normalized === resource ||
+            normalized.startsWith(`${resource}/`));
+    };
+    const isTemplateResource = (file) => {
+        const normalized = path.posix.normalize(file);
+        return templateResources.some((resource) => normalized === resource || normalized.startsWith(`${resource}/`));
+    };
+    const resolveOwnedResource = (file) => {
+        const normalized = normalizeOwnedResource(file);
+        if (!inDeclaredResources(normalized)) {
+            throw new Error(`参考包 ${options.packageName} prepare 阶段资源超出声明范围：${file}`);
+        }
+        const resolved = path.resolve(resourceRoot, ...normalized.split("/"));
+        const relative = path.relative(resourceRoot, resolved);
+        if (relative === ".." ||
+            relative.startsWith(`..${path.sep}`) ||
+            path.isAbsolute(relative)) {
+            throw new Error(`参考包 ${options.packageName} prepare 阶段资源超出所属根目录：${file}`);
+        }
+        return resolved;
+    };
+    const sourceCache = new Map();
+    const source = (file) => {
+        const normalized = path.posix.normalize(file);
+        const existing = sourceCache.get(normalized);
+        if (existing !== undefined)
+            return existing;
+        const handle = createTemplateSourceHandle(resolveOwnedResource(normalized));
+        sourceCache.set(normalized, handle);
+        return handle;
+    };
+    const contents = new Map();
+    const jsonDocuments = new Map();
+    let preparation;
+    let preparedRuntimeResources = [];
+    let preparedTemplateResources = [];
+    let preparedResourcesByPath = new Map();
+    const prepare = () => {
+        if (preparation !== undefined)
+            return preparation;
+        try {
+            const preparedDependencyUses = dependencyUses();
+            const scopes = new Map();
+            const scopeFor = (directory) => {
+                const existing = scopes.get(directory);
+                if (existing !== undefined)
+                    return existing;
+                const rules = ignore();
+                if (directory === ".")
+                    rules.add(options.resourceIgnore ?? resourceIgnoreSnapshot);
+                const ignoreFile = path.posix.join(directory, ".gitignore");
+                try {
+                    if (inDeclaredResources(ignoreFile)) {
+                        rules.add(readFileSync(resolveOwnedResource(ignoreFile), "utf8"));
+                    }
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+                const scope = { directory, rules };
+                scopes.set(directory, scope);
+                return scope;
+            };
+            const ignored = (file, directory) => {
+                if (file === ".git" || file.startsWith(".git/"))
+                    return true;
+                let excluded = false;
+                let parent = ".";
+                for (const part of ["", ...file.split("/").slice(0, -1)]) {
+                    if (part !== "")
+                        parent = path.posix.join(parent, part);
+                    const scope = scopeFor(parent);
+                    const relative = path.posix.relative(scope.directory, file);
+                    const result = scope.rules.test(relative + (directory ? "/" : ""));
+                    if (result.ignored)
+                        excluded = true;
+                    else if (result.unignored)
+                        excluded = false;
+                }
+                return excluded;
+            };
+            const files = new Set();
+            const visit = (directory) => {
+                for (const entry of readdirSync(resolveOwnedResource(directory), {
+                    withFileTypes: true,
+                }).sort((left, right) => left.name.localeCompare(right.name))) {
+                    const file = path.posix.join(directory, entry.name);
+                    if (ignored(file, entry.isDirectory()))
+                        continue;
+                    if (entry.isDirectory())
+                        visit(file);
+                    else if (file !== "package.json")
+                        files.add(file);
+                }
+            };
+            for (const resource of normalizedResources) {
+                if (resource === ".") {
+                    visit(resource);
+                    continue;
+                }
+                let entry;
+                try {
+                    entry = statSync(resolveOwnedResource(resource));
+                }
+                catch (error) {
+                    if (error.code === "ENOENT") {
+                        throw new Error(`参考资源不存在：${resource}`, { cause: error });
+                    }
+                    throw error;
+                }
+                if (ignored(resource, entry.isDirectory()))
+                    continue;
+                if (entry.isDirectory())
+                    visit(resource);
+                else if (resource !== "package.json")
+                    files.add(resource);
+            }
+            const resources = [...files]
+                .toSorted((left, right) => left.localeCompare(right))
+                .map((file) => {
+                const sourcePath = resolveOwnedResource(file);
+                const sourceText = readFileSync(sourcePath).toString("utf8");
+                const mode = statSync(sourcePath).mode & 0o777;
+                contents.set(file, sourceText);
+                if (/^tsconfig(?:\.[^/]+)?\.json$/u.test(file) ||
+                    /(^|\/)turbo\.jsonc?$/u.test(file)) {
+                    const errors = [];
+                    const parsed = parse(sourceText, errors, {
+                        allowTrailingComma: true,
+                    });
+                    if (errors.length > 0 ||
+                        typeof parsed !== "object" ||
+                        parsed === null ||
+                        Array.isArray(parsed)) {
+                        throw new Error(`原生工具配置必须是有效的 JSONC 对象：${file}`);
+                    }
+                    jsonDocuments.set(file, parsed);
+                }
+                return { path: file, source: source(file), mode };
+            });
+            preparedResourcesByPath = new Map(resources.map((resource) => [resource.path, resource]));
+            const executionData = executionDataPaths.map((resourcePath) => {
+                const resource = preparedResourcesByPath.get(resourcePath);
+                if (resource === undefined) {
+                    throw new Error(`模板执行数据未包含在参考资源范围中：${resourcePath}`);
+                }
+                return resource;
+            });
+            preparedRuntimeResources = resources.filter((resource) => !isTemplateResource(resource.path));
+            preparedTemplateResources = resources;
+            const preparedResourcePaths = new Set(preparedResourcesByPath.keys());
+            const ownerFacts = options.prepare?.({
+                manifest,
+                dependencyUses: preparedDependencyUses,
+                resources,
+                executionData,
+                readText(resourcePath) {
+                    const normalized = path.posix.normalize(resourcePath);
+                    if (!preparedResourcePaths.has(normalized) ||
+                        !executionDataPaths.includes(normalized)) {
+                        throw new Error(`所属准备请求了未声明或缺失的文本资源：${resourcePath}`);
+                    }
+                    const content = contents.get(normalized);
+                    if (content === undefined) {
+                        throw new Error(`所属准备请求的资源不是文本：${resourcePath}`);
+                    }
+                    return content;
+                },
+            });
+            preparation = Object.freeze({
+                owner: Object.freeze({
+                    packageName: manifest.name,
+                    exportPath: "./template",
+                }),
+                manifest,
+                resources: Object.freeze(resources),
+                executionData: Object.freeze(executionData),
+                templateDependencies,
+                dependencyUses: preparedDependencyUses,
+                ownerFacts: ownerFacts,
+            });
+            return preparation;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`参考包 ${options.packageName}/./template prepare 阶段失败：${message}`, { cause: error });
+        }
+    };
+    const requirePreparation = () => {
+        if (preparation === undefined) {
+            throw new Error(`参考包 ${options.packageName}/./template 尚未完成 prepare 阶段`);
+        }
+        return preparation;
+    };
+    const collectOperations = (targetPath, includeTemplateResources) => {
+        requirePreparation();
+        const resources = includeTemplateResources
+            ? preparedTemplateResources
+            : preparedRuntimeResources;
+        return resources.map((resource) => ({
+            kind: "copyFile",
+            source: resource.source,
+            from: ".",
+            to: path.posix.join(targetPath, resource.path),
+        }));
+    };
+    const operations = (targetPath) => collectOperations(targetPath, false);
+    const referencePackage = {
+        alias: options.alias,
+        resolve: options.resolve,
+        instance: options.instance,
+        defaultLeafName: options.defaultLeafName,
+        defaultPath,
+        role: options.role,
+        defaultIdentity(scope) {
+            return {
+                name: `@${scope}/${options.defaultLeafName}`,
+                path: defaultPath,
+                role: options.role,
+            };
+        },
+        ...(options.workspaceConfiguration === undefined
+            ? {}
+            : { workspaceConfiguration: options.workspaceConfiguration }),
+        ...(options.requiresRootRustToolchain === undefined
+            ? {}
+            : { requiresRootRustToolchain: options.requiresRootRustToolchain }),
+        manifest,
+        templateDependencies,
+        get dependencyUses() {
+            return dependencyUses();
+        },
+        ...(options.normalizeConfiguration === undefined
+            ? {}
+            : { normalizeConfiguration: options.normalizeConfiguration }),
+        targetDependencyNames,
+        prepare,
+        prepareArtifact() {
+            const prepared = prepare();
+            const dependencyPurposes = new Map(prepared.dependencyUses.map((dependency) => [
+                dependency.name,
+                dependency.purposes.filter((purpose) => purpose === "target" || purpose === "template-execution"),
+            ]));
+            const resources = new Map([...preparedRuntimeResources, ...prepared.executionData].map((resource) => [resource.path, resource]));
+            return prepareNativeContentArtifact({
+                manifest: prepared.manifest,
+                resourceRoot: options.resourceRoot,
+                exportPath: "./template",
+                ...(options.artifactVersion === undefined
+                    ? {}
+                    : { artifactVersion: options.artifactVersion }),
+                resources: [...resources.values()],
+                dependencyPurposes,
+            });
+        },
+        source,
+        operations,
+        payloadOperations: (targetPath) => collectOperations(targetPath, true),
+        contribute(input) {
+            const prepared = input.preparation ?? requirePreparation();
+            if (prepared.owner.packageName !== options.packageName ||
+                prepared.owner.exportPath !== "./template") {
+                throw new Error(`参考包 ${options.packageName}/./template 收到不匹配的所属 prepare 事实：${prepared.owner.packageName}#${prepared.owner.exportPath}`);
+            }
+            const manifest = prepared.manifest;
+            const bindings = input.bindings ?? new Map();
+            const targetDependencies = new Set(targetDependencyNames({
+                configuration: input.configuration ??
+                    options.normalizeConfiguration?.(undefined) ??
+                    null,
+                ...(input.creationInput === undefined
+                    ? {}
+                    : { creationInput: input.creationInput }),
+            }));
+            const names = new Map([...bindings].map(([name, definition]) => [name, definition.name]));
+            names.set(manifest.name, input.definition.name);
+            const projected = mapPackageNamesInJson(manifest, names);
+            const exports = {
+                ...projected.exports,
+            };
+            for (const key of [
+                "./reference",
+                "./template",
+                ...(options.template.exports ?? []),
+            ])
+                delete exports[key];
+            const scripts = { ...manifest.scripts };
+            for (const script of options.template.scripts)
+                delete scripts[script];
+            if (Object.keys(exports).length > 0)
+                projected.exports = exports;
+            else
+                delete projected.exports;
+            projected.scripts = scripts;
+            projected.name = input.definition.name;
+            projected.engines = {
+                ...manifest.engines,
+                node: input.context.toolchain.nodeLtsMajor,
+            };
+            for (const field of [
+                "dependencies",
+                "devDependencies",
+                "peerDependencies",
+                "optionalDependencies",
+            ]) {
+                if (manifest[field] === undefined)
+                    continue;
+                const dependencies = {
+                    ...projected[field],
+                };
+                for (const dependency of prepared.dependencyUses) {
+                    if (!targetDependencies.has(dependency.name))
+                        delete dependencies[names.get(dependency.name) ?? dependency.name];
+                }
+                for (const [nativeName, definition] of bindings) {
+                    if (!targetDependencies.has(nativeName))
+                        continue;
+                    const native = manifest[field][nativeName];
+                    if (native === undefined)
+                        continue;
+                    const relative = path.posix.relative(input.definition.path, definition.path);
+                    dependencies[definition.name] = native.startsWith("link:")
+                        ? `link:${relative}`
+                        : native.startsWith("workspace:.")
+                            ? `workspace:${relative}`
+                            : native;
+                }
+                projected[field] = dependencies;
+            }
+            const outputOperations = [
+                {
+                    kind: "writeJson",
+                    to: `${input.definition.path}/package.json`,
+                    value: {},
+                },
+            ];
+            for (const operation of operations(input.definition.path)) {
+                const relative = path.posix.relative(input.definition.path, operation.to);
+                const isTypeScriptConfig = /^tsconfig(?:\.[^/]+)?\.json$/u.test(relative);
+                const isTurboConfig = relative === "turbo.json" || relative === "turbo.jsonc";
+                if (isTypeScriptConfig || isTurboConfig) {
+                    const original = jsonDocuments.get(relative);
+                    if (original === undefined)
+                        throw new Error(`准备结果缺少已解析配置：${relative}`);
+                    const value = mapPackageNamesInJson(original, names);
+                    if (isTypeScriptConfig && Array.isArray(value.include))
+                        value.include = value.include.filter((entry) => typeof entry !== "string" || !isTemplateResource(entry));
+                    if (isTurboConfig &&
+                        typeof value.tasks === "object" &&
+                        value.tasks !== null) {
+                        const tasks = value.tasks;
+                        for (const script of options.template.scripts) {
+                            delete tasks[script];
+                            delete tasks[`${input.definition.name}#${script}`];
+                        }
+                    }
+                    outputOperations.push(isDeepStrictEqual(original, value)
+                        ? operation
+                        : { kind: "writeJson", to: operation.to, value });
+                }
+                else if (relative.endsWith(".ts")) {
+                    const sourceFile = resolveTemplateSource(operation.source, operation.from);
+                    const original = contents.get(relative);
+                    const preparedResource = preparedResourcesByPath.get(relative);
+                    if (original === undefined || preparedResource === undefined) {
+                        throw new Error(`准备结果缺少已读取源码资源：${relative}`);
+                    }
+                    const text = mapTypeScriptModuleSpecifiers(original, names, sourceFile);
+                    outputOperations.push(text === original
+                        ? operation
+                        : {
+                            kind: "writeText",
+                            to: operation.to,
+                            text,
+                            mode: preparedResource.mode,
+                            templateSource: {
+                                handle: operation.source,
+                                path: operation.from,
+                            },
+                            ...(operation.overwrite === undefined
+                                ? {}
+                                : { overwrite: operation.overwrite }),
+                            ...(operation.provenance === undefined
+                                ? {}
+                                : { provenance: operation.provenance }),
+                        });
+                }
+                else {
+                    outputOperations.push(operation);
+                }
+            }
+            const contribution = {
+                definition: input.definition,
+                manifest: projected,
+                exposure: {
+                    exports,
+                    imports: (projected.imports ?? {}),
+                },
+                operations: outputOperations,
+                foundation: {
+                    ...contextual(options.foundation, input),
+                    ...(options.workspaceConfiguration === undefined
+                        ? {}
+                        : { workspaceConfiguration: options.workspaceConfiguration }),
+                },
+                environmentNeeds: contextual(options.environmentNeeds, input),
+                referenceSource: manifest.name,
+                referenceBindings: Object.fromEntries(bindings),
+            };
+            return (options.project?.(contribution, {
+                ...input,
+                preparation: prepared,
+            }) ?? contribution);
+        },
+    };
+    return referencePackage;
+}

package/node_modules/@ykdz/template-workspace/dist/release-toolchain-snapshot.d.ts

@@ -0,0 +1,6 @@
+export declare const releaseToolchainSnapshot: Readonly<{
+    readonly nodeVersion: "24.21.0";
+    readonly packageManagerPin: "pnpm@12.9.1";
+    readonly rustVersion: "1.99.0";
+}>;
+export type ReleaseToolchainSnapshot = typeof releaseToolchainSnapshot;

package/node_modules/@ykdz/template-workspace/dist/release-toolchain-snapshot.js

@@ -0,0 +1,6 @@
+// 由根 sync:workspace-policy 从原生工具链声明派生，请修改事实源后显式同步。
+export const releaseToolchainSnapshot = Object.freeze({
+    nodeVersion: "24.21.0",
+    packageManagerPin: "pnpm@12.9.1",
+    rustVersion: "1.99.0",
+});

package/node_modules/@ykdz/template-workspace/dist/root-projection.d.ts

@@ -0,0 +1,29 @@
+import type { RenderOperation } from "@ykdz/template-core/renderer";
+export declare const packageManifestKeyOrder: readonly ["name", "version", "private", "bin", "files", "type", "types", "imports", "exports", "publishConfig", "scripts", "dependencies", "devDependencies", "dependenciesMeta", "peerDependencies", "optionalDependencies", "engines", "packageManager"];
+export declare const packageConditionKeyOrder: readonly ["source", "types", "default"];
+export declare function createWorkspaceRootManifest(options: {
+    readonly name: string;
+    readonly toolingConfigPackageName?: string;
+    readonly nodeDeclaration: string;
+    readonly packageManagerPin: string;
+}): Record<string, unknown>;
+export declare function projectPreparedWorkspaceRoot(options: {
+    readonly rootManifest: Readonly<Record<string, unknown>>;
+    readonly packageGlobs: readonly string[];
+    readonly dependencyCatalog: Readonly<Record<string, string>>;
+    readonly dependencyOverrides: Readonly<Record<string, string>>;
+    readonly turboTemplate: Readonly<Record<string, unknown>>;
+    readonly referenceNames: ReadonlyMap<string, string>;
+    readonly toolingConfigPackagePath?: string;
+    readonly turboBoundaryTags?: readonly ("app" | "library")[];
+    readonly rootTsconfigCompilerOptions: Readonly<Record<string, unknown>>;
+    readonly rootTsconfigInclude: readonly string[];
+    readonly tsconfigConfigTemplate: Readonly<Record<string, unknown>>;
+}): {
+    readonly manifest: RenderOperation;
+    readonly workspace: RenderOperation;
+    readonly turbo: RenderOperation;
+    readonly tsconfig: RenderOperation;
+    readonly tsconfigConfig: RenderOperation;
+    readonly tsconfigScripts: RenderOperation;
+};