devkit-quality 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,93 @@
+# Changelog
+
+All notable changes to this project are documented in this file. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-10-02
+
+**Heads up if you ran `devkit scan` on 0.1.0:** file discovery silently
+skipped a meaningful share of most repositories (any `build`/`out`/`vendor`/
+`dist`/`coverage`-named folder anywhere in the tree, any file with a "do not
+edit" comment anywhere in it, and anything outside a correctly-anchored
+`.gitignore` pattern), and the secret scanner only ever looked at `.js`/`.ts`
+files. A clean-looking score or a "no findings" security result from 0.1.0
+may reflect files that were never actually scanned, including `.env`, YAML,
+and JSON config files that can hold real credentials. Re-run `devkit scan` on
+0.1.1 before trusting a prior result.
+
+### Fixed
+
+- Discovery no longer silently skips source files: folders named `build`,
+  `out`, `dist`, or `coverage` are only skipped when they are build output in
+  a package root (a `src/build/` or `src/commands/out/` is scanned normally);
+  `vendor/` is never auto-skipped, since vendored/checked-in code is still
+  real, committed content; root-anchored `.gitignore` patterns (`/lib`) stay
+  anchored instead of matching at every depth; a "do not edit" note is only
+  treated as a generated-file marker when it appears in the file's leading
+  comment block, not anywhere in the file; `**/x` globs no longer false-match
+  `myx`. Discovery now uses `git ls-files` when available, so `.gitignore` is
+  applied with exact git semantics.
+- Secret scanning now covers every text file (`.env`, YAML, JSON,
+  Dockerfiles, other languages), not only JS/TS. A `.gitignore`d `.env` is no
+  longer reported as committed.
+- Dependency rules (`DEP001`/`DEP002`) are now workspace-aware: every
+  `package.json` in the repo is checked against its own files, with the
+  workspace root tolerated as a hoisting source. Previously, every
+  correctly-declared dependency in a non-root workspace/monorepo package was
+  flagged as "unlisted."
+- Scoring: security findings are now part of the overall score and cap it at
+  6.9 on a credible (high-confidence, non-test) finding, instead of being
+  computed and then discarded; architecture is only scored when
+  `architecture.layers` is configured, instead of granting free points;
+  findings inside test files count at half weight; a scan that analyzes zero
+  source files now always fails `--min-score` instead of scoring 10.
+- CLI: `--category` accepts `dead-code`-style names (previously only the
+  internal camelCase form matched, so the documented examples didn't work);
+  filtering findings with `--category`/`--severity` no longer recomputes a
+  fake score for the filtered subset; invalid `--min-score`, `--fail-on`, and
+  `--format` values are now rejected instead of silently passing.
+- Duplication detection no longer flags shared `import` headers between
+  files, or overlapping windows within the same file, as copy-pasted code.
+- An empty catch block with an explanatory comment is no longer flagged by
+  `ERR001`, matching the rule's own suggested fix.
+- Fixed the published CLI command name (`devkit`) to match the `bin` entry in
+  `package.json`.
+
+### Added
+
+- Every scanning command (`scan`, `report`, `metrics`, `fix`,
+  `baseline create`/`compare`) now accepts an optional `[path]` argument to
+  scan a directory other than the current one.
+- A `devkit-disable-file` suppression directive, alongside the existing
+  `devkit-disable-next-line`, for silencing specific rules (or all rules)
+  across a whole file.
+- Scan coverage is now reported: files found vs. analyzed vs. secret-scanned,
+  generated/oversized/binary files skipped, and scan duration.
+
+### Changed
+
+- Terminal output redesigned: live progress bar during the scan (previously a
+  spinner that never animated, since the scan is synchronous), a letter
+  grade, a scan-coverage section, per-category score bars, a severity
+  distribution bar, a file "hotspots" list, and restyled issue cards.
+- `console.*` findings (`HYGIENE001`) in a file that imports a CLI
+  argument-parsing library (commander, yargs, cac, meow, sade, clipanion) are
+  now reported at LOW confidence instead of CERTAIN, since that output is
+  usually the program's actual product, not a debug leftover. Still
+  reported, not suppressed.
+- Open-sourced the project: contributing guide, code of conduct, security
+  policy, issue/PR templates, and CI.
+
+## [0.1.0]
+
+- Initial release: deterministic scan pipeline (discovery, TypeScript
+  Compiler API parse, module graph, rules, scoring, reporting).
+- Rule categories: dead code, dependencies, complexity, duplication, error
+  handling, redundant logic, TypeScript safety, JavaScript hygiene, security,
+  architecture, repository hygiene.
+- Terminal, JSON, Markdown, and SARIF output formats.
+- `devkit init`, `scan`, `report`, `metrics`, `rules`, `explain`, `baseline`,
+  and `fix` commands.

package/README.md

@@ -1,11 +1,15 @@
 # DevKit
 
+[![CI](https://github.com/Karan071/devkit-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Karan071/devkit-cli/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/devkit-quality.svg)](https://www.npmjs.com/package/devkit-quality)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
 DevKit is a deterministic, offline code-quality scanner for JavaScript and TypeScript repositories. It walks a project, parses every source file with the TypeScript compiler, and reports a 0-10 "code quality" score backed by concrete, file-and-line findings — dead code, unused dependencies, excessive complexity, duplication, unsafe error handling, unsafe TypeScript, security anti-patterns, architecture violations, and repository hygiene issues.
 
 It does not call an LLM, an API, or the network. Every finding is reproducible from the source tree alone.
 
 ```bash
-npx devkit scan
+npx devkit-quality scan
 ```
 
 ```
@@ -33,13 +37,15 @@ DevKit Repository Scan
 - [Output formats](#output-formats)
 - [CI/CD integration](#cicd-integration)
 - [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## How it works
 
 A scan runs in a single pass over the repository:
 
-1. **Discovery** — walk the directory tree, apply configured include/exclude and ignore patterns, skip generated files, and select `.js`/`.jsx`/`.ts`/`.tsx`/`.mjs`/`.cjs` files.
-2. **Parse** — build one `ts.Program` (via the TypeScript Compiler API) covering every discovered file, with `noUnusedLocals`/`noUnusedParameters`/`noImplicitAny` enabled so the compiler itself surfaces dead bindings and implicit `any`.
+1. **Discovery** — list files with `git ls-files` (exact `.gitignore` semantics; falls back to a filesystem walk outside git), apply include/exclude and `.devkitignore`, skip generated/minified files and build output in package roots, and split files into JS/TS sources (`.js`/`.jsx`/`.ts`/`.tsx`/`.mjs`/`.cjs`/`.mts`/`.cts`, fully analyzed) and other text files (configs, `.env`, YAML, other languages — secret-scanned).
+2. **Parse & type-check** — build one `ts.Program` (via the TypeScript Compiler API) covering every discovered file, with `noUnusedLocals`/`noUnusedParameters`/`noImplicitAny` enabled so the compiler itself surfaces dead bindings and implicit `any`.
 3. **Module graph** — resolve imports, `require()`, dynamic `import()`, TypeScript path aliases, and re-exports into an internal dependency graph (edges, reverse edges, entry points, re-export targets).
 4. **Rules** — each rule module receives a shared `RuleContext` (files, program, module graph, config, `package.json`) and returns `Finding[]`.
 5. **Scoring** — findings are weighted by severity × confidence, normalized against repository size, and rolled up into per-category and overall scores.
@@ -101,7 +107,7 @@ Design principle carried over from the project's PRD (`devkit-slop-scanner-final
 | [`src/ast/comments.ts`](src/ast/comments.ts) | Collects and caches comment ranges for hygiene checks and suppressions. |
 | [`src/moduleResolution.ts`](src/moduleResolution.ts) | Resolves modules using TypeScript config, path aliases, and a per-scan cache. |
 | [`src/moduleGraph.ts`](src/moduleGraph.ts) | Resolves imports/exports/re-exports into an internal dependency graph; detects entry points and import cycles. |
-| [`src/suppressions.ts`](src/suppressions.ts) | Applies `devkit-disable-next-line` directives to findings. |
+| [`src/suppressions.ts`](src/suppressions.ts) | Applies `devkit-disable-next-line` and `devkit-disable-file` directives to findings. |
 | [`src/cliLogic.ts`](src/cliLogic.ts) | Pure finding-filter and quality-gate logic used by the CLI. |
 | [`src/config.ts`](src/config.ts) | Loads/writes `.devkitrc.json`; rule enable/disable and threshold overrides. |
 | [`src/context.ts`](src/context.ts) | `RuleContext` type shared by every rule module. |
@@ -131,7 +137,7 @@ Design principle carried over from the project's PRD (`devkit-slop-scanner-final
 
 Run `devkit rules` for the live list, or `devkit explain <RULE_ID>` for a rule's full writeup (why it matters, example, fix classification).
 
-> **Note:** `devkit-slop-scanner-final-prd.md` in the repo root is the original product-requirements document and describes a larger target surface (incremental caching, monorepo-aware scoring, rule presets, a V2 LLM layer, and more). The table above reflects what is currently implemented in `src/`; treat the PRD as the roadmap, not the current feature set. Minimal `devkit-disable-next-line` suppressions are implemented.
+> **Note:** `devkit-slop-scanner-final-prd.md` in the repo root is the original product-requirements document and describes a larger target surface (incremental caching, monorepo-aware scoring, rule presets, a V2 LLM layer, and more). The table above reflects what is currently implemented in `src/`; treat the PRD as the roadmap, not the current feature set. Minimal `devkit-disable-next-line` and `devkit-disable-file` suppressions are implemented; monorepo-aware dependency scoring (DEP001/DEP002) is implemented.
 
 ## Project layout
 
@@ -160,7 +166,7 @@ cli-tool/
 
 ## Setup
 
-Requires Node.js (for the TypeScript compiler API and `fs`/`path` usage — any reasonably current LTS version works).
+Requires Node.js `^22.12.0 || ^24.0.0 || >=26.0.0` (the version range the test suite's dependencies require; Node 18 and 20 are not supported).
 
 ```bash
 # install dependencies
@@ -202,10 +208,11 @@ Run a full scan (defaults to colored terminal output):
 
 ```bash
 devkit scan
+devkit scan ../other-repo              # scan another directory (every scanning command takes an optional path)
 devkit scan --json                     # machine-readable JSON (ScanSummary)
 devkit scan --format markdown          # Markdown report
 devkit scan --format sarif             # SARIF, for code-scanning platforms
-devkit scan --category dead-code       # only one category
+devkit scan --category dead-code       # only one category (dead-code, security, type-safety, ...)
 devkit scan --severity high            # only one severity level
 ```
 
@@ -262,25 +269,29 @@ Architecture-layer rules (`ARCH001`) are opt-in and only produce findings once c
 
 ## Scoring model
 
-Each finding is weighted by `severity × confidence` ([`src/scoring.ts`](src/scoring.ts)) and normalized against source LOC (in 500-line chunks), so a single low-confidence finding in a large repository barely moves the score. Category scores are combined into the overall score using fixed weights:
+Each finding is weighted by `severity × confidence` ([`src/scoring.ts`](src/scoring.ts)); findings in test files count at half weight. Quality categories are normalized against lines of code (in 500-line chunks), so the same number of findings costs less in a larger repository. Security is normalized only by the square root of size, capped at 3×, because one leaked key is just as serious in a large repository. Category scores are combined into the overall score using these weights:
 
 | Category | Weight |
 | --- | ---: |
-| Dead code | 20% |
+| Dead code | 15% |
 | Complexity | 15% |
+| Security | 15% |
 | Dependencies | 10% |
 | Duplication | 10% |
-| Redundant logic | 10% |
 | Error handling | 10% |
 | Type safety | 10% |
-| Architecture | 10% |
+| Redundant logic | 5% |
+| Architecture | 5% |
 | Hygiene | 5% |
 
-Security findings are scored and reported separately rather than folded into the overall score.
+- **Security cap:** a HIGH/CRITICAL security finding with HIGH or CERTAIN confidence outside test files caps the overall score at 6.9, however clean the rest of the code is.
+- **Architecture** is only scored when `architecture.layers` is configured; otherwise it is shown as `n/a` and the other weights are rescaled.
+- **Filters** (`--category`, `--severity`) only narrow the findings that are displayed. Scores and `--min-score` always use the whole repository.
+- A scan that analyzes zero JS/TS files prints a warning and always fails `--min-score`.
 
 ## Output formats
 
-- **Terminal** (default) — colored, with a score bar, per-category breakdown, and code frames for the top finding per category.
+- **Terminal** (default) — live progress on stderr, then a score with letter grade, scan coverage (files found, analyzed, secret-scanned, skipped, duration), per-category score bars, severity distribution, file hotspots, and code frames for the worst finding per category. Respects `NO_COLOR`/`FORCE_COLOR`; set `DEVKIT_ASCII=1` for plain-ASCII glyphs.
 - **JSON** (`--json` / `--format json`) — the full `ScanSummary` object: score, category scores, every finding, repository metrics.
 - **Markdown** (`--format markdown` / `devkit report`) — category table, top deductions, and a flat findings list, suitable for pasting into a PR description.
 - **SARIF** (`--format sarif`) — standard SARIF 2.1.0, for GitHub code scanning and similar tools.
@@ -288,10 +299,14 @@ Security findings are scored and reported separately rather than folded into the
 ## Current limitations
 
 - Framework entry-point detection is limited to package metadata, tests, and a basic Next.js convention check. Other React setups such as Vite may need entry files specified through package metadata or imports.
-- `.gitignore` and `.devkitignore` negation patterns (`!pattern`) are skipped; full Git ignore semantics are not implemented.
+- Outside a git repository, `.gitignore` is approximated (negation patterns `!pattern` are skipped). `.devkitignore` never supports negation.
+- Non-JS/TS files (Python, Go, YAML, ...) only get the secret scan, not code-quality rules. Script blocks in `.vue`/`.svelte` files are not parsed.
 - `devkit fix` only previews findings marked as safe. It does not modify files.
 - `devkit baseline compare` compares the overall score only; it does not report newly added or resolved findings.
-- DevKit has no rule presets, React-specific or test-quality rules, configuration analysis, incremental cache, or monorepo-aware scoring.
+- The secret scan is scoped by `scan.exclude`, not `scan.include`: a secret outside your configured `include` globs is still reported, by design (security blind spots are worse than noise), but this is easy to miss if you expect `include` to fully sandbox a scan.
+- DEP001/DEP002 are workspace-aware (each `package.json` in the repo is checked against its own files, with the root tolerated as a hoisting source) but do not read `pnpm-workspace.yaml` or Lerna config — only the `package.json` layout itself.
+- The CLI-entry heuristic that discounts `console.*` findings looks for an import of a known argv-parsing library (commander, yargs, cac, meow, sade, clipanion). A hand-rolled CLI without one of these still gets flagged at full confidence.
+- DevKit has no rule presets, React-specific or test-quality rules, configuration analysis, or incremental cache.
 
 ## CI/CD integration
 
@@ -310,3 +325,11 @@ npm run dev        # tsx src/cli.ts (no build step)
 ```
 
 Tests live in [`src/__tests__/`](src/__tests__), one file per rule category plus an end-to-end scan test (`e2e.test.ts`) and a scoring test. Each rule test typically builds a small in-memory `RuleContext` (see [`testUtils.ts`](src/__tests__/testUtils.ts)) and asserts on the findings a rule produces for known-good and known-bad snippets.
+
+## Contributing
+
+Contributions are welcome — new rules, bug fixes, false-positive reports, and documentation improvements. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development setup and the process for adding a rule. This project follows the [Code of Conduct](CODE_OF_CONDUCT.md). To report a security issue, see [SECURITY.md](SECURITY.md) rather than opening a public issue.
+
+## License
+
+[MIT](LICENSE) © Karan Chourasia

package/dist/cli.js

@@ -11,18 +11,26 @@ const config_1 = require("./config");
 const rules_1 = require("./rules");
 const reporters_1 = require("./reporters");
 const scanner_1 = require("./scanner");
-const scoring_1 = require("./scoring");
 const terminal_1 = require("./terminal");
 const cliLogic_1 = require("./cliLogic");
-async function runWithSpinner(text, task) {
-    const spinner = new terminal_1.Spinner(text);
-    spinner.start();
-    await (0, terminal_1.waitForNextTick)();
+function resolveTarget(target) {
+    const root = node_path_1.default.resolve(target ?? process.cwd());
+    if (!node_fs_1.default.existsSync(root) || !node_fs_1.default.statSync(root).isDirectory()) {
+        throw new Error(`Not a directory: ${root}`);
+    }
+    return root;
+}
+function scanWithProgress(root) {
+    const progress = new terminal_1.ProgressRenderer();
     try {
-        return task();
+        const summary = (0, scanner_1.scanRepository)(root, (update) => progress.update(update));
+        const coverage = summary.coverage;
+        progress.finish(coverage ? `Scanned ${coverage.analyzedFiles} source files + ${coverage.textFilesScanned} other files` : 'Scan complete');
+        return summary;
     }
-    finally {
-        spinner.stop();
+    catch (error) {
+        progress.fail();
+        throw error;
     }
 }
 const program = new commander_1.Command();
@@ -34,17 +42,26 @@ program
     const configPath = (0, config_1.writeConfig)(process.cwd());
     console.log(`Created config at ${configPath}`);
 });
-async function runScan(options) {
-    const summary = await runWithSpinner('Scanning repository...', () => (0, scanner_1.scanRepository)(process.cwd()));
-    const filteredFindings = (0, cliLogic_1.filterFindings)(summary.findings, options);
-    const filteredSummary = filteredFindings.length === summary.findings.length
-        ? summary
-        : {
-            ...summary,
-            findings: filteredFindings,
-            ...(0, scoring_1.computeScores)(filteredFindings, summary.metrics.sourceLOC)
-        };
+const OUTPUT_FORMATS = ['terminal', 'json', 'markdown', 'sarif'];
+function runScan(target, options) {
+    const gateError = (0, cliLogic_1.validateGates)(options);
+    if (gateError) {
+        console.error(gateError);
+        return true;
+    }
     const outputType = options.json ? 'json' : (options.format ?? 'terminal');
+    if (!OUTPUT_FORMATS.includes(outputType)) {
+        console.error(`Unknown format "${outputType}". Use one of: ${OUTPUT_FORMATS.join(', ')}`);
+        return true;
+    }
+    const summary = scanWithProgress(resolveTarget(target));
+    // Filters narrow the findings that are displayed; scores always describe the whole repository,
+    // so `--category security --min-score 8` still gates on the real overall score.
+    const filteredFindings = (0, cliLogic_1.filterFindings)(summary.findings, options);
+    const filteredSummary = { ...summary, findings: filteredFindings };
+    if ((options.category || options.severity) && filteredFindings.length === 0 && summary.findings.length > 0 && outputType === 'terminal') {
+        console.error(terminal_1.color.yellow(`No findings match the filter. Categories: ${[...new Set(summary.findings.map((finding) => finding.category))].join(', ')}`));
+    }
     const output = outputType === 'json'
         ? (0, reporters_1.formatJson)(filteredSummary)
         : outputType === 'markdown'
@@ -53,45 +70,50 @@ async function runScan(options) {
                 ? (0, reporters_1.formatSarif)(filteredSummary)
                 : (0, reporters_1.formatTerminal)(filteredSummary);
     console.log(output);
-    if (options.failOn && !(0, cliLogic_1.isKnownSeverity)(options.failOn))
-        console.error(`Unknown severity: ${options.failOn}`);
-    return (0, cliLogic_1.determineExitFailure)(filteredSummary, options);
+    return (0, cliLogic_1.determineExitFailure)(summary, { minScore: options.minScore }) || (0, cliLogic_1.determineExitFailure)(filteredSummary, { failOn: options.failOn });
 }
 program
-    .command('scan')
-    .description('Scan the current repository for code-quality issues')
+    .command('scan [path]')
+    .description('Scan a repository (default: current directory) for code-quality issues')
     .option('--json', 'Output JSON instead of terminal text')
     .option('--format <type>', 'Output format: terminal, json, markdown, sarif')
-    .option('--category <name>', 'Filter by category')
-    .option('--severity <level>', 'Filter by severity')
-    .option('--min-score <score>', 'Fail with exit code 1 when score falls below this threshold')
-    .option('--fail-on <severity>', 'Fail with exit code 1 when any finding at or above this severity exists')
-    .action(async (options) => {
-    if (await runScan(options)) {
+    .option('--category <name>', 'Show only one category (e.g. security, dead-code, complexity)')
+    .option('--severity <level>', 'Show only one severity (critical, high, medium, low, info)')
+    .option('--min-score <score>', 'Fail with exit code 1 when the overall score falls below this threshold')
+    .option('--fail-on <severity>', 'Fail with exit code 1 when any shown finding is at or above this severity')
+    .action((target, options) => {
+    if (runScan(target, options)) {
         process.exitCode = 1;
     }
 });
 program
-    .command('report')
-    .description('Generate a detailed Markdown report of the current repository')
-    .action(async () => {
-    const summary = await runWithSpinner('Scanning repository...', () => (0, scanner_1.scanRepository)(process.cwd()));
-    console.log((0, reporters_1.formatMarkdown)(summary));
+    .command('report [path]')
+    .description('Generate a detailed Markdown report of a repository')
+    .action((target) => {
+    console.log((0, reporters_1.formatMarkdown)(scanWithProgress(resolveTarget(target))));
 });
 program
-    .command('metrics')
-    .description('Print repository metrics for the current project')
-    .action(async () => {
-    const summary = await runWithSpinner('Scanning repository...', () => (0, scanner_1.scanRepository)(process.cwd()));
-    console.log((0, reporters_1.formatMetrics)(summary));
+    .command('metrics [path]')
+    .description('Print repository metrics')
+    .action((target) => {
+    console.log((0, reporters_1.formatMetrics)(scanWithProgress(resolveTarget(target))));
 });
 program
     .command('rules')
     .description('List the available built-in rules')
     .action(() => {
-    for (const rule of (0, rules_1.listRules)()) {
-        console.log(`${rule.id} - ${rule.title} (${rule.category})`);
+    const rules = (0, rules_1.listRules)();
+    const idWidth = Math.max(...rules.map((rule) => rule.id.length)) + 2;
+    const titleWidth = Math.max(...rules.map((rule) => rule.title.length)) + 2;
+    let category = '';
+    for (const rule of [...rules].sort((a, b) => a.category.localeCompare(b.category) || a.id.localeCompare(b.id))) {
+        if (rule.category !== category) {
+            category = rule.category;
+            console.log(`\n${terminal_1.color.bold(category)}`);
+        }
+        console.log(`  ${terminal_1.color.cyan((0, terminal_1.pad)(rule.id, idWidth))}${(0, terminal_1.pad)(rule.title, titleWidth)}${(0, terminal_1.severityColor)(rule.severity, rule.severity.toLowerCase())}`);
     }
+    console.log(terminal_1.color.dim(`\n${rules.length} rules · devkit explain <RULE_ID> for details`));
 });
 program
     .command('explain <ruleId>')
@@ -116,17 +138,17 @@ program
     }
 });
 program
-    .command('baseline <action>')
+    .command('baseline <action> [path]')
     .description('Create or compare a baseline score stored under .devkit')
-    .action(async (action) => {
-    const root = process.cwd();
+    .action((action, target) => {
+    const root = resolveTarget(target);
     const dir = node_path_1.default.join(root, '.devkit');
     const baselineFile = node_path_1.default.join(dir, 'baseline.json');
     if (!node_fs_1.default.existsSync(dir)) {
         node_fs_1.default.mkdirSync(dir, { recursive: true });
     }
     if (action === 'create') {
-        const summary = await runWithSpinner('Scanning repository...', () => (0, scanner_1.scanRepository)(root));
+        const summary = scanWithProgress(root);
         node_fs_1.default.writeFileSync(baselineFile, JSON.stringify({ score: summary.score }, null, 2));
         console.log(`Created baseline at ${baselineFile} with score ${summary.score.toFixed(1)}`);
         return;
@@ -138,7 +160,7 @@ program
             return;
         }
         const previousBaseline = JSON.parse(node_fs_1.default.readFileSync(baselineFile, 'utf8'));
-        const current = await runWithSpinner('Scanning repository...', () => (0, scanner_1.scanRepository)(root));
+        const current = scanWithProgress(root);
         const previousScore = Number(previousBaseline.score ?? current.score);
         console.log((0, reporters_1.formatBaselineCompare)(previousScore, current.score));
         return;
@@ -147,10 +169,10 @@ program
     process.exitCode = 1;
 });
 program
-    .command('fix')
+    .command('fix [path]')
     .description('Preview findings marked as safe to fix')
-    .action(async () => {
-    const summary = await runWithSpinner('Scanning repository...', () => (0, scanner_1.scanRepository)(process.cwd()));
+    .action((target) => {
+    const summary = scanWithProgress(resolveTarget(target));
     const safeFixes = summary.findings.filter((finding) => finding.fixAvailable);
     console.log('Safe fix preview');
     if (safeFixes.length === 0) {

package/dist/cliLogic.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.filterFindings = filterFindings;
 exports.isKnownSeverity = isKnownSeverity;
+exports.validateGates = validateGates;
 exports.determineExitFailure = determineExitFailure;
 const SEVERITY_RANK = {
     INFO: 0,
@@ -10,9 +11,25 @@ const SEVERITY_RANK = {
     HIGH: 3,
     CRITICAL: 4
 };
+/** `dead-code`, `Dead Code`, `dead_code` and `deadCode` all name the same category. */
+function normalizeCategory(value) {
+    return value.toLowerCase().replace(/[^a-z]/g, '');
+}
+const CATEGORY_ALIASES = {
+    typesafety: 'typescript',
+    types: 'typescript',
+    redundancy: 'redundantlogic',
+    redundant: 'redundantlogic',
+    deps: 'dependencies',
+    dead: 'deadcode',
+    errors: 'errorhandling',
+    arch: 'architecture'
+};
 function filterFindings(findings, filters) {
+    const category = filters.category ? normalizeCategory(filters.category) : undefined;
+    const wantedCategory = category ? (CATEGORY_ALIASES[category] ?? category) : undefined;
     return findings.filter((finding) => {
-        if (filters.category && finding.category.toLowerCase() !== filters.category.toLowerCase())
+        if (wantedCategory && normalizeCategory(finding.category) !== wantedCategory)
             return false;
         if (filters.severity && finding.severity.toLowerCase() !== filters.severity.toLowerCase())
             return false;
@@ -22,13 +39,31 @@ function filterFindings(findings, filters) {
 function isKnownSeverity(value) {
     return Object.prototype.hasOwnProperty.call(SEVERITY_RANK, value.toUpperCase());
 }
+/** Returns an error message for invalid gate options, or null when they are usable. */
+function validateGates(gates) {
+    if (gates.minScore !== undefined) {
+        const value = Number(gates.minScore);
+        if (gates.minScore.trim() === '' || !Number.isFinite(value) || value < 0 || value > 10) {
+            return `--min-score must be a number between 0 and 10 (got "${gates.minScore}")`;
+        }
+    }
+    if (gates.failOn !== undefined && !isKnownSeverity(gates.failOn)) {
+        return `--fail-on must be one of ${Object.keys(SEVERITY_RANK).join(', ').toLowerCase()} (got "${gates.failOn}")`;
+    }
+    return null;
+}
 function determineExitFailure(summary, gates) {
-    if (gates.minScore !== undefined && summary.score < Number(gates.minScore))
+    if (validateGates(gates))
         return true;
+    if (gates.minScore !== undefined) {
+        // A score computed from zero analyzed files is meaningless; never let it pass a quality gate.
+        if (summary.coverage && summary.coverage.analyzedFiles === 0)
+            return true;
+        if (summary.score < Number(gates.minScore))
+            return true;
+    }
     if (gates.failOn !== undefined) {
         const threshold = gates.failOn.toUpperCase();
-        if (!isKnownSeverity(gates.failOn))
-            return true;
         if (summary.findings.some((finding) => SEVERITY_RANK[finding.severity] >= SEVERITY_RANK[threshold]))
             return true;
     }