code-scent

code-scent is a Node CLI dev-tool for finding code smells in JavaScript and TypeScript. It feels like a test runner: point it at source paths, get file-and-line diagnostics, use the exit code in CI, or keep it running in watch mode.

The smell names and design intent follow Martin Fowler’s Refactoring: Improving the Design of Existing Code, Second Edition. Descriptions in this project are original paraphrases; the book remains the authoritative explanation. Fowler also maintains the official Refactoring catalog.

Code smells are prompts for investigation, not proof that code is wrong. Static rules are necessarily heuristic, so thresholds are configurable and individual rules can be disabled.

Requires Node 20 or newer.

npm install --save-dev code-scent

npx code-scent src

With npm 7+, the locally installed binary can also be run through an npm script:

{
  "scripts": {
    "lint:smells": "code-scent src --fail-on error"
  }
}

npm run lint:smells

While developing this repository, the same command can be run directly:

node ./bin/code-scent.js src

Common forms:

code-scent                         # checks ./src
code-scent src packages/core      # checks multiple source trees
code-scent src --watch             # reruns after edits
code-scent . --format json         # machine-readable diagnostics
code-scent src --fail-on error     # warnings do not fail the process
code-scent src --rule loops=off    # one-run rule override
code-scent --list-smells           # all 24 catalog entries

Supported extensions are .js, .cjs, .mjs, .jsx, .ts, .cts, .mts, and .tsx. Common generated and dependency directories are skipped.

The CLI automatically loads the first configuration file it finds in the working directory:

• code-scent.config.js
• code-scent.config.mjs
• code-scent.config.cjs
• code-scent.config.json

For example:

import { defineConfig } from 'code-scent/config';

export default defineConfig({
  failOn: 'warning', // warning | error | never
  format: 'pretty',  // pretty | json
  exclude: ['node_modules', 'dist', 'coverage', '.git', 'generated'],
  rules: {
    'long-function': { maxLines: 60, maxStatements: 35 },
    'long-parameter-list': { maxParameters: 5 },
    'mysterious-name': { enabled: false }
  }
});

See code-scent.config.example.js and src/config.js for every default threshold.

The complete second-edition catalog is represented. The CLI separates smells that have useful static evidence from smells that need history or human design judgment.

The conservative gaps are intentional. For example, import fan-out alone does not prove Shotgun Surgery, and an unused abstraction alone does not prove Speculative Generality.

• 0: no finding at or above the configured failure threshold
• 1: findings crossed failOn or --max-warnings
• 2: the CLI itself could not run, such as an invalid option or missing path

Syntax errors are reported as error findings so one bad file does not prevent other files from being analyzed.

import { analyze, defaultConfig } from 'code-scent';

const result = await analyze(['src/index.ts'], {
  cwd: process.cwd(),
  config: defaultConfig
});

for (const finding of result.findings) {
  console.log(finding.ruleId, finding.file, finding.line, finding.message);
}

npm install
npm test
npm run check

The tests use Node’s built-in test runner. The only runtime dependency is Babel’s parser.

After signing in to npm and choosing a new version, publish from a clean working tree:

npm test
npm run check
npm version patch
npm publish

npm publish is configured for public access and runs the same test and check commands through prepublishOnly. Verify the exact release contents first with npm pack --dry-run.

This project is not affiliated with or endorsed by Martin Fowler or Pearson.