@brainervirus/workit-core 0.5.6 → 0.6.1

package/src/core/docs-validate.ts

@@ -15,17 +15,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 +37,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,7 +98,14 @@ 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);
@@ -85,13 +113,19 @@ export const docsValidate = ({
   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");
@@ -106,12 +140,24 @@ export const docsValidate = ({
     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));
+      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 +169,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)]);
     }
   }
@@ -144,13 +199,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 +262,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 +309,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 +369,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;

package/src/core/flow-state.ts

@@ -104,7 +104,10 @@ export const transitionSpec = (
         ok: false,
         error:
           "spec self-review failed: " +
-          hard.map((f) => `${f.code} — ${f.message}`).concat(missing).join("; ") +
+          hard
+            .map((f) => `${f.code} — ${f.message}`)
+            .concat(missing)
+            .join("; ") +
           " — see templates/spec-template.md for the required structure",
       };
     }
@@ -150,7 +153,8 @@ export const transitionPlan = (
     }
     const missing: string[] = [];
     const stripped = stripFences(text);
-    if (parseTasksFromPlan(text).length === 0) missing.push("no ### Task N: sections outside fences");
+    if (parseTasksFromPlan(text).length === 0)
+      missing.push("no ### Task N: sections outside fences");
     if (!/^\s*\*+Spec:\*+/im.test(stripped)) missing.push("**Spec:** header missing");
     if (!/^\s*\*+Branch:\*+/im.test(stripped)) missing.push("**Branch:** header missing");
     if (missing.length > 0) {

package/src/core/gitignore.ts

@@ -25,7 +25,12 @@ export const ensureProjectGitignore = (
   if (!confirmed) return { ok: false, error: "confirmed: true required" };
   const file = path.join(workspaceRoot, ".gitignore");
   const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
-  const existingLines = new Set(existing.split("\n").map((l) => l.trim()).filter(Boolean));
+  const existingLines = new Set(
+    existing
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean),
+  );
   const added: string[] = [];
   const append: string[] = [];
   for (const entry of GITIGNORE_ENTRIES) {
@@ -35,7 +40,11 @@ export const ensureProjectGitignore = (
   }
   if (append.length) {
     const separator = existing && !existing.endsWith("\n") ? "\n" : "";
-    writeFileSync(file, existing + separator + (existing ? "\n" : "") + append.join("\n") + "\n", "utf8");
+    writeFileSync(
+      file,
+      existing + separator + (existing ? "\n" : "") + append.join("\n") + "\n",
+      "utf8",
+    );
   } else if (!existsSync(file)) {
     writeFileSync(file, "", "utf8");
   }

package/src/core/handoff-context.ts

@@ -25,7 +25,8 @@ const resolveFromMessagePaths = (root: string, message: string): Resolved => {
   const paths = extractMessagePaths(message);
   if (paths.length === 0) return { error: "no paths" };
   const slugs = [...new Set(paths.map((p) => p.split("/")[1]))];
-  if (slugs.length !== 1) return { error: "multiple features in message — use exactly one docs/<slug>/ pair" };
+  if (slugs.length !== 1)
+    return { error: "multiple features in message — use exactly one docs/<slug>/ pair" };
   const slug = slugs[0];
   const plan = `docs/${slug}/plan.md`;
   const spec = `docs/${slug}/spec.md`;
@@ -49,8 +50,15 @@ const resolveActivePair = (root: string): Resolved => {
     const plan = path.join("docs", slug, "plan.md");
     const spec = path.join("docs", slug, "spec.md");
     if (!existsSync(path.join(root, plan)) || !existsSync(path.join(root, spec))) continue;
-    const score = Math.max(statSync(path.join(root, spec)).mtimeMs, statSync(path.join(root, plan)).mtimeMs);
-    if (best === null || score > best.score || (score === best.score && slug < best.spec.split("/")[1])) {
+    const score = Math.max(
+      statSync(path.join(root, spec)).mtimeMs,
+      statSync(path.join(root, plan)).mtimeMs,
+    );
+    if (
+      best === null ||
+      score > best.score ||
+      (score === best.score && slug < best.spec.split("/")[1])
+    ) {
       best = { score, spec, plan, source: "active_pair" };
     }
   }
@@ -69,7 +77,10 @@ export const resolveWorkflowPaths = (root: string, message: string): Resolved =>
   if (!existsSync(docsDir) || listMd(docsDir).length === 0) {
     return { error: "no docs/<slug>/ features found under docs/" };
   }
-  return { error: "could not resolve spec and plan — mention docs/<slug>/plan.md or create docs/<slug>/{spec.md,plan.md}" };
+  return {
+    error:
+      "could not resolve spec and plan — mention docs/<slug>/plan.md or create docs/<slug>/{spec.md,plan.md}",
+  };
 };
 
 export const buildHandoffContract = ({
@@ -85,7 +96,9 @@ export const buildHandoffContract = ({
 }): { prompt: string } | { error: string } => {
   const validated = docsValidate({ spec_path: spec, plan_path: plan, workspace_root: root });
   if (validated.ok === false) {
-    return { error: `docs validation failed\n${JSON.stringify({ ok: false, errors: validated.errors })}` };
+    return {
+      error: `docs validation failed\n${JSON.stringify({ ok: false, errors: validated.errors })}`,
+    };
   }
   const branchResolved = resolveBranch({ spec_path: spec, plan_path: plan, workspace_root: root });
   if ("error" in branchResolved) return { error: branchResolved.error as string };

package/src/core/hygiene.ts

@@ -3,7 +3,13 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { changelogUnreleasedStats } from "./changelog";
 
-export type HygieneFile = "CHANGELOG.md" | "README.md" | ".editorconfig" | ".gitattributes" | "LICENSE" | "CONTRIBUTING.md";
+export type HygieneFile =
+  | "CHANGELOG.md"
+  | "README.md"
+  | ".editorconfig"
+  | ".gitattributes"
+  | "LICENSE"
+  | "CONTRIBUTING.md";
 type State = "missing" | "invalid" | "ok" | "skip";
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
@@ -11,7 +17,11 @@ const templatesDir = () => path.join(repoRoot, "templates", "hygiene");
 
 const packageJson = (root: string): Record<string, unknown> | null => {
   if (!existsSync(path.join(root, "package.json"))) return null;
-  try { return JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")); } catch { return null; }
+  try {
+    return JSON.parse(readFileSync(path.join(root, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
 };
 
 const isOpenSource = (root: string): boolean => {
@@ -34,15 +44,27 @@ const licenseHolder = (root: string): string => {
   return "";
 };
 
-export const hygieneFiles = (root: string): { state: Record<HygieneFile, State>; openSource: boolean } => {
+export const hygieneFiles = (
+  root: string,
+): { state: Record<HygieneFile, State>; openSource: boolean } => {
   const openSource = isOpenSource(root);
   const state = {} as Record<HygieneFile, State>;
-  for (const file of ["CHANGELOG.md", "README.md", ".editorconfig", ".gitattributes", "LICENSE", "CONTRIBUTING.md"] as HygieneFile[]) {
+  for (const file of [
+    "CHANGELOG.md",
+    "README.md",
+    ".editorconfig",
+    ".gitattributes",
+    "LICENSE",
+    "CONTRIBUTING.md",
+  ] as HygieneFile[]) {
     if (file === "LICENSE" || file === "CONTRIBUTING.md") {
       state[file] = openSource ? (existsSync(path.join(root, file)) ? "ok" : "missing") : "skip";
       continue;
     }
-    if (!existsSync(path.join(root, file))) { state[file] = "missing"; continue; }
+    if (!existsSync(path.join(root, file))) {
+      state[file] = "missing";
+      continue;
+    }
     if (file === "CHANGELOG.md") {
       const stats = changelogUnreleasedStats(root);
       state[file] = stats.exists && stats.has_unreleased ? "ok" : "invalid";