CodexDoctor

CodexDoctor is a lightweight, dependency-free command-line tool and Python API for static diagnostics of Python projects. It checks source syntax, likely missing imports, selected risky APIs, and a few project-structure conventions.

CodexDoctor is an early static-analysis tool, not a replacement for a test suite, type checker, linter, dependency scanner, or professional security audit. Its security and import checks are heuristic and can produce false positives or miss issues.

Features

• Scans Python source without importing or executing project code.
• Reports syntax errors with file and line information.
• Checks likely missing imports against the active interpreter and a conservative local-module index, including common src/ layouts and relative imports.
• Recognizes imports guarded by try/except ImportError as optional.
• Flags selected risky patterns: eval, exec, unsafe pickle/dill deserialization, potentially unsafe yaml.load, shell-enabled subprocess calls, os.system/os.popen, and tempfile.mktemp.
• Reports missing README, tests, or packaging metadata as informational findings.
• Supports readable terminal output and JSON output for CI pipelines.
• Skips common generated and environment directories and symbolic links by default; supports explicit exclusions, hidden-file inclusion, and a maximum source-file size.
• Does not modify scanned source files. The CLI writes a report only when --output is explicitly supplied.

Requirements

• Python 3.10 or newer.
• No runtime third-party dependencies.

Install from source

python -m pip install .

For development:

python -m pip install -e ".[dev]"
python -m pytest

Command-line usage

Scan the current directory:

codexdoctor scan .

Scan another project:

codexdoctor scan path/to/project

Get JSON output:

codexdoctor scan . --format json

Save a report (the destination file is created or replaced):

codexdoctor scan . --format json --output codexdoctor-report.json

Exclude directories, increase the file-size limit to 5 MiB, or disable selected checks:

codexdoctor scan . --exclude-dir examples --exclude-dir generated --max-file-size 5
codexdoctor scan . --no-import-check --no-security-check

Control the process exit code for CI. The default only fails on errors:

codexdoctor scan . --fail-on warning
codexdoctor scan . --fail-on never

You can also use the module form:

python -m codexdoctor scan .

Python API

from codexdoctor import ScanOptions, scan

options = ScanOptions(
    exclude_dirs=("examples", "generated"),
    max_file_size=3 * 1024 * 1024,
)
report = scan(".", options=options)

print(report.summary())
for finding in report.findings:
    print(finding.severity, finding.code, finding.path, finding.line)

For a quick scan with defaults:

from codexdoctor import scan

report = scan(".")

The API returns a ScanReport; it does not write files or execute the project.

Diagnostic codes

Scope and limitations

• Import resolution is static and deliberately conservative. Dynamic imports, plugin systems, generated modules, editable installs, namespace packages, platform-specific dependencies, and some complex monorepos may not be fully understood.
• Import availability is checked in the Python environment running CodexDoctor, which may differ from the project's target environment.
• Optional imports inside a recognized try/except ImportError are skipped. Other optional-import conventions may still be reported.
• Security checks detect selected AST patterns. They do not prove that a project is safe or vulnerable; aliases, wrappers, dynamic execution, data flow, and custom APIs can evade or confuse these heuristics.
• Syntax parsing uses the Python version running CodexDoctor. Code targeting a different Python version may produce different results.
• The scanner does not install packages, run tests, format code, or change source files. Hidden files can be included explicitly, but hard-excluded cache/repository folders (such as .git, .venv, and __pycache__) remain skipped.

Development

python -m pip install -e ".[dev]"
python -m pytest
python -m build
python -m twine check dist/*

See CONTRIBUTING.md for contribution guidance, SECURITY.md for reporting security concerns, and PUBLISHING.md for the release process.

License

MIT. See LICENSE.