create-yss-spec 3.1.0 → 3.2.0

package/src/filesystem/transaction.js

@@ -0,0 +1,153 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { copyPath } = require("./copy-path");
+const {
+  normalizeRelativePath,
+  targetPath,
+  pathKind,
+} = require("./path-utils");
+
+class FileTransaction {
+  constructor(targetDir, deps = {}) {
+    this.targetDir = path.resolve(targetDir);
+    this.fs = deps.fs || fs;
+    this.path = deps.path || path;
+    this.copyPath = deps.copyPath || copyPath;
+    this.pathKind = deps.pathKind || pathKind;
+    this.backupRoot = deps.backupRoot || this.fs.mkdtempSync(
+      this.path.join((deps.os || os).tmpdir(), "create-yss-spec-backup-"),
+    );
+    this.backups = [];
+    this.mutated = [];
+    this.createdDirectories = [];
+  }
+
+  relative(absolutePath) {
+    return normalizeRelativePath(this.path.relative(this.targetDir, absolutePath));
+  }
+
+  backupPath(relativePath) {
+    return this.path.join(this.backupRoot, ...normalizeRelativePath(relativePath).split("/"));
+  }
+
+  prepare(relativePaths) {
+    const candidates = [...new Set(relativePaths)]
+      .map((relativePath) => normalizeRelativePath(relativePath))
+      .filter(
+        (relativePath) =>
+          relativePath &&
+          this.pathKind(targetPath(this.targetDir, relativePath)) !== "missing",
+      )
+      .sort((left, right) => left.split("/").length - right.split("/").length);
+
+    for (const relativePath of candidates) {
+      if (
+        this.backups.some(
+          (backup) =>
+            relativePath === backup.relativePath ||
+            relativePath.startsWith(`${backup.relativePath}/`),
+        )
+      ) {
+        continue;
+      }
+
+      const source = targetPath(this.targetDir, relativePath);
+      const destination = this.backupPath(relativePath);
+      this.copyPath(source, destination);
+      this.backups.push({ relativePath, destination });
+    }
+  }
+
+  ensureParent(absolutePath) {
+    const missing = [];
+    let current = this.path.dirname(absolutePath);
+
+    while (current !== this.targetDir && !this.fs.existsSync(current)) {
+      missing.push(current);
+      current = this.path.dirname(current);
+    }
+
+    if (current !== this.targetDir && this.pathKind(current) !== "directory") {
+      throw new Error(`目标父路径不是目录：${this.relative(current)}`);
+    }
+
+    for (const directory of missing.reverse()) {
+      this.fs.mkdirSync(directory);
+      this.createdDirectories.push(this.relative(directory));
+    }
+  }
+
+  mark(absolutePath) {
+    this.mutated.push(this.relative(absolutePath));
+  }
+
+  writeFile(absolutePath, content, options = "utf8") {
+    this.ensureParent(absolutePath);
+    this.fs.writeFileSync(absolutePath, content, options);
+    this.mark(absolutePath);
+  }
+
+  copyFile(sourcePath, destinationPath) {
+    this.ensureParent(destinationPath);
+    this.copyPath(sourcePath, destinationPath);
+    this.mark(destinationPath);
+  }
+
+  remove(absolutePath) {
+    if (!this.fs.existsSync(absolutePath)) return;
+    this.fs.rmSync(absolutePath, { recursive: true, force: true });
+    this.mark(absolutePath);
+  }
+
+  move(sourcePath, destinationPath) {
+    this.ensureParent(destinationPath);
+    this.copyPath(sourcePath, destinationPath);
+    this.mark(destinationPath);
+    this.remove(sourcePath);
+  }
+
+  rollback() {
+    for (const relativePath of [...new Set(this.mutated)].sort(
+      (left, right) => right.split("/").length - left.split("/").length,
+    )) {
+      this.fs.rmSync(targetPath(this.targetDir, relativePath), {
+        recursive: true,
+        force: true,
+      });
+    }
+
+    for (const relativePath of [...new Set(this.createdDirectories)].sort(
+      (left, right) => right.split("/").length - left.split("/").length,
+    )) {
+      const directory = targetPath(this.targetDir, relativePath);
+      if (this.fs.existsSync(directory) && this.fs.readdirSync(directory).length === 0) {
+        this.fs.rmdirSync(directory);
+      }
+    }
+
+    for (const backup of [...this.backups].sort(
+      (left, right) =>
+        left.relativePath.split("/").length - right.relativePath.split("/").length,
+    )) {
+      this.copyPath(
+        backup.destination,
+        targetPath(this.targetDir, backup.relativePath),
+      );
+    }
+  }
+
+  finish() {
+    if (this.backups.length === 0) {
+      this.fs.rmSync(this.backupRoot, { recursive: true, force: true });
+      return null;
+    }
+    return this.backupRoot;
+  }
+}
+
+module.exports = {
+  FileTransaction,
+};

package/src/git/submodule.js

@@ -0,0 +1,115 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const GITLINK_MODE = "160000";
+const GITLINK_PATH_CACHE = new Map();
+
+function posixRelative(from, to) {
+  return path.relative(from, to).split(path.sep).join("/");
+}
+
+function parseGitmodules(content) {
+  const modules = [];
+  if (typeof content !== "string" || content.length === 0) return modules;
+  let current = null;
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    const name = line.match(/^\[submodule "(.+)"\]$/);
+    if (name) {
+      current = { name: name[1], path: "", url: "" };
+      modules.push(current);
+      continue;
+    }
+    if (!current) continue;
+    const pathMatch = line.match(/^path\s*=\s*(.+)$/);
+    if (pathMatch) {
+      current.path = pathMatch[1].trim().replace(/\\/g, "/").replace(/\/+$/, "");
+    }
+    const urlMatch = line.match(/^url\s*=\s*(.+)$/);
+    if (urlMatch) current.url = urlMatch[1].trim();
+  }
+  return modules;
+}
+
+function readGitmodules(repoRoot, deps = {}) {
+  const file = path.join(repoRoot, ".gitmodules");
+  const pathKind =
+    deps.pathKind ||
+    ((value) => {
+      try {
+        const stat = fs.lstatSync(value);
+        if (stat.isFile()) return "file";
+        if (stat.isDirectory()) return "directory";
+        return "other";
+      } catch (error) {
+        if (error.code === "ENOENT") return "missing";
+        throw error;
+      }
+    });
+  if (!fs.existsSync(file) || pathKind(file) !== "file") return [];
+  return parseGitmodules(fs.readFileSync(file, "utf8"));
+}
+
+function gitlinkPaths(repoRoot, deps = {}) {
+  const resolvedRoot = path.resolve(repoRoot);
+  const useCache = !deps.disableCache && !deps.spawn;
+  if (useCache && GITLINK_PATH_CACHE.has(resolvedRoot)) {
+    return GITLINK_PATH_CACHE.get(resolvedRoot);
+  }
+
+  const spawn = deps.spawn || spawnSync;
+  const result = spawn(
+    "git",
+    ["-C", resolvedRoot, "ls-files", "--stage", "-z"],
+    {
+      encoding: "utf8",
+      timeout: 5000,
+    },
+  );
+  const paths = new Set();
+  if (result.status === 0) {
+    for (const record of (result.stdout || "").split("\0")) {
+      const match = record.match(/^(160000)\s+[0-9a-f]+\s+\d+\s+(.+)$/i);
+      if (match) paths.add(match[2].replaceAll("\\", "/"));
+    }
+  }
+
+  if (useCache) GITLINK_PATH_CACHE.set(resolvedRoot, paths);
+  return paths;
+}
+
+function clearGitlinkPathCache(repoRoot = null) {
+  if (repoRoot === null) {
+    GITLINK_PATH_CACHE.clear();
+    return;
+  }
+  GITLINK_PATH_CACHE.delete(path.resolve(repoRoot));
+}
+
+function isGitSubmoduleMount(repoRoot, targetPathValue, deps = {}) {
+  const relative = posixRelative(repoRoot, path.resolve(targetPathValue));
+  if (
+    !relative ||
+    relative === "." ||
+    relative.startsWith("..") ||
+    path.isAbsolute(relative)
+  ) {
+    return false;
+  }
+  if (readGitmodules(repoRoot, deps).some((item) => item.path === relative)) return true;
+  return gitlinkPaths(repoRoot, deps).has(relative);
+}
+
+module.exports = {
+  GITLINK_MODE,
+  GITLINK_PATH_CACHE,
+  parseGitmodules,
+  readGitmodules,
+  gitlinkPaths,
+  clearGitlinkPathCache,
+  isGitSubmoduleMount,
+  posixRelative,
+};

package/src/git/worktree.js

@@ -0,0 +1,69 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { isGitSubmoduleMount, posixRelative } = require("./submodule");
+
+function collectGitRoots(start) {
+  const roots = [];
+  if (!start) return roots;
+  let current = path.resolve(start);
+  while (true) {
+    const gitPath = path.join(current, ".git");
+    let validGitEntry = false;
+    try {
+      const gitStat = fs.lstatSync(gitPath);
+      validGitEntry = gitStat.isDirectory() ? fs.readdirSync(gitPath).length > 0 : gitStat.isFile();
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    if (validGitEntry || fs.existsSync(path.join(current, ".gitmodules"))) roots.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return roots;
+}
+
+function gitShowSuperproject(cwd, spawn = spawnSync) {
+  const result = spawn("git", ["-C", cwd, "rev-parse", "--show-superproject-working-tree"], { encoding: "utf8", timeout: 5000 });
+  return result.status === 0 ? (result.stdout || "").trim() : "";
+}
+
+function gitAbbrevRef(cwd, spawn = spawnSync) {
+  const result = spawn("git", ["-C", cwd, "rev-parse", "--abbrev-ref", "HEAD"], { encoding: "utf8", timeout: 5000 });
+  return result.status === 0 ? (result.stdout || "").trim() : null;
+}
+
+function isEmptyDir(dir) {
+  if (!fs.existsSync(dir)) return true;
+  try {
+    return fs.readdirSync(dir).filter((name) => name !== "." && name !== "..").length === 0;
+  } catch {
+    return false;
+  }
+}
+
+function inspectCheckoutState(repoRoot, targetPathValue, deps = {}) {
+  const resolved = path.resolve(targetPathValue);
+  const relative = posixRelative(path.resolve(repoRoot), resolved);
+  const isMount = isGitSubmoduleMount(repoRoot, resolved, deps) || Boolean(fs.existsSync(path.join(resolved, ".git")) && gitShowSuperproject(resolved, deps.spawn || spawnSync));
+  const hasGit = fs.existsSync(path.join(resolved, ".git"));
+  if (isMount && !hasGit) return isEmptyDir(resolved) ? "empty-gitlink" : "uninitialized";
+  if (isMount && hasGit) return gitAbbrevRef(resolved, deps.spawn || spawnSync) === "HEAD" ? "detached-head" : "attached-branch";
+  if (!relative || relative.startsWith("..")) return null;
+  return null;
+}
+
+function gitDirtyWarning(targetDir, spawn = spawnSync) {
+  const probe = spawn("git", ["rev-parse", "--is-inside-work-tree"], { cwd: targetDir, encoding: "utf8", timeout: 5000 });
+  if (probe.status !== 0 || (probe.stdout || "").trim() !== "true") return null;
+  const status = spawn("git", ["status", "--porcelain"], { cwd: targetDir, encoding: "utf8", timeout: 5000 });
+  if (status.status === 0 && (status.stdout || "").trim()) {
+    return "警告：目标 Git worktree 存在未提交改动；CLI 不会自动 stash 或提交，请在结果后检查 git diff / git status";
+  }
+  return null;
+}
+
+module.exports = { collectGitRoots, gitShowSuperproject, gitAbbrevRef, isEmptyDir, inspectCheckoutState, gitDirtyWarning };

package/src/template/attach-planner-runtime.js

@@ -0,0 +1,51 @@
+"use strict";
+
+const {
+  classifyAttachOperations,
+  createAttachPlan,
+} = require("./attach-planner");
+const {
+  ownershipAwareUnmanagedReason,
+  decoratePlanWithOwnership,
+} = require("./ownership-runtime");
+const {
+  applyLifecycleToOperations,
+  decoratePlanWithLifecycle,
+} = require("./lifecycle-runtime");
+
+function buildAttachPlanFromRuntime({
+  targetDir,
+  desiredOperations,
+  migration,
+  warning = null,
+  getUnmanagedReason,
+  getPathKind,
+  getFileHash,
+}) {
+  const lifecycleOperations = applyLifecycleToOperations(desiredOperations);
+  const classified = classifyAttachOperations({
+    desiredOperations: lifecycleOperations,
+    getUnmanagedReason: (operation) =>
+      ownershipAwareUnmanagedReason(operation, getUnmanagedReason),
+    getPathKind,
+    getFileHash,
+  });
+
+  const basePlan = createAttachPlan({
+    targetDir,
+    classified,
+    migration,
+    warnings: warning ? [warning] : [],
+  });
+  const ownershipPlan = decoratePlanWithOwnership(basePlan, lifecycleOperations);
+  const plan = decoratePlanWithLifecycle(ownershipPlan, lifecycleOperations);
+
+  return {
+    classified,
+    plan,
+  };
+}
+
+module.exports = {
+  buildAttachPlanFromRuntime,
+};

package/src/template/attach-planner.js

@@ -0,0 +1,160 @@
+"use strict";
+
+function classifyAttachOperations({
+  desiredOperations = [],
+  getUnmanagedReason = () => null,
+  getPathKind,
+  getFileHash,
+}) {
+  if (typeof getPathKind !== "function") {
+    throw new TypeError("classifyAttachOperations requires getPathKind");
+  }
+  if (typeof getFileHash !== "function") {
+    throw new TypeError("classifyAttachOperations requires getFileHash");
+  }
+
+  const missing = [];
+  const matched = [];
+  const identity = [];
+  const conflicts = [];
+  const forceableConflicts = [];
+  const unsafe = [];
+
+  for (const operation of desiredOperations) {
+    const unmanagedReason = getUnmanagedReason(operation);
+    if (unmanagedReason) {
+      unsafe.push({ ...operation, reason: unmanagedReason });
+      continue;
+    }
+
+    const kind = getPathKind(operation);
+    if (kind === "missing") {
+      missing.push(operation);
+      continue;
+    }
+
+    if (kind !== "file") {
+      unsafe.push({
+        ...operation,
+        reason: `目标路径类型为 ${kind}，无法安全判断是否可以替换`,
+      });
+      continue;
+    }
+
+    const currentHash = getFileHash(operation);
+    if (currentHash === operation.desiredHash) {
+      matched.push(operation);
+    } else if (operation.identityConversion) {
+      identity.push(operation);
+    } else {
+      const conflict = {
+        ...operation,
+        reason:
+          operation.mergeStrategy === "manual"
+            ? "目标可定制文件已存在且内容不一致；mergeStrategy=manual，必须人工处理"
+            : "目标受管文件已存在且内容不一致",
+      };
+      conflicts.push(conflict);
+      if (operation.mergeStrategy !== "manual") {
+        forceableConflicts.push(conflict);
+      }
+    }
+  }
+
+  return {
+    missing,
+    matched,
+    identity,
+    conflicts,
+    forceableConflicts,
+    unsafe,
+    desiredOperations,
+  };
+}
+
+function createAttachPlan({
+  targetDir,
+  classified,
+  migration = null,
+  warnings = [],
+}) {
+  if (!classified || typeof classified !== "object") {
+    throw new TypeError("createAttachPlan requires classified attach operations");
+  }
+
+  const missing = classified.missing || [];
+  const matched = classified.matched || [];
+  const identity = classified.identity || [];
+  const classifiedConflicts = classified.conflicts || [];
+  const forceableConflicts = classified.forceableConflicts || classifiedConflicts;
+  const classifiedUnsafe = classified.unsafe || [];
+  const migrationConflicts = migration?.conflicts || [];
+  const migrationUnsafe = migration?.unsafe || [];
+
+  const conflicts = [
+    ...classifiedConflicts.map((operation) => ({
+      path: operation.relativePath,
+      reason: operation.reason,
+      forceable: forceableConflicts.includes(operation),
+      source: "managed-file",
+    })),
+    ...migrationConflicts.map((item) => ({
+      path: item.from || item.path || item.to,
+      from: item.from,
+      to: item.to,
+      reason: item.reason,
+      forceable: false,
+      source: "migration",
+    })),
+  ];
+  const unsafe = [
+    ...classifiedUnsafe.map((operation) => ({
+      path: operation.relativePath,
+      reason: operation.reason,
+      source: "managed-file",
+    })),
+    ...migrationUnsafe.map((item) => ({
+      path: item.path,
+      reason: item.reason,
+      source: "migration",
+    })),
+  ];
+
+  return {
+    operation: "attach",
+    targetDir,
+    template: null,
+    changes: [
+      ...missing.map((operation) => ({
+        action: "add",
+        path: operation.relativePath,
+      })),
+      ...identity.map((operation) => ({
+        action: "identity-convert",
+        path: operation.relativePath,
+      })),
+    ],
+    conflicts,
+    unsafe,
+    migration: migration || {
+      operations: [],
+      legacy: [],
+      conflicts: [],
+      unsafe: [],
+    },
+    warnings,
+    blocked: unsafe.length > 0 || migrationConflicts.length > 0,
+    stats: {
+      missing: missing.length,
+      matched: matched.length,
+      identity: identity.length,
+      conflicts: conflicts.length,
+      unsafe: unsafe.length,
+    },
+  };
+}
+
+module.exports = {
+  classifyAttachOperations,
+  createAttachPlan,
+};