@ykdz/template 0.0.42 → 0.1.0-experimental.1

package/node_modules/@ykdz/template-workspace/dist/project-linking.js

@@ -0,0 +1,218 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import {} from "@ykdz/template-core/project-blueprint";
+import { assertDefaultProjectBlueprint } from "./default-package-identity.js";
+import { isDefaultPackageRole } from "./default-package-role.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function canConsumeNodePackageNameImport(contribution, manifest = contribution.manifest) {
+    return canConsumeNodePackageNameImportForRole(contribution.definition.role, manifest);
+}
+/** 用已公开的 Package Role 与真实 manifest 判断是否能消费包名导入。 */
+export function canConsumeNodePackageNameImportForRole(role, manifest) {
+    return (isDefaultPackageRole(role) &&
+        role !== "native-package" &&
+        manifest.type === "module");
+}
+export function canLinkNodePackageRoles(consumerRole, providerRole) {
+    if (!isDefaultPackageRole(consumerRole) ||
+        !isDefaultPackageRole(providerRole)) {
+        return false;
+    }
+    if (consumerRole === "native-package" || providerRole === "native-package") {
+        return false;
+    }
+    return consumerRole !== "shared-library" || providerRole === "shared-library";
+}
+function isPackageRelativeTarget(value, extension) {
+    if (typeof value !== "string" ||
+        !value.startsWith("./") ||
+        value.includes("\\")) {
+        return false;
+    }
+    const segments = value.slice(2).split("/");
+    return (segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..") && extension.test(value));
+}
+function manifestExports(manifest) {
+    const exports = manifest.exports;
+    return typeof exports === "object" &&
+        exports !== null &&
+        !Array.isArray(exports)
+        ? exports
+        : {};
+}
+function requestsInjectedDependency(manifest, dependencyName) {
+    const dependenciesMeta = manifest.dependenciesMeta;
+    if (typeof dependenciesMeta !== "object" ||
+        dependenciesMeta === null ||
+        Array.isArray(dependenciesMeta)) {
+        return false;
+    }
+    const dependency = dependenciesMeta[dependencyName];
+    return (typeof dependency === "object" &&
+        dependency !== null &&
+        !Array.isArray(dependency) &&
+        dependency.injected === true);
+}
+function exposesSourceCondition(manifest) {
+    const rootExport = manifestExports(manifest)["."];
+    if (typeof rootExport !== "object" ||
+        rootExport === null ||
+        Array.isArray(rootExport) ||
+        Object.keys(rootExport).join("\u0000") !== "source\u0000types\u0000default") {
+        return false;
+    }
+    const conditions = rootExport;
+    return (isPackageRelativeTarget(conditions.source, /(?<!\.d)\.(?:[cm]?ts|tsx)$/u) &&
+        isPackageRelativeTarget(conditions.types, /\.d\.[cm]?ts$/u) &&
+        isPackageRelativeTarget(conditions.default, /\.[cm]?js$/u));
+}
+export function canProvideSourceConditionPackageNameImport(contribution, manifest = contribution.manifest) {
+    return canProvideSourceConditionPackageNameImportForRole(contribution.definition.role, manifest);
+}
+/** 用内容拥有的公开角色与 manifest 判断是否能提供 source 条件导入。 */
+export function canProvideSourceConditionPackageNameImportForRole(role, manifest) {
+    return (isDefaultPackageRole(role) &&
+        role !== "native-package" &&
+        exposesSourceCondition(manifest));
+}
+/** 读取显式连接端点已有的当前 package manifest，供正式连接计划复核。 */
+export function readProjectLinkManifestTruth(options) {
+    const truth = new Map();
+    for (const packagePath of new Set(options.packagePaths)) {
+        let manifestText;
+        try {
+            manifestText = readFileSync(path.join(options.repositoryRoot, packagePath, "package.json"), "utf8");
+        }
+        catch (error) {
+            if (typeof error === "object" &&
+                error !== null &&
+                "code" in error &&
+                error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+        const parsed = JSON.parse(manifestText);
+        truth.set(packagePath, isRecord(parsed) ? parsed : {});
+    }
+    return truth;
+}
+function exposesImportablePackageRoot(manifest) {
+    const rootExport = manifestExports(manifest)["."];
+    if (isPackageRelativeTarget(rootExport, /\.[cm]?[jt]sx?$/u)) {
+        return true;
+    }
+    if (typeof rootExport !== "object" ||
+        rootExport === null ||
+        Array.isArray(rootExport)) {
+        return false;
+    }
+    return isPackageRelativeTarget(rootExport.default, /\.[cm]?[jt]sx?$/u);
+}
+/**
+ * Resolves durable Link Intents from Package Contributions, optionally using
+ * Current Manifest Truth for a follow-up decision. No Preset identity or
+ * string resource protocol is involved.
+ */
+export function planExplicitProjectLinks(options) {
+    const blueprint = assertDefaultProjectBlueprint(options.blueprint);
+    const contributionsByPath = new Map(options.contributions.map((contribution) => [
+        contribution.definition.path,
+        contribution,
+    ]));
+    const manifestPatches = new Map();
+    for (const intent of blueprint.packageLinkIntents ?? []) {
+        const provider = contributionsByPath.get(intent.providerPackagePath);
+        const consumer = contributionsByPath.get(intent.consumerPackagePath);
+        if (provider === undefined || consumer === undefined) {
+            throw new Error("Project Linking requires explicit Package Contributions for every Link Intent endpoint");
+        }
+        const providerManifest = options.manifestTruthByPackagePath?.get(intent.providerPackagePath) ??
+            provider.manifest;
+        const consumerManifest = options.manifestTruthByPackagePath?.get(intent.consumerPackagePath) ??
+            consumer.manifest;
+        for (const [contribution, manifest] of [
+            [provider, providerManifest],
+            [consumer, consumerManifest],
+        ]) {
+            if (manifest.name !== contribution.definition.name) {
+                throw new Error(`Project Linking Manifest Truth for ${contribution.definition.path} must have package name ${contribution.definition.name}`);
+            }
+        }
+        if (!canConsumeNodePackageNameImport(consumer, consumerManifest)) {
+            const validPackagePaths = options.contributions
+                .filter((candidate) => candidate.definition.path !== intent.providerPackagePath &&
+                canConsumeNodePackageNameImport(candidate, options.manifestTruthByPackagePath?.get(candidate.definition.path) ?? candidate.manifest))
+                .map((candidate) => candidate.definition.path)
+                .toSorted();
+            throw new Error(`Package Link consumer ${consumer.definition.path} cannot consume a Node package-name import. Valid Package Paths: ${validPackagePaths.length === 0 ? "<none>" : validPackagePaths.join(", ")}`);
+        }
+        if (!canLinkNodePackageRoles(consumer.definition.role, provider.definition.role)) {
+            throw new Error(`Package Link ${consumer.definition.path} (${consumer.definition.role}) cannot depend on ${provider.definition.path} (${provider.definition.role}) under Package Role boundaries`);
+        }
+        if (!exposesImportablePackageRoot(providerManifest)) {
+            throw new Error(`Package Link provider ${provider.definition.path} does not expose an importable package root`);
+        }
+        const injected = !exposesSourceCondition(providerManifest) ||
+            requestsInjectedDependency(consumerManifest, provider.definition.name);
+        const consumerPatch = manifestPatches.get(intent.consumerPackagePath);
+        if (consumerPatch === undefined) {
+            manifestPatches.set(intent.consumerPackagePath, {
+                dependencies: { [provider.definition.name]: "workspace:*" },
+                ...(injected
+                    ? {
+                        dependenciesMeta: {
+                            [provider.definition.name]: { injected: true },
+                        },
+                    }
+                    : {}),
+            });
+        }
+        else {
+            consumerPatch.dependencies[provider.definition.name] = "workspace:*";
+            if (injected) {
+                (consumerPatch.dependenciesMeta ??= {})[provider.definition.name] = {
+                    injected: true,
+                };
+            }
+        }
+    }
+    return {
+        manifestPatchesByPackagePath: manifestPatches,
+        hasBuildOrdering: manifestPatches.size > 0,
+    };
+}
+/** 被注入的参考包将其绑定的 TypeScript 配置作为运行时依赖携带。 */
+export function promoteInjectedProviderRuntimeDependencies(options) {
+    const injectedProviderNames = new Set([...options.linkPlan.manifestPatchesByPackagePath.values()].flatMap((patch) => Object.entries(patch.dependenciesMeta ?? {})
+        .filter(([, metadata]) => metadata.injected)
+        .map(([name]) => name)));
+    return options.contributions.map((contribution) => {
+        if (contribution.referenceSource === undefined ||
+            !injectedProviderNames.has(contribution.definition.name)) {
+            return contribution;
+        }
+        const devDependencies = {
+            ...(isRecord(contribution.manifest.devDependencies)
+                ? contribution.manifest.devDependencies
+                : {}),
+        };
+        const dependencies = {
+            ...(isRecord(contribution.manifest.dependencies)
+                ? contribution.manifest.dependencies
+                : {}),
+        };
+        for (const definition of Object.values(contribution.referenceBindings ?? {})) {
+            if (devDependencies[definition.name] === undefined)
+                continue;
+            dependencies[definition.name] = "workspace:*";
+            delete devDependencies[definition.name];
+        }
+        return {
+            ...contribution,
+            manifest: { ...contribution.manifest, dependencies, devDependencies },
+        };
+    });
+}

package/node_modules/@ykdz/template-workspace/dist/project-requirements.d.ts

@@ -0,0 +1,17 @@
+import type { PackageDefinition } from "@ykdz/template-core/project-blueprint";
+export type DependencyEcosystem = "npm" | "cargo" | "github-actions" | "docker" | "devcontainers" | "rust-toolchain";
+export type DependabotDirectory = `/${string}`;
+/** 内容可以请求的有限根级依赖维护范围。 */
+export type DependencyMaintenancePolicy = {
+    readonly ecosystems: readonly DependencyEcosystem[];
+    readonly directories?: Partial<Record<DependencyEcosystem, DependabotDirectory>>;
+    readonly extraDirectories?: Partial<Record<DependencyEcosystem, readonly DependabotDirectory[]>>;
+    readonly interval: "weekly";
+};
+/** 内容通过稳定节点身份请求的显式包连接，具体可连接性由工作区策略判定。 */
+export type PackageLinkRequirement = {
+    readonly kind: "package-link";
+    readonly consumer: PackageDefinition;
+    readonly provider: PackageDefinition;
+};
+export type ProjectRequirement = PackageLinkRequirement;

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

@@ -0,0 +1,146 @@
+import type { PackageDefinition } from "@ykdz/template-core/project-blueprint";
+import { type CopyFileOperation, type TemplateSourceHandle } from "@ykdz/template-core/renderer";
+import type { GeneratorNodeInstances, GeneratorPackageCreatedBy, PackageCreationInput } from "@ykdz/template-core/workspace-strategy";
+import { type PreparedNativeContentArtifact } from "@ykdz/template-workspace-authoring/content-artifact";
+import type { DefaultPackageRole } from "./default-package-role.ts";
+import type { GenerationContext } from "./generation-context.ts";
+import type { PackageContribution } from "./package-contribution.ts";
+export type ReferencePackageManifest = Readonly<Record<string, unknown>> & {
+    readonly name: string;
+    readonly exports?: Readonly<Record<string, unknown>>;
+    readonly imports?: Readonly<Record<string, unknown>>;
+    readonly scripts?: Readonly<Record<string, string>>;
+    readonly dependencies?: Readonly<Record<string, string>>;
+    readonly devDependencies?: Readonly<Record<string, string>>;
+};
+export type ReferenceTemplateDependencyPurpose = "target" | "template-execution" | "template-build";
+export type ReferenceTemplateDependency = {
+    readonly name: string;
+    readonly purpose: ReferenceTemplateDependencyPurpose;
+};
+/** 按所属声明归一化后的同一依赖用途事实。 */
+export type ReferenceDependencyUse = {
+    readonly name: string;
+    readonly purposes: readonly ReferenceTemplateDependencyPurpose[];
+};
+export type PreparedReferenceResource = {
+    /** 仅为所属包内的公开资源路径，不包含物理工作区位置。 */
+    readonly path: string;
+    readonly source: TemplateSourceHandle;
+    readonly mode: number;
+};
+/** 所属自定义读取器仅能消费已声明并准备的文本资源。 */
+export type ReferencePackagePreparationInput = {
+    readonly manifest: ReferencePackageManifest;
+    readonly dependencyUses: readonly ReferenceDependencyUse[];
+    readonly resources: readonly PreparedReferenceResource[];
+    readonly executionData: readonly PreparedReferenceResource[];
+    readText(path: string): string;
+};
+/** 所属准备返回的公开原生事实和不暴露物理路径的资源句柄。 */
+export type ReferencePackagePreparation<OwnerFacts = unknown> = {
+    readonly owner: {
+        readonly packageName: string;
+        readonly exportPath: "./template";
+    };
+    readonly manifest: ReferencePackageManifest;
+    readonly resources: readonly PreparedReferenceResource[];
+    /** 模板执行阶段会读取的数据；它可以与目标排除资源重叠。 */
+    readonly executionData: readonly PreparedReferenceResource[];
+    readonly templateDependencies: readonly ReferenceTemplateDependency[];
+    readonly dependencyUses: readonly ReferenceDependencyUse[];
+    readonly ownerFacts: OwnerFacts;
+};
+export type ReferenceContributionOptions<CreationInput extends PackageCreationInput = PackageCreationInput> = {
+    readonly context: GenerationContext;
+    readonly configuration?: unknown;
+    readonly definition: PackageDefinition;
+    readonly bindings?: ReadonlyMap<string, PackageDefinition>;
+    /** 公开生成器传入的持久创建语义。 */
+    readonly createdBy?: GeneratorPackageCreatedBy;
+    readonly creationInput?: CreationInput;
+    readonly nodeInstances?: GeneratorNodeInstances;
+    /** 已由公开生成器或所属适配器执行的同一包准备结果。 */
+    readonly preparation?: unknown;
+};
+type Contextual<Value, CreationInput extends PackageCreationInput = PackageCreationInput> = Value | ((options: ReferenceContributionOptions<CreationInput>) => Value);
+type ReferencePackageProjectOptions<CreationInput extends PackageCreationInput, OwnerFacts> = Omit<ReferenceContributionOptions<CreationInput>, "preparation"> & {
+    readonly preparation: ReferencePackagePreparation<OwnerFacts>;
+};
+export type ReferencePackage<CreationInput extends PackageCreationInput = PackageCreationInput, OwnerFacts = unknown> = {
+    readonly alias: string;
+    readonly resolve: (specifier: string) => string;
+    readonly instance: "shared" | "independent";
+    readonly defaultLeafName: string;
+    readonly defaultPath: string;
+    readonly role: DefaultPackageRole;
+    /** 由参考包自身提供默认工作区实例身份，供外部调用者校验碰撞。 */
+    defaultIdentity(scope: string): {
+        readonly name: string;
+        readonly path: string;
+        readonly role: DefaultPackageRole;
+    };
+    /** 实际配置拥有者标记的有限工作区配置能力。 */
+    readonly workspaceConfiguration?: {
+        readonly kind: "typescript-workspace-configuration";
+    };
+    /** 内容被选中时需要根策略准备 Rust 工具链事实。 */
+    readonly requiresRootRustToolchain?: true;
+    readonly manifest: ReferencePackageManifest;
+    readonly templateDependencies: readonly ReferenceTemplateDependency[];
+    /** prepare 后可供策略和贡献共同消费的用途归一化事实。 */
+    readonly dependencyUses: readonly ReferenceDependencyUse[];
+    normalizeConfiguration?(input: unknown): unknown;
+    targetDependencyNames(options: {
+        readonly configuration: unknown;
+        readonly creationInput?: CreationInput;
+    }): readonly string[];
+    prepare(): ReferencePackagePreparation<OwnerFacts>;
+    /** 完成原生模板编译后，公开可供collection装配的所属制品句柄。 */
+    prepareArtifact(): PreparedNativeContentArtifact;
+    source(file: string): TemplateSourceHandle;
+    operations(targetPath: string): CopyFileOperation[];
+    payloadOperations(targetPath: string): CopyFileOperation[];
+    contribute(options: ReferenceContributionOptions<CreationInput>): PackageContribution;
+};
+/** 原生包声明是生成事实源，描述只补充资源范围与局部差异。 */
+export declare function defineReferencePackage<CreationInput extends PackageCreationInput = PackageCreationInput, OwnerFacts = undefined>(options: {
+    readonly packageName: string;
+    /** 原生清单未声明version时由所属包提供的安装制品坐标。 */
+    readonly artifactVersion?: string;
+    readonly resolve: (specifier: string) => string;
+    /** 所属包公开准备职责选择的本包资源根目录。 */
+    readonly resourceRoot: URL;
+    readonly alias: string;
+    readonly instance: "shared" | "independent";
+    readonly defaultLeafName: string;
+    readonly defaultPath?: string;
+    readonly role: DefaultPackageRole;
+    readonly workspaceConfiguration?: {
+        readonly kind: "typescript-workspace-configuration";
+    };
+    /** 内容被选中时需要根策略准备 Rust 工具链事实。 */
+    readonly requiresRootRustToolchain?: true;
+    readonly resources: readonly string[];
+    readonly resourceIgnore?: string;
+    readonly template: {
+        readonly dependencies: readonly ReferenceTemplateDependency[];
+        readonly exports?: readonly string[];
+        readonly scripts: readonly string[];
+        readonly resources?: readonly string[];
+        /** 模板执行会读取的数据资源；与生成目标排除规则分开声明。 */
+        readonly executionData?: readonly string[];
+    };
+    readonly prepare?: (options: ReferencePackagePreparationInput) => OwnerFacts;
+    readonly normalizeConfiguration?: (input: unknown) => unknown;
+    /** 仅从原生声明的目标依赖全集中按实例配置选择。 */
+    readonly targetDependencies?: (options: {
+        readonly configuration: unknown;
+        readonly creationInput?: CreationInput;
+        readonly dependencies: readonly string[];
+    }) => readonly string[];
+    readonly foundation: Contextual<PackageContribution["foundation"], CreationInput>;
+    readonly environmentNeeds: Contextual<PackageContribution["environmentNeeds"], CreationInput>;
+    readonly project?: (contribution: PackageContribution, options: ReferencePackageProjectOptions<CreationInput, OwnerFacts>) => PackageContribution;
+}): ReferencePackage<CreationInput, OwnerFacts>;
+export {};