@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/scope-check.js

@@ -0,0 +1,603 @@
+const path = require("path");
+const { getMarkdownSection } = require("./audit-parsers");
+const { pathExists, readTextIfExists } = require("./utils");
+const { STATUS } = require("./workflow-contract");
+const {
+  parseListItems,
+  unique,
+  resolveChangeDir,
+  parseRuntimeSpecs
+} = require("./planning-parsers");
+
+const PAGE_NAME_PATTERN = /`([^`]+)`|([a-z0-9][a-z0-9 \-/]{1,80}?)\s+pages?\b/gi;
+const STATE_SYNONYMS = {
+  success: ["success", "succeed", "succeeds", "succeeded"],
+  error: ["error", "fail", "fails", "failed", "failure"],
+  loading: ["loading", "load", "spinner"]
+};
+
+function normalizeWhitespace(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function normalizePageKey(value) {
+  return normalizeWhitespace(value)
+    .replace(/\b(page|pages|screen|screens)\b/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function normalizeStateKey(value) {
+  const raw = String(value || "").split(":")[0];
+  return normalizeWhitespace(raw)
+    .replace(/\bstate\b/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function registerName(map, key, label) {
+  if (!key) {
+    return;
+  }
+  if (!map.has(key)) {
+    map.set(key, String(label || key).trim());
+  }
+}
+
+function extractPageCandidatesFromItem(item) {
+  const text = String(item || "");
+  const pages = [];
+  let match;
+  while ((match = PAGE_NAME_PATTERN.exec(text)) !== null) {
+    const pageName = String(match[1] || match[2] || "").trim();
+    if (pageName) {
+      pages.push(pageName);
+    }
+  }
+  if (/homepage/i.test(text)) {
+    pages.push("Homepage");
+  }
+  if (/product detail/i.test(text)) {
+    pages.push("Product Detail");
+  }
+  return unique(pages);
+}
+
+function parseProposal(text) {
+  const scopeSection = getMarkdownSection(text, "Scope");
+  const nonGoalsSection = getMarkdownSection(text, "Non-Goals");
+  const scopeItems = parseListItems(scopeSection);
+  const nonGoalItems = parseListItems(nonGoalsSection);
+
+  const scopePages = unique(scopeItems.flatMap((item) => extractPageCandidatesFromItem(item)));
+
+  return {
+    scopeItems,
+    nonGoalItems,
+    scopePages
+  };
+}
+
+function parsePageMap(text) {
+  const canonicalSection = getMarkdownSection(text, "Canonical Pages");
+  const statesPerPageSection = getMarkdownSection(text, "States Per Page");
+
+  const canonicalItems = parseListItems(canonicalSection);
+  const pageNames = [];
+  for (const item of canonicalItems) {
+    const first = String(item || "").split("->")[0];
+    const cleaned = String(first || "")
+      .replace(/`/g, "")
+      .trim();
+    if (!cleaned) {
+      continue;
+    }
+    pageNames.push(cleaned);
+  }
+
+  const statesPerPageItems = parseListItems(statesPerPageSection);
+  const stateNames = [];
+  for (const item of statesPerPageItems) {
+    const stateSlice = String(item || "").split(":").slice(1).join(":").trim();
+    if (!stateSlice) {
+      continue;
+    }
+    for (const statePart of stateSlice.split(/[;,/]| and /i)) {
+      const normalized = String(statePart || "").trim();
+      if (!normalized) {
+        continue;
+      }
+      stateNames.push(normalized);
+    }
+  }
+
+  return {
+    pages: unique(pageNames),
+    states: unique(stateNames),
+    canonicalItems,
+    statesPerPageItems
+  };
+}
+
+function parseSpecs(changeDir, projectRoot) {
+  const specRecords = parseRuntimeSpecs(changeDir, projectRoot);
+  const stateNames = [];
+  const combinedTextChunks = [];
+  const records = [];
+
+  for (const record of specRecords) {
+    const text = record.text || "";
+    const parsed = record.parsed || {
+      missingSections: [],
+      emptySections: [],
+      sections: {
+        states: { items: [] }
+      }
+    };
+    const relativePath = record.path || "";
+    const states = parsed.sections.states.items.map((item) => {
+      const value = String(item || "").split(":")[0].trim();
+      return value || item;
+    });
+    stateNames.push(...states);
+    combinedTextChunks.push(text);
+    records.push({
+      path: relativePath,
+      missingSections: parsed.missingSections,
+      emptySections: parsed.emptySections,
+      states
+    });
+  }
+
+  return {
+    files: specRecords.map((item) => item.path),
+    records,
+    states: unique(stateNames),
+    combinedText: combinedTextChunks.join("\n")
+  };
+}
+
+function parsePencilDesign(text) {
+  const statesSection = getMarkdownSection(text, "States Represented");
+  const screensSection = getMarkdownSection(text, "Screens");
+  const stateItems = parseListItems(statesSection);
+  const screenItems = parseListItems(screensSection);
+  const states = [];
+  const pages = [];
+
+  for (const item of stateItems) {
+    const afterColon = String(item || "").split(":").slice(1).join(":").trim();
+    if (afterColon) {
+      for (const token of afterColon.split(/[;,/]| and /i)) {
+        const candidate = String(token || "").trim();
+        if (candidate) {
+          states.push(candidate);
+        }
+      }
+      continue;
+    }
+    states.push(item);
+  }
+
+  for (const item of screenItems) {
+    const screenName = String(item || "").split("->")[0].replace(/`/g, "").trim();
+    if (screenName) {
+      pages.push(screenName);
+    }
+  }
+
+  return {
+    states: unique(states),
+    pages: unique(pages)
+  };
+}
+
+function parseTasks(text) {
+  const normalizedText = normalizeWhitespace(text);
+  const taskGroups = [];
+  const checklistItems = [];
+
+  const lines = String(text || "").replace(/\r\n?/g, "\n").split("\n");
+  for (const line of lines) {
+    const groupMatch = line.match(/^\s{0,3}##\s+(\d+(?:\.\d+)*)\.\s+(.+)$/);
+    if (groupMatch) {
+      taskGroups.push({
+        id: groupMatch[1],
+        title: String(groupMatch[2] || "").trim()
+      });
+      continue;
+    }
+
+    const checklistMatch = line.match(/^\s*-\s*\[[ xX]\]\s+(.+)$/);
+    if (checklistMatch) {
+      const item = String(checklistMatch[1] || "").trim();
+      if (item) {
+        checklistItems.push(item);
+      }
+    }
+  }
+
+  const mentionedPages = unique(checklistItems.flatMap((item) => extractPageCandidatesFromItem(item)));
+
+  return {
+    text,
+    normalizedText,
+    taskGroups,
+    checklistItems,
+    mentionedPages
+  };
+}
+
+function expandStateCoverageTokens(stateKey) {
+  const normalized = normalizeStateKey(stateKey);
+  if (!normalized) {
+    return [];
+  }
+  return STATE_SYNONYMS[normalized] || [normalized];
+}
+
+function containsAnyToken(source, tokens) {
+  const normalizedSource = normalizeWhitespace(source);
+  return (tokens || []).some((token) => normalizedSource.includes(normalizeWhitespace(token)));
+}
+
+function buildScopeResultEnvelope(projectRoot, strict) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    strict,
+    coverage: null,
+    matrix: {
+      pages: [],
+      states: []
+    },
+    summary: {
+      pages: 0,
+      states: 0
+    }
+  };
+}
+
+function resolveChange(projectRoot, requestedChangeId, failures, notes) {
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  failures.push(...resolved.failures);
+  notes.push(...resolved.notes);
+  return resolved.changeDir;
+}
+
+function finalizeResult(result) {
+  const hasFindings = result.failures.length > 0 || result.warnings.length > 0;
+  if (!hasFindings) {
+    result.status = STATUS.PASS;
+    return result;
+  }
+
+  if (result.strict) {
+    result.status = STATUS.BLOCK;
+    return result;
+  }
+
+  result.status = STATUS.WARN;
+  return result;
+}
+
+function analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign, tasks) {
+  const pageNames = new Map();
+  const stateNames = new Map();
+
+  const proposalPageKeys = new Set();
+  for (const page of proposal.scopePages) {
+    const key = normalizePageKey(page);
+    if (!key) {
+      continue;
+    }
+    proposalPageKeys.add(key);
+    registerName(pageNames, key, page);
+  }
+
+  const pageMapPageKeys = new Set();
+  for (const page of pageMap.pages) {
+    const key = normalizePageKey(page);
+    if (!key) {
+      continue;
+    }
+    pageMapPageKeys.add(key);
+    registerName(pageNames, key, page);
+  }
+
+  const pencilPageKeys = new Set();
+  for (const page of pencilDesign.pages) {
+    const key = normalizePageKey(page);
+    if (!key) {
+      continue;
+    }
+    pencilPageKeys.add(key);
+    registerName(pageNames, key, page);
+  }
+
+  const taskPageKeys = new Set();
+  for (const page of tasks.mentionedPages) {
+    const key = normalizePageKey(page);
+    if (!key) {
+      continue;
+    }
+    taskPageKeys.add(key);
+    registerName(pageNames, key, page);
+  }
+
+  const scopeText = proposal.scopeItems.join(" ");
+  const specText = specs.combinedText;
+  const tasksText = tasks.text;
+
+  const allPageKeys = unique([
+    ...proposalPageKeys,
+    ...pageMapPageKeys,
+    ...pencilPageKeys,
+    ...taskPageKeys
+  ]);
+  for (const key of allPageKeys) {
+    const tokens = STATE_SYNONYMS[key] || [key];
+    const row = {
+      key,
+      label: pageNames.get(key) || key,
+      proposal: proposalPageKeys.has(key),
+      pageMap: pageMapPageKeys.has(key),
+      spec: containsAnyToken(specText, tokens),
+      pencil: pencilPageKeys.has(key),
+      tasks: containsAnyToken(tasksText, tokens) || taskPageKeys.has(key)
+    };
+    result.matrix.pages.push(row);
+  }
+
+  const specStateKeys = new Set();
+  for (const state of specs.states) {
+    const key = normalizeStateKey(state);
+    if (!key) {
+      continue;
+    }
+    specStateKeys.add(key);
+    registerName(stateNames, key, state);
+  }
+
+  const pageMapStateKeys = new Set();
+  for (const state of pageMap.states) {
+    const key = normalizeStateKey(state);
+    if (!key) {
+      continue;
+    }
+    pageMapStateKeys.add(key);
+    registerName(stateNames, key, state);
+  }
+
+  const pencilStateKeys = new Set();
+  for (const state of pencilDesign.states) {
+    const key = normalizeStateKey(state);
+    if (!key) {
+      continue;
+    }
+    pencilStateKeys.add(key);
+    registerName(stateNames, key, state);
+  }
+
+  const taskStateKeys = new Set();
+  const taskText = tasks.text;
+  for (const key of specStateKeys) {
+    if (containsAnyToken(taskText, expandStateCoverageTokens(key))) {
+      taskStateKeys.add(key);
+    }
+  }
+
+  const allStateKeys = unique([...specStateKeys, ...pageMapStateKeys, ...pencilStateKeys, ...taskStateKeys]);
+  for (const key of allStateKeys) {
+    const tokens = expandStateCoverageTokens(key);
+    const row = {
+      key,
+      label: stateNames.get(key) || key,
+      spec: specStateKeys.has(key),
+      pageMap: pageMapStateKeys.has(key),
+      pencil: pencilStateKeys.has(key),
+      tasks: containsAnyToken(taskText, tokens) || taskStateKeys.has(key)
+    };
+    result.matrix.states.push(row);
+  }
+
+  result.summary.pages = result.matrix.pages.length;
+  result.summary.states = result.matrix.states.length;
+
+  for (const row of result.matrix.pages) {
+    if (row.pageMap && !row.proposal) {
+      result.warnings.push(
+        `Page propagation gap: \`${row.label}\` is in page-map but missing from proposal scope.`
+      );
+    }
+    if (row.proposal && !row.pageMap) {
+      result.warnings.push(
+        `Page propagation gap: \`${row.label}\` is in proposal scope but missing from page-map.`
+      );
+    }
+    if (row.pageMap && !row.spec) {
+      result.warnings.push(`Page propagation gap: \`${row.label}\` is in page-map but missing from specs.`);
+    }
+    if (row.pageMap && !row.tasks) {
+      result.warnings.push(`Page propagation gap: \`${row.label}\` is in page-map but missing from tasks.`);
+    }
+    if (row.tasks && !row.proposal && !row.pageMap) {
+      result.warnings.push(`Overscoped task surface: \`${row.label}\` appears in tasks but is outside proposal/page-map scope.`);
+    }
+  }
+
+  for (const row of result.matrix.states) {
+    if (row.spec && !row.pageMap) {
+      result.warnings.push(
+        `State propagation gap: \`${row.label}\` is in specs but missing from page-map states.`
+      );
+    }
+    if (row.spec && !row.pencil) {
+      result.warnings.push(
+        `State propagation gap: \`${row.label}\` is in specs but missing from pencil-design states.`
+      );
+    }
+    if (row.spec && !row.tasks) {
+      result.warnings.push(`State propagation gap: \`${row.label}\` is in specs but missing from tasks.`);
+    }
+  }
+
+  const scopeSet = new Set(proposal.scopeItems.map((item) => normalizeWhitespace(item)));
+  const nonGoalOverlap = proposal.nonGoalItems
+    .map((item) => normalizeWhitespace(item))
+    .filter((item) => scopeSet.has(item));
+  for (const value of unique(nonGoalOverlap)) {
+    result.warnings.push(`Contradictory scope signal: \`${value}\` appears in both Scope and Non-Goals.`);
+  }
+
+  result.coverage = {
+    proposal: {
+      scopeItems: proposal.scopeItems,
+      nonGoalItems: proposal.nonGoalItems,
+      pages: proposal.scopePages
+    },
+    pageMap: {
+      pages: pageMap.pages,
+      states: pageMap.states
+    },
+    specs: {
+      files: specs.files,
+      states: specs.states
+    },
+    pencilDesign: {
+      pages: pencilDesign.pages,
+      states: pencilDesign.states
+    },
+    tasks: {
+      groups: tasks.taskGroups,
+      checklistItems: tasks.checklistItems,
+      pages: tasks.mentionedPages
+    }
+  };
+}
+
+function runScopeCheck(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const strict = options.strict === true;
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const result = buildScopeResultEnvelope(projectRoot, strict);
+
+  if (!pathExists(projectRoot)) {
+    result.failures.push(`Project path does not exist: ${projectRoot}`);
+    result.notes.push("scope-check defaults to advisory mode; pass `--strict` to block on findings.");
+    result.notes.push(
+      "Promotion criteria: turn on `--strict` in CI after scope-check warning baselines are stable and reviewed."
+    );
+    return finalizeResult(result);
+  }
+
+  const changeDir = resolveChange(projectRoot, requestedChangeId, result.failures, result.notes);
+  if (!changeDir) {
+    result.notes.push("scope-check defaults to advisory mode; pass `--strict` to block on findings.");
+    result.notes.push(
+      "Promotion criteria: turn on `--strict` in CI after scope-check warning baselines are stable and reviewed."
+    );
+    return finalizeResult(result);
+  }
+  result.changeId = path.basename(changeDir);
+
+  const proposalPath = path.join(changeDir, "proposal.md");
+  const pageMapPath = path.join(projectRoot, ".da-vinci", "page-map.md");
+  const fallbackPageMapPath = path.join(changeDir, "page-map.md");
+  const pencilDesignPath = path.join(changeDir, "pencil-design.md");
+  const tasksPath = path.join(changeDir, "tasks.md");
+
+  const proposalText = readTextIfExists(proposalPath);
+  const pageMapText = readTextIfExists(pageMapPath) || readTextIfExists(fallbackPageMapPath);
+  const pencilDesignText = readTextIfExists(pencilDesignPath);
+  const tasksText = readTextIfExists(tasksPath);
+
+  if (!proposalText) {
+    result.failures.push("Missing `proposal.md` for scope-check.");
+  }
+  if (!pageMapText) {
+    result.failures.push("Missing `.da-vinci/page-map.md` (or change-local fallback) for scope-check.");
+  }
+  if (!pencilDesignText) {
+    result.failures.push("Missing `pencil-design.md` for scope-check state propagation.");
+  }
+  if (!tasksText) {
+    result.failures.push("Missing `tasks.md` for scope-check propagation.");
+  }
+
+  const specs = parseSpecs(changeDir, projectRoot);
+  if (specs.files.length === 0) {
+    result.failures.push("Missing runtime spec files under `.da-vinci/changes/<change-id>/specs/*/spec.md`.");
+  }
+  for (const record of specs.records) {
+    if (record.missingSections.length > 0 || record.emptySections.length > 0) {
+      result.warnings.push(
+        `Spec shape warning: \`${record.path}\` has incomplete runtime sections; scope-check coverage may be degraded.`
+      );
+    }
+  }
+
+  if (result.failures.length === 0) {
+    const proposal = parseProposal(proposalText);
+    const pageMap = parsePageMap(pageMapText);
+    const pencilDesign = parsePencilDesign(pencilDesignText);
+    const tasks = parseTasks(tasksText);
+    analyzeScopePropagation(result, proposal, pageMap, specs, pencilDesign, tasks);
+  }
+
+  result.warnings = unique(result.warnings);
+  result.notes = unique(result.notes);
+  result.notes.push("scope-check defaults to advisory mode; pass `--strict` to block on findings.");
+  result.notes.push(
+    "Promotion criteria: turn on `--strict` in CI after scope-check warning baselines are stable and reviewed."
+  );
+
+  return finalizeResult(result);
+}
+
+function formatScopeCheckReport(result) {
+  const lines = [
+    "Da Vinci scope-check",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Strict mode: ${result.strict ? "yes" : "no"}`,
+    `Status: ${result.status}`,
+    `Coverage rows: pages=${result.summary.pages}, states=${result.summary.states}`
+  ];
+
+  if (result.failures.length > 0) {
+    lines.push("", "Failures:");
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  if (result.notes.length > 0) {
+    lines.push("", "Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  runScopeCheck,
+  formatScopeCheckReport
+};