@loomhelm/multi-task-flow 0.2.1 → 0.2.7

package/toolkit/skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_legacy.ts

@@ -0,0 +1,376 @@
+import {
+  existsSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { gitRefExists } from "./git";
+import { catalogConfirmsLegacyId } from "./migration_common";
+import type { DriftPathContext } from "./spec_drift_types";
+
+export function pathCountsAsSpecSync(
+  path: string,
+  root: string,
+  associatedSpec: string,
+): boolean {
+  if (!root || !path.startsWith(`${root}/`)) return false;
+  const relativePathValue = path.slice(root.length + 1);
+  if (
+    ["SPEC.md", "IMPLEMENTATION.md", "HISTORY.md"].includes(relativePathValue)
+  )
+    return true;
+  if (relativePathValue === "PLAN.md")
+    return /^(docs\/plan|docs\/specs)\/.+\/PLAN\.md$/.test(associatedSpec);
+  return relativePathValue.startsWith("contracts/");
+}
+
+export function specTargetFromChangedPath(path: string): string | null {
+  if (path.startsWith("docs/plan/")) {
+    const relativePathValue = path.slice("docs/plan/".length);
+    const root = relativePathValue.split("/")[0];
+    return root ? `docs/plan/${root}/PLAN.md` : null;
+  }
+  if (/^docs\/specs\/[^/]+\/PLAN\.md$/.test(path)) return path;
+  if (path.startsWith("docs/specs/")) {
+    const root = path.slice("docs/specs/".length).split("/")[0];
+    return root ? `docs/specs/${root}/SPEC.md` : null;
+  }
+  return null;
+}
+
+export function isLegacySpecDirName(name: string): boolean {
+  return /^\d{4}(?:$|[-:])/.test(name) || /^[a-z0-9]{5}[-:]/i.test(name);
+}
+
+export function extractSpecId(path: string): string {
+  const match = /^(?:docs\/specs|docs\/plan)\/([^/]+)\//.exec(path);
+  if (!match?.[1]) return "";
+  return match[1].split(/[-:]/, 1)[0] ?? "";
+}
+
+export function legacyTopicFromDir(directory: string): string {
+  if (/^\d{4}[-:]/.test(directory)) return directory.slice(5);
+  if (/^[a-z0-9]{5}[-:]/i.test(directory)) return directory.slice(6);
+  return directory;
+}
+
+export function pathExists(path: string): boolean {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function file(path: string): boolean {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function directory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function catalogProves(repoRoot: string, sourcePath: string): boolean {
+  const match = /^(docs\/(?:plan|specs)\/[^/]+\/(?:PLAN|SPEC)\.md)$/.exec(
+    sourcePath,
+  );
+  if (!match) return false;
+  const root = dirname(sourcePath);
+  const name = basename(root);
+  if (!isLegacySpecDirName(name)) return false;
+  const id = extractSpecId(sourcePath);
+  const catalog = sourcePath.startsWith("docs/plan/")
+    ? "docs/plan/README.md"
+    : "docs/specs/README.md";
+  const relativeToCatalog = sourcePath.slice(dirname(catalog).length + 1);
+  return Boolean(
+    (id && catalogConfirmsLegacyId(repoRoot, catalog, sourcePath, id)) ||
+    (id && catalogConfirmsLegacyId(repoRoot, catalog, relativeToCatalog, id)),
+  );
+}
+
+function historyProves(repoRoot: string, sourcePath: string): boolean {
+  if (!sourcePath.startsWith("docs/specs/") || !sourcePath.endsWith("/SPEC.md"))
+    return false;
+  const directoryName = basename(dirname(sourcePath));
+  if (!isLegacySpecDirName(directoryName)) return false;
+  const id = extractSpecId(sourcePath);
+  const topic = legacyTopicFromDir(directoryName);
+  const history = resolve(repoRoot, `docs/specs/${topic}/HISTORY.md`);
+  if (!id || !file(history)) return false;
+  return new RegExp(
+    `^\\s*-\\s*Legacy compatibility identity:\\s*\`#?${id}\`(?:\\s|\\.|$)`,
+    "m",
+  ).test(readFileSync(history, "utf8"));
+}
+
+function legacyProof(repoRoot: string, sourcePath: string): boolean {
+  return (
+    catalogProves(repoRoot, sourcePath) || historyProves(repoRoot, sourcePath)
+  );
+}
+
+function renameMatches(
+  context: DriftPathContext,
+  oldPath: string,
+  newPath: string,
+): boolean {
+  if (
+    !oldPath.startsWith("docs/specs/") ||
+    !oldPath.endsWith("/SPEC.md") ||
+    !newPath.startsWith("docs/specs/") ||
+    !newPath.endsWith("/SPEC.md")
+  )
+    return false;
+  const oldDirectory = basename(dirname(oldPath));
+  const newDirectory = basename(dirname(newPath));
+  if (
+    !isLegacySpecDirName(oldDirectory) ||
+    !legacyProof(context.repoRoot, oldPath)
+  )
+    return false;
+  const oldId = extractSpecId(oldPath);
+  if (isLegacySpecDirName(newDirectory))
+    return oldId !== "" && oldId === extractSpecId(newPath);
+  return newDirectory === legacyTopicFromDir(oldDirectory);
+}
+
+function movedTarget(
+  context: DriftPathContext,
+  oldPath: string,
+): string | null | "ambiguous" {
+  const direct = context.renamePairs.find(
+    (pair) =>
+      pair.oldPath === oldPath &&
+      pair.newPath.startsWith("docs/specs/") &&
+      pair.newPath.endsWith("/SPEC.md") &&
+      renameMatches(context, pair.oldPath, pair.newPath),
+  );
+  if (direct) return direct.newPath;
+  if (!legacyProof(context.repoRoot, oldPath)) return null;
+  const id = extractSpecId(oldPath);
+  const candidates = new Set<string>();
+  for (const path of context.changedFiles)
+    if (
+      path.startsWith(`docs/specs/${id}-`) ||
+      path.startsWith(`docs/specs/${id}:`)
+    )
+      if (
+        path.endsWith("/SPEC.md") &&
+        pathExists(resolve(context.repoRoot, path)) &&
+        renameMatches(context, oldPath, path)
+      )
+        candidates.add(path);
+  const specsRoot = resolve(context.repoRoot, "docs/specs");
+  if (directory(specsRoot))
+    for (const entry of readdirSync(specsRoot, { withFileTypes: true }))
+      if (
+        entry.isDirectory() &&
+        (entry.name.startsWith(`${id}-`) || entry.name.startsWith(`${id}:`))
+      ) {
+        const path = `docs/specs/${entry.name}/SPEC.md`;
+        if (
+          file(resolve(context.repoRoot, path)) &&
+          renameMatches(context, oldPath, path)
+        )
+          candidates.add(path);
+      }
+  if (candidates.size === 1) return [...candidates][0] as string;
+  return candidates.size > 1 ? "ambiguous" : null;
+}
+
+function resolveLegacyPlan(
+  context: DriftPathContext,
+  path: string,
+): string | null | "ambiguous" {
+  const match = /^(?:docs\/plan|docs\/specs)\/([^/]+)\/PLAN\.md$/.exec(path);
+  if (!match?.[1]) return null;
+  const relativeDirectory = match[1];
+  const candidates = new Set<string>();
+  const direct = `docs/specs/${relativeDirectory}/SPEC.md`;
+  if (pathExists(resolve(context.repoRoot, direct))) candidates.add(direct);
+  if (legacyProof(context.repoRoot, path)) {
+    const topic = legacyTopicFromDir(relativeDirectory);
+    const slug = `docs/specs/${topic}/SPEC.md`;
+    if (file(resolve(context.repoRoot, slug))) candidates.add(slug);
+    const id = extractSpecId(path);
+    const root = resolve(context.repoRoot, "docs/specs");
+    if (directory(root))
+      for (const entry of readdirSync(root, { withFileTypes: true }))
+        if (
+          entry.isDirectory() &&
+          (entry.name.startsWith(`${id}-`) || entry.name.startsWith(`${id}:`))
+        ) {
+          const candidate = `docs/specs/${entry.name}/SPEC.md`;
+          if (file(resolve(context.repoRoot, candidate)))
+            candidates.add(candidate);
+        }
+  }
+  if (candidates.size === 1) return [...candidates][0] as string;
+  return candidates.size > 1 ? "ambiguous" : null;
+}
+
+function resolveLegacySpec(
+  context: DriftPathContext,
+  path: string,
+): string | null | "ambiguous" {
+  if (!/^docs\/specs\/[^/]+\/SPEC\.md$/.test(path)) return null;
+  const directoryName = basename(dirname(path));
+  if (
+    pathExists(resolve(context.repoRoot, path)) &&
+    isLegacySpecDirName(directoryName) &&
+    legacyProof(context.repoRoot, path)
+  ) {
+    const slug = `docs/specs/${legacyTopicFromDir(directoryName)}/SPEC.md`;
+    if (file(resolve(context.repoRoot, slug)) && slug !== path) return slug;
+  }
+  if (pathExists(resolve(context.repoRoot, path))) return path;
+  const moved = movedTarget(context, path);
+  if (moved) return moved;
+  if (moved === "ambiguous") return "ambiguous";
+  if (!legacyProof(context.repoRoot, path)) return path;
+  const id = extractSpecId(path);
+  const topic = legacyTopicFromDir(directoryName);
+  const candidates = [`docs/specs/${topic}/SPEC.md`];
+  const root = resolve(context.repoRoot, "docs/specs");
+  if (directory(root))
+    for (const entry of readdirSync(root, { withFileTypes: true }))
+      if (
+        entry.isDirectory() &&
+        (entry.name.startsWith(`${id}-`) || entry.name.startsWith(`${id}:`))
+      )
+        candidates.push(`docs/specs/${entry.name}/SPEC.md`);
+  const existing = [
+    ...new Set(
+      candidates.filter((candidate) =>
+        file(resolve(context.repoRoot, candidate)),
+      ),
+    ),
+  ];
+  return existing.length === 1
+    ? (existing[0] as string)
+    : existing.length > 1
+      ? "ambiguous"
+      : path;
+}
+
+export function resolveAssociatedSpecPath(
+  context: DriftPathContext,
+  path: string,
+): string | null | "ambiguous" {
+  if (/^(?:docs\/plan|docs\/specs)\/[^/]+\/PLAN\.md$/.test(path))
+    return resolveLegacyPlan(context, path) ?? path;
+  if (/^docs\/specs\/[^/]+\/SPEC\.md$/.test(path))
+    return resolveLegacySpec(context, path) ?? path;
+  if (legacyProof(context.repoRoot, path)) {
+    const id = extractSpecId(path);
+    const root = resolve(context.repoRoot, "docs/specs");
+    if (directory(root))
+      for (const entry of readdirSync(root, { withFileTypes: true }))
+        if (
+          entry.isDirectory() &&
+          (entry.name.startsWith(`${id}-`) || entry.name.startsWith(`${id}:`))
+        )
+          return `docs/specs/${entry.name}/SPEC.md`;
+  }
+  return path;
+}
+
+function compareRefHas(context: DriftPathContext, path: string): boolean {
+  return gitRefExists(context.repoRoot, `${context.baseRef}:${path}`);
+}
+
+export function grandfatheredLegacyRename(
+  context: DriftPathContext,
+  newPath: string,
+): boolean {
+  const oldPaths = context.renamePairs
+    .filter((pair) => pair.newPath === newPath)
+    .map((pair) => pair.oldPath)
+    .concat(context.deletedFiles);
+  return oldPaths.some(
+    (oldPath) =>
+      oldPath !== newPath &&
+      renameMatches(context, oldPath, newPath) &&
+      compareRefHas(context, oldPath) &&
+      !compareRefHas(context, `${dirname(oldPath)}/IMPLEMENTATION.md`) &&
+      !compareRefHas(context, `${dirname(oldPath)}/HISTORY.md`),
+  );
+}
+
+export function requiredSpecFiles(
+  context: DriftPathContext,
+  specPath: string,
+): string[] {
+  if (/^(?:docs\/plan|docs\/specs)\/[^/]+\/PLAN\.md$/.test(specPath)) {
+    if (compareRefHas(context, specPath)) return [specPath];
+    const topic = legacyTopicFromDir(basename(dirname(specPath)));
+    const canonicalRoot = `docs/specs/${topic}`;
+    return [
+      `${canonicalRoot}/SPEC.md`,
+      `${canonicalRoot}/IMPLEMENTATION.md`,
+      `${canonicalRoot}/HISTORY.md`,
+    ];
+  }
+  const root = dirname(specPath);
+  const implementation = `${root}/IMPLEMENTATION.md`;
+  const history = `${root}/HISTORY.md`;
+  const isNew =
+    !compareRefHas(context, specPath) &&
+    !grandfatheredLegacyRename(context, specPath);
+  const needsCompanions =
+    isNew ||
+    compareRefHas(context, implementation) ||
+    compareRefHas(context, history) ||
+    pathExists(resolve(context.repoRoot, implementation)) ||
+    pathExists(resolve(context.repoRoot, history)) ||
+    context.deletedFiles.includes(implementation) ||
+    context.deletedFiles.includes(history);
+  return [
+    `${root}/SPEC.md`,
+    ...(needsCompanions ? [implementation, history] : []),
+  ];
+}
+
+export function sourceRequiresRelatedAdrs(
+  context: DriftPathContext,
+  source: string,
+  target: string,
+): boolean {
+  if (
+    !/^docs\/specs\/[^/]+\/SPEC\.md$/.test(target) ||
+    source !== target ||
+    !context.changedFiles.includes(target)
+  )
+    return false;
+  if (
+    legacyProof(context.repoRoot, target) ||
+    grandfatheredLegacyRename(context, target)
+  )
+    return false;
+  return !context.renamePairs.some(
+    (pair) =>
+      pair.newPath === target && renameMatches(context, pair.oldPath, target),
+  );
+}
+
+export function specAllowsLegacyRelatedAdrsNone(
+  context: DriftPathContext,
+  spec: string,
+): boolean {
+  return (
+    legacyProof(context.repoRoot, spec) ||
+    grandfatheredLegacyRename(context, spec)
+  );
+}

package/toolkit/skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_paths.ts

@@ -0,0 +1,3 @@
+export * from "./spec_drift_types";
+export * from "./spec_drift_legacy";
+export * from "./spec_drift_validation";

package/toolkit/skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_types.ts

@@ -0,0 +1,27 @@
+export interface DriftPathContext {
+  repoRoot: string;
+  baseRef: string;
+  changedFiles: string[];
+  deletedFiles: string[];
+  renamePairs: RenamePair[];
+}
+
+export interface RenamePair {
+  oldPath: string;
+  newPath: string;
+}
+
+export interface RelatedAdrResult {
+  ok: boolean;
+  paths: string[];
+  error?: string;
+}
+
+export interface DriftResult {
+  exitCode: 0 | 2 | 3;
+  status: "通过" | "阻断" | "未检查";
+  drift: "不存在" | "存在" | "未检查";
+  evidence: string;
+  reason: string;
+  stdout: string;
+}

package/toolkit/skills/docs-migrate/scripts/_runtime/modules/docs/spec_drift_validation.ts

@@ -0,0 +1,251 @@
+import { readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { gitFileText, gitRefExists, gitText } from "./git";
+import { isTopicSlug } from "./migration_common";
+import { file, pathExists } from "./spec_drift_legacy";
+import type { DriftPathContext, RelatedAdrResult } from "./spec_drift_types";
+
+export function relatedAdrPaths(
+  text: string,
+  allowLegacyNone: boolean,
+  requireSection: boolean,
+): RelatedAdrResult {
+  let inSection = false;
+  let headingCount = 0;
+  let noneCount = 0;
+  let sawLink = false;
+  let previous = "";
+  const paths: string[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    if (/^##\s+/.test(line)) {
+      if (line === "## Related ADRs" || /^## Related ADRs\s+$/.test(line)) {
+        headingCount += 1;
+        inSection = true;
+        continue;
+      }
+      if (inSection) inSection = false;
+    }
+    if (!inSection || !line.trim()) continue;
+    if (line === "None" || (allowLegacyNone && line === "- None")) {
+      noneCount += 1;
+      continue;
+    }
+    const match =
+      /^-\s+\[[^\]]+\]\(\.\.\/\.\.\/(adr\/[0-9]{4}-[a-z0-9]+(?:-[a-z0-9]+)*\.md)\)$/.exec(
+        line,
+      );
+    if (!match?.[1])
+      return {
+        ok: false,
+        paths,
+        error: "entries must be None or canonical ADR links",
+      };
+    const path = `docs/${match[1]}`;
+    if (previous && path <= previous)
+      return { ok: false, paths, error: "ADR paths must be unique and sorted" };
+    previous = path;
+    paths.push(path);
+    sawLink = true;
+  }
+  if (headingCount === 0)
+    return requireSection
+      ? { ok: false, paths, error: "slug-only Specs require the section" }
+      : { ok: true, paths };
+  if (headingCount !== 1)
+    return { ok: false, paths, error: "section must appear exactly once" };
+  if ((noneCount > 0 && sawLink) || (noneCount !== 1 && !sawLink))
+    return {
+      ok: false,
+      paths,
+      error: "use exactly None or one or more ADR links",
+    };
+  return { ok: true, paths };
+}
+
+export function adrStatus(text: string): string {
+  const lines = text.split(/\r?\n/);
+  if (lines[0] !== "---") return "";
+  for (const line of lines.slice(1)) {
+    if (line === "---") break;
+    const match = /^status:\s*(.*?)\s*$/.exec(line);
+    if (match?.[1]) return match[1];
+  }
+  return "";
+}
+
+export function validateRelatedAdrs(
+  context: DriftPathContext,
+  spec: string,
+  requireSection: boolean,
+  allowLegacyNone: boolean,
+): RelatedAdrResult {
+  if (!spec.startsWith("docs/specs/") || !spec.endsWith("/SPEC.md"))
+    return { ok: true, paths: [] };
+  const current = resolve(context.repoRoot, spec);
+  if (pathExists(current)) {
+    if (!file(current))
+      return {
+        ok: false,
+        paths: [],
+        error: `candidate Spec must be a regular file`,
+      };
+    const parsed = relatedAdrPaths(
+      readFileSync(current, "utf8"),
+      allowLegacyNone,
+      requireSection,
+    );
+    if (!parsed.ok)
+      return {
+        ok: false,
+        paths: parsed.paths,
+        error: `entries in candidate ${spec}: ${parsed.error}`,
+      };
+    const targetError = validateAdrTargets(
+      context,
+      parsed.paths,
+      "candidate",
+      false,
+    );
+    if (targetError)
+      return { ok: false, paths: parsed.paths, error: targetError };
+  }
+  const indexEntry =
+    gitText(context.repoRoot, ["ls-files", "-s", "--", spec]) ?? "";
+  if (indexEntry) {
+    if (!/^(?:100644|100755)\s+[0-9a-f]{40}\s+0\s/.test(indexEntry))
+      return { ok: false, paths: [], error: `Spec must be a regular file` };
+    const staged = gitFileText(context.repoRoot, ":", spec);
+    if (staged === null)
+      return { ok: false, paths: [], error: "cannot read staged Spec" };
+    const parsed = relatedAdrPaths(staged, allowLegacyNone, requireSection);
+    if (!parsed.ok)
+      return {
+        ok: false,
+        paths: parsed.paths,
+        error: `entries in index ${spec}: ${parsed.error}`,
+      };
+    const targetError = validateAdrTargets(
+      context,
+      parsed.paths,
+      "index",
+      true,
+    );
+    if (targetError)
+      return { ok: false, paths: parsed.paths, error: targetError };
+    return { ok: true, paths: parsed.paths };
+  }
+  if (
+    pathExists(current) &&
+    gitRefExists(context.repoRoot, `${context.baseRef}:${spec}`)
+  )
+    return { ok: false, paths: [], error: "staged candidate removed Spec" };
+  return { ok: true, paths: [] };
+}
+
+function validateAdrTargets(
+  context: DriftPathContext,
+  paths: string[],
+  label: string,
+  index: boolean,
+): string | null {
+  for (const path of paths) {
+    let text: string | null;
+    if (index) {
+      const entry =
+        gitText(context.repoRoot, ["ls-files", "-s", "--", path]) ?? "";
+      if (!/^(?:100644|100755)\s+[0-9a-f]{40}\s+0\s/.test(entry))
+        return `missing ADR target ${path} (not a regular index file)`;
+      text = gitFileText(context.repoRoot, ":", path);
+      if (text === null) return `cannot read staged ADR target ${path}`;
+    } else {
+      const candidate = resolve(context.repoRoot, path);
+      if (!file(candidate))
+        return `missing ADR target ${path} (not a regular file)`;
+      text = readFileSync(candidate, "utf8");
+    }
+    const status = adrStatus(text);
+    if (status === "superseded" || status === "deprecated")
+      return `ADR ${path} is ${status}`;
+    if (status && status !== "accepted")
+      return `ADR ${path} has non-accepted status ${status}`;
+  }
+  return null;
+}
+
+export function isImplementationPath(path: string): boolean {
+  if (
+    path.startsWith("docs/") ||
+    path.startsWith("README") ||
+    path.startsWith(".github/")
+  )
+    return false;
+  const base = basename(path);
+  if ([".DS_Store"].includes(base) || /\.(log|tmp|swp|bak)$/.test(base))
+    return false;
+  if (
+    /^(src|app|web\/src|server|backend|frontend|cmd|pkg|internal|services|modules|crates|libs)\//.test(
+      path,
+    )
+  )
+    return true;
+  if (
+    /^(Dockerfile|Containerfile|Makefile|GNUmakefile|Procfile|Gemfile|Rakefile|Vagrantfile|Jenkinsfile)$/.test(
+      base,
+    )
+  )
+    return true;
+  if (
+    /\.(c|cc|cpp|h|hpp|rs|go|py|ts|tsx|js|jsx|mjs|cjs|java|kt|swift|rb|php|cs|sh|bash|zsh|toml|json|yaml|yml)$/.test(
+      path,
+    )
+  )
+    return true;
+  return !base.includes(".");
+}
+
+export function parseNameStatus(
+  line: string,
+): { status: string; path1: string; path2?: string } | null {
+  const tab = line.indexOf("\t");
+  if (!line || tab < 0) return null;
+  const status = line.slice(0, tab);
+  const rest = line.slice(tab + 1);
+  if (/^[RC]/.test(status)) {
+    const split = rest.indexOf("\t");
+    if (split < 0) return null;
+    return {
+      status,
+      path1: rest.slice(0, split),
+      path2: rest.slice(split + 1),
+    };
+  }
+  return { status, path1: rest };
+}
+
+export function pathDeleted(context: DriftPathContext, path: string): boolean {
+  return context.deletedFiles.includes(path);
+}
+
+export function currentHash(context: DriftPathContext, path: string): string {
+  return (
+    gitText(context.repoRoot, ["hash-object", path])?.trim() ||
+    gitText(context.repoRoot, [
+      "rev-parse",
+      "--verify",
+      `HEAD:${path}`,
+    ])?.trim() ||
+    "unknown"
+  );
+}
+
+export function frozenAdrMembership(
+  context: DriftPathContext,
+  spec: string,
+): string[] {
+  const text = gitFileText(context.repoRoot, ":", spec);
+  return text ? relatedAdrPaths(text, false, false).paths : [];
+}
+
+export function slugOnly(value: string): boolean {
+  return isTopicSlug(value);
+}