@sebassdc/crap4ts 0.1.0

package/dist/report.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRunner = detectRunner;
+exports.runCoverage = runCoverage;
+exports.evaluateThresholds = evaluateThresholds;
+exports.runReport = runReport;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const child_process_1 = require("child_process");
+const core_1 = require("./core");
+const coverage_1 = require("./coverage");
+const crap_1 = require("./crap");
+const VITEST_CONFIGS = ['vitest.config.ts', 'vitest.config.js', 'vitest.config.mts', 'vitest.config.mjs'];
+const JEST_CONFIGS = ['jest.config.ts', 'jest.config.js', 'jest.config.mjs'];
+function hasJestInPackageJson() {
+    if (!(0, fs_1.existsSync)('package.json'))
+        return false;
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)('package.json', 'utf-8'));
+        return !!(pkg.devDependencies?.jest || pkg.dependencies?.jest);
+    }
+    catch {
+        console.warn("Unable to parse package.json while detecting the test runner. Fix package.json or use --runner to specify explicitly.");
+        return false;
+    }
+}
+function detectRunner() {
+    if (VITEST_CONFIGS.some(f => (0, fs_1.existsSync)(f)))
+        return 'vitest';
+    if (JEST_CONFIGS.some(f => (0, fs_1.existsSync)(f)))
+        return 'jest';
+    if (hasJestInPackageJson())
+        return 'jest';
+    return 'vitest';
+}
+function runCoverage(runner, timeoutMs) {
+    const cmd = runner === 'vitest'
+        ? ['npx', 'vitest', 'run', '--coverage']
+        : ['npx', 'jest', '--coverage', '--coverageReporters=json'];
+    const result = (0, child_process_1.spawnSync)(cmd[0], cmd.slice(1), { stdio: 'inherit', timeout: timeoutMs });
+    const timedOut = result.signal === 'SIGTERM' && result.status === null;
+    return { ok: result.status === 0, timedOut };
+}
+function evaluateThresholds(entries, opts) {
+    if (opts.failOnCrap != null) {
+        const violations = entries.filter(e => e.crap >= opts.failOnCrap);
+        if (violations.length > 0) {
+            return `CI failed: ${violations.length} function(s) exceed CRAP threshold of ${opts.failOnCrap}`;
+        }
+    }
+    if (opts.failOnComplexity != null) {
+        const violations = entries.filter(e => e.complexity >= opts.failOnComplexity);
+        if (violations.length > 0) {
+            return `CI failed: ${violations.length} function(s) exceed complexity threshold of ${opts.failOnComplexity}`;
+        }
+    }
+    if (opts.failOnCoverageBelow != null) {
+        const violations = entries.filter(e => e.coverage < opts.failOnCoverageBelow);
+        if (violations.length > 0) {
+            return `CI failed: ${violations.length} function(s) below coverage threshold of ${opts.failOnCoverageBelow}%`;
+        }
+    }
+    return null;
+}
+function findFiles(opts) {
+    if (!(0, fs_1.existsSync)(opts.srcDir)) {
+        console.error(`Source directory '${opts.srcDir}' not found. Use --src to specify a different directory.`);
+        return null;
+    }
+    const rawFiles = (0, core_1.findSourceFiles)(opts.srcDir);
+    const excludes = opts.excludes ?? [];
+    const allFiles = excludes.length > 0
+        ? rawFiles.filter(f => !excludes.some(ex => f.includes(ex)))
+        : rawFiles;
+    if (allFiles.length === 0) {
+        console.error(`No TypeScript files found in '${opts.srcDir}'. Verify your source directory contains .ts files.`);
+        return null;
+    }
+    const filtered = (0, core_1.filterSources)(allFiles, opts.filters);
+    if (filtered.length === 0) {
+        console.error(`No files match the filters: [${opts.filters.join(', ')}]. Check your filter arguments.`);
+        return null;
+    }
+    return filtered;
+}
+function cleanStaleCoverage(coverageDir) {
+    if ((0, fs_1.existsSync)(coverageDir)) {
+        try {
+            (0, fs_1.rmSync)(coverageDir, { recursive: true, force: true });
+        }
+        catch (e) {
+            console.warn(`Warning: failed to remove stale coverage dir ${coverageDir}: ${e.message}`);
+        }
+    }
+}
+function executeCoverage(opts) {
+    const { coverageDir, timeoutMs } = opts;
+    cleanStaleCoverage(coverageDir);
+    let ok;
+    let timedOut;
+    if (opts.coverageCommand) {
+        const result = (0, child_process_1.spawnSync)(opts.coverageCommand, [], { shell: true, stdio: 'inherit', timeout: timeoutMs });
+        timedOut = result.signal === 'SIGTERM' && result.status === null;
+        ok = result.status === 0;
+    }
+    else {
+        const runner = opts.runner ?? detectRunner();
+        ({ ok, timedOut } = runCoverage(runner, timeoutMs));
+    }
+    if (timedOut) {
+        console.error(`Coverage run timed out after ${timeoutMs / 1000}s.`);
+        return { ok: false };
+    }
+    if (!ok) {
+        console.error('Coverage run failed.');
+        return { ok: false };
+    }
+    if (!(0, fs_1.existsSync)(`${coverageDir}/coverage-final.json`)) {
+        console.error(`No coverage-final.json found in ${coverageDir}/.\n` +
+            `Configure your test runner to output Istanbul JSON coverage.\n` +
+            `  Vitest: add coverage.reporter: ['json'] in vitest.config.ts\n` +
+            `  Jest:   add "json" to coverageReporters in jest.config`);
+        return { ok: false };
+    }
+    return { ok: true };
+}
+function formatOutput(entries, opts) {
+    if (opts.output === 'json') {
+        console.log((0, crap_1.formatJsonReport)(entries));
+    }
+    else if (opts.output === 'markdown') {
+        console.log((0, crap_1.formatMarkdownReport)(entries));
+    }
+    else if (opts.output === 'csv') {
+        console.log((0, crap_1.formatCsvReport)(entries));
+    }
+    else {
+        console.log((0, crap_1.formatReport)(entries));
+    }
+}
+async function runReport(opts) {
+    const files = findFiles(opts);
+    if (!files)
+        return 1;
+    const covResult = executeCoverage(opts);
+    if (!covResult.ok)
+        return 1;
+    const filesData = (0, coverage_1.parseCoverage)(opts.coverageDir);
+    const resolvedSrc = (0, path_1.resolve)(opts.srcDir);
+    const allEntries = files.flatMap(f => (0, core_1.analyzeFile)(f, filesData, resolvedSrc));
+    if (allEntries.length === 0) {
+        console.warn('No functions found. crap4ts analyzes top-level functions, arrow functions, and class methods.');
+    }
+    const sorted = (0, crap_1.sortByCrap)(allEntries);
+    const displayed = opts.top != null ? sorted.slice(0, opts.top) : sorted;
+    formatOutput(displayed, opts);
+    const failureMessage = evaluateThresholds(sorted, opts);
+    if (failureMessage) {
+        console.error(failureMessage);
+        return 1;
+    }
+    return 0;
+}

package/dist/skill-cmd.d.ts

@@ -0,0 +1,13 @@
+export type Scope = 'global' | 'project';
+export declare function bundledSkillPath(): string;
+export declare function globalSkillDir(): string;
+export declare function projectSkillDir(cwd?: string): string;
+export declare function installSkill(opts: {
+    scope: Scope;
+}): Promise<string>;
+export declare function uninstallSkill(opts: {
+    scope: Scope;
+}): Promise<boolean>;
+export declare function showSkill(): string;
+export declare function skillPath(scope: Scope): string;
+export declare function runSkillCommand(argv: string[]): Promise<number>;

package/dist/skill-cmd.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bundledSkillPath = bundledSkillPath;
+exports.globalSkillDir = globalSkillDir;
+exports.projectSkillDir = projectSkillDir;
+exports.installSkill = installSkill;
+exports.uninstallSkill = uninstallSkill;
+exports.showSkill = showSkill;
+exports.skillPath = skillPath;
+exports.runSkillCommand = runSkillCommand;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+function bundledSkillPath() {
+    const candidates = [
+        (0, path_1.join)(__dirname, 'skill', 'SKILL.md'),
+        (0, path_1.join)(__dirname, '..', 'src', 'skill', 'SKILL.md'),
+    ];
+    for (const c of candidates) {
+        if ((0, fs_1.existsSync)(c))
+            return (0, path_1.resolve)(c);
+    }
+    throw new Error(`crap4ts: bundled SKILL.md not found. Looked in:\n  ${candidates.join('\n  ')}`);
+}
+function globalSkillDir() {
+    return (0, path_1.join)((0, os_1.homedir)(), '.agents', 'skills', 'crap4ts');
+}
+function projectSkillDir(cwd = process.cwd()) {
+    return (0, path_1.join)(cwd, '.agents', 'skills', 'crap4ts');
+}
+function destDir(scope) {
+    return scope === 'global' ? globalSkillDir() : projectSkillDir();
+}
+async function installSkill(opts) {
+    const src = bundledSkillPath();
+    const dir = destDir(opts.scope);
+    (0, fs_1.mkdirSync)(dir, { recursive: true });
+    const dest = (0, path_1.join)(dir, 'SKILL.md');
+    (0, fs_1.copyFileSync)(src, dest);
+    return dest;
+}
+async function uninstallSkill(opts) {
+    const dir = destDir(opts.scope);
+    const file = (0, path_1.join)(dir, 'SKILL.md');
+    if (!(0, fs_1.existsSync)(file))
+        return false;
+    (0, fs_1.rmSync)(file, { force: true });
+    try {
+        (0, fs_1.rmSync)(dir, { recursive: false });
+    }
+    catch { /* non-empty or already gone */ }
+    return true;
+}
+function showSkill() {
+    return (0, fs_1.readFileSync)(bundledSkillPath(), 'utf-8');
+}
+function skillPath(scope) {
+    return (0, path_1.join)(destDir(scope), 'SKILL.md');
+}
+function scopeFromArgs(argv) {
+    return argv.includes('--project') ? 'project' : 'global';
+}
+async function runSkillCommand(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    const scope = scopeFromArgs(rest);
+    switch (sub) {
+        case 'install': {
+            const dest = await installSkill({ scope });
+            console.log(`Installed crap4ts skill to ${dest}`);
+            return 0;
+        }
+        case 'uninstall': {
+            const removed = await uninstallSkill({ scope });
+            console.log(removed
+                ? `Removed crap4ts skill from ${skillPath(scope)}`
+                : `No crap4ts skill installed at ${skillPath(scope)}`);
+            return 0;
+        }
+        case 'show': {
+            console.log(showSkill());
+            return 0;
+        }
+        case 'path': {
+            console.log(skillPath(scope));
+            return 0;
+        }
+        default:
+            console.error(`Unknown skill subcommand: ${sub ?? '(none)'}\n` +
+                `Usage: crap4ts skill <install|uninstall|show|path> [--project]`);
+            return 1;
+    }
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@sebassdc/crap4ts",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "CRAP metric CLI for TypeScript: combines cyclomatic complexity and test coverage to find risky code, with a bundled cross-agent AI skill.",
+  "main": "dist/api.js",
+  "types": "dist/api.d.ts",
+  "exports": {
+    ".": "./dist/api.js",
+    "./cli": "./dist/index.js"
+  },
+  "bin": {
+    "crap4ts": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src/skill/SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "typescript",
+    "cli",
+    "testing",
+    "coverage",
+    "cyclomatic-complexity",
+    "code-quality",
+    "static-analysis",
+    "metrics",
+    "crap",
+    "ai-agent",
+    "skill"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sebassdc/crap4ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sebassdc/crap4ts/issues"
+  },
+  "homepage": "https://github.com/sebassdc/crap4ts#readme",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "typescript": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/skill/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: crap4ts
+description: Use when the user asks for a CRAP report, cyclomatic complexity analysis, or code quality metrics on a TypeScript project
+---
+
+# crap4ts — CRAP Metric for TypeScript
+
+Computes the **CRAP** (Change Risk Anti-Pattern) score for every function and method in a TypeScript project. CRAP combines cyclomatic complexity with test coverage to identify functions that are both complex and under-tested.
+
+## Setup
+
+The target project must use Vitest or Jest with Istanbul JSON coverage output.
+
+**Vitest** — add to `vitest.config.ts`:
+```ts
+coverage: {
+  provider: 'v8',
+  reporter: ['text', 'json'],
+}
+```
+
+**Jest** — add to `jest.config.ts`:
+```ts
+coverageReporters: ['text', 'json']
+```
+
+Install crap4ts from source:
+```bash
+git clone https://github.com/sebassdc/crap4ts.git
+cd crap4ts
+npm install
+npm run build
+npm install -g .
+```
+
+## Usage
+
+Run from the project root (where `src/` lives):
+
+```bash
+crap4ts
+
+# Filter to specific modules
+crap4ts parser validator
+
+# Exclude paths
+crap4ts --exclude dist --exclude fixtures
+
+# Custom source directory
+crap4ts --src packages/core/src
+```
+
+crap4ts automatically deletes stale coverage data, runs the test suite with coverage, and prints the report.
+
+### CLI Options
+
+| Flag | Argument | Description | Default |
+|------|----------|-------------|---------|
+| `--src` | `<dir>` | Source directory to analyze | `src` |
+| `--exclude` | `<pattern>` | Exclude paths containing pattern (repeatable) | none |
+| `--output` | `text\|json\|markdown\|csv` | Output format | `text` |
+| `--json` | — | Shorthand for `--output json` | — |
+| `--runner` | `vitest\|jest` | Skip auto-detection, use specified runner | auto-detect |
+| `--coverage-command` | `<cmd>` | Custom shell command for coverage generation | none |
+| `--fail-on-crap` | `<n>` | Exit 1 if any function CRAP score >= n | none |
+| `--fail-on-complexity` | `<n>` | Exit 1 if any function complexity >= n | none |
+| `--fail-on-coverage-below` | `<n>` | Exit 1 if coverage < n% (0-100) | none |
+| `--top` | `<n>` | Show only top N entries (thresholds still check all) | all |
+| `--timeout` | `<seconds>` | Analysis timeout | `600` |
+| `--config` | `<path>` | Load config from specific file | auto-discover |
+| `--help, -h` | — | Show help | — |
+| `--version, -v` | — | Show version | — |
+
+### Configuration File
+
+crap4ts auto-discovers `crap4ts.config.json` or `.crap4tsrc.json` in the working directory. CLI flags override config values.
+
+```json
+{
+  "src": "lib",
+  "exclude": ["dist", "fixtures"],
+  "output": "json",
+  "runner": "vitest",
+  "coverageCommand": "npm run test:api -- --coverage",
+  "failOnCrap": 30,
+  "failOnComplexity": 15,
+  "failOnCoverageBelow": 70,
+  "top": 10,
+  "timeout": 120
+}
+```
+
+### Output Formats
+
+**Text** (default) — sorted table:
+```
+CRAP Report
+===========
+Function                       Module                              CC   Cov%     CRAP
+-------------------------------------------------------------------------------------
+complexFn                      my.module                          12  45.0%    130.2
+simpleFn                       my.module                           1 100.0%      1.0
+```
+
+**JSON** (`--json` or `--output json`):
+```json
+{
+  "tool": "crap4ts",
+  "entries": [
+    { "name": "complexFn", "module": "my.module", "complexity": 12, "coverage": 45, "crap": 130.2 }
+  ]
+}
+```
+
+**Markdown** (`--output markdown`) — pipe-table format.
+
+**CSV** (`--output csv`) — header row + data rows.
+
+### CI Integration
+
+Use `--fail-on-*` flags to enforce quality gates:
+
+```bash
+crap4ts --fail-on-crap 30 --fail-on-complexity 15 --fail-on-coverage-below 70
+```
+
+Exit codes: `0` success, `1` threshold violation or error, `2` usage error.
+
+### Custom Coverage Command
+
+For non-standard setups, bypass runner auto-detection entirely:
+
+```bash
+crap4ts --coverage-command "CI=1 yarn test --coverage --coverageReporters=json"
+```
+
+## Interpreting Scores
+
+| CRAP Score | Meaning |
+|-----------|---------|
+| 1-5       | Clean — low complexity, well tested |
+| 5-30      | Moderate — consider refactoring or adding tests |
+| 30+       | Crappy — high complexity with poor coverage |
+
+## Programmatic API
+
+```typescript
+import { generateReport } from '@sebassdc/crap4ts';
+
+const { entries } = generateReport({
+  srcDir: 'src',
+  coverageDir: 'coverage',
+  filters: ['parser', 'validator'],
+  excludes: ['__mocks__', '.stories']
+});
+
+entries.forEach(e => console.log(`${e.name}: CRAP ${e.crap}`));
+```
+
+Also exports: `extractFunctions`, `parseCoverage`, `coverageForRange`, `crapScore`, `sortByCrap`, `formatReport`, `formatJsonReport`, `formatMarkdownReport`, `formatCsvReport`, `findSourceFiles`, `filterSources`, `analyzeFile`, `sourceToModule`, `normalizePath`.
+
+## How It Works
+
+1. Deletes stale `coverage/` directory
+2. Detects test runner (Vitest or Jest) from config files, or uses `--runner` / `--coverage-command`
+3. Runs tests with coverage to generate `coverage/coverage-final.json`
+4. Finds all `.ts` / `.tsx` files under the source directory
+5. Extracts top-level functions, class methods/getters/setters, and object literal methods using the TypeScript compiler API
+6. Computes cyclomatic complexity:
+   - `if`/`else if`, ternary: +1 each
+   - `for`, `for...of`, `for...in`, `while`, `do...while`: +1 each
+   - `catch` handler: +1 each
+   - `&&`, `||`, `??`: +1 per operator
+   - `case` in `switch`: +1 each (`default` excluded)
+   - Nested functions and classes are skipped
+7. Reads `coverage/coverage-final.json` for per-statement coverage data
+8. Applies CRAP formula: `CC` x `(1 - cov)^3 + CC`
+9. Applies filters, exclusions, and `--top` limit
+10. Formats output and checks thresholds