@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.1

package/lib/execution-signals.js

@@ -0,0 +1,136 @@
+const fs = require("fs");
+const path = require("path");
+const { pathExists, writeFileAtomic } = require("./utils");
+
+function resolveSignalsDir(projectRoot) {
+  return path.join(projectRoot, ".da-vinci", "state", "execution-signals");
+}
+
+function parseSignalFileName(fileName) {
+  const base = String(fileName || "").replace(/\.json$/i, "");
+  const separatorIndex = base.indexOf("__");
+  if (separatorIndex === -1) {
+    return {
+      changeId: "",
+      surface: ""
+    };
+  }
+  return {
+    changeId: base.slice(0, separatorIndex),
+    surface: base.slice(separatorIndex + 2)
+  };
+}
+
+function sanitizeSurfaceName(surface) {
+  return String(surface || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function buildSignalPath(projectRoot, changeId, surface) {
+  const safeSurface = sanitizeSurfaceName(surface);
+  const safeChangeId = String(changeId || "global")
+    .trim()
+    .replace(/[^A-Za-z0-9._-]+/g, "-");
+  return path.join(resolveSignalsDir(projectRoot), `${safeChangeId}__${safeSurface}.json`);
+}
+
+function writeExecutionSignal(projectRoot, payload) {
+  const changeId = payload && payload.changeId ? String(payload.changeId).trim() : "global";
+  const signal = {
+    version: 1,
+    surface: payload.surface,
+    status: payload.status,
+    advisory: payload.advisory !== false,
+    strict: payload.strict === true,
+    failures: Array.isArray(payload.failures) ? payload.failures : [],
+    warnings: Array.isArray(payload.warnings) ? payload.warnings : [],
+    notes: Array.isArray(payload.notes) ? payload.notes : [],
+    timestamp: new Date().toISOString(),
+    changeId
+  };
+
+  const targetPath = buildSignalPath(projectRoot, changeId, payload.surface);
+  fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+  writeFileAtomic(targetPath, `${JSON.stringify(signal, null, 2)}\n`);
+  return targetPath;
+}
+
+function readExecutionSignals(projectRoot, options = {}) {
+  const changeId = options.changeId ? String(options.changeId).trim() : "";
+  const signalsDir = resolveSignalsDir(projectRoot);
+  if (!pathExists(signalsDir)) {
+    return [];
+  }
+
+  const entries = fs
+    .readdirSync(signalsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".json"));
+  const loaded = [];
+
+  for (const entry of entries) {
+    const absolutePath = path.join(signalsDir, entry.name);
+    const parsedName = parseSignalFileName(entry.name);
+    try {
+      const payload = JSON.parse(fs.readFileSync(absolutePath, "utf8"));
+      if (changeId && String(payload.changeId || "") !== changeId) {
+        continue;
+      }
+      loaded.push({
+        ...payload,
+        path: absolutePath
+      });
+    } catch (error) {
+      const discoveredChangeId = String(parsedName.changeId || "").trim();
+      if (changeId && discoveredChangeId && discoveredChangeId !== changeId) {
+        continue;
+      }
+      let timestamp = new Date().toISOString();
+      try {
+        const stat = fs.statSync(absolutePath);
+        timestamp = new Date(stat.mtimeMs).toISOString();
+      } catch (_statError) {
+        // Keep fallback timestamp.
+      }
+      loaded.push({
+        version: 1,
+        surface: "signal-file-parse",
+        status: "WARN",
+        advisory: true,
+        strict: false,
+        failures: [],
+        warnings: [
+          `Malformed execution signal ignored: ${entry.name} (${error && error.message ? error.message : "parse error"})`
+        ],
+        notes: [],
+        timestamp,
+        changeId: discoveredChangeId || "global",
+        path: absolutePath
+      });
+    }
+  }
+
+  return loaded.sort((left, right) =>
+    String(right.timestamp || "").localeCompare(String(left.timestamp || ""))
+  );
+}
+
+function summarizeSignalsBySurface(signals) {
+  const summary = {};
+  for (const signal of signals || []) {
+    const key = sanitizeSurfaceName(signal.surface || "");
+    if (!key || summary[key]) {
+      continue;
+    }
+    summary[key] = signal;
+  }
+  return summary;
+}
+
+module.exports = {
+  writeExecutionSignal,
+  readExecutionSignals,
+  summarizeSignalsBySurface
+};

package/lib/lint-bindings.js

@@ -0,0 +1,143 @@
+const path = require("path");
+const { STATUS } = require("./workflow-contract");
+const {
+  unique,
+  resolveImplementationLanding,
+  resolveChangeDir,
+  parseBindingsArtifact,
+  readChangeArtifacts,
+  readArtifactTexts
+} = require("./planning-parsers");
+
+function buildEnvelope(projectRoot, strict) {
+  return {
+    status: STATUS.PASS,
+    failures: [],
+    warnings: [],
+    notes: [],
+    projectRoot,
+    changeId: null,
+    strict,
+    summary: {
+      mappings: 0,
+      malformed: 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 lintBindings(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-bindings 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.bindings) {
+    result.failures.push("Missing `pencil-bindings.md` for lint-bindings.");
+    result.notes.push("lint-bindings defaults to advisory mode; pass `--strict` to block on findings.");
+    return finalize(result);
+  }
+
+  const parsed = parseBindingsArtifact(artifacts.bindings);
+  result.summary.mappings = parsed.mappings.length;
+  result.summary.malformed = parsed.malformed.length;
+
+  if (parsed.mappings.length === 0) {
+    result.failures.push("No implementation-to-Pencil mappings were parsed from `pencil-bindings.md`.");
+  }
+  if (parsed.malformed.length > 0) {
+    for (const malformed of parsed.malformed) {
+      result.warnings.push(`Malformed binding mapping entry: "${malformed}".`);
+    }
+  }
+
+  for (const mapping of parsed.mappings) {
+    if (!mapping.implementation || !mapping.designPage) {
+      result.warnings.push(`Malformed binding mapping entry: "${mapping.raw}".`);
+      continue;
+    }
+
+    const landing = resolveImplementationLanding(projectRoot, mapping.implementation);
+    if (!landing) {
+      const noteContainsIntentionalGap = parsed.notes.some((note) =>
+        /missing|todo|gap|pending|temporary/i.test(note)
+      );
+      if (noteContainsIntentionalGap) {
+        result.warnings.push(
+          `Unresolved implementation landing for "${mapping.implementation}" (allowed by explicit notes).`
+        );
+      } else {
+        result.warnings.push(`Unresolved implementation landing for "${mapping.implementation}".`);
+      }
+    }
+
+    if (mapping.designSource && !String(mapping.designSource).includes(".pen")) {
+      result.warnings.push(
+        `Binding source for "${mapping.implementation}" does not look like a .pen path: "${mapping.designSource}".`
+      );
+    }
+  }
+
+  result.notes.push("lint-bindings defaults to advisory mode; pass `--strict` to block on findings.");
+  return finalize(result);
+}
+
+function formatLintBindingsReport(result) {
+  const lines = [
+    "Da Vinci lint-bindings",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Strict mode: ${result.strict ? "yes" : "no"}`,
+    `Status: ${result.status}`,
+    `Mappings: ${result.summary.mappings}`,
+    `Malformed entries: ${result.summary.malformed}`
+  ];
+
+  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 = {
+  lintBindings,
+  formatLintBindingsReport
+};

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
+};