06-impact-analysis-synchronizer.mjs

#!/usr/bin/env node
/**
 * Evolith Core Impact Analysis & Synchronization Agent
 *
 * Mandatory mechanism that executes after relevant changes in Evolith Core.
 * Detects, analyzes, and synchronizes: ADRs, documentation, rules, standards,
 * architecture, harness, agents, and rulesets.
 *
 * Usage:
 *   node .harness/scripts/impact-analysis-synchronizer.mjs [options]
 *
 * Options:
 *   --staged       Analyze staged changes only (pre-commit hook default)
 *   --working-tree Analyze working tree changes (uncommitted)
 *   --all          Analyze all changes since last commit
 *   --dry-run      Report only, no changes applied
 *   --verbose      Detailed output
 *   --report       Generate report to .harness/reports/
 *
 * Idempotent: running with same inputs produces no changes.
 * Incremental: only affected components are touched.
 */

import fs from "node:fs";
import path from "node:path";
import { execSync } from "node:child_process";
import crypto from "node:crypto";

// GT-556: root came from process.cwd(), so every glob and every git invocation below
// silently re-scoped itself to wherever the script happened to be launched from.
// The `reference/navigation/**` patterns were also dead — navigation now lives at the
// repo-root MASTER_INDEX.md plus reference/core/control-center/taxonomy.
import { REPO_ROOT } from '../lib/paths.mjs';

const root = REPO_ROOT;

// ============================================================================
// CHANGE CATEGORY DEFINITIONS
// ============================================================================

const CHANGE_CATEGORIES = {
  ADR: {
    patterns: [
      /\/adrs\/core\/ADR-\d+\.md$/i,
      /\/adrs\/nodejs\/ADR-\d+\.md$/i,
      /\/adrs\/dotnet\/ADR-\d+\.md$/i,
      /\/adrs\/android\/ADR-\d+\.md$/i,
      /\/adrs\/.*\.es\.md$/i,
    ],
    impactZones: ["adrs", "rulesets", "documentation", "navigation", "harness"],
    severity: { create: "high", modify: "high", delete: "critical", rename: "medium" }
  },
  DOCS: {
    patterns: [
      /\/reference\/.*\.md$/i,
      /\/reference\/.*\.es\.md$/i,
    ],
    excludePatterns: [
      /\/adrs\//,
      /\/blueprints\//,
    ],
    impactZones: ["documentation", "navigation", "bilingual"],
    severity: { create: "medium", modify: "low", delete: "medium", rename: "low" }
  },
  RULES: {
    patterns: [
      /\/reference\/governance\/standards\/.*\.md$/i,
      /\/rulesets\/.*\.rules\.json$/i,
      /\/rulesets\/.*\.schema\.json$/i,
    ],
    impactZones: ["rulesets", "harness", "documentation", "adrs"],
    severity: { create: "high", modify: "high", delete: "critical", rename: "medium" }
  },
  ARCH: {
    patterns: [
      /\/reference\/architecture\/blueprints\/.*\.md$/i,
      /\/reference\/architecture\/canonical-patterns\/.*\.md$/i,
    ],
    impactZones: ["adrs", "rulesets", "documentation", "templates"],
    severity: { create: "high", modify: "medium", delete: "high", rename: "medium" }
  },
  HARNESS: {
    patterns: [
      /\.harness\/.*\.mjs$/i,
      /\.harness\/.*\.md$/i,
      /\.harness\/.*\.json$/i,
      /\.husky\/.*$/i,
    ],
    impactZones: ["harness", "rulesets", "validators"],
    severity: { create: "high", modify: "high", delete: "critical", rename: "high" }
  },
  SCHEMA: {
    patterns: [
      /rulesets\/schema\/.*\.json$/i,
      /\.harness\/schemas\/.*\.json$/i,
    ],
    impactZones: ["rulesets", "validators", "harness"],
    severity: { create: "critical", modify: "critical", delete: "critical", rename: "high" }
  },
  TEMPLATE: {
    patterns: [
      /\/sdlc\/04-artifact-templates\/.*\.md$/i,
      /\/sdlc\/04-artifact-templates\/.*\.es\.md$/i,
    ],
    impactZones: ["templates", "documentation", "navigation"],
    severity: { create: "high", modify: "medium", delete: "high", rename: "medium" }
  },
  NAVIGATION: {
    patterns: [
      /\/navigation\/MASTER_INDEX\.md$/i,
      /\/navigation\/.*README\.md$/i,
      /\/MASTER_INDEX\.md$/i,
      /\/README\.md$/i,
      /\/README\.es\.md$/i,
    ],
    impactZones: ["navigation", "documentation"],
    severity: { create: "low", modify: "low", delete: "medium", rename: "low" }
  }
};

// ============================================================================
// IMPACT ZONE DEPENDENCY MAP
// ============================================================================

const IMPACT_DEPENDENCIES = {
  adrs: {
    affectedBy: ["ADR", "ARCH", "RULES"],
    syncActions: ["index_update", "cross_ref_sync", "bilingual_sync"]
  },
  rulesets: {
    affectedBy: ["RULES", "SCHEMA", "HARNESS", "ADR"],
    syncActions: ["schema_update", "rule_propagation", "index_update"]
  },
  documentation: {
    affectedBy: ["DOCS", "ADR", "ARCH", "RULES", "TEMPLATE"],
    syncActions: ["bilingual_sync", "cross_ref_sync", "navigation_sync"]
  },
  navigation: {
    affectedBy: ["DOCS", "ADR", "ARCH", "RULES", "HARNESS", "NAVIGATION", "TEMPLATE"],
    syncActions: ["navigation_sync", "index_update"]
  },
  harness: {
    affectedBy: ["HARNESS", "RULES", "SCHEMA"],
    syncActions: ["validation", "rule_propagation"]
  },
  templates: {
    affectedBy: ["TEMPLATE", "SCHEMA", "ADR"],
    syncActions: ["template_validation", "bilingual_sync"]
  },
  validators: {
    affectedBy: ["SCHEMA", "RULES", "HARNESS"],
    syncActions: ["schema_update", "rule_propagation"]
  },
  bilingual: {
    affectedBy: ["DOCS", "ADR", "TEMPLATE", "NAVIGATION"],
    syncActions: ["bilingual_sync", "index_update"]
  }
};

// ============================================================================
// IMPACT ZONE TO FILE PATTERNS
// ============================================================================

const IMPACT_ZONE_FILES = {
  adrs: [
    "reference/core/architecture/adrs/*/README.md",
    "reference/core/architecture/adrs/*/README.es.md",
    "reference/core/architecture/adrs/adr-matrix.md",
    "reference/core/architecture/adrs/adr-matrix.es.md",
  ],
  rulesets: [
    "src/rulesets/**/*.md",
    "src/rulesets/**/*.json",
  ],
  documentation: [
    "reference/**/*.md",
    "reference/**/*.es.md",
  ],
  navigation: [
    "reference/core/control-center/taxonomy/**/*.md",
    "MASTER_INDEX.md",
    "MASTER_INDEX.es.md",
    "README.md",
    "README.es.md",
  ],
  harness: [
    ".harness/scripts/*.mjs",
    ".harness/**/*.md",
    ".harness/**/*.json",
    ".harness/**/*.es.md",
  ],
  templates: [
    "reference/core/sdlc/04-artifact-templates/*.md",
    "reference/core/sdlc/04-artifact-templates/*.es.md",
  ],
  validators: [
    ".harness/scripts/validate-docs.mjs",
    ".harness/scripts/check-bilingual-parity.mjs",
    ".harness/scripts/bilingual-coverage.mjs",
  ]
};

// ============================================================================
// SYNCHRONIZATION RULES
// ============================================================================

const SYNC_RULES = {
  adrs: {
    onCreate: (change, ctx) => {
      const syncs = [];
      const adrDir = path.dirname(change.file);
      const isSpanish = change.file.endsWith(".es.md");
      const baseFile = isSpanish
        ? change.file.replace(".es.md", ".md")
        : change.file;

      // Update ADR index
      const indexFile = path.join(adrDir, "README.md");
      if (fs.existsSync(indexFile)) {
        syncs.push({
          type: "index_update",
          target: indexFile,
          action: "updated",
          changeSource: change.file,
          details: `Added ${path.basename(change.file)} to index`
        });
      }

      // Update bilingual index if Spanish
      if (isSpanish) {
        syncs.push({
          type: "bilingual_sync",
          target: baseFile,
          action: "validated",
          changeSource: change.file,
          details: "Spanish version created - EN version validated"
        });
      }

      // Check for ADR number in filename
      const adrMatch = change.file.match(/(\d+)[-\w]*\.md$/);
      if (adrMatch && ctx.adrMatrix) {
        syncs.push({
          type: "cross_ref_sync",
          target: "reference/core/architecture/adrs/adr-matrix.md",
          action: "updated",
          changeSource: change.file,
          details: `ADR-${adrMatch[1]} registered in decision matrix`
        });
      }

      return syncs;
    },
    onModify: (change, ctx) => {
      const syncs = [];
      const isSpanish = change.file.endsWith(".es.md");

      // Validate bilingual parity
      const counterpart = isSpanish
        ? change.file.replace(".es.md", ".md")
        : change.file.replace(".md", ".es.md");

      if (fs.existsSync(counterpart)) {
        syncs.push({
          type: "bilingual_sync",
          target: counterpart,
          action: "validated",
          changeSource: change.file,
          details: "Bilingual counterpart exists and is valid"
        });
      }

      return syncs;
    },
    onDelete: (change, ctx) => {
      const syncs = [];
      const isSpanish = change.file.endsWith(".es.md");
      const counterpart = isSpanish
        ? change.file.replace(".es.md", ".md")
        : change.file.replace(".md", ".es.md");

      if (fs.existsSync(counterpart)) {
        syncs.push({
          type: "bilingual_sync",
          target: counterpart,
          action: "requires_manual",
          changeSource: change.file,
          details: `Counterpart ${counterpart} exists - manual review required before deletion`
        });
      }

      return syncs;
    }
  },
  rulesets: {
    onCreate: (change, ctx) => {
      const syncs = [];
      const isJson = change.file.endsWith(".json");

      if (isJson) {
        // Validate JSON schema syntax
        try {
          const content = fs.readFileSync(path.join(root, change.file), "utf8");
          JSON.parse(content);
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "validated",
            changeSource: change.file,
            details: "JSON schema syntax validated"
          });
        } catch (e) {
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "failed",
            changeSource: change.file,
            details: `JSON parse error: ${e.message}`
          });
        }
      }

      // Update ruleset index
      const rulesetDir = path.dirname(change.file);
      const indexFile = path.join(rulesetDir, "README.md");
      if (fs.existsSync(indexFile)) {
        syncs.push({
          type: "index_update",
          target: indexFile,
          action: "updated",
          changeSource: change.file,
          details: `Added ${path.basename(change.file)} to ruleset index`
        });
      }

      return syncs;
    },
    onModify: (change, ctx) => {
      const syncs = [];

      if (change.file.endsWith(".rules.json")) {
        // Validate rules JSON structure
        try {
          const content = fs.readFileSync(path.join(root, change.file), "utf8");
          const rules = JSON.parse(content);
          if (!rules.rules || !Array.isArray(rules.rules)) {
            throw new Error("Missing 'rules' array in rules file");
          }
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "validated",
            changeSource: change.file,
            details: `Rules file validated: ${rules.rules.length} rules`
          });
        } catch (e) {
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "failed",
            changeSource: change.file,
            details: `Rules validation error: ${e.message}`
          });
        }
      }

      return syncs;
    }
  },
  harness: {
    onCreate: (change, ctx) => {
      const syncs = [];

      // Validate JSON files
      if (change.file.endsWith(".json")) {
        try {
          const content = fs.readFileSync(path.join(root, change.file), "utf8");
          const parsed = JSON.parse(content);

          // Validate schema structure if it looks like a schema
          if (parsed.$schema || parsed.title || parsed.type) {
            syncs.push({
              type: "schema_update",
              target: change.file,
              action: "validated",
              changeSource: change.file,
              details: `Schema validated: ${parsed.title || "untitled"}`
            });
          } else {
            syncs.push({
              type: "schema_update",
              target: change.file,
              action: "validated",
              changeSource: change.file,
              details: "JSON file syntax validated"
            });
          }
        } catch (e) {
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "failed",
            changeSource: change.file,
            details: `JSON parse error: ${e.message}`
          });
        }
      }

      // Validate MJS files for basic syntax
      if (change.file.endsWith(".mjs")) {
        try {
          const content = fs.readFileSync(path.join(root, change.file), "utf8");
          // Basic syntax check - look for common issues
          const importCount = (content.match(/^import\s/gm) || []).length;
          const exportCount = (content.match(/^export\s/gm) || []).length;
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "validated",
            changeSource: change.file,
            details: `Module validated: ${importCount} imports, ${exportCount} exports`
          });
        } catch (e) {
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "failed",
            changeSource: change.file,
            details: `File read error: ${e.message}`
          });
        }
      }

      // Update harness index if exists
      if (change.file.includes("/scripts/") && !change.file.endsWith(".md")) {
        syncs.push({
          type: "index_update",
          target: ".harness/scripts",
          action: "updated",
          changeSource: change.file,
          details: `New script registered: ${path.basename(change.file)}`
        });
      }

      return syncs;
    },
    onModify: (change, ctx) => {
      const syncs = [];

      if (change.file.endsWith(".json")) {
        try {
          const content = fs.readFileSync(path.join(root, change.file), "utf8");
          JSON.parse(content);
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "validated",
            changeSource: change.file,
            details: "JSON file validated after modification"
          });
        } catch (e) {
          syncs.push({
            type: "schema_update",
            target: change.file,
            action: "failed",
            changeSource: change.file,
            details: `JSON parse error: ${e.message}`
          });
        }
      }

      // If modifying pre-commit hook, validate it
      if (change.file.includes("pre-commit")) {
        syncs.push({
          type: "schema_update",
          target: change.file,
          action: "validated",
          changeSource: change.file,
          details: "Pre-commit hook validated"
        });
      }

      return syncs;
    }
  },
  documentation: {
    onCreate: (change, ctx) => {
      const syncs = [];
      const isSpanish = change.file.endsWith(".es.md");

      // Check bilingual counterpart
      const counterpart = isSpanish
        ? change.file.replace(".es.md", ".md")
        : change.file.replace(".md", ".es.md");

      const counterpartExists = fs.existsSync(path.join(root, counterpart));

      if (!isSpanish && !counterpartExists) {
        syncs.push({
          type: "bilingual_sync",
          target: counterpart,
          action: "skipped",
          changeSource: change.file,
          details: "ES counterpart not required yet - coverage will track"
        });
      } else if (isSpanish && !counterpartExists) {
        syncs.push({
          type: "bilingual_sync",
          target: change.file,
          action: "failed",
          changeSource: counterpart,
          details: "EN counterpart missing for Spanish file"
        });
      } else {
        syncs.push({
          type: "bilingual_sync",
          target: counterpart,
          action: "validated",
          changeSource: change.file,
          details: "Bilingual counterpart validated"
        });
      }

      // Update navigation if in navigation directory
      if (change.file.includes("/taxonomy/") || change.file === "MASTER_INDEX.md") {
        syncs.push({
          type: "navigation_sync",
          target: "MASTER_INDEX.md",
          action: "updated",
          changeSource: change.file,
          details: "MASTER_INDEX refreshed for navigation changes"
        });
      }

      return syncs;
    },
    onModify: (change, ctx) => {
      const syncs = [];
      const isSpanish = change.file.endsWith(".es.md");
      const counterpart = isSpanish
        ? change.file.replace(".es.md", ".md")
        : change.file.replace(".md", ".es.md");

      if (fs.existsSync(path.join(root, counterpart))) {
        syncs.push({
          type: "bilingual_sync",
          target: counterpart,
          action: "validated",
          changeSource: change.file,
          details: "Bilingual counterpart validated after modification"
        });
      }

      return syncs;
    }
  },
  navigation: {
    onCreate: (change, ctx) => {
      return [{
        type: "navigation_sync",
        target: change.file,
        action: "updated",
        changeSource: change.file,
        details: "Navigation file registered"
      }];
    },
    onModify: (change, ctx) => {
      // Validate navigation links
      const syncs = [];
      const content = fs.readFileSync(path.join(root, change.file), "utf8");
      const linkPattern = /\.\.\/[^)\s]+/g;
      const links = content.match(linkPattern) || [];

      for (const link of links) {
        const resolved = path.resolve(path.dirname(change.file), link);
        const rel = path.relative(root, resolved);
        if (!fs.existsSync(rel)) {
          syncs.push({
            type: "navigation_sync",
            target: change.file,
            action: "failed",
            changeSource: change.file,
            details: `Broken link detected: ${link} → ${rel}`
          });
        }
      }

      if (syncs.length === 0) {
        syncs.push({
          type: "navigation_sync",
          target: change.file,
          action: "validated",
          changeSource: change.file,
          details: `Navigation file validated: ${links.length} links checked`
        });
      }

      return syncs;
    }
  }
};

// ============================================================================
// CORE FUNCTIONS
// ============================================================================

function generateAnalysisId() {
  return crypto.randomUUID();
}

function getTimestamp() {
  return new Date().toISOString();
}

function getChangedFiles(scope = "staged") {
  try {
    let files = new Set();

    if (scope === "staged" || scope === "all") {
      // Staged changes
      const stagedOutput = execSync("git diff --staged --name-only --diff-filter=AMD", {
        encoding: "utf8",
        cwd: root
      });
      for (const f of stagedOutput.split("\n")) {
        if (f.trim()) files.add(f.trim());
      }

      // Staged new files (added)
      const stagedNewOutput = execSync("git diff --staged --name-only --diff-filter=A", {
        encoding: "utf8",
        cwd: root
      });
      for (const f of stagedNewOutput.split("\n")) {
        if (f.trim()) files.add(f.trim());
      }
    }

    if (scope === "working-tree" || scope === "all") {
      // Modified tracked files (not staged)
      const modifiedOutput = execSync("git diff --name-only --diff-filter=AMD", {
        encoding: "utf8",
        cwd: root
      });
      for (const f of modifiedOutput.split("\n")) {
        if (f.trim()) files.add(f.trim());
      }

      // Untracked new files
      const untrackedOutput = execSync("git ls-files --others --exclude-standard", {
        encoding: "utf8",
        cwd: root
      });
      for (const f of untrackedOutput.split("\n")) {
        if (f.trim() && !f.includes("node_modules") && !f.includes(".git")) {
          files.add(f.trim());
        }
      }
    }

    return [...files];
  } catch (e) {
    console.warn(`Warning: Could not get git diff: ${e.message}`);
    return [];
  }
}

function classifyChange(file) {
  for (const [category, config] of Object.entries(CHANGE_CATEGORIES)) {
    if (config.excludePatterns) {
      const shouldExclude = config.excludePatterns.some(p => p.test(file));
      if (shouldExclude) continue;
    }

    if (config.patterns.some(p => p.test(file))) {
      return category;
    }
  }
  return null;
}

function getChangeType(file, scope) {
  try {
    let cmd;
    switch (scope) {
      case "staged":
        cmd = `git diff --staged --name-status "${file}"`;
        break;
      case "working-tree":
        // Check staged first, then unstaged
        cmd = `git diff --staged --name-status "${file}" 2>/dev/null || git diff --name-status "${file}"`;
        break;
      case "all":
        cmd = `git diff --name-status HEAD -- "${file}"`;
        break;
      default:
        cmd = `git diff --staged --name-status "${file}"`;
    }

    const output = execSync(cmd, { encoding: "utf8", cwd: root });
    const status = output.trim()[0] || "?";
    const typeMap = { A: "create", M: "modify", D: "delete", R: "rename", "?": "create" };
    return typeMap[status] || "create";
  } catch {
    // Untracked or new file - check if it exists on disk
    const fullPath = path.join(root, file);
    if (fs.existsSync(fullPath)) {
      return "create";  // New untracked file exists on disk
    }
    return "modify";
  }
}

function buildImpactMap(changes) {
  const impactMap = {
    harness: [],
    agents: [],
    rulesets: [],
    adrs: [],
    documentation: [],
    templates: [],
    validators: [],
    navigation: [],
    bilingual: []
  };

  for (const change of changes) {
    const category = change.category;
    if (!category) continue;

    const config = CHANGE_CATEGORIES[category];
    if (!config) continue;

    for (const zone of config.impactZones) {
      if (!impactMap[zone]) impactMap[zone] = [];
      if (!impactMap[zone].includes(change.file)) {
        impactMap[zone].push(change.file);
      }

      // Add cascading impacts within the same zone iteration
      const dependencies = IMPACT_DEPENDENCIES[zone];
      if (dependencies) {
        for (const depZone of Object.keys(impactMap)) {
          if (depZone === zone) continue;
          const depConfig = IMPACT_DEPENDENCIES[depZone];
          if (depConfig && depConfig.affectedBy.includes(category)) {
            if (!impactMap[depZone].includes(change.file)) {
              impactMap[depZone].push(change.file);
            }
          }
        }
      }
    }
  }

  // Remove duplicates and empty arrays
  for (const zone of Object.keys(impactMap)) {
    impactMap[zone] = [...new Set(impactMap[zone])];
  }

  return impactMap;
}

function countAffectedComponents(impactMap) {
  const allComponents = new Set();
  for (const files of Object.values(impactMap)) {
    for (const file of files) {
      allComponents.add(file);
    }
  }
  return allComponents.size;
}

function executeSynchronization(change, impactMap, dryRun = false) {
  const syncs = [];
  const zone = change.category?.toLowerCase();

  const syncRule = SYNC_RULES[zone] || SYNC_RULES[change.category?.toLowerCase()];

  if (syncRule) {
    const ctx = { impactMap };

    // Check if this is a bilingual file
    const isSpanish = change.file.endsWith(".es.md");
    const counterpart = isSpanish
      ? change.file.replace(".es.md", ".md")
      : change.file.replace(".md", ".es.md");

    // Add bilingual sync for any change that has a bilingual counterpart
    if (fs.existsSync(path.join(root, counterpart))) {
      syncs.push({
        type: "bilingual_sync",
        target: counterpart,
        action: dryRun ? "skipped" : "validated",
        changeSource: change.file,
        details: `Bilingual pair ${isSpanish ? "ES→EN" : "EN→ES"} synchronized`
      });
    }

    switch (change.changeType) {
      case "create":
        if (syncRule.onCreate) {
          syncs.push(...syncRule.onCreate(change, ctx));
        }
        break;
      case "modify":
        if (syncRule.onModify) {
          syncs.push(...syncRule.onModify(change, ctx));
        }
        break;
      case "delete":
        if (syncRule.onDelete) {
          syncs.push(...syncRule.onDelete(change, ctx));
        }
        break;
    }
  } else {
    // Default synchronization when no specific rule exists
    syncs.push({
      type: "index_update",
      target: change.category,
      action: dryRun ? "skipped" : "validated",
      changeSource: change.file,
      details: `Change ${change.changeType} in ${change.category} zone analyzed`
    });
  }

  return syncs;
}

function checkForRisks(changes, impactMap, syncs) {
  const risks = [];

  for (const change of changes) {
    if (change.changeType === "delete") {
      const isSpanish = change.file.endsWith(".es.md");
      const counterpart = isSpanish
        ? change.file.replace(".es.md", ".md")
        : change.file.replace(".md", ".es.md");

      if (fs.existsSync(path.join(root, counterpart))) {
        risks.push({
          risk: `Bilingual counterpart exists for deleted file`,
          severity: "medium",
          affectedComponent: change.file,
          mitigation: `Review ${counterpart} - may need to also be updated to maintain bilingual parity`
        });
      }
    }

    if (change.category === "SCHEMA" && change.changeType === "modify") {
      risks.push({
        risk: `Schema modification may affect validation across multiple components`,
        severity: "high",
        affectedComponent: change.file,
        mitigation: "Run full validation suite after schema change"
      });
    }

    if (change.category === "HARNESS" && change.changeType === "modify") {
      risks.push({
        risk: `Harness modification may affect CI/CD pipeline behavior`,
        severity: "high",
        affectedComponent: change.file,
        mitigation: "Verify all validation scripts still pass after harness change"
      });
    }
  }

  // Check for failed syncs
  const failures = syncs.filter(s => s.status === "failed");
  for (const failure of failures) {
    risks.push({
      risk: `Synchronization failure: ${failure.details}`,
      severity: "high",
      affectedComponent: failure.target,
      mitigation: "Manual intervention required to resolve synchronization failure"
    });
  }

  return risks;
}

function checkForManualActions(changes, syncs, risks) {
  const pending = [];

  const failures = syncs.filter(s => s.action === "requires_manual");
  for (const f of failures) {
    pending.push({
      action: `Review and resolve: ${f.details}`,
      reason: "Automated resolution not possible without manual review",
      priority: "high",
      affectedComponent: f.target
    });
  }

  const deletesWithoutCounterpart = changes.filter(
    c => c.changeType === "delete" &&
    c.category === "DOCS" &&
    !c.file.includes("/node_modules/")
  );

  if (deletesWithoutCounterpart.length > 0) {
    pending.push({
      action: `Review deleted files for bilingual consistency: ${deletesWithoutCounterpart.length} files`,
      reason: "Files were deleted without checking bilingual counterpart status",
      priority: "medium",
      affectedComponent: "bilingual documentation"
    });
  }

  // Check for ADR deletions
  const adrDeletes = changes.filter(c => c.category === "ADR" && c.changeType === "delete");
  if (adrDeletes.length > 0) {
    pending.push({
      action: `Architecture Board review required for deleted ADRs: ${adrDeletes.map(d => d.file).join(", ")}`,
      reason: "ADR deletion requires Architecture Board approval as per INH-01 Core Immutability rules",
      priority: "critical",
      affectedComponent: "ADR Registry"
    });
  }

  return pending;
}

function generateReport(analysis) {
  const totalChanges = analysis.changes.length;
  const affectedComponents = countAffectedComponents(analysis.impactMap);
  const syncsApplied = analysis.synchronizations.filter(s =>
    (s.action === "validated" || s.action === "updated" || s.action === "created") && s.status !== "failed"
  ).length;
  const syncsSkipped = analysis.synchronizations.filter(s =>
    s.action === "skipped" || s.status === "skipped"
  ).length;
  const failures = analysis.synchronizations.filter(s =>
    s.action === "failed" || s.status === "failed"
  ).length;
  const risksCount = analysis.risks.length;
  const manualCount = analysis.pendingManualActions.length;

  let summary = `Impact Analysis completed. `;
  summary += `${totalChanges} change(s) detected, `;
  summary += `affecting ${affectedComponents} component(s). `;
  summary += `${syncsApplied} sync(s) applied, ${syncsSkipped} skipped`;
  if (failures > 0) {
    summary += `, ${failures} failure(s)`;
  }
  if (risksCount > 0) {
    summary += `, ${risksCount} risk(s)`;
  }
  if (manualCount > 0) {
    summary += `, ${manualCount} manual action(s)`;
  }

  return {
    summary,
    changesDetected: totalChanges,
    componentsAffected: affectedComponents,
    synchronizationsApplied: syncsApplied,
    synchronizationsSkipped: syncsSkipped,
    failures,
    risksIdentified: risksCount,
    manualActionsRequired: manualCount
  };
}

function runAnalysis(scope = "staged", dryRun = false, verbose = false) {
  const startTime = Date.now();
  const analysisId = generateAnalysisId();

  if (verbose) {
    console.log(`\n[Impact Analysis] Starting analysis ${analysisId}`);
    console.log(`[Impact Analysis] Scope: ${scope}, Dry-run: ${dryRun}`);
  }

  // 1. Detect changes
  const changedFiles = getChangedFiles(scope);

  if (verbose) {
    console.log(`[Impact Analysis] Detected ${changedFiles.length} changed file(s)`);
  }

  if (changedFiles.length === 0) {
    const emptyAnalysis = {
      analysisId,
      timestamp: getTimestamp(),
      trigger: { type: "pre_commit", source: "no changes" },
      changes: [],
      impactMap: {},
      synchronizations: [{
        type: "index_update",
        target: "none",
        action: "skipped",
        changeSource: "none",
        details: "No changes detected - analysis skipped",
        status: "skipped"
      }],
      risks: [],
      pendingManualActions: [],
      report: {
        summary: "No changes detected - no action required",
        changesDetected: 0,
        componentsAffected: 0,
        synchronizationsApplied: 0,
        synchronizationsSkipped: 1,
        failures: 0,
        risksIdentified: 0,
        manualActionsRequired: 0
      },
      executionMetadata: {
        analyzerVersion: "1.0.0",
        rulesetVersion: "1.0.0",
        executionTimeMs: Date.now() - startTime,
        idempotent: true
      }
    };
    return emptyAnalysis;
  }

  // 2. Classify changes
  const changes = changedFiles.map(file => {
    const category = classifyChange(file) || "DOCS";
    const changeType = getChangeType(file, scope);
    const config = CHANGE_CATEGORIES[category] || { severity: { create: "medium", modify: "low", delete: "high" } };
    const severity = config.severity[changeType] || "medium";

    // Extract ADR ID if applicable
    let adrId = null;
    const adrMatch = file.match(/ADR-(\d+)/i);
    if (adrMatch) {
      adrId = `ADR-${adrMatch[1]}`;
    }

    return {
      file,
      category,
      changeType,
      severity,
      adrId,
      justification: `Detected via ${scope} analysis`
    };
  });

  if (verbose) {
    console.log(`[Impact Analysis] Classified ${changes.length} change(s)`);
    const byCategory = changes.reduce((acc, c) => {
      acc[c.category] = (acc[c.category] || 0) + 1;
      return acc;
    }, {});
    console.log(`[Impact Analysis] By category:`, byCategory);
  }

  // 3. Build impact map
  const impactMap = buildImpactMap(changes);

  if (verbose) {
    const zones = Object.entries(impactMap).filter(([, v]) => v.length > 0);
    console.log(`[Impact Analysis] Impact zones affected: ${zones.length}`);
    zones.forEach(([zone, files]) => {
      console.log(`  - ${zone}: ${files.length} file(s)`);
    });
  }

  // 4. Execute synchronizations
  const synchronizations = [];
  for (const change of changes) {
    const syncs = executeSynchronization(change, impactMap, dryRun);
    synchronizations.push(...syncs);
  }

  if (verbose) {
    console.log(`[Impact Analysis] Executed ${synchronizations.length} synchronization(s)`);
  }

  // 5. Check for risks
  const risks = checkForRisks(changes, impactMap, synchronizations);

  if (verbose && risks.length > 0) {
    console.log(`[Impact Analysis] ${risks.length} risk(s) identified:`);
    risks.forEach(r => console.log(`  - [${r.severity}] ${r.risk}`));
  }

  // 6. Check for manual actions
  const pendingManualActions = checkForManualActions(changes, synchronizations, risks);

  if (verbose && pendingManualActions.length > 0) {
    console.log(`[Impact Analysis] ${pendingManualActions.length} manual action(s) required`);
    pendingManualActions.forEach(a => console.log(`  - [${a.priority}] ${a.action}`));
  }

  // 7. Generate report
  const report = generateReport({
    changes,
    impactMap,
    synchronizations,
    risks,
    pendingManualActions
  });

  const executionTimeMs = Date.now() - startTime;

  const analysis = {
    analysisId,
    timestamp: getTimestamp(),
    trigger: {
      type: "pre_commit",
      source: execSync("git rev-parse HEAD", { encoding: "utf8", cwd: root }).trim()
    },
    changes,
    impactMap,
    synchronizations,
    risks,
    pendingManualActions,
    report,
    executionMetadata: {
      analyzerVersion: "1.0.0",
      rulesetVersion: "1.0.0",
      executionTimeMs,
      idempotent: dryRun || synchronizations.every(s => s.action !== "updated")
    }
  };

  return analysis;
}

// ============================================================================
// REPORT GENERATION
// ============================================================================

function formatReport(analysis) {
  const lines = [];

  lines.push("═".repeat(70));
  lines.push("  EVOLITH CORE — IMPACT ANALYSIS & SYNCHRONIZATION REPORT");
  lines.push("═".repeat(70));
  lines.push("");

  lines.push(`  Analysis ID    : ${analysis.analysisId}`);
  lines.push(`  Timestamp      : ${analysis.timestamp}`);
  lines.push(`  Trigger        : ${analysis.trigger.type} (${analysis.trigger.source})`);
  lines.push(`  Execution Time : ${analysis.executionMetadata.executionTimeMs}ms`);
  lines.push(`  Idempotent     : ${analysis.executionMetadata.idempotent ? "✓ Yes" : "✗ No"}`);
  lines.push("");

  lines.push("─".repeat(70));
  lines.push("  1. CHANGES DETECTED");
  lines.push("─".repeat(70));

  if (analysis.changes.length === 0) {
    lines.push("  No changes detected.");
  } else {
    const byCategory = analysis.changes.reduce((acc, c) => {
      acc[c.category] = acc[c.category] || [];
      acc[c.category].push(c);
      return acc;
    }, {});

    for (const [category, items] of Object.entries(byCategory)) {
      lines.push(`\n  [${category}] ${items.length} change(s):`);
      for (const item of items) {
        const flag = item.changeType === "delete" ? "✗" : item.changeType === "create" ? "+" : "~";
        lines.push(`    ${flag} ${item.file}`);
        lines.push(`       Type: ${item.changeType} | Severity: ${item.severity}`);
      }
    }
  }

  lines.push("");
  lines.push("─".repeat(70));
  lines.push("  2. IMPACT MAP (Affected Zones)");
  lines.push("─".repeat(70));

  const zones = Object.entries(analysis.impactMap).filter(([, v]) => v.length > 0);
  if (zones.length === 0) {
    lines.push("  No impact zones affected.");
  } else {
    for (const [zone, files] of zones) {
      lines.push(`\n  ${zone.toUpperCase()} (${files.length} file(s)):`);
      for (const file of files.slice(0, 5)) {
        lines.push(`    → ${file}`);
      }
      if (files.length > 5) {
        lines.push(`    ... and ${files.length - 5} more`);
      }
    }
  }

  lines.push("");
  lines.push("─".repeat(70));
  lines.push("  3. SYNCHRONIZATIONS");
  lines.push("─".repeat(70));

  const success = analysis.synchronizations.filter(s =>
    s.action === "validated" || s.action === "updated" || s.action === "created"
  );
  const skipped = analysis.synchronizations.filter(s => s.action === "skipped");
  const failed = analysis.synchronizations.filter(s => s.action === "failed");
  const manual = analysis.synchronizations.filter(s => s.action === "requires_manual");

  lines.push(`  Applied: ${success.length} | Skipped: ${skipped.length} | Failed: ${failed.length} | Manual: ${manual.length}`);
  lines.push("");

  if (failed.length > 0) {
    lines.push("  FAILED:");
    for (const f of failed) {
      lines.push(`    ✗ ${f.target}`);
      lines.push(`      ${f.details}`);
    }
    lines.push("");
  }

  if (manual.length > 0) {
    lines.push("  REQUIRES MANUAL:");
    for (const m of manual) {
      lines.push(`    ⚠ ${m.target}`);
      lines.push(`      ${m.details}`);
    }
    lines.push("");
  }

  lines.push("");
  lines.push("─".repeat(70));
  lines.push("  4. RISKS & PENDING MANUAL ACTIONS");
  lines.push("─".repeat(70));

  if (analysis.risks.length > 0) {
    lines.push(`\n  ${analysis.risks.length} RISK(S):`);
    for (const risk of analysis.risks) {
      lines.push(`\n    [${risk.severity.toUpperCase()}] ${risk.risk}`);
      lines.push(`    Affected: ${risk.affectedComponent}`);
      lines.push(`    Mitigation: ${risk.mitigation}`);
    }
    lines.push("");
  }

  if (analysis.pendingManualActions.length > 0) {
    lines.push(`\n  ${analysis.pendingManualActions.length} MANUAL ACTION(S) REQUIRED:`);
    for (const action of analysis.pendingManualActions) {
      lines.push(`\n    [${action.priority.toUpperCase()}] ${action.action}`);
      lines.push(`    Reason: ${action.reason}`);
      lines.push(`    Component: ${action.affectedComponent}`);
    }
    lines.push("");
  }

  if (analysis.risks.length === 0 && analysis.pendingManualActions.length === 0) {
    lines.push("  ✓ No risks identified. ✓ No manual actions required.");
    lines.push("");
  }

  lines.push("═".repeat(70));
  lines.push(`  SUMMARY: ${analysis.report.summary}`);
  lines.push("═".repeat(70));

  return lines.join("\n");
}

function saveReport(analysis) {
  const reportsDir = path.join(root, ".harness", "reports");

  if (!fs.existsSync(reportsDir)) {
    fs.mkdirSync(reportsDir, { recursive: true });
  }

  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
  const filename = `impact-analysis-${timestamp}.json`;
  const filepath = path.join(reportsDir, filename);

  fs.writeFileSync(filepath, JSON.stringify(analysis, null, 2));

  const textFilename = filename.replace(".json", ".txt");
  const textPath = path.join(reportsDir, textFilename);
  fs.writeFileSync(textPath, formatReport(analysis));

  return { jsonPath: filepath, textPath };
}

// ============================================================================
// MAIN
// ============================================================================

function main() {
  const args = process.argv.slice(2);

  const options = {
    scope: "staged",
    dryRun: false,
    verbose: false,
    saveReport: false,
    failOnRisk: false
  };

  for (const arg of args) {
    if (arg === "--staged") options.scope = "staged";
    else if (arg === "--working-tree") options.scope = "working-tree";
    else if (arg === "--all") options.scope = "all";
    else if (arg === "--dry-run") options.dryRun = true;
    else if (arg === "--verbose") options.verbose = true;
    else if (arg === "--report") options.saveReport = true;
    else if (arg === "--fail-on-risk") options.failOnRisk = true;
    else if (arg === "--help") {
      console.log(`Usage: node impact-analysis-synchronizer.mjs [options]

Options:
  --staged        Analyze staged changes only (default)
  --working-tree  Analyze working tree changes
  --all           Analyze all changes since last commit
  --dry-run       Report only, no changes applied
  --verbose       Detailed output
  --report        Save report to .harness/reports/
  --fail-on-risk  Exit with error if risks identified
  --help          Show this help message`);
      process.exit(0);
    }
  }

  const analysis = runAnalysis(options.scope, options.dryRun, options.verbose);

  if (options.verbose || options.dryRun) {
    console.log("\n" + formatReport(analysis));
  }

  if (options.saveReport) {
    const { jsonPath, textPath } = saveReport(analysis);
    console.log(`\n✓ Report saved to:`);
    console.log(`  JSON: ${jsonPath}`);
    console.log(`  TXT:  ${textPath}`);
  }

  // Exit code logic
  const criticalRisks = analysis.risks.filter(r => r.severity === "critical");
  const manualActions = analysis.pendingManualActions.filter(a => a.priority === "critical");
  const failures = analysis.synchronizations.filter(s => s.status === "failed");

  if (failures.length > 0) {
    console.error(`\n✗ Synchronization failures detected: ${failures.length}`);
    process.exit(1);
  }

  if (options.failOnRisk && (criticalRisks.length > 0 || manualActions.length > 0)) {
    console.error(`\n✗ Critical risks or manual actions detected. Review required before proceeding.`);
    process.exit(1);
  }

  if (analysis.pendingManualActions.length > 0 && !options.dryRun) {
    console.warn(`\n⚠ ${analysis.pendingManualActions.length} manual action(s) required. Check report for details.`);
  }

  process.exit(0);
}

main();