@xenonbyte/da-vinci-workflow 0.1.26 → 0.2.2

package/lib/diff-spec.js

@@ -0,0 +1,242 @@
+const fs = require("fs");
+const path = require("path");
+const { STATUS } = require("./workflow-contract");
+const { pathExists } = require("./utils");
+const { generatePlanningSidecars } = require("./sidecars");
+const { digestObject } = require("./planning-parsers");
+
+function keyByText(items) {
+  const map = new Map();
+  for (const item of items || []) {
+    const text = String(item && item.text ? item.text : item || "").trim();
+    if (!text) {
+      continue;
+    }
+    map.set(text, item);
+  }
+  return map;
+}
+
+function readJsonFileIfExists(filePath) {
+  if (!filePath || !pathExists(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch (_error) {
+    return null;
+  }
+}
+
+function diffTextCollection(baseItems, headItems) {
+  const baseMap = keyByText(baseItems);
+  const headMap = keyByText(headItems);
+  const added = [];
+  const removed = [];
+  const modified = [];
+
+  for (const text of headMap.keys()) {
+    if (!baseMap.has(text)) {
+      added.push(text);
+    }
+  }
+  for (const text of baseMap.keys()) {
+    if (!headMap.has(text)) {
+      removed.push(text);
+    }
+  }
+
+  for (const text of headMap.keys()) {
+    if (!baseMap.has(text)) {
+      continue;
+    }
+    const baseRecord = baseMap.get(text) || {};
+    const headRecord = headMap.get(text) || {};
+    if (String(baseRecord.specPath || "") !== String(headRecord.specPath || "")) {
+      modified.push({
+        text,
+        from: String(baseRecord.specPath || ""),
+        to: String(headRecord.specPath || "")
+      });
+    }
+  }
+
+  return {
+    added: added.sort((a, b) => a.localeCompare(b)),
+    removed: removed.sort((a, b) => a.localeCompare(b)),
+    modified
+  };
+}
+
+function hasAnyDiff(diff) {
+  return (
+    (diff.added && diff.added.length > 0) ||
+    (diff.removed && diff.removed.length > 0) ||
+    (diff.modified && diff.modified.length > 0)
+  );
+}
+
+function chooseBaseSidecars(projectRoot, changeId, fromDir) {
+  const sidecarDir = fromDir || path.join(projectRoot, ".da-vinci", "changes", changeId, "sidecars");
+  return {
+    spec: readJsonFileIfExists(path.join(sidecarDir, "spec.index.json")),
+    tasks: readJsonFileIfExists(path.join(sidecarDir, "tasks.index.json")),
+    pageMap: readJsonFileIfExists(path.join(sidecarDir, "page-map.index.json")),
+    bindings: readJsonFileIfExists(path.join(sidecarDir, "bindings.index.json")),
+    sidecarDir
+  };
+}
+
+function diffSpec(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const requestedChangeId = options.changeId ? String(options.changeId).trim() : "";
+  const sidecarResult = generatePlanningSidecars(projectRoot, {
+    changeId: requestedChangeId,
+    write: false
+  });
+  if (sidecarResult.failures.length > 0 || !sidecarResult.changeId) {
+    return {
+      status: STATUS.BLOCK,
+      failures: sidecarResult.failures,
+      warnings: sidecarResult.warnings,
+      notes: sidecarResult.notes,
+      projectRoot,
+      changeId: sidecarResult.changeId || null,
+      diff: null
+    };
+  }
+
+  const changeId = sidecarResult.changeId;
+  const baseSidecars = chooseBaseSidecars(projectRoot, changeId, options.fromDir);
+  const headSidecars = sidecarResult.sidecars;
+
+  if (!baseSidecars.spec) {
+    return {
+      status: STATUS.WARN,
+      failures: [],
+      warnings: [
+        `No baseline sidecars found in ${baseSidecars.sidecarDir}. Run \`da-vinci generate-sidecars\` before diff-spec.`
+      ],
+      notes: [
+        "diff-spec currently stays under the `diff-spec` surface and includes broader planning summaries for page-map/bindings/tasks."
+      ],
+      projectRoot,
+      changeId,
+      diff: {
+        spec: null,
+        tasks: null,
+        pageMap: null,
+        bindings: null
+      }
+    };
+  }
+
+  const baseSpecCollections = baseSidecars.spec.collections || {};
+  const headSpecCollections = headSidecars["spec.index.json"].collections || {};
+  const baseSpecDigest = digestObject(baseSidecars.spec);
+  const headSpecDigest = digestObject(headSidecars["spec.index.json"]);
+  const specDiff = {
+    behavior: diffTextCollection(baseSpecCollections.behavior || [], headSpecCollections.behavior || []),
+    states: diffTextCollection(baseSpecCollections.states || [], headSpecCollections.states || []),
+    inputs: diffTextCollection(baseSpecCollections.inputs || [], headSpecCollections.inputs || []),
+    outputs: diffTextCollection(baseSpecCollections.outputs || [], headSpecCollections.outputs || []),
+    acceptance: diffTextCollection(baseSpecCollections.acceptance || [], headSpecCollections.acceptance || [])
+  };
+
+  const tasksDiff = {
+    taskGroups: diffTextCollection(
+      (baseSidecars.tasks && baseSidecars.tasks.taskGroups
+        ? baseSidecars.tasks.taskGroups.map((item) => ({ text: `${item.id}: ${item.title}` }))
+        : []),
+      headSidecars["tasks.index.json"].taskGroups.map((item) => ({ text: `${item.id}: ${item.title}` }))
+    )
+  };
+
+  const pageMapDiff = {
+    pages: diffTextCollection(
+      (baseSidecars.pageMap && baseSidecars.pageMap.pages
+        ? baseSidecars.pageMap.pages.map((page) => ({ text: page }))
+        : []),
+      headSidecars["page-map.index.json"].pages.map((page) => ({ text: page }))
+    )
+  };
+
+  const bindingsDiff = {
+    mappings: diffTextCollection(
+      (baseSidecars.bindings && baseSidecars.bindings.mappings
+        ? baseSidecars.bindings.mappings.map((item) => ({
+            text: `${item.implementation} -> ${item.designPage}`
+          }))
+        : []),
+      headSidecars["bindings.index.json"].mappings.map((item) => ({
+        text: `${item.implementation} -> ${item.designPage}`
+      }))
+    )
+  };
+
+  const hasChanges =
+    Object.values(specDiff).some((entry) => hasAnyDiff(entry)) ||
+    baseSpecDigest !== headSpecDigest ||
+    hasAnyDiff(tasksDiff.taskGroups) ||
+    hasAnyDiff(pageMapDiff.pages) ||
+    hasAnyDiff(bindingsDiff.mappings);
+
+  return {
+    status: hasChanges ? STATUS.WARN : STATUS.PASS,
+    failures: [],
+    warnings: hasChanges ? ["Planning sidecar differences detected."] : [],
+    notes: [
+      "diff-spec includes normalized spec deltas and broader planning summaries (tasks/page-map/bindings)."
+    ],
+    projectRoot,
+    changeId,
+    diff: {
+      spec: specDiff,
+      specDigestChanged: baseSpecDigest !== headSpecDigest,
+      tasks: tasksDiff,
+      pageMap: pageMapDiff,
+      bindings: bindingsDiff
+    }
+  };
+}
+
+function formatDiffSpecReport(result) {
+  const lines = [
+    "Da Vinci diff-spec",
+    `Project: ${result.projectRoot}`,
+    `Change: ${result.changeId || "(not selected)"}`,
+    `Status: ${result.status}`
+  ];
+  if (result.failures && result.failures.length > 0) {
+    lines.push("", "Failures:");
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+  if (result.warnings && result.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of result.warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+  if (result.diff && result.diff.spec) {
+    lines.push("", "Spec deltas:");
+    for (const [section, entry] of Object.entries(result.diff.spec)) {
+      lines.push(
+        `- ${section}: +${entry.added.length} / -${entry.removed.length} / ~${entry.modified.length}`
+      );
+    }
+  }
+  if (result.notes && result.notes.length > 0) {
+    lines.push("", "Notes:");
+    for (const note of result.notes) {
+      lines.push(`- ${note}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+module.exports = {
+  diffSpec,
+  formatDiffSpecReport
+};

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