@brainervirus/workit-core 0.6.0 → 0.7.0

package/src/core/docs-repo.ts

@@ -2,10 +2,10 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from
 import { execFileSync } from "node:child_process";
 import path from "node:path";
 import { configDir } from "./config";
+import { resolveCanonicalLayout } from "./docs-layout";
 
 const configPath = () =>
-  process.env.WORKFLOW_DOCS_REPO_CONFIG
-  ?? path.join(configDir(), "docs-repo.json");
+  process.env.WORKFLOW_DOCS_REPO_CONFIG ?? path.join(configDir(), "docs-repo.json");
 
 export const readDocsRepoConfig = (): { path: string } | null => {
   try {
@@ -25,7 +25,8 @@ export const writeDocsRepoConfig = (docsPath: string): void => {
 export const docsRepoPath = (): string | null => readDocsRepoConfig()?.path ?? null;
 
 export const validateDocsRepo = (docsPath: string): { ok: true } | { ok: false; error: string } => {
-  if (!existsSync(docsPath)) return { ok: false, error: `docs repo path does not exist: ${docsPath}` };
+  if (!existsSync(docsPath))
+    return { ok: false, error: `docs repo path does not exist: ${docsPath}` };
   try {
     execFileSync("git", ["-C", docsPath, "rev-parse", "--is-inside-work-tree"], { stdio: "pipe" });
   } catch {
@@ -49,7 +50,10 @@ export const linkDocsRepo = (
 
 export const listSpecs = (
   workspaceRoot: string,
-): { docs_repo: string | null; specs: { slug: string; spec: string; promoted: boolean; target: string | null }[] } => {
+): {
+  docs_repo: string | null;
+  specs: { slug: string; spec: string; promoted: boolean; target: string | null }[];
+} => {
   const repoPath = docsRepoPath();
   const specs: { slug: string; spec: string; promoted: boolean; target: string | null }[] = [];
   const docsDir = path.join(workspaceRoot, "docs");
@@ -63,7 +67,9 @@ export const listSpecs = (
       if (repoPath) {
         const featuresDir = path.join(repoPath, "features");
         if (existsSync(featuresDir)) {
-          const match = readdirSync(featuresDir).find((d) => new RegExp(`^20\\d{2}-\\d{2}-${slug}$`).test(d));
+          const match = readdirSync(featuresDir).find((d) =>
+            new RegExp(`^20\\d{2}-\\d{2}-${slug}$`).test(d),
+          );
           if (match) {
             promoted = true;
             target = path.join(repoPath, "features", match);
@@ -84,13 +90,20 @@ const monthPrefix = () => {
 };
 
 const readSafe = (p: string): string | null => {
-  try { return readFileSync(p, "utf8"); } catch { return null; }
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    return null;
+  }
 };
 
 const specSummary = (specText: string): string => {
-  const contextMatch = specText.match(/## Context\n\n([\s\S]*?)(?=\n## |\Z)/);
+  const contextMatch = specText.match(/## Context\n\n([\s\S]*?)(?=\n## |Z)/);
   if (!contextMatch) return "";
-  const first = contextMatch[1].trim().split("\n").find((l) => l.trim() && !l.startsWith("<!--"));
+  const first = contextMatch[1]
+    .trim()
+    .split("\n")
+    .find((l) => l.trim() && !l.startsWith("<!--"));
   return (first ?? "").trim();
 };
 
@@ -99,46 +112,68 @@ const specRepos = (specText: string): string => {
   return match?.[1]?.trim() ?? "—";
 };
 
-const SLUG_RE = /^[a-z0-9][a-z0-9._-]*$/i;
-
 export const promoteSpec = (
   workspaceRoot: string,
   slug: string,
   opts: { confirmed: boolean; force?: boolean },
-): { ok: true; target_dir: string; files: string[]; index_updated: boolean }
+):
+  | { ok: true; target_dir: string; files: string[]; index_updated: boolean }
   | { ok: false; error: string; findings?: unknown[] } => {
   if (!opts.confirmed) return { ok: false, error: "confirmed: true required" };
-  if (!SLUG_RE.test(slug)) return { ok: false, error: `invalid slug: ${JSON.stringify(slug)}` };
+  // One shared contained path contract (DC-01, DC-02): invalid slugs and
+  // non-canonical workspace roots fail here before any read or write.
+  const resolved = resolveCanonicalLayout({ workspace_root: workspaceRoot, slug });
+  if (!resolved.ok) return { ok: false, error: resolved.error };
+  const workspaceRootCanonical = resolved.layout.workspace;
   const repoPath = docsRepoPath();
   if (!repoPath) return { ok: false, error: "docs repo not linked — run workflow_docs_repo_link" };
   const repoValid = validateDocsRepo(repoPath);
   if (!repoValid.ok) return { ok: false, error: repoValid.error };
-
   const specRel = path.posix.join("docs", slug, "spec.md");
   const planRel = path.posix.join("docs", slug, "plan.md");
-  const specText = readSafe(path.join(workspaceRoot, specRel));
+  const specText = readSafe(resolved.layout.spec);
   if (specText === null) return { ok: false, error: `docs/${slug}/spec.md not found` };
 
-  const planText = readSafe(path.join(workspaceRoot, planRel));
+  const planText = readSafe(resolved.layout.plan);
   if (planText !== null) {
-    const validated = docsValidate({ spec_path: specRel, plan_path: planRel, workspace_root: workspaceRoot });
+    const validated = docsValidate({
+      spec_path: specRel,
+      plan_path: planRel,
+      workspace_root: workspaceRootCanonical,
+    });
     if (validated.ok === false) return { ok: false, error: validated.error };
   }
 
   const findings = qualitySpec(specText);
   const hardFindings = findings.filter((f) => f.severity === "hard");
   if (hardFindings.length > 0 && !opts.force) {
-    return { ok: false, error: "spec has hard quality findings; pass force: true to override", findings };
+    return {
+      ok: false,
+      error: "spec has hard quality findings; pass force: true to override",
+      findings,
+    };
   }
 
   // SDD working state must be gitignored before promotion
   if (!opts.force) {
-    const sddDir = path.join(workspaceRoot, "docs", slug, "sdd");
+    const sddDir = path.join(workspaceRootCanonical, "docs", slug, "sdd");
     if (existsSync(sddDir)) {
       try {
-        execFileSync("git", ["-C", workspaceRoot, "check-ignore", path.posix.join("docs", slug, "sdd", "progress.md")], { stdio: "pipe" });
+        execFileSync(
+          "git",
+          [
+            "-C",
+            workspaceRootCanonical,
+            "check-ignore",
+            path.posix.join("docs", slug, "sdd", "progress.md"),
+          ],
+          { stdio: "pipe" },
+        );
       } catch {
-        return { ok: false, error: `docs/${slug}/sdd/ is not gitignored — add 'docs/*/sdd/' to .gitignore or pass force: true` };
+        return {
+          ok: false,
+          error: `docs/${slug}/sdd/ is not gitignored — add 'docs/*/sdd/' to .gitignore or pass force: true`,
+        };
       }
     }
   }
@@ -179,7 +214,9 @@ ${planText !== null ? "| [plan.md](./plan.md) | Plan de implementación |\n" : "
   files.push("README.md");
 
   const indexPath = path.join(repoPath, "features", "README.md");
-  const indexText = readSafe(indexPath) ?? `# Features\n\nEspecificaciones y planes por feature.\n\n## Features documentadas\n\n| Feature | Repos afectados | Estado |\n| --- | --- | --- |\n`;
+  const indexText =
+    readSafe(indexPath) ??
+    `# Features\n\nEspecificaciones y planes por feature.\n\n## Features documentadas\n\n| Feature | Repos afectados | Estado |\n| --- | --- | --- |\n`;
   const row = `| [${slug}](./${prefix}-${slug}/) | ${specRepos(specText)} | Spec en revisión |`;
   const rowRe = new RegExp(`^\\| \\[${slug}\\]\\([^)]*\\) \\|.*$`, "m");
   let newIndex: string;

package/src/core/docs-validate.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { hygieneFiles } from "./hygiene";
 import { execFileSync } from "node:child_process";
 import path from "node:path";
+import { resolveCanonicalLayout, resolveDocsPath } from "./docs-layout";
 
 export type DocError = { code: string; message: string; path?: string };
 
@@ -15,17 +16,20 @@ const err = (code: string, message: string, path?: string): DocError => {
   return item;
 };
 
-const failValidate = (
-  errors: DocError[],
-): { ok: false; errors: DocError[]; error: string } => ({
+const failValidate = (errors: DocError[]): { ok: false; errors: DocError[]; error: string } => ({
   ok: false,
   errors,
-  error: errors.map((e) => e.message).filter(Boolean).join("; ") || "docs validation failed",
+  error:
+    errors
+      .map((e) => e.message)
+      .filter(Boolean)
+      .join("; ") || "docs validation failed",
 });
 
 const readBranch = (text: string, label: string): [string | null, DocError | null] => {
   const match = text.match(BRANCH_RE);
-  if (!match) return [null, err("missing_branch", `**Branch:** feature/* or bugfix/* required in ${label}`)];
+  if (!match)
+    return [null, err("missing_branch", `**Branch:** feature/* or bugfix/* required in ${label}`)];
   return [match[1].trim().replace(/`/g, ""), null];
 };
 
@@ -34,37 +38,55 @@ const scanTaskHeadings = (planText: string): [number[], string[], DocError | nul
   const titles: string[] = [];
   let inFence = false;
   for (const line of planText.split("\n")) {
-    if (line.startsWith("```")) { inFence = !inFence; continue; }
+    if (line.startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
     if (inFence) continue;
     const match = line.match(TASK_RE);
-    if (match) { ids.push(Number(match[1])); titles.push(match[2].trim()); }
+    if (match) {
+      ids.push(Number(match[1]));
+      titles.push(match[2].trim());
+    }
   }
-  if (ids.length === 0) return [ids, titles, err("task_order", "no ### Task N sections found outside fences")];
+  if (ids.length === 0)
+    return [ids, titles, err("task_order", "no ### Task N sections found outside fences")];
   const expected = ids.map((_, i) => i + 1);
   const sorted = [...ids].sort((a, b) => a - b);
   if (JSON.stringify(sorted) !== JSON.stringify(expected) || new Set(ids).size !== ids.length) {
-    return [ids, titles, err("task_order", `task headings must be contiguous from 1..${ids.length}; found ${ids}`)];
+    return [
+      ids,
+      titles,
+      err("task_order", `task headings must be contiguous from 1..${ids.length}; found ${ids}`),
+    ];
   }
   return [ids, titles, null];
 };
 
 // Port of scripts/lib/parse-plan-tasks.sh (JSON mode)
-export const parseTasksFromPlan = (planText: string): { id: number; title: string; section_text: string }[] => {
+export const parseTasksFromPlan = (
+  planText: string,
+): { id: number; title: string; section_text: string }[] => {
   const tasks: { id: number; title: string; section_text: string }[] = [];
   let current: { id: number; title: string; body: string[] } | null = null;
   let inFence = false;
   for (const line of planText.split("\n")) {
-    if (line.startsWith("```")) { inFence = !inFence; continue; }
+    if (line.startsWith("```")) {
+      inFence = !inFence;
+      continue;
+    }
     if (inFence) continue;
     const match = line.match(TASK_RE);
     if (match) {
-      if (current) tasks.push({ id: current.id, title: current.title, section_text: current.body.join("\n") });
+      if (current)
+        tasks.push({ id: current.id, title: current.title, section_text: current.body.join("\n") });
       current = { id: Number(match[1]), title: match[2].trim(), body: [] };
     } else if (current) {
       current.body.push(line);
     }
   }
-  if (current) tasks.push({ id: current.id, title: current.title, section_text: current.body.join("\n") });
+  if (current)
+    tasks.push({ id: current.id, title: current.title, section_text: current.body.join("\n") });
   return tasks;
 };
 
@@ -77,21 +99,40 @@ export const docsValidate = ({
   plan_path: string;
   workspace_root: string;
 }):
-  | { ok: true; spec: string; plan: string; branch: string; task_count: number; quality: QualityFinding[] }
+  | {
+      ok: true;
+      spec: string;
+      plan: string;
+      branch: string;
+      task_count: number;
+      quality: QualityFinding[];
+    }
   | { ok: false; errors: DocError[]; error: string } => {
-  const cwd = path.resolve(workspace_root);
-  const specAbs = path.isAbsolute(spec_path) ? spec_path : path.join(cwd, spec_path);
-  const planAbs = path.isAbsolute(plan_path) ? plan_path : path.join(cwd, plan_path);
+  // One shared contained path contract (DC-01, DC-02): absolute/traversal/
+  // symlink-escape/cross-slug/wrong-basename/legacy paths all fail here before
+  // any document bytes are read.
+  const resolved = resolveCanonicalLayout({ workspace_root, spec_path, plan_path });
+  if (!resolved.ok) return failValidate([err("path_contract", resolved.error)]);
+  const cwd = resolved.layout.workspace;
+  const specAbs = resolved.layout.spec;
+  const planAbs = resolved.layout.plan;
+  const slug = resolved.layout.slug;
   const errors: DocError[] = [];
 
   const read = (p: string): string | null => {
-    try { return readFileSync(p, "utf8"); } catch { return null; }
+    try {
+      return readFileSync(p, "utf8");
+    } catch {
+      return null;
+    }
   };
 
   const specText = read(specAbs);
   const planText = read(planAbs);
-  if (specText === null) errors.push(err("missing_file", `spec not found: ${spec_path}`, spec_path));
-  if (planText === null) errors.push(err("missing_file", `plan not found: ${plan_path}`, plan_path));
+  if (specText === null)
+    errors.push(err("missing_file", `spec not found: ${spec_path}`, spec_path));
+  if (planText === null)
+    errors.push(err("missing_file", `plan not found: ${plan_path}`, plan_path));
   if (errors.length) return failValidate(errors);
 
   const [specBranch, specErr] = readBranch(specText!, "spec");
@@ -104,14 +145,32 @@ export const docsValidate = ({
     errors.push(err("missing_spec_link", "**Spec:** link required in plan", plan_path));
   } else {
     const linked = (linkMatch[1] ?? linkMatch[2] ?? "").trim();
-    const linkedAbs = path.isAbsolute(linked) ? linked : path.join(cwd, linked);
-    if (path.resolve(linkedAbs) !== path.resolve(specAbs)) {
-      errors.push(err("spec_mismatch", `plan **Spec:** ${linked} does not match spec_path ${spec_path}`, plan_path));
+    // The plan link is a path inside the workspace docs tree: canonicalize it
+    // under the same contained contract before comparing to the canonical spec.
+    const linkedResolved = resolveDocsPath({ workspace_root: cwd, path: linked });
+    if (!linkedResolved.ok) {
+      errors.push(
+        err("spec_link_escape", `plan **Spec:** ${linked} is not a contained docs path`, plan_path),
+      );
+    } else if (linkedResolved.path !== specAbs) {
+      errors.push(
+        err(
+          "spec_mismatch",
+          `plan **Spec:** ${linked} does not match spec_path ${spec_path}`,
+          plan_path,
+        ),
+      );
     }
   }
 
   if (specBranch && planBranch && specBranch !== planBranch) {
-    errors.push(err("branch_mismatch", `spec branch ${JSON.stringify(specBranch)} != plan branch ${JSON.stringify(planBranch)}`, plan_path));
+    errors.push(
+      err(
+        "branch_mismatch",
+        `spec branch ${JSON.stringify(specBranch)} != plan branch ${JSON.stringify(planBranch)}`,
+        plan_path,
+      ),
+    );
   }
 
   const [, , taskErr] = scanTaskHeadings(planText!);
@@ -123,10 +182,19 @@ export const docsValidate = ({
   const [headingIds, headingTitles, headingErr] = scanTaskHeadings(planText!);
   if (headingErr) return failValidate([headingErr]);
   if (tasks.length !== headingIds.length) {
-    return failValidate([err("task_order", `parse count ${tasks.length} != heading count ${headingIds.length}`, plan_path)]);
+    return failValidate([
+      err(
+        "task_order",
+        `parse count ${tasks.length} != heading count ${headingIds.length}`,
+        plan_path,
+      ),
+    ]);
   }
   for (let i = 0; i < tasks.length; i++) {
-    if (String(tasks[i].id) !== String(headingIds[i]) || tasks[i].title.trim() !== headingTitles[i]) {
+    if (
+      String(tasks[i].id) !== String(headingIds[i]) ||
+      tasks[i].title.trim() !== headingTitles[i]
+    ) {
       return failValidate([err("task_order", `task mismatch at position ${i + 1}`, plan_path)]);
     }
   }
@@ -134,7 +202,6 @@ export const docsValidate = ({
   const relSpec = path.isAbsolute(spec_path) ? path.relative(cwd, specAbs) : spec_path;
   const relPlan = path.isAbsolute(plan_path) ? path.relative(cwd, planAbs) : plan_path;
   const quality = qualitySpec(specText!);
-  const slug = path.basename(path.dirname(spec_path));
   if (!sddIgnored(cwd, slug)) {
     quality.push({
       code: "sdd_not_ignored",
@@ -144,13 +211,45 @@ export const docsValidate = ({
   }
   const hygiene = hygieneFiles(cwd);
   const hyState = hygiene.state;
-  if (hyState["CHANGELOG.md"] === "missing") quality.push({ code: "changelog_missing", message: "CHANGELOG.md missing — create it with Keep a Changelog format (run wk-init hygiene)", severity: "warning" });
-  if (hyState["CHANGELOG.md"] === "invalid") quality.push({ code: "changelog_invalid_format", message: "CHANGELOG.md lacks ## [Unreleased] — Keep a Changelog format required", severity: "warning" });
-  if (hyState["README.md"] === "missing") quality.push({ code: "readme_missing", message: "README.md missing", severity: "warning" });
-  if (hyState[".editorconfig"] === "missing") quality.push({ code: "editorconfig_missing", message: ".editorconfig missing", severity: "warning" });
-  if (hyState[".gitattributes"] === "missing") quality.push({ code: "gitattributes_missing", message: ".gitattributes missing", severity: "warning" });
-  if (hygiene.openSource && hyState.LICENSE === "missing") quality.push({ code: "license_missing", message: "LICENSE missing (open-source repo)", severity: "warning" });
-  if (hygiene.openSource && hyState["CONTRIBUTING.md"] === "missing") quality.push({ code: "contributing_missing", message: "CONTRIBUTING.md missing (open-source repo)", severity: "warning" });
+  if (hyState["CHANGELOG.md"] === "missing")
+    quality.push({
+      code: "changelog_missing",
+      message:
+        "CHANGELOG.md missing — create it with Keep a Changelog format (run wk-init hygiene)",
+      severity: "warning",
+    });
+  if (hyState["CHANGELOG.md"] === "invalid")
+    quality.push({
+      code: "changelog_invalid_format",
+      message: "CHANGELOG.md lacks ## [Unreleased] — Keep a Changelog format required",
+      severity: "warning",
+    });
+  if (hyState["README.md"] === "missing")
+    quality.push({ code: "readme_missing", message: "README.md missing", severity: "warning" });
+  if (hyState[".editorconfig"] === "missing")
+    quality.push({
+      code: "editorconfig_missing",
+      message: ".editorconfig missing",
+      severity: "warning",
+    });
+  if (hyState[".gitattributes"] === "missing")
+    quality.push({
+      code: "gitattributes_missing",
+      message: ".gitattributes missing",
+      severity: "warning",
+    });
+  if (hygiene.openSource && hyState.LICENSE === "missing")
+    quality.push({
+      code: "license_missing",
+      message: "LICENSE missing (open-source repo)",
+      severity: "warning",
+    });
+  if (hygiene.openSource && hyState["CONTRIBUTING.md"] === "missing")
+    quality.push({
+      code: "contributing_missing",
+      message: "CONTRIBUTING.md missing (open-source repo)",
+      severity: "warning",
+    });
   return {
     ok: true,
     spec: relSpec,
@@ -175,12 +274,22 @@ const REQUIRED_SECTIONS = [
   "## Acceptance criteria",
 ];
 
-const UI_KEYWORDS = [/\bui\b/, /\binterface\b/, /\bscreen\b/, /\bmodal\b/, /\bform\b/, /\bcomponent\b/];
+const UI_KEYWORDS = [
+  /\bui\b/,
+  /\binterface\b/,
+  /\bscreen\b/,
+  /\bmodal\b/,
+  /\bform\b/,
+  /\bcomponent\b/,
+];
 const FLOW_KEYWORDS = [/\bflow\b/, /\bpipeline\b/, /\bsequence\b/, /\bdiagram\b/];
 const GLOSSARY_KEYWORDS = [/\bglossary\b/, /\bcontracts?\b/, /\bscope\b/];
 
-const finding = (code: string, message: string, severity: "warning" | "hard"): QualityFinding =>
-  ({ code, message, severity });
+const finding = (code: string, message: string, severity: "warning" | "hard"): QualityFinding => ({
+  code,
+  message,
+  severity,
+});
 
 // Replace fenced code blocks with a single marker line so their content cannot
 // satisfy the checks, but the fence itself (and its language) stays detectable.
@@ -212,27 +321,52 @@ export const qualitySpec = (text: string): QualityFinding[] => {
 
   const hasCa = /^\s*(?:- CA-\d+|CA-\d+[.:])/m.test(body); // M1: ^ with /m covers line starts
   if (!hasCa) {
-    findings.push(finding("missing_acceptance_criteria", "no enumerable CA-XX acceptance criteria found", "hard"));
+    findings.push(
+      finding(
+        "missing_acceptance_criteria",
+        "no enumerable CA-XX acceptance criteria found",
+        "hard",
+      ),
+    );
   }
 
   const hasAsciiFence = /```(?:text|ascii)/.test(body);
   const mentionsUi = UI_KEYWORDS.some((k) => k.test(lower));
   if (mentionsUi && !hasAsciiFence) {
-    findings.push(finding("missing_ascii_for_ui", "spec mentions UI but has no ASCII wireframe fence", "warning"));
+    findings.push(
+      finding(
+        "missing_ascii_for_ui",
+        "spec mentions UI but has no ASCII wireframe fence",
+        "warning",
+      ),
+    );
   }
 
   const hasMermaid = /```mermaid/.test(body);
   const explicitlyNoFlow = /\bno (?:flow|pipeline|sequence|diagram)\b/.test(lower);
   const mentionsFlow = FLOW_KEYWORDS.some((k) => k.test(lower));
   if (mentionsFlow && !hasMermaid && !explicitlyNoFlow) {
-    findings.push(finding("missing_mermaid_for_flow", "spec describes a flow/pipeline/sequence but has no mermaid fence", "warning"));
+    findings.push(
+      finding(
+        "missing_mermaid_for_flow",
+        "spec describes a flow/pipeline/sequence but has no mermaid fence",
+        "warning",
+      ),
+    );
   }
 
   const hasTable = /^\s*\|.+\|.+\|/m.test(body);
   const mentionsGlossary = GLOSSARY_KEYWORDS.some((k) => k.test(lower));
-  const onlyOutOfScope = /\bout of scope\b/.test(lower) && !/\bglossary\b/.test(lower) && !/\bcontracts?\b/.test(lower);
+  const onlyOutOfScope =
+    /\bout of scope\b/.test(lower) && !/\bglossary\b/.test(lower) && !/\bcontracts?\b/.test(lower);
   if (mentionsGlossary && !hasTable && !onlyOutOfScope) {
-    findings.push(finding("missing_table", "spec has glossary/contract/scope content but no markdown table", "warning"));
+    findings.push(
+      finding(
+        "missing_table",
+        "spec has glossary/contract/scope content but no markdown table",
+        "warning",
+      ),
+    );
   }
 
   return findings;
@@ -247,7 +381,11 @@ const sddIgnored = (cwd: string, slug: string): boolean => {
     return true; // not a git repo — nothing to be unignored in; validation presupposes a repo
   }
   try {
-    execFileSync("git", ["-C", cwd, "check-ignore", path.posix.join("docs", slug, "sdd", "progress.md")], { stdio: "pipe" });
+    execFileSync(
+      "git",
+      ["-C", cwd, "check-ignore", path.posix.join("docs", slug, "sdd", "progress.md")],
+      { stdio: "pipe" },
+    );
     return true;
   } catch {
     return false;