Metadata-Version: 2.4
Name: codexdoctor
Version: 0.2.0
Summary: Static, read-only diagnostics for Python projects
Author: Mohammad Rasol
License: MIT License
        
        Copyright (c) 2026 Mohammad Rasol
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Keywords: python,static-analysis,diagnostics,security,code-quality
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6; extra == "dev"
Dynamic: license-file

# 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

```bash
python -m pip install .
```

For development:

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

## Command-line usage

Scan the current directory:

```bash
codexdoctor scan .
```

Scan another project:

```bash
codexdoctor scan path/to/project
```

Get JSON output:

```bash
codexdoctor scan . --format json
```

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

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

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

```bash
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:

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

You can also use the module form:

```bash
python -m codexdoctor scan .
```

## Python API

```python
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:

```python
from codexdoctor import scan

report = scan(".")
```

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

## Diagnostic codes

| Code | Meaning |
|---|---|
| `PY_SYNTAX` | Python source could not be parsed. |
| `IMPORT_NOT_FOUND` | An import could not be located in the active environment or project index. |
| `SEC_EVAL` / `SEC_EXEC` | Dynamic evaluation or execution call detected. |
| `SEC_UNSAFE_DESERIALIZATION` | Pickle/dill load operation detected. |
| `SEC_UNSAFE_YAML` | `yaml.load` detected without a recognized safe loader. |
| `SEC_SUBPROCESS_SHELL` | A supported subprocess function uses `shell=True`. |
| `SEC_OS_SHELL` | `os.system` or `os.popen` detected. |
| `SEC_TEMPFILE_MKTEMP` | Race-prone `tempfile.mktemp` detected. |
| `PROJECT_NO_README` | No common README file at the project root. |
| `PROJECT_NO_TESTS` | No conventional tests directory or test filename found. |
| `PROJECT_NO_PACKAGING` | No common Python packaging configuration found. |
| `FILE_ENCODING` | Source encoding could not be detected/decoded. |
| `FILE_READ_ERROR` | Source could not be read. |
| `FILE_TOO_LARGE` | Source skipped because it exceeded the configured size limit. |

## 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

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

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

## License

MIT. See [LICENSE](LICENSE).
