sinapse-ai 9.3.0 → 9.5.0

package/.sinapse-ai/infrastructure/scripts/validate-manifest-parity.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+/**
+ * Validate Install Manifest Parity
+ *
+ * @script .sinapse-ai/infrastructure/scripts/validate-manifest-parity.js
+ * @story A.4 - Install Manifest Parity & Regeneration (epic-install-ux-hardening)
+ *
+ * Purpose:
+ *   Catches drift between the real repository and the two source-of-truth
+ *   files that track framework entities:
+ *     - .sinapse-ai/install-manifest.yaml
+ *     - .sinapse-ai/data/entity-registry.yaml
+ *
+ *   Unlike scripts/validate-manifest.js (which hashes every file in the
+ *   manifest), this script focuses on domain-level parity for the 4
+ *   domains most likely to drift silently:
+ *     - agents      → .sinapse-ai/development/agents/*.md       (top-level)
+ *     - tasks       → .sinapse-ai/development/tasks/*.md
+ *     - templates   → .sinapse-ai/development/templates/*.{md,yaml}
+ *     - checklists  → .sinapse-ai/development/checklists/*.md
+ *
+ *   It also cross-validates that entity-registry.yaml agrees with the
+ *   manifest and with reality on the number of agents and their names.
+ *
+ * Usage:
+ *   node .sinapse-ai/infrastructure/scripts/validate-manifest-parity.js
+ *   npm run validate:manifest:parity
+ *
+ * Options:
+ *   --json        Emit machine-readable JSON (for CI)
+ *   --root <dir>  Override the repo root (for tests)
+ *
+ * Exit codes:
+ *   0 - Parity OK
+ *   1 - Drift detected
+ *   2 - Script/internal error
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// Domains to check. Each entry describes one logical domain of entities
+// and how to find its real files on disk.
+const DOMAINS = [
+  {
+    name: 'agents',
+    dir: 'development/agents',
+    // Only top-level .md files count as "agents". Sub-folder MEMORY.md
+    // files belong to the agent's memory, not the agent roster.
+    recursive: false,
+    exts: ['.md'],
+    // Exclude internal files that live alongside agents but are not agents.
+    exclude: (name) => /^(README|CHANGELOG|INDEX|MEMORY)\.md$/i.test(name),
+  },
+  {
+    name: 'tasks',
+    dir: 'development/tasks',
+    recursive: false,
+    exts: ['.md'],
+    exclude: (name) => /^(README|CHANGELOG|INDEX)\.md$/i.test(name),
+  },
+  {
+    name: 'templates',
+    dir: 'development/templates',
+    recursive: false,
+    exts: ['.md', '.yaml', '.yml'],
+    exclude: (name) => /^README\.md$/i.test(name),
+  },
+  {
+    name: 'checklists',
+    dir: 'development/checklists',
+    recursive: false,
+    exts: ['.md'],
+    exclude: (name) => /^(README|INDEX)\.md$/i.test(name),
+  },
+];
+
+/**
+ * Find every file on disk that belongs to a given domain.
+ * @param {string} sinapseCoreDir - Path to `.sinapse-ai/`
+ * @param {object} domain - Domain descriptor from DOMAINS
+ * @returns {Set<string>} Set of POSIX-style relative paths (e.g.
+ *                        `development/agents/developer.md`)
+ */
+function scanDomain(sinapseCoreDir, domain) {
+  const domainDir = path.join(sinapseCoreDir, domain.dir);
+  const found = new Set();
+
+  if (!fs.existsSync(domainDir)) return found;
+
+  const entries = fs.readdirSync(domainDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) continue; // not recursing
+    if (!entry.isFile()) continue;
+    const ext = path.extname(entry.name).toLowerCase();
+    if (!domain.exts.includes(ext)) continue;
+    if (domain.exclude && domain.exclude(entry.name)) continue;
+    found.add(`${domain.dir}/${entry.name}`);
+  }
+  return found;
+}
+
+/**
+ * Collect every manifest entry whose path matches a given domain directory.
+ * @param {Array<{path:string}>} manifestFiles
+ * @param {object} domain
+ * @returns {Set<string>}
+ */
+function collectManifestEntries(manifestFiles, domain) {
+  const set = new Set();
+  const prefix = `${domain.dir}/`;
+  for (const entry of manifestFiles) {
+    const p = String(entry.path || '').replace(/\\/g, '/');
+    if (!p.startsWith(prefix)) continue;
+    // Only keep top-level (same depth filter as scanDomain) unless
+    // the domain is configured as recursive.
+    const rest = p.slice(prefix.length);
+    if (!domain.recursive && rest.includes('/')) continue;
+    const ext = path.extname(rest).toLowerCase();
+    if (!domain.exts.includes(ext)) continue;
+    if (domain.exclude && domain.exclude(path.basename(rest))) continue;
+    set.add(p);
+  }
+  return set;
+}
+
+/**
+ * Diff two sets, returning extras and missings relative to disk.
+ * @param {Set<string>} onDisk
+ * @param {Set<string>} inManifest
+ * @returns {{missingFromManifest:string[], missingFromDisk:string[]}}
+ */
+function diffSets(onDisk, inManifest) {
+  const missingFromManifest = [];
+  const missingFromDisk = [];
+  for (const p of onDisk) {
+    if (!inManifest.has(p)) missingFromManifest.push(p);
+  }
+  for (const p of inManifest) {
+    if (!onDisk.has(p)) missingFromDisk.push(p);
+  }
+  missingFromManifest.sort();
+  missingFromDisk.sort();
+  return { missingFromManifest, missingFromDisk };
+}
+
+/**
+ * Load a YAML file, returning null if it does not exist.
+ */
+function loadYaml(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return yaml.load(raw);
+}
+
+/**
+ * Extract the set of top-level agent names from entity-registry.yaml.
+ * Registry shape: entities.agents.{agentName}: { ... }
+ * @returns {Set<string>}
+ */
+function getRegistryAgentNames(registry) {
+  const names = new Set();
+  const agents = registry && registry.entities && registry.entities.agents;
+  if (!agents || typeof agents !== 'object') return names;
+  for (const key of Object.keys(agents)) names.add(key);
+  return names;
+}
+
+/**
+ * Run the full parity check.
+ * @param {string} repoRoot - Repo root directory
+ * @returns {object} report
+ */
+function runParityCheck(repoRoot) {
+  const sinapseCoreDir = path.join(repoRoot, '.sinapse-ai');
+  const manifestPath = path.join(sinapseCoreDir, 'install-manifest.yaml');
+  const registryPath = path.join(sinapseCoreDir, 'data', 'entity-registry.yaml');
+
+  const report = {
+    ok: true,
+    errors: [],
+    domains: {},
+    registry: {
+      checked: false,
+      agentCountManifest: 0,
+      agentCountRegistry: 0,
+      agentCountDisk: 0,
+      extraInRegistry: [],
+      missingInRegistry: [],
+    },
+  };
+
+  const manifest = loadYaml(manifestPath);
+  if (!manifest) {
+    report.ok = false;
+    report.errors.push(`install-manifest.yaml not found at ${manifestPath}`);
+    return report;
+  }
+  if (!Array.isArray(manifest.files)) {
+    report.ok = false;
+    report.errors.push('install-manifest.yaml has no `files` array');
+    return report;
+  }
+
+  for (const domain of DOMAINS) {
+    const onDisk = scanDomain(sinapseCoreDir, domain);
+    const inManifest = collectManifestEntries(manifest.files, domain);
+    const { missingFromManifest, missingFromDisk } = diffSets(onDisk, inManifest);
+
+    const domainOk = missingFromManifest.length === 0 && missingFromDisk.length === 0;
+    if (!domainOk) report.ok = false;
+
+    report.domains[domain.name] = {
+      ok: domainOk,
+      dir: domain.dir,
+      diskCount: onDisk.size,
+      manifestCount: inManifest.size,
+      missingFromManifest,
+      missingFromDisk,
+    };
+  }
+
+  // Cross-validate entity-registry.yaml against manifest + disk for agents.
+  const registry = loadYaml(registryPath);
+  if (!registry) {
+    report.ok = false;
+    report.errors.push(`entity-registry.yaml not found at ${registryPath}`);
+  } else {
+    report.registry.checked = true;
+    const agentsDomain = report.domains.agents;
+    const diskAgentNames = new Set(
+      Array.from(scanDomain(sinapseCoreDir, DOMAINS[0])).map((p) =>
+        path.basename(p, '.md'),
+      ),
+    );
+    const registryAgentNames = getRegistryAgentNames(registry);
+    report.registry.agentCountDisk = diskAgentNames.size;
+    report.registry.agentCountManifest = agentsDomain ? agentsDomain.manifestCount : 0;
+    report.registry.agentCountRegistry = registryAgentNames.size;
+
+    // Registry should mention exactly the same agent names as disk.
+    for (const name of registryAgentNames) {
+      if (!diskAgentNames.has(name)) report.registry.extraInRegistry.push(name);
+    }
+    for (const name of diskAgentNames) {
+      if (!registryAgentNames.has(name)) report.registry.missingInRegistry.push(name);
+    }
+    report.registry.extraInRegistry.sort();
+    report.registry.missingInRegistry.sort();
+
+    if (
+      report.registry.extraInRegistry.length > 0 ||
+      report.registry.missingInRegistry.length > 0 ||
+      report.registry.agentCountRegistry !== report.registry.agentCountDisk
+    ) {
+      report.ok = false;
+    }
+  }
+
+  return report;
+}
+
+/**
+ * Render a human-readable report.
+ */
+function printReport(report) {
+  const line = '='.repeat(60);
+  console.log(line);
+  console.log('SINAPSE Install Manifest Parity Report');
+  console.log(line);
+
+  if (report.errors.length > 0) {
+    console.log('');
+    console.log('ERRORS:');
+    for (const err of report.errors) console.log(`  - ${err}`);
+  }
+
+  console.log('');
+  console.log('Domains:');
+  for (const [name, info] of Object.entries(report.domains)) {
+    const status = info.ok ? 'OK' : 'DRIFT';
+    console.log(
+      `  ${name.padEnd(11)} ${status.padEnd(6)} disk=${info.diskCount} manifest=${info.manifestCount}`,
+    );
+    if (info.missingFromManifest.length > 0) {
+      console.log(`    Missing from manifest (${info.missingFromManifest.length}):`);
+      for (const p of info.missingFromManifest.slice(0, 20)) console.log(`      + ${p}`);
+      if (info.missingFromManifest.length > 20) {
+        console.log(`      ... and ${info.missingFromManifest.length - 20} more`);
+      }
+    }
+    if (info.missingFromDisk.length > 0) {
+      console.log(`    In manifest but missing on disk (${info.missingFromDisk.length}):`);
+      for (const p of info.missingFromDisk.slice(0, 20)) console.log(`      - ${p}`);
+      if (info.missingFromDisk.length > 20) {
+        console.log(`      ... and ${info.missingFromDisk.length - 20} more`);
+      }
+    }
+  }
+
+  if (report.registry.checked) {
+    const r = report.registry;
+    const status =
+      r.extraInRegistry.length === 0 &&
+      r.missingInRegistry.length === 0 &&
+      r.agentCountDisk === r.agentCountRegistry
+        ? 'OK'
+        : 'DRIFT';
+    console.log('');
+    console.log(`Entity Registry cross-check: ${status}`);
+    console.log(
+      `  agents: disk=${r.agentCountDisk} manifest=${r.agentCountManifest} registry=${r.agentCountRegistry}`,
+    );
+    if (r.extraInRegistry.length > 0) {
+      console.log(`  Extra in registry (${r.extraInRegistry.length}):`);
+      for (const n of r.extraInRegistry) console.log(`      ! ${n}`);
+    }
+    if (r.missingInRegistry.length > 0) {
+      console.log(`  Missing from registry (${r.missingInRegistry.length}):`);
+      for (const n of r.missingInRegistry) console.log(`      ? ${n}`);
+    }
+  }
+
+  console.log('');
+  console.log('-'.repeat(60));
+  if (report.ok) {
+    console.log('PARITY OK — manifest, disk, and registry agree.');
+  } else {
+    console.log('PARITY DRIFT — fix with:');
+    console.log('  1. npm run generate:manifest');
+    console.log('  2. review entity-registry.yaml agents section');
+    console.log('  3. rerun npm run validate:manifest:parity');
+  }
+  console.log('-'.repeat(60));
+}
+
+function parseArgs(argv) {
+  const opts = { json: false, root: process.cwd() };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') opts.json = true;
+    else if (a === '--root' && argv[i + 1]) {
+      opts.root = argv[++i];
+    }
+  }
+  return opts;
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  try {
+    const report = runParityCheck(opts.root);
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    } else {
+      printReport(report);
+    }
+    process.exit(report.ok ? 0 : 1);
+  } catch (err) {
+    console.error('validate-manifest-parity: internal error:', err && err.message);
+    if (process.env.DEBUG) console.error(err && err.stack);
+    process.exit(2);
+  }
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = {
+  runParityCheck,
+  scanDomain,
+  collectManifestEntries,
+  diffSets,
+  getRegistryAgentNames,
+  DOMAINS,
+};

package/.sinapse-ai/infrastructure/scripts/validate-parity.js

@@ -20,34 +20,71 @@ function parseArgs(argv = process.argv.slice(2)) {
   return {
     quiet: args.has('--quiet') || args.has('-q'),
     json: args.has('--json'),
+    fast: args.has('--fast'),
     contractPath: contractArg ? contractArg.slice('--contract='.length) : null,
     diffPath: diffArg ? diffArg.slice('--diff='.length) : null,
   };
 }
 
+function extractSyncFailureDetails(rawOutput) {
+  if (!rawOutput || typeof rawOutput !== 'string') {
+    return [];
+  }
+  const details = [];
+  const driftMatch = rawOutput.match(/\|\s*Drift\s*\|\s*(\d+)\s*\|/i);
+  const missingMatch = rawOutput.match(/\|\s*Missing\s*\|\s*(\d+)\s*\|/i);
+  const orphanedMatch = rawOutput.match(/\|\s*Orphaned\s*\|\s*(\d+)\s*\|/i);
+  if (driftMatch && Number(driftMatch[1]) > 0) {
+    details.push(`${driftMatch[1]} file(s) drifted from source-of-truth`);
+  }
+  if (missingMatch && Number(missingMatch[1]) > 0) {
+    details.push(`${missingMatch[1]} file(s) missing from IDE mirror`);
+  }
+  if (orphanedMatch && Number(orphanedMatch[1]) > 0) {
+    details.push(`${orphanedMatch[1]} orphaned file(s) in IDE mirror`);
+  }
+  const fileBlocks = rawOutput.match(/(?:^|\n)-\s+`?([^`\n]+\.md)`?/g);
+  if (fileBlocks) {
+    for (const block of fileBlocks.slice(0, 5)) {
+      const name = block.replace(/^[\s\-`]+|`+\s*$/g, '');
+      if (name) details.push(`  - ${name}`);
+    }
+  }
+  return details;
+}
+
 function runSyncValidate(ide, projectRoot) {
   const script = path.join('.sinapse-ai', 'infrastructure', 'scripts', 'ide-sync', 'index.js');
   const result = spawnSync('node', [script, 'validate', '--ide', ide, '--strict'], {
     cwd: projectRoot,
     encoding: 'utf8',
   });
-  return {
-    ok: result.status === 0,
-    errors: result.status === 0 ? [] : [`Sync validation failed for ${ide}`],
-    warnings: [],
-    raw: result.stdout || result.stderr || '',
-  };
+  const raw = result.stdout || result.stderr || '';
+  if (result.status === 0) {
+    return { ok: true, errors: [], warnings: [], raw };
+  }
+  const details = extractSyncFailureDetails(raw);
+  const errors = [
+    `Sync validation failed for ${ide}`,
+    ...details,
+    `Run \`npm run sync:ide\` then re-stage the .claude/ and .codex/ changes`,
+  ];
+  return { ok: false, errors, warnings: [], raw };
 }
 
 function getDefaultContractPath(projectRoot = process.cwd()) {
-  return path.join(
+  const contractsDir = path.join(
     projectRoot,
     '.sinapse-ai',
     'infrastructure',
     'contracts',
     'compatibility',
-    'sinapse-4.0.4.yaml',
   );
+  const currentPath = path.join(contractsDir, 'sinapse-current.yaml');
+  if (fs.existsSync(currentPath)) {
+    return currentPath;
+  }
+  return path.join(contractsDir, 'sinapse-4.0.4.yaml');
 }
 
 function loadCompatibilityContract(contractPath) {
@@ -218,6 +255,7 @@ function diffCompatibilityContracts(currentContract, previousContract) {
 
 function runParityValidation(options = {}, deps = {}) {
   const projectRoot = options.projectRoot || process.cwd();
+  const fast = Boolean(options.fast);
   const runSync = deps.runSyncValidate || runSyncValidate;
   const runCodexSync = deps.validateCodexSync || validateCodexSync;
   const runClaudeIntegration = deps.validateClaudeIntegration || validateClaudeIntegration;
@@ -228,12 +266,12 @@ function runParityValidation(options = {}, deps = {}) {
     ? path.resolve(projectRoot, options.contractPath)
     : getDefaultContractPath(projectRoot);
   const loadContract = deps.loadCompatibilityContract || loadCompatibilityContract;
-  const contract = loadContract(resolvedContractPath);
+  const contract = fast ? null : loadContract(resolvedContractPath);
   const resolvedDiffPath = options.diffPath ? path.resolve(projectRoot, options.diffPath) : null;
-  const previousContract = resolvedDiffPath ? loadContract(resolvedDiffPath) : null;
+  const previousContract = resolvedDiffPath && !fast ? loadContract(resolvedDiffPath) : null;
   const docsPath = path.join(projectRoot, 'docs', 'ide-integration.md');
   const docsPathRelative = path.relative(projectRoot, docsPath);
-  const checks = [
+  const fullChecks = [
     { id: 'claude-sync', exec: () => runSync('claude-code', projectRoot) },
     { id: 'claude-integration', exec: () => runClaudeIntegration({ projectRoot }) },
     { id: 'codex-sync', exec: () => runCodexSync({ projectRoot, quiet: true }) },
@@ -241,31 +279,42 @@ function runParityValidation(options = {}, deps = {}) {
     { id: 'codex-skills', exec: () => runCodexSkills({ projectRoot, strict: true, quiet: true }) },
     { id: 'paths', exec: () => runPaths({ projectRoot }) },
   ];
+  const fastChecks = [
+    { id: 'claude-sync', exec: () => runSync('claude-code', projectRoot) },
+    { id: 'codex-sync', exec: () => runCodexSync({ projectRoot, quiet: true }) },
+    { id: 'paths', exec: () => runPaths({ projectRoot }) },
+  ];
+  const checks = fast ? fastChecks : fullChecks;
 
   const results = checks.map((check) => {
     const normalized = normalizeResult(check.exec());
     return { id: check.id, ...normalized };
   });
   const resultById = Object.fromEntries(results.map((r) => [r.id, r]));
-  const contractViolations = validateCompatibilityContract(contract, resultById, {
-    docsPath,
-    docsPathRelative,
-  });
-  const contractSummary = contract
-    ? {
-        release: contract.release || null,
-        path: path.relative(projectRoot, resolvedContractPath),
-      }
-    : {
-        release: null,
-        path: path.relative(projectRoot, resolvedContractPath),
-      };
+  const contractViolations = fast
+    ? []
+    : validateCompatibilityContract(contract, resultById, {
+        docsPath,
+        docsPathRelative,
+      });
+  const contractSummary = fast
+    ? null
+    : contract
+      ? {
+          release: contract.release || null,
+          path: path.relative(projectRoot, resolvedContractPath),
+        }
+      : {
+          release: null,
+          path: path.relative(projectRoot, resolvedContractPath),
+        };
 
   return {
     ok: results.every((r) => r.ok) && contractViolations.length === 0,
+    fast,
     checks: results,
     contract: contractSummary,
-    contractDiff: diffCompatibilityContracts(contract, previousContract),
+    contractDiff: fast ? null : diffCompatibilityContracts(contract, previousContract),
     contractViolations,
   };
 }
@@ -347,4 +396,6 @@ module.exports = {
   normalizeResult,
   formatHumanReport,
   diffCompatibilityContracts,
+  getDefaultContractPath,
+  extractSyncFailureDetails,
 };