@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/planning-parsers.js

@@ -0,0 +1,567 @@
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { getMarkdownSection } = require("./audit-parsers");
+const { parseRuntimeSpecMarkdown } = require("./artifact-parsers");
+const { pathExists, readTextIfExists } = require("./utils");
+
+const LIST_ITEM_PATTERN = /^\s*(?:[-*+]|\d+[.)])\s+(.+?)\s*$/;
+const DEFAULT_SCAN_MAX_DEPTH = 32;
+const DEFAULT_SPEC_SCAN_MAX_DEPTH = 64;
+
+function toPositiveInteger(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    return fallback;
+  }
+  const normalized = Math.floor(parsed);
+  if (normalized <= 0) {
+    return fallback;
+  }
+  return normalized;
+}
+
+function normalizeText(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function parseListItems(sectionText) {
+  const normalized = String(sectionText || "").replace(/\r\n?/g, "\n").trim();
+  if (!normalized) {
+    return [];
+  }
+
+  const lines = normalized.split("\n");
+  const items = [];
+  for (const line of lines) {
+    const match = line.match(LIST_ITEM_PATTERN);
+    if (!match) {
+      continue;
+    }
+    const value = String(match[1] || "").trim();
+    if (value) {
+      items.push(value);
+    }
+  }
+  if (items.length > 0) {
+    return items;
+  }
+
+  return normalized
+    .split(/\n\s*\n/g)
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function unique(values) {
+  return Array.from(new Set((values || []).filter(Boolean)));
+}
+
+function resolveImplementationLanding(projectRoot, implementationToken) {
+  const knownExtensions = [".html", ".tsx", ".jsx", ".ts", ".js"];
+  const seen = new Set();
+  const candidates = [];
+  const addCandidate = (relativePath) => {
+    const normalized = String(relativePath || "").trim();
+    if (!normalized || seen.has(normalized)) {
+      return;
+    }
+    seen.add(normalized);
+    candidates.push(normalized);
+  };
+  const addFileCandidates = (basePath) => {
+    addCandidate(basePath);
+    for (const extension of knownExtensions) {
+      addCandidate(`${basePath}${extension}`);
+    }
+  };
+  const addIndexCandidates = (dirPath) => {
+    for (const extension of knownExtensions) {
+      addCandidate(path.join(dirPath, `index${extension}`));
+    }
+  };
+  const addPageCandidates = (dirPath) => {
+    for (const extension of knownExtensions) {
+      addCandidate(path.join(dirPath, `page${extension}`));
+    }
+  };
+  const resolveFileCandidate = (relativePath) => {
+    const absolutePath = path.join(projectRoot, relativePath);
+    try {
+      const stat = fs.statSync(absolutePath);
+      return stat.isFile() ? absolutePath : null;
+    } catch (_error) {
+      return null;
+    }
+  };
+
+  const normalized = String(implementationToken || "").trim();
+  if (!normalized) {
+    return null;
+  }
+
+  if (normalized === "/" || normalized === "index" || normalized === "/index") {
+    addFileCandidates("index");
+    addFileCandidates(path.join("pages", "index"));
+    addIndexCandidates("pages");
+    addFileCandidates(path.join("src", "pages", "index"));
+    addIndexCandidates(path.join("src", "pages"));
+    addFileCandidates(path.join("app", "page"));
+    addPageCandidates("app");
+    addFileCandidates(path.join("src", "app", "page"));
+    addPageCandidates(path.join("src", "app"));
+  } else {
+    const routePath = normalized.replace(/^\//, "").replace(/\/+$/, "");
+    addFileCandidates(routePath);
+    addIndexCandidates(routePath);
+
+    addFileCandidates(path.join("src", routePath));
+    addIndexCandidates(path.join("src", routePath));
+
+    addFileCandidates(path.join("pages", routePath));
+    addIndexCandidates(path.join("pages", routePath));
+    addFileCandidates(path.join("src", "pages", routePath));
+    addIndexCandidates(path.join("src", "pages", routePath));
+
+    addFileCandidates(path.join("app", routePath, "page"));
+    addPageCandidates(path.join("app", routePath));
+    addFileCandidates(path.join("src", "app", routePath, "page"));
+    addPageCandidates(path.join("src", "app", routePath));
+  }
+
+  for (const candidate of candidates) {
+    const resolved = resolveFileCandidate(candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  return null;
+}
+
+function listImmediateDirs(targetDir) {
+  if (!pathExists(targetDir)) {
+    return [];
+  }
+
+  let entries = [];
+  try {
+    entries = fs.readdirSync(targetDir, { withFileTypes: true });
+  } catch (_error) {
+    return [];
+  }
+
+  return entries
+    .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
+    .map((entry) => path.join(targetDir, entry.name));
+}
+
+function hasAnyFile(targetDir, options = {}) {
+  if (!pathExists(targetDir)) {
+    return false;
+  }
+
+  const maxDepth = toPositiveInteger(options.maxDepth, DEFAULT_SCAN_MAX_DEPTH);
+  const stack = [{ dir: targetDir, depth: 0 }];
+  const visited = new Set();
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current.depth > maxDepth) {
+      continue;
+    }
+
+    let resolvedCurrent;
+    try {
+      resolvedCurrent = fs.realpathSync(current.dir);
+    } catch (_error) {
+      continue;
+    }
+    if (visited.has(resolvedCurrent)) {
+      continue;
+    }
+    visited.add(resolvedCurrent);
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current.dir, { withFileTypes: true });
+    } catch (_error) {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isFile()) {
+        return true;
+      }
+      if (entry.isDirectory() && !entry.isSymbolicLink()) {
+        stack.push({
+          dir: path.join(current.dir, entry.name),
+          depth: current.depth + 1
+        });
+      }
+    }
+  }
+  return false;
+}
+
+function pickLatestChange(changeDirs) {
+  if (!Array.isArray(changeDirs) || changeDirs.length === 0) {
+    return null;
+  }
+
+  const withMtime = changeDirs
+    .map((changeDir) => {
+      try {
+        const stat = fs.statSync(changeDir);
+        return {
+          changeDir,
+          mtimeMs: stat.mtimeMs
+        };
+      } catch (_error) {
+        return null;
+      }
+    })
+    .filter(Boolean)
+    .sort((left, right) => right.mtimeMs - left.mtimeMs);
+  if (withMtime.length === 0) {
+    return null;
+  }
+  return withMtime[0].changeDir;
+}
+
+function resolveChangeDir(projectRoot, requestedChangeId = "") {
+  const workflowRoot = path.join(projectRoot, ".da-vinci");
+  const changesRoot = path.join(workflowRoot, "changes");
+  const response = {
+    changeDir: null,
+    changeId: null,
+    failures: [],
+    notes: []
+  };
+
+  if (!pathExists(workflowRoot)) {
+    response.failures.push("Missing `.da-vinci/` directory.");
+    return response;
+  }
+
+  const changeDirs = listImmediateDirs(changesRoot).filter((changeDir) => hasAnyFile(changeDir));
+  if (changeDirs.length === 0) {
+    response.failures.push("No non-empty change directory found under `.da-vinci/changes/`.");
+    return response;
+  }
+
+  if (requestedChangeId) {
+    const requestedDir = path.join(changesRoot, requestedChangeId);
+    if (!pathExists(requestedDir) || !hasAnyFile(requestedDir)) {
+      response.failures.push(
+        `Requested change was not found or is empty: .da-vinci/changes/${requestedChangeId}`
+      );
+      return response;
+    }
+    response.changeDir = requestedDir;
+    response.changeId = requestedChangeId;
+    return response;
+  }
+
+  if (changeDirs.length === 1) {
+    response.changeDir = changeDirs[0];
+    response.changeId = path.basename(changeDirs[0]);
+    return response;
+  }
+
+  const changeIds = changeDirs.map((changeDir) => path.basename(changeDir)).sort();
+  response.failures.push("Multiple non-empty change directories found. Re-run with `--change <change-id>`.");
+  response.notes.push(`Available change ids: ${changeIds.join(", ")}`);
+  const latest = pickLatestChange(changeDirs);
+  if (latest) {
+    response.notes.push(`Latest inferred change for context only: ${path.basename(latest)}`);
+  }
+  return response;
+}
+
+function detectSpecFiles(specsDir, options = {}) {
+  if (!pathExists(specsDir)) {
+    return [];
+  }
+
+  const maxDepth = toPositiveInteger(options.maxDepth, DEFAULT_SPEC_SCAN_MAX_DEPTH);
+  const discovered = [];
+  const stack = [{ dir: specsDir, depth: 0 }];
+  const visited = new Set();
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current.depth > maxDepth) {
+      continue;
+    }
+
+    let resolvedCurrent;
+    try {
+      resolvedCurrent = fs.realpathSync(current.dir);
+    } catch (_error) {
+      continue;
+    }
+    if (visited.has(resolvedCurrent)) {
+      continue;
+    }
+    visited.add(resolvedCurrent);
+
+    let entries = [];
+    try {
+      entries = fs.readdirSync(current.dir, { withFileTypes: true });
+    } catch (_error) {
+      continue;
+    }
+    for (const entry of entries) {
+      const absolutePath = path.join(current.dir, entry.name);
+      if (entry.isDirectory() && !entry.isSymbolicLink()) {
+        stack.push({
+          dir: absolutePath,
+          depth: current.depth + 1
+        });
+        continue;
+      }
+      if (entry.isFile() && entry.name === "spec.md") {
+        discovered.push(absolutePath);
+      }
+    }
+  }
+  return discovered.sort();
+}
+
+function parseProposalArtifact(text) {
+  return {
+    scopeItems: parseListItems(getMarkdownSection(text, "Scope")),
+    nonGoalItems: parseListItems(getMarkdownSection(text, "Non-Goals"))
+  };
+}
+
+function parsePageMapArtifact(text) {
+  const canonicalItems = parseListItems(getMarkdownSection(text, "Canonical Pages"));
+  const statesPerPageItems = parseListItems(getMarkdownSection(text, "States Per Page"));
+  const pages = canonicalItems
+    .map((item) => String(item || "").split("->")[0].replace(/`/g, "").trim())
+    .filter(Boolean);
+
+  return {
+    canonicalItems,
+    statesPerPageItems,
+    pages: unique(pages)
+  };
+}
+
+function parseTasksArtifact(text) {
+  const lines = String(text || "").replace(/\r\n?/g, "\n").split("\n");
+  const taskGroups = [];
+  const checklistItems = [];
+  const checkpointItems = [];
+  const sections = [];
+  let currentSection = null;
+
+  for (const line of lines) {
+    const groupMatch = line.match(/^\s{0,3}##\s+(\d+(?:\.\d+)*)\.\s+(.+)$/);
+    if (groupMatch) {
+      const group = {
+        id: groupMatch[1],
+        title: String(groupMatch[2] || "").trim()
+      };
+      taskGroups.push(group);
+      if (currentSection) {
+        sections.push(currentSection);
+      }
+      currentSection = {
+        id: group.id,
+        title: group.title,
+        checklistItems: []
+      };
+      continue;
+    }
+
+    const checklistMatch = line.match(/^\s*-\s*\[([ xX])\]\s+(.+)$/);
+    if (checklistMatch) {
+      const checked = String(checklistMatch[1] || "").toLowerCase() === "x";
+      const textValue = String(checklistMatch[2] || "").trim();
+      if (!textValue) {
+        continue;
+      }
+      checklistItems.push({
+        checked,
+        text: textValue
+      });
+      if (currentSection) {
+        currentSection.checklistItems.push({
+          checked,
+          text: textValue
+        });
+      }
+      if (/checkpoint/i.test(textValue)) {
+        checkpointItems.push({
+          checked,
+          text: textValue
+        });
+      }
+    }
+  }
+  if (currentSection) {
+    sections.push(currentSection);
+  }
+
+  return {
+    taskGroups,
+    checklistItems,
+    checkpointItems,
+    sections,
+    text: String(text || "")
+  };
+}
+
+function parseBindingsArtifact(text) {
+  const bindingSections = [
+    "Bindings",
+    "Page To Pencil Page",
+    "Bound Pages",
+    "Page Mapping"
+  ];
+
+  let sectionText = "";
+  for (const heading of bindingSections) {
+    sectionText = getMarkdownSection(text, heading);
+    if (sectionText) {
+      break;
+    }
+  }
+
+  const items = parseListItems(sectionText);
+  const mappings = [];
+  const malformed = [];
+
+  for (const item of items) {
+    const segments = String(item || "")
+      .split("->")
+      .map((segment) => segment.replace(/`/g, "").trim())
+      .filter(Boolean);
+
+    if (segments.length < 2) {
+      malformed.push(item);
+      continue;
+    }
+
+    const mapping = {
+      implementation: segments[0],
+      designPage: segments[segments.length - 1],
+      designSource: segments.length >= 3 ? segments[1] : "",
+      raw: item
+    };
+
+    const idMatch = mapping.designPage.match(/\(([^)]+)\)\s*$/);
+    if (idMatch) {
+      mapping.screenId = String(idMatch[1] || "").trim();
+      mapping.designPage = mapping.designPage.replace(/\(([^)]+)\)\s*$/, "").trim();
+    } else {
+      mapping.screenId = "";
+    }
+
+    mappings.push(mapping);
+  }
+
+  const notes = parseListItems(getMarkdownSection(text, "Notes"));
+  const sharedBindings = parseListItems(getMarkdownSection(text, "Shared Bindings"));
+
+  return {
+    mappings,
+    malformed,
+    notes,
+    sharedBindings
+  };
+}
+
+function parseVerificationArtifact(text) {
+  return {
+    requirementCoverage: parseListItems(getMarkdownSection(text, "Requirement Coverage")),
+    designCoverage: parseListItems(getMarkdownSection(text, "Design Coverage")),
+    behaviorDrift: parseListItems(getMarkdownSection(text, "Behavior Drift")),
+    bindingDrift: parseListItems(getMarkdownSection(text, "Binding Drift")),
+    outcome: parseListItems(getMarkdownSection(text, "Outcome"))
+  };
+}
+
+function parseRuntimeSpecs(changeDir, projectRoot) {
+  const specsDir = path.join(changeDir, "specs");
+  const specFiles = detectSpecFiles(specsDir);
+  const records = [];
+
+  for (const specFile of specFiles) {
+    const text = fs.readFileSync(specFile, "utf8");
+    const parsed = parseRuntimeSpecMarkdown(text);
+    records.push({
+      path: path.relative(projectRoot, specFile) || specFile,
+      text,
+      parsed
+    });
+  }
+
+  return records;
+}
+
+function digestObject(value) {
+  return crypto
+    .createHash("sha256")
+    .update(JSON.stringify(value))
+    .digest("hex");
+}
+
+function digestFile(filePath) {
+  if (!pathExists(filePath)) {
+    return "";
+  }
+  const payload = fs.readFileSync(filePath);
+  return crypto.createHash("sha256").update(payload).digest("hex");
+}
+
+function readChangeArtifacts(projectRoot, changeId) {
+  const changeDir = path.join(projectRoot, ".da-vinci", "changes", changeId);
+  const pageMapPath = path.join(projectRoot, ".da-vinci", "page-map.md");
+  const fallbackPageMapPath = path.join(changeDir, "page-map.md");
+  return {
+    changeDir,
+    proposalPath: path.join(changeDir, "proposal.md"),
+    pageMapPath: pathExists(pageMapPath) ? pageMapPath : fallbackPageMapPath,
+    tasksPath: path.join(changeDir, "tasks.md"),
+    bindingsPath: path.join(changeDir, "pencil-bindings.md"),
+    pencilDesignPath: path.join(changeDir, "pencil-design.md"),
+    verificationPath: path.join(changeDir, "verification.md")
+  };
+}
+
+function readArtifactTexts(paths) {
+  return {
+    proposal: readTextIfExists(paths.proposalPath),
+    pageMap: readTextIfExists(paths.pageMapPath),
+    tasks: readTextIfExists(paths.tasksPath),
+    bindings: readTextIfExists(paths.bindingsPath),
+    pencilDesign: readTextIfExists(paths.pencilDesignPath),
+    verification: readTextIfExists(paths.verificationPath)
+  };
+}
+
+module.exports = {
+  normalizeText,
+  parseListItems,
+  unique,
+  resolveImplementationLanding,
+  listImmediateDirs,
+  hasAnyFile,
+  pickLatestChange,
+  resolveChangeDir,
+  detectSpecFiles,
+  parseProposalArtifact,
+  parsePageMapArtifact,
+  parseTasksArtifact,
+  parseBindingsArtifact,
+  parseVerificationArtifact,
+  parseRuntimeSpecs,
+  digestObject,
+  digestFile,
+  readChangeArtifacts,
+  readArtifactTexts
+};