@codesentinel/codesentinel 1.2.0 → 1.3.0

package/dist/index.js

@@ -6,6 +6,104 @@ import { readFileSync as readFileSync2 } from "fs";
 import { dirname, resolve as resolve3 } from "path";
 import { fileURLToPath } from "url";
 
+// src/application/format-analyze-output.ts
+var createSummaryShape = (summary) => ({
+  targetPath: summary.structural.targetPath,
+  structural: summary.structural.metrics,
+  evolution: summary.evolution.available ? {
+    available: true,
+    metrics: summary.evolution.metrics,
+    hotspotsTop: summary.evolution.hotspots.slice(0, 5).map((hotspot) => hotspot.filePath)
+  } : {
+    available: false,
+    reason: summary.evolution.reason
+  },
+  external: summary.external.available ? {
+    available: true,
+    metrics: summary.external.metrics,
+    highRiskDependenciesTop: summary.external.highRiskDependencies.slice(0, 10)
+  } : {
+    available: false,
+    reason: summary.external.reason
+  },
+  risk: {
+    repositoryScore: summary.risk.repositoryScore,
+    normalizedScore: summary.risk.normalizedScore,
+    hotspotsTop: summary.risk.hotspots.slice(0, 5).map((hotspot) => ({
+      file: hotspot.file,
+      score: hotspot.score
+    })),
+    fragileClusterCount: summary.risk.fragileClusters.length,
+    dependencyAmplificationZoneCount: summary.risk.dependencyAmplificationZones.length
+  }
+});
+var formatAnalyzeOutput = (summary, mode) => mode === "json" ? JSON.stringify(summary, null, 2) : JSON.stringify(createSummaryShape(summary), null, 2);
+
+// src/application/logger.ts
+var logLevelRank = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+var noop = () => {
+};
+var createSilentLogger = () => ({
+  error: noop,
+  warn: noop,
+  info: noop,
+  debug: noop
+});
+var shouldLog = (configuredLevel, messageLevel) => {
+  if (configuredLevel === "silent") {
+    return false;
+  }
+  return logLevelRank[messageLevel] <= logLevelRank[configuredLevel];
+};
+var write = (messageLevel, message) => {
+  process.stderr.write(`[codesentinel] ${messageLevel.toUpperCase()} ${message}
+`);
+};
+var createStderrLogger = (level) => {
+  if (level === "silent") {
+    return createSilentLogger();
+  }
+  return {
+    error: (message) => {
+      if (shouldLog(level, "error")) {
+        write("error", message);
+      }
+    },
+    warn: (message) => {
+      if (shouldLog(level, "warn")) {
+        write("warn", message);
+      }
+    },
+    info: (message) => {
+      if (shouldLog(level, "info")) {
+        write("info", message);
+      }
+    },
+    debug: (message) => {
+      if (shouldLog(level, "debug")) {
+        write("debug", message);
+      }
+    }
+  };
+};
+var parseLogLevel = (value) => {
+  switch (value) {
+    case "silent":
+    case "error":
+    case "warn":
+    case "info":
+    case "debug":
+      return value;
+    default:
+      return "info";
+  }
+};
+
 // src/application/run-analyze-command.ts
 import { resolve as resolve2 } from "path";
 
@@ -385,16 +483,18 @@ var extractModuleSpecifiers = (sourceFile) => {
   visit(sourceFile);
   return [...specifiers];
 };
-var parseTypescriptProject = (projectPath) => {
+var parseTypescriptProject = (projectPath, onProgress) => {
   const projectRoot = isAbsolute(projectPath) ? projectPath : resolve(projectPath);
   const { fileNames, options } = parseTsConfig(projectRoot);
   const sourceFilePaths = fileNames.filter((filePath) => isProjectSourceFile(filePath, projectRoot)).map((filePath) => normalizePath(resolve(filePath)));
   const uniqueSourceFilePaths = [...new Set(sourceFilePaths)].sort((a, b) => a.localeCompare(b));
   const sourceFilePathSet = new Set(uniqueSourceFilePaths);
+  onProgress?.({ stage: "files_discovered", totalSourceFiles: uniqueSourceFilePaths.length });
   const program2 = ts.createProgram({
     rootNames: uniqueSourceFilePaths,
     options
   });
+  onProgress?.({ stage: "program_created", totalSourceFiles: uniqueSourceFilePaths.length });
   const nodeByAbsolutePath = /* @__PURE__ */ new Map();
   for (const sourcePath of uniqueSourceFilePaths) {
     const relativePath = normalizePath(relative(projectRoot, sourcePath));
@@ -407,7 +507,7 @@ var parseTypescriptProject = (projectPath) => {
   }
   const resolverCache = /* @__PURE__ */ new Map();
   const edges = [];
-  for (const sourcePath of uniqueSourceFilePaths) {
+  for (const [index, sourcePath] of uniqueSourceFilePaths.entries()) {
     const sourceFile = program2.getSourceFile(sourcePath);
     if (sourceFile === void 0) {
       continue;
@@ -436,14 +536,24 @@ var parseTypescriptProject = (projectPath) => {
       }
       edges.push({ from: fromNode.id, to: toNode.id });
     }
+    const processed = index + 1;
+    if (processed === 1 || processed === uniqueSourceFilePaths.length || processed % 50 === 0) {
+      onProgress?.({
+        stage: "file_processed",
+        processed,
+        total: uniqueSourceFilePaths.length,
+        filePath: fromNode.id
+      });
+    }
   }
+  onProgress?.({ stage: "edges_resolved", totalEdges: edges.length });
   return {
     nodes: [...nodeByAbsolutePath.values()],
     edges
   };
 };
 var buildProjectGraphSummary = (input) => {
-  const parsedProject = parseTypescriptProject(input.projectPath);
+  const parsedProject = parseTypescriptProject(input.projectPath, input.onProgress);
   const graphData = createGraphData(parsedProject.nodes, parsedProject.edges);
   return createGraphAnalysisSummary(input.projectPath, graphData);
 };
@@ -1007,7 +1117,7 @@ var mapWithConcurrency = async (values, limit, handler) => {
   await Promise.all(workers);
   return results;
 };
-var analyzeDependencyExposure = async (input, metadataProvider) => {
+var analyzeDependencyExposure = async (input, metadataProvider, onProgress) => {
   const packageJson = loadPackageJson(input.repositoryPath);
   if (packageJson === null) {
     return {
@@ -1016,6 +1126,7 @@ var analyzeDependencyExposure = async (input, metadataProvider) => {
       reason: "package_json_not_found"
     };
   }
+  onProgress?.({ stage: "package_json_loaded" });
   const lockfile = selectLockfile(input.repositoryPath);
   if (lockfile === null) {
     return {
@@ -1024,23 +1135,50 @@ var analyzeDependencyExposure = async (input, metadataProvider) => {
       reason: "lockfile_not_found"
     };
   }
+  onProgress?.({ stage: "lockfile_selected", kind: lockfile.kind });
   try {
     const directSpecs = parsePackageJson(packageJson.raw);
     const extraction = parseExtraction(lockfile.kind, lockfile.raw, directSpecs);
     const config = withDefaults(input.config);
+    onProgress?.({
+      stage: "lockfile_parsed",
+      dependencyNodes: extraction.nodes.length,
+      directDependencies: extraction.directDependencies.length
+    });
+    onProgress?.({ stage: "metadata_fetch_started", total: extraction.nodes.length });
+    let completed = 0;
     const metadataEntries = await mapWithConcurrency(
       extraction.nodes,
       config.metadataRequestConcurrency,
-      async (node) => ({
-        key: `${node.name}@${node.version}`,
-        metadata: await metadataProvider.getMetadata(node.name, node.version)
-      })
+      async (node) => {
+        const result = {
+          key: `${node.name}@${node.version}`,
+          metadata: await metadataProvider.getMetadata(node.name, node.version)
+        };
+        completed += 1;
+        onProgress?.({
+          stage: "metadata_fetch_progress",
+          completed,
+          total: extraction.nodes.length,
+          packageName: node.name
+        });
+        return result;
+      }
     );
+    onProgress?.({ stage: "metadata_fetch_completed", total: extraction.nodes.length });
     const metadataByKey = /* @__PURE__ */ new Map();
     for (const entry of metadataEntries) {
       metadataByKey.set(entry.key, entry.metadata);
     }
-    return buildExternalAnalysisSummary(input.repositoryPath, extraction, metadataByKey, config);
+    const summary = buildExternalAnalysisSummary(input.repositoryPath, extraction, metadataByKey, config);
+    if (summary.available) {
+      onProgress?.({
+        stage: "summary_built",
+        totalDependencies: summary.metrics.totalDependencies,
+        directDependencies: summary.metrics.directDependencies
+      });
+    }
+    return summary;
   } catch (error) {
     const message = error instanceof Error ? error.message : "unknown";
     if (message.includes("unsupported_lockfile_format")) {
@@ -1123,9 +1261,9 @@ var NoopMetadataProvider = class {
     return null;
   }
 };
-var analyzeDependencyExposureFromProject = async (input) => {
+var analyzeDependencyExposureFromProject = async (input, onProgress) => {
   const metadataProvider = process.env["CODESENTINEL_EXTERNAL_METADATA"] === "none" ? new NoopMetadataProvider() : new NpmRegistryMetadataProvider();
-  return analyzeDependencyExposure(input, metadataProvider);
+  return analyzeDependencyExposure(input, metadataProvider, onProgress);
 };
 
 // ../git-analyzer/dist/index.js
@@ -1422,17 +1560,26 @@ var createEffectiveConfig = (overrides) => ({
   ...DEFAULT_EVOLUTION_CONFIG,
   ...overrides
 });
-var analyzeRepositoryEvolution = (input, historyProvider) => {
+var analyzeRepositoryEvolution = (input, historyProvider, onProgress) => {
+  onProgress?.({ stage: "checking_git_repository" });
   if (!historyProvider.isGitRepository(input.repositoryPath)) {
+    onProgress?.({ stage: "not_git_repository" });
     return {
       targetPath: input.repositoryPath,
       available: false,
       reason: "not_git_repository"
     };
   }
-  const commits = historyProvider.getCommitHistory(input.repositoryPath);
+  onProgress?.({ stage: "loading_commit_history" });
+  const commits = historyProvider.getCommitHistory(
+    input.repositoryPath,
+    (event) => onProgress?.({ stage: "history", event })
+  );
   const config = createEffectiveConfig(input.config);
-  return computeRepositoryEvolutionSummary(input.repositoryPath, commits, config);
+  onProgress?.({ stage: "computing_metrics" });
+  const summary = computeRepositoryEvolutionSummary(input.repositoryPath, commits, config);
+  onProgress?.({ stage: "analysis_completed", available: summary.available });
+  return summary;
 };
 var GitCommandError = class extends Error {
   args;
@@ -1459,6 +1606,11 @@ var ExecGitCommandClient = class {
 var COMMIT_RECORD_SEPARATOR = "";
 var COMMIT_FIELD_SEPARATOR = "";
 var GIT_LOG_FORMAT = `%x1e%H%x1f%at%x1f%an%x1f%ae`;
+var mapParseProgressToHistoryProgress = (event) => ({
+  stage: "git_log_parse_progress",
+  parsedRecords: event.parsedRecords,
+  totalRecords: event.totalRecords
+});
 var parseInteger = (value) => {
   if (value.length === 0) {
     return null;
@@ -1521,10 +1673,10 @@ var parseNumstatLine = (line) => {
     deletions
   };
 };
-var parseGitLog = (rawLog) => {
+var parseGitLog = (rawLog, onProgress) => {
   const records = rawLog.split(COMMIT_RECORD_SEPARATOR).map((record) => record.trim()).filter((record) => record.length > 0);
   const commits = [];
-  for (const record of records) {
+  for (const [index, record] of records.entries()) {
     const lines = record.split("\n").map((line) => line.trimEnd()).filter((line) => line.length > 0);
     if (lines.length === 0) {
       continue;
@@ -1555,6 +1707,10 @@ var parseGitLog = (rawLog) => {
       authoredAtUnix,
       fileChanges
     });
+    const parsedRecords = index + 1;
+    if (parsedRecords === 1 || parsedRecords === records.length || parsedRecords % 500 === 0) {
+      onProgress?.({ parsedRecords, totalRecords: records.length });
+    }
   }
   commits.sort((a, b) => a.authoredAtUnix - b.authoredAtUnix || a.hash.localeCompare(b.hash));
   return commits;
@@ -1579,7 +1735,7 @@ var GitCliHistoryProvider = class {
       throw error;
     }
   }
-  getCommitHistory(repositoryPath) {
+  getCommitHistory(repositoryPath, onProgress) {
     const output = this.gitClient.run(repositoryPath, [
       "-c",
       "core.quotepath=false",
@@ -1591,31 +1747,810 @@ var GitCliHistoryProvider = class {
       "--numstat",
       "--find-renames"
     ]);
-    return parseGitLog(output);
+    onProgress?.({ stage: "git_log_received", bytes: Buffer.byteLength(output, "utf8") });
+    const commits = parseGitLog(output, (event) => onProgress?.(mapParseProgressToHistoryProgress(event)));
+    onProgress?.({ stage: "git_log_parsed", commits: commits.length });
+    return commits;
   }
 };
-var analyzeRepositoryEvolutionFromGit = (input) => {
+var analyzeRepositoryEvolutionFromGit = (input, onProgress) => {
   const historyProvider = new GitCliHistoryProvider(new ExecGitCommandClient());
-  return analyzeRepositoryEvolution(input, historyProvider);
+  return analyzeRepositoryEvolution(input, historyProvider, onProgress);
+};
+
+// ../risk-engine/dist/index.js
+var DEFAULT_RISK_ENGINE_CONFIG = {
+  // Base dimensional influence. Risk is never dominated by a single dimension by default.
+  dimensionWeights: {
+    structural: 0.44,
+    evolution: 0.36,
+    external: 0.2
+  },
+  // Interaction terms activate only when both related dimensions are high.
+  interactionWeights: {
+    structuralEvolution: 0.35,
+    centralInstability: 0.25,
+    dependencyAmplification: 0.2
+  },
+  structuralFactorWeights: {
+    fanIn: 0.3,
+    fanOut: 0.25,
+    depth: 0.2,
+    cycleParticipation: 0.25
+  },
+  evolutionFactorWeights: {
+    frequency: 0.26,
+    churn: 0.24,
+    recentVolatility: 0.2,
+    ownershipConcentration: 0.18,
+    busFactorRisk: 0.12
+  },
+  dependencyFactorWeights: {
+    signals: 0.38,
+    staleness: 0.16,
+    maintainerConcentration: 0.16,
+    transitiveBurden: 0.1,
+    centrality: 0.08,
+    chainDepth: 0.06,
+    busFactorRisk: 0.06
+  },
+  quantileClamp: {
+    lower: 0.05,
+    upper: 0.95
+  },
+  hotspotTopPercent: 0.12,
+  hotspotMinFiles: 3,
+  hotspotMaxFiles: 30,
+  couplingCluster: {
+    minCoChangeCommits: 2,
+    percentileThreshold: 0.9,
+    floorScore: 0.35
+  },
+  amplificationZone: {
+    pressureFloor: 0.2,
+    percentileThreshold: 0.85,
+    maxZones: 20
+  },
+  module: {
+    maxPrefixSegments: 2,
+    rootLabel: "(root)",
+    commonSourceRoots: ["src", "lib", "app", "packages"]
+  },
+  dependencySignals: {
+    inheritedSignalMultiplier: 0.45,
+    // At this age, staleness reaches 50% risk.
+    abandonedHalfLifeDays: 540,
+    missingMetadataPenalty: 0.5
+  },
+  externalDimension: {
+    topDependencyPercentile: 0.85,
+    dependencyDepthHalfLife: 6
+  }
+};
+var clamp01 = (value) => {
+  if (Number.isNaN(value)) {
+    return 0;
+  }
+  if (value <= 0) {
+    return 0;
+  }
+  if (value >= 1) {
+    return 1;
+  }
+  return value;
+};
+var round44 = (value) => Number(value.toFixed(4));
+var average = (values) => {
+  if (values.length === 0) {
+    return 0;
+  }
+  const total = values.reduce((sum, current) => sum + current, 0);
+  return total / values.length;
+};
+var percentile = (values, p) => {
+  if (values.length === 0) {
+    return 0;
+  }
+  if (values.length === 1) {
+    return values[0] ?? 0;
+  }
+  const sorted = [...values].sort((a, b) => a - b);
+  const position = clamp01(p) * (sorted.length - 1);
+  const lowerIndex = Math.floor(position);
+  const upperIndex = Math.ceil(position);
+  const lower = sorted[lowerIndex] ?? 0;
+  const upper = sorted[upperIndex] ?? lower;
+  if (lowerIndex === upperIndex) {
+    return lower;
+  }
+  const ratio = position - lowerIndex;
+  return lower + (upper - lower) * ratio;
+};
+var saturatingComposite = (baseline, amplifications) => {
+  let value = clamp01(baseline);
+  for (const amplification of amplifications) {
+    const boundedAmplification = clamp01(amplification);
+    value += (1 - value) * boundedAmplification;
+  }
+  return clamp01(value);
+};
+var halfLifeRisk = (value, halfLife) => {
+  if (value <= 0 || halfLife <= 0) {
+    return 0;
+  }
+  return clamp01(value / (value + halfLife));
+};
+var normalizeWeights = (weights, enabled) => {
+  let total = 0;
+  const result = { ...weights };
+  for (const key of Object.keys(result)) {
+    const enabledValue = enabled[key];
+    if (!enabledValue) {
+      result[key] = 0;
+      continue;
+    }
+    const value = Math.max(0, result[key]);
+    result[key] = value;
+    total += value;
+  }
+  if (total === 0) {
+    const activeKeys = Object.keys(result).filter((key) => enabled[key]);
+    if (activeKeys.length === 0) {
+      return result;
+    }
+    const uniform = 1 / activeKeys.length;
+    for (const key of activeKeys) {
+      result[key] = uniform;
+    }
+    return result;
+  }
+  for (const key of Object.keys(result)) {
+    if (enabled[key]) {
+      result[key] = result[key] / total;
+    }
+  }
+  return result;
+};
+var logScale = (value) => Math.log1p(Math.max(0, value));
+var buildQuantileScale = (values, lowerPercentile, upperPercentile) => {
+  if (values.length === 0) {
+    return { lower: 0, upper: 0 };
+  }
+  return {
+    lower: percentile(values, lowerPercentile),
+    upper: percentile(values, upperPercentile)
+  };
+};
+var normalizeWithScale = (value, scale) => {
+  if (scale.upper <= scale.lower) {
+    return value > 0 ? 1 : 0;
+  }
+  return clamp01((value - scale.lower) / (scale.upper - scale.lower));
+};
+var normalizePath2 = (path) => path.replaceAll("\\", "/");
+var dependencySignalWeights = {
+  single_maintainer: 0.3,
+  abandoned: 0.3,
+  high_centrality: 0.16,
+  deep_chain: 0.14,
+  high_fanout: 0.06,
+  metadata_unavailable: 0.04
+};
+var dependencySignalWeightBudget = Object.values(dependencySignalWeights).reduce(
+  (sum, value) => sum + value,
+  0
+);
+var computeDependencySignalScore = (ownSignals, inheritedSignals, inheritedSignalMultiplier) => {
+  const ownWeight = ownSignals.reduce((sum, signal) => sum + (dependencySignalWeights[signal] ?? 0), 0);
+  const inheritedWeight = inheritedSignals.reduce(
+    (sum, signal) => sum + (dependencySignalWeights[signal] ?? 0),
+    0
+  );
+  const weightedTotal = ownWeight + inheritedWeight * inheritedSignalMultiplier;
+  const maxWeightedTotal = dependencySignalWeightBudget * (1 + inheritedSignalMultiplier);
+  if (maxWeightedTotal <= 0) {
+    return 0;
+  }
+  return clamp01(weightedTotal / maxWeightedTotal);
+};
+var computeDependencyScores = (external, config) => {
+  if (!external.available) {
+    return {
+      dependencyScores: [],
+      repositoryExternalPressure: 0
+    };
+  }
+  const transitiveCounts = external.dependencies.map(
+    (dependency) => logScale(dependency.transitiveDependencies.length)
+  );
+  const dependentCounts = external.dependencies.map((dependency) => logScale(dependency.dependents));
+  const chainDepths = external.dependencies.map((dependency) => dependency.dependencyDepth);
+  const transitiveScale = buildQuantileScale(
+    transitiveCounts,
+    config.quantileClamp.lower,
+    config.quantileClamp.upper
+  );
+  const dependentScale = buildQuantileScale(
+    dependentCounts,
+    config.quantileClamp.lower,
+    config.quantileClamp.upper
+  );
+  const chainDepthScale = buildQuantileScale(
+    chainDepths,
+    config.quantileClamp.lower,
+    config.quantileClamp.upper
+  );
+  const dependencyScores = external.dependencies.map((dependency) => {
+    const signalScore = computeDependencySignalScore(
+      dependency.ownRiskSignals,
+      dependency.inheritedRiskSignals,
+      config.dependencySignals.inheritedSignalMultiplier
+    );
+    const maintainerConcentrationRisk = dependency.maintainerCount === null ? config.dependencySignals.missingMetadataPenalty : clamp01(1 / Math.max(1, dependency.maintainerCount));
+    const stalenessRisk = dependency.daysSinceLastRelease === null ? config.dependencySignals.missingMetadataPenalty : halfLifeRisk(
+      dependency.daysSinceLastRelease,
+      config.dependencySignals.abandonedHalfLifeDays
+    );
+    const transitiveBurdenRisk = normalizeWithScale(
+      logScale(dependency.transitiveDependencies.length),
+      transitiveScale
+    );
+    const centralityRisk = normalizeWithScale(logScale(dependency.dependents), dependentScale);
+    const chainDepthRisk = normalizeWithScale(dependency.dependencyDepth, chainDepthScale);
+    const busFactorRisk = dependency.busFactor === null ? config.dependencySignals.missingMetadataPenalty : clamp01(1 / Math.max(1, dependency.busFactor));
+    const weights = config.dependencyFactorWeights;
+    const normalizedScore = clamp01(
+      signalScore * weights.signals + stalenessRisk * weights.staleness + maintainerConcentrationRisk * weights.maintainerConcentration + transitiveBurdenRisk * weights.transitiveBurden + centralityRisk * weights.centrality + chainDepthRisk * weights.chainDepth + busFactorRisk * weights.busFactorRisk
+    );
+    return {
+      dependency: dependency.name,
+      score: round44(normalizedScore * 100),
+      normalizedScore: round44(normalizedScore),
+      ownRiskSignals: dependency.ownRiskSignals,
+      inheritedRiskSignals: dependency.inheritedRiskSignals
+    };
+  }).sort(
+    (a, b) => b.normalizedScore - a.normalizedScore || a.dependency.localeCompare(b.dependency)
+  );
+  const normalizedValues = dependencyScores.map((score) => score.normalizedScore);
+  const highDependencyRisk = dependencyScores.length === 0 ? 0 : percentile(normalizedValues, config.externalDimension.topDependencyPercentile);
+  const averageDependencyRisk = average(normalizedValues);
+  const depthRisk = halfLifeRisk(
+    external.metrics.dependencyDepth,
+    config.externalDimension.dependencyDepthHalfLife
+  );
+  const repositoryExternalPressure = clamp01(
+    highDependencyRisk * 0.5 + averageDependencyRisk * 0.3 + depthRisk * 0.2
+  );
+  return {
+    dependencyScores,
+    repositoryExternalPressure: round44(repositoryExternalPressure)
+  };
+};
+var mapEvolutionByFile = (evolution) => {
+  if (!evolution.available) {
+    return /* @__PURE__ */ new Map();
+  }
+  return new Map(
+    evolution.files.map((fileMetrics) => [normalizePath2(fileMetrics.filePath), fileMetrics])
+  );
+};
+var computeEvolutionScales = (evolutionByFile, config) => {
+  const evolutionFiles = [...evolutionByFile.values()];
+  return {
+    commitCount: buildQuantileScale(
+      evolutionFiles.map((metrics) => logScale(metrics.commitCount)),
+      config.quantileClamp.lower,
+      config.quantileClamp.upper
+    ),
+    churnTotal: buildQuantileScale(
+      evolutionFiles.map((metrics) => logScale(metrics.churnTotal)),
+      config.quantileClamp.lower,
+      config.quantileClamp.upper
+    ),
+    busFactor: buildQuantileScale(
+      evolutionFiles.map((metrics) => metrics.busFactor),
+      config.quantileClamp.lower,
+      config.quantileClamp.upper
+    )
+  };
+};
+var inferModuleName = (filePath, config) => {
+  const normalized = normalizePath2(filePath);
+  const parts = normalized.split("/").filter((part) => part.length > 0);
+  if (parts.length <= 1) {
+    return config.module.rootLabel;
+  }
+  const first = parts[0];
+  if (first === void 0) {
+    return config.module.rootLabel;
+  }
+  if (!config.module.commonSourceRoots.includes(first)) {
+    return first;
+  }
+  if (parts.length <= config.module.maxPrefixSegments) {
+    return first;
+  }
+  return parts.slice(0, config.module.maxPrefixSegments).join("/");
+};
+var buildFragileClusters = (structural, evolution, fileScoresByFile, config) => {
+  const clusters = [];
+  let cycleClusterCount = 0;
+  for (const cycle of structural.cycles) {
+    const files = [...new Set(cycle.nodes.map((node) => normalizePath2(node)))].filter(
+      (filePath) => fileScoresByFile.has(filePath)
+    );
+    if (files.length < 2) {
+      continue;
+    }
+    files.sort((a, b) => a.localeCompare(b));
+    const averageRisk = average(
+      files.map((filePath) => fileScoresByFile.get(filePath)?.normalizedScore ?? 0)
+    );
+    const cycleSizeRisk = clamp01((files.length - 1) / 5);
+    const score = round44(clamp01(averageRisk * 0.75 + cycleSizeRisk * 0.25) * 100);
+    cycleClusterCount += 1;
+    clusters.push({
+      id: `cycle:${cycleClusterCount}`,
+      kind: "structural_cycle",
+      files,
+      score
+    });
+  }
+  if (evolution.available && evolution.coupling.pairs.length > 0) {
+    const candidates = evolution.coupling.pairs.filter(
+      (pair) => pair.coChangeCommits >= config.couplingCluster.minCoChangeCommits
+    );
+    const threshold = Math.max(
+      config.couplingCluster.floorScore,
+      percentile(
+        candidates.map((pair) => pair.couplingScore),
+        config.couplingCluster.percentileThreshold
+      )
+    );
+    const selectedPairs = candidates.filter((pair) => pair.couplingScore >= threshold).map((pair) => ({
+      fileA: normalizePath2(pair.fileA),
+      fileB: normalizePath2(pair.fileB),
+      couplingScore: pair.couplingScore
+    })).filter(
+      (pair) => pair.fileA !== pair.fileB && fileScoresByFile.has(pair.fileA) && fileScoresByFile.has(pair.fileB)
+    );
+    const adjacency = /* @__PURE__ */ new Map();
+    for (const pair of selectedPairs) {
+      const aNeighbors = adjacency.get(pair.fileA) ?? /* @__PURE__ */ new Set();
+      aNeighbors.add(pair.fileB);
+      adjacency.set(pair.fileA, aNeighbors);
+      const bNeighbors = adjacency.get(pair.fileB) ?? /* @__PURE__ */ new Set();
+      bNeighbors.add(pair.fileA);
+      adjacency.set(pair.fileB, bNeighbors);
+    }
+    const visited = /* @__PURE__ */ new Set();
+    let couplingClusterCount = 0;
+    const orderedStarts = [...adjacency.keys()].sort((a, b) => a.localeCompare(b));
+    for (const start of orderedStarts) {
+      if (visited.has(start)) {
+        continue;
+      }
+      const stack = [start];
+      const files = [];
+      while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === void 0 || visited.has(current)) {
+          continue;
+        }
+        visited.add(current);
+        files.push(current);
+        const neighbors = adjacency.get(current);
+        if (neighbors === void 0) {
+          continue;
+        }
+        for (const neighbor of neighbors) {
+          if (!visited.has(neighbor)) {
+            stack.push(neighbor);
+          }
+        }
+      }
+      if (files.length < 2) {
+        continue;
+      }
+      files.sort((a, b) => a.localeCompare(b));
+      const fileSet = new Set(files);
+      const componentPairs = selectedPairs.filter(
+        (pair) => fileSet.has(pair.fileA) && fileSet.has(pair.fileB)
+      );
+      const meanFileRisk = average(
+        files.map((filePath) => fileScoresByFile.get(filePath)?.normalizedScore ?? 0)
+      );
+      const meanCoupling = average(componentPairs.map((pair) => pair.couplingScore));
+      const score = round44(clamp01(meanFileRisk * 0.65 + meanCoupling * 0.35) * 100);
+      couplingClusterCount += 1;
+      clusters.push({
+        id: `coupling:${couplingClusterCount}`,
+        kind: "change_coupling",
+        files,
+        score
+      });
+    }
+  }
+  return clusters.sort(
+    (a, b) => b.score - a.score || a.kind.localeCompare(b.kind) || a.id.localeCompare(b.id)
+  );
+};
+var computeRiskSummary = (structural, evolution, external, config) => {
+  const dependencyComputation = computeDependencyScores(external, config);
+  const evolutionByFile = mapEvolutionByFile(evolution);
+  const evolutionScales = computeEvolutionScales(evolutionByFile, config);
+  const cycleFileSet = new Set(
+    structural.cycles.flatMap((cycle) => cycle.nodes.map((node) => normalizePath2(node)))
+  );
+  const fanInScale = buildQuantileScale(
+    structural.files.map((file) => logScale(file.fanIn)),
+    config.quantileClamp.lower,
+    config.quantileClamp.upper
+  );
+  const fanOutScale = buildQuantileScale(
+    structural.files.map((file) => logScale(file.fanOut)),
+    config.quantileClamp.lower,
+    config.quantileClamp.upper
+  );
+  const depthScale = buildQuantileScale(
+    structural.files.map((file) => file.depth),
+    config.quantileClamp.lower,
+    config.quantileClamp.upper
+  );
+  const dimensionWeights = normalizeWeights(config.dimensionWeights, {
+    structural: true,
+    evolution: evolution.available,
+    external: external.available
+  });
+  const fileRiskContexts = structural.files.map((file) => {
+    const filePath = normalizePath2(file.id);
+    const inCycle = cycleFileSet.has(filePath) ? 1 : 0;
+    const fanInRisk = normalizeWithScale(logScale(file.fanIn), fanInScale);
+    const fanOutRisk = normalizeWithScale(logScale(file.fanOut), fanOutScale);
+    const depthRisk = normalizeWithScale(file.depth, depthScale);
+    const structuralWeights = config.structuralFactorWeights;
+    const structuralFactor = clamp01(
+      fanInRisk * structuralWeights.fanIn + fanOutRisk * structuralWeights.fanOut + depthRisk * structuralWeights.depth + inCycle * structuralWeights.cycleParticipation
+    );
+    const structuralCentrality = clamp01((fanInRisk + fanOutRisk) / 2);
+    let evolutionFactor = 0;
+    const evolutionMetrics = evolutionByFile.get(filePath);
+    if (evolution.available && evolutionMetrics !== void 0) {
+      const frequencyRisk = normalizeWithScale(
+        logScale(evolutionMetrics.commitCount),
+        evolutionScales.commitCount
+      );
+      const churnRisk = normalizeWithScale(
+        logScale(evolutionMetrics.churnTotal),
+        evolutionScales.churnTotal
+      );
+      const volatilityRisk = clamp01(evolutionMetrics.recentVolatility);
+      const ownershipConcentrationRisk = clamp01(evolutionMetrics.topAuthorShare);
+      const busFactorRisk = clamp01(1 - normalizeWithScale(evolutionMetrics.busFactor, evolutionScales.busFactor));
+      const evolutionWeights = config.evolutionFactorWeights;
+      evolutionFactor = clamp01(
+        frequencyRisk * evolutionWeights.frequency + churnRisk * evolutionWeights.churn + volatilityRisk * evolutionWeights.recentVolatility + ownershipConcentrationRisk * evolutionWeights.ownershipConcentration + busFactorRisk * evolutionWeights.busFactorRisk
+      );
+    }
+    const dependencyAffinity = clamp01(structuralCentrality * 0.6 + evolutionFactor * 0.4);
+    const externalFactor = external.available ? clamp01(dependencyComputation.repositoryExternalPressure * dependencyAffinity) : 0;
+    const baseline = structuralFactor * dimensionWeights.structural + evolutionFactor * dimensionWeights.evolution + externalFactor * dimensionWeights.external;
+    const interactions = [
+      structuralFactor * evolutionFactor * config.interactionWeights.structuralEvolution,
+      structuralCentrality * evolutionFactor * config.interactionWeights.centralInstability,
+      externalFactor * Math.max(structuralFactor, evolutionFactor) * config.interactionWeights.dependencyAmplification
+    ];
+    const normalizedScore = saturatingComposite(baseline, interactions);
+    return {
+      file: filePath,
+      score: round44(normalizedScore * 100),
+      normalizedScore: round44(normalizedScore),
+      factors: {
+        structural: round44(structuralFactor),
+        evolution: round44(evolutionFactor),
+        external: round44(externalFactor)
+      },
+      structuralCentrality: round44(structuralCentrality)
+    };
+  }).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
+  const fileScores = fileRiskContexts.map((context) => ({
+    file: context.file,
+    score: context.score,
+    normalizedScore: context.normalizedScore,
+    factors: context.factors
+  }));
+  const fileScoresByFile = new Map(fileScores.map((fileScore) => [fileScore.file, fileScore]));
+  const hotspotsCount = Math.min(
+    config.hotspotMaxFiles,
+    Math.max(config.hotspotMinFiles, Math.ceil(fileScores.length * config.hotspotTopPercent))
+  );
+  const hotspots = fileScores.slice(0, hotspotsCount).map((fileScore) => ({
+    file: fileScore.file,
+    score: fileScore.score,
+    factors: fileScore.factors
+  }));
+  const moduleFiles = /* @__PURE__ */ new Map();
+  for (const fileScore of fileScores) {
+    const moduleName = inferModuleName(fileScore.file, config);
+    const values = moduleFiles.get(moduleName) ?? [];
+    values.push(fileScore.normalizedScore);
+    moduleFiles.set(moduleName, values);
+  }
+  const moduleScores = [...moduleFiles.entries()].map(([module, values]) => {
+    const averageScore = average(values);
+    const peakScore = values.reduce((max, value) => Math.max(max, value), 0);
+    const normalizedScore = clamp01(averageScore * 0.65 + peakScore * 0.35);
+    return {
+      module,
+      score: round44(normalizedScore * 100),
+      normalizedScore: round44(normalizedScore),
+      fileCount: values.length
+    };
+  }).sort((a, b) => b.score - a.score || a.module.localeCompare(b.module));
+  const fragileClusters = buildFragileClusters(structural, evolution, fileScoresByFile, config);
+  const externalPressures = fileScores.map((fileScore) => fileScore.factors.external);
+  const pressureThreshold = Math.max(
+    config.amplificationZone.pressureFloor,
+    percentile(externalPressures, config.amplificationZone.percentileThreshold)
+  );
+  const dependencyAmplificationZones = fileScores.map((fileScore) => {
+    const intensity = clamp01(
+      fileScore.factors.external * Math.max(fileScore.factors.structural, fileScore.factors.evolution)
+    );
+    const normalizedZoneScore = clamp01(intensity * 0.7 + fileScore.normalizedScore * 0.3);
+    return {
+      file: fileScore.file,
+      score: round44(normalizedZoneScore * 100),
+      externalPressure: fileScore.factors.external
+    };
+  }).filter((zone) => external.available && zone.externalPressure >= pressureThreshold).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, config.amplificationZone.maxZones).map((zone) => ({
+    ...zone,
+    externalPressure: round44(zone.externalPressure)
+  }));
+  const structuralDimension = average(fileScores.map((fileScore) => fileScore.factors.structural));
+  const evolutionDimension = average(fileScores.map((fileScore) => fileScore.factors.evolution));
+  const externalDimension = dependencyComputation.repositoryExternalPressure;
+  const topCentralSlice = Math.max(1, Math.ceil(fileRiskContexts.length * 0.1));
+  const criticalInstability = average(
+    [...fileRiskContexts].sort(
+      (a, b) => b.structuralCentrality * b.factors.evolution - a.structuralCentrality * a.factors.evolution || a.file.localeCompare(b.file)
+    ).slice(0, topCentralSlice).map((context) => context.structuralCentrality * context.factors.evolution)
+  );
+  const dependencyAmplification = average(
+    dependencyAmplificationZones.map(
+      (zone) => clamp01(zone.externalPressure * zone.score / 100)
+    )
+  );
+  const repositoryBaseline = structuralDimension * dimensionWeights.structural + evolutionDimension * dimensionWeights.evolution + externalDimension * dimensionWeights.external;
+  const repositoryNormalizedScore = saturatingComposite(repositoryBaseline, [
+    structuralDimension * evolutionDimension * config.interactionWeights.structuralEvolution,
+    criticalInstability * config.interactionWeights.centralInstability,
+    dependencyAmplification * config.interactionWeights.dependencyAmplification
+  ]);
+  return {
+    repositoryScore: round44(repositoryNormalizedScore * 100),
+    normalizedScore: round44(repositoryNormalizedScore),
+    hotspots,
+    fragileClusters,
+    dependencyAmplificationZones,
+    fileScores,
+    moduleScores,
+    dependencyScores: dependencyComputation.dependencyScores
+  };
+};
+var mergeConfig = (overrides) => {
+  if (overrides === void 0) {
+    return DEFAULT_RISK_ENGINE_CONFIG;
+  }
+  return {
+    ...DEFAULT_RISK_ENGINE_CONFIG,
+    ...overrides,
+    dimensionWeights: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.dimensionWeights,
+      ...overrides.dimensionWeights
+    },
+    interactionWeights: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.interactionWeights,
+      ...overrides.interactionWeights
+    },
+    structuralFactorWeights: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.structuralFactorWeights,
+      ...overrides.structuralFactorWeights
+    },
+    evolutionFactorWeights: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.evolutionFactorWeights,
+      ...overrides.evolutionFactorWeights
+    },
+    dependencyFactorWeights: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.dependencyFactorWeights,
+      ...overrides.dependencyFactorWeights
+    },
+    quantileClamp: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.quantileClamp,
+      ...overrides.quantileClamp
+    },
+    couplingCluster: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.couplingCluster,
+      ...overrides.couplingCluster
+    },
+    amplificationZone: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.amplificationZone,
+      ...overrides.amplificationZone
+    },
+    module: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.module,
+      ...overrides.module
+    },
+    dependencySignals: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.dependencySignals,
+      ...overrides.dependencySignals
+    },
+    externalDimension: {
+      ...DEFAULT_RISK_ENGINE_CONFIG.externalDimension,
+      ...overrides.externalDimension
+    }
+  };
+};
+var computeRepositoryRiskSummary = (input) => {
+  const config = mergeConfig(input.config);
+  return computeRiskSummary(input.structural, input.evolution, input.external, config);
 };
 
 // src/application/run-analyze-command.ts
 var resolveTargetPath = (inputPath, cwd) => resolve2(cwd, inputPath ?? ".");
-var runAnalyzeCommand = async (inputPath, authorIdentityMode) => {
+var createExternalProgressReporter = (logger) => {
+  let lastLoggedProgress = 0;
+  return (event) => {
+    switch (event.stage) {
+      case "package_json_loaded":
+        logger.debug("external: package.json loaded");
+        break;
+      case "lockfile_selected":
+        logger.info(`external: lockfile selected (${event.kind})`);
+        break;
+      case "lockfile_parsed":
+        logger.info(
+          `external: parsed ${event.dependencyNodes} locked dependencies (${event.directDependencies} direct)`
+        );
+        break;
+      case "metadata_fetch_started":
+        logger.info(`external: fetching dependency metadata (${event.total} packages)`);
+        break;
+      case "metadata_fetch_progress": {
+        const currentPercent = event.total === 0 ? 100 : Math.floor(event.completed / event.total * 100);
+        if (event.completed === event.total || event.completed === 1 || event.completed - lastLoggedProgress >= 25) {
+          lastLoggedProgress = event.completed;
+          logger.info(
+            `external: metadata progress ${event.completed}/${event.total} (${currentPercent}%)`
+          );
+          logger.debug(`external: last package processed ${event.packageName}`);
+        }
+        break;
+      }
+      case "metadata_fetch_completed":
+        logger.info(`external: metadata fetch completed (${event.total} packages)`);
+        break;
+      case "summary_built":
+        logger.info(
+          `external: summary built (${event.totalDependencies} total, ${event.directDependencies} direct)`
+        );
+        break;
+    }
+  };
+};
+var createStructuralProgressReporter = (logger) => {
+  let lastProcessed = 0;
+  return (event) => {
+    switch (event.stage) {
+      case "files_discovered":
+        logger.info(`structural: discovered ${event.totalSourceFiles} source files`);
+        break;
+      case "program_created":
+        logger.debug(`structural: TypeScript program created (${event.totalSourceFiles} files)`);
+        break;
+      case "file_processed":
+        if (event.processed === event.total || event.processed === 1 || event.processed - lastProcessed >= 50) {
+          lastProcessed = event.processed;
+          logger.info(`structural: resolved ${event.processed}/${event.total} files`);
+          logger.debug(`structural: last file processed ${event.filePath}`);
+        }
+        break;
+      case "edges_resolved":
+        logger.info(`structural: resolved ${event.totalEdges} dependency edges`);
+        break;
+    }
+  };
+};
+var createEvolutionProgressReporter = (logger) => {
+  let lastParsedRecords = 0;
+  return (event) => {
+    switch (event.stage) {
+      case "checking_git_repository":
+        logger.debug("evolution: checking git repository");
+        break;
+      case "not_git_repository":
+        logger.warn("evolution: target path is not a git repository");
+        break;
+      case "loading_commit_history":
+        logger.info("evolution: loading git history");
+        break;
+      case "history":
+        if (event.event.stage === "git_log_received") {
+          logger.info(`evolution: git log loaded (${event.event.bytes} bytes)`);
+          break;
+        }
+        if (event.event.stage === "git_log_parsed") {
+          logger.info(`evolution: parsed ${event.event.commits} commits`);
+          break;
+        }
+        if (event.event.stage === "git_log_parse_progress" && (event.event.parsedRecords === event.event.totalRecords || event.event.parsedRecords === 1 || event.event.parsedRecords - lastParsedRecords >= 500)) {
+          lastParsedRecords = event.event.parsedRecords;
+          const currentPercent = event.event.totalRecords === 0 ? 100 : Math.floor(event.event.parsedRecords / event.event.totalRecords * 100);
+          logger.info(
+            `evolution: parse progress ${event.event.parsedRecords}/${event.event.totalRecords} (${currentPercent}%)`
+          );
+        }
+        break;
+      case "computing_metrics":
+        logger.info("evolution: computing metrics");
+        break;
+      case "analysis_completed":
+        logger.debug(`evolution: analysis completed (available=${event.available})`);
+        break;
+    }
+  };
+};
+var runAnalyzeCommand = async (inputPath, authorIdentityMode, logger = createSilentLogger()) => {
   const invocationCwd = process.env["INIT_CWD"] ?? process.cwd();
   const targetPath = resolveTargetPath(inputPath, invocationCwd);
-  const structural = buildProjectGraphSummary({ projectPath: targetPath });
+  logger.info(`analyzing repository: ${targetPath}`);
+  logger.info("building structural graph");
+  const structural = buildProjectGraphSummary({
+    projectPath: targetPath,
+    onProgress: createStructuralProgressReporter(logger)
+  });
+  logger.debug(
+    `structural metrics: nodes=${structural.metrics.nodeCount}, edges=${structural.metrics.edgeCount}, cycles=${structural.metrics.cycleCount}`
+  );
+  logger.info(`analyzing git evolution (author identity: ${authorIdentityMode})`);
   const evolution = analyzeRepositoryEvolutionFromGit({
     repositoryPath: targetPath,
     config: { authorIdentityMode }
+  }, createEvolutionProgressReporter(logger));
+  if (evolution.available) {
+    logger.debug(
+      `evolution metrics: commits=${evolution.metrics.totalCommits}, files=${evolution.metrics.totalFiles}, hotspotThreshold=${evolution.metrics.hotspotThresholdCommitCount}`
+    );
+  } else {
+    logger.warn(`evolution analysis unavailable: ${evolution.reason}`);
+  }
+  logger.info("analyzing external dependencies");
+  const external = await analyzeDependencyExposureFromProject(
+    { repositoryPath: targetPath },
+    createExternalProgressReporter(logger)
+  );
+  if (external.available) {
+    logger.debug(
+      `external metrics: total=${external.metrics.totalDependencies}, direct=${external.metrics.directDependencies}, transitive=${external.metrics.transitiveDependencies}`
+    );
+  } else {
+    logger.warn(`external analysis unavailable: ${external.reason}`);
+  }
+  logger.info("computing risk summary");
+  const risk = computeRepositoryRiskSummary({
+    structural,
+    evolution,
+    external
   });
-  const external = await analyzeDependencyExposureFromProject({ repositoryPath: targetPath });
+  logger.info(`analysis completed (repositoryScore=${risk.repositoryScore})`);
   const summary = {
     structural,
     evolution,
-    external
+    external,
+    risk
   };
-  return JSON.stringify(summary, null, 2);
+  return summary;
 };
 
 // src/index.ts
@@ -1628,14 +2563,35 @@ program.command("analyze").argument("[path]", "path to the project to analyze").
     "--author-identity <mode>",
     "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
   ).choices(["likely_merge", "strict_email"]).default("likely_merge")
-).action(async (path, options) => {
-  const output = await runAnalyzeCommand(path, options.authorIdentity);
-  process.stdout.write(`${output}
+).addOption(
+  new Option(
+    "--log-level <level>",
+    "log verbosity: silent, error, warn, info, debug (logs are written to stderr)"
+  ).choices(["silent", "error", "warn", "info", "debug"]).default(parseLogLevel(process.env["CODESENTINEL_LOG_LEVEL"]))
+).addOption(
+  new Option(
+    "--output <mode>",
+    "output mode: summary (default) or json (full analysis object)"
+  ).choices(["summary", "json"]).default("summary")
+).option("--json", "shortcut for --output json").action(
+  async (path, options) => {
+    const logger = createStderrLogger(options.logLevel);
+    const summary = await runAnalyzeCommand(path, options.authorIdentity, logger);
+    const outputMode = options.json === true ? "json" : options.output;
+    process.stdout.write(`${formatAnalyzeOutput(summary, outputMode)}
 `);
-});
+  }
+);
 if (process.argv.length <= 2) {
   program.outputHelp();
   process.exit(0);
 }
-await program.parseAsync(process.argv);
+var executablePath = process.argv[0] ?? "";
+var scriptPath = process.argv[1] ?? "";
+var argv = process.argv[2] === "--" ? [executablePath, scriptPath, ...process.argv.slice(3)] : process.argv;
+if (argv.length <= 2) {
+  program.outputHelp();
+  process.exit(0);
+}
+await program.parseAsync(argv);
 //# sourceMappingURL=index.js.map