@brainwav/diagram 1.0.8 → 1.1.0

package/src/config/diagramrc.js

@@ -0,0 +1,79 @@
+const fs = require('fs');
+const path = require('path');
+const { z } = require('zod');
+
+const DIAGRAMRC_FILENAME = '.diagramrc';
+
+/**
+ * Zod schema for .diagramrc config file.
+ * All fields are optional — the file does not need to exist.
+ */
+const DiagramRcSchema = z.object({
+  /** Glob patterns or directory names to ignore during analysis */
+  ignore: z.array(z.string()).optional(),
+  /** Comma-separated file glob patterns (same as --patterns CLI flag) */
+  patterns: z.string().optional(),
+  /** Comma-separated file globs to exclude (same as --exclude CLI flag) */
+  exclude: z.string().optional(),
+  /** Maximum files to analyze (1–10000, same as --max-files CLI flag) */
+  maxFiles: z.number().int().positive().max(10000).optional(),
+  /** Default theme for diagram output */
+  theme: z.enum(['default', 'dark', 'forest', 'neutral', 'light']).optional(),
+}).strict();
+
+/**
+ * Load and validate .diagramrc from the project root.
+ *
+ * Returns the parsed config object if found and valid, or an empty object
+ * if the file doesn't exist. Exits the process with code 2 if the file
+ * exists but is invalid JSON or fails schema validation.
+ *
+ * @param {string} rootPath - Project root directory
+ * @param {{ quiet?: boolean }} opts
+ * @returns {z.infer<typeof DiagramRcSchema>}
+ */
+function loadDiagramRc(rootPath, opts = {}) {
+  const rcPath = path.join(rootPath, DIAGRAMRC_FILENAME);
+
+  if (!fs.existsSync(rcPath)) {
+    return {};
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(rcPath, 'utf8');
+  } catch (err) {
+    console.error(`\u274c Failed to read ${DIAGRAMRC_FILENAME}: ${err.message}`);
+    process.exit(2);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`\u274c ${DIAGRAMRC_FILENAME} is not valid JSON: ${err.message}`);
+    process.exit(2);
+  }
+
+  const result = DiagramRcSchema.safeParse(parsed);
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((issue) => `  • ${issue.path.join('.')||'(root)'}: ${issue.message}`)
+      .join('\n');
+    console.error(`\u274c Invalid ${DIAGRAMRC_FILENAME}:\n${issues}`);
+    process.exit(2);
+  }
+
+  if (!opts.quiet) {
+    // Only log the load notice in DEBUG mode — don't clutter normal output
+    if (process.env.DEBUG) {
+      console.log(`\u2139\ufe0f  Loaded ${DIAGRAMRC_FILENAME} from ${rcPath}`);
+    }
+  }
+
+  return result.data;
+}
+
+module.exports = {
+  loadDiagramRc,
+};

package/src/context/build-context-pack.js

@@ -0,0 +1,291 @@
+const { readFileSync, writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+const {
+  AGENT_DIAGRAM_PRIORITY,
+  estimateTokensFromBytes,
+  sortByPriority,
+} = require('../artifacts/artifact-budget');
+const { FIXED_DETERMINISTIC_TIMESTAMP } = require('../artifacts/evidence-manifest');
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return parsed;
+}
+
+function trimToMaxLines(content, maxLines) {
+  const lines = String(content || '').trimEnd().split(/\r?\n/);
+  if (lines.length <= maxLines) {
+    return { text: lines.join('\n'), truncated: false, omittedLines: 0 };
+  }
+  const kept = lines.slice(0, maxLines);
+  return {
+    text: kept.join('\n'),
+    truncated: true,
+    omittedLines: lines.length - maxLines,
+  };
+}
+
+function buildOmittedSection(omittedTypes, compact = false) {
+  if (!Array.isArray(omittedTypes) || omittedTypes.length === 0) {
+    return '';
+  }
+
+  if (compact) {
+    return [
+      '## Omitted Diagrams',
+      '',
+      `Omitted from embedding due to budget/profile constraints: ${omittedTypes.length} diagram(s).`,
+      '',
+    ].join('\n');
+  }
+
+  return [
+    '## Omitted Diagrams',
+    '',
+    `Omitted from embedding due to budget/profile constraints: ${omittedTypes.join(', ')}`,
+    'Use `.diagram/*.mmd` files directly for full-fidelity diagram content.',
+    '',
+  ].join('\n');
+}
+
+function buildHeaderText({
+  sortedDiagrams,
+  contextMaxBytes,
+  contextMaxEmbeddedDiagrams,
+  contextMaxLinesPerDiagram,
+}) {
+  const staticPrefix = [
+    '# Diagram Context Pack',
+    '',
+    'Machine-oriented context for agents. This pack is intentionally compact and token-budgeted.',
+    '',
+    `Context byte budget: ${contextMaxBytes}`,
+    `Max embedded diagrams: ${contextMaxEmbeddedDiagrams}`,
+    `Max lines per embedded diagram: ${contextMaxLinesPerDiagram}`,
+    '',
+    '## Diagram Index',
+    '',
+    '| Type | File | Bytes | Lines | Placeholder | Approx Tokens |',
+    '| --- | --- | ---: | ---: | --- | ---: |',
+  ];
+  const staticSuffix = ['', '## Embedded Mermaid (Budgeted)', '', ''];
+  const indexRows = [];
+
+  const buildCandidate = (rows, summaryLine = '') => {
+    const summary = summaryLine ? ['', summaryLine] : [];
+    return `${staticPrefix.concat(rows, summary, staticSuffix).join('\n')}`;
+  };
+
+  for (const entry of sortedDiagrams) {
+    const row = `| ${entry.type} | ${entry.file} | ${entry.bytes} | ${entry.lines} | ${entry.isPlaceholder ? 'yes' : 'no'} | ${estimateTokensFromBytes(entry.bytes || 0)} |`;
+    const candidateWithRow = buildCandidate(indexRows.concat(row));
+    if (Buffer.byteLength(candidateWithRow, 'utf8') > contextMaxBytes) {
+      break;
+    }
+    indexRows.push(row);
+  }
+
+  const compacted = indexRows.length < sortedDiagrams.length;
+  const compactSummary = compacted
+    ? `Diagram index compacted to ${indexRows.length}/${sortedDiagrams.length} row(s) to fit budget.`
+    : '';
+  const candidate = buildCandidate(indexRows, compactSummary);
+  if (Buffer.byteLength(candidate, 'utf8') <= contextMaxBytes) {
+    return {
+      text: candidate,
+      indexRowsIncluded: indexRows.length,
+      headerCompacted: compacted,
+    };
+  }
+
+  const minimal = [
+    '# Diagram Context Pack',
+    '',
+    `Compact header due to strict budget (${contextMaxBytes} bytes).`,
+    `Diagrams available: ${sortedDiagrams.length}`,
+    `Max embedded diagrams: ${contextMaxEmbeddedDiagrams}`,
+    `Max lines per embedded diagram: ${contextMaxLinesPerDiagram}`,
+    '',
+    '## Embedded Mermaid (Budgeted)',
+    '',
+  ].join('\n');
+  if (Buffer.byteLength(minimal, 'utf8') > contextMaxBytes) {
+    throw new Error(`Context byte budget (${contextMaxBytes}) is too small for header.`);
+  }
+  return {
+    text: minimal,
+    indexRowsIncluded: 0,
+    headerCompacted: true,
+  };
+}
+
+function buildContextPack({
+  rootDir,
+  tmpDir,
+  contextMaxBytes = 12000,
+  contextMaxLinesPerDiagram = 140,
+  contextMaxEmbeddedDiagrams = 3,
+  contextPath,
+  contextMetaPath,
+  deterministic = false,
+}) {
+  if (!rootDir || !tmpDir || !contextPath) {
+    throw new Error('buildContextPack requires rootDir, tmpDir, and contextPath');
+  }
+
+  const diagramsDir = join(tmpDir, 'diagrams');
+  const manifestPath = join(diagramsDir, 'manifest.json');
+  const nowIso = deterministic ? FIXED_DETERMINISTIC_TIMESTAMP : new Date().toISOString();
+
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const diagramEntries = Array.isArray(manifest.diagrams) ? manifest.diagrams : [];
+  const sortedDiagrams = sortByPriority(diagramEntries, AGENT_DIAGRAM_PRIORITY);
+
+  const header = buildHeaderText({
+    sortedDiagrams,
+    contextMaxBytes,
+    contextMaxEmbeddedDiagrams,
+    contextMaxLinesPerDiagram,
+  });
+  const headerText = header.text;
+  let contextText = headerText;
+  let embeddedCount = 0;
+  const omittedTypes = [];
+  const includedSections = [];
+
+  for (let index = 0; index < sortedDiagrams.length; index += 1) {
+    const entry = sortedDiagrams[index];
+    if (embeddedCount >= contextMaxEmbeddedDiagrams) {
+      omittedTypes.push(entry.type);
+      continue;
+    }
+    const diagramPath = join(diagramsDir, entry.file);
+    const rawContent = readFileSync(diagramPath, 'utf8');
+    const rawBytes = Buffer.byteLength(rawContent || '', 'utf8');
+    const { text: trimmedContent, truncated, omittedLines } = trimToMaxLines(
+      rawContent,
+      contextMaxLinesPerDiagram
+    );
+
+    const section = [
+      `### ${entry.type}`,
+      '',
+      `Path: \`.diagram/${entry.file}\``,
+      `Approx tokens (full): ${estimateTokensFromBytes(rawBytes)}`,
+      ...(truncated ? [`Note: truncated to ${contextMaxLinesPerDiagram} lines (${omittedLines} lines omitted).`] : []),
+      '',
+      '```mermaid',
+      trimmedContent,
+      '```',
+      '',
+    ].join('\n');
+
+    const next = contextText + section;
+    if (Buffer.byteLength(next, 'utf8') > contextMaxBytes) {
+      omittedTypes.push(entry.type);
+      continue;
+    }
+
+    const remainingTypes = sortedDiagrams
+      .slice(index + 1)
+      .map((remaining) => remaining.type);
+    const reservedOmittedSection = buildOmittedSection(
+      omittedTypes.concat(remainingTypes)
+    );
+    if (Buffer.byteLength(next + reservedOmittedSection, 'utf8') > contextMaxBytes) {
+      omittedTypes.push(entry.type);
+      continue;
+    }
+
+    contextText = next;
+    embeddedCount += 1;
+    includedSections.push({ type: entry.type, section });
+  }
+
+  let omittedSection = buildOmittedSection(omittedTypes);
+  while (
+    Buffer.byteLength(contextText + omittedSection, 'utf8') > contextMaxBytes
+    && includedSections.length > 0
+  ) {
+    const removed = includedSections.pop();
+    embeddedCount = Math.max(embeddedCount - 1, 0);
+    omittedTypes.push(removed.type);
+    contextText = headerText + includedSections.map((entry) => entry.section).join('');
+    omittedSection = buildOmittedSection(omittedTypes);
+  }
+
+  if (
+    Buffer.byteLength(contextText + omittedSection, 'utf8') > contextMaxBytes
+    && omittedTypes.length > 0
+  ) {
+    omittedSection = buildOmittedSection(omittedTypes, true);
+  }
+
+  if (Buffer.byteLength(contextText + omittedSection, 'utf8') > contextMaxBytes) {
+    omittedSection = '';
+  }
+
+  contextText += omittedSection;
+  const result = {
+    generatedAt: nowIso,
+    embeddedCount,
+    omittedTypes: [...new Set(omittedTypes)].sort(),
+    bytes: Buffer.byteLength(contextText, 'utf8'),
+    headerCompacted: header.headerCompacted,
+    indexRowsIncluded: header.indexRowsIncluded,
+  };
+  if (!deterministic) {
+    result.rootPath = rootDir;
+  }
+  writeFileSync(contextPath, contextText);
+  if (contextMetaPath) {
+    writeFileSync(contextMetaPath, `${JSON.stringify(result, null, 2)}\n`);
+  }
+  return result;
+}
+
+function runFromEnv() {
+  const rootDir = process.env.ROOT_DIR;
+  const tmpDir = process.env.TMP_DIR;
+  const contextPath = process.env.CONTEXT_OUTPUT_PATH;
+  const contextMetaPath = process.env.CONTEXT_META_OUTPUT_PATH;
+  const contextMaxBytes = parsePositiveInt(process.env.CONTEXT_MAX_BYTES || '12000', 12000);
+  const contextMaxLinesPerDiagram = parsePositiveInt(
+    process.env.CONTEXT_MAX_LINES_PER_DIAGRAM || '140',
+    140
+  );
+  const contextMaxEmbeddedDiagrams = parsePositiveInt(
+    process.env.CONTEXT_MAX_EMBEDDED_DIAGRAMS || '3',
+    3
+  );
+  const deterministic = ['1', 'true', 'yes'].includes(
+    String(process.env.CONTEXT_DETERMINISTIC || '').toLowerCase()
+  );
+
+  buildContextPack({
+    rootDir,
+    tmpDir,
+    contextPath,
+    contextMetaPath,
+    contextMaxBytes,
+    contextMaxLinesPerDiagram,
+    contextMaxEmbeddedDiagrams,
+    deterministic,
+  });
+}
+
+if (require.main === module) {
+  try {
+    runFromEnv();
+  } catch (error) {
+    console.error(error.message || String(error));
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  buildContextPack,
+};

package/src/context/normalize-diagram-manifest.js

@@ -0,0 +1,282 @@
+const { createHash } = require('node:crypto');
+const { readdirSync, readFileSync, writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+const { estimateTokensFromBytes } = require('../artifacts/artifact-budget');
+
+function ensureTrailingNewline(content) {
+  return content.endsWith('\n') ? content : `${content}\n`;
+}
+
+function stableId(prefix, value) {
+  const slug = String(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 48) || prefix;
+  const digest = createHash('sha1').update(String(value)).digest('hex').slice(0, 8);
+  return `${prefix}_${slug}_${digest}`;
+}
+
+function parseArchitecture(content) {
+  const lines = String(content || '').trimEnd().split(/\r?\n/);
+  const subgraphs = [];
+  let currentSubgraph = null;
+
+  for (const line of lines) {
+    const subgraphMatch = line.match(/^  subgraph (\S+)\["(.+)"\]$/);
+    if (subgraphMatch) {
+      currentSubgraph = {
+        rawId: subgraphMatch[1],
+        label: subgraphMatch[2],
+        nodes: [],
+      };
+      subgraphs.push(currentSubgraph);
+      continue;
+    }
+
+    if (line === '  end') {
+      currentSubgraph = null;
+      continue;
+    }
+
+    const nodeMatch = line.match(/^    (\S+)\["(.+)"\]$/);
+    if (nodeMatch && currentSubgraph) {
+      currentSubgraph.nodes.push({
+        rawId: nodeMatch[1],
+        label: nodeMatch[2],
+      });
+    }
+  }
+
+  return subgraphs;
+}
+
+function firstMermaidDirective(content) {
+  const lines = String(content || '').split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('%%')) continue;
+    return trimmed;
+  }
+  return '';
+}
+
+function isClassicFlowchartArchitecture(content) {
+  const firstDirective = firstMermaidDirective(content);
+  return firstDirective === 'graph TD' || firstDirective.startsWith('graph TD ');
+}
+
+function buildArchitecture(subgraphs) {
+  const nodeMap = new Map();
+  const lines = ['graph TD'];
+  const sortedSubgraphs = [...subgraphs].sort((left, right) =>
+    left.label.localeCompare(right.label)
+  );
+
+  for (const subgraph of sortedSubgraphs) {
+    const subgraphId = stableId('sg', subgraph.label);
+    lines.push(`  subgraph ${subgraphId}["${subgraph.label}"]`);
+    const sortedNodes = [...subgraph.nodes].sort((left, right) =>
+      left.label.localeCompare(right.label)
+    );
+    for (const node of sortedNodes) {
+      const nodeId = stableId('node', `${subgraph.label}/${node.label}`);
+      nodeMap.set(node.rawId, { canonicalId: nodeId, label: node.label });
+      lines.push(`    ${nodeId}["${node.label}"]`);
+    }
+    lines.push('  end');
+  }
+
+  return {
+    content: ensureTrailingNewline(lines.join('\n')),
+    nodeMap,
+  };
+}
+
+function buildDependency(content, nodeMap) {
+  const lines = String(content || '').trimEnd().split(/\r?\n/);
+  if (lines.length === 0) {
+    return ensureTrailingNewline(String(content || ''));
+  }
+
+  const externalNodeMap = new Map();
+  const dependencyEdges = [];
+  const styleEntries = [];
+
+  for (const line of lines.slice(1)) {
+    const edgeMatch = line.match(/^  (\S+)\["(.+)"\] --> (\S+)$/);
+    if (edgeMatch) {
+      const [, rawSourceId, sourceLabel, rawTargetId] = edgeMatch;
+      const target = nodeMap.get(rawTargetId) ?? {
+        canonicalId: stableId('node', rawTargetId),
+        label: rawTargetId,
+      };
+      const sourceCanonicalId =
+        externalNodeMap.get(rawSourceId) ?? stableId('ext', sourceLabel);
+      externalNodeMap.set(rawSourceId, sourceCanonicalId);
+      dependencyEdges.push({
+        line: `  ${sourceCanonicalId}["${sourceLabel}"] --> ${target.canonicalId}`,
+        sortKey: `${sourceLabel}::${target.label}`,
+      });
+      continue;
+    }
+
+    const styleMatch = line.match(/^  style (\S+) (.+)$/);
+    if (!styleMatch) continue;
+    const [, rawNodeId, styleSpec] = styleMatch;
+    const canonicalId = externalNodeMap.get(rawNodeId);
+    if (!canonicalId) continue;
+    styleEntries.push({
+      line: `  style ${canonicalId} ${styleSpec}`,
+      sortKey: canonicalId,
+    });
+  }
+
+  return ensureTrailingNewline([
+    'graph LR',
+    ...dependencyEdges
+      .sort((left, right) => left.sortKey.localeCompare(right.sortKey))
+      .map((entry) => entry.line),
+    ...styleEntries
+      .sort((left, right) => left.sortKey.localeCompare(right.sortKey))
+      .map((entry) => entry.line),
+  ].join('\n'));
+}
+
+function isPlaceholderDiagram(content) {
+  const text = String(content || '');
+  return /placeholder/i.test(text)
+    || /not enough/i.test(text)
+    || /limited to/i.test(text);
+}
+
+function parseNonNegativeInt(value) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return null;
+  if (parsed < 0) return null;
+  return Math.floor(parsed);
+}
+
+function normalizeDiagramManifest({ rootDir, tmpDir, manifestPath }) {
+  if (!rootDir || !tmpDir || !manifestPath) {
+    throw new Error('normalizeDiagramManifest requires rootDir, tmpDir, and manifestPath');
+  }
+
+  const diagramsDir = join(tmpDir, 'diagrams');
+  let sourceManifest = {};
+  try {
+    sourceManifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`Failed to read diagram manifest at ${manifestPath}: ${error.message}`);
+  }
+
+  const diagramFiles = readdirSync(diagramsDir).filter((entry) => entry.endsWith('.mmd'));
+  const architecturePath = join(diagramsDir, 'architecture.mmd');
+  const dependencyPath = join(diagramsDir, 'dependency.mmd');
+
+  if (diagramFiles.includes('architecture.mmd')) {
+    const architectureContent = readFileSync(architecturePath, 'utf8');
+    if (!isClassicFlowchartArchitecture(architectureContent)) {
+      writeFileSync(architecturePath, ensureTrailingNewline(architectureContent.trimEnd()));
+    } else {
+      const parsedArchitecture = parseArchitecture(architectureContent);
+      const hasParsedNodes = parsedArchitecture.some((subgraph) =>
+        Array.isArray(subgraph.nodes) && subgraph.nodes.length > 0
+      );
+      if (!hasParsedNodes) {
+        throw new Error('Failed to normalize architecture.mmd: parsed structure was empty.');
+      }
+
+      const { content: canonicalArchitecture, nodeMap } = buildArchitecture(parsedArchitecture);
+      if (!(nodeMap instanceof Map) || nodeMap.size === 0) {
+        throw new Error('Failed to normalize architecture.mmd: canonical node map was empty.');
+      }
+      writeFileSync(architecturePath, canonicalArchitecture);
+
+      if (diagramFiles.includes('dependency.mmd')) {
+        const dependencyContent = readFileSync(dependencyPath, 'utf8');
+        writeFileSync(dependencyPath, buildDependency(dependencyContent, nodeMap));
+      }
+    }
+  }
+
+  for (const file of diagramFiles) {
+    if (file === 'architecture.mmd' || file === 'dependency.mmd') {
+      continue;
+    }
+    const filePath = join(diagramsDir, file);
+    writeFileSync(filePath, ensureTrailingNewline(readFileSync(filePath, 'utf8').trimEnd()));
+  }
+
+  const sourceDiagramEntries = Array.isArray(sourceManifest.diagrams)
+    ? sourceManifest.diagrams.filter((entry) => entry && typeof entry === 'object')
+    : [];
+  const sourceByFile = new Map();
+  const sourceByType = new Map();
+  for (const entry of sourceDiagramEntries) {
+    if (typeof entry.file === 'string' && entry.file) {
+      sourceByFile.set(entry.file, entry);
+    }
+    if (typeof entry.type === 'string' && entry.type) {
+      sourceByType.set(entry.type, entry);
+    }
+  }
+
+  const diagrams = readdirSync(diagramsDir)
+    .filter((file) => file.endsWith('.mmd'))
+    .sort()
+    .map((file) => {
+      const content = readFileSync(join(diagramsDir, file), 'utf8');
+      const type = file.replace(/\.mmd$/, '');
+      const existingEntry = sourceByFile.get(file) || sourceByType.get(type) || {};
+      const bytes = Buffer.byteLength(content);
+      const sourceBytes = parseNonNegativeInt(existingEntry.sourceBytes) ?? bytes;
+      const tokenBaseBytes = sourceBytes > 0 ? sourceBytes : bytes;
+      return {
+        ...existingEntry,
+        type,
+        file,
+        outputPath: `.diagram/${file}`,
+        lines: content.split(/\r?\n/).length,
+        bytes,
+        sourceBytes,
+        approxTokens: estimateTokensFromBytes(tokenBaseBytes),
+        isPlaceholder: isPlaceholderDiagram(content),
+      };
+    });
+
+  const manifest = {
+    ...(typeof sourceManifest.generatedAt === 'string' && sourceManifest.generatedAt
+      ? { generatedAt: sourceManifest.generatedAt }
+      : {}),
+    rootPath: rootDir,
+    diagramDir: '.diagram',
+    ...(sourceManifest && typeof sourceManifest.compaction === 'object'
+      ? { compaction: sourceManifest.compaction }
+      : {}),
+    diagrams,
+  };
+
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  return manifest;
+}
+
+function runFromEnv() {
+  const rootDir = process.env.ROOT_DIR;
+  const tmpDir = process.env.TMP_DIR;
+  const manifestPath = process.env.MANIFEST_PATH;
+  normalizeDiagramManifest({ rootDir, tmpDir, manifestPath });
+}
+
+if (require.main === module) {
+  try {
+    runFromEnv();
+  } catch (error) {
+    console.error(error.message || String(error));
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  normalizeDiagramManifest,
+};