litscan

A small CLI tool that scans a codebase for string and numeric literals, helping you quickly spot hard-coded values in source files.

Prerequisites

• Python 3.14+

Installation

pip install litscan

Usage

After installation, litscan is available as a console script:

litscan <path> [options]

What is detected

The scanner uses tree-sitter to parse each file and extracts literal nodes per language:

Files with extensions not in the table above are skipped with a warning.

Results are grouped by unique literal value and sorted by occurrence count (highest first).

Arguments

Options

Examples

Scan all files in the current directory and produce a JSON report:

litscan .

Scan only Python and JavaScript files in src/:

litscan src --ext py,js

Generate both JSON and HTML reports in a custom directory:

litscan . --format all --output-dir my-reports

Scan a Java source tree with a custom output name:

litscan src/main/java --ext java --format all --output-dir reports

Scan only literals inside functions and methods:

litscan src --functions-only

Only report string literals that occur at least 3 times:

litscan src --mode string --min 3

Restrict the report to specific target literal values:

litscan src --literals "TODO;FIXME"

Configuration

Ignore patterns

The lit_ignore file (seeded into LITSCAN_CONFIG_DIR on first run) contains one regex pattern per line. Any literal whose value matches a pattern is excluded from scan results. Edit the file to suppress noise such as common stop-words or numeric constants you do not care about.

Ignored files and directories

The .litscanignore file (also seeded into LITSCAN_CONFIG_DIR on first run) uses gitignore syntax to exclude entire files or directories from being scanned in the first place — matching directories are pruned during traversal, so their contents are never read. It ships with sensible defaults (.git/, node_modules/, dist/, build/, __pycache__/, .venv/); edit the file to add project-specific paths to skip.

Report metadata

Every JSON/HTML report records the run's inputs alongside the findings: the resolved --path entries (paths-scanned), the --min threshold (min-count), the --mode used, and any --literals targets applied.

Development

Prerequisites

• Poetry 2.2+

Installation

poetry install

Architecture

flowchart TD
    CLI["cli.py\n(entry point)"] --> logenrich["setup_logger()\nlogenrich"]
    CLI --> discover["discover_files()"]
    discover --> pathignore[".litscanignore\n(braincraft.IgnoreFile)"]
    discover --> concurrent["ThreadPoolExecutor\n(parallel scan)"]
    concurrent --> scan["scan_file()\nscanner.py"]
    scan --> parser["parser.py\n(tree-sitter)"]
    parser --> ts["Language-specific\ngrammar packages"]
    scan --> litignore["lit_ignore\n(exclude patterns)"]
    scan --> store["SessionStore\nstore.py (SQLite)"]
    store --> report["write_outputs()\nreporter.py"]
    report --> JSON["JSON report"]
    report --> HTML["HTML report"]

Test with coverage

poetry run pytest --cov=litscan tests --cov-report html

Format and lint

poetry run black litscan; poetry run pylint litscan

Quality gates

• Coverage ≥ 90%
• Pylint score 10/10

Example

Scan the test fixtures and produce both JSON and HTML reports:

poetry run litscan tests\fixtures --format all

Publishing to PyPI

Prerequisites

• A PyPI account with an API token.

Configure the token

poetry config pypi-token.pypi <your-token>

Build and publish

poetry publish --build

This builds the source distribution and wheel, then uploads them to PyPI in one step.

Note: PyPI releases are immutable. Once a version is published, it cannot be overwritten.
To fix a mistake, yank the release via the PyPI web UI and publish a new version.

Changelog

License

MIT

Author

Ron Webb <ron@ronella.xyz>