@xenonbyte/da-vinci-workflow 0.2.5 → 0.2.6

package/lib/maintainer-readiness.js

@@ -0,0 +1,317 @@
+const path = require("path");
+const { spawnSync } = require("child_process");
+const { validateAssets, verifyInstall } = require("./install");
+const { dedupeMessages } = require("./utils");
+
+const DEFAULT_FOCUSED_QUALITY_LANE = "quality:ci:contracts";
+const DEEPER_VALIDATION_LANES = ["npm run quality:ci:e2e", "npm run quality:ci"];
+
+function buildFocusedLaneCommand(laneScript) {
+  return `npm run ${laneScript}`;
+}
+
+function normalizeValidateAssetsResult(rawResult, repoRoot) {
+  if (!rawResult || typeof rawResult !== "object") {
+    return {
+      status: "BLOCK",
+      details: "asset validation failed",
+      failureMessage: "validate-assets failed; inspect command output for details.",
+      requiredAssets: null
+    };
+  }
+
+  const statusToken = rawResult.status === "PASS" || rawResult.status === "BLOCK"
+    ? rawResult.status
+    : "BLOCK";
+  const details =
+    rawResult.details && String(rawResult.details).trim()
+      ? String(rawResult.details).trim()
+      : statusToken === "PASS"
+      ? `required assets: ${Number(rawResult.requiredAssets) || 0}`
+      : "asset validation failed";
+  const failureMessage =
+    rawResult.failureMessage && String(rawResult.failureMessage).trim()
+      ? String(rawResult.failureMessage).trim()
+      : `validate-assets failed under ${repoRoot}; run \`npm run validate-assets\` in the target repository.`;
+
+  return {
+    status: statusToken,
+    details,
+    failureMessage,
+    requiredAssets:
+      Number.isFinite(Number(rawResult.requiredAssets)) && Number(rawResult.requiredAssets) >= 0
+        ? Number(rawResult.requiredAssets)
+        : null
+  };
+}
+
+function runValidateAssetsCheck(options = {}) {
+  const repoRoot = options.repoRoot || process.cwd();
+  if (typeof options.validateAssetsRunner === "function") {
+    return normalizeValidateAssetsResult(options.validateAssetsRunner({ repoRoot }), repoRoot);
+  }
+
+  try {
+    const assets = validateAssets({ repoRoot });
+    return {
+      status: "PASS",
+      details: `required assets: ${assets.requiredAssets}`,
+      requiredAssets: assets.requiredAssets
+    };
+  } catch (error) {
+    return {
+      status: "BLOCK",
+      details: error && error.message ? error.message : "asset validation failed",
+      failureMessage: `validate-assets failed under ${repoRoot}; run \`npm run validate-assets\` in the target repository.`
+    };
+  }
+}
+
+function normalizeFocusedLaneResult(rawResult, laneScript) {
+  const laneCommand = buildFocusedLaneCommand(laneScript);
+  if (!rawResult || typeof rawResult !== "object") {
+    return {
+      status: "BLOCK",
+      details: `${laneCommand} failed`,
+      failureMessage: `${laneCommand} failed; inspect command output for details.`
+    };
+  }
+
+  const statusToken =
+    rawResult.status === "PASS" || rawResult.status === "SKIP" || rawResult.status === "BLOCK"
+      ? rawResult.status
+      : "BLOCK";
+  const details =
+    rawResult.details && String(rawResult.details).trim()
+      ? String(rawResult.details).trim()
+      : statusToken === "PASS"
+      ? `${laneCommand} passed`
+      : statusToken === "SKIP"
+      ? `${laneCommand} skipped`
+      : `${laneCommand} failed`;
+  const failureMessage =
+    rawResult.failureMessage && String(rawResult.failureMessage).trim()
+      ? String(rawResult.failureMessage).trim()
+      : `${laneCommand} failed; run ${laneCommand} directly for details.`;
+
+  return {
+    status: statusToken,
+    details,
+    failureMessage
+  };
+}
+
+function runFocusedQualityLane(options = {}) {
+  const laneScript = String(options.focusedQualityLane || DEFAULT_FOCUSED_QUALITY_LANE).trim();
+  const normalizedLaneScript = laneScript || DEFAULT_FOCUSED_QUALITY_LANE;
+  const laneCommand = buildFocusedLaneCommand(normalizedLaneScript);
+
+  if (typeof options.focusedQualityLaneRunner === "function") {
+    return normalizeFocusedLaneResult(
+      options.focusedQualityLaneRunner({
+        laneScript: normalizedLaneScript,
+        laneCommand,
+        repoRoot: options.repoRoot || process.cwd()
+      }),
+      normalizedLaneScript
+    );
+  }
+
+  const repoRoot = options.repoRoot || process.cwd();
+  const result = spawnSync("npm", ["run", normalizedLaneScript], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    env: options.env || process.env
+  });
+
+  if (result.error) {
+    return {
+      status: "BLOCK",
+      details: `${laneCommand} failed to start`,
+      failureMessage: `${laneCommand} failed to start: ${result.error.message}`
+    };
+  }
+  if (result.status === 0) {
+    return {
+      status: "PASS",
+      details: `${laneCommand} passed`
+    };
+  }
+
+  const stderrText = String(result.stderr || "").trim();
+  const stdoutText = String(result.stdout || "").trim();
+  const detailSource = stderrText || stdoutText;
+  const summaryLine = detailSource
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .slice(-1)[0];
+
+  return {
+    status: "BLOCK",
+    details: `${laneCommand} failed`,
+    failureMessage: summaryLine
+      ? `${laneCommand} failed: ${summaryLine}`
+      : `${laneCommand} failed; inspect output for details.`
+  };
+}
+
+function runMaintainerReadinessCheck(options = {}) {
+  const repoRoot = options.repoRoot ? path.resolve(String(options.repoRoot)) : process.cwd();
+  const focusedQualityLane = String(options.focusedQualityLane || DEFAULT_FOCUSED_QUALITY_LANE).trim()
+    || DEFAULT_FOCUSED_QUALITY_LANE;
+  const focusedQualityLaneCommand = buildFocusedLaneCommand(focusedQualityLane);
+  const runFocusedQualityLaneCheck = options.runFocusedQualityLane !== false;
+  const checks = [];
+  const failures = [];
+  const warnings = [];
+  const notes = [];
+
+  const validateAssetsResult = runValidateAssetsCheck({
+    repoRoot,
+    validateAssetsRunner: options.validateAssetsRunner
+  });
+  if (validateAssetsResult.status === "PASS") {
+    checks.push({
+      id: "validate-assets",
+      status: "PASS",
+      details: validateAssetsResult.details
+    });
+  } else {
+    checks.push({
+      id: "validate-assets",
+      status: "BLOCK",
+      details: validateAssetsResult.details
+    });
+    failures.push(validateAssetsResult.failureMessage);
+  }
+
+  const installResult = verifyInstall({
+    homeDir: options.homeDir,
+    platforms: options.platforms
+  });
+  checks.push({
+    id: "verify-install",
+    status: installResult.status,
+    details: installResult.scope.known
+      ? `selected platforms: ${installResult.scope.selectedPlatforms.join(", ")}`
+      : "selected platforms: unknown scope"
+  });
+  if (installResult.status === "BLOCK") {
+    failures.push(...installResult.failures);
+  } else if (installResult.status === "WARN") {
+    warnings.push(...installResult.warnings);
+  }
+  notes.push(...installResult.notes);
+
+  if (!runFocusedQualityLaneCheck) {
+    checks.push({
+      id: focusedQualityLaneCommand,
+      status: "SKIP",
+      details: "skipped by caller"
+    });
+  } else if (failures.length > 0) {
+    checks.push({
+      id: focusedQualityLaneCommand,
+      status: "SKIP",
+      details: "skipped because blocking prerequisite checks failed"
+    });
+  } else {
+    const focusedLaneResult = runFocusedQualityLane({
+      focusedQualityLane,
+      focusedQualityLaneRunner: options.focusedQualityLaneRunner,
+      repoRoot,
+      env: options.env
+    });
+    checks.push({
+      id: focusedQualityLaneCommand,
+      status: focusedLaneResult.status,
+      details: focusedLaneResult.details
+    });
+    if (focusedLaneResult.status === "BLOCK") {
+      failures.push(focusedLaneResult.failureMessage);
+    }
+  }
+
+  const status = failures.length > 0 ? "BLOCK" : warnings.length > 0 ? "WARN" : "PASS";
+  const nextSteps = [];
+  if (failures.length > 0) {
+    nextSteps.push("Resolve failing checks, then rerun `da-vinci maintainer-readiness`.");
+  }
+  if (warnings.length > 0) {
+    nextSteps.push("Resolve warnings or accept degraded coverage before broader changes.");
+  }
+  nextSteps.push(
+    "The canonical readiness surface is diagnosis only; bootstrap/setup still starts with install plus verify-install."
+  );
+  nextSteps.push(`If focused readiness lane did not pass, run \`${focusedQualityLaneCommand}\` directly for details.`);
+  nextSteps.push("Before high-risk changes, run deeper optional lanes such as `npm run quality:ci:e2e` or `npm run quality:ci`.");
+
+  return {
+    status,
+    repoRoot,
+    canonicalGuide: "docs/maintainer-bootstrap.md",
+    focusedQualityLane: focusedQualityLaneCommand,
+    componentChecks: ["npm run validate-assets", "da-vinci verify-install", focusedQualityLaneCommand],
+    scope: installResult.scope,
+    checks,
+    failures: dedupeMessages(failures, { normalize: (item) => String(item || "").trim() }),
+    warnings: dedupeMessages(warnings, { normalize: (item) => String(item || "").trim() }),
+    notes: dedupeMessages(notes, { normalize: (item) => String(item || "").trim() }),
+    nextSteps: dedupeMessages(nextSteps, { normalize: (item) => String(item || "").trim() }),
+    deeperValidationLanes: DEEPER_VALIDATION_LANES.slice()
+  };
+}
+
+function formatMaintainerReadinessReport(result) {
+  const scopeLabel = result.scope && result.scope.known
+    ? result.scope.selectedPlatforms.join(", ")
+    : "unknown";
+  const lines = [
+    "Da Vinci maintainer-readiness",
+    `Status: ${result.status}`,
+    `Repo root: ${result.repoRoot || "unknown"}`,
+    `Guide: ${result.canonicalGuide}`,
+    "Surface: diagnosis/readiness (repository health), not bootstrap/setup",
+    `Platform scope: ${scopeLabel}`,
+    "Checks:"
+  ];
+
+  for (const check of Array.isArray(result.checks) ? result.checks : []) {
+    lines.push(`- ${check.id}: ${check.status}${check.details ? ` (${check.details})` : ""}`);
+  }
+
+  if (Array.isArray(result.failures) && result.failures.length > 0) {
+    lines.push("Failures:");
+    for (const message of result.failures) {
+      lines.push(`- ${message}`);
+    }
+  }
+  if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+    lines.push("Warnings:");
+    for (const message of result.warnings) {
+      lines.push(`- ${message}`);
+    }
+  }
+  if (Array.isArray(result.notes) && result.notes.length > 0) {
+    lines.push("Notes:");
+    for (const message of result.notes) {
+      lines.push(`- ${message}`);
+    }
+  }
+  if (Array.isArray(result.nextSteps) && result.nextSteps.length > 0) {
+    lines.push("Next steps:");
+    for (const step of result.nextSteps) {
+      lines.push(`- ${step}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+module.exports = {
+  runMaintainerReadinessCheck,
+  formatMaintainerReadinessReport,
+  runFocusedQualityLane,
+  runValidateAssetsCheck
+};

package/lib/planning-parsers.js

@@ -12,6 +12,125 @@ 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;
+const PLANNING_ANCHOR_ID_PATTERN = /^(behavior|acceptance|state|mapping)-[a-z0-9._-]+$/i;
+const ARTIFACT_ANCHOR_PATTERN = /^artifact:([^#\s]+)(?:#(.+))?$/i;
+const AMBIGUITY_RECORD_PATTERN =
+  /^\s*-\s*\[(blocking|bounded|advisory)\]\s*([a-z][a-z0-9_-]{1,40})\s*:\s*(.+?)\s*$/i;
+
+function parsePlanningAnchorRef(value) {
+  const raw = String(value || "").trim();
+  if (!raw) {
+    return {
+      raw,
+      ref: "",
+      valid: false,
+      reason: "empty_anchor"
+    };
+  }
+
+  const ref = raw.replace(/[`"'(),]/g, "").trim();
+  if (!ref) {
+    return {
+      raw,
+      ref,
+      valid: false,
+      reason: "empty_anchor"
+    };
+  }
+
+  if (PLANNING_ANCHOR_ID_PATTERN.test(ref)) {
+    const family = String(ref.split("-")[0] || "").toLowerCase();
+    return {
+      raw,
+      ref,
+      valid: true,
+      type: "sidecar_id",
+      family
+    };
+  }
+
+  const artifactMatch = ref.match(ARTIFACT_ANCHOR_PATTERN);
+  if (artifactMatch) {
+    return {
+      raw,
+      ref,
+      valid: true,
+      type: "artifact_ref",
+      artifactPath: String(artifactMatch[1] || "").trim(),
+      artifactToken: String(artifactMatch[2] || "").trim()
+    };
+  }
+
+  return {
+    raw,
+    ref,
+    valid: false,
+    reason: "unsupported_anchor_format"
+  };
+}
+
+function parseAmbiguityRecords(text) {
+  const source = String(text || "").replace(/\r\n?/g, "\n");
+  const lines = source.split("\n");
+  const records = [];
+  const malformed = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = String(lines[index] || "");
+    const match = line.match(AMBIGUITY_RECORD_PATTERN);
+    if (match) {
+      const severity = String(match[1] || "").toLowerCase();
+      const ambiguityClass = String(match[2] || "").toLowerCase();
+      const payload = String(match[3] || "").trim();
+      const segments = payload.split(/\s+\|\s+/).map((item) => item.trim()).filter(Boolean);
+      const summary = String(segments.shift() || "").trim();
+      const metadata = {};
+      for (const segment of segments) {
+        const delimiter = segment.indexOf(":");
+        if (delimiter === -1) {
+          malformed.push({
+            line: index + 1,
+            text: line,
+            reason: "malformed_metadata_segment"
+          });
+          continue;
+        }
+        const key = String(segment.slice(0, delimiter) || "").trim().toLowerCase();
+        const value = String(segment.slice(delimiter + 1) || "").trim();
+        if (!key || !value) {
+          malformed.push({
+            line: index + 1,
+            text: line,
+            reason: "empty_metadata_key_or_value"
+          });
+          continue;
+        }
+        metadata[key] = value;
+      }
+      records.push({
+        line: index + 1,
+        severity,
+        ambiguityClass,
+        summary,
+        metadata
+      });
+      continue;
+    }
+
+    if (/\[(?:blocking|bounded|advisory)\]/i.test(line) && /:\s*/.test(line)) {
+      malformed.push({
+        line: index + 1,
+        text: line,
+        reason: "malformed_ambiguity_record"
+      });
+    }
+  }
+
+  return {
+    records,
+    malformed
+  };
+}
 
 function toPositiveInteger(value, fallback) {
   const parsed = Number(value);
@@ -33,6 +152,25 @@ function normalizeText(value) {
     .trim();
 }
 
+function tokenizeNormalizedWords(value, options = {}) {
+  const normalized = normalizeText(value);
+  const pattern = options.pattern instanceof RegExp ? options.pattern : /[a-z0-9_-]{3,}/g;
+  const stopWords = options.stopWords instanceof Set ? options.stopWords : null;
+  const words = normalized.match(pattern) || [];
+  return unique(words.filter((word) => !stopWords || !stopWords.has(word)));
+}
+
+function textContainsAnyNormalizedToken(source, tokens) {
+  if (!Array.isArray(tokens) || tokens.length === 0) {
+    return false;
+  }
+  const normalizedSource = normalizeText(source);
+  return tokens.some((token) => {
+    const normalizedToken = normalizeText(token);
+    return normalizedToken && normalizedSource.includes(normalizedToken);
+  });
+}
+
 function parseListItems(sectionText) {
   const normalized = String(sectionText || "").replace(/\r\n?/g, "\n").trim();
   if (!normalized) {
@@ -477,6 +615,8 @@ function analyzeTaskGroup(section) {
   const placeholderItems = [];
   const rawFileReferences = [];
   const executionHints = [];
+  const planningAnchorRecords = [];
+  const malformedAnchorRecords = [];
 
   const lines = Array.isArray(section.lines) ? section.lines : [];
   for (let index = 0; index < lines.length; index += 1) {
@@ -517,6 +657,31 @@ function analyzeTaskGroup(section) {
         targetFiles.push(...extractFileReferences(entry));
       }
     }
+
+    if (/^\s*planning anchors\s*:\s*$/i.test(line)) {
+      for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+        const followLine = String(lines[cursor] || "");
+        if (/^\s*$/.test(followLine)) {
+          continue;
+        }
+        if (/^\s{0,3}##\s+/.test(followLine)) {
+          break;
+        }
+        if (/^\s*[A-Za-z][A-Za-z0-9 _-]{0,80}\s*:\s*$/.test(followLine)) {
+          break;
+        }
+        const itemMatch = followLine.match(/^\s*-\s+(.+)$/);
+        if (!itemMatch) {
+          break;
+        }
+        const anchorRecord = parsePlanningAnchorRef(String(itemMatch[1] || "").trim());
+        if (anchorRecord.valid) {
+          planningAnchorRecords.push(anchorRecord);
+        } else {
+          malformedAnchorRecords.push(anchorRecord);
+        }
+      }
+    }
   }
 
   for (const item of section.checklistItems) {
@@ -532,6 +697,16 @@ function analyzeTaskGroup(section) {
     if (executionIntent) {
       executionHints.push(executionIntent);
     }
+
+    const inlineAnchorMatches = String(item.text || "").matchAll(/\banchor\s*:\s*([^\s,;]+)/gi);
+    for (const anchorMatch of inlineAnchorMatches) {
+      const anchorRecord = parsePlanningAnchorRef(String(anchorMatch[1] || "").trim());
+      if (anchorRecord.valid) {
+        planningAnchorRecords.push(anchorRecord);
+      } else {
+        malformedAnchorRecords.push(anchorRecord);
+      }
+    }
   }
 
   const mergedFileReferences = unique([...targetFiles, ...rawFileReferences]);
@@ -551,7 +726,10 @@ function analyzeTaskGroup(section) {
     reviewIntent: hasReviewIntent(joinedContent),
     testingIntent: hasTestingIntent(joinedContent),
     codeChangeLikely: looksLikeCodeChange(joinedContent),
-    placeholderItems: unique(placeholderItems.filter(Boolean))
+    placeholderItems: unique(placeholderItems.filter(Boolean)),
+    planningAnchors: unique(planningAnchorRecords.map((item) => item.ref)),
+    anchorRecords: planningAnchorRecords,
+    malformedAnchors: malformedAnchorRecords
   };
 }
 
@@ -639,6 +817,9 @@ function parseTasksArtifact(text) {
       testingIntent: section.testingIntent,
       codeChangeLikely: section.codeChangeLikely,
       placeholderItems: section.placeholderItems,
+      planningAnchors: section.planningAnchors,
+      anchorRecords: section.anchorRecords,
+      malformedAnchors: section.malformedAnchors,
       checklistItems: section.checklistItems
     };
   });
@@ -769,6 +950,8 @@ function readChangeArtifacts(projectRoot, changeId) {
   return {
     changeDir,
     proposalPath: path.join(changeDir, "proposal.md"),
+    designBriefPath: path.join(changeDir, "design-brief.md"),
+    designPath: path.join(changeDir, "design.md"),
     pageMapPath: pathExists(pageMapPath) ? pageMapPath : fallbackPageMapPath,
     tasksPath: path.join(changeDir, "tasks.md"),
     bindingsPath: path.join(changeDir, "pencil-bindings.md"),
@@ -780,6 +963,8 @@ function readChangeArtifacts(projectRoot, changeId) {
 function readArtifactTexts(paths) {
   return {
     proposal: readTextIfExists(paths.proposalPath),
+    designBrief: readTextIfExists(paths.designBriefPath),
+    design: readTextIfExists(paths.designPath),
     pageMap: readTextIfExists(paths.pageMapPath),
     tasks: readTextIfExists(paths.tasksPath),
     bindings: readTextIfExists(paths.bindingsPath),
@@ -790,7 +975,11 @@ function readArtifactTexts(paths) {
 
 module.exports = {
   normalizeText,
+  tokenizeNormalizedWords,
+  textContainsAnyNormalizedToken,
   parseListItems,
+  parsePlanningAnchorRef,
+  parseAmbiguityRecords,
   unique,
   resolveImplementationLanding,
   listImmediateDirs,

package/lib/planning-quality-utils.js

@@ -0,0 +1,81 @@
+const { STATUS } = require("./workflow-contract");
+const { resolveChangeDir } = require("./planning-parsers");
+
+const COMMON_STOP_WORDS = Object.freeze([
+  "the",
+  "and",
+  "for",
+  "with",
+  "from",
+  "that",
+  "this",
+  "then",
+  "when",
+  "into",
+  "only",
+  "each",
+  "user",
+  "users",
+  "page",
+  "state",
+  "states",
+  "input",
+  "inputs",
+  "output",
+  "outputs",
+  "should",
+  "must",
+  "shall",
+  "able",
+  "about",
+  "after",
+  "before",
+  "during",
+  "while",
+  "where",
+  "there",
+  "have",
+  "has"
+]);
+
+function buildStopWordSet(extraWords = []) {
+  return new Set([...COMMON_STOP_WORDS, ...(Array.isArray(extraWords) ? extraWords : [])]);
+}
+
+function buildBasePlanningResultEnvelope(projectRoot, strict) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    strict
+  };
+}
+
+function finalizePlanningResult(result) {
+  const hasFindings = result.failures.length > 0 || result.warnings.length > 0;
+  if (!hasFindings) {
+    result.status = STATUS.PASS;
+    return result;
+  }
+
+  result.status = result.strict ? STATUS.BLOCK : STATUS.WARN;
+  return result;
+}
+
+function resolveChangeWithFindings(projectRoot, requestedChangeId, failures, notes) {
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  failures.push(...resolved.failures);
+  notes.push(...resolved.notes);
+  return resolved.changeDir;
+}
+
+module.exports = {
+  COMMON_STOP_WORDS,
+  buildStopWordSet,
+  buildBasePlanningResultEnvelope,
+  finalizePlanningResult,
+  resolveChangeWithFindings
+};