create-yss-spec 3.1.0 → 3.2.0

package/src/template/instance-runtime.js

@@ -0,0 +1,463 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const { treeHash } = require("../template-hash");
+const { targetPath, pathKind, normalizeRelativePath } = require("../filesystem/path-utils");
+const { validateTemplateSnapshot } = require("../validation/snapshot");
+const { validateTemplateMetadata } = require("../validation/metadata");
+const {
+  parseRepositoryIdentity,
+  convertTemplateSourceToInstance,
+} = require("../validation/identity");
+
+const PACKAGE_ROOT = path.resolve(__dirname, "../..");
+const PACKAGE_MANIFEST = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
+);
+const BUNDLED_TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
+const BUNDLED_MANIFEST_PATH = path.join(PACKAGE_ROOT, "template.manifest.json");
+const BUNDLED_SNAPSHOT_PATH = path.join(PACKAGE_ROOT, "template.snapshot.json");
+const TEMPLATE_MANIFEST_TEXT = fs.readFileSync(BUNDLED_MANIFEST_PATH, "utf8");
+const TEMPLATE_MANIFEST = JSON.parse(TEMPLATE_MANIFEST_TEXT);
+const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
+const TEMPLATE_SOURCE = "github:iloveZzz/yss-spec-project-template";
+const METADATA_SCHEMA_VERSION = 2;
+
+const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
+const ROOT_EXCLUDED_FILES = new Set(TEMPLATE_MANIFEST.excludeRootFiles);
+const EXCLUDED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.excludePaths);
+const ALLOWED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.allowFiles || []);
+const INIT_EXCLUDED_ROOT_ENTRIES = new Set(
+  TEMPLATE_MANIFEST.initExcludeRootEntries || [],
+);
+const INIT_EXCLUDED_ROOT_FILES = new Set(
+  TEMPLATE_MANIFEST.initExcludeRootFiles || [],
+);
+const INIT_EXCLUDED_RELATIVE_PATHS = new Set(
+  TEMPLATE_MANIFEST.initExcludePaths || [],
+);
+const RENDERED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.renderPaths);
+const EXAMPLE_DOC_PATHS = new Set(TEMPLATE_MANIFEST.exampleDocPaths);
+
+let bundledPathToLogicalPath = null;
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+const TEMPLATE_MANIFEST_VERSION = sha256(TEMPLATE_MANIFEST_TEXT);
+
+function nowIsoString() {
+  return new Date().toISOString();
+}
+
+function readTemplateSnapshot() {
+  if (!fs.existsSync(BUNDLED_SNAPSHOT_PATH)) {
+    throw new Error(
+      "缺少模板快照元数据，请先运行 npm run sync-template；正式发布不得使用浮动模板引用",
+    );
+  }
+
+  let snapshot;
+  try {
+    snapshot = JSON.parse(fs.readFileSync(BUNDLED_SNAPSHOT_PATH, "utf8"));
+  } catch (error) {
+    throw new Error(`模板快照元数据无法解析：${error.message}`);
+  }
+
+  return validateTemplateSnapshot(snapshot, {
+    manifestHash: TEMPLATE_MANIFEST_VERSION,
+    treeHash: treeHash(BUNDLED_TEMPLATE_ROOT),
+  });
+}
+
+function logicalTemplatePath(bundledPath) {
+  if (bundledPathToLogicalPath === null) {
+    const snapshot = readTemplateSnapshot();
+    bundledPathToLogicalPath = new Map(
+      Object.entries(snapshot.encodedPaths || {}).map(([logicalPath, encodedPath]) => [
+        normalizeRelativePath(encodedPath),
+        normalizeRelativePath(logicalPath),
+      ]),
+    );
+  }
+  return (
+    bundledPathToLogicalPath.get(normalizeRelativePath(bundledPath)) ||
+    normalizeRelativePath(bundledPath)
+  );
+}
+
+function shouldExcludeRelativePath(relativePath, mode = "managed") {
+  const normalized = normalizeRelativePath(relativePath);
+  if (
+    [...ALLOWED_RELATIVE_PATHS].some(
+      (allowedPath) =>
+        allowedPath === normalized || allowedPath.startsWith(`${normalized}/`),
+    )
+  ) {
+    return false;
+  }
+  return (
+    EXCLUDED_RELATIVE_PATHS.has(normalized) ||
+    (mode === "init" &&
+      (INIT_EXCLUDED_RELATIVE_PATHS.has(normalized) ||
+        INIT_EXCLUDED_ROOT_FILES.has(normalized)))
+  );
+}
+
+function shouldSkipRootEntry(entryName, mode = "managed") {
+  return (
+    ROOT_EXCLUDED_ENTRIES.has(entryName) ||
+    ROOT_EXCLUDED_FILES.has(entryName) ||
+    (mode === "init" &&
+      (INIT_EXCLUDED_ROOT_ENTRIES.has(entryName) ||
+        INIT_EXCLUDED_ROOT_FILES.has(entryName)))
+  );
+}
+
+function readTargetIdentity(targetDir) {
+  const identityPath = targetPath(targetDir, "yss-project.yaml");
+  const identityKind = pathKind(identityPath);
+  if (identityKind === "missing") {
+    return { state: "missing", path: identityPath, content: null };
+  }
+  if (identityKind !== "file") {
+    throw new Error("yss-project.yaml 不能是符号链接或其他特殊文件");
+  }
+
+  const content = fs.readFileSync(identityPath, "utf8");
+  return {
+    state: "valid",
+    path: identityPath,
+    content,
+    fields: parseRepositoryIdentity(content),
+  };
+}
+
+function renderTemplateFile(relativePath, content, variables) {
+  if (relativePath === "yss-project.yaml") {
+    return convertTemplateSourceToInstance(content);
+  }
+
+  if (relativePath === "AGENTS.md") {
+    return content
+      .replace(
+        /(\*\*项目名称：\*\*\s*)\[填写\]/,
+        (_, prefix) => `${prefix}${variables.projectName}`,
+      )
+      .replace(
+        /(\*\*业务领域：\*\*\s*)\[填写\]/,
+        (_, prefix) => `${prefix}${variables.businessDomain}`,
+      )
+      .replace(
+        /(\*\*团队规模：\*\*\s*)\[填写\]/,
+        (_, prefix) => `${prefix}${variables.teamSize}`,
+      );
+  }
+
+  if (relativePath === "README.md") {
+    const renderedContent = content
+      .replace(/^# YSS Spec Project Template/m, `# ${variables.projectName}`)
+      .replace(
+        /^> Matt Pocock Engineering Skills/m,
+        `> 默认 Issue Tracker：${variables.issueTracker}\n>\n> Matt Pocock Engineering Skills`,
+      );
+
+    if (!variables.includeExampleDocs) {
+      return renderedContent.replace(
+        /^\| \[docs\/discovery\/IDEATION\.md\]\(\.\/docs\/discovery\/IDEATION\.md\) \|.*\r?\n/m,
+        "",
+      );
+    }
+    return renderedContent;
+  }
+
+  return content;
+}
+
+function buildCopyPlan(
+  sourceDir,
+  targetDir,
+  variables,
+  relativeDir = "",
+  mode = "managed",
+) {
+  const operations = [];
+  const entries = fs.readdirSync(sourceDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!relativeDir && shouldSkipRootEntry(entry.name, mode)) continue;
+
+    const bundledRelativePath = relativeDir
+      ? path.posix.join(relativeDir, entry.name)
+      : entry.name;
+    const relativePath = logicalTemplatePath(bundledRelativePath);
+
+    if (shouldExcludeRelativePath(relativePath, mode)) continue;
+    if (!variables.includeExampleDocs && EXAMPLE_DOC_PATHS.has(relativePath)) continue;
+
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPathValue = targetPath(targetDir, relativePath);
+
+    if (entry.isDirectory()) {
+      operations.push({ type: "mkdir", relativePath, targetPath: targetPathValue });
+      operations.push(
+        ...buildCopyPlan(
+          sourcePath,
+          targetDir,
+          variables,
+          bundledRelativePath,
+          mode,
+        ),
+      );
+      continue;
+    }
+    if (!entry.isFile()) continue;
+
+    operations.push({
+      type: RENDERED_RELATIVE_PATHS.has(relativePath) ? "render" : "copy",
+      relativePath,
+      sourcePath,
+      targetPath: targetPathValue,
+    });
+  }
+
+  return operations;
+}
+
+function fileHash(filePath) {
+  return sha256(fs.readFileSync(filePath));
+}
+
+function buildSyncVariables(metadata) {
+  const variables = metadata.variables || {};
+  return {
+    projectName: variables.projectName || "待补充",
+    businessDomain: variables.businessDomain || "待补充",
+    teamSize: variables.teamSize || "待补充",
+    issueTracker: variables.issueTracker || "github",
+    includeExampleDocs:
+      variables.includeExampleDocs === undefined
+        ? true
+        : Boolean(variables.includeExampleDocs),
+  };
+}
+
+function buildDesiredManagedFile(operation, variables) {
+  if (operation.type === "render") {
+    const desiredContent = renderTemplateFile(
+      operation.relativePath,
+      fs.readFileSync(operation.sourcePath, "utf8"),
+      variables,
+    );
+    return {
+      ...operation,
+      desiredContent,
+      desiredHash: sha256(desiredContent),
+    };
+  }
+
+  return {
+    ...operation,
+    desiredContent: fs.readFileSync(operation.sourcePath),
+    desiredHash: fileHash(operation.sourcePath),
+  };
+}
+
+function buildDesiredManagedOperations(targetDir, variables, mode = "managed") {
+  return buildCopyPlan(BUNDLED_TEMPLATE_ROOT, targetDir, variables, "", mode)
+    .filter((operation) => operation.type === "copy" || operation.type === "render")
+    .map((operation) => buildDesiredManagedFile(operation, variables));
+}
+
+function buildSyncDesiredOperations(targetDir, metadata, identity) {
+  const variables = buildSyncVariables(metadata);
+  return buildDesiredManagedOperations(targetDir, variables, "init").map((operation) => {
+    if (
+      operation.relativePath !== "yss-project.yaml" ||
+      identity.state !== "valid" ||
+      identity.fields.repository_mode !== "template-source"
+    ) {
+      return operation;
+    }
+
+    const desiredContent = convertTemplateSourceToInstance(identity.content);
+    return {
+      ...operation,
+      desiredContent,
+      desiredHash: sha256(desiredContent),
+      identityConversion: true,
+      identitySourceHash: sha256(identity.content),
+    };
+  });
+}
+
+function buildAttachDesiredOperations(targetDir, variables, identity) {
+  return buildDesiredManagedOperations(targetDir, variables, "managed").map((operation) => {
+    if (operation.relativePath !== "yss-project.yaml" || identity.state === "missing") {
+      return operation;
+    }
+
+    if (identity.fields.repository_mode === "project-instance") {
+      return {
+        ...operation,
+        desiredContent: identity.content,
+        desiredHash: sha256(identity.content),
+        identityPreserved: true,
+      };
+    }
+
+    const desiredContent = convertTemplateSourceToInstance(identity.content);
+    return {
+      ...operation,
+      desiredContent,
+      desiredHash: sha256(desiredContent),
+      identityConversion: true,
+    };
+  });
+}
+
+function loadTemplateMetadata(targetDir) {
+  const metadataPath = targetPath(targetDir, TEMPLATE_METADATA_FILENAME);
+  const metadataKind = pathKind(metadataPath);
+  if (metadataKind === "missing") {
+    throw new Error(
+      `当前目录不是受支持的模板实例仓库，缺少模板元数据文件 ${TEMPLATE_METADATA_FILENAME}；请先使用 attach`,
+    );
+  }
+  if (metadataKind !== "file") {
+    throw new Error("模板元数据不能是符号链接或其他特殊文件");
+  }
+
+  let metadata;
+  try {
+    metadata = JSON.parse(fs.readFileSync(metadataPath, "utf8"));
+  } catch (error) {
+    throw new Error(`模板元数据无法解析：${error.message}`);
+  }
+
+  validateTemplateMetadata(metadata, {
+    currentSchemaVersion: METADATA_SCHEMA_VERSION,
+    templateName: PACKAGE_MANIFEST.name,
+    templateSource: TEMPLATE_SOURCE,
+  });
+
+  return { metadataPath, metadata };
+}
+
+function collectManagedFiles(desiredOperations) {
+  const managedFiles = {};
+  for (const operation of desiredOperations) {
+    if (pathKind(operation.targetPath) !== "file") continue;
+    managedFiles[operation.relativePath] = {
+      type: operation.type,
+      contentHash: fileHash(operation.targetPath),
+    };
+  }
+  return managedFiles;
+}
+
+function buildMetadata(variables, desiredOperations, timestamp = nowIsoString()) {
+  return {
+    metadataSchemaVersion: METADATA_SCHEMA_VERSION,
+    templateName: PACKAGE_MANIFEST.name,
+    cliVersion: PACKAGE_MANIFEST.version,
+    templateVersion: PACKAGE_MANIFEST.version,
+    templateSource: TEMPLATE_SOURCE,
+    templateCommit: readTemplateSnapshot().templateCommit,
+    initializedAt: timestamp,
+    lastSyncedAt: timestamp,
+    managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
+    variables: {
+      projectName: variables.projectName,
+      businessDomain: variables.businessDomain,
+      teamSize: variables.teamSize,
+      issueTracker: variables.issueTracker,
+      includeExampleDocs: variables.includeExampleDocs,
+    },
+    managedFiles: collectManagedFiles(desiredOperations),
+  };
+}
+
+function writeTemplateMetadata(targetDir, metadata, transaction = null) {
+  const metadataPath = targetPath(targetDir, TEMPLATE_METADATA_FILENAME);
+  const content = `${JSON.stringify(metadata, null, 2)}\n`;
+  if (transaction) {
+    transaction.writeFile(metadataPath, content);
+    return;
+  }
+  fs.writeFileSync(metadataPath, content, "utf8");
+}
+
+function buildNextSyncMetadata(metadata, syncPlan) {
+  const nextManagedFiles = { ...(metadata.managedFiles || {}) };
+  for (const relativePath of syncPlan.removed) {
+    delete nextManagedFiles[relativePath];
+  }
+  for (const operation of syncPlan.desiredOperations) {
+    if (pathKind(operation.targetPath) !== "file") continue;
+    const currentHash = fileHash(operation.targetPath);
+    if (currentHash === operation.desiredHash) {
+      nextManagedFiles[operation.relativePath] = {
+        type: operation.type,
+        contentHash: operation.desiredHash,
+      };
+    }
+  }
+
+  return {
+    ...metadata,
+    metadataSchemaVersion: METADATA_SCHEMA_VERSION,
+    templateName: PACKAGE_MANIFEST.name,
+    cliVersion: PACKAGE_MANIFEST.version,
+    templateVersion: PACKAGE_MANIFEST.version,
+    templateSource: TEMPLATE_SOURCE,
+    templateCommit: readTemplateSnapshot().templateCommit,
+    lastSyncedAt: nowIsoString(),
+    managedFilesManifestVersion: TEMPLATE_MANIFEST_VERSION,
+    managedFiles: nextManagedFiles,
+  };
+}
+
+function verifyGeneratedSyncInstance(targetDir) {
+  const identity = readTargetIdentity(targetDir);
+  if (
+    identity.state !== "valid" ||
+    identity.fields.repository_mode !== "project-instance"
+  ) {
+    throw new Error("初始化结果的 yss-project.yaml 必须是 project-instance");
+  }
+
+  const agentsContent = fs.readFileSync(targetPath(targetDir, "AGENTS.md"), "utf8");
+  const readmeContent = fs.readFileSync(targetPath(targetDir, "README.md"), "utf8");
+  if (agentsContent.includes("[填写]") || readmeContent.includes("[填写]")) {
+    throw new Error("初始化结果仍包含模板占位信息");
+  }
+}
+
+module.exports = {
+  PACKAGE_ROOT,
+  PACKAGE_MANIFEST,
+  BUNDLED_TEMPLATE_ROOT,
+  TEMPLATE_MANIFEST,
+  TEMPLATE_MANIFEST_VERSION,
+  TEMPLATE_METADATA_FILENAME,
+  TEMPLATE_SOURCE,
+  METADATA_SCHEMA_VERSION,
+  sha256,
+  fileHash,
+  readTemplateSnapshot,
+  readTargetIdentity,
+  buildSyncVariables,
+  buildDesiredManagedOperations,
+  buildSyncDesiredOperations,
+  buildAttachDesiredOperations,
+  loadTemplateMetadata,
+  buildMetadata,
+  writeTemplateMetadata,
+  buildNextSyncMetadata,
+  verifyGeneratedSyncInstance,
+};

package/src/template/lifecycle-metadata.js

@@ -0,0 +1,99 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const {
+  CUSTOMIZATION_POLICY,
+  GENERATOR_POLICY,
+  applyLifecycleToOperations,
+} = require("./lifecycle-runtime");
+
+function policyHash(policy) {
+  return crypto.createHash("sha256").update(JSON.stringify(policy)).digest("hex");
+}
+
+function decorateMetadataLifecycle(metadata) {
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+    throw new TypeError("metadata must be an object");
+  }
+
+  const managedFiles = Object.fromEntries(
+    Object.entries(metadata.managedFiles || {}).map(([relativePath, record]) => {
+      const [operation] = applyLifecycleToOperations([
+        {
+          relativePath,
+          ownership: record?.ownership,
+        },
+      ]);
+      const next = { ...record };
+      if (operation?.mergeStrategy) next.mergeStrategy = operation.mergeStrategy;
+      if (operation?.generatorId) next.generatorId = operation.generatorId;
+      if (operation?.generatorVersion) {
+        next.generatorVersion = operation.generatorVersion;
+      }
+      return [relativePath, next];
+    }),
+  );
+
+  return {
+    ...metadata,
+    customizationPolicyVersion: CUSTOMIZATION_POLICY.version,
+    customizationPolicyHash: policyHash(CUSTOMIZATION_POLICY),
+    generatorPolicyVersion: GENERATOR_POLICY.version,
+    generatorPolicyHash: policyHash(GENERATOR_POLICY),
+    managedFiles,
+  };
+}
+
+function lifecyclePolicyDrift(metadata) {
+  const customizationExpected = {
+    version: CUSTOMIZATION_POLICY.version,
+    hash: policyHash(CUSTOMIZATION_POLICY),
+  };
+  const generatorExpected = {
+    version: GENERATOR_POLICY.version,
+    hash: policyHash(GENERATOR_POLICY),
+  };
+
+  const customizationState =
+    metadata?.customizationPolicyVersion === undefined ||
+    metadata?.customizationPolicyHash === undefined
+      ? "missing"
+      : metadata.customizationPolicyVersion !== customizationExpected.version ||
+          metadata.customizationPolicyHash !== customizationExpected.hash
+        ? "drift"
+        : "matched";
+
+  const generatorState =
+    metadata?.generatorPolicyVersion === undefined ||
+    metadata?.generatorPolicyHash === undefined
+      ? "missing"
+      : metadata.generatorPolicyVersion !== generatorExpected.version ||
+          metadata.generatorPolicyHash !== generatorExpected.hash
+        ? "drift"
+        : "matched";
+
+  return {
+    customization: {
+      state: customizationState,
+      expected: customizationExpected,
+      actual: {
+        version: metadata?.customizationPolicyVersion ?? null,
+        hash: metadata?.customizationPolicyHash ?? null,
+      },
+    },
+    generator: {
+      state: generatorState,
+      expected: generatorExpected,
+      actual: {
+        version: metadata?.generatorPolicyVersion ?? null,
+        hash: metadata?.generatorPolicyHash ?? null,
+      },
+    },
+  };
+}
+
+module.exports = {
+  policyHash,
+  decorateMetadataLifecycle,
+  lifecyclePolicyDrift,
+};

package/src/template/lifecycle-policy.js

@@ -0,0 +1,129 @@
+"use strict";
+
+const {
+  validateOwnershipPattern,
+  matchesOwnershipPattern,
+} = require("./ownership-policy");
+
+const CUSTOMIZATION_POLICY_VERSION = 1;
+const CUSTOMIZATION_STRATEGIES = Object.freeze([
+  "replace-with-force",
+  "manual",
+]);
+const GENERATOR_POLICY_VERSION = 1;
+
+function validateRulePattern(pattern) {
+  return validateOwnershipPattern(pattern);
+}
+
+function validateCustomizationPolicy(policy) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new Error("customizationPolicy 必须是 JSON 对象");
+  }
+  if (policy.version !== CUSTOMIZATION_POLICY_VERSION) {
+    throw new Error(`不支持的 customizationPolicy version：${policy.version}`);
+  }
+  if (!CUSTOMIZATION_STRATEGIES.includes(policy.defaultStrategy)) {
+    throw new Error(`customizationPolicy defaultStrategy 非法：${policy.defaultStrategy}`);
+  }
+  if (!Array.isArray(policy.rules)) {
+    throw new Error("customizationPolicy rules 必须是数组");
+  }
+
+  const seen = new Set();
+  const rules = policy.rules.map((rule, index) => {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+      throw new Error(`customizationPolicy rules[${index}] 必须是对象`);
+    }
+    const pattern = validateRulePattern(rule.pattern);
+    if (seen.has(pattern)) {
+      throw new Error(`customizationPolicy pattern 重复：${pattern}`);
+    }
+    seen.add(pattern);
+    if (!CUSTOMIZATION_STRATEGIES.includes(rule.strategy)) {
+      throw new Error(
+        `customizationPolicy rules[${index}].strategy 非法：${rule.strategy}`,
+      );
+    }
+    return { pattern, strategy: rule.strategy };
+  });
+
+  return {
+    version: CUSTOMIZATION_POLICY_VERSION,
+    defaultStrategy: policy.defaultStrategy,
+    rules,
+  };
+}
+
+function resolveCustomizationStrategy(relativePath, policy) {
+  const validated = validateCustomizationPolicy(policy);
+  for (const rule of validated.rules) {
+    if (matchesOwnershipPattern(relativePath, rule.pattern)) {
+      return rule.strategy;
+    }
+  }
+  return validated.defaultStrategy;
+}
+
+function validateGeneratorPolicy(policy) {
+  if (!policy || typeof policy !== "object" || Array.isArray(policy)) {
+    throw new Error("generatorPolicy 必须是 JSON 对象");
+  }
+  if (policy.version !== GENERATOR_POLICY_VERSION) {
+    throw new Error(`不支持的 generatorPolicy version：${policy.version}`);
+  }
+  if (!Array.isArray(policy.rules)) {
+    throw new Error("generatorPolicy rules 必须是数组");
+  }
+
+  const seen = new Set();
+  const rules = policy.rules.map((rule, index) => {
+    if (!rule || typeof rule !== "object" || Array.isArray(rule)) {
+      throw new Error(`generatorPolicy rules[${index}] 必须是对象`);
+    }
+    const pattern = validateRulePattern(rule.pattern);
+    if (seen.has(pattern)) {
+      throw new Error(`generatorPolicy pattern 重复：${pattern}`);
+    }
+    seen.add(pattern);
+    if (!/^[a-z][a-z0-9-]*$/.test(rule.generatorId || "")) {
+      throw new Error(`generatorPolicy rules[${index}].generatorId 非法`);
+    }
+    if (!Number.isInteger(rule.generatorVersion) || rule.generatorVersion < 1) {
+      throw new Error(`generatorPolicy rules[${index}].generatorVersion 必须是正整数`);
+    }
+    return {
+      pattern,
+      generatorId: rule.generatorId,
+      generatorVersion: rule.generatorVersion,
+    };
+  });
+
+  return {
+    version: GENERATOR_POLICY_VERSION,
+    rules,
+  };
+}
+
+function resolveGenerator(relativePath, policy) {
+  const validated = validateGeneratorPolicy(policy);
+  for (const rule of validated.rules) {
+    if (matchesOwnershipPattern(relativePath, rule.pattern)) {
+      return {
+        generatorId: rule.generatorId,
+        generatorVersion: rule.generatorVersion,
+      };
+    }
+  }
+  return null;
+}
+
+module.exports = {
+  CUSTOMIZATION_POLICY_VERSION,
+  CUSTOMIZATION_STRATEGIES,
+  GENERATOR_POLICY_VERSION,
+  validateCustomizationPolicy,
+  resolveCustomizationStrategy,
+  validateGeneratorPolicy,
+  resolveGenerator,
+};