@loomhelm/multi-task-flow 0.2.6 → 0.2.7

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

@@ -0,0 +1,245 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { gitText } from "./git";
+
+export const STATUS_READY = "待实现";
+export const STATUS_PARTIAL_PREFIX = "部分完成";
+export const STATUS_PENDING_DESIGN = "待设计";
+export const STATUS_SKIPPED = "跳过";
+export const STATUS_DONE = "已完成";
+export const STATUS_VOID = "作废";
+export const STATUS_REDESIGN_PREFIX = "重新设计";
+
+export type Json = Record<string, unknown>;
+export interface Candidate {
+  id: string;
+  title: string;
+  status: string;
+  path: string;
+  createdAt: string | null;
+  rank: number;
+}
+
+export function row(line: string): string[] {
+  let raw = line.trim();
+  if (raw.startsWith("|")) raw = raw.slice(1);
+  if (raw.endsWith("|")) raw = raw.slice(0, -1);
+  return raw.split("|").map((cell) => cell.trim());
+}
+
+export function separator(cells: string[]): boolean {
+  return (
+    cells.length > 0 &&
+    cells.every((cell) => {
+      const value = cell.replaceAll(":", "").trim();
+      return value === "" || [...value].every((char) => char === "-");
+    })
+  );
+}
+
+export function pathCell(value: string): string | null {
+  const text = value.trim();
+  const link = /^\s*\[[^\]]+\]\(([^)]+)\)\s*$/.exec(text);
+  return link?.[1]?.trim() ?? (text || null);
+}
+
+export function table(lines: string[]): {
+  columns: Record<string, number>;
+  start: number;
+  pathLabel: string;
+  mode: "status" | "lifecycle";
+} | null {
+  for (let index = 0; index + 1 < lines.length; index += 1) {
+    if (!lines[index]?.trimStart().startsWith("|")) continue;
+    const headers = row(lines[index] as string);
+    if (
+      !headers.length ||
+      separator(headers) ||
+      !separator(row(lines[index + 1] as string))
+    )
+      continue;
+    const map: Record<string, number> = {};
+    headers.forEach((header, position) => {
+      if (header) map[header.toLowerCase()] = position;
+    });
+    const pathLabel =
+      map.spec !== undefined ? "spec" : map.plan !== undefined ? "plan" : null;
+    if (!pathLabel) continue;
+    if (
+      map.id !== undefined &&
+      map.title !== undefined &&
+      map.status !== undefined
+    )
+      return {
+        columns: {
+          id: map.id,
+          title: map.title,
+          status: map.status,
+          path: map[pathLabel] as number,
+        },
+        start: index + 2,
+        pathLabel,
+        mode: "status",
+      };
+    if (
+      map.id !== undefined &&
+      map.title !== undefined &&
+      map.lifecycle !== undefined
+    )
+      return {
+        columns: {
+          id: map.id,
+          title: map.title,
+          lifecycle: map.lifecycle,
+          path: map[pathLabel] as number,
+        },
+        start: index + 2,
+        pathLabel,
+        mode: "lifecycle",
+      };
+    if (map.topic !== undefined && map.lifecycle !== undefined)
+      return {
+        columns: {
+          topic: map.topic,
+          lifecycle: map.lifecycle,
+          path: map[pathLabel] as number,
+        },
+        start: index + 2,
+        pathLabel,
+        mode: "lifecycle",
+      };
+  }
+  return null;
+}
+
+export function relOrAbs(root: string, path: string): string {
+  const relativePath = relative(resolve(root), resolve(path)).replaceAll(
+    "\\",
+    "/",
+  );
+  return relativePath.startsWith("../") ? resolve(path) : relativePath;
+}
+
+export function detectRoot(
+  root: string,
+): { mode: string; primary: string; fallback: string | null } | null {
+  const specs = join(root, "docs/specs");
+  const plan = join(root, "docs/plan");
+  if (existsSync(specs))
+    return {
+      mode: "specs",
+      primary: specs,
+      fallback: existsSync(plan) ? plan : null,
+    };
+  if (existsSync(plan))
+    return { mode: "plan_legacy", primary: plan, fallback: null };
+  return null;
+}
+
+export function findPaths(root: string, id: string): string[] {
+  if (!existsSync(root)) return [];
+  const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const directoryPattern = new RegExp(`^${escaped}(?:-|:).+`);
+  const matches: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !directoryPattern.test(entry.name)) continue;
+    for (const file of ["SPEC.md", "PLAN.md"]) {
+      const candidate = join(root, entry.name, file);
+      if (existsSync(candidate) && statSync(candidate).isFile())
+        matches.push(resolve(candidate));
+    }
+  }
+  return [...new Set(matches)];
+}
+
+export function resolveCandidate(
+  root: string,
+  id: string,
+  cell: string,
+  primary: string,
+  fallback: string | null,
+): { path: string | null; candidates: string[] } {
+  const raw = pathCell(cell);
+  if (raw) {
+    const direct = resolve(root, raw);
+    if (existsSync(direct) && statSync(direct).isFile())
+      return {
+        path: relOrAbs(root, direct),
+        candidates: [relOrAbs(root, direct)],
+      };
+  }
+  const primaryMatches = findPaths(primary, id);
+  const specOnly = primaryMatches.filter(
+    (path) => basename(path) === "SPEC.md",
+  );
+  if (primaryMatches.length === 1 || specOnly.length === 1) {
+    const selected = (
+      primaryMatches.length === 1 ? primaryMatches : specOnly
+    )[0] as string;
+    return {
+      path: relOrAbs(root, selected),
+      candidates: [relOrAbs(root, selected)],
+    };
+  }
+  if (primaryMatches.length)
+    return {
+      path: null,
+      candidates: primaryMatches.map((path) => relOrAbs(root, path)),
+    };
+  const fallbackMatches = fallback ? findPaths(fallback, id) : [];
+  const fallbackSpecs = fallbackMatches.filter(
+    (path) => basename(path) === "SPEC.md",
+  );
+  if (fallbackMatches.length === 1 || fallbackSpecs.length === 1) {
+    const selected = (
+      fallbackMatches.length === 1 ? fallbackMatches : fallbackSpecs
+    )[0] as string;
+    return {
+      path: relOrAbs(root, selected),
+      candidates: [relOrAbs(root, selected)],
+    };
+  }
+  return {
+    path: null,
+    candidates: fallbackMatches.map((path) => relOrAbs(root, path)),
+  };
+}
+
+export function createdAt(root: string, path: string): string | null {
+  const output = gitText(root, [
+    "log",
+    "--diff-filter=A",
+    "--follow",
+    "--format=%aI",
+    "--",
+    path,
+  ]);
+  if (!output) return null;
+  const lines = output.split(/\r?\n/).filter(Boolean);
+  return lines[lines.length - 1] ?? null;
+}
+
+export function statusRank(status: string): number {
+  return status.startsWith(STATUS_PARTIAL_PREFIX)
+    ? 0
+    : status === STATUS_READY
+      ? 1
+      : 99;
+}
+export function noPick(statuses: string[]): string {
+  if (statuses.some((status) => status.includes(STATUS_PENDING_DESIGN)))
+    return "no_implementable_has_pending_design";
+  if (statuses.some((status) => status.includes(STATUS_SKIPPED)))
+    return "no_implementable_has_skipped";
+  if (
+    statuses.length > 0 &&
+    statuses.every(
+      (status) =>
+        status === STATUS_DONE ||
+        status === STATUS_VOID ||
+        status.startsWith(STATUS_REDESIGN_PREFIX),
+    )
+  )
+    return "no_implementable_all_terminal";
+  return "no_implementable";
+}

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

@@ -0,0 +1,299 @@
+import { lstatSync, readFileSync, statSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { gitText } from "./git";
+
+const TOP_LEVEL_RE = /^##\s+(.+?)\s*$/;
+const REQ_RE = /\bREQ-[A-Z0-9][A-Z0-9_-]*\b/g;
+const VER_RE = /\bVER-[A-Z0-9][A-Z0-9_-]*\b/g;
+const NORMATIVE_RE =
+  /\b(MUST|SHALL|SHOULD|MAY NOT|MUST NOT)\b|必须|不得|仅可|只能|应当|不可/i;
+const UNRESOLVED_RE =
+  /\b(TBD|TBA|TBC|TODO|TO BE DETERMINED|TO BE CONFIRMED|OPEN QUESTION)\b|待确认|待定|未决/i;
+const FORBIDDEN_HEADINGS = new Set([
+  "acceptance checklist",
+  "quality gates",
+  "related prs",
+  "related pr",
+  "pull requests",
+  "pr checklist",
+  "related changes",
+  "test commands",
+  "verification commands",
+  "risks",
+  "open questions",
+  "assumptions",
+  "task orchestration",
+  "execution steps",
+  "current status",
+  "milestones",
+  "implementation status",
+  "delivery status",
+  "execution",
+]);
+
+export interface SpecIssue {
+  path: string;
+  code: string;
+  message: string;
+  line?: number;
+}
+
+function emit(
+  path: string,
+  code: string,
+  message: string,
+  line?: number,
+): SpecIssue {
+  return { path, code, message, ...(line === undefined ? {} : { line }) };
+}
+
+function repoRelative(path: string, root: string): string | null {
+  const rel = relative(resolve(root), resolve(path)).replaceAll("\\", "/");
+  return rel === "" || (!rel.startsWith("../") && rel !== "..") ? rel : null;
+}
+
+function regularFile(path: string): boolean {
+  try {
+    return lstatSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function collectIds(text: string, pattern: RegExp): string[] {
+  return [...new Set(text.match(pattern) ?? [])].sort();
+}
+
+function headingBodies(
+  lines: string[],
+): Map<string, { line: number; body: string[] }> {
+  const headings = new Map<string, { line: number; body: string[] }>();
+  let current: { name: string; line: number; body: string[] } | undefined;
+  for (const [index, line] of lines.entries()) {
+    const match = TOP_LEVEL_RE.exec(line);
+    if (match?.[1] !== undefined) {
+      if (current)
+        headings.set(current.name, { line: current.line, body: current.body });
+      current = { name: match[1].trim(), line: index + 1, body: [] };
+    } else if (current) {
+      current.body.push(line);
+    }
+  }
+  if (current)
+    headings.set(current.name, { line: current.line, body: current.body });
+  return headings;
+}
+
+export function repositoryRoot(cwd = process.cwd()): string {
+  return gitText(cwd, ["rev-parse", "--show-toplevel"])?.trim() ?? cwd;
+}
+
+export function checkSpec(path: string, root: string): SpecIssue[] {
+  const absolute = resolve(path);
+  const rel = repoRelative(absolute, root);
+  if (rel === null) {
+    return [
+      emit(
+        absolute,
+        "SPEC_PATH_INVALID",
+        "Spec path must remain inside the repository root",
+      ),
+    ];
+  }
+  if (!/^docs\/specs\/[a-z0-9]+(?:-[a-z0-9]+)*\/SPEC\.md$/.test(rel)) {
+    return [
+      emit(
+        rel,
+        "SPEC_PATH_INVALID",
+        "strict checking only applies to canonical docs/specs/<slug>/SPEC.md",
+      ),
+    ];
+  }
+  if (!regularFile(absolute)) {
+    return [emit(rel, "SPEC_NOT_REGULAR_FILE", "Spec must be a regular file")];
+  }
+
+  const lines = readFileSync(absolute, "utf8").split(/\r?\n/);
+  const headings = headingBodies(lines);
+  const errors: SpecIssue[] = [];
+  for (const required of [
+    "Context and Scope",
+    "Requirements",
+    "Verification",
+    "Related ADRs",
+  ]) {
+    if (!headings.has(required))
+      errors.push(
+        emit(
+          rel,
+          "SPEC_SECTION_MISSING",
+          `missing required section: ## ${required}`,
+        ),
+      );
+  }
+  for (const [heading, value] of headings) {
+    const normalized = heading.toLowerCase().trim();
+    if (
+      [...FORBIDDEN_HEADINGS].some(
+        (forbidden) =>
+          normalized === forbidden || normalized.startsWith(`${forbidden} `),
+      )
+    ) {
+      errors.push(
+        emit(
+          rel,
+          "SPEC_FORBIDDEN_SECTION",
+          `task-state or execution section is not allowed in SPEC.md: ## ${heading}`,
+          value.line,
+        ),
+      );
+    }
+  }
+  for (const [index, line] of lines.entries()) {
+    if (/^\s*-\s*\[[ xX]\]/.test(line))
+      errors.push(
+        emit(
+          rel,
+          "SPEC_CHECKBOX_FORBIDDEN",
+          "SPEC.md cannot contain checkbox progress",
+          index + 1,
+        ),
+      );
+  }
+
+  const requirements = headings.get("Requirements")?.body.join("\n") ?? "";
+  const verification = headings.get("Verification")?.body.join("\n") ?? "";
+  const reqIds = collectIds(requirements, REQ_RE);
+  const verIds = collectIds(verification, VER_RE);
+  if (reqIds.length === 0)
+    errors.push(
+      emit(
+        rel,
+        "SPEC_REQUIREMENTS_MISSING",
+        "Requirements must declare stable REQ-* identifiers",
+      ),
+    );
+  if (verIds.length === 0)
+    errors.push(
+      emit(
+        rel,
+        "SPEC_VERIFICATION_MISSING",
+        "Verification must declare stable VER-* identifiers",
+      ),
+    );
+  if (requirements && !NORMATIVE_RE.test(requirements))
+    errors.push(
+      emit(
+        rel,
+        "SPEC_NORMATIVE_BOUNDARY_MISSING",
+        "Requirements must contain normative MUST/SHALL or Chinese normative language",
+      ),
+    );
+  for (const id of reqIds) {
+    const pattern = new RegExp(
+      `(?:covers?|覆盖)\\s*[:=]\\s*[^\\n]*\\b${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`,
+      "i",
+    );
+    if (!pattern.test(verification))
+      errors.push(
+        emit(
+          rel,
+          "SPEC_TRACEABILITY_MISSING",
+          `no VER-* verification explicitly covers ${id}`,
+        ),
+      );
+  }
+  for (const id of verIds) {
+    if (!new RegExp(`\\b${id}\\b`).test(verification))
+      errors.push(
+        emit(
+          rel,
+          "SPEC_VERIFICATION_INVALID",
+          `verification id ${id} is not readable`,
+        ),
+      );
+  }
+
+  const related =
+    headings.get("Related ADRs")?.body.filter((line) => line.trim()) ?? [];
+  if (headings.has("Related ADRs")) {
+    if (related.length === 0)
+      errors.push(
+        emit(
+          rel,
+          "SPEC_RELATED_ADRS_INVALID",
+          "Related ADRs must be exactly None or contain ADR links",
+        ),
+      );
+    else if (related.length !== 1 || related[0] !== "None") {
+      const paths: string[] = [];
+      for (const line of related) {
+        const match =
+          /^-\s+\[[^\]]+\]\(\.\.\/\.\.\/(adr\/[0-9]{4}-[a-z0-9]+(?:-[a-z0-9]+)*\.md)\)$/.exec(
+            line,
+          );
+        if (!match?.[1]) {
+          errors.push(
+            emit(
+              rel,
+              "SPEC_RELATED_ADRS_INVALID",
+              `invalid Related ADRs entry: ${line}`,
+            ),
+          );
+          continue;
+        }
+        const adr = `docs/${match[1]}`;
+        paths.push(adr);
+        try {
+          if (!statSync(resolve(root, adr)).isFile())
+            errors.push(
+              emit(
+                rel,
+                "SPEC_RELATED_ADRS_INVALID",
+                `missing ADR target: ${adr}`,
+              ),
+            );
+        } catch {
+          errors.push(
+            emit(
+              rel,
+              "SPEC_RELATED_ADRS_INVALID",
+              `missing ADR target: ${adr}`,
+            ),
+          );
+        }
+      }
+      if (paths.join("\n") !== [...new Set(paths)].sort().join("\n"))
+        errors.push(
+          emit(
+            rel,
+            "SPEC_RELATED_ADRS_INVALID",
+            "Related ADRs must be path-sorted and duplicate-free",
+          ),
+        );
+    }
+  }
+  for (const [index, line] of lines.entries()) {
+    if (
+      UNRESOLVED_RE.test(line) &&
+      !line.trimStart().startsWith(">") &&
+      !line.trimStart().startsWith("<!--")
+    )
+      errors.push(
+        emit(
+          rel,
+          "SPEC_UNRESOLVED_DECISION",
+          "unresolved decision markers do not belong in canonical SPEC.md",
+          index + 1,
+        ),
+      );
+  }
+  return errors;
+}
+
+export function checkSpecs(
+  paths: string[],
+  root = repositoryRoot(),
+): SpecIssue[] {
+  return paths.flatMap((path) => checkSpec(resolve(root, path), root));
+}