@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/lint-spec.js

@@ -0,0 +1,408 @@
+const fs = require("fs");
+const path = require("path");
+const { pathExists } = require("./utils");
+const { STATUS } = require("./workflow-contract");
+const { parseRuntimeSpecMarkdown } = require("./artifact-parsers");
+const { resolveChangeDir, detectSpecFiles } = require("./planning-parsers");
+
+const MAX_EXAMPLE_ITEMS = 3;
+const TESTABLE_ACCEPTANCE_PATTERN =
+  /\b(must|shall|should|when|then|if|display|show|hide|render|return|emit|within|ms|seconds?|error|success|true|false)\b/i;
+const VAGUE_ACCEPTANCE_PATTERN =
+  /\b(good|nice|better|clean|intuitive|seamless|smooth|easy|simple|beautiful|fast)\b/i;
+const WORD_PATTERN = /[a-z][a-z0-9_-]{2,}/gi;
+const STOP_WORDS = new Set([
+  "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",
+  "into"
+]);
+const EXPLICIT_CONTRADICTORY_PAIRS = [
+  ["enabled", "disabled"],
+  ["active", "inactive"],
+  ["online", "offline"],
+  ["visible", "hidden"],
+  ["open", "closed"],
+  ["expanded", "collapsed"],
+  ["authenticated", "unauthenticated"],
+  ["authorized", "unauthorized"]
+];
+
+function buildResultEnvelope(projectRoot, strict) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    strict,
+    specs: [],
+    summary: {
+      checked: 0
+    }
+  };
+}
+
+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 normalizeText(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[`*_~]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function toKeywordSet(value) {
+  const words = String(value || "").match(WORD_PATTERN) || [];
+  return new Set(
+    words
+      .map((word) => String(word || "").toLowerCase())
+      .filter((word) => word && !STOP_WORDS.has(word))
+  );
+}
+
+function containsAnyKeyword(text, keywords) {
+  if (!Array.isArray(keywords) || keywords.length === 0) {
+    return false;
+  }
+  const source = normalizeText(text);
+  return keywords.some((keyword) => source.includes(keyword));
+}
+
+function expandCoverageKeywords(keywords) {
+  const expanded = [];
+  for (const keyword of keywords || []) {
+    if (!keyword) {
+      continue;
+    }
+    expanded.push(keyword);
+
+    if (keyword === "success") {
+      expanded.push("succeed", "succeeds", "succeeded");
+      continue;
+    }
+    if (keyword === "error") {
+      expanded.push("fail", "fails", "failed", "failure");
+      continue;
+    }
+    if (keyword === "loading") {
+      expanded.push("load", "spinner");
+    }
+  }
+  return dedupe(expanded);
+}
+
+function dedupe(values) {
+  return Array.from(new Set((values || []).filter(Boolean)));
+}
+
+function appendSectionPresenceFindings(relativePath, parsed, failures) {
+  for (const heading of parsed.missingSections) {
+    failures.push(`${relativePath}: missing required section \`${heading}\`.`);
+  }
+  for (const heading of parsed.emptySections) {
+    failures.push(`${relativePath}: required section \`${heading}\` is empty.`);
+  }
+
+  const requiredItemSections = [
+    "behavior",
+    "states",
+    "inputs",
+    "outputs",
+    "acceptance",
+    "edgeCases"
+  ];
+  for (const sectionId of requiredItemSections) {
+    const section = parsed.sections[sectionId];
+    if (!section || !section.present || section.empty) {
+      continue;
+    }
+    if (section.items.length === 0) {
+      failures.push(
+        `${relativePath}: section \`${section.heading}\` is present but no list or paragraph items were parsed.`
+      );
+    }
+  }
+}
+
+function appendAcceptanceQualityFindings(relativePath, parsed, warnings) {
+  const acceptanceItems = parsed.sections.acceptance ? parsed.sections.acceptance.items : [];
+  for (const item of acceptanceItems) {
+    const normalized = String(item || "").trim();
+    if (!normalized) {
+      continue;
+    }
+
+    const hasTestableSignal = TESTABLE_ACCEPTANCE_PATTERN.test(normalized);
+    const looksVague = VAGUE_ACCEPTANCE_PATTERN.test(normalized);
+    const hasMetricHint = /\d/.test(normalized);
+    if (hasTestableSignal && (!looksVague || hasMetricHint)) {
+      continue;
+    }
+
+    warnings.push(
+      `${relativePath}: acceptance item may be non-testable: "${normalized.slice(0, 120)}".`
+    );
+  }
+}
+
+function appendStateContradictionFindings(relativePath, parsed, warnings) {
+  const stateItems = parsed.sections.states ? parsed.sections.states.items : [];
+  const normalizedStates = stateItems.map((value) => normalizeText(value)).filter(Boolean);
+  const uniqueStates = new Set(normalizedStates);
+
+  if (uniqueStates.size !== normalizedStates.length) {
+    warnings.push(`${relativePath}: duplicate state names were detected.`);
+  }
+
+  for (const [left, right] of EXPLICIT_CONTRADICTORY_PAIRS) {
+    if (uniqueStates.has(left) && uniqueStates.has(right)) {
+      warnings.push(`${relativePath}: contradictory state pair detected: "${left}" and "${right}".`);
+    }
+  }
+
+  const prefixedNegationMap = new Map();
+  for (const state of uniqueStates) {
+    const match = state.match(/^(?:not|non)\s+(.+)$/);
+    if (!match) {
+      continue;
+    }
+    const positive = String(match[1] || "").trim();
+    if (!positive) {
+      continue;
+    }
+    prefixedNegationMap.set(positive, state);
+  }
+
+  for (const [positive, negative] of prefixedNegationMap.entries()) {
+    if (uniqueStates.has(positive)) {
+      warnings.push(
+        `${relativePath}: contradictory state pair detected: "${positive}" and "${negative}".`
+      );
+    }
+  }
+}
+
+function appendCoverageFindings(relativePath, parsed, warnings) {
+  const behaviorItems = parsed.sections.behavior ? parsed.sections.behavior.items : [];
+  const stateItems = parsed.sections.states ? parsed.sections.states.items : [];
+  const acceptanceItems = parsed.sections.acceptance ? parsed.sections.acceptance.items : [];
+
+  const behaviorText = behaviorItems.join(" ");
+  const acceptanceText = acceptanceItems.join(" ");
+  const combinedCoverageText = `${behaviorText} ${acceptanceText}`.trim();
+
+  for (const stateItem of stateItems) {
+    const keywords = expandCoverageKeywords(Array.from(toKeywordSet(stateItem)));
+    if (keywords.length === 0) {
+      continue;
+    }
+    if (!containsAnyKeyword(combinedCoverageText, keywords)) {
+      warnings.push(
+        `${relativePath}: state coverage gap: "${stateItem}" does not appear in behavior or acceptance sections.`
+      );
+    }
+  }
+
+  const uncoveredBehaviorItems = [];
+  for (const behaviorItem of behaviorItems) {
+    const keywords = Array.from(toKeywordSet(behaviorItem));
+    if (keywords.length === 0) {
+      continue;
+    }
+    if (!containsAnyKeyword(acceptanceText, keywords)) {
+      uncoveredBehaviorItems.push(behaviorItem);
+    }
+  }
+
+  if (uncoveredBehaviorItems.length > 0) {
+    const preview = uncoveredBehaviorItems.slice(0, MAX_EXAMPLE_ITEMS).join(" | ");
+    warnings.push(
+      `${relativePath}: acceptance coverage may miss behavior items (${uncoveredBehaviorItems.length}): ${preview}`
+    );
+  }
+}
+
+function resolveChange(projectRoot, requestedChangeId, failures, notes) {
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  failures.push(...resolved.failures);
+  notes.push(...resolved.notes);
+  return resolved.changeDir;
+}
+
+function lintRuntimeSpecs(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const strict = options.strict === true;
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const result = buildResultEnvelope(projectRoot, strict);
+
+  if (!pathExists(projectRoot)) {
+    result.failures.push(`Project path does not exist: ${projectRoot}`);
+    result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
+    return finalizeResult(result);
+  }
+
+  const changeDir = resolveChange(projectRoot, requestedChangeId, result.failures, result.notes);
+  if (!changeDir) {
+    result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
+    return finalizeResult(result);
+  }
+  result.changeId = path.basename(changeDir);
+
+  const specsDir = path.join(changeDir, "specs");
+  const specFiles = detectSpecFiles(specsDir);
+  if (specFiles.length === 0) {
+    result.failures.push("No runtime spec files found under `.da-vinci/changes/<change-id>/specs/*/spec.md`.");
+    result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
+    return finalizeResult(result);
+  }
+
+  for (const specPath of specFiles) {
+    const relativePath = path.relative(projectRoot, specPath) || specPath;
+    const raw = fs.readFileSync(specPath, "utf8");
+    const parsed = parseRuntimeSpecMarkdown(raw);
+    const fileFailures = [];
+    const fileWarnings = [];
+    const fileNotes = [];
+
+    appendSectionPresenceFindings(relativePath, parsed, fileFailures);
+    appendAcceptanceQualityFindings(relativePath, parsed, fileWarnings);
+    appendStateContradictionFindings(relativePath, parsed, fileWarnings);
+    appendCoverageFindings(relativePath, parsed, fileWarnings);
+
+    if (/^\s*##\s+ADDED Requirements\b/im.test(raw)) {
+      fileNotes.push(
+        `${relativePath}: OpenSpec planning sections detected. Runtime lint still requires Da Vinci runtime headings.`
+      );
+    }
+
+    result.failures.push(...fileFailures);
+    result.warnings.push(...fileWarnings);
+    result.notes.push(...fileNotes);
+    result.specs.push({
+      path: relativePath,
+      status:
+        fileFailures.length > 0 || fileWarnings.length > 0
+          ? strict
+            ? STATUS.BLOCK
+            : STATUS.WARN
+          : STATUS.PASS,
+      failures: fileFailures,
+      warnings: fileWarnings,
+      notes: fileNotes,
+      parsed: {
+        missingSections: parsed.missingSections,
+        emptySections: parsed.emptySections,
+        itemCounts: {
+          behavior: parsed.sections.behavior.items.length,
+          states: parsed.sections.states.items.length,
+          inputs: parsed.sections.inputs.items.length,
+          outputs: parsed.sections.outputs.items.length,
+          acceptance: parsed.sections.acceptance.items.length,
+          edgeCases: parsed.sections.edgeCases.items.length
+        }
+      }
+    });
+  }
+
+  result.summary.checked = result.specs.length;
+  result.failures = dedupe(result.failures);
+  result.warnings = dedupe(result.warnings);
+  result.notes = dedupe(result.notes);
+  result.notes.push("lint-spec uses advisory mode by default; use `--strict` to block on findings.");
+
+  return finalizeResult(result);
+}
+
+function formatLintSpecReport(result) {
+  const lines = [
+    "Da Vinci lint-spec",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Strict mode: ${result.strict ? "yes" : "no"}`,
+    `Status: ${result.status}`,
+    `Spec files checked: ${result.summary.checked}`
+  ];
+
+  if (result.specs.length > 0) {
+    lines.push("", "Spec results:");
+    for (const spec of result.specs) {
+      lines.push(`- ${spec.path}: ${spec.status}`);
+    }
+  }
+
+  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 = {
+  lintRuntimeSpecs,
+  formatLintSpecReport
+};

package/lib/lint-tasks.js

@@ -0,0 +1,176 @@
+const path = require("path");
+const { STATUS } = require("./workflow-contract");
+const {
+  normalizeText,
+  unique,
+  resolveChangeDir,
+  parseTasksArtifact,
+  parseRuntimeSpecs,
+  readChangeArtifacts,
+  readArtifactTexts
+} = require("./planning-parsers");
+
+function buildEnvelope(projectRoot, strict) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    strict,
+    summary: {
+      groups: 0,
+      checklistItems: 0
+    }
+  };
+}
+
+function finalize(result) {
+  result.failures = unique(result.failures);
+  result.warnings = unique(result.warnings);
+  result.notes = unique(result.notes);
+  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 findMissingTaskGroupSequence(taskGroups) {
+  const numeric = taskGroups
+    .map((group) => Number.parseInt(String(group.id || "").split(".")[0], 10))
+    .filter(Number.isFinite)
+    .sort((a, b) => a - b);
+  if (numeric.length === 0) {
+    return [];
+  }
+  const missing = [];
+  for (let value = numeric[0]; value <= numeric[numeric.length - 1]; value += 1) {
+    if (!numeric.includes(value)) {
+      missing.push(value);
+    }
+  }
+  return missing;
+}
+
+function lintTasks(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const strict = options.strict === true;
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const result = buildEnvelope(projectRoot, strict);
+
+  const resolved = resolveChangeDir(projectRoot, requestedChangeId);
+  result.failures.push(...resolved.failures);
+  result.notes.push(...resolved.notes);
+  if (!resolved.changeDir) {
+    result.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
+    return finalize(result);
+  }
+  result.changeId = resolved.changeId;
+
+  const artifactPaths = readChangeArtifacts(projectRoot, resolved.changeId);
+  const artifacts = readArtifactTexts(artifactPaths);
+  if (!artifacts.tasks) {
+    result.failures.push("Missing `tasks.md` for lint-tasks.");
+    result.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
+    return finalize(result);
+  }
+
+  const parsedTasks = parseTasksArtifact(artifacts.tasks);
+  const specRecords = parseRuntimeSpecs(resolved.changeDir, projectRoot);
+  const taskText = normalizeText(artifacts.tasks);
+
+  result.summary.groups = parsedTasks.taskGroups.length;
+  result.summary.checklistItems = parsedTasks.checklistItems.length;
+
+  if (parsedTasks.taskGroups.length === 0) {
+    result.failures.push("`tasks.md` is missing top-level numbered task groups (for example `## 1. Setup`).");
+  }
+
+  const missingSequence = findMissingTaskGroupSequence(parsedTasks.taskGroups);
+  if (missingSequence.length > 0) {
+    result.warnings.push(
+      `Task-group numbering is non-contiguous. Missing top-level groups: ${missingSequence.join(", ")}.`
+    );
+  }
+
+  const nonNumericGroups = parsedTasks.taskGroups.filter(
+    (group) => !/^\d+(?:\.\d+)*$/.test(String(group.id || ""))
+  );
+  if (nonNumericGroups.length > 0) {
+    result.warnings.push("Some task-group headings are not numeric and may be skipped by execution metadata.");
+  }
+
+  if (parsedTasks.checklistItems.length === 0) {
+    result.failures.push("`tasks.md` has no checklist items.");
+  }
+
+  const hasVerificationAction =
+    parsedTasks.taskGroups.some((group) => /verify|verification|coverage/i.test(group.title)) ||
+    parsedTasks.checklistItems.some((item) => /verify|verification|coverage/i.test(item.text));
+  if (!hasVerificationAction) {
+    result.warnings.push("Missing explicit verification actions in `tasks.md`.");
+  }
+
+  for (const specRecord of specRecords) {
+    const behaviorItems = specRecord.parsed.sections.behavior.items || [];
+    for (const behaviorItem of behaviorItems) {
+      const normalizedBehavior = normalizeText(behaviorItem)
+        .split(" ")
+        .filter((token) => token.length >= 4)
+        .slice(0, 6);
+      if (normalizedBehavior.length === 0) {
+        continue;
+      }
+      const covered = normalizedBehavior.some((token) => taskText.includes(token));
+      if (!covered) {
+        result.warnings.push(
+          `Planned behavior may be uncovered in tasks: "${behaviorItem}" (${specRecord.path}).`
+        );
+      }
+    }
+  }
+
+  result.notes.push("lint-tasks defaults to advisory mode; pass `--strict` to block on findings.");
+  return finalize(result);
+}
+
+function formatLintTasksReport(result) {
+  const lines = [
+    "Da Vinci lint-tasks",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Strict mode: ${result.strict ? "yes" : "no"}`,
+    `Status: ${result.status}`,
+    `Task groups: ${result.summary.groups}`,
+    `Checklist items: ${result.summary.checklistItems}`
+  ];
+
+  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 = {
+  lintTasks,
+  formatLintTasksReport
+};