@cod3vil/kount-cli 1.0.0

package/src/core/aggregator.ts

@@ -0,0 +1,204 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import {
+    BlankLinesPlugin,
+    CommentLinesPlugin,
+    FileSizePlugin,
+    LanguageDistributionPlugin,
+    LargestFilesPlugin,
+    TotalFilesPlugin,
+    TotalLinesPlugin,
+} from '../plugins/index.js';
+import type { AnalyzedFileData, AnalyzerPlugin, PluginResult, ProjectStats } from '../plugins/types.js';
+import type { ScannedFile } from '../scanner/stream-reader.js';
+import { Scanner } from '../scanner/stream-reader.js';
+import { CacheManager } from './cache.js';
+
+/**
+ * Default set of built-in v1 plugins.
+ */
+function getDefaultPlugins(): AnalyzerPlugin[] {
+  return [
+    new TotalLinesPlugin(),
+    new BlankLinesPlugin(),
+    new CommentLinesPlugin(),
+    new FileSizePlugin(),
+    new TotalFilesPlugin(),
+    new LanguageDistributionPlugin(),
+    new LargestFilesPlugin(),
+  ];
+}
+
+export interface AggregatorOptions {
+  respectGitignore?: boolean;
+  plugins?: AnalyzerPlugin[];
+  cacheEnabled?: boolean;
+  clearCache?: boolean;
+}
+
+/**
+ * Orchestrator: connects the Scanner to the Plugin pipeline.
+ * Streams each file, builds AnalyzedFileData, then runs all plugins.
+ * Integrates the CacheManager to skip unchanged files.
+ */
+export class Aggregator {
+  private scanner: Scanner;
+  private plugins: AnalyzerPlugin[];
+  private rootDir: string;
+  private cache: CacheManager;
+  private clearCacheFirst: boolean;
+
+  constructor(rootDir: string, options?: AggregatorOptions) {
+    this.rootDir = path.resolve(rootDir);
+    this.scanner = new Scanner(this.rootDir, options?.respectGitignore ?? true);
+    this.plugins = options?.plugins ?? getDefaultPlugins();
+    this.cache = new CacheManager(this.rootDir, options?.cacheEnabled ?? true);
+    this.clearCacheFirst = options?.clearCache ?? false;
+  }
+
+  /**
+   * Runs the full pipeline: discover → cache check → stream → analyze → aggregate → save cache.
+   * Returns a ProjectStats payload ready for reporters.
+   *
+   * @param onProgress Optional callback fired per file for progress tracking.
+   */
+  async run(onProgress?: (current: number, total: number, filePath: string) => void): Promise<ProjectStats> {
+    // 0. Cache setup
+    if (this.clearCacheFirst) {
+      await this.cache.clear();
+    }
+    await this.cache.load();
+
+    // 1. Discover files
+    const scannedFiles = await this.scanner.discover(this.rootDir);
+
+    // 2. Stream each file (or use cache) and build enriched data
+    const analyzedFiles: AnalyzedFileData[] = [];
+    let current = 0;
+
+    for (const scannedFile of scannedFiles) {
+      const fileData = await this.processFile(scannedFile);
+      analyzedFiles.push(fileData);
+      current++;
+
+      if (onProgress) {
+        onProgress(current, scannedFiles.length, scannedFile.filePath);
+      }
+    }
+
+    // 3. Run each plugin against the full analyzed data
+    const pluginResults = new Map<string, PluginResult>();
+    for (const plugin of this.plugins) {
+      const result = plugin.analyze(analyzedFiles);
+      pluginResults.set(plugin.name, result);
+    }
+
+    // 4. Update cache with fresh per-file metrics from plugins
+    for (const file of analyzedFiles) {
+      const metrics: Record<string, number> = {};
+      for (const [pluginName, result] of pluginResults) {
+        const value = result.perFile.get(file.filePath);
+        if (value !== undefined) {
+          metrics[pluginName] = value;
+        }
+      }
+
+      try {
+        const stat = await fsp.stat(file.filePath);
+        this.cache.set(file.filePath, stat.mtimeMs, stat.size, metrics);
+      } catch {
+        // File may have been deleted between discover and cache save — skip
+      }
+    }
+
+    // 5. Save cache to disk
+    await this.cache.save();
+
+    // 6. Compute language distribution
+    const langPlugin = this.plugins.find(
+      (p): p is LanguageDistributionPlugin => p.name === 'LanguageDistribution'
+    ) as LanguageDistributionPlugin | undefined;
+    const languageDistribution = langPlugin
+      ? langPlugin.getDistribution(analyzedFiles)
+      : new Map<string, number>();
+
+    // 7. Compute largest files
+    const largestPlugin = this.plugins.find(
+      (p): p is LargestFilesPlugin => p.name === 'LargestFiles'
+    ) as LargestFilesPlugin | undefined;
+    const largestFiles = largestPlugin
+      ? largestPlugin.getTopFiles(analyzedFiles)
+      : [];
+
+    return {
+      rootDir: this.rootDir,
+      totalFiles: scannedFiles.length,
+      pluginResults,
+      languageDistribution,
+      largestFiles,
+      scannedAt: new Date(),
+    };
+  }
+
+  /**
+   * Processes a single file: checks cache first, streams if cache miss.
+   */
+  private async processFile(scannedFile: ScannedFile): Promise<AnalyzedFileData> {
+    // Check cache (we need the current stat to compare)
+    try {
+      const stat = await fsp.stat(scannedFile.filePath);
+      const cached = this.cache.lookup(scannedFile.filePath, stat.mtimeMs, stat.size);
+
+      if (cached !== null) {
+        // Cache hit — we still need AnalyzedFileData for the plugins.
+        // Since plugins need `lines`, we need to re-stream on cache miss.
+        // For cache hits, we can't avoid re-reading if plugins need full line data.
+        // However the cache stores per-file metrics directly, so for a future
+        // optimization we could bypass plugins entirely. For now, we still stream
+        // but the cache mechanism is in place for the next optimization pass.
+      }
+    } catch {
+      // stat failed — proceed with streaming
+    }
+
+    return this.streamAndParse(scannedFile);
+  }
+
+  /**
+   * Streams a single file and collects its lines.
+   * Uses the Scanner's streaming API to avoid loading the entire file at once.
+   */
+  private async streamAndParse(scannedFile: ScannedFile): Promise<AnalyzedFileData> {
+    const lines: string[] = [];
+    let remainder = '';
+
+    await this.scanner.streamFile(scannedFile.filePath, (chunk, isLast) => {
+      if (chunk.length === 0 && isLast) {
+        // Flush any remaining partial line
+        if (remainder.length > 0) {
+          lines.push(remainder);
+          remainder = '';
+        }
+        return;
+      }
+
+      const text = remainder + chunk.toString('utf8');
+      const parts = text.split('\n');
+
+      // All complete lines (everything except the last element which may be partial)
+      for (let i = 0; i < parts.length - 1; i++) {
+        lines.push(parts[i]);
+      }
+
+      // Keep the last part as remainder (may be partial line)
+      remainder = parts[parts.length - 1];
+    });
+
+    return {
+      filePath: scannedFile.filePath,
+      size: scannedFile.size,
+      extension: path.extname(scannedFile.filePath),
+      lines,
+    };
+  }
+}

package/src/core/cache.ts

@@ -0,0 +1,130 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Per-file cached entry storing metrics and invalidation keys.
+ */
+export interface CacheEntry {
+  /** Last modified time in ms (from stat.mtimeMs). */
+  mtimeMs: number;
+  /** File size in bytes (from stat.size). */
+  size: number;
+  /** Cached plugin results keyed by plugin name. */
+  metrics: Record<string, number>;
+}
+
+/**
+ * Shape of the .kountcache.json file on disk.
+ */
+interface CacheFile {
+  version: number;
+  entries: Record<string, CacheEntry>;
+}
+
+const CACHE_VERSION = 1;
+const CACHE_FILENAME = '.kountcache.json';
+
+/**
+ * Manages the .kountcache.json file for incremental scanning.
+ * Uses mtime + size to determine if a file needs re-scanning.
+ */
+export class CacheManager {
+  private cachePath: string;
+  private entries: Map<string, CacheEntry> = new Map();
+  private enabled: boolean;
+  private dirty = false;
+
+  constructor(rootDir: string, enabled: boolean = true) {
+    this.cachePath = path.join(path.resolve(rootDir), CACHE_FILENAME);
+    this.enabled = enabled;
+  }
+
+  /**
+   * Loads the cache from disk. If it doesn't exist or is corrupt, starts fresh.
+   */
+  async load(): Promise<void> {
+    if (!this.enabled) return;
+
+    try {
+      const raw = await fsp.readFile(this.cachePath, 'utf8');
+      const parsed: CacheFile = JSON.parse(raw);
+
+      if (parsed.version !== CACHE_VERSION) {
+        // Version mismatch — discard and start fresh
+        this.entries = new Map();
+        return;
+      }
+
+      this.entries = new Map(Object.entries(parsed.entries));
+    } catch {
+      // File doesn't exist or is corrupt — start with empty cache
+      this.entries = new Map();
+    }
+  }
+
+  /**
+   * Checks whether a file's cached entry is still valid by comparing
+   * mtime and size from the current stat against the stored values.
+   *
+   * @returns The cached metrics if valid, or null if the file needs re-scanning.
+   */
+  lookup(filePath: string, currentMtimeMs: number, currentSize: number): Record<string, number> | null {
+    if (!this.enabled) return null;
+
+    const entry = this.entries.get(filePath);
+    if (!entry) return null;
+
+    if (entry.mtimeMs === currentMtimeMs && entry.size === currentSize) {
+      return entry.metrics;
+    }
+
+    // Invalidated — mtime or size changed
+    return null;
+  }
+
+  /**
+   * Stores or updates a file's cache entry after scanning.
+   */
+  set(filePath: string, mtimeMs: number, size: number, metrics: Record<string, number>): void {
+    if (!this.enabled) return;
+
+    this.entries.set(filePath, { mtimeMs, size, metrics });
+    this.dirty = true;
+  }
+
+  /**
+   * Persists the cache to disk if any entries were updated.
+   */
+  async save(): Promise<void> {
+    if (!this.enabled || !this.dirty) return;
+
+    const cacheFile: CacheFile = {
+      version: CACHE_VERSION,
+      entries: Object.fromEntries(this.entries),
+    };
+
+    await fsp.writeFile(this.cachePath, JSON.stringify(cacheFile, null, 2), 'utf8');
+    this.dirty = false;
+  }
+
+  /**
+   * Removes the cache file from disk.
+   */
+  async clear(): Promise<void> {
+    this.entries = new Map();
+    this.dirty = false;
+
+    try {
+      await fsp.unlink(this.cachePath);
+    } catch {
+      // File didn't exist — that's fine
+    }
+  }
+
+  /**
+   * Returns the number of cached entries (for diagnostics).
+   */
+  get size(): number {
+    return this.entries.size;
+  }
+}

package/src/index.tsx

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+import React, { useState, useEffect, useCallback } from 'react';
+import { render, Box, Text, useApp } from 'ink';
+import { createCli } from './cli/parser.js';
+import { resolveConfig } from './cli/config-resolver.js';
+import type { KountConfig } from './cli/config-resolver.js';
+import { Aggregator } from './core/aggregator.js';
+import type { ProjectStats } from './plugins/types.js';
+import { Splash } from './reporters/terminal/Splash.js';
+import { Progress } from './reporters/terminal/Progress.js';
+import { Summary } from './reporters/terminal/Summary.js';
+import { Wizard } from './reporters/terminal/Wizard.js';
+import type { WizardResult } from './reporters/terminal/Wizard.js';
+import { writeMarkdownReport } from './reporters/markdown.js';
+import { serveHtmlDashboard } from './reporters/html.js';
+
+// ---------------------------------------------------------------------------
+// Non-interactive execution (markdown / html modes, or terminal with flags)
+// ---------------------------------------------------------------------------
+
+async function runHeadless(config: KountConfig): Promise<void> {
+    const aggregator = new Aggregator(config.rootDir, {
+        respectGitignore: config.respectGitignore,
+        cacheEnabled: config.cache.enabled,
+        clearCache: config.cache.clearFirst,
+    });
+
+    const stats = await aggregator.run();
+
+    if (config.outputMode === 'markdown') {
+        const outputPath = await writeMarkdownReport(stats, config.outputPath, config.force);
+        process.stdout.write(`Markdown report written to ${outputPath}\n`);
+    } else if (config.outputMode === 'html') {
+        const { url } = await serveHtmlDashboard(stats);
+        process.stdout.write(`Dashboard running at ${url}\nPress Ctrl+C to stop.\n`);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Ink Terminal UI App
+// ---------------------------------------------------------------------------
+
+type AppPhase = 'splash' | 'wizard' | 'scanning' | 'done';
+
+interface AppProps {
+    config: KountConfig;
+    needsWizard: boolean;
+}
+
+function App({ config: initialConfig, needsWizard }: AppProps): React.ReactElement {
+    const { exit } = useApp();
+    const [phase, setPhase] = useState<AppPhase>(needsWizard ? 'splash' : 'scanning');
+    const [config, setConfig] = useState<KountConfig>(initialConfig);
+    const [progress, setProgress] = useState({ current: 0, total: 0, file: '' });
+    const [stats, setStats] = useState<ProjectStats | null>(null);
+    const [error, setError] = useState<string | null>(null);
+
+    // Show splash briefly, then move to wizard
+    useEffect(() => {
+        if (phase === 'splash') {
+            const timer = setTimeout(() => setPhase('wizard'), 1500);
+            return () => clearTimeout(timer);
+        }
+        return undefined;
+    }, [phase]);
+
+    // Run the scan when entering the scanning phase
+    useEffect(() => {
+        if (phase !== 'scanning') return;
+
+        const aggregator = new Aggregator(config.rootDir, {
+            respectGitignore: config.respectGitignore,
+            cacheEnabled: config.cache.enabled,
+            clearCache: config.cache.clearFirst,
+        });
+
+        aggregator
+            .run((current, total, filePath) => {
+                setProgress({ current, total, file: filePath });
+            })
+            .then((result) => {
+                setStats(result);
+                setPhase('done');
+            })
+            .catch((err: unknown) => {
+                setError(err instanceof Error ? err.message : String(err));
+                setPhase('done');
+            });
+    }, [phase, config]);
+
+    const handleWizardComplete = useCallback((result: WizardResult) => {
+        setConfig((prev) => ({
+            ...prev,
+            rootDir: result.rootDir,
+            outputMode: result.outputMode,
+            includeTests: result.includeTests,
+        }));
+        setPhase('scanning');
+    }, []);
+
+    // Auto-exit after done phase is displayed
+    useEffect(() => {
+        if (phase === 'done' && stats) {
+            // Give the user a moment to see the results
+            const timer = setTimeout(() => exit(), 500);
+            return () => clearTimeout(timer);
+        }
+        return undefined;
+    }, [phase, stats, exit]);
+
+    return (
+        <Box flexDirection= "column" >
+        { phase === 'splash' && <Splash />
+}
+{ phase === 'wizard' && <Wizard onComplete={ handleWizardComplete } /> }
+{
+    phase === 'scanning' && (
+        <Box flexDirection="column" >
+            <Progress
+            current={ progress.current }
+    total = { progress.total }
+    currentFile = { progress.file }
+        />
+        </Box>
+      )
+}
+{
+    phase === 'done' && error && (
+        <Box marginY={ 1 }>
+            <Text color="red" bold > Error: { error } </Text>
+                </Box>
+      )
+}
+{ phase === 'done' && stats && <Summary stats={ stats } /> }
+</Box>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+    const cliFlags = createCli(process.argv);
+    const config = await resolveConfig(cliFlags);
+
+    if (config.outputMode === 'terminal') {
+        // Determine if we need the wizard (no explicit flags were passed)
+        const hasExplicitFlags = cliFlags.rootDir !== undefined || cliFlags.outputMode !== undefined;
+
+        render(
+            React.createElement(App, {
+                config,
+                needsWizard: !hasExplicitFlags,
+            })
+        );
+    } else {
+        // Markdown or HTML — run headless
+        await runHeadless(config);
+    }
+}
+
+main().catch((err: unknown) => {
+    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/src/plugins/built-in/blank-lines.ts

@@ -0,0 +1,26 @@
+import type { AnalyzedFileData, AnalyzerPlugin, PluginResult } from '../types.js';
+
+/**
+ * Counts blank (empty or whitespace-only) lines across all scanned files.
+ */
+export class BlankLinesPlugin implements AnalyzerPlugin {
+  readonly name = 'BlankLines';
+
+  analyze(files: AnalyzedFileData[]): PluginResult {
+    const perFile = new Map<string, number>();
+    let summaryValue = 0;
+
+    for (const file of files) {
+      let blankCount = 0;
+      for (const line of file.lines) {
+        if (line.trim() === '') {
+          blankCount++;
+        }
+      }
+      perFile.set(file.filePath, blankCount);
+      summaryValue += blankCount;
+    }
+
+    return { pluginName: this.name, summaryValue, perFile };
+  }
+}

package/src/plugins/built-in/comment-lines.ts

@@ -0,0 +1,90 @@
+import { getCommentSyntax } from '../../utils/language-map.js';
+import type { AnalyzedFileData, AnalyzerPlugin, PluginResult } from '../types.js';
+
+/**
+ * Counts comment lines across all scanned files.
+ * Handles single-line comments (//, #, --, ;) and block comments (/* *​/, <!-- -->).
+ */
+export class CommentLinesPlugin implements AnalyzerPlugin {
+  readonly name = 'CommentLines';
+
+  analyze(files: AnalyzedFileData[]): PluginResult {
+    const perFile = new Map<string, number>();
+    let summaryValue = 0;
+
+    for (const file of files) {
+      const commentCount = this.countComments(file);
+      perFile.set(file.filePath, commentCount);
+      summaryValue += commentCount;
+    }
+
+    return { pluginName: this.name, summaryValue, perFile };
+  }
+
+  private countComments(file: AnalyzedFileData): number {
+    const syntaxes = getCommentSyntax(file.extension);
+    if (syntaxes.length === 0) return 0;
+
+    // Separate single-line and block comment markers
+    const singleLineMarkers: string[] = [];
+    const blockMarkers: Array<{ open: string; close: string }> = [];
+
+    for (const syntax of syntaxes) {
+      if (syntax.includes(' ')) {
+        // Block comment syntax like '/* */' or '<!-- -->'
+        const parts = syntax.split(' ');
+        if (parts.length === 2) {
+          blockMarkers.push({ open: parts[0], close: parts[1] });
+        }
+      } else {
+        // Single-line comment syntax like '//' or '#'
+        singleLineMarkers.push(syntax);
+      }
+    }
+
+    let commentCount = 0;
+    let inBlockComment = false;
+    let currentBlockClose = '';
+
+    for (const line of file.lines) {
+      const trimmed = line.trim();
+
+      if (inBlockComment) {
+        commentCount++;
+        if (trimmed.includes(currentBlockClose)) {
+          inBlockComment = false;
+          currentBlockClose = '';
+        }
+        continue;
+      }
+
+      // Check for block comment opening
+      let isBlockStart = false;
+      for (const block of blockMarkers) {
+        if (trimmed.includes(block.open)) {
+          commentCount++;
+          isBlockStart = true;
+          // Check if block closes on the same line
+          const afterOpen = trimmed.substring(trimmed.indexOf(block.open) + block.open.length);
+          if (!afterOpen.includes(block.close)) {
+            inBlockComment = true;
+            currentBlockClose = block.close;
+          }
+          break;
+        }
+      }
+
+      if (isBlockStart) continue;
+
+      // Check for single-line comments
+      for (const marker of singleLineMarkers) {
+        if (trimmed.startsWith(marker)) {
+          commentCount++;
+          break;
+        }
+      }
+    }
+
+    return commentCount;
+  }
+}

package/src/plugins/built-in/file-size.ts

@@ -0,0 +1,20 @@
+import type { AnalyzedFileData, AnalyzerPlugin, PluginResult } from '../types.js';
+
+/**
+ * Computes total file size (bytes) across all scanned files.
+ */
+export class FileSizePlugin implements AnalyzerPlugin {
+  readonly name = 'FileSize';
+
+  analyze(files: AnalyzedFileData[]): PluginResult {
+    const perFile = new Map<string, number>();
+    let summaryValue = 0;
+
+    for (const file of files) {
+      perFile.set(file.filePath, file.size);
+      summaryValue += file.size;
+    }
+
+    return { pluginName: this.name, summaryValue, perFile };
+  }
+}