@brainwav/diagram 1.0.7 → 1.1.0

package/src/artifacts/artifact-budget.js

@@ -0,0 +1,224 @@
+const AGENT_DIAGRAM_PRIORITY = Object.freeze([
+  'architecture',
+  'dependency',
+  'erd',
+  'database',
+  'security',
+  'auth',
+  'events',
+  'user',
+  'flow',
+  'class',
+  'sequence',
+  'agent',
+  'c4context',
+  'rag',
+]);
+const BYTES_PER_TOKEN_ESTIMATE = 4;
+
+const BASE_ARTIFACT_PROFILES = Object.freeze({
+  full: Object.freeze({
+    name: 'full',
+    maxBytesTotal: null,
+    maxBytesPerDiagram: null,
+    maxDiagrams: null,
+    priorityOrder: AGENT_DIAGRAM_PRIORITY,
+  }),
+  agent: Object.freeze({
+    name: 'agent',
+    maxBytesTotal: 12000,
+    maxBytesPerDiagram: 4000,
+    maxDiagrams: 4,
+    priorityOrder: AGENT_DIAGRAM_PRIORITY,
+  }),
+  'ultra-compact': Object.freeze({
+    name: 'ultra-compact',
+    maxBytesTotal: 9000,
+    maxBytesPerDiagram: 3000,
+    maxDiagrams: 3,
+    priorityOrder: AGENT_DIAGRAM_PRIORITY,
+  }),
+});
+
+function toPositiveInt(value) {
+  if (value === null || value === undefined) return null;
+  if (value === '') return null;
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return null;
+  }
+  return parsed;
+}
+
+function byteLength(text) {
+  return Buffer.byteLength(String(text || ''), 'utf8');
+}
+
+function estimateTokensFromBytes(byteCount) {
+  const normalized = Number.isFinite(byteCount) ? byteCount : 0;
+  return Math.ceil(normalized / BYTES_PER_TOKEN_ESTIMATE);
+}
+
+function resolveArtifactProfile(profileName = 'full', overrides = {}) {
+  const normalizedName = String(profileName || 'full').toLowerCase();
+  const base = BASE_ARTIFACT_PROFILES[normalizedName];
+  if (!base) {
+    const supported = Object.keys(BASE_ARTIFACT_PROFILES).join(', ');
+    throw new Error(`Invalid artifact profile "${profileName}". Supported profiles: ${supported}`);
+  }
+
+  return {
+    ...base,
+    maxBytesTotal: toPositiveInt(overrides.maxBytesTotal) ?? base.maxBytesTotal,
+    maxBytesPerDiagram: toPositiveInt(overrides.maxBytesPerDiagram) ?? base.maxBytesPerDiagram,
+    maxDiagrams: toPositiveInt(overrides.maxDiagrams) ?? base.maxDiagrams,
+    priorityOrder: Array.isArray(base.priorityOrder) ? [...base.priorityOrder] : [],
+  };
+}
+
+function sortByPriority(diagrams, priorityOrder) {
+  const rank = new Map((priorityOrder || []).map((type, index) => [type, index]));
+  return [...(Array.isArray(diagrams) ? diagrams : [])].sort((left, right) => {
+    const leftRank = rank.has(left.type) ? rank.get(left.type) : Number.MAX_SAFE_INTEGER;
+    const rightRank = rank.has(right.type) ? rank.get(right.type) : Number.MAX_SAFE_INTEGER;
+    if (leftRank !== rightRank) {
+      return leftRank - rightRank;
+    }
+    return String(left.type || '').localeCompare(String(right.type || ''));
+  });
+}
+
+function truncateMermaidByBytes(mermaid, maxBytes) {
+  const content = String(mermaid || '');
+  const originalBytes = byteLength(content);
+  if (!maxBytes || originalBytes <= maxBytes) {
+    return {
+      content,
+      bytes: originalBytes,
+      originalBytes,
+      truncated: false,
+      omittedLines: 0,
+    };
+  }
+
+  const sourceLines = content.split(/\r?\n/);
+  const marker = `%% compacted: truncated to ${maxBytes} bytes from ${originalBytes} bytes`;
+  const suffix = '%% compacted: tail omitted';
+  const header = `${marker}\n`;
+  const footer = `\n${suffix}\n`;
+  const maxBodyBytes = maxBytes - byteLength(header) - byteLength(footer);
+  if (maxBodyBytes <= 0) {
+    const minimal = `${marker}\n${suffix}\n`;
+    return {
+      content: minimal,
+      bytes: byteLength(minimal),
+      originalBytes,
+      truncated: true,
+      omittedLines: sourceLines.length,
+    };
+  }
+
+  const keptLines = [];
+  let bodyBytes = 0;
+  for (const line of sourceLines) {
+    const candidate = keptLines.length > 0 ? `\n${line}` : line;
+    const candidateBytes = byteLength(candidate);
+    if (bodyBytes + candidateBytes > maxBodyBytes) {
+      break;
+    }
+    keptLines.push(line);
+    bodyBytes += candidateBytes;
+  }
+
+  const compacted = `${header}${keptLines.join('\n')}${footer}`;
+  return {
+    content: compacted,
+    bytes: byteLength(compacted),
+    originalBytes,
+    truncated: true,
+    omittedLines: Math.max(sourceLines.length - keptLines.length, 0),
+  };
+}
+
+function applyArtifactBudget(diagrams, profile) {
+  const sorted = sortByPriority(diagrams, profile.priorityOrder);
+  const included = [];
+  const omitted = [];
+  let writtenBytes = 0;
+  let originalBytes = 0;
+
+  for (const diagram of sorted) {
+    const source = String(diagram.mermaid || '');
+    const sourceBytes = byteLength(source);
+    originalBytes += sourceBytes;
+
+    if (profile.name !== 'full' && diagram.metadata?.compactEligible === false) {
+      omitted.push({
+        type: diagram.type,
+        reason: 'low_confidence',
+        originalBytes: sourceBytes,
+      });
+      continue;
+    }
+
+    if (profile.maxDiagrams && included.length >= profile.maxDiagrams) {
+      omitted.push({
+        type: diagram.type,
+        reason: 'max_diagrams',
+        originalBytes: sourceBytes,
+      });
+      continue;
+    }
+
+    const compacted = truncateMermaidByBytes(source, profile.maxBytesPerDiagram);
+
+    if (profile.maxBytesTotal && writtenBytes + compacted.bytes > profile.maxBytesTotal) {
+      omitted.push({
+        type: diagram.type,
+        reason: 'max_total_bytes',
+        originalBytes: sourceBytes,
+      });
+      continue;
+    }
+
+    included.push({
+      type: diagram.type,
+      mermaid: compacted.content,
+      metadata: diagram.metadata,
+      bytes: compacted.bytes,
+      originalBytes: compacted.originalBytes,
+      truncated: compacted.truncated,
+      omittedLines: compacted.omittedLines,
+      bytesSaved: Math.max(compacted.originalBytes - compacted.bytes, 0),
+    });
+    writtenBytes += compacted.bytes;
+  }
+
+  const truncatedTypes = included
+    .filter((entry) => entry.truncated)
+    .map((entry) => entry.type);
+  const bytesSaved = Math.max(originalBytes - writtenBytes, 0);
+
+  return {
+    included,
+    omitted,
+    truncatedTypes,
+    applied: omitted.length > 0 || truncatedTypes.length > 0,
+    summary: {
+      generatedCount: sorted.length,
+      includedCount: included.length,
+      omittedCount: omitted.length,
+      originalBytes,
+      writtenBytes,
+      bytesSaved,
+    },
+  };
+}
+
+module.exports = {
+  AGENT_DIAGRAM_PRIORITY,
+  estimateTokensFromBytes,
+  resolveArtifactProfile,
+  applyArtifactBudget,
+  sortByPriority,
+};

package/src/artifacts/brief.js

@@ -0,0 +1,153 @@
+const fs = require('fs');
+const path = require('path');
+const { summarizeAnalysis } = require('./evidence-summary');
+
+const BRIEF_HEADINGS = Object.freeze([
+  '# Archscope Evidence Brief',
+  '## Summary',
+  '## Artifact Read Order',
+  '## Risk And Validation',
+  '## Warnings',
+  '## Agent Handoff',
+  '## Next Action',
+]);
+
+function formatList(items, emptyText) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return [`- ${emptyText}`];
+  }
+  return items.map((item) => `- ${item}`);
+}
+
+/**
+ * Build a markdown "Archscope Evidence Brief" describing analysis and manifest outcomes.
+ *
+ * Produces a structured markdown string containing headings for summary, artifact read order,
+ * risk and validation, warnings, agent handoff and next actions, plus PR-specific details when
+ * PR impact information is provided or PR evidence generation failed.
+ *
+ * @param {Object} params - Input parameters.
+ * @param {Object} params.manifest - Manifest describing artifacts, read order and validation status.
+ * @param {Object} params.analysis - Analysis result used to summarise components, files, languages and areas.
+ * @param {Object|null} [params.prImpact=null] - Optional PR impact data; when present the brief includes PR base/head, changed components, blast radius, risk reasons, suggested reviewer checks, validation evidence and confidence.
+ * @param {string[]} [params.warnings=[]] - Array of warning messages to include in the brief.
+ * @param {Array<{category:string,message:string,artifact?:string}>} [params.errors=[]] - Array of error objects to include; PR evidence generation errors are surfaced in the PR section.
+ * @returns {string} A markdown-formatted evidence brief.
+ */
+function buildArchitectureBrief({
+  manifest,
+  analysis,
+  prImpact = null,
+  warnings = [],
+  errors = [],
+}) {
+  const [
+    titleHeading,
+    summaryHeading,
+    readOrderHeading,
+    riskHeading,
+    warningsHeading,
+    handoffHeading,
+    nextActionHeading,
+  ] = BRIEF_HEADINGS;
+  const summary = summarizeAnalysis(analysis);
+  const languageText = summary.languages.length > 0
+    ? summary.languages.map(([name, count]) => `${name} (${count})`).join(', ')
+    : 'unknown';
+  const areaText = summary.areas.length > 0
+    ? summary.areas.map(([name, count]) => `${name} (${count})`).join(', ')
+    : 'unknown';
+  const prError = errors.find((error) => error.artifact === 'pr-impact');
+  const modeText = prImpact || prError ? 'pr scan' : 'repository scan';
+  const warningLines = formatList(warnings, 'No warnings recorded.');
+  const errorLines = formatList(
+    errors.map((error) => `${error.category}: ${error.message}`),
+    'No errors recorded.'
+  );
+  const prImpactPath = prImpact?.prImpactPath
+    || manifest.artifacts.find((entry) => entry.id === 'pr-impact' && entry.status === 'written')?.path
+    || null;
+  const decisionLine = prImpact
+    ? `- Review decision: inspect ${prImpactPath || 'the PR evidence outcome'} before approving architecture-sensitive changes.`
+    : prError
+      ? '- Review decision: resolve PR evidence failure before approving architecture-sensitive changes.'
+      : '- Review decision: read the manifest and brief before handing this repo to a reviewer or coding agent.';
+  let prLines;
+  if (prImpact) {
+    prLines = [
+      `- PR base: ${prImpact.base}`,
+      `- PR head: ${prImpact.head}`,
+      `- Changed components: ${prImpact.agentSummary?.changedComponents ?? prImpact.changedComponents?.length ?? 0}`,
+      `- Blast radius: ${prImpact.blastRadius?.impactedComponents?.length ?? 0}`,
+      `- Risk reasons: ${(prImpact.agentSummary?.riskReasons || []).join(', ') || 'none'}`,
+      `- Reviewer checks: ${(prImpact.agentSummary?.suggestedReviewerChecks || []).join('; ') || 'none'}`,
+      prImpactPath
+        ? `- Validation evidence: workflow pr contract reused via ${prImpactPath}`
+        : `- Validation evidence: PR impact artifact not written (${prImpact._meta?.status || 'not_written'}).`,
+      `- Confidence: ${prImpact.confidence?.level || 'unknown'}`,
+    ];
+  } else if (prError) {
+    prLines = [`- PR evidence generation failed: ${prError.category}: ${prError.message}`];
+  } else {
+    prLines = ['- PR refs not supplied.'];
+  }
+
+  const lines = [
+    titleHeading,
+    '',
+    summaryHeading,
+    '',
+    `- Mode: ${modeText}`,
+    `- Components detected: ${summary.componentCount}`,
+    `- Files considered: ${summary.totalFilesFound}`,
+    `- Entry points detected: ${summary.entryPointCount}`,
+    `- Languages: ${languageText}`,
+    `- Architecture areas: ${areaText}`,
+    decisionLine,
+    '',
+    readOrderHeading,
+    '',
+    ...manifest.artifactReadOrder.map((artifactPath, index) => `${index + 1}. ${artifactPath}`),
+    '',
+    riskHeading,
+    '',
+    `- Validation: ${manifest.validation.status}`,
+    `- Risk: ${prImpact?.risk?.level || 'unknown until PR refs or policy validation are supplied'}`,
+    `- Evidence status: ${manifest.artifacts.some((entry) => entry.status === 'failed') ? 'failed' : 'written'}`,
+    ...prLines,
+    '',
+    warningsHeading,
+    '',
+    ...warningLines,
+    '',
+    handoffHeading,
+    '',
+    `- Read ${manifest.artifactReadOrder[0]} first for artifact status.`,
+    `- Use ${manifest.primaryAgentArtifact} as the parser-safe agent contract.`,
+    `- Open ${manifest.primaryHumanArtifact} for the concise human summary.`,
+    '',
+    nextActionHeading,
+    '',
+    ...errorLines,
+  ];
+
+  return `${lines.join('\n')}\n`;
+}
+
+function writeArchitectureBrief(filePath, input) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const content = buildArchitectureBrief(input);
+  fs.writeFileSync(filePath, content);
+  return {
+    path: filePath,
+    lines: content.trimEnd().split(/\r?\n/).length,
+    bytes: Buffer.byteLength(content, 'utf8'),
+  };
+}
+
+module.exports = {
+  BRIEF_HEADINGS,
+  buildArchitectureBrief,
+  summarizeAnalysis,
+  writeArchitectureBrief,
+};

package/src/artifacts/evidence-manifest.js

@@ -0,0 +1,206 @@
+const fs = require('fs');
+const path = require('path');
+const { estimateTokensFromBytes } = require('./artifact-budget');
+
+const FIXED_DETERMINISTIC_TIMESTAMP = '1970-01-01T00:00:00.000Z';
+const ARTIFACT_STATUSES = new Set(['written', 'deferred', 'partial', 'failed']);
+
+function unixPath(value) {
+  return String(value || '').split(path.sep).join('/');
+}
+
+function sortStrings(values) {
+  return [...(values || [])].sort((a, b) => String(a).localeCompare(String(b)));
+}
+
+function getGeneratedAt(deterministic) {
+  return deterministic ? FIXED_DETERMINISTIC_TIMESTAMP : new Date().toISOString();
+}
+
+function realpathIfPresent(value) {
+  try {
+    return fs.realpathSync(value);
+  } catch (_error) {
+    return value;
+  }
+}
+
+function writeJsonFile(filePath, payload) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function createGenerateAllManifest({
+  root,
+  outDir,
+  artifactProfile,
+  budgeted,
+  deterministic = false,
+}) {
+  const realRoot = realpathIfPresent(root);
+  return {
+    generatedAt: getGeneratedAt(deterministic),
+    schemaVersion: '1.0',
+    rootPath: root,
+    diagramDir: path.relative(realRoot, outDir) || '.',
+    compaction: {
+      applied: budgeted.applied,
+      profile: artifactProfile.name,
+      maxTotalBytes: artifactProfile.maxBytesTotal,
+      maxPerDiagramBytes: artifactProfile.maxBytesPerDiagram,
+      maxDiagrams: artifactProfile.maxDiagrams,
+      generatedDiagrams: budgeted.summary.generatedCount,
+      writtenDiagrams: budgeted.summary.includedCount,
+      omittedTypes: budgeted.omitted.map((entry) => entry.type),
+      truncatedTypes: budgeted.truncatedTypes,
+      bytesSaved: budgeted.summary.bytesSaved,
+      estimatedTokensSaved: estimateTokensFromBytes(budgeted.summary.bytesSaved),
+      reason: artifactProfile.name === 'full'
+        ? 'full_profile'
+        : (budgeted.applied ? 'budget_constraints' : 'within_budget'),
+    },
+    diagrams: [],
+  };
+}
+
+function artifactEntry({
+  id,
+  path: artifactPath,
+  status,
+  role,
+  optional = false,
+  reason = null,
+  errorCategory = null,
+}) {
+  if (!ARTIFACT_STATUSES.has(status)) {
+    throw new Error(`Invalid artifact status for ${id}: ${status}`);
+  }
+  return {
+    id,
+    path: artifactPath,
+    status,
+    role,
+    optional,
+    ...(reason ? { reason } : {}),
+    ...(errorCategory ? { errorCategory } : {}),
+  };
+}
+
+function createScanEvidenceManifest({
+  root,
+  outDir,
+  deterministic = false,
+  warnings = [],
+  artifactStatuses = {},
+  artifactReasons = {},
+  artifactErrorCategories = {},
+}) {
+  const realRoot = realpathIfPresent(root);
+  const diagramDir = unixPath(path.relative(realRoot, outDir) || '.');
+  const artifactPath = (fileName) => unixPath(path.join(diagramDir, fileName));
+  const statusFor = (id, fallback) => artifactStatuses[id] || fallback;
+  const reportStatus = statusFor('report', 'deferred');
+
+  const artifacts = [
+    artifactEntry({
+      id: 'manifest',
+      path: artifactPath('manifest.json'),
+      status: statusFor('manifest', 'written'),
+      role: 'artifact-index',
+      reason: artifactReasons.manifest || null,
+      errorCategory: artifactErrorCategories.manifest || null,
+    }),
+    artifactEntry({
+      id: 'brief',
+      path: artifactPath('brief.md'),
+      status: statusFor('brief', 'deferred'),
+      role: 'primary-human-summary',
+      reason: artifactReasons.brief
+        || (statusFor('brief', 'deferred') === 'deferred' ? 'p1_not_implemented' : null),
+      errorCategory: artifactErrorCategories.brief || null,
+    }),
+    artifactEntry({
+      id: 'agent-context',
+      path: artifactPath('agent-context.json'),
+      status: statusFor('agent-context', 'deferred'),
+      role: 'primary-agent-context',
+      reason: artifactReasons['agent-context']
+        || (statusFor('agent-context', 'deferred') === 'deferred' ? 'p1_not_implemented' : null),
+      errorCategory: artifactErrorCategories['agent-context'] || null,
+    }),
+    artifactEntry({
+      id: 'architecture',
+      path: artifactPath('architecture.mmd'),
+      status: statusFor('architecture', 'deferred'),
+      role: 'supporting-diagram',
+      reason: artifactReasons.architecture
+        || (statusFor('architecture', 'deferred') === 'deferred' ? 'p1_not_implemented' : null),
+      errorCategory: artifactErrorCategories.architecture || null,
+    }),
+    artifactEntry({
+      id: 'report',
+      path: artifactPath('report.html'),
+      status: reportStatus,
+      role: 'human-report',
+      optional: true,
+      reason: artifactReasons.report || (reportStatus === 'deferred' ? 'ui_spec_required' : null),
+      errorCategory: artifactErrorCategories.report || null,
+    }),
+    artifactEntry({
+      id: 'pr-impact',
+      path: artifactPath('pr-impact/pr-impact.json'),
+      status: statusFor('pr-impact', 'deferred'),
+      role: 'pr-impact-json',
+      optional: true,
+      reason: artifactReasons['pr-impact']
+        || (statusFor('pr-impact', 'deferred') === 'deferred' ? 'pr_refs_not_supplied' : null),
+      errorCategory: artifactErrorCategories['pr-impact'] || null,
+    }),
+  ].sort((a, b) => a.path.localeCompare(b.path));
+
+  const primaryHumanArtifact = reportStatus === 'written'
+    ? artifactPath('report.html')
+    : artifactPath('brief.md');
+  const primaryAgentArtifact = artifactPath('agent-context.json');
+  const artifactReadOrder = [
+    artifactPath('manifest.json'),
+    artifactPath('brief.md'),
+    artifactPath('agent-context.json'),
+    ...(statusFor('pr-impact', 'deferred') === 'written' ? [artifactPath('pr-impact/pr-impact.json')] : []),
+  ];
+
+  return {
+    schemaVersion: '1.0',
+    command: 'scan',
+    generatedAt: getGeneratedAt(deterministic),
+    deterministic: Boolean(deterministic),
+    project: {
+      label: path.basename(root) || '.',
+      path: '.',
+    },
+    outputDirectory: diagramDir,
+    primaryHumanArtifact,
+    primaryAgentArtifact,
+    artifactReadOrder,
+    artifacts,
+    subordinateDirectories: [
+      unixPath(path.join(diagramDir, 'contracts')),
+      unixPath(path.join(diagramDir, 'context')),
+      unixPath(path.join(diagramDir, 'migration')),
+      unixPath(path.join(diagramDir, 'pr-impact')),
+    ].sort(),
+    validation: {
+      status: 'not_run',
+      summary: 'scan does not run validation automatically',
+    },
+    warnings: sortStrings(warnings),
+  };
+}
+
+module.exports = {
+  FIXED_DETERMINISTIC_TIMESTAMP,
+  createGenerateAllManifest,
+  createScanEvidenceManifest,
+  getGeneratedAt,
+  writeJsonFile,
+};

package/src/artifacts/evidence-summary.js

@@ -0,0 +1,29 @@
+function countBy(items, selectKey) {
+  const counts = new Map();
+  for (const item of items || []) {
+    const key = selectKey(item);
+    if (!key) continue;
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  return [...counts.entries()].sort((left, right) =>
+    left[0].localeCompare(right[0])
+  );
+}
+
+function summarizeAnalysis(analysis = {}) {
+  const components = Array.isArray(analysis.components) ? analysis.components : [];
+  return {
+    componentCount: components.length,
+    entryPointCount: Array.isArray(analysis.entryPoints) ? analysis.entryPoints.length : 0,
+    totalFilesFound: Number.isFinite(Number(analysis.totalFilesFound))
+      ? Number(analysis.totalFilesFound)
+      : components.length,
+    languages: countBy(components, (component) => component.language),
+    areas: countBy(components, (component) => component.type),
+  };
+}
+
+module.exports = {
+  countBy,
+  summarizeAnalysis,
+};