@brainwav/diagram 1.0.7 → 1.1.0

package/src/incremental/cache.js

@@ -0,0 +1,210 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const CACHE_SCHEMA_VERSION = '1.0';
+
+function normalizeOptions(options = {}) {
+  return {
+    patterns: options.patterns || null,
+    exclude: options.exclude || null,
+    maxFiles: options.maxFiles || null,
+    analyzer: options.analyzer || 'default',
+  };
+}
+
+function buildCacheKey(command, options = {}) {
+  const payload = {
+    command,
+    schemaVersion: CACHE_SCHEMA_VERSION,
+    options: normalizeOptions(options),
+  };
+  const hash = crypto
+    .createHash('sha256')
+    .update(JSON.stringify(payload))
+    .digest('hex')
+    .slice(0, 16);
+  return `${command}-${hash}`;
+}
+
+function resolveCacheDir(rootPath) {
+  if (process.env.DIAGRAM_CACHE_DIR) {
+    const resolved = path.resolve(process.env.DIAGRAM_CACHE_DIR);
+    // Security: ensure the override stays inside the project root
+    const rel = path.relative(rootPath, resolved);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(
+        `DIAGRAM_CACHE_DIR must be inside the project root.\n` +
+        `  Root:     ${rootPath}\n` +
+        `  Resolved: ${resolved}`
+      );
+    }
+    return resolved;
+  }
+  return path.join(rootPath, '.diagram', 'cache');
+}
+
+/**
+ * Build a directory-mtime signature from the parent directories of all analyzed
+ * files. Adding or deleting any file inside a tracked directory changes that
+ * directory's mtime, causing a cache miss on the next read.
+ *
+ * This is cheaper than re-globbing and doesn't require passing options into the
+ * read path. It correctly detects file additions and deletions.
+ *
+ * @param {string[]} filePaths - Relative file paths from analysis.components
+ * @param {string} rootPath - Project root (used to resolve relative paths)
+ * @returns {string} SHA-256 hex digest of sorted dir:mtime:nlink entries
+ */
+function buildDirectoryMtimeSignature(filePaths, rootPath) {
+  // Collect unique parent directories, always including the root itself
+  const dirs = new Set([rootPath]);
+  for (const fp of filePaths) {
+    const abs = path.isAbsolute(fp) ? fp : path.join(rootPath, fp);
+    dirs.add(path.dirname(abs));
+  }
+
+  const entries = [];
+  for (const dir of dirs) {
+    try {
+      const st = fs.statSync(dir);
+      // nlink tracks the number of directory entries; mtimeMs tracks last change
+      entries.push(`${dir}:${st.mtimeMs}:${st.nlink}`);
+    } catch {
+      // Directory gone — treat as a change
+      entries.push(`${dir}:MISSING`);
+    }
+  }
+  entries.sort();
+  return crypto.createHash('sha256').update(entries.join('\n')).digest('hex');
+}
+
+/**
+ * Build a content signature for the set of files that were analyzed.
+ * Uses file mtime + size — fast enough for hundreds of files, no content read required.
+ * Detects modifications to existing files; pair with buildFileListSignature to
+ * also detect additions and deletions.
+ *
+ * @param {string[]} filePaths - Absolute or relative (to rootPath) file paths
+ * @param {string} rootPath - Project root
+ * @returns {string} SHA-256 hex digest of the sorted mtime+size tuples
+ */
+function buildContentSignature(filePaths, rootPath) {
+  const entries = [];
+  for (const fp of filePaths) {
+    const abs = path.isAbsolute(fp) ? fp : path.join(rootPath, fp);
+    try {
+      const st = fs.statSync(abs);
+      // Include mtime in ms and size; sorting ensures stable ordering
+      entries.push(`${fp}:${st.mtimeMs}:${st.size}`);
+    } catch {
+      // File gone — treat as a change
+      entries.push(`${fp}:MISSING`);
+    }
+  }
+  entries.sort();
+  return crypto.createHash('sha256').update(entries.join('\n')).digest('hex');
+}
+
+/**
+ * Validate the stored content signature against current file state.
+ * Returns true when the cache is still fresh.
+ *
+ * @param {string[]} storedFilePaths - Relative file paths stored in analysis.components
+ * @param {string} storedSignature - Digest stored in the cache entry
+ * @param {string} rootPath - Project root
+ * @returns {boolean}
+ */
+function isCacheContentFresh(storedFilePaths, storedSignature, rootPath) {
+  if (!storedSignature || !Array.isArray(storedFilePaths)) return false;
+  const current = buildContentSignature(storedFilePaths, rootPath);
+  return current === storedSignature;
+}
+
+function readCachedAnalysis(rootPath, key) {
+  const cacheDir = resolveCacheDir(rootPath);
+  const cachePath = path.join(cacheDir, `${key}.json`);
+  if (!fs.existsSync(cachePath)) {
+    return { hit: false, reason: 'cache_miss', data: null, cachePath };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+    if (parsed.schemaVersion !== CACHE_SCHEMA_VERSION) {
+      return { hit: false, reason: 'schema_mismatch', data: null, cachePath };
+    }
+    if (!parsed.analysis || !parsed.savedAt) {
+      return { hit: false, reason: 'invalid_cache_payload', data: null, cachePath };
+    }
+
+    const storedFilePaths = (parsed.analysis.components || []).map((c) => c.filePath);
+
+    // Step 1: Directory-mtime check — detects file additions and deletions.
+    // At write time we snapshot each parent directory's mtime+nlink. Any new
+    // or deleted file changes its parent directory, so this hash will differ.
+    const storedDirSig = parsed.directoryMtimeSignature;
+    if (!storedDirSig) {
+      // Old cache entry — force a refresh to pick up the new signature.
+      return { hit: false, reason: 'no_directory_mtime_signature', data: null, cachePath };
+    }
+    const currentDirSig = buildDirectoryMtimeSignature(storedFilePaths, rootPath);
+    if (currentDirSig !== storedDirSig) {
+      return { hit: false, reason: 'directory_changed', data: null, cachePath };
+    }
+
+    // Step 2: Content check — detects modifications to existing files.
+    const storedSignature = parsed.contentSignature;
+    if (storedSignature) {
+      if (!isCacheContentFresh(storedFilePaths, storedSignature, rootPath)) {
+        return { hit: false, reason: 'content_changed', data: null, cachePath };
+      }
+    } else {
+      return { hit: false, reason: 'no_content_signature', data: null, cachePath };
+    }
+
+    return {
+      hit: true,
+      reason: 'cache_hit',
+      data: parsed.analysis,
+      cachePath,
+      savedAt: parsed.savedAt,
+    };
+  } catch (error) {
+    return { hit: false, reason: 'cache_parse_error', data: null, cachePath, error: error.message };
+  }
+}
+
+function writeCachedAnalysis(rootPath, key, analysis) {
+  const cacheDir = resolveCacheDir(rootPath);
+  const cachePath = path.join(cacheDir, `${key}.json`);
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const filePaths = (analysis.components || []).map((c) => c.filePath);
+  // directoryMtimeSignature: detects new/deleted files by watching parent dir mtimes.
+  const directoryMtimeSignature = buildDirectoryMtimeSignature(filePaths, rootPath);
+  // contentSignature: detects modifications to the existing file set.
+  const contentSignature = buildContentSignature(filePaths, rootPath);
+
+  fs.writeFileSync(
+    cachePath,
+    `${JSON.stringify({
+      schemaVersion: CACHE_SCHEMA_VERSION,
+      savedAt: new Date().toISOString(),
+      directoryMtimeSignature,
+      contentSignature,
+      analysis,
+    }, null, 2)}\n`
+  );
+  return cachePath;
+}
+
+module.exports = {
+  CACHE_SCHEMA_VERSION,
+  buildCacheKey,
+  buildDirectoryMtimeSignature,
+  buildContentSignature,
+  isCacheContentFresh,
+  readCachedAnalysis,
+  writeCachedAnalysis,
+  resolveCacheDir,
+};

package/src/ir/architecture-ir.js

@@ -0,0 +1,48 @@
+const fs = require('fs');
+const path = require('path');
+
+const IR_SCHEMA_VERSION = '1.0';
+
+function toArchitectureIR(analysisResult, metadata = {}) {
+  const components = Array.isArray(analysisResult?.components)
+    ? analysisResult.components.map((component) => ({
+        name: component.name,
+        originalName: component.originalName,
+        filePath: component.filePath,
+        type: component.type,
+        roleTags: Array.isArray(component.roleTags) ? [...component.roleTags].sort() : [],
+        dependencies: Array.isArray(component.dependencies) ? [...component.dependencies].sort() : [],
+      }))
+    : [];
+
+  return {
+    schemaVersion: IR_SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    rootPath: analysisResult?.rootPath || metadata.rootPath || '',
+    analyzer: metadata.analyzer || { name: 'default', version: 'unknown' },
+    summary: {
+      componentCount: components.length,
+      languageCount: Object.keys(analysisResult?.languages || {}).length,
+      entryPointCount: Array.isArray(analysisResult?.entryPoints) ? analysisResult.entryPoints.length : 0,
+    },
+    languages: analysisResult?.languages || {},
+    entryPoints: analysisResult?.entryPoints || [],
+    components,
+  };
+}
+
+function writeArchitectureIR(rootPath, ir, explicitPath) {
+  const destination = explicitPath
+    ? path.resolve(explicitPath)
+    : path.join(rootPath, '.diagram', 'ir', 'architecture-ir.json');
+
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.writeFileSync(destination, `${JSON.stringify(ir, null, 2)}\n`);
+  return destination;
+}
+
+module.exports = {
+  IR_SCHEMA_VERSION,
+  toArchitectureIR,
+  writeArchitectureIR,
+};

package/src/migration/evidence.js

@@ -0,0 +1,262 @@
+const crypto = require('crypto');
+
+const RC_TAG_PATTERN = /^v(\d+)\.(\d+)\.(\d+)-rc\.(\d+)$/;
+const RELEASE_ID_PATTERN = /^(\d+)\.(\d+)\.(\d+)-rc\.(\d+)$/;
+const UTC_TIMESTAMP_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/;
+const MINIMUM_WINDOW_DAYS = 30;
+const MINIMUM_RELEASE_CANDIDATES = 2;
+const DEFAULT_EVIDENCE_REFS = [
+  {
+    gate: 'dual_command_identity_available',
+    evidence: 'test/command-identity.test.js',
+  },
+  {
+    gate: 'compatibility_path_regression_passed',
+    evidence: 'scripts/validate-archscope-readiness.js compatibilityDrill',
+  },
+  {
+    gate: 'machine_command_coverage_manifest_valid',
+    evidence: 'scripts/validate-machine-contracts.js',
+  },
+  {
+    gate: 'machine_envelope_conformance_passed',
+    evidence: 'test/workflow-pr-machine-envelope.test.js',
+  },
+  {
+    gate: 'migration_evidence_hash_valid',
+    evidence: 'scripts/validate-migration-artifacts.js',
+  },
+  {
+    gate: 'append_only_ledger_valid',
+    evidence: 'scripts/validate-migration-artifacts.js',
+  },
+  {
+    gate: 'rollback_drill_passed',
+    evidence: 'scripts/validate-archscope-readiness.js compatibilityDrill',
+  },
+];
+
+function sortObjectDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map(sortObjectDeep);
+  }
+  if (value && typeof value === 'object') {
+    const sorted = {};
+    for (const key of Object.keys(value).sort()) {
+      sorted[key] = sortObjectDeep(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+function canonicalize(value) {
+  return JSON.stringify(sortObjectDeep(value));
+}
+
+function withoutContentHash(record) {
+  const clone = JSON.parse(JSON.stringify(record));
+  delete clone.contentHash;
+  return clone;
+}
+
+function computeContentHash(record) {
+  return crypto
+    .createHash('sha256')
+    .update(canonicalize(withoutContentHash(record)))
+    .digest('hex');
+}
+
+function attachContentHash(record) {
+  return {
+    ...record,
+    contentHash: computeContentHash(record),
+  };
+}
+
+function parseRcTag(tag) {
+  const match = RC_TAG_PATTERN.exec(String(tag || ''));
+  if (!match) return null;
+  const [, major, minor, patch, rc] = match;
+  return {
+    tag,
+    baseVersion: `${major}.${minor}.${patch}`,
+    rcNumber: Number.parseInt(rc, 10),
+  };
+}
+
+function releaseIdToTag(releaseId) {
+  if (!RELEASE_ID_PATTERN.test(String(releaseId || ''))) {
+    throw new Error(`Invalid releaseId: ${releaseId}`);
+  }
+  return `v${releaseId}`;
+}
+
+function daysBetweenUtc(startUtc, endUtc) {
+  if (!UTC_TIMESTAMP_PATTERN.test(String(startUtc || '')) || !UTC_TIMESTAMP_PATTERN.test(String(endUtc || ''))) {
+    throw new Error('compatibility window timestamps must be UTC ISO-8601 strings ending in Z');
+  }
+  const start = Date.parse(startUtc);
+  const end = Date.parse(endUtc);
+  if (!Number.isFinite(start) || !Number.isFinite(end)) {
+    throw new Error('compatibility window timestamps must be valid UTC date strings');
+  }
+  return Math.floor((end - start) / (24 * 60 * 60 * 1000));
+}
+
+function evaluateRcSequence(releaseCandidateTags, baseVersion) {
+  const parsed = releaseCandidateTags
+    .map(parseRcTag)
+    .filter((entry) => entry && (!baseVersion || entry.baseVersion === baseVersion))
+    .sort((a, b) => a.rcNumber - b.rcNumber);
+  const rcNumbers = parsed.map((entry) => entry.rcNumber);
+  const consecutive = rcNumbers.every((number, index) => (
+    index === 0 || number === rcNumbers[index - 1] + 1
+  ));
+  return {
+    baseVersion,
+    releaseCandidateTags: parsed.map((entry) => entry.tag),
+    releaseCandidateCount: parsed.length,
+    rcNumbers,
+    consecutive,
+  };
+}
+
+function evaluateMigrationWindow({
+  releaseId,
+  compatibilityDeclaredAtUtc,
+  evaluatedAtUtc,
+  releaseCandidateTags,
+  minimumWindowDays = MINIMUM_WINDOW_DAYS,
+  minimumReleaseCandidates = MINIMUM_RELEASE_CANDIDATES,
+}) {
+  const releaseTag = releaseIdToTag(releaseId);
+  const releaseRc = parseRcTag(releaseTag);
+  const daysElapsed = daysBetweenUtc(compatibilityDeclaredAtUtc, evaluatedAtUtc);
+  const rcSequence = evaluateRcSequence(releaseCandidateTags, releaseRc.baseVersion);
+  const rcSatisfied = rcSequence.consecutive && rcSequence.releaseCandidateCount >= minimumReleaseCandidates;
+  const dayWindowSatisfied = daysElapsed >= minimumWindowDays;
+  const satisfied = rcSatisfied && dayWindowSatisfied;
+
+  return {
+    compatibilityDeclaredAtUtc,
+    evaluatedAtUtc,
+    minimumWindowDays,
+    minimumReleaseCandidates,
+    daysElapsed,
+    windowSatisfiedAtUtc: dayWindowSatisfied ? evaluatedAtUtc : null,
+    rcSequence,
+    satisfied,
+  };
+}
+
+function buildMigrationReadinessRecord({
+  releaseId,
+  sourceCommit,
+  compatibilityDeclaredAtUtc,
+  releaseCandidateTags,
+  generatedAtUtc = new Date().toISOString(),
+}) {
+  const releaseTag = releaseIdToTag(releaseId);
+  const compatibilityWindow = evaluateMigrationWindow({
+    releaseId,
+    compatibilityDeclaredAtUtc,
+    evaluatedAtUtc: generatedAtUtc,
+    releaseCandidateTags,
+  });
+  const record = {
+    schemaVersion: '1.0',
+    releaseId,
+    releaseTag,
+    sourceCommit,
+    generatedAtUtc,
+    evaluatedAt: generatedAtUtc,
+    migrationState: 'compatibility',
+    status: compatibilityWindow.satisfied ? 'eligible' : 'blocked',
+    finalizationEligible: compatibilityWindow.satisfied,
+    criteria: {
+      minimumWindowDays: compatibilityWindow.minimumWindowDays,
+      minimumReleaseCandidates: compatibilityWindow.minimumReleaseCandidates,
+      releaseCandidateCount: compatibilityWindow.rcSequence.releaseCandidateCount,
+      releaseCandidatesConsecutive: compatibilityWindow.rcSequence.consecutive,
+      daysElapsed: compatibilityWindow.daysElapsed,
+      satisfied: compatibilityWindow.satisfied,
+    },
+    evidenceRefs: DEFAULT_EVIDENCE_REFS,
+    approvals: [],
+    compatibilityWindow,
+    checks: {
+      immutableRecord: true,
+      contentHashAlgorithm: 'sha256-canonical-json-without-contentHash',
+    },
+  };
+  return attachContentHash(record);
+}
+
+function validateMigrationReadinessRecord(record) {
+  const errors = [];
+  if (record?.schemaVersion !== '1.0') errors.push('schemaVersion must be 1.0');
+  if (!RELEASE_ID_PATTERN.test(String(record?.releaseId || ''))) errors.push('releaseId must match X.Y.Z-rc.N');
+  if (record?.releaseTag !== `v${record?.releaseId}`) errors.push('releaseTag must equal v<releaseId>');
+  if (!record?.sourceCommit) errors.push('sourceCommit is required');
+  if (!UTC_TIMESTAMP_PATTERN.test(String(record?.evaluatedAt || ''))) errors.push('evaluatedAt must be a UTC ISO-8601 string ending in Z');
+  if (record?.migrationState !== 'compatibility') errors.push('migrationState must be compatibility');
+  if (!['eligible', 'blocked'].includes(record?.status)) errors.push('status must be eligible or blocked');
+  if (!Array.isArray(record?.evidenceRefs)) errors.push('evidenceRefs must be an array');
+  if (!Array.isArray(record?.approvals)) errors.push('approvals must be an array');
+  if (record?.contentHash !== computeContentHash(record || {})) errors.push('contentHash mismatch');
+  const window = record?.compatibilityWindow || {};
+  if (window.minimumWindowDays !== MINIMUM_WINDOW_DAYS) errors.push('minimumWindowDays must equal 30');
+  if (window.minimumReleaseCandidates !== MINIMUM_RELEASE_CANDIDATES) errors.push('minimumReleaseCandidates must equal 2');
+  if (!window.rcSequence?.consecutive) errors.push('release candidates must be consecutive');
+  if ((window.rcSequence?.releaseCandidateCount || 0) < MINIMUM_RELEASE_CANDIDATES) {
+    errors.push('releaseCandidateCount must meet minimumReleaseCandidates');
+  }
+  if ((window.daysElapsed || 0) < MINIMUM_WINDOW_DAYS) {
+    errors.push('daysElapsed must meet minimumWindowDays');
+  }
+  const expectedSatisfied = window.rcSequence?.consecutive === true
+    && (window.rcSequence?.releaseCandidateCount || 0) >= MINIMUM_RELEASE_CANDIDATES
+    && (window.daysElapsed || 0) >= MINIMUM_WINDOW_DAYS;
+  if (window.satisfied !== expectedSatisfied) {
+    errors.push('compatibilityWindow.satisfied does not match derived eligibility');
+  }
+  if (record?.status !== (expectedSatisfied ? 'eligible' : 'blocked')) {
+    errors.push('status does not match compatibilityWindow.satisfied');
+  }
+  if (record?.finalizationEligible !== expectedSatisfied) {
+    errors.push('finalizationEligible does not match compatibilityWindow.satisfied');
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+function validateLedgerAppendOnly(previousLedger, nextLedger) {
+  const previous = Array.isArray(previousLedger) ? previousLedger : [];
+  const next = Array.isArray(nextLedger) ? nextLedger : [];
+  if (next.length < previous.length) {
+    return { valid: false, errors: ['ledger cannot shrink'] };
+  }
+  for (let index = 0; index < previous.length; index += 1) {
+    if (canonicalize(previous[index]) !== canonicalize(next[index])) {
+      return { valid: false, errors: [`ledger entry changed at index ${index}`] };
+    }
+  }
+  return { valid: true, errors: [] };
+}
+
+module.exports = {
+  MINIMUM_RELEASE_CANDIDATES,
+  MINIMUM_WINDOW_DAYS,
+  DEFAULT_EVIDENCE_REFS,
+  attachContentHash,
+  buildMigrationReadinessRecord,
+  computeContentHash,
+  evaluateMigrationWindow,
+  parseRcTag,
+  releaseIdToTag,
+  validateLedgerAppendOnly,
+  validateMigrationReadinessRecord,
+};

package/src/migration/finalization-policy.js

@@ -0,0 +1,35 @@
+const REQUIRED_GATES = [
+  'dual_command_identity_available',
+  'compatibility_path_regression_passed',
+  'machine_command_coverage_manifest_valid',
+  'machine_envelope_conformance_passed',
+  'migration_evidence_hash_valid',
+  'append_only_ledger_valid',
+  'rollback_drill_passed',
+];
+
+function validateFinalizationPolicy(policy) {
+  const errors = [];
+  if (policy?.schemaVersion !== '1.0') errors.push('schemaVersion must be 1.0');
+  if (policy?.migrationState !== 'compatibility') errors.push('migrationState must be compatibility');
+  if (policy?.effectiveFromState !== 'compatibility') errors.push('effectiveFromState must be compatibility');
+  if (policy?.targetState !== 'finalized') errors.push('targetState must be finalized');
+  if (policy?.minimumWindow?.releaseCandidates !== 2) errors.push('minimumWindow.releaseCandidates must equal 2');
+  if (policy?.minimumWindow?.days !== 30) errors.push('minimumWindow.days must equal 30');
+  if (policy?.minimumWindow?.clock !== 'UTC') errors.push('minimumWindow.clock must be UTC');
+  const gates = Array.isArray(policy?.gatingCriteria) ? policy.gatingCriteria : [];
+  for (const gate of REQUIRED_GATES) {
+    if (!gates.includes(gate)) {
+      errors.push(`missing required gate: ${gate}`);
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+module.exports = {
+  REQUIRED_GATES,
+  validateFinalizationPolicy,
+};