@cod3vil/kount-cli 1.0.0

package/README.md

@@ -0,0 +1,375 @@
+<p align="center">
+<pre>
+ ██╗  ██╗ ██████╗ ██╗   ██╗███╗   ██╗████████╗
+ ██║ ██╔╝██╔═══██╗██║   ██║████╗  ██║╚══██╔══╝
+ █████╔╝ ██║   ██║██║   ██║██╔██╗ ██║   ██║
+ ██╔═██╗ ██║   ██║██║   ██║██║╚██╗██║   ██║
+ ██║  ██╗╚██████╔╝╚██████╔╝██║ ╚████║   ██║
+ ╚═╝  ╚═╝ ╚═════╝  ╚═════╝ ╚═╝  ╚═══╝   ╚═╝
+</pre>
+</p>
+
+<p align="center">
+  <strong>Project Intelligence for Codebases</strong>
+</p>
+
+<p align="center">
+  <em>Analyze your code with precision. Stream-based. Cached. Beautiful.</em>
+</p>
+
+<p align="center">
+  <a href="#installation">Installation</a> •
+  <a href="#quick-start">Quick Start</a> •
+  <a href="#features">Features</a> •
+  <a href="#cli-reference">CLI Reference</a> •
+  <a href="#architecture">Architecture</a> •
+  <a href="#configuration">Configuration</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+## What is Kount?
+
+**Kount** is a codebase intelligence CLI tool that scans your project and delivers precise metrics — total lines, code lines, blank lines, comments, file sizes, language distribution, and more. It outputs results as a stunning **terminal UI**, a clean **Markdown report**, or an interactive **HTML dashboard**.
+
+Built with [Bun](https://bun.sh), [TypeScript](https://www.typescriptlang.org/), and [Ink](https://github.com/vadimdemedes/ink) (React for CLIs).
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Stream-Based Scanning** | Files are read chunk-by-chunk via `fs.createReadStream`. No file is ever fully loaded into memory. |
+| **Incremental Cache** | Uses `mtime` + `size` invalidation to skip unchanged files on subsequent runs. |
+| **Plugin Architecture** | 7 built-in analyzers, each implementing a clean `AnalyzerPlugin` interface. |
+| **Three Output Modes** | Terminal (Ink), Markdown (with idempotent `KOUNT:START/END` markers), and HTML (Tailwind + Alpine.js dashboard). |
+| **Interactive Wizard** | When run without flags, a step-by-step TUI wizard guides configuration. |
+| **Respects Ignore Rules** | Automatically reads `.gitignore` and `.kountignore` files recursively. |
+| **Config File Support** | Configure defaults via `.kountrc.json` or `.kountrc.yaml`. |
+
+---
+
+## Installation
+
+Install globally from npm using your preferred package manager:
+
+```bash
+# npm
+npm install -g @cod3vil/kount-cli
+
+# pnpm
+pnpm add -g @cod3vil/kount-cli
+
+# bun
+bun add -g @cod3vil/kount-cli
+```
+
+Once installed, the `kount` command is available globally.
+
+### Install from source
+
+Alternatively, clone and run directly:
+
+```bash
+git clone https://github.com/michaelnji/kount.git
+cd kount
+bun install
+bun run dev
+```
+
+---
+
+## Quick Start
+
+### Interactive mode (Wizard)
+
+Simply run kount without any flags to launch the interactive wizard:
+
+```bash
+kount
+```
+
+The wizard will guide you through:
+1. **Root directory** — which directory to scan
+2. **Output mode** — terminal, markdown, or html
+3. **Include tests** — whether to include test files
+
+### Scan and display in terminal
+
+```bash
+kount -d ./my-project
+```
+
+### Generate a Markdown report
+
+```bash
+kount --output-mode markdown --output ./REPORT.md
+```
+
+### Launch the HTML dashboard
+
+```bash
+kount --output-mode html
+```
+
+This auto-opens your browser with a sortable, interactive dashboard including a **Help page** with full CLI reference and developer info.
+
+---
+
+## CLI Reference
+
+```
+Usage: kount [options]
+
+Project Intelligence for Codebases — analyze your code with precision.
+
+Options:
+  -V, --version              Display version number
+  -d, --root-dir <path>      Root directory to scan (default: current directory)
+  -o, --output-mode <mode>   Output mode: terminal, markdown, or html
+  -t, --include-tests        Include test files in the analysis
+  -f, --force                Force overwrite output files (for markdown mode)
+  --output <path>            Output file path (for markdown mode)
+  --no-gitignore             Ignore .gitignore rules
+  --no-cache                 Disable caching
+  --clear-cache              Clear the cache before scanning
+  -h, --help                 Display help for command
+```
+
+### Examples
+
+```bash
+# Scan current directory, display in terminal
+kount
+
+# Scan a specific project
+kount -d ~/projects/my-app
+
+# Generate markdown report, overwriting any existing KOUNT section
+kount -o markdown -f
+
+# Launch HTML dashboard
+kount -o html
+
+# Scan including test files, no cache
+kount -t --no-cache
+
+# Clear stale cache, then scan
+kount --clear-cache
+```
+
+---
+
+## Output Modes
+
+### Terminal (default)
+
+An Ink-powered React TUI with:
+- **Splash screen** — ASCII logo on launch
+- **Progress bar** — color-coded (red → yellow → green) with current file display
+- **Summary panel** — files, lines, code ratio, language distribution, largest files
+
+### Markdown
+
+Generates a report with `<!-- KOUNT:START -->` / `<!-- KOUNT:END -->` markers. Running kount again will **replace** the existing section in-place, making it safe to commit to your README.
+
+| Behavior | When |
+|----------|------|
+| Creates new file | File doesn't exist |
+| Appends section | File exists but has no KOUNT markers |
+| Replaces section | File has existing KOUNT markers |
+| Overwrites file | `--force` flag is used |
+
+### HTML Dashboard
+
+Serves a Tailwind CSS + Alpine.js dashboard on a local server with:
+- **Summary cards** — files, lines, code ratio, size
+- **Language distribution** — sortable bar chart
+- **Top largest files** — ranked table
+- **Help page** — about, CLI reference, developer info
+
+---
+
+## Built-in Plugins
+
+| Plugin | Metric | Description |
+|--------|--------|-------------|
+| `TotalLinesPlugin` | Total Lines | Counts all lines across all files |
+| `BlankLinesPlugin` | Blank Lines | Counts empty or whitespace-only lines |
+| `CommentLinesPlugin` | Comment Lines | Detects single-line and block comments using language-aware syntax mapping |
+| `FileSizePlugin` | File Size | Sums total file sizes in bytes |
+| `TotalFilesPlugin` | Total Files | Counts all scanned files |
+| `LanguageDistributionPlugin` | Languages | Groups files by detected programming language |
+| `LargestFilesPlugin` | Largest Files | Identifies and ranks the top 10 largest files |
+
+---
+
+## Architecture
+
+```
+src/
+├── cli/
+│   ├── config-resolver.ts    # Merges CLI flags > config file > defaults
+│   └── parser.ts             # Commander-based CLI argument parsing
+├── core/
+│   ├── aggregator.ts         # Orchestrator: Scanner → Plugins → Stats
+│   └── cache.ts              # mtime+size invalidation cache (.kountcache.json)
+├── plugins/
+│   ├── types.ts              # AnalyzerPlugin interface & ProjectStats type
+│   ├── index.ts              # Barrel export
+│   └── built-in/             # 7 built-in analyzer plugins
+├── reporters/
+│   ├── markdown.ts           # Markdown report generator with KOUNT markers
+│   ├── html.ts               # HTML dashboard with Tailwind + Alpine.js
+│   └── terminal/             # Ink components: Splash, Progress, Summary, Wizard
+├── scanner/
+│   ├── ignore-parser.ts      # .gitignore / .kountignore integration
+│   └── stream-reader.ts      # Recursive directory walker + chunk streamer
+├── utils/
+│   └── language-map.ts       # File extension → comment syntax mapping
+└── index.tsx                 # Main entry point
+```
+
+### Data Flow
+
+```
+CLI Flags + Config File
+        │
+        ▼
+  Config Resolver    ──→   Resolved KountConfig
+        │
+        ▼
+    Aggregator
+        │
+        ├──→ Scanner (discovers files, streams chunks)
+        ├──→ Plugins (analyze each file's data)
+        ├──→ Cache (load/save per-file metrics)
+        │
+        ▼
+   ProjectStats
+        │
+        ├──→ Terminal Reporter (Ink)
+        ├──→ Markdown Reporter
+        └──→ HTML Reporter
+```
+
+---
+
+## Configuration
+
+### `.kountrc.json`
+
+Place a `.kountrc.json` in your project root to set defaults:
+
+```json
+{
+  "rootDir": ".",
+  "outputMode": "terminal",
+  "includeTests": false,
+  "respectGitignore": true,
+  "cache": {
+    "enabled": true,
+    "clearFirst": false
+  }
+}
+```
+
+### `.kountrc.yaml`
+
+Alternatively, use YAML:
+
+```yaml
+rootDir: .
+outputMode: terminal
+includeTests: false
+respectGitignore: true
+cache:
+  enabled: true
+  clearFirst: false
+```
+
+### `.kountignore`
+
+Works like `.gitignore` — add glob patterns for files/directories kount should skip:
+
+```
+# Ignore generated files
+dist/
+coverage/
+*.min.js
+```
+
+### Priority
+
+Configuration is resolved with this precedence:
+
+```
+CLI Flags  >  Config File (.kountrc.json/.yaml)  >  Defaults
+```
+
+---
+
+## Testing
+
+Kount has comprehensive tests covering all layers:
+
+```bash
+# Run all tests
+bun test
+
+# Watch mode
+bun run test:watch
+```
+
+**Test suite: 28 tests, 0 failures**
+
+| Test File | Coverage |
+|-----------|----------|
+| `tests/scanner.test.ts` | File discovery, ignore rules, chunk streaming |
+| `tests/plugins.test.ts` | All 7 plugins + edge cases |
+| `tests/cache.test.ts` | Load, save, hit, miss (mtime/size), clear, disabled mode |
+| `tests/reporters.test.ts` | Markdown generation, file write modes, HTML generation |
+
+---
+
+## Tech Stack
+
+| Technology | Role |
+|------------|------|
+| [Bun](https://bun.sh) | Runtime, package manager, bundler |
+| [TypeScript](https://www.typescriptlang.org/) | Strict mode, ESM |
+| [Ink](https://github.com/vadimdemedes/ink) | React-based terminal UI |
+| [Commander](https://github.com/tj/commander.js) | CLI argument parsing |
+| [Vitest](https://vitest.dev/) | Testing framework |
+| [Tailwind CSS](https://tailwindcss.com/) | HTML dashboard styling (CDN) |
+| [Alpine.js](https://alpinejs.dev/) | HTML dashboard interactivity (CDN) |
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feat/my-feature`
+3. Write tests for your changes
+4. Run `bun test` to ensure all tests pass
+5. Commit your changes: `git commit -m "feat: add my feature"`
+6. Push to the branch: `git push origin feat/my-feature`
+7. Open a Pull Request
+
+---
+
+## Author
+
+**Michael Nji** — Full stack web developer with a passion for building beautiful and robust web projects.
+
+- 🌐 [Portfolio](https://michaelnji.codes)
+- 🐙 [GitHub](https://github.com/michaelnji)
+- ✍️ [Blog](https://michaelnji.codes/blog)
+
+---
+
+## License
+
+MIT © [Michael Nji](https://michaelnji.codes)

package/bin/kount.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import './src/index.tsx';

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@cod3vil/kount-cli",
+  "packageManager": "bun@1.3.5",
+  "version": "1.0.0",
+  "description": "Project Intelligence for Codebases — analyze your code with precision.",
+  "module": "src/index.tsx",
+  "type": "module",
+  "bin": {
+    "kount": "./bin/kount.js"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "bun run src/index.tsx",
+    "start": "bun run src/index.tsx",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "bun build ./src/index.tsx --compile --external react-devtools-core --outfile dist/kount",
+    "prepublishOnly": "bun run build",
+    "release": "np"
+  },
+  "np": {
+    "yarn": false,
+    "testScript": "test",
+    "branch": "main"
+  },
+  "keywords": [
+    "cli",
+    "codebase",
+    "analysis",
+    "loc",
+    "lines-of-code",
+    "project-stats",
+    "developer-tools"
+  ],
+  "author": "Michael Nji",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/michaelnji/kount"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.3.2",
+    "@types/react": "^19.2.14",
+    "np": "^11.0.2",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^14.0.3",
+    "ignore": "^7.0.5",
+    "ink": "^6.8.0",
+    "react": "^19.2.4"
+  }
+}

package/src/cli/config-resolver.ts

@@ -0,0 +1,175 @@
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Resolved configuration used throughout the application.
+ */
+export interface KountConfig {
+  rootDir: string;
+  outputMode: 'terminal' | 'markdown' | 'html';
+  includeTests: boolean;
+  respectGitignore: boolean;
+  cache: {
+    enabled: boolean;
+    clearFirst: boolean;
+  };
+  force: boolean;
+  outputPath?: string;
+}
+
+/**
+ * Shape of the .kountrc.json / .kountrc.yaml config file.
+ */
+interface ConfigFile {
+  rootDir?: string;
+  outputMode?: string;
+  includeTests?: boolean;
+  respectGitignore?: boolean;
+  cache?: {
+    enabled?: boolean;
+    clearFirst?: boolean;
+  };
+}
+
+/**
+ * CLI flags that can override the config file.
+ */
+export interface CliFlags {
+  rootDir?: string;
+  outputMode?: string;
+  includeTests?: boolean;
+  respectGitignore?: boolean;
+  cache?: boolean;
+  clearCache?: boolean;
+  force?: boolean;
+  output?: string;
+}
+
+const DEFAULTS: KountConfig = {
+  rootDir: '.',
+  outputMode: 'terminal',
+  includeTests: false,
+  respectGitignore: true,
+  cache: {
+    enabled: true,
+    clearFirst: false,
+  },
+  force: false,
+};
+
+/**
+ * Attempts to load a config file from the given directory.
+ * Checks for .kountrc.json first, then .kountrc.yaml.
+ */
+async function loadConfigFile(dir: string): Promise<ConfigFile> {
+  const jsonPath = path.join(dir, '.kountrc.json');
+
+  try {
+    const raw = await fsp.readFile(jsonPath, 'utf8');
+    return JSON.parse(raw) as ConfigFile;
+  } catch {
+    // JSON not found or invalid — try YAML
+  }
+
+  // YAML support: we'll parse manually for the simple flat structure
+  // rather than adding a heavy dependency. This handles basic key: value pairs.
+  const yamlPath = path.join(dir, '.kountrc.yaml');
+  try {
+    const raw = await fsp.readFile(yamlPath, 'utf8');
+    return parseSimpleYaml(raw);
+  } catch {
+    // No config file found — use defaults
+  }
+
+  return {};
+}
+
+/**
+ * Minimal YAML parser for flat config files.
+ * Handles: string, boolean, and nested single-level objects.
+ */
+function parseSimpleYaml(raw: string): ConfigFile {
+  const result: Record<string, unknown> = {};
+  let currentObject: Record<string, unknown> | null = null;
+  let currentKey = '';
+
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+
+    const indent = line.length - line.trimStart().length;
+
+    if (indent > 0 && currentObject !== null) {
+      // Nested key
+      const match = trimmed.match(/^(\w+)\s*:\s*(.+)$/);
+      if (match) {
+        currentObject[match[1]] = parseYamlValue(match[2]);
+      }
+    } else {
+      // Top-level key
+      const match = trimmed.match(/^(\w+)\s*:\s*(.*)$/);
+      if (match) {
+        const key = match[1];
+        const value = match[2].trim();
+
+        if (value === '') {
+          // Start of nested object
+          currentKey = key;
+          currentObject = {};
+          result[key] = currentObject;
+        } else {
+          currentObject = null;
+          result[key] = parseYamlValue(value);
+        }
+      }
+    }
+  }
+
+  return result as unknown as ConfigFile;
+}
+
+function parseYamlValue(val: string): string | boolean | number {
+  if (val === 'true') return true;
+  if (val === 'false') return false;
+  const num = Number(val);
+  if (!isNaN(num) && val !== '') return num;
+  // Strip quotes
+  if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+    return val.slice(1, -1);
+  }
+  return val;
+}
+
+/**
+ * Resolves the final configuration from:
+ *   CLI flags > Config file > Defaults
+ *
+ * @param cliFlags Parsed CLI arguments.
+ * @param cwd Current working directory (for finding config files).
+ */
+export async function resolveConfig(cliFlags: CliFlags, cwd: string = process.cwd()): Promise<KountConfig> {
+  const fileConfig = await loadConfigFile(cwd);
+
+  const outputMode = validateOutputMode(
+    cliFlags.outputMode ?? fileConfig.outputMode ?? DEFAULTS.outputMode
+  );
+
+  return {
+    rootDir: path.resolve(cwd, cliFlags.rootDir ?? fileConfig.rootDir ?? DEFAULTS.rootDir),
+    outputMode,
+    includeTests: cliFlags.includeTests ?? fileConfig.includeTests ?? DEFAULTS.includeTests,
+    respectGitignore: cliFlags.respectGitignore ?? fileConfig.respectGitignore ?? DEFAULTS.respectGitignore,
+    cache: {
+      enabled: cliFlags.cache ?? fileConfig.cache?.enabled ?? DEFAULTS.cache.enabled,
+      clearFirst: cliFlags.clearCache ?? fileConfig.cache?.clearFirst ?? DEFAULTS.cache.clearFirst,
+    },
+    force: cliFlags.force ?? DEFAULTS.force,
+    outputPath: cliFlags.output,
+  };
+}
+
+function validateOutputMode(mode: string): 'terminal' | 'markdown' | 'html' {
+  const valid = ['terminal', 'markdown', 'html'];
+  if (valid.includes(mode)) return mode as 'terminal' | 'markdown' | 'html';
+  return 'terminal';
+}

package/src/cli/parser.ts

@@ -0,0 +1,52 @@
+import { Command } from 'commander';
+import type { CliFlags } from './config-resolver.js';
+
+/**
+ * Creates and configures the Commander CLI program.
+ * Returns parsed CLI flags for the config resolver.
+ *
+ * Follows tuicfg-sensible-defaults, tuicfg-flags-over-args,
+ * and tuicfg-help-system guidelines from terminal-ui skill.
+ */
+export function createCli(argv: string[]): CliFlags {
+  const program = new Command();
+
+  program
+    .name('kount')
+    .description('Project Intelligence for Codebases — analyze your code with precision.')
+    .version('1.0.0')
+    .option('-d, --root-dir <path>', 'Root directory to scan (default: current directory)')
+    .option(
+      '-o, --output-mode <mode>',
+      'Output mode: terminal, markdown, or html (default: terminal)'
+    )
+    .option('-t, --include-tests', 'Include test files in the analysis')
+    .option('--no-gitignore', 'Ignore .gitignore rules')
+    .option('--no-cache', 'Disable caching')
+    .option('--clear-cache', 'Clear the cache before scanning')
+    .option('-f, --force', 'Force overwrite output files (for markdown mode)')
+    .option('--output <path>', 'Output file path (for markdown mode)')
+    .parse(argv);
+
+  const opts = program.opts<{
+    rootDir?: string;
+    outputMode?: string;
+    includeTests?: boolean;
+    gitignore?: boolean;
+    cache?: boolean;
+    clearCache?: boolean;
+    force?: boolean;
+    output?: string;
+  }>();
+
+  return {
+    rootDir: opts.rootDir,
+    outputMode: opts.outputMode,
+    includeTests: opts.includeTests,
+    respectGitignore: opts.gitignore, // Commander converts --no-gitignore to gitignore: false
+    cache: opts.cache, // Commander converts --no-cache to cache: false
+    clearCache: opts.clearCache,
+    force: opts.force,
+    output: opts.output,
+  };
+}