fcis 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fcis",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Functional Core, Imperative Shell analyzer for TypeScript codebases",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,7 @@
   "dependencies": {
     "chalk": "^5.3.0",
     "cleye": "^1.3.2",
+    "jsonc-parser": "^3.3.1",
     "ts-morph": "^24.0.0",
     "ts-pattern": "^5.6.0",
     "zod": "^3.24.0"

package/src/cli-utils.ts

@@ -0,0 +1,201 @@
+/**
+ * CLI Utilities - Pure Functions
+ *
+ * Extracted pure functions for CLI validation and configuration building.
+ * These are separated from cli.ts to enable unit testing without triggering
+ * the CLI entry point.
+ */
+
+import { z } from 'zod'
+import type { AnalyzerConfig } from './types.js'
+
+const VALID_FORMATS = ['console', 'json', 'summary'] as const
+type OutputFormat = (typeof VALID_FORMATS)[number]
+
+/**
+ * CLI flags as parsed by cleye
+ * Note: cleye automatically adds `version` and `help` flags
+ */
+export type CliFlags = {
+  json: boolean
+  output: string | undefined
+  minHealth: number | undefined
+  minPurity: number | undefined
+  minQuality: number | undefined
+  files: string | undefined
+  format: string
+  quiet: boolean
+  verbose: boolean
+  dirDepth: number | undefined
+  version: boolean | undefined
+  help: boolean | undefined
+}
+
+/**
+ * Validation result type
+ */
+export type ValidationResult = { valid: true } | { valid: false; error: string }
+
+/**
+ * Validate a threshold value (0-100)
+ */
+const ThresholdSchema = z.number().min(0).max(100)
+
+/**
+ * Validate a positive integer (for --dir-depth)
+ */
+const PositiveIntegerSchema = z.number().int().min(1)
+
+/**
+ * Validate CLI flags (pure function)
+ */
+export function validateCliFlags(flags: CliFlags): ValidationResult {
+  // Validate threshold values
+  if (flags.minHealth !== undefined) {
+    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 !== undefined) {
+    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 !== undefined) {
+    const result = ThresholdSchema.safeParse(flags.minQuality)
+    if (!result.success) {
+      return {
+        valid: false,
+        error: '--min-quality must be a number between 0 and 100',
+      }
+    }
+  }
+
+  // Validate format
+  if (!VALID_FORMATS.includes(flags.format as OutputFormat)) {
+    return {
+      valid: false,
+      error: `--format must be one of: ${VALID_FORMATS.join(', ')}`,
+    }
+  }
+
+  // Validate dir-depth
+  if (flags.dirDepth !== undefined) {
+    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 }
+}
+
+/**
+ * Validate a glob pattern (pure function)
+ */
+export function validateGlobPattern(pattern: string): ValidationResult {
+  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 /)',
+    }
+  }
+
+  // Check for unbalanced brackets
+  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 }
+}
+
+/**
+ * Build AnalyzerConfig from CLI flags (pure function)
+ */
+export function buildAnalyzerConfig(
+  tsconfigPath: string,
+  flags: CliFlags,
+): AnalyzerConfig {
+  const config: AnalyzerConfig = {
+    tsconfigPath,
+    format: flags.format as 'console' | 'json' | 'summary',
+    quiet: flags.quiet,
+    verbose: flags.verbose,
+  }
+
+  if (flags.files !== undefined) {
+    config.filesGlob = flags.files
+  }
+  if (flags.minHealth !== undefined) {
+    config.minHealth = flags.minHealth
+  }
+  if (flags.minPurity !== undefined) {
+    config.minPurity = flags.minPurity
+  }
+  if (flags.minQuality !== undefined) {
+    config.minQuality = flags.minQuality
+  }
+  if (flags.output !== undefined) {
+    config.outputPath = flags.output
+  }
+  if (flags.dirDepth !== undefined) {
+    config.dirDepth = flags.dirDepth
+  }
+
+  return config
+}
+
+/**
+ * Build threshold config from CLI flags (pure function)
+ */
+export function buildThresholdConfig(flags: CliFlags): {
+  minHealth?: number
+  minPurity?: number
+  minQuality?: number
+} {
+  const config: {
+    minHealth?: number
+    minPurity?: number
+    minQuality?: number
+  } = {}
+
+  if (flags.minHealth !== undefined) {
+    config.minHealth = flags.minHealth
+  }
+  if (flags.minPurity !== undefined) {
+    config.minPurity = flags.minPurity
+  }
+  if (flags.minQuality !== undefined) {
+    config.minQuality = flags.minQuality
+  }
+
+  return config
+}

package/src/cli.ts

@@ -13,26 +13,90 @@
  */
 
 import { cli } from 'cleye'
-import { z } from 'zod'
 import chalk from 'chalk'
 import * as fs from 'node:fs'
 import * as path from 'node:path'
 
 import { analyze, checkThresholds } from './analyzer.js'
-import { stripJsonComments } from './extraction/extractor.js'
+import { validateTsconfigContent } from './extraction/extractor.js'
 import {
   printConsoleReport,
   generateSummaryLine,
 } from './reporting/report-console.js'
 import { generateJsonReport, writeJsonReport } from './reporting/report-json.js'
-import type { AnalyzerConfig } from './types.js'
+import type { ProjectScore } from './types.js'
+import {
+  validateCliFlags,
+  validateGlobPattern,
+  buildAnalyzerConfig,
+  buildThresholdConfig,
+  type CliFlags,
+  type ValidationResult,
+} from './cli-utils.js'
 
 const EXIT_SUCCESS = 0
 const EXIT_THRESHOLD_FAILED = 1
 const EXIT_CONFIG_ERROR = 2
 const EXIT_ANALYSIS_ERROR = 3
 
-const ThresholdSchema = z.number().min(0).max(100)
+/**
+ * Handle analysis output based on flags (shell function - performs I/O)
+ */
+function handleAnalysisOutput(score: ProjectScore, flags: CliFlags): void {
+  if (!flags.quiet) {
+    if (flags.json || flags.format === 'json') {
+      const jsonOptions: { pretty: boolean; dirDepth?: number } = {
+        pretty: true,
+      }
+      if (flags.dirDepth !== undefined) {
+        jsonOptions.dirDepth = flags.dirDepth
+      }
+      console.log(generateJsonReport(score, jsonOptions))
+    } else if (flags.format === 'summary') {
+      console.log(generateSummaryLine(score))
+    } else {
+      const reportOptions: { verbose?: boolean; dirDepth?: number } = {
+        verbose: flags.verbose,
+      }
+      if (flags.dirDepth !== undefined) {
+        reportOptions.dirDepth = flags.dirDepth
+      }
+      printConsoleReport(score, reportOptions)
+    }
+  }
+
+  // Write JSON to file if requested
+  if (flags.output) {
+    const outputOptions: { pretty: boolean; dirDepth?: number } = {
+      pretty: true,
+    }
+    if (flags.dirDepth !== undefined) {
+      outputOptions.dirDepth = flags.dirDepth
+    }
+    writeJsonReport(score, flags.output, outputOptions)
+    if (!flags.quiet && flags.format !== 'json') {
+      console.log(chalk.green(`Report written to: ${flags.output}`))
+    }
+  }
+}
+
+/**
+ * Ensure output directory exists (shell function - performs I/O)
+ */
+function ensureOutputDirectory(outputPath: string): ValidationResult {
+  const outputDir = path.dirname(path.resolve(outputPath))
+  if (!fs.existsSync(outputDir)) {
+    try {
+      fs.mkdirSync(outputDir, { recursive: true })
+    } catch {
+      return {
+        valid: false,
+        error: `Cannot create output directory: ${outputDir}`,
+      }
+    }
+  }
+  return { valid: true }
+}
 
 const argv = cli({
   name: 'fcis',
@@ -83,6 +147,11 @@ const argv = cli({
       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>'],
   help: {
@@ -102,13 +171,14 @@ async function main(): Promise<void> {
 
   const tsconfigPath = args.tsconfig
 
-  // Validate tsconfig exists
+  // Validate tsconfig path provided
   if (!tsconfigPath) {
     console.error(chalk.red('Error: tsconfig path is required'))
     console.error('Usage: fcis <tsconfig> [options]')
     process.exit(EXIT_CONFIG_ERROR)
   }
 
+  // Validate tsconfig exists
   const absoluteTsconfigPath = path.resolve(tsconfigPath)
   if (!fs.existsSync(absoluteTsconfigPath)) {
     console.error(
@@ -117,71 +187,39 @@ async function main(): Promise<void> {
     process.exit(EXIT_CONFIG_ERROR)
   }
 
-  // Validate tsconfig is valid JSON (strip comments first since TypeScript allows them)
-  try {
-    const content = fs.readFileSync(absoluteTsconfigPath, 'utf-8')
-    const strippedContent = stripJsonComments(content)
-    JSON.parse(strippedContent)
-  } catch (e) {
+  // Validate tsconfig content
+  const tsconfigContent = fs.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)
   }
 
-  // Validate threshold values
-  if (flags.minHealth !== undefined) {
-    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 !== undefined) {
-    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)
-    }
+  // Validate CLI flags
+  const flagsValidation = validateCliFlags(flags)
+  if (!flagsValidation.valid) {
+    console.error(chalk.red(`Error: ${flagsValidation.error}`))
+    process.exit(EXIT_CONFIG_ERROR)
   }
 
-  if (flags.minQuality !== undefined) {
-    const result = ThresholdSchema.safeParse(flags.minQuality)
-    if (!result.success) {
-      console.error(
-        chalk.red('Error: --min-quality must be a number between 0 and 100'),
-      )
+  // Validate glob pattern if provided
+  if (flags.files !== undefined) {
+    const globValidation = validateGlobPattern(flags.files)
+    if (!globValidation.valid) {
+      console.error(chalk.red(`Error: ${globValidation.error}`))
       process.exit(EXIT_CONFIG_ERROR)
     }
   }
 
-  // Validate format
-  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)
-  }
-
   // Validate output path if provided
   if (flags.output) {
-    const outputDir = path.dirname(path.resolve(flags.output))
-    if (!fs.existsSync(outputDir)) {
-      try {
-        fs.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)
     }
   }
 
@@ -191,69 +229,14 @@ async function main(): Promise<void> {
       console.log(chalk.gray(`Analyzing ${process.cwd()}...`))
     }
 
-    // Build config with proper undefined handling
-    const config: AnalyzerConfig = {
-      tsconfigPath: absoluteTsconfigPath,
-      format: flags.format as 'console' | 'json' | 'summary',
-      quiet: flags.quiet,
-      verbose: flags.verbose,
-    }
-
-    // Only add optional properties if they are defined
-    if (flags.files !== undefined) {
-      config.filesGlob = flags.files
-    }
-    if (flags.minHealth !== undefined) {
-      config.minHealth = flags.minHealth
-    }
-    if (flags.minPurity !== undefined) {
-      config.minPurity = flags.minPurity
-    }
-    if (flags.minQuality !== undefined) {
-      config.minQuality = flags.minQuality
-    }
-    if (flags.output !== undefined) {
-      config.outputPath = flags.output
-    }
-
+    const config = buildAnalyzerConfig(absoluteTsconfigPath, flags)
     const score = await analyze(config)
 
-    // Output results based on format
-    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 })
-      }
-    }
-
-    // Write JSON to file if requested
-    if (flags.output) {
-      writeJsonReport(score, flags.output, { pretty: true })
-      if (!flags.quiet && flags.format !== 'json') {
-        console.log(chalk.green(`Report written to: ${flags.output}`))
-      }
-    }
-
-    // Check thresholds - build object only with defined values
-    const thresholdConfig: {
-      minHealth?: number
-      minPurity?: number
-      minQuality?: number
-    } = {}
-
-    if (flags.minHealth !== undefined) {
-      thresholdConfig.minHealth = flags.minHealth
-    }
-    if (flags.minPurity !== undefined) {
-      thresholdConfig.minPurity = flags.minPurity
-    }
-    if (flags.minQuality !== undefined) {
-      thresholdConfig.minQuality = flags.minQuality
-    }
+    // Output results
+    handleAnalysisOutput(score, flags)
 
+    // Check thresholds
+    const thresholdConfig = buildThresholdConfig(flags)
     const thresholdResult = checkThresholds(score, thresholdConfig)
 
     if (!thresholdResult.passed) {
@@ -274,7 +257,6 @@ async function main(): Promise<void> {
       console.error(error instanceof Error ? error.message : String(error))
     }
 
-    // Check if it's a "no files" error
     if (error instanceof Error && error.message.includes('No source files')) {
       process.exit(EXIT_ANALYSIS_ERROR)
     }