@kb-labs/quality-core 2.94.0 → 2.98.0

package/dist/health/index.js

@@ -1,130 +1,102 @@
-import { readFile, access } from 'fs/promises';
-import { join } from 'path';
-import globby from 'globby';
+import { DIMENSION_WEIGHTS, HEALTH_GRADES } from '@kb-labs/quality-contracts';
 
 // src/health/calculate-health.ts
-async function checkDuplicateDependencies(rootDir, pkgFiles) {
-  const packageJsonFiles = pkgFiles ?? await globby("**/package.json", {
-    cwd: rootDir,
-    ignore: ["**/node_modules/**", "**/.git/**"],
-    absolute: true
-  });
-  const depVersions = /* @__PURE__ */ new Map();
-  const contents = await Promise.all(
-    packageJsonFiles.map((f) => readFile(f, "utf-8").catch(() => null))
-  );
-  for (const content of contents) {
-    if (!content) {
-      continue;
-    }
-    try {
-      const pkg = JSON.parse(content);
-      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-      for (const [name, version] of Object.entries(allDeps)) {
-        if (typeof version !== "string") {
-          continue;
-        }
-        if (!depVersions.has(name)) {
-          depVersions.set(name, /* @__PURE__ */ new Set());
-        }
-        depVersions.get(name).add(version);
-      }
-    } catch {
+function gradeFromScore(score) {
+  for (const [g, { min }] of Object.entries(HEALTH_GRADES)) {
+    if (score >= min) {
+      return g;
     }
   }
-  const duplicates = Array.from(depVersions.entries()).filter(
-    ([, versions]) => versions.size > 1
-  );
-  if (duplicates.length === 0) {
-    return null;
-  }
-  const penalty = Math.min(duplicates.length * 2, 30);
-  return {
-    type: "duplicate",
-    severity: duplicates.length > 20 ? "high" : duplicates.length > 10 ? "medium" : "low",
-    message: `Found ${duplicates.length} duplicate dependencies with different versions`,
-    count: duplicates.length,
-    penalty
-  };
+  return "F";
 }
-async function checkMissingReadmes(rootDir, packageJsonFiles) {
-  const pkgFiles = packageJsonFiles ?? await globby("**/package.json", {
-    cwd: rootDir,
-    ignore: ["**/node_modules/**", "**/.git/**", "package.json"],
-    absolute: true
-  });
-  const hasReadme = async (pkgPath) => {
-    const dir = join(pkgPath, "..");
-    for (const name of ["README.md", "readme.md", "Readme.md"]) {
-      try {
-        await access(join(dir, name));
-        return true;
-      } catch {
-      }
-    }
-    return false;
-  };
-  const results = await Promise.all(pkgFiles.map(hasReadme));
-  const missingCount = results.filter((has) => !has).length;
-  if (missingCount === 0) {
-    return null;
-  }
-  const penalty = Math.min(missingCount, 15);
-  return {
-    type: "readme",
-    severity: missingCount > 20 ? "high" : missingCount > 10 ? "medium" : "low",
-    message: `Found ${missingCount} packages without README`,
-    count: missingCount,
-    penalty
-  };
+function clamp(n) {
+  return Math.max(0, Math.min(100, Math.round(n)));
 }
-function calculateHealthScore(issues) {
-  const baseScore = 100;
-  const totalPenalty = issues.reduce((sum, issue) => sum + issue.penalty, 0);
-  return Math.max(0, baseScore - totalPenalty);
+function scoreArchitecture(layering, coupling, thresholds) {
+  const details = [];
+  const layeringPenalty = Math.min(layering.totalViolations * 5, 60);
+  if (layering.totalViolations > 0) {
+    details.push(`${layering.totalViolations} layering violation(s) in ${layering.affectedPackages.length} package(s)`);
+  }
+  const highInstability = coupling.packages.filter((p) => p.instability > thresholds.instability);
+  const couplingPenalty = Math.min(highInstability.length * 3, 30);
+  if (highInstability.length > 0) {
+    details.push(`${highInstability.length} package(s) with instability > ${thresholds.instability}`);
+  }
+  const score = clamp(100 - layeringPenalty - couplingPenalty);
+  return { score, grade: gradeFromScore(score), details };
 }
-function scoreToGrade(score) {
-  if (score >= 90) {
-    return "A";
+function scoreTypeScript(types) {
+  const details = [];
+  const totalAny = types.packages.reduce((s, p) => s + p.anyCount, 0);
+  const anyPenalty = Math.min(totalAny * 0.5, 50);
+  if (totalAny > 0) {
+    details.push(`${totalAny} \`any\` usage(s)`);
   }
-  if (score >= 80) {
-    return "B";
+  const totalIgnore = types.packages.reduce((s, p) => s + p.tsIgnoreCount, 0);
+  const ignorePenalty = Math.min(totalIgnore * 2, 30);
+  if (totalIgnore > 0) {
+    details.push(`${totalIgnore} @ts-ignore(s)`);
   }
-  if (score >= 70) {
-    return "C";
+  const errorPenalty = Math.min(types.totalErrors * 3, 20);
+  if (types.totalErrors > 0) {
+    details.push(`${types.totalErrors} type error(s)`);
   }
-  if (score >= 60) {
-    return "D";
+  const score = clamp(100 - anyPenalty - ignorePenalty - errorPenalty);
+  return { score, grade: gradeFromScore(score), details };
+}
+function scoreDeadCode(knip) {
+  const details = [];
+  const filePenalty = Math.min(knip.unusedFiles.length * 2, 50);
+  if (knip.unusedFiles.length > 0) {
+    details.push(`${knip.unusedFiles.length} unused file(s)`);
   }
-  return "F";
+  const exportPenalty = Math.min(knip.unusedExports.length * 0.5, 30);
+  if (knip.unusedExports.length > 0) {
+    details.push(`${knip.unusedExports.length} unused export(s)`);
+  }
+  const score = clamp(100 - filePenalty - exportPenalty);
+  return { score, grade: gradeFromScore(score), details };
 }
-async function calculateHealth(rootDir) {
-  const issues = [];
-  const packageJsonFiles = await globby("**/package.json", {
-    cwd: rootDir,
-    ignore: ["**/node_modules/**", "**/.git/**", "**/.kb/**", "**/dist/**"],
-    absolute: true,
-    deep: 6
-  });
-  const [duplicatesIssue, readmesIssue] = await Promise.all([
-    checkDuplicateDependencies(rootDir, packageJsonFiles),
-    checkMissingReadmes(rootDir, packageJsonFiles)
-  ]);
-  if (duplicatesIssue) {
-    issues.push(duplicatesIssue);
+function scoreDepHygiene(knip) {
+  const details = [];
+  const unusedPenalty = Math.min(knip.unusedDependencies.length * 5, 50);
+  if (knip.unusedDependencies.length > 0) {
+    details.push(`${knip.unusedDependencies.length} unused dep(s)`);
   }
-  if (readmesIssue) {
-    issues.push(readmesIssue);
+  const unlistedPenalty = Math.min(knip.unlistedDependencies.length * 10, 40);
+  if (knip.unlistedDependencies.length > 0) {
+    details.push(`${knip.unlistedDependencies.length} unlisted dep(s)`);
   }
-  const score = calculateHealthScore(issues);
-  const grade = scoreToGrade(score);
-  return {
-    score,
-    grade,
-    issues
+  const score = clamp(100 - unusedPenalty - unlistedPenalty);
+  return { score, grade: gradeFromScore(score), details };
+}
+function scoreTestCoverage(avgCoverage) {
+  if (avgCoverage === null) {
+    return { score: 100, grade: "A", details: ["no coverage data \u2014 skipped"] };
+  }
+  const score = clamp(avgCoverage);
+  const details = avgCoverage < 80 ? [`avg coverage ${avgCoverage.toFixed(1)}%`] : [];
+  return { score, grade: gradeFromScore(score), details };
+}
+function calculateHealth(input) {
+  const { layering, coupling, types, knip, avgTestCoverage, thresholds } = input;
+  const dimensions = {
+    architecture: scoreArchitecture(layering, coupling, thresholds),
+    typescript: scoreTypeScript(types),
+    deadCode: scoreDeadCode(knip),
+    depHygiene: scoreDepHygiene(knip),
+    testCoverage: scoreTestCoverage(avgTestCoverage)
   };
+  const score = clamp(
+    Object.entries(DIMENSION_WEIGHTS).reduce(
+      (sum, [key, weight]) => sum + dimensions[key].score * weight,
+      0
+    )
+  );
+  return { score, grade: gradeFromScore(score), dimensions };
 }
 
-export { calculateHealth, calculateHealthScore, checkDuplicateDependencies, checkMissingReadmes, scoreToGrade };
+export { calculateHealth };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/health/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/health/calculate-health.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Calculate monorepo health score\n *\n * Atomic functions for health checks and scoring.\n */\n\nimport { readFile, access } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport globby from 'globby';\n\nexport interface HealthResult {\n  score: number;\n  grade: 'A' | 'B' | 'C' | 'D' | 'F';\n  issues: HealthIssue[];\n}\n\nexport interface HealthIssue {\n  type: 'duplicate' | 'unused' | 'missing' | 'structure' | 'readme';\n  severity: 'high' | 'medium' | 'low';\n  message: string;\n  count: number;\n  penalty: number;\n}\n\n/**\n * Check for duplicate dependencies across packages\n */\nexport async function checkDuplicateDependencies(rootDir: string, pkgFiles?: string[]): Promise<HealthIssue | null> {\n  const packageJsonFiles = pkgFiles ?? await globby('**/package.json', {\n    cwd: rootDir,\n    ignore: ['**/node_modules/**', '**/.git/**'],\n    absolute: true,\n  });\n\n  // Read all package.json files in parallel\n  const depVersions = new Map<string, Set<string>>();\n  const contents = await Promise.all(\n    packageJsonFiles.map(f => readFile(f, 'utf-8').catch(() => null))\n  );\n\n  for (const content of contents) {\n    if (!content) {continue;}\n    try {\n      const pkg = JSON.parse(content);\n      const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };\n      for (const [name, version] of Object.entries(allDeps)) {\n        if (typeof version !== 'string') {continue;}\n        if (!depVersions.has(name)) {depVersions.set(name, new Set());}\n        depVersions.get(name)!.add(version);\n      }\n    } catch { /* skip invalid */ }\n  }\n\n  // Count duplicates (deps with more than 1 version)\n  const duplicates = Array.from(depVersions.entries()).filter(\n    ([, versions]) => versions.size > 1\n  );\n\n  if (duplicates.length === 0) {return null;}\n\n  const penalty = Math.min(duplicates.length * 2, 30); // Max -30 points\n\n  return {\n    type: 'duplicate',\n    severity: duplicates.length > 20 ? 'high' : duplicates.length > 10 ? 'medium' : 'low',\n    message: `Found ${duplicates.length} duplicate dependencies with different versions`,\n    count: duplicates.length,\n    penalty,\n  };\n}\n\n/**\n * Check for packages missing README\n */\nexport async function checkMissingReadmes(rootDir: string, packageJsonFiles?: string[]): Promise<HealthIssue | null> {\n  const pkgFiles = packageJsonFiles ?? await globby('**/package.json', {\n    cwd: rootDir,\n    ignore: ['**/node_modules/**', '**/.git/**', 'package.json'],\n    absolute: true,\n  });\n\n  const hasReadme = async (pkgPath: string): Promise<boolean> => {\n    const dir = join(pkgPath, '..');\n    for (const name of ['README.md', 'readme.md', 'Readme.md']) {\n      try {\n        await access(join(dir, name));\n        return true;\n      } catch { /* not found */ }\n    }\n    return false;\n  };\n\n  const results = await Promise.all(pkgFiles.map(hasReadme));\n  const missingCount = results.filter(has => !has).length;\n\n  if (missingCount === 0) {return null;}\n\n  const penalty = Math.min(missingCount, 15); // Max -15 points\n\n  return {\n    type: 'readme',\n    severity: missingCount > 20 ? 'high' : missingCount > 10 ? 'medium' : 'low',\n    message: `Found ${missingCount} packages without README`,\n    count: missingCount,\n    penalty,\n  };\n}\n\n/**\n * Calculate health score from issues\n */\nexport function calculateHealthScore(issues: HealthIssue[]): number {\n  const baseScore = 100;\n  const totalPenalty = issues.reduce((sum, issue) => sum + issue.penalty, 0);\n\n  return Math.max(0, baseScore - totalPenalty);\n}\n\n/**\n * Convert score to letter grade\n */\nexport function scoreToGrade(score: number): 'A' | 'B' | 'C' | 'D' | 'F' {\n  if (score >= 90) {return 'A';}\n  if (score >= 80) {return 'B';}\n  if (score >= 70) {return 'C';}\n  if (score >= 60) {return 'D';}\n  return 'F';\n}\n\n/**\n * Calculate complete health report\n */\nexport async function calculateHealth(rootDir: string): Promise<HealthResult> {\n  const issues: HealthIssue[] = [];\n\n  // Single globby scan shared by all checks\n  // depth=6 covers workspace/subrepo/packages/pkg-name/src/... without scanning deep trees\n  const packageJsonFiles = await globby('**/package.json', {\n    cwd: rootDir,\n    ignore: ['**/node_modules/**', '**/.git/**', '**/.kb/**', '**/dist/**'],\n    absolute: true,\n    deep: 6,\n  });\n\n  const [duplicatesIssue, readmesIssue] = await Promise.all([\n    checkDuplicateDependencies(rootDir, packageJsonFiles),\n    checkMissingReadmes(rootDir, packageJsonFiles),\n  ]);\n\n  if (duplicatesIssue) {issues.push(duplicatesIssue);}\n  if (readmesIssue) {issues.push(readmesIssue);}\n\n  const score = calculateHealthScore(issues);\n  const grade = scoreToGrade(score);\n\n  return {\n    score,\n    grade,\n    issues,\n  };\n}\n"]}
+{"version":3,"sources":["../../src/health/calculate-health.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Multidimensional health score calculation.\n *\n * Composite score = weighted average of 5 dimensions:\n *   architecture  30% — layering violations + avg instability\n *   typescript    25% — any count + ts-ignore count\n *   deadCode      20% — unused files + unused exports from knip\n *   depHygiene    15% — unused + unlisted dependencies from knip\n *   testCoverage  10% — avg test coverage % (optional, defaults to 100 if unavailable)\n */\n\nimport { DIMENSION_WEIGHTS, HEALTH_GRADES } from '@kb-labs/quality-contracts';\nimport type {\n  HealthScore,\n  DimensionScore,\n  DimensionScores,\n  LayeringReport,\n  CouplingReport,\n  KnipReport,\n  TypeAnalysisResult,\n  QualityThresholds,\n} from '@kb-labs/quality-contracts';\n\nfunction gradeFromScore(score: number): HealthScore['grade'] {\n  for (const [g, { min }] of Object.entries(HEALTH_GRADES) as [HealthScore['grade'], { min: number }][]) {\n    if (score >= min) {return g;}\n  }\n  return 'F';\n}\n\nfunction clamp(n: number): number {\n  return Math.max(0, Math.min(100, Math.round(n)));\n}\n\n// ── Dimension scorers ─────────────────────────────────────────────────────────\n\nfunction scoreArchitecture(\n  layering: LayeringReport,\n  coupling: CouplingReport,\n  thresholds: QualityThresholds\n): DimensionScore {\n  const details: string[] = [];\n\n  // Each violation costs 5 points, max -60\n  const layeringPenalty = Math.min(layering.totalViolations * 5, 60);\n  if (layering.totalViolations > 0) {\n    details.push(`${layering.totalViolations} layering violation(s) in ${layering.affectedPackages.length} package(s)`);\n  }\n\n  // Packages above instability threshold cost 3 points each, max -30\n  const highInstability = coupling.packages.filter(p => p.instability > thresholds.instability);\n  const couplingPenalty = Math.min(highInstability.length * 3, 30);\n  if (highInstability.length > 0) {\n    details.push(`${highInstability.length} package(s) with instability > ${thresholds.instability}`);\n  }\n\n  const score = clamp(100 - layeringPenalty - couplingPenalty);\n  return { score, grade: gradeFromScore(score), details };\n}\n\nfunction scoreTypeScript(types: TypeAnalysisResult): DimensionScore {\n  const details: string[] = [];\n\n  const totalAny = types.packages.reduce((s, p) => s + p.anyCount, 0);\n  const anyPenalty = Math.min(totalAny * 0.5, 50);\n  if (totalAny > 0) {details.push(`${totalAny} \\`any\\` usage(s)`);}\n\n  const totalIgnore = types.packages.reduce((s, p) => s + p.tsIgnoreCount, 0);\n  const ignorePenalty = Math.min(totalIgnore * 2, 30);\n  if (totalIgnore > 0) {details.push(`${totalIgnore} @ts-ignore(s)`);}\n\n  const errorPenalty = Math.min(types.totalErrors * 3, 20);\n  if (types.totalErrors > 0) {details.push(`${types.totalErrors} type error(s)`);}\n\n  const score = clamp(100 - anyPenalty - ignorePenalty - errorPenalty);\n  return { score, grade: gradeFromScore(score), details };\n}\n\nfunction scoreDeadCode(knip: KnipReport): DimensionScore {\n  const details: string[] = [];\n\n  const filePenalty = Math.min(knip.unusedFiles.length * 2, 50);\n  if (knip.unusedFiles.length > 0) {details.push(`${knip.unusedFiles.length} unused file(s)`);}\n\n  const exportPenalty = Math.min(knip.unusedExports.length * 0.5, 30);\n  if (knip.unusedExports.length > 0) {details.push(`${knip.unusedExports.length} unused export(s)`);}\n\n  const score = clamp(100 - filePenalty - exportPenalty);\n  return { score, grade: gradeFromScore(score), details };\n}\n\nfunction scoreDepHygiene(knip: KnipReport): DimensionScore {\n  const details: string[] = [];\n\n  const unusedPenalty = Math.min(knip.unusedDependencies.length * 5, 50);\n  if (knip.unusedDependencies.length > 0) {details.push(`${knip.unusedDependencies.length} unused dep(s)`);}\n\n  const unlistedPenalty = Math.min(knip.unlistedDependencies.length * 10, 40);\n  if (knip.unlistedDependencies.length > 0) {details.push(`${knip.unlistedDependencies.length} unlisted dep(s)`);}\n\n  const score = clamp(100 - unusedPenalty - unlistedPenalty);\n  return { score, grade: gradeFromScore(score), details };\n}\n\nfunction scoreTestCoverage(avgCoverage: number | null): DimensionScore {\n  if (avgCoverage === null) {\n    return { score: 100, grade: 'A', details: ['no coverage data — skipped'] };\n  }\n  const score = clamp(avgCoverage);\n  const details = avgCoverage < 80 ? [`avg coverage ${avgCoverage.toFixed(1)}%`] : [];\n  return { score, grade: gradeFromScore(score), details };\n}\n\n// ── Public API ────────────────────────────────────────────────────────────────\n\nexport interface HealthInput {\n  layering: LayeringReport;\n  coupling: CouplingReport;\n  types: TypeAnalysisResult;\n  knip: KnipReport;\n  totalPackages: number;\n  /** Average test coverage in %, or null if not collected */\n  avgTestCoverage: number | null;\n  thresholds: QualityThresholds;\n}\n\nexport function calculateHealth(input: HealthInput): HealthScore {\n  const { layering, coupling, types, knip, avgTestCoverage, thresholds } = input;\n\n  const dimensions: DimensionScores = {\n    architecture: scoreArchitecture(layering, coupling, thresholds),\n    typescript: scoreTypeScript(types),\n    deadCode: scoreDeadCode(knip),\n    depHygiene: scoreDepHygiene(knip),\n    testCoverage: scoreTestCoverage(avgTestCoverage),\n  };\n\n  const score = clamp(\n    Object.entries(DIMENSION_WEIGHTS).reduce(\n      (sum, [key, weight]) => sum + dimensions[key as keyof DimensionScores].score * weight,\n      0\n    )\n  );\n\n  return { score, grade: gradeFromScore(score), dimensions };\n}\n"]}

package/dist/index.d.ts

@@ -1,9 +1,106 @@
 export { DependencyGraph, PackageNode, TopologicalSortResult, buildDependencyGraph, findCircularDependencies, getBuildOrderForPackage, getImpactAnalysis, getReverseDependencies, topologicalSort } from './graph/index.js';
 export { MonorepoStats, calculateLinesOfCode, calculateSize, calculateStats, countPackages, formatBytes } from './stats/index.js';
-export { HealthIssue, HealthResult, calculateHealth, calculateHealthScore, checkDuplicateDependencies, checkMissingReadmes, scoreToGrade } from './health/index.js';
+export { HealthInput, calculateHealth } from './health/index.js';
 export { DependencyAnalysis, DuplicateDependency, MissingDependency, UnusedDependency, VersionInfo, analyzeDependencies, analyzeDuplicateDependencies, analyzeMissingDependencies, analyzeUnusedDependencies } from './dependencies/index.js';
 export { BuildCheckOptions, BuildCheckResult, checkBuilds } from './builds/index.js';
 export { TypeAnalysisOptions, TypeAnalysisResult, analyzeTypes } from './types/index.js';
 export { TestRunOptions, TestRunResult, runTests } from './tests/index.js';
-export { buildFileImportGraph, collectEntryPoints, distPathToSrcPath, extractFileImports, findReachableFiles, listBackups, parseManifestHandlers, parseTsupEntries, removeDeadFiles, resolveRelativeImport, restoreFromBackup, scanDeadFiles } from './dead-code/index.js';
-import '@kb-labs/quality-contracts';
+export { buildFileImportGraph, collectEntryPoints, distPathToSrcPath, extractFileImports, findReachableFiles, listBackups, parseManifestHandlers, parseTsupEntries, removeDeadFiles, resolveRelativeImport, restoreFromBackup, runKnip, scanDeadFiles } from './dead-code/index.js';
+import { QualityLayerMap, LayeringReport, CouplingReport, QualitySnapshot, SnapshotHistory } from '@kb-labs/quality-contracts';
+import '@kb-labs/sdk';
+
+/**
+ * Workspace package scanner for flat monorepo layout.
+ *
+ * Discovers all packages by scanning top-level dirs (core/, sdk/, plugins/, etc.)
+ * and reading their package.json files.
+ */
+
+interface WorkspacePackage {
+    name: string;
+    dir: string;
+    packageJsonPath: string;
+    /** Layer index derived from path prefix */
+    layer: number;
+    deps: string[];
+    devDeps: string[];
+}
+/** Resolve layer index for a package dir relative to rootDir */
+declare function resolveLayer(pkgDir: string, rootDir: string, layerMap?: QualityLayerMap): number;
+/** Scan all workspace packages in a flat monorepo */
+declare function scanWorkspace(rootDir: string, layerMap?: QualityLayerMap): WorkspacePackage[];
+/** Build a map from package name → WorkspacePackage */
+declare function buildPackageMap(packages: WorkspacePackage[]): Map<string, WorkspacePackage>;
+
+/**
+ * Layering violation detector using TypeScript compiler API.
+ *
+ * Checks that imports respect the layer hierarchy defined in CLAUDE.md:
+ *   Layer 0: core/
+ *   Layer 1: sdk/ shared/
+ *   Layer 2: cli/ adapters/
+ *   Layer 3: plugins/
+ *   Layer 4: studio/ sites/
+ *
+ * A violation = a package at layer N importing a package at layer M where M > N.
+ */
+
+interface LayeringOptions {
+    rootDir: string;
+    layerMap?: QualityLayerMap;
+}
+/** Run layering analysis and return violations */
+declare function analyzeLayering(opts: LayeringOptions): Promise<LayeringReport>;
+
+/**
+ * Coupling metrics — Robert Martin's package metrics.
+ *
+ * Ca (afferent coupling): packages that depend on this package
+ * Ce (efferent coupling): packages this package depends on
+ * Instability = Ce / (Ca + Ce), range [0, 1]
+ *   0 = maximally stable (many dependents, no deps)
+ *   1 = maximally unstable (no dependents, many deps)
+ */
+
+interface CouplingOptions {
+    rootDir: string;
+    layerMap?: QualityLayerMap;
+    /** How many packages to include in mostUnstable / mostCoupled lists */
+    topN?: number;
+}
+declare function analyzeCoupling(opts: CouplingOptions): CouplingReport;
+
+interface BuildOrderOptions {
+    rootDir: string;
+    layerMap?: QualityLayerMap;
+    /** Limit to transitive deps of this package */
+    filterPackage?: string;
+}
+interface BuildOrderResult {
+    layers: string[][];
+    sorted: string[];
+    circular: string[][];
+    packageCount: number;
+    layerCount: number;
+    hasCircular: boolean;
+}
+declare function analyzeBuildOrder(opts: BuildOrderOptions): BuildOrderResult;
+
+interface SnapshotInput {
+    score: number;
+    grade: QualitySnapshot['grade'];
+    dimensions: QualitySnapshot['dimensions'];
+    counters: QualitySnapshot['counters'];
+    git: QualitySnapshot['git'];
+}
+declare class QualitySnapshotStore {
+    private readonly snapshotPath;
+    private readonly maxEntries;
+    constructor(rootDir: string, maxEntries?: number);
+    load(): QualitySnapshot[];
+    save(input: SnapshotInput): QualitySnapshot;
+    latest(): QualitySnapshot | null;
+    history(): SnapshotHistory;
+}
+
+export { type BuildOrderOptions, type BuildOrderResult, type CouplingOptions, type LayeringOptions, QualitySnapshotStore, type SnapshotInput, type WorkspacePackage, analyzeBuildOrder, analyzeCoupling, analyzeLayering, buildPackageMap, resolveLayer, scanWorkspace };