lostconf

A meta-linter that validates and detects stale references in configuration files across languages and tools.

The Problem

Linter configs accumulate exclusions over time. Files get deleted, patterns become stale, but configs are never cleaned up. This leads to:

• Confusing config files full of dead references that nobody understands
• Security risks when exclusions outlive the code they were meant to exclude
• Maintenance burden when trying to understand what's actually being ignored
• False confidence in your linting when patterns no longer match anything

The Solution

lostconf scans your config files, extracts path/glob/regex patterns, validates them against your codebase, and reports dead references.

$ npx lostconf
.eslintignore:3    src/legacy/*.js       no matches
.rubocop.yml:47    spec/old_helper.rb    file not found
pyproject.toml:12  test_.*_old\.py       no matches

Found 3 stale patterns in 3 files

Installation

Run directly with npx (no install required):

npx lostconf

Or install globally:

npm install -g lostconf

Or add to your project:

npm install --save-dev lostconf

Quick Start

# Scan current directory (shows medium+ severity by default)
npx lostconf

# Show all findings including low severity (common patterns like node_modules)
npx lostconf --show-all

# Only show high severity issues
npx lostconf --min-severity=high

# Scan specific paths
npx lostconf ./src ./lib

# Fail CI if stale patterns found
npx lostconf --fail-on-stale

# JSON output for automation
npx lostconf --format json

# Only check TypeScript configs
npx lostconf --include "**/tsconfig.json"

CLI Options

Filtering Options

• --skip-ignore-files - Skip all ignore files (.gitignore, .prettierignore, .eslintignore, .dockerignore, .stylelintignore, etc.). Reduces noise by 70-80% since these files contain many intentionally missing patterns.
• --exclude-parsers <names...> - Skip specific parsers by name (e.g., --exclude-parsers gitignore prettierignore)
• --include <glob...> - Only check config files matching these glob patterns (e.g., --include "**/tsconfig.json")
• --exclude <glob...> - Skip config files matching these glob patterns (e.g., --exclude "**/test/**")

Output Options

• -f, --format <fmt> - Output format: text (default), json, or sarif
• -o, --output <file> - Write results to file instead of stdout
• --fail-on-stale - Exit with code 1 if stale patterns are found (useful for CI)
• -q, --quiet - Suppress non-error output
• -v, --verbose - Show detailed debug information

Progress

• --no-progress - Disable the progress indicator (enabled by default in text mode)

Examples

# Focus on actionable issues (skip ignore files)
npx lostconf --skip-ignore-files

# Check only TypeScript configs in packages directory
npx lostconf packages/ --include "**/tsconfig.json"

# CI mode: fail build if stale patterns found, output JSON
npx lostconf --fail-on-stale --format json --skip-ignore-files

# Scan large monorepo with progress disabled
npx lostconf --no-progress

# Check everything except test directories
npx lostconf --exclude "**/test/**" --exclude "**/tests/**"

Supported Config Files

lostconf supports 67+ configuration files from popular tools across 15+ languages:

Language/Category	Tool	Config File(s)	What We Check
JavaScript/TypeScript	ESLint	.eslintignore	File paths and glob patterns in ignore list
	ESLint Flat Config	eslint.config.json	Patterns in ignores and files arrays (JSON only)
	Prettier	.prettierignore	File paths and glob patterns in ignore list
	TypeScript	tsconfig.json	Files in exclude, include arrays
	Jest	jest.config.json	Test paths, coverage paths, module paths
	Stylelint	.stylelintignore, .stylelintrc.json	File paths and glob patterns, ignore patterns in config
	Biome	biome.json, biome.jsonc	Patterns in files.ignore, linter.ignore, formatter.ignore
	Deno	deno.json, deno.jsonc	Global exclude, lint.exclude/include, fmt.exclude/include, test.exclude/include
	Oxlint	.oxlintrc.json, oxlint.config.json	Patterns in ignorePatterns array
	commitlint	.commitlintrc, .commitlintrc.json	Commit message patterns in ignores, file paths in extends
	lint-staged	.lintstagedrc, .lintstagedrc.json	Object keys are glob patterns matching staged files
Python	pytest, coverage, mypy, ruff, black, isort	pyproject.toml	Test paths, source paths, exclude patterns, omit patterns
	Flake8	.flake8, setup.cfg	Exclude patterns, extend-exclude, filename patterns, per-file-ignores
	Pylint	.pylintrc, pylintrc	Ignore paths, ignore patterns in [MASTER]/[MAIN] section
	Bandit	.bandit	Exclude directories, exclude files, test paths
	Pyright	pyrightconfig.json	include, exclude, ignore, extraPaths patterns
SQL	SQLFluff	.sqlfluff, setup.cfg	Exclude patterns, ignore patterns, template paths
Ruby	RuboCop	.rubocop.yml	Exclude patterns, Include patterns in AllCops
	Brakeman	config/brakeman.yml, .brakeman.yml	Patterns in skip-files and only-files
	Reek	.reek.yml, .reek, config.reek	Directory paths in exclude_paths
	bundler-audit	.bundler-audit.yml	Advisory IDs in ignore (CVE, OSVDB, GHSA)
	YARD-Lint	.yard-lint.yml	File patterns in global and per-validator Exclude
Go	golangci-lint	.golangci.yml	Skip-dirs, skip-files, exclude patterns
Rust	rustfmt	rustfmt.toml	Ignore patterns
	Clippy	clippy.toml	Excluded files
Java	Checkstyle	checkstyle.xml	SuppressionFilter file attributes
	PMD	pmd.xml	Exclude patterns in rulesets
	SpotBugs	spotbugs.xml	Match/Class elements
Kotlin	detekt	detekt.yml	Excludes patterns in config
PHP	PHP_CodeSniffer	phpcs.xml	Exclude-pattern elements
	PHPStan	phpstan.neon	Excludes_analyse, ignoreErrors paths
Swift	SwiftLint	.swiftlint.yml	Excluded paths, included paths
C/C++	clang-tidy	.clang-tidy	CheckOptions paths
	clang-format	.clang-format	File patterns
Scala	Scalafmt	.scalafmt.conf	Project.excludeFilters
	Scalafix	.scalafix.conf	Excludes patterns
Elixir	Credo	.credo.exs	Files.excluded paths
.NET	EditorConfig	.editorconfig	File globs and patterns
	MSBuild	Directory.Build.props	Include/Exclude item patterns
Shell	ShellCheck	.shellcheckrc	Source-path directives
YAML	yamllint	.yamllint, .yamllint.yml	Ignore patterns, ignore-from-file paths
Terraform	TFLint	.tflint.hcl	Source paths, module directories, exclude patterns
Security	Semgrep	.semgrep.yml, .semgrep.yaml, .semgrepignore	paths.exclude, paths.include in rules, ignore patterns
	Gitleaks	.gitleaks.toml	allowlist.paths, allowlist.regexes, rule-specific allowlists
Docker	Hadolint	.hadolint.yaml, .hadolint.yml	ignored patterns, trustedRegistries (non-URL paths)
DevOps	ansible-lint	.ansible-lint, .ansible-lint.yaml	Patterns in exclude_paths list
Protocol Buffers	buf	buf.yaml, buf.work.yaml	Patterns in lint.ignore, breaking.ignore, workspace directories
Git Hooks	lefthook	lefthook.yml, .lefthook.yml	Patterns in files, glob, exclude, skip fields
	pre-commit	.pre-commit-config.yaml	Regex patterns in top-level and hook-level files and exclude
General	Git	.gitignore	All file paths and patterns
	Docker	.dockerignore	All file paths and patterns
	markdownlint	.markdownlintignore	All file paths and patterns
	remark	.remarkignore	All file paths and patterns
	lychee	.lycheeignore	All file paths and patterns
	secretlint	.secretlintignore	All file paths and patterns
	VS Code	.vscodeignore	All file paths and patterns
	git-leaks	.ignoresecrets	All file paths and patterns
Documentation	alex	.alexignore, .alexrc, .alexrc.json	Ignore patterns and allowed terms

What Does lostconf Validate?

lostconf extracts and validates three types of patterns from configuration files:

Pattern Types

• File Paths: Direct references to files or directories (e.g., src/legacy/old.js)
• Glob Patterns: Wildcards and patterns (e.g., **/*.test.js, *.py)
• Regex Patterns: Regular expressions in certain config contexts (e.g., Python test file patterns)

Validation Strategy by Tool

Ignore Files (.gitignore, .eslintignore, .prettierignore, etc.)

• Validates that each pattern matches at least one file in your codebase
• Warns about patterns that no longer match anything (stale patterns)

Configuration Files with Path References (tsconfig.json, pyproject.toml, etc.)

• Checks exclude, include, ignore, and similar fields
• Validates source paths, test paths, and coverage paths
• Ensures referenced files and directories exist

Linter-Specific Configs

• ESLint/Prettier/Stylelint: Ignore patterns
• TypeScript: Files in exclude/include arrays
• Jest: Test paths, coverage directories, module path mappings
• Biome: Ignore/include patterns across files, linter, and formatter sections
• Python Tools (pytest, mypy, ruff, black, isort, flake8, pylint, bandit): Source paths, test paths, exclude patterns
• RuboCop: Exclude/Include patterns in AllCops
• Go (golangci-lint): Skip directories and files
• Rust (rustfmt, clippy): Ignored file patterns
• Java (checkstyle, pmd, spotbugs): Suppression files and exclude patterns
• Kotlin (detekt): Exclude patterns
• PHP (phpcs, phpstan): Exclude patterns and ignored paths
• Swift (swiftlint): Excluded and included file paths
• C/C++ (clang-tidy, clang-format): File patterns and paths
• Scala (scalafmt, scalafix): Exclude filters
• Elixir (credo): Excluded file paths
• .NET (editorconfig, MSBuild): File globs and item patterns
• ShellCheck: Source path references
• yamllint: Ignore patterns and ignore-from-file references
• Terraform (tflint): Module sources and exclude patterns

What Causes a Stale Pattern?

1. File Not Found - A specific file or directory path doesn't exist
2. No Matches - A glob or regex pattern doesn't match any files in the codebase
3. Invalid Pattern - The pattern syntax is malformed

CLI Reference

lostconf [options] [paths...]

Arguments:
  paths                Paths to scan (default: current directory)

Options:
  -V, --version        Show version number
  -f, --format <fmt>   Output format: text, json, sarif (default: text)
  -o, --output <file>  Write to file instead of stdout
  --include <glob...>  Only check matching config files
  --exclude <glob...>  Skip matching config files
  --fail-on-stale      Exit code 1 if stale patterns found
  -q, --quiet          Suppress non-error output
  -v, --verbose        Show debug info
  -h, --help           Show help

Output Formats

Text (Default)

Human-readable output with colors:

.eslintignore:3    src/legacy/*.js       no matches
.rubocop.yml:47    spec/old_helper.rb    file not found

Found 2 stale patterns in 2 files

JSON

Machine-readable format for automation:

npx lostconf --format json

{
  "findings": [
    {
      "file": ".eslintignore",
      "line": 3,
      "pattern": "src/legacy/*.js",
      "type": "glob",
      "reason": "no_matches",
      "parser": "eslintignore"
    }
  ],
  "summary": { "total": 1, "files": 1 }
}

SARIF

SARIF format for IDE integration and GitHub Code Scanning:

npx lostconf --format sarif --output results.sarif

CI Integration

GitHub Actions

Basic usage:

name: Lint
on: [push, pull_request]

jobs:
  lostconf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npx lostconf --fail-on-stale

GitHub Code Scanning with SARIF

name: Code Scanning
on: [push, pull_request]

jobs:
  lostconf:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Run lostconf
        run: npx lostconf --format sarif --output results.sarif
        continue-on-error: true

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: lostconf
        name: Check for stale config patterns
        entry: npx lostconf --fail-on-stale
        language: system
        pass_filenames: false

Exit Codes

Code	Description
0	Success (no stale patterns, or --fail-on-stale not set)
1	Stale patterns found (when --fail-on-stale is set)
2	Error (invalid arguments, file read errors, etc.)

Programmatic API

Use lostconf as a library in your Node.js scripts:

import { createEngine, getBuiltinParsers } from 'lostconf';

async function checkConfigs() {
  const parsers = getBuiltinParsers();
  const engine = createEngine(parsers, {
    paths: ['.'],
    verbose: false
  });

  const result = await engine.run();

  console.log(`Found ${result.summary.total} stale patterns`);

  for (const finding of result.findings) {
    console.log(`${finding.file}:${finding.line} - ${finding.pattern}`);
  }
}

checkConfigs();

Creating Custom Parsers

import { createEngine, Parser, Pattern, PatternType } from 'lostconf';

const myParser: Parser = {
  name: 'my-tool',
  filePatterns: ['.mytoolrc', '**/.mytoolrc'],
  parse(filename: string, content: string): Pattern[] {
    const patterns: Pattern[] = [];
    // Parse your config format and extract patterns
    // ...
    return patterns;
  }
};

const engine = createEngine([myParser], { paths: ['.'] });
const result = await engine.run();

Pattern Types

lostconf understands three types of patterns:

Type	Description	Example
path	Exact file or directory path	src/legacy/old.js
glob	Glob pattern with wildcards	src/**/*.test.js
regex	Regular expression	test_.*_old\.py

Stale Reasons

Reason	Description
file_not_found	The referenced file or directory doesn't exist
no_matches	The glob/regex pattern doesn't match any files
invalid_pattern	The pattern syntax is invalid

Contributing

Contributions are welcome! Here's how to get started:

# Clone the repository
git clone https://github.com/mensfeld/lostconf.git
cd lostconf

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run linter
npm run lint

# Check formatting
npm run format:check

# Run lostconf on itself
npm run selfcheck

Adding a New Parser

1. Create a new file in src/parsers/
2. Implement the Parser interface
3. Export the parser from src/parsers/index.ts
4. Add tests in tests/parsers/

License

MIT