get_codebase_health

Instructions

Implementation Reference

• src/health/store.ts:95-127 (helper)

  Helper functions: readHealthFile reads and validates the health.json artifact, normalizeHealthLookupKey normalizes file paths for lookup, and indexHealthByFile builds a Map for O(1) file access.

  export async function readHealthFile(healthPath: string): Promise<CodebaseHealthArtifact | null> {
    try {
      const content = await fs.readFile(healthPath, 'utf-8');
      return normalizeHealthArtifact(JSON.parse(content));
    } catch {
      return null;
    }
  }
  
  export function normalizeHealthLookupKey(filePath: string, rootPath?: string): string {
    const normalized = filePath.replace(/\\/g, '/').replace(/^\.\//, '');
    if (!rootPath) {
      return normalized;
    }
    const normalizedRoot = rootPath.replace(/\\/g, '/').replace(/\/$/, '');
    if (normalized.startsWith(normalizedRoot)) {
      return normalized.slice(normalizedRoot.length).replace(/^\//, '');
    }
    return normalized;
  }
  
  export function indexHealthByFile(
    artifact: CodebaseHealthArtifact | null,
    rootPath?: string
  ): Map<string, CodebaseHealthFile> {
    const map = new Map<string, CodebaseHealthFile>();
    if (!artifact) return map;
    for (const fileHealth of artifact.files) {
      map.set(normalizeHealthLookupKey(fileHealth.file, rootPath), fileHealth);
    }
    return map;
  }

• src/health/derive.ts:168-207 (helper)

  deriveCodebaseHealth generates the health artifact from code chunks and dependency graph, computing risk levels (high/medium/low) based on metrics like cycle count, fan-in, hotspot rank, and cyclomatic complexity.

  export function deriveCodebaseHealth({
    buildId,
    formatVersion,
    generatedAt,
    chunks,
    graph
  }: DeriveCodebaseHealthParams): CodebaseHealthArtifact {
    const fileMetrics = collectFileMetrics(chunks, graph);
    const files = Array.from(fileMetrics.entries())
      .map(([file, metrics]) => {
        const health = getHealthLevel(metrics);
        return {
          ...health,
          file
        };
      })
      .sort((a, b) => {
        const priority = { high: 0, medium: 1, low: 2 };
        const levelDelta = priority[a.level] - priority[b.level];
        if (levelDelta !== 0) return levelDelta;
        if (b.score !== a.score) return b.score - a.score;
        return a.file.localeCompare(b.file);
      });
  
    const highRiskFiles = files.filter((file) => file.level === 'high').length;
    const mediumRiskFiles = files.filter((file) => file.level === 'medium').length;
    const lowRiskFiles = files.length - highRiskFiles - mediumRiskFiles;
  
    return {
      header: { buildId, formatVersion },
      generatedAt,
      summary: {
        files: files.length,
        highRiskFiles,
        mediumRiskFiles,
        lowRiskFiles
      },
      files
    };
  }