@work-graph/cli 0.2.0

package/vendor/src/codeGapOperatorProjection.mjs

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+import { buildCodeGapBacklogFeed } from './codeGapBacklogFeeder.mjs';
+import { buildCodeGapBacklogCandidateList } from './codeGapDraftIntakeApi.mjs';
+
+export { analyzeCodeGaps, CODE_GAP_REPORT_SCHEMA } from './codeGapAnalyzer.mjs';
+
+export const CODE_GAP_PROJECTION_SCHEMA = 'workgraph.code-gap-projection.v1';
+export const DEFAULT_CODE_GAP_REPORT_PATH = 'tests/fixtures/code-gap-report.v1.json';
+
+export async function readCodeGapReport(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const reportPath = resolve(cwd, options.reportPath ?? DEFAULT_CODE_GAP_REPORT_PATH);
+
+  if (options.report !== undefined) {
+    return options.report;
+  }
+
+  try {
+    const text = await readFile(reportPath, 'utf8');
+    return JSON.parse(text);
+  } catch (error) {
+    if (error && typeof error === 'object' && error.code === 'ENOENT') {
+      return {
+        schema: 'code-gap.report.v1',
+        summary: { total: 0 },
+        entries: [],
+      };
+    }
+
+    throw error;
+  }
+}
+
+export async function buildCodeGapOperatorProjection(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const reportPath = options.reportPath ?? DEFAULT_CODE_GAP_REPORT_PATH;
+  const report = await readCodeGapReport({ cwd, reportPath, report: options.report });
+  const feed = buildCodeGapBacklogFeed(report, options);
+  const promotionCandidates = buildCodeGapBacklogCandidateList(
+    {
+      suggestions: feed.suggestions,
+      sourceReportPath: reportPath,
+    },
+    options,
+  );
+
+  return {
+    schema: CODE_GAP_PROJECTION_SCHEMA,
+    reportSchema: report.schema ?? 'code-gap.report.v1',
+    sourceReportPath: reportPath,
+    reportSummary: feed.sourceReport ?? {},
+    suggestionCount: feed.suggestionCount,
+    reviewRequired: feed.reviewRequired,
+    promotionProtocol: feed.promotionProtocol,
+    suggestions: feed.suggestions,
+    promotionCandidates,
+  };
+}

package/vendor/src/codeSyntaxHighlight.mjs

@@ -0,0 +1,123 @@
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+const JS_KEYWORDS = new Set([
+  'async', 'await', 'break', 'case', 'catch', 'class', 'const', 'continue', 'default', 'delete',
+  'do', 'else', 'export', 'extends', 'false', 'finally', 'for', 'from', 'function', 'if', 'import',
+  'in', 'let', 'new', 'null', 'return', 'switch', 'this', 'throw', 'true', 'try', 'typeof',
+  'undefined', 'var', 'void', 'while',
+]);
+
+export function normalizeCodeLanguage(language) {
+  const value = String(language ?? '').trim().toLowerCase();
+  if (value === 'yml') return 'yaml';
+  if (value === 'js') return 'javascript';
+  if (value === 'ts') return 'typescript';
+  if (value === 'sh' || value === 'shell') return 'bash';
+  return value || 'plaintext';
+}
+
+function highlightStructuredTokens(text) {
+  let result = '';
+  let index = 0;
+  const source = String(text ?? '');
+
+  while (index < source.length) {
+    const char = source[index];
+
+    if (char === '"' || char === '\'' || char === '`') {
+      const quote = char;
+      let end = index + 1;
+      while (end < source.length && source[end] !== quote) {
+        end += 1;
+      }
+      if (end < source.length) {
+        end += 1;
+      }
+      result += `<span class="code-hl-string">${escapeHtml(source.slice(index, end))}</span>`;
+      index = end;
+      continue;
+    }
+
+    if (/[{}[\],():]/u.test(char)) {
+      result += `<span class="code-hl-punct">${escapeHtml(char)}</span>`;
+      index += 1;
+      continue;
+    }
+
+    const numberMatch = source.slice(index).match(/^\d+(?:\.\d+)?/u);
+    if (numberMatch && (index === 0 || /[\s,:[{(-]/u.test(source[index - 1]))) {
+      result += `<span class="code-hl-number">${escapeHtml(numberMatch[0])}</span>`;
+      index += numberMatch[0].length;
+      continue;
+    }
+
+    const wordMatch = source.slice(index).match(/^[\w.-]+/u);
+    if (wordMatch) {
+      const word = wordMatch[0];
+      const className = JS_KEYWORDS.has(word) ? 'code-hl-keyword' : 'code-hl-key';
+      result += `<span class="${className}">${escapeHtml(word)}</span>`;
+      index += word.length;
+      continue;
+    }
+
+    result += escapeHtml(char);
+    index += 1;
+  }
+
+  return result;
+}
+
+function highlightYaml(source) {
+  return String(source ?? '').split('\n').map((line) => {
+    if (/^\s*#/u.test(line)) {
+      return `<span class="code-hl-comment">${escapeHtml(line)}</span>`;
+    }
+
+    const keyMatch = line.match(/^(\s*)([\w.-]+)(\s*:\s*)([\s\S]*)$/u);
+    if (keyMatch) {
+      const [, indent, key, separator, rest] = keyMatch;
+      const restTrimmed = rest.trim();
+      if (restTrimmed !== '' && !/[{}[\]]/u.test(restTrimmed)) {
+        return `${escapeHtml(indent)}<span class="code-hl-key">${escapeHtml(key)}</span>${escapeHtml(separator)}<span class="code-hl-string">${escapeHtml(rest)}</span>`;
+      }
+
+      return `${escapeHtml(indent)}<span class="code-hl-key">${escapeHtml(key)}</span>${escapeHtml(separator)}${highlightStructuredTokens(rest)}`;
+    }
+
+    return highlightStructuredTokens(line);
+  }).join('\n');
+}
+
+function highlightJavaScript(source) {
+  return String(source ?? '').split('\n').map((line) => {
+    const commentMatch = line.match(/^(\s*)(\/\/.*)$/u);
+    if (commentMatch) {
+      return `${escapeHtml(commentMatch[1])}<span class="code-hl-comment">${escapeHtml(commentMatch[2])}</span>`;
+    }
+
+    return highlightStructuredTokens(line);
+  }).join('\n');
+}
+
+export function highlightCodeBlock(source, language) {
+  const normalized = normalizeCodeLanguage(language);
+
+  switch (normalized) {
+    case 'yaml':
+      return highlightYaml(source);
+    case 'json':
+      return highlightStructuredTokens(source);
+    case 'javascript':
+    case 'typescript':
+    case 'bash':
+      return highlightJavaScript(source);
+    default:
+      return escapeHtml(source);
+  }
+}

package/vendor/src/codegenEvidence.mjs

@@ -0,0 +1,187 @@
+import { createHash } from 'node:crypto';
+
+import { evaluateBracketIrDrift } from './bracketIrTraceSignal.mjs';
+
+const CODEGEN_KINDS = new Set(['integrity', 'roundtrip', 'generated_test']);
+const compareText = (left, right) => String(left).localeCompare(String(right), 'en', { sensitivity: 'variant' });
+
+function createStableId(value) {
+  return createHash('sha256').update(String(value), 'utf8').digest('hex').slice(0, 16);
+}
+
+export function isCodegenFacingWorkItem(item) {
+  const labels = item.labels ?? {};
+  return Boolean(
+    labels['trace.codegen_source_step']
+    || labels['trace.codegen_integrity_hash']
+    || labels['compiler.mode']
+    || labels['trace.bracket_ir_hash'],
+  );
+}
+
+export function buildCodegenEvidenceRecord({ kind, taskId, summary, status = 'succeeded', artifacts = [], command = '', exitCode = 0, details = {} }) {
+  if (!CODEGEN_KINDS.has(kind)) {
+    throw new Error(`unsupported codegen evidence kind: ${kind}`);
+  }
+
+  const idSuffix = [taskId, kind, summary, ...artifacts].join('\0');
+
+  return {
+    schema: 'codegen.evidence.record.v1',
+    id: `codegen:${kind}:${createStableId(idSuffix)}`,
+    kind,
+    taskId,
+    summary,
+    status,
+    artifacts: [...artifacts].sort(compareText),
+    command,
+    exitCode,
+    details: { ...details, codegenKind: kind },
+    evidenceV1: {
+      type: kind === 'generated_test' || command ? 'test' : 'command',
+      summary,
+      status: status === 'succeeded' ? 'succeeded' : 'failed',
+      artifacts,
+      command: command || undefined,
+      exitCode: command ? exitCode : undefined,
+      details: { codegenKind: kind, ...details },
+    },
+  };
+}
+
+export function buildCodegenRoundtripEvidence(result) {
+  const status = result.status === 'passed' ? 'succeeded' : result.status === 'skipped' ? 'skipped' : 'failed';
+  return buildCodegenEvidenceRecord({
+    kind: 'roundtrip',
+    taskId: result.taskId ?? 'unknown',
+    summary: result.diffSummary ?? `Compiler round-trip ${result.status} for ${result.stepPath}`,
+    status,
+    artifacts: [result.stepPath, ...(result.generatedPaths ?? [])].filter(Boolean),
+    command: result.command ?? '',
+    exitCode: result.exitCode ?? (status === 'succeeded' ? 0 : 1),
+    details: {
+      stepPath: result.stepPath,
+      engineVersion: result.engineVersion ?? '',
+      roundtripStatus: result.status,
+    },
+  });
+}
+
+export function buildCodegenIntegrityEvidence({ taskId, integrityHash, artifacts, summary }) {
+  return buildCodegenEvidenceRecord({
+    kind: 'integrity',
+    taskId,
+    summary: summary ?? `Codegen integrity hash ${integrityHash}`,
+    artifacts,
+    details: { integrityHash },
+  });
+}
+
+export function parseLegacyEvidenceForCodegen(evidenceLines = []) {
+  const records = [];
+  for (const line of evidenceLines) {
+    const text = String(line);
+    if (/round[- ]?trip/iu.test(text)) {
+      records.push({ kind: 'roundtrip', summary: text });
+    } else if (/integrity|hash|drift/iu.test(text)) {
+      records.push({ kind: 'integrity', summary: text });
+    } else if (/generated test|codegen test/iu.test(text)) {
+      records.push({ kind: 'generated_test', summary: text });
+    }
+  }
+
+  return records;
+}
+
+export function evaluateCodegenVerifyGate(item, options = {}) {
+  const diagnostics = [];
+  const targetStatus = options.targetStatus ?? item.status;
+
+  if (!isCodegenFacingWorkItem(item)) {
+    return { ok: true, diagnostics, codegenFacing: false };
+  }
+
+  const legacyRecords = parseLegacyEvidenceForCodegen(item.evidence ?? []);
+  const structuredRecords = options.codegenEvidence ?? [];
+  const allKinds = new Set([
+    ...legacyRecords.map((record) => record.kind),
+    ...structuredRecords.map((record) => record.kind),
+  ]);
+
+  const bracketDrift = evaluateBracketIrDrift(item, options);
+  diagnostics.push(...bracketDrift.diagnostics);
+
+  if (targetStatus === 'done' || targetStatus === 'verify') {
+    if (!allKinds.has('integrity') && item.labels?.['trace.codegen_integrity_hash']) {
+      diagnostics.push({
+        severity: 'error',
+        code: 'codegen.integrity_missing',
+        message: `WorkItem ${item.id} expects integrity evidence for codegen hash label.`,
+        actionable: 'Record integrity evidence after reviewing generated output.',
+      });
+    }
+
+    if (!allKinds.has('roundtrip') && item.labels?.['trace.codegen_source_step']) {
+      diagnostics.push({
+        severity: 'warning',
+        code: 'codegen.roundtrip_missing',
+        message: `WorkItem ${item.id} has codegen source step but no roundtrip evidence.`,
+        actionable: 'Run compiler round-trip and attach evidence before done.',
+      });
+    }
+  }
+
+  if (item.labels?.['trace.codegen_integrity_hash'] && legacyRecords.some((record) => /drift|mismatch/iu.test(record.summary))) {
+    diagnostics.push({
+      severity: 'error',
+      code: 'codegen.integrity_drift',
+      message: `WorkItem ${item.id} reports generated code drift.`,
+      actionable: 'Re-run round-trip or update integrity hash after review.',
+    });
+  }
+
+  const ok = diagnostics.every((diagnostic) => diagnostic.severity !== 'error');
+  return { ok, diagnostics, codegenFacing: true, bracketSignal: bracketDrift.signal };
+}
+
+export function buildCodegenVerificationGate(items, options = {}) {
+  if (!Array.isArray(items)) {
+    throw new TypeError('items must be an array');
+  }
+
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 24;
+  const evaluations = items
+    .map((item) => {
+      const gate = evaluateCodegenVerifyGate(item, { targetStatus: item.status });
+      if (!gate.codegenFacing) {
+        return null;
+      }
+
+      return {
+        workId: item.id,
+        title: item.title ?? item.id,
+        status: item.status,
+        ok: gate.ok,
+        diagnostics: gate.diagnostics,
+      };
+    })
+    .filter(Boolean)
+    .sort((left, right) => compareText(left.workId, right.workId));
+
+  const failedCount = evaluations.filter((entry) => !entry.ok).length;
+  const passedCount = evaluations.length - failedCount;
+  let status = 'not_run';
+  if (evaluations.length > 0) {
+    status = failedCount === 0 ? 'passed' : 'failed';
+  }
+
+  return {
+    schema: 'verification.codegen-gate.v1',
+    status,
+    codegenFacingCount: evaluations.length,
+    passedCount,
+    failedCount,
+    truncated: evaluations.length > limit,
+    items: evaluations.slice(0, limit),
+  };
+}

package/vendor/src/compilerRoundTripCli.mjs

@@ -0,0 +1,164 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { buildCodegenRoundtripEvidence } from './codegenEvidence.mjs';
+import {
+  formatStepAtomDraft,
+  parseStepAtomDrafts,
+  validateStepAtomDraft,
+} from './stepAtomFormatter.mjs';
+
+export const COMPILER_ROUNDTRIP_RESULT_SCHEMA = 'compiler.roundtrip.result.v1';
+export const COMPILER_ROUNDTRIP_ENGINE_VERSION = 'workgraph-compiler-roundtrip-mvp.v1';
+
+function isCompilerModeDraft(draft) {
+  const labels = draft?.labels ?? {};
+  return labels['compiler.mode'] !== undefined || draft?.profile === 'compiler';
+}
+
+export async function runCompilerRoundTrip(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const stepPath = String(options.stepPath ?? '').trim();
+
+  if (stepPath === '') {
+    throw new TypeError('stepPath is required');
+  }
+
+  const absoluteStepPath = resolve(cwd, stepPath);
+  const command = options.command ?? `npm run compiler:roundtrip -- ${stepPath.replace(/\\/g, '/')}`;
+  const stepText = options.stepText ?? await readFile(absoluteStepPath, 'utf8');
+  const imports = parseStepAtomDrafts(stepText);
+  const primary = imports[0];
+
+  if (!primary?.draft || !isCompilerModeDraft(primary.draft)) {
+    const result = {
+      schema: COMPILER_ROUNDTRIP_RESULT_SCHEMA,
+      stepPath: stepPath.replace(/\\/g, '/'),
+      generatedPaths: [],
+      status: 'skipped',
+      command,
+      exitCode: 0,
+      diffSummary: 'Step is not compiler-mode; round-trip skipped.',
+      engineVersion: COMPILER_ROUNDTRIP_ENGINE_VERSION,
+      taskId: options.taskId ?? null,
+      skippedReason: 'not_compiler_mode',
+    };
+
+    return {
+      result,
+      evidence: buildCodegenRoundtripEvidence(result),
+      validationErrors: [],
+      warnings: primary?.warnings ?? [],
+    };
+  }
+
+  const validationErrors = [
+    ...(primary.errors ?? []),
+    ...validateStepAtomDraft(primary.draft),
+  ];
+
+  if (validationErrors.length > 0) {
+    const result = {
+      schema: COMPILER_ROUNDTRIP_RESULT_SCHEMA,
+      stepPath: stepPath.replace(/\\/g, '/'),
+      generatedPaths: [],
+      status: 'failed',
+      command,
+      exitCode: 1,
+      diffSummary: `StepAtomDraft validation failed: ${validationErrors.join('; ')}`,
+      engineVersion: COMPILER_ROUNDTRIP_ENGINE_VERSION,
+      taskId: options.taskId ?? primary.draft.labels?.['work.id'] ?? primary.draft.name,
+    };
+
+    return {
+      result,
+      evidence: buildCodegenRoundtripEvidence(result),
+      validationErrors,
+      warnings: primary.warnings ?? [],
+    };
+  }
+
+  const formattedOnce = formatStepAtomDraft(primary.draft);
+  const reparsed = parseStepAtomDrafts(formattedOnce)[0];
+  const formattedTwice = formatStepAtomDraft(reparsed.draft);
+  const stable = formattedOnce === formattedTwice;
+  const reparsedErrors = [
+    ...(reparsed.errors ?? []),
+    ...validateStepAtomDraft(reparsed.draft),
+  ];
+
+  const result = {
+    schema: COMPILER_ROUNDTRIP_RESULT_SCHEMA,
+    stepPath: stepPath.replace(/\\/g, '/'),
+    generatedPaths: [stepPath.replace(/\\/g, '/')],
+    status: stable && reparsedErrors.length === 0 ? 'passed' : 'failed',
+    command,
+    exitCode: stable && reparsedErrors.length === 0 ? 0 : 1,
+    diffSummary: stable && reparsedErrors.length === 0
+      ? 'format(parse(format(draft))) stable for compiler-mode step'
+      : 'Round-trip invariant failed for compiler-mode step',
+    engineVersion: COMPILER_ROUNDTRIP_ENGINE_VERSION,
+    taskId: options.taskId ?? primary.draft.labels?.['work.id'] ?? primary.draft.name,
+  };
+
+  return {
+    result,
+    evidence: buildCodegenRoundtripEvidence(result),
+    validationErrors: reparsedErrors,
+    warnings: [...(primary.warnings ?? []), ...(reparsed.warnings ?? [])],
+  };
+}
+
+export async function runCompilerRoundTripCli(argv = process.argv) {
+  const args = argv.slice(2);
+  let stepPath;
+  let taskId;
+  let jsonOnly = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--json') {
+      jsonOnly = true;
+      continue;
+    }
+    if (arg === '--task-id') {
+      taskId = args[index + 1];
+      index += 1;
+      continue;
+    }
+    if (!arg.startsWith('-') && stepPath === undefined) {
+      stepPath = arg;
+    }
+  }
+
+  if (!stepPath) {
+    stepPath = 'tests/fixtures/compiler-roundtrip/sample.compiler.bvc';
+  }
+
+  const output = await runCompilerRoundTrip({ stepPath, taskId });
+
+  if (jsonOnly) {
+    console.log(JSON.stringify({
+      result: output.result,
+      evidence: output.evidence,
+      validationErrors: output.validationErrors,
+      warnings: output.warnings,
+    }, null, 2));
+  } else {
+    console.log(JSON.stringify({
+      schema: output.result.schema,
+      status: output.result.status,
+      stepPath: output.result.stepPath,
+      evidenceId: output.evidence.id,
+      diffSummary: output.result.diffSummary,
+    }, null, 2));
+  }
+
+  return output.result.status === 'failed' ? 1 : 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const exitCode = await runCompilerRoundTripCli();
+  process.exitCode = exitCode;
+}

package/vendor/src/dagreGraphLayout.mjs

@@ -0,0 +1,78 @@
+import dagre from '@dagrejs/dagre';
+import { resolveGraphCanvasOverlaps } from './graphCanvasLitFlow/resolveGraphCanvasOverlaps.mjs';
+
+/**
+ * @typedef {{
+ *   nodesep?: number,
+ *   ranksep?: number,
+ *   edgesep?: number,
+ *   marginx?: number,
+ *   marginy?: number,
+ *   rankdir?: 'TB' | 'BT' | 'LR' | 'RL',
+ *   ranker?: 'network-simplex' | 'tight-tree' | 'longest-path',
+ *   align?: 'UL' | 'UR' | 'DL' | 'DR',
+ *   resolveOverlaps?: boolean,
+ *   overlapGap?: number,
+ * }} DagreLayoutOptions
+ */
+
+/**
+ * @param {Array<{ id: string, width: number, height: number, [key: string]: unknown }>} nodes
+ * @param {Array<{ from: string, to: string }>} edges
+ * @param {DagreLayoutOptions} [options]
+ */
+export function layoutGraphWithDagre(nodes, edges, options = {}) {
+  const rankdir = options.rankdir ?? 'TB';
+  const graph = new dagre.graphlib.Graph({ compound: false, directed: true });
+  graph.setGraph({
+    rankdir,
+    nodesep: options.nodesep ?? 56,
+    ranksep: options.ranksep ?? 112,
+    edgesep: options.edgesep ?? 24,
+    marginx: options.marginx ?? 32,
+    marginy: options.marginy ?? 32,
+    ranker: options.ranker ?? 'network-simplex',
+    align: options.align ?? 'UL',
+  });
+  graph.setDefaultEdgeLabel(() => ({}));
+
+  for (const node of nodes) {
+    graph.setNode(node.id, { width: node.width, height: node.height });
+  }
+
+  for (const edge of edges) {
+    if (graph.hasNode(edge.from) && graph.hasNode(edge.to)) {
+      graph.setEdge(edge.from, edge.to);
+    }
+  }
+
+  dagre.layout(graph);
+
+  const isHorizontal = rankdir === 'LR' || rankdir === 'RL';
+  const rankByCoord = new Map();
+  const sortedRanks = [...new Set(nodes.map((node) => graph.node(node.id)[isHorizontal ? 'x' : 'y']))]
+    .sort((left, right) => left - right);
+  sortedRanks.forEach((value, index) => rankByCoord.set(value, index));
+
+  let placed = nodes.map((node) => {
+    const positioned = graph.node(node.id);
+    const rankCoord = isHorizontal ? positioned.x : positioned.y;
+    const crossCoord = isHorizontal ? positioned.y : positioned.x;
+    return {
+      ...node,
+      x: positioned.x - node.width / 2,
+      y: positioned.y - node.height / 2,
+      row: isHorizontal ? crossCoord : (rankByCoord.get(rankCoord) ?? 0),
+      col: isHorizontal ? (rankByCoord.get(rankCoord) ?? 0) : crossCoord,
+    };
+  });
+
+  if (options.resolveOverlaps !== false) {
+    placed = resolveGraphCanvasOverlaps(placed, {
+      gap: options.overlapGap ?? 28,
+      layoutDirection: rankdir,
+    });
+  }
+
+  return placed;
+}