fcis 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { cli } from 'cleye';
-import { z } from 'zod';
 import chalk from 'chalk';
 import * as fs3 from 'fs';
 import * as path4 from 'path';
 import { Project, SyntaxKind } from 'ts-morph';
+import * as jsonc from 'jsonc-parser';
+import { z } from 'zod';
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
   get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
@@ -18,6 +19,31 @@ var DEFAULT_QUALITY_THRESHOLDS = {
   okThreshold: 70,
   reviewThreshold: 40
 };
+var INLINE_CALLBACK_METHODS = /* @__PURE__ */ new Set([
+  // Array methods
+  "map",
+  "filter",
+  "reduce",
+  "forEach",
+  "find",
+  "findIndex",
+  "some",
+  "every",
+  "flatMap",
+  "sort",
+  "toSorted",
+  // Promise methods
+  "then",
+  "catch",
+  "finally",
+  // Timing
+  "setTimeout",
+  "setInterval",
+  // Events
+  "addEventListener",
+  "on",
+  "once"
+]);
 function extractFunctions(sourceFile) {
   const functions = [];
   const filePath = sourceFile.getFilePath();
@@ -105,25 +131,54 @@ function extractFunctions(sourceFile) {
     if (node.getKind() === SyntaxKind.ArrowFunction) {
       const arrowFn = node;
       const parentContext = inferParentContext(arrowFn);
+      const isInlineCallback = isInlineCallbackToKnownHOF(parentContext);
+      const enclosingFunctionStartLine = isInlineCallback ? findEnclosingFunctionStartLine(arrowFn) : null;
       addFunction(
-        extractFunctionData(arrowFn, filePath, "arrow", parentContext, false)
+        extractFunctionData(
+          arrowFn,
+          filePath,
+          "arrow",
+          parentContext,
+          false,
+          isInlineCallback,
+          enclosingFunctionStartLine
+        )
       );
     } else if (node.getKind() === SyntaxKind.FunctionExpression) {
       const funcExpr = node;
       const parentContext = inferParentContext(funcExpr);
+      const isInlineCallback = isInlineCallbackToKnownHOF(parentContext);
+      const enclosingFunctionStartLine = isInlineCallback ? findEnclosingFunctionStartLine(funcExpr) : null;
       addFunction(
         extractFunctionData(
           funcExpr,
           filePath,
           "function-expression",
           parentContext,
-          false
+          false,
+          isInlineCallback,
+          enclosingFunctionStartLine
         )
       );
     }
   });
   return functions;
 }
+function isInlineCallbackToKnownHOF(parentContext) {
+  if (parentContext === null) return false;
+  return INLINE_CALLBACK_METHODS.has(parentContext);
+}
+function findEnclosingFunctionStartLine(node) {
+  let current = node.getParent();
+  while (current) {
+    const kind = current.getKind();
+    if (kind === SyntaxKind.FunctionDeclaration || kind === SyntaxKind.MethodDeclaration || kind === SyntaxKind.ArrowFunction || kind === SyntaxKind.FunctionExpression || kind === SyntaxKind.GetAccessor || kind === SyntaxKind.SetAccessor) {
+      return current.getStartLineNumber();
+    }
+    current = current.getParent();
+  }
+  return null;
+}
 function inferParentContext(node) {
   const parent = node.getParent();
   if (!parent) return null;
@@ -148,7 +203,7 @@ function inferParentContext(node) {
   }
   return null;
 }
-function extractFunctionData(node, filePath, kind, parentContext = null, isExportedOverride) {
+function extractFunctionData(node, filePath, kind, parentContext = null, isExportedOverride, isInlineCallback = false, enclosingFunctionStartLine = null) {
   const startLine = node.getStartLineNumber();
   const endLine = node.getEndLineNumber();
   const bodyLineCount = endLine - startLine + 1;
@@ -184,7 +239,9 @@ function extractFunctionData(node, filePath, kind, parentContext = null, isExpor
     callSites,
     hasAwait,
     propertyAccessChains,
-    kind
+    kind,
+    enclosingFunctionStartLine,
+    isInlineCallback
   };
 }
 function getBodyNode(node) {
@@ -210,8 +267,12 @@ function isStatement(node) {
 function checkForConditionals(body) {
   if (!body) return false;
   let hasConditionals = false;
-  body.forEachDescendant((node) => {
+  body.forEachDescendant((node, traversal) => {
     const kind = node.getKind();
+    if (kind === SyntaxKind.FunctionDeclaration || kind === SyntaxKind.FunctionExpression || kind === SyntaxKind.ArrowFunction || kind === SyntaxKind.MethodDeclaration) {
+      traversal.skip();
+      return;
+    }
     if (kind === SyntaxKind.IfStatement || kind === SyntaxKind.ConditionalExpression || kind === SyntaxKind.SwitchStatement) {
       hasConditionals = true;
     }
@@ -341,73 +402,30 @@ function isTypeOnlyFile(sourceFile) {
   }
   return true;
 }
-function stripJsonComments(jsonString) {
-  let result = "";
-  let inString = false;
-  let inLineComment = false;
-  let inBlockComment = false;
-  let i = 0;
-  while (i < jsonString.length) {
-    const char = jsonString[i];
-    const nextChar = jsonString[i + 1];
-    if (!inLineComment && !inBlockComment && char === '"') {
-      let backslashCount = 0;
-      let j = i - 1;
-      while (j >= 0 && jsonString[j] === "\\") {
-        backslashCount++;
-        j--;
-      }
-      if (backslashCount % 2 === 0) {
-        inString = !inString;
-      }
-    }
-    if (inString) {
-      result += char;
-      i++;
-      continue;
-    }
-    if (!inBlockComment && char === "/" && nextChar === "/") {
-      inLineComment = true;
-      i += 2;
-      continue;
-    }
-    if (inLineComment && (char === "\n" || char === "\r")) {
-      inLineComment = false;
-      result += char;
-      i++;
-      continue;
-    }
-    if (!inLineComment && char === "/" && nextChar === "*") {
-      inBlockComment = true;
-      i += 2;
-      continue;
-    }
-    if (inBlockComment && char === "*" && nextChar === "/") {
-      inBlockComment = false;
-      i += 2;
-      continue;
-    }
-    if (!inLineComment && !inBlockComment) {
-      result += char;
-    }
-    i++;
+function validateTsconfigContent(content) {
+  const errors = [];
+  jsonc.parse(content, errors, { allowTrailingComma: true });
+  if (errors.length > 0 && errors[0]) {
+    return {
+      valid: false,
+      error: `Parse error at offset ${errors[0].offset}: ${jsonc.printParseErrorCode(errors[0].error)}`
+    };
   }
-  return result;
+  return { valid: true };
 }
 function loadProject(options) {
   const { tsconfigPath, filesGlob } = options;
   const errors = [];
   const absoluteTsconfigPath = path4.resolve(tsconfigPath);
+  const projectDir = path4.dirname(absoluteTsconfigPath);
   if (!fs3.existsSync(absoluteTsconfigPath)) {
     throw new Error(`tsconfig.json not found at: ${absoluteTsconfigPath}`);
   }
-  try {
-    const content = fs3.readFileSync(absoluteTsconfigPath, "utf-8");
-    const strippedContent = stripJsonComments(content);
-    JSON.parse(strippedContent);
-  } catch (e) {
+  const content = fs3.readFileSync(absoluteTsconfigPath, "utf-8");
+  const validationResult = validateTsconfigContent(content);
+  if (!validationResult.valid) {
     throw new Error(
-      `Invalid tsconfig.json at ${absoluteTsconfigPath}: ${e instanceof Error ? e.message : String(e)}`
+      `Invalid tsconfig.json at ${absoluteTsconfigPath}: ${validationResult.error}`
     );
   }
   const project = new Project({
@@ -416,7 +434,7 @@ function loadProject(options) {
   });
   let sourceFiles = project.getSourceFiles().filter((sf) => {
     const filePath = sf.getFilePath();
-    return filePath.endsWith(".ts") && !filePath.endsWith(".d.ts") && !filePath.endsWith(".test.ts") && !filePath.endsWith(".spec.ts") && !filePath.includes("/node_modules/") && !filePath.includes("/generated/");
+    return filePath.startsWith(projectDir + "/") && filePath.endsWith(".ts") && !filePath.endsWith(".d.ts") && !filePath.endsWith(".test.ts") && !filePath.endsWith(".spec.ts") && !filePath.includes("/node_modules/") && !filePath.includes("/generated/");
   });
   if (filesGlob) {
     const globPattern = createGlobMatcher(filesGlob);
@@ -977,6 +995,122 @@ function deriveStatus(classification, qualityScore, thresholds = DEFAULT_QUALITY
 }
 
 // src/scoring/scorer.ts
+function groupFunctionsByParent(functions) {
+  const byStartLine = /* @__PURE__ */ new Map();
+  for (const fn of functions) {
+    byStartLine.set(fn.startLine, fn);
+  }
+  const topLevel = [];
+  const childrenByParentLine = /* @__PURE__ */ new Map();
+  for (const fn of functions) {
+    const isTopLevel = !fn.isInlineCallback || fn.enclosingFunctionStartLine === null;
+    if (isTopLevel) {
+      topLevel.push({ fn, children: [] });
+    } else if (fn.enclosingFunctionStartLine !== null) {
+      const existing = childrenByParentLine.get(fn.enclosingFunctionStartLine);
+      if (existing) {
+        existing.push(fn);
+      } else {
+        childrenByParentLine.set(fn.enclosingFunctionStartLine, [fn]);
+      }
+    }
+  }
+  for (const entry of topLevel) {
+    const children = childrenByParentLine.get(entry.fn.startLine);
+    if (children) {
+      entry.children = children;
+    }
+  }
+  return topLevel;
+}
+function isEffectivelyImpure(entry) {
+  if (entry.fn.classification === "impure") return true;
+  return entry.children.some((child) => child.classification === "impure");
+}
+function getEffectiveStatus(entry) {
+  const statuses = [entry.fn.status, ...entry.children.map((c) => c.status)];
+  if (statuses.includes("refactor")) return "refactor";
+  if (statuses.includes("review")) return "review";
+  return "ok";
+}
+function computeComposedQuality(entry) {
+  const impureChildren = entry.children.filter(
+    (c) => c.classification === "impure"
+  );
+  if (impureChildren.length === 0) {
+    return entry.fn.qualityScore ?? 50;
+  }
+  const childTotalLines = entry.children.reduce(
+    (sum, c) => sum + c.bodyLineCount,
+    0
+  );
+  const parentOwnLines = Math.max(1, entry.fn.bodyLineCount - childTotalLines);
+  const totalLines = parentOwnLines + childTotalLines;
+  const parentQuality = entry.fn.qualityScore ?? 50;
+  const parentContribution = parentQuality * parentOwnLines;
+  const childContribution = impureChildren.reduce(
+    (sum, c) => sum + (c.qualityScore ?? 50) * c.bodyLineCount,
+    0
+  );
+  return (parentContribution + childContribution) / totalLines;
+}
+function aggregateMetrics(items) {
+  const scorableItems = items.filter(
+    (item) => item.pureCount + item.impureCount > 0
+  );
+  const totalPure = items.reduce((sum, item) => sum + item.pureCount, 0);
+  const totalImpure = items.reduce((sum, item) => sum + item.impureCount, 0);
+  const total = totalPure + totalImpure;
+  if (total === 0) {
+    return {
+      purity: 100,
+      impurityQuality: null,
+      health: 100,
+      pureCount: 0,
+      impureCount: 0,
+      excludedCount: items.reduce((sum, item) => sum + item.excludedCount, 0),
+      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
+      pureLineCount: 0,
+      impureLineCount: 0
+    };
+  }
+  const purity = totalPure / total * 100;
+  let impurityQuality = null;
+  if (totalImpure > 0) {
+    const weightedQuality = scorableItems.reduce((sum, item) => {
+      if (item.impurityQuality !== null && item.impureCount > 0) {
+        return sum + item.impurityQuality * item.impureCount;
+      }
+      return sum;
+    }, 0);
+    impurityQuality = weightedQuality / totalImpure;
+  }
+  const statusBreakdown = {
+    ok: items.reduce((sum, item) => sum + item.statusBreakdown.ok, 0),
+    review: items.reduce((sum, item) => sum + item.statusBreakdown.review, 0),
+    refactor: items.reduce(
+      (sum, item) => sum + item.statusBreakdown.refactor,
+      0
+    )
+  };
+  const health = statusBreakdown.ok / total * 100;
+  const pureLineCount = items.reduce((sum, item) => sum + item.pureLineCount, 0);
+  const impureLineCount = items.reduce(
+    (sum, item) => sum + item.impureLineCount,
+    0
+  );
+  return {
+    purity,
+    impurityQuality,
+    health,
+    pureCount: totalPure,
+    impureCount: totalImpure,
+    excludedCount: items.reduce((sum, item) => sum + item.excludedCount, 0),
+    statusBreakdown,
+    pureLineCount,
+    impureLineCount
+  };
+}
 function scoreFile(filePath, functions, isTypeOnly = false) {
   if (isTypeOnly) {
     return {
@@ -995,12 +1129,8 @@ function scoreFile(filePath, functions, isTypeOnly = false) {
       typeOnly: true
     };
   }
-  const pureFunctions = functions.filter((f) => f.classification === "pure");
-  const impureFunctions = functions.filter((f) => f.classification === "impure");
-  const pureCount = pureFunctions.length;
-  const impureCount = impureFunctions.length;
-  const total = pureCount + impureCount;
-  if (total === 0) {
+  const grouped = groupFunctionsByParent(functions);
+  if (grouped.length === 0) {
     return {
       filePath,
       purity: 100,
@@ -1017,36 +1147,49 @@ function scoreFile(filePath, functions, isTypeOnly = false) {
       allExcluded: true
     };
   }
-  const purity = pureCount / total * 100;
+  let pureCount = 0;
+  let impureCount = 0;
+  let pureLineCount = 0;
+  let impureLineCount = 0;
+  const statusBreakdown = { ok: 0, review: 0, refactor: 0 };
+  for (const entry of grouped) {
+    const effectivelyImpure = isEffectivelyImpure(entry);
+    const effectiveStatus = getEffectiveStatus(entry);
+    if (effectivelyImpure) {
+      impureCount++;
+      impureLineCount += entry.fn.bodyLineCount;
+    } else {
+      pureCount++;
+      pureLineCount += entry.fn.bodyLineCount;
+    }
+    statusBreakdown[effectiveStatus]++;
+  }
+  const total = pureCount + impureCount;
+  const purity = total > 0 ? pureCount / total * 100 : 100;
   let impurityQuality = null;
   if (impureCount > 0) {
-    const totalQuality = impureFunctions.reduce(
-      (sum, f) => sum + (f.qualityScore ?? 0),
+    const impureEntries = grouped.filter((e) => isEffectivelyImpure(e));
+    const totalQuality = impureEntries.reduce(
+      (sum, e) => sum + computeComposedQuality(e),
       0
     );
     impurityQuality = totalQuality / impureCount;
   }
-  const statusBreakdown = {
-    ok: functions.filter((f) => f.status === "ok").length,
-    review: functions.filter((f) => f.status === "review").length,
-    refactor: functions.filter((f) => f.status === "refactor").length
-  };
-  const health = statusBreakdown.ok / total * 100;
-  const pureLineCount = pureFunctions.reduce(
-    (sum, f) => sum + f.bodyLineCount,
-    0
-  );
-  const impureLineCount = impureFunctions.reduce(
-    (sum, f) => sum + f.bodyLineCount,
-    0
-  );
-  const refactoringCandidates = impureFunctions.filter((f) => f.status === "refactor").map((f) => ({
-    name: f.name,
-    startLine: f.startLine,
-    bodyLineCount: f.bodyLineCount,
-    qualityScore: f.qualityScore ?? 0,
-    markers: f.markers.map((m) => m.type)
-  })).sort((a, b) => {
+  const health = total > 0 ? statusBreakdown.ok / total * 100 : 100;
+  const refactoringCandidates = grouped.filter((e) => isEffectivelyImpure(e) && getEffectiveStatus(e) === "refactor").map((e) => {
+    const allMarkers = [
+      ...e.fn.markers.map((m) => m.type),
+      ...e.children.flatMap((c) => c.markers.map((m) => m.type))
+    ];
+    const uniqueMarkers = [...new Set(allMarkers)];
+    return {
+      name: e.fn.name,
+      startLine: e.fn.startLine,
+      bodyLineCount: e.fn.bodyLineCount,
+      qualityScore: e.fn.qualityScore ?? 0,
+      markers: uniqueMarkers
+    };
+  }).sort((a, b) => {
     const impactA = a.bodyLineCount * (100 - a.qualityScore);
     const impactB = b.bodyLineCount * (100 - b.qualityScore);
     return impactB - impactA;
@@ -1063,6 +1206,7 @@ function scoreFile(filePath, functions, isTypeOnly = false) {
     pureLineCount,
     impureLineCount,
     functions,
+    // Keep all functions for drill-down (includes isInlineCallback flag)
     refactoringCandidates
   };
 }
@@ -1071,62 +1215,19 @@ function scoreDirectory(dirPath, fileScores) {
     (f) => !f.typeOnly && !f.allExcluded && f.pureCount + f.impureCount > 0
   );
   if (scorableFiles.length === 0) {
+    const emptyMetrics = aggregateMetrics([]);
     return {
       dirPath,
-      purity: 100,
-      impurityQuality: null,
-      health: 100,
-      pureCount: 0,
-      impureCount: 0,
+      ...emptyMetrics,
       excludedCount: fileScores.reduce((sum, f) => sum + f.excludedCount, 0),
-      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
-      pureLineCount: 0,
-      impureLineCount: 0,
       fileScores
     };
   }
-  const totalPure = scorableFiles.reduce((sum, f) => sum + f.pureCount, 0);
-  const totalImpure = scorableFiles.reduce((sum, f) => sum + f.impureCount, 0);
-  const total = totalPure + totalImpure;
-  const purity = total > 0 ? totalPure / total * 100 : 100;
-  let impurityQuality = null;
-  if (totalImpure > 0) {
-    const weightedQuality = scorableFiles.reduce((sum, f) => {
-      if (f.impurityQuality !== null && f.impureCount > 0) {
-        return sum + f.impurityQuality * f.impureCount;
-      }
-      return sum;
-    }, 0);
-    impurityQuality = weightedQuality / totalImpure;
-  }
-  const statusBreakdown = {
-    ok: scorableFiles.reduce((sum, f) => sum + f.statusBreakdown.ok, 0),
-    review: scorableFiles.reduce((sum, f) => sum + f.statusBreakdown.review, 0),
-    refactor: scorableFiles.reduce(
-      (sum, f) => sum + f.statusBreakdown.refactor,
-      0
-    )
-  };
-  const health = total > 0 ? statusBreakdown.ok / total * 100 : 100;
-  const pureLineCount = scorableFiles.reduce(
-    (sum, f) => sum + f.pureLineCount,
-    0
-  );
-  const impureLineCount = scorableFiles.reduce(
-    (sum, f) => sum + f.impureLineCount,
-    0
-  );
+  const aggregated = aggregateMetrics(scorableFiles);
   return {
     dirPath,
-    purity,
-    impurityQuality,
-    health,
-    pureCount: totalPure,
-    impureCount: totalImpure,
+    ...aggregated,
     excludedCount: fileScores.reduce((sum, f) => sum + f.excludedCount, 0),
-    statusBreakdown,
-    pureLineCount,
-    impureLineCount,
     fileScores
   };
 }
@@ -1142,19 +1243,13 @@ function scoreProject(directoryScores, options = {}) {
     (d) => d.pureCount + d.impureCount > 0
   );
   if (scorableDirs.length === 0) {
+    const emptyMetrics = aggregateMetrics([]);
     return {
-      purity: 100,
-      impurityQuality: null,
-      health: 100,
-      pureCount: 0,
-      impureCount: 0,
+      ...emptyMetrics,
       excludedCount: directoryScores.reduce(
         (sum, d) => sum + d.excludedCount,
         0
       ),
-      statusBreakdown: { ok: 0, review: 0, refactor: 0 },
-      pureLineCount: 0,
-      impureLineCount: 0,
       directoryScores,
       timestamp,
       commitHash,
@@ -1164,37 +1259,7 @@ function scoreProject(directoryScores, options = {}) {
       ...errors.length > 0 && { errors }
     };
   }
-  const totalPure = scorableDirs.reduce((sum, d) => sum + d.pureCount, 0);
-  const totalImpure = scorableDirs.reduce((sum, d) => sum + d.impureCount, 0);
-  const total = totalPure + totalImpure;
-  const purity = total > 0 ? totalPure / total * 100 : 100;
-  let impurityQuality = null;
-  if (totalImpure > 0) {
-    const weightedQuality = scorableDirs.reduce((sum, d) => {
-      if (d.impurityQuality !== null && d.impureCount > 0) {
-        return sum + d.impurityQuality * d.impureCount;
-      }
-      return sum;
-    }, 0);
-    impurityQuality = weightedQuality / totalImpure;
-  }
-  const statusBreakdown = {
-    ok: scorableDirs.reduce((sum, d) => sum + d.statusBreakdown.ok, 0),
-    review: scorableDirs.reduce((sum, d) => sum + d.statusBreakdown.review, 0),
-    refactor: scorableDirs.reduce(
-      (sum, d) => sum + d.statusBreakdown.refactor,
-      0
-    )
-  };
-  const health = total > 0 ? statusBreakdown.ok / total * 100 : 100;
-  const pureLineCount = scorableDirs.reduce(
-    (sum, d) => sum + d.pureLineCount,
-    0
-  );
-  const impureLineCount = scorableDirs.reduce(
-    (sum, d) => sum + d.impureLineCount,
-    0
-  );
+  const aggregated = aggregateMetrics(scorableDirs);
   const allCandidates = [];
   for (const dir of directoryScores) {
     for (const file of dir.fileScores) {
@@ -1212,15 +1277,8 @@ function scoreProject(directoryScores, options = {}) {
     return impactB - impactA;
   });
   const result = {
-    purity,
-    impurityQuality,
-    health,
-    pureCount: totalPure,
-    impureCount: totalImpure,
+    ...aggregated,
     excludedCount: directoryScores.reduce((sum, d) => sum + d.excludedCount, 0),
-    statusBreakdown,
-    pureLineCount,
-    impureLineCount,
     directoryScores,
     timestamp,
     commitHash,
@@ -1253,6 +1311,56 @@ function getDirectoryPath(filePath) {
   if (lastSlash === -1) return ".";
   return filePath.slice(0, lastSlash);
 }
+function getPathAtDepth(relativePath, depth) {
+  const normalized = relativePath.replace(/\\/g, "/");
+  const segments = normalized.split("/").filter(Boolean);
+  if (segments.length === 0) {
+    return ".";
+  }
+  const segmentCount = depth + 1;
+  if (segmentCount >= segments.length) {
+    return segments.join("/");
+  }
+  return segments.slice(0, segmentCount).join("/");
+}
+function rollupDirectoriesByDepth(directories, depth) {
+  if (directories.length === 0) {
+    return [];
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const dir of directories) {
+    const truncatedPath = getPathAtDepth(dir.dirPath, depth);
+    const existing = groups.get(truncatedPath);
+    if (existing) {
+      existing.push(dir);
+    } else {
+      groups.set(truncatedPath, [dir]);
+    }
+  }
+  const rolledUp = [];
+  for (const [groupPath, groupDirs] of groups) {
+    const scorableDirs = groupDirs.filter((d) => d.pureCount + d.impureCount > 0);
+    if (scorableDirs.length === 0) {
+      const emptyMetrics = aggregateMetrics([]);
+      rolledUp.push({
+        dirPath: groupPath,
+        ...emptyMetrics,
+        excludedCount: groupDirs.reduce((sum, d) => sum + d.excludedCount, 0),
+        fileScores: []
+      });
+      continue;
+    }
+    const aggregated = aggregateMetrics(scorableDirs);
+    rolledUp.push({
+      dirPath: groupPath,
+      ...aggregated,
+      excludedCount: groupDirs.reduce((sum, d) => sum + d.excludedCount, 0),
+      fileScores: []
+    });
+  }
+  rolledUp.sort((a, b) => a.dirPath.localeCompare(b.dirPath));
+  return rolledUp;
+}
 function getDiagnosticInsights(score) {
   const insights = [];
   if (score.purity >= 60 && score.impurityQuality !== null && score.impurityQuality < 50) {
@@ -1390,8 +1498,79 @@ function checkThresholds(score, config) {
     failures
   };
 }
+function getMetricColor(value) {
+  if (value >= 70) return chalk.green;
+  if (value >= 50) return chalk.yellow;
+  return chalk.red;
+}
+function getMetricColorNullable(value) {
+  if (value === null) return chalk.gray;
+  return getMetricColor(value);
+}
+function toRelativePath(absolutePath) {
+  const cwd = process.cwd();
+  if (absolutePath.startsWith(cwd)) {
+    const relative3 = path4.relative(cwd, absolutePath);
+    return relative3 || ".";
+  }
+  return absolutePath;
+}
+function relativizeDirectoryPaths(directories, projectRoot) {
+  return directories.map((d) => ({
+    ...d,
+    dirPath: path4.relative(projectRoot, d.dirPath).replace(/\\/g, "/")
+  }));
+}
+function printDirectoryTable(directories, options) {
+  const { title, includeQualityColumn, sortBy, emptyMessage } = options;
+  let filtered = directories.filter((d) => d.pureCount + d.impureCount > 0);
+  if (sortBy === "health-asc") {
+    filtered = [...filtered].sort((a, b) => a.health - b.health);
+  }
+  console.log(chalk.bold(title));
+  console.log(chalk.gray("\u2500".repeat(80)));
+  if (includeQualityColumn) {
+    console.log(
+      chalk.gray(
+        padEnd("Directory", 40) + padEnd("Health", 10) + padEnd("Purity", 10) + padEnd("Quality", 10) + padEnd("Functions", 10)
+      )
+    );
+  } else {
+    console.log(
+      chalk.gray(
+        padEnd("Directory", 45) + padEnd("Health", 10) + padEnd("Purity", 10) + padEnd("Functions", 15)
+      )
+    );
+  }
+  console.log(chalk.gray("\u2500".repeat(80)));
+  if (filtered.length === 0) {
+    if (emptyMessage) {
+      console.log(chalk.gray(`  ${emptyMessage}`));
+    }
+    console.log();
+    return;
+  }
+  for (const dir of filtered) {
+    const healthColor = getMetricColor(dir.health);
+    const purityColor = getMetricColor(dir.purity);
+    const total = dir.pureCount + dir.impureCount;
+    if (includeQualityColumn) {
+      const qualityStr = dir.impurityQuality !== null ? dir.impurityQuality.toFixed(0) + "%" : "\u2014";
+      const qualityColor = getMetricColorNullable(dir.impurityQuality);
+      console.log(
+        padEnd(dir.dirPath, 40) + healthColor(padEnd(dir.health.toFixed(0) + "%", 10)) + purityColor(padEnd(dir.purity.toFixed(0) + "%", 10)) + qualityColor(padEnd(qualityStr, 10)) + padEnd(`${dir.pureCount}/${total}`, 10)
+      );
+    } else {
+      const relativePath = toRelativePath(dir.dirPath);
+      console.log(
+        padEnd(relativePath, 45) + healthColor(padEnd(dir.health.toFixed(0) + "%", 10)) + purityColor(padEnd(dir.purity.toFixed(0) + "%", 10)) + padEnd(`${dir.pureCount}/${total}`, 15)
+      );
+    }
+  }
+  console.log();
+}
 function printConsoleReport(score, options = {}) {
-  const { verbose = false } = options;
+  const { verbose = false, dirDepth } = options;
   printHeader();
   printProjectSummary(score);
   printStatusBreakdown(
@@ -1399,8 +1578,24 @@ function printConsoleReport(score, options = {}) {
     score.pureCount + score.impureCount
   );
   printInsights(score);
-  if (verbose) {
-    printDirectoryBreakdown(score.directoryScores);
+  if (dirDepth !== void 0) {
+    const relativized = relativizeDirectoryPaths(
+      score.directoryScores,
+      process.cwd()
+    );
+    const rolledUp = rollupDirectoriesByDepth(relativized, dirDepth);
+    printDirectoryTable(rolledUp, {
+      title: `Directory Breakdown (depth=${dirDepth}):`,
+      includeQualityColumn: true,
+      sortBy: "preserve-order",
+      emptyMessage: "No directories with functions found"
+    });
+  } else if (verbose) {
+    printDirectoryTable(score.directoryScores, {
+      title: "Directory Breakdown:",
+      includeQualityColumn: false,
+      sortBy: "health-asc"
+    });
   } else {
     printWorstDirectories(score.directoryScores);
   }
@@ -1420,8 +1615,8 @@ function printHeader() {
 }
 function printProjectSummary(score) {
   const healthBar = createProgressBar(score.health, 25);
-  const healthColor = score.health >= 70 ? chalk.green : score.health >= 50 ? chalk.yellow : chalk.red;
-  const purityColor = score.purity >= 70 ? chalk.green : score.purity >= 50 ? chalk.yellow : chalk.red;
+  const healthColor = getMetricColor(score.health);
+  const purityColor = getMetricColor(score.purity);
   console.log(
     `Project Health: ${healthColor(score.health.toFixed(0) + "%")} ${healthBar}`
   );
@@ -1429,7 +1624,7 @@ function printProjectSummary(score) {
     `  Purity:           ${purityColor(score.purity.toFixed(0) + "%")} (${score.pureCount} pure / ${score.pureCount + score.impureCount} total)`
   );
   if (score.impurityQuality !== null) {
-    const qualityColor = score.impurityQuality >= 70 ? chalk.green : score.impurityQuality >= 50 ? chalk.yellow : chalk.red;
+    const qualityColor = getMetricColor(score.impurityQuality);
     console.log(
       `  Impurity Quality: ${qualityColor(score.impurityQuality.toFixed(0) + "%")} average`
     );
@@ -1462,34 +1657,12 @@ function printInsights(score) {
     console.log();
   }
 }
-function printDirectoryBreakdown(directories) {
-  const sorted = [...directories].filter((d) => d.pureCount + d.impureCount > 0).sort((a, b) => a.health - b.health);
-  if (sorted.length === 0) return;
-  console.log(chalk.bold("Directory Breakdown:"));
-  console.log(chalk.gray("\u2500".repeat(80)));
-  console.log(
-    chalk.gray(
-      padEnd("Directory", 45) + padEnd("Health", 10) + padEnd("Purity", 10) + padEnd("Functions", 15)
-    )
-  );
-  console.log(chalk.gray("\u2500".repeat(80)));
-  for (const dir of sorted) {
-    const healthColor = dir.health >= 70 ? chalk.green : dir.health >= 50 ? chalk.yellow : chalk.red;
-    const purityColor = dir.purity >= 70 ? chalk.green : dir.purity >= 50 ? chalk.yellow : chalk.red;
-    const relativePath = toRelativePath(dir.dirPath);
-    const total = dir.pureCount + dir.impureCount;
-    console.log(
-      padEnd(relativePath, 45) + healthColor(padEnd(dir.health.toFixed(0) + "%", 10)) + purityColor(padEnd(dir.purity.toFixed(0) + "%", 10)) + padEnd(`${dir.pureCount}/${total}`, 15)
-    );
-  }
-  console.log();
-}
 function printWorstDirectories(directories) {
   const sorted = [...directories].filter((d) => d.pureCount + d.impureCount > 0 && d.health < 70).sort((a, b) => a.health - b.health).slice(0, 5);
   if (sorted.length === 0) return;
   console.log(chalk.bold("Directories Needing Attention:"));
   for (const dir of sorted) {
-    const healthColor = dir.health >= 50 ? chalk.yellow : chalk.red;
+    const healthColor = getMetricColor(dir.health);
     const total = dir.pureCount + dir.impureCount;
     const relativePath = toRelativePath(dir.dirPath);
     console.log(
@@ -1555,13 +1728,7 @@ function createProgressBar(percent, width) {
   const filledChar = "\u2588";
   const emptyChar = "\u2591";
   const bar = filledChar.repeat(filled) + emptyChar.repeat(empty);
-  if (percent >= 70) {
-    return chalk.green(bar);
-  } else if (percent >= 50) {
-    return chalk.yellow(bar);
-  } else {
-    return chalk.red(bar);
-  }
+  return getMetricColor(percent)(bar);
 }
 function generateSummaryLine(score) {
   const parts = [
@@ -1573,21 +1740,29 @@ function generateSummaryLine(score) {
   }
   return parts.join(" | ");
 }
-function toRelativePath(absolutePath) {
-  const cwd = process.cwd();
-  if (absolutePath.startsWith(cwd)) {
-    const relative2 = path4.relative(cwd, absolutePath);
-    return relative2 || ".";
-  }
-  return absolutePath;
-}
 function padEnd(str, length) {
   if (str.length >= length) return str.slice(0, length);
   return str + " ".repeat(length - str.length);
 }
 function generateJsonReport(score, options = {}) {
-  const { pretty = true, includeFunction = false } = options;
-  const reportData = prepareReportData(score, includeFunction);
+  const {
+    pretty = true,
+    includeFunction = true,
+    dirDepth,
+    projectRoot = process.cwd()
+  } = options;
+  let reportData = prepareReportData(score, includeFunction);
+  if (dirDepth !== void 0) {
+    const relativized = score.directoryScores.map((d) => ({
+      ...d,
+      dirPath: path4.relative(projectRoot, d.dirPath).replace(/\\/g, "/")
+    }));
+    const rolledUp = rollupDirectoriesByDepth(relativized, dirDepth);
+    reportData = {
+      ...reportData,
+      rolledUpDirectories: rolledUp
+    };
+  }
   if (pretty) {
     return JSON.stringify(reportData, null, 2);
   }
@@ -1617,13 +1792,175 @@ function writeJsonReport(score, outputPath, options = {}) {
   }
   fs3.writeFileSync(outputPath, json, "utf-8");
 }
+var VALID_FORMATS = ["console", "json", "summary"];
+var ThresholdSchema = z.number().min(0).max(100);
+var PositiveIntegerSchema = z.number().int().min(1);
+function validateCliFlags(flags) {
+  if (flags.minHealth !== void 0) {
+    const result = ThresholdSchema.safeParse(flags.minHealth);
+    if (!result.success) {
+      return {
+        valid: false,
+        error: "--min-health must be a number between 0 and 100"
+      };
+    }
+  }
+  if (flags.minPurity !== void 0) {
+    const result = ThresholdSchema.safeParse(flags.minPurity);
+    if (!result.success) {
+      return {
+        valid: false,
+        error: "--min-purity must be a number between 0 and 100"
+      };
+    }
+  }
+  if (flags.minQuality !== void 0) {
+    const result = ThresholdSchema.safeParse(flags.minQuality);
+    if (!result.success) {
+      return {
+        valid: false,
+        error: "--min-quality must be a number between 0 and 100"
+      };
+    }
+  }
+  if (!VALID_FORMATS.includes(flags.format)) {
+    return {
+      valid: false,
+      error: `--format must be one of: ${VALID_FORMATS.join(", ")}`
+    };
+  }
+  if (flags.dirDepth !== void 0) {
+    const result = PositiveIntegerSchema.safeParse(flags.dirDepth);
+    if (!result.success) {
+      return {
+        valid: false,
+        error: "--dir-depth must be a positive integer (1 or greater)"
+      };
+    }
+  }
+  return { valid: true };
+}
+function validateGlobPattern(pattern) {
+  if (!pattern || pattern.trim() === "") {
+    return { valid: false, error: "Glob pattern cannot be empty" };
+  }
+  if (pattern.startsWith("/")) {
+    return {
+      valid: false,
+      error: "Glob pattern cannot be an absolute path (starting with /)"
+    };
+  }
+  let bracketDepth = 0;
+  let braceDepth = 0;
+  for (const char of pattern) {
+    if (char === "[") bracketDepth++;
+    if (char === "]") bracketDepth--;
+    if (char === "{") braceDepth++;
+    if (char === "}") braceDepth--;
+    if (bracketDepth < 0 || braceDepth < 0) {
+      return { valid: false, error: "Glob pattern has unbalanced brackets" };
+    }
+  }
+  if (bracketDepth !== 0 || braceDepth !== 0) {
+    return { valid: false, error: "Glob pattern has unbalanced brackets" };
+  }
+  return { valid: true };
+}
+function buildAnalyzerConfig(tsconfigPath, flags) {
+  const config = {
+    tsconfigPath,
+    format: flags.format,
+    quiet: flags.quiet,
+    verbose: flags.verbose
+  };
+  if (flags.files !== void 0) {
+    config.filesGlob = flags.files;
+  }
+  if (flags.minHealth !== void 0) {
+    config.minHealth = flags.minHealth;
+  }
+  if (flags.minPurity !== void 0) {
+    config.minPurity = flags.minPurity;
+  }
+  if (flags.minQuality !== void 0) {
+    config.minQuality = flags.minQuality;
+  }
+  if (flags.output !== void 0) {
+    config.outputPath = flags.output;
+  }
+  if (flags.dirDepth !== void 0) {
+    config.dirDepth = flags.dirDepth;
+  }
+  return config;
+}
+function buildThresholdConfig(flags) {
+  const config = {};
+  if (flags.minHealth !== void 0) {
+    config.minHealth = flags.minHealth;
+  }
+  if (flags.minPurity !== void 0) {
+    config.minPurity = flags.minPurity;
+  }
+  if (flags.minQuality !== void 0) {
+    config.minQuality = flags.minQuality;
+  }
+  return config;
+}
 
 // src/cli.ts
 var EXIT_SUCCESS = 0;
 var EXIT_THRESHOLD_FAILED = 1;
 var EXIT_CONFIG_ERROR = 2;
 var EXIT_ANALYSIS_ERROR = 3;
-var ThresholdSchema = z.number().min(0).max(100);
+function handleAnalysisOutput(score, flags) {
+  if (!flags.quiet) {
+    if (flags.json || flags.format === "json") {
+      const jsonOptions = {
+        pretty: true
+      };
+      if (flags.dirDepth !== void 0) {
+        jsonOptions.dirDepth = flags.dirDepth;
+      }
+      console.log(generateJsonReport(score, jsonOptions));
+    } else if (flags.format === "summary") {
+      console.log(generateSummaryLine(score));
+    } else {
+      const reportOptions = {
+        verbose: flags.verbose
+      };
+      if (flags.dirDepth !== void 0) {
+        reportOptions.dirDepth = flags.dirDepth;
+      }
+      printConsoleReport(score, reportOptions);
+    }
+  }
+  if (flags.output) {
+    const outputOptions = {
+      pretty: true
+    };
+    if (flags.dirDepth !== void 0) {
+      outputOptions.dirDepth = flags.dirDepth;
+    }
+    writeJsonReport(score, flags.output, outputOptions);
+    if (!flags.quiet && flags.format !== "json") {
+      console.log(chalk.green(`Report written to: ${flags.output}`));
+    }
+  }
+}
+function ensureOutputDirectory(outputPath) {
+  const outputDir = path4.dirname(path4.resolve(outputPath));
+  if (!fs3.existsSync(outputDir)) {
+    try {
+      fs3.mkdirSync(outputDir, { recursive: true });
+    } catch {
+      return {
+        valid: false,
+        error: `Cannot create output directory: ${outputDir}`
+      };
+    }
+  }
+  return { valid: true };
+}
 var argv = cli({
   name: "fcis",
   version: "0.1.0",
@@ -1671,6 +2008,10 @@ var argv = cli({
       alias: "v",
       description: "Show per-file scores and all classified functions",
       default: false
+    },
+    dirDepth: {
+      type: Number,
+      description: "Roll up directory metrics to depth N (e.g., 1 for top-level)"
     }
   },
   parameters: ["<tsconfig>"],
@@ -1699,115 +2040,42 @@ async function main() {
     );
     process.exit(EXIT_CONFIG_ERROR);
   }
-  try {
-    const content = fs3.readFileSync(absoluteTsconfigPath, "utf-8");
-    const strippedContent = stripJsonComments(content);
-    JSON.parse(strippedContent);
-  } catch (e) {
+  const tsconfigContent = fs3.readFileSync(absoluteTsconfigPath, "utf-8");
+  const tsconfigValidation = validateTsconfigContent(tsconfigContent);
+  if (!tsconfigValidation.valid) {
     console.error(
       chalk.red(`Error: Invalid tsconfig.json at ${absoluteTsconfigPath}`)
     );
-    console.error(e instanceof Error ? e.message : String(e));
+    console.error(tsconfigValidation.error);
     process.exit(EXIT_CONFIG_ERROR);
   }
-  if (flags.minHealth !== void 0) {
-    const result = ThresholdSchema.safeParse(flags.minHealth);
-    if (!result.success) {
-      console.error(
-        chalk.red("Error: --min-health must be a number between 0 and 100")
-      );
-      process.exit(EXIT_CONFIG_ERROR);
-    }
-  }
-  if (flags.minPurity !== void 0) {
-    const result = ThresholdSchema.safeParse(flags.minPurity);
-    if (!result.success) {
-      console.error(
-        chalk.red("Error: --min-purity must be a number between 0 and 100")
-      );
-      process.exit(EXIT_CONFIG_ERROR);
-    }
+  const flagsValidation = validateCliFlags(flags);
+  if (!flagsValidation.valid) {
+    console.error(chalk.red(`Error: ${flagsValidation.error}`));
+    process.exit(EXIT_CONFIG_ERROR);
   }
-  if (flags.minQuality !== void 0) {
-    const result = ThresholdSchema.safeParse(flags.minQuality);
-    if (!result.success) {
-      console.error(
-        chalk.red("Error: --min-quality must be a number between 0 and 100")
-      );
+  if (flags.files !== void 0) {
+    const globValidation = validateGlobPattern(flags.files);
+    if (!globValidation.valid) {
+      console.error(chalk.red(`Error: ${globValidation.error}`));
       process.exit(EXIT_CONFIG_ERROR);
     }
   }
-  const validFormats = ["console", "json", "summary"];
-  if (!validFormats.includes(flags.format)) {
-    console.error(
-      chalk.red(`Error: --format must be one of: ${validFormats.join(", ")}`)
-    );
-    process.exit(EXIT_CONFIG_ERROR);
-  }
   if (flags.output) {
-    const outputDir = path4.dirname(path4.resolve(flags.output));
-    if (!fs3.existsSync(outputDir)) {
-      try {
-        fs3.mkdirSync(outputDir, { recursive: true });
-      } catch (e) {
-        console.error(
-          chalk.red(`Error: Cannot create output directory: ${outputDir}`)
-        );
-        process.exit(EXIT_CONFIG_ERROR);
-      }
+    const outputValidation = ensureOutputDirectory(flags.output);
+    if (!outputValidation.valid) {
+      console.error(chalk.red(`Error: ${outputValidation.error}`));
+      process.exit(EXIT_CONFIG_ERROR);
     }
   }
   try {
     if (!flags.quiet && flags.format === "console") {
       console.log(chalk.gray(`Analyzing ${process.cwd()}...`));
     }
-    const config = {
-      tsconfigPath: absoluteTsconfigPath,
-      format: flags.format,
-      quiet: flags.quiet,
-      verbose: flags.verbose
-    };
-    if (flags.files !== void 0) {
-      config.filesGlob = flags.files;
-    }
-    if (flags.minHealth !== void 0) {
-      config.minHealth = flags.minHealth;
-    }
-    if (flags.minPurity !== void 0) {
-      config.minPurity = flags.minPurity;
-    }
-    if (flags.minQuality !== void 0) {
-      config.minQuality = flags.minQuality;
-    }
-    if (flags.output !== void 0) {
-      config.outputPath = flags.output;
-    }
+    const config = buildAnalyzerConfig(absoluteTsconfigPath, flags);
     const score = await analyze(config);
-    if (!flags.quiet) {
-      if (flags.json || flags.format === "json") {
-        console.log(generateJsonReport(score, { pretty: true }));
-      } else if (flags.format === "summary") {
-        console.log(generateSummaryLine(score));
-      } else {
-        printConsoleReport(score, { verbose: flags.verbose });
-      }
-    }
-    if (flags.output) {
-      writeJsonReport(score, flags.output, { pretty: true });
-      if (!flags.quiet && flags.format !== "json") {
-        console.log(chalk.green(`Report written to: ${flags.output}`));
-      }
-    }
-    const thresholdConfig = {};
-    if (flags.minHealth !== void 0) {
-      thresholdConfig.minHealth = flags.minHealth;
-    }
-    if (flags.minPurity !== void 0) {
-      thresholdConfig.minPurity = flags.minPurity;
-    }
-    if (flags.minQuality !== void 0) {
-      thresholdConfig.minQuality = flags.minQuality;
-    }
+    handleAnalysisOutput(score, flags);
+    const thresholdConfig = buildThresholdConfig(flags);
     const thresholdResult = checkThresholds(score, thresholdConfig);
     if (!thresholdResult.passed) {
       if (!flags.quiet) {