2026-02-09 17:55:34 +08:00
# Repository Guidelines
## Project Structure & Module Organization
- Core package lives in `src/vlm/` .
2026-02-10 16:56:17 +08:00
- CLI entrypoint is `src/vlm/cli.py` (`vlm` console script). Commands use `pass_context` and `CLIContext` from `context.py` ; some command logic lives in `commands/` (e.g. `scan` , `analyze` , `plan` ).
- Functional modules by concern: scanning (`scanner.py` ), parsing (`parser.py` ), enrichment (`enrichment.py` , `cache.py` , `providers/` ), analysis/planning/execution (`analysis.py` , `planner.py` , `executor.py` ), I/O helpers (`io.py` ), utilities (`utils.py` ), state/reporting/logging (`state.py` , `reports.py` , `logging_config.py` ), config (`config.py` ), models (`models.py` ).
- Tests live in `tests/` and mirror feature areas (e.g. `tests/test_scanner.py` , `tests/test_cli_state.py` , `tests/test_enrichment.py` ).
2026-02-09 17:55:34 +08:00
- Project metadata and tool config are in `pyproject.toml` .
## Build, Test, and Development Commands
- `uv pip install -e .` installs the package in editable mode.
- `uv pip install -e ".[dev]"` installs dev dependencies (`pytest` , `hypothesis` ).
- `pytest` runs the full test suite.
- `pytest tests/test_logging.py` runs a targeted test file during iteration.
- `vlm --help` verifies CLI startup and available commands.
## Coding Style & Naming Conventions
- Use Python 3.10+ idioms, 4-space indentation, and PEP 8 naming.
- Modules/functions/variables: `snake_case` ; classes: `PascalCase` ; constants: `UPPER_SNAKE_CASE` .
- Keep modules focused on a single responsibility; prefer small pure helpers in domain modules.
- Add type hints for public functions and non-trivial internal APIs.
- No formatter/linter is currently enforced in `pyproject.toml` ; keep style consistent with existing files.
## Testing Guidelines
- Framework: `pytest` ; property-based tests use `hypothesis` .
- Naming (enforced in config): files `test_*.py` , functions `test_*` , classes `Test*` .
- Add/extend tests with each behavior change, including CLI error paths and edge cases.
- Prefer narrow unit tests for module logic plus targeted CLI integration tests via `CliRunner` .
## Commit & Pull Request Guidelines
- Current history is minimal; use clear, imperative commit subjects (example: `fix logging fallback for unwritable log dir` ).
- Keep commits focused; avoid mixing refactors and behavior changes unless tightly coupled.
- PRs should include: summary, rationale, test evidence (`pytest` output), and any CLI-visible output changes.
- Link related issues/tasks when applicable and call out config or migration impacts.
## Security & Configuration Tips
- Do not commit local paths, personal media metadata, or generated state/log artifacts.
- Validate config changes against `vlm --help` and at least one end-to-end CLI flow before merging.
