44 lines
2.9 KiB
Markdown
44 lines
2.9 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- Core package lives in `src/vlm/`.
|
|
- CLI entrypoint is `src/vlm/cli.py` (`vlm` console script). Commands use `pass_context` and `CLIContext` from `context.py`; command logic is modularized in `commands/` (e.g. `scan`, `parse`, `enrich`, `analyze`, `plan`, `execute`).
|
|
- 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`).
|
|
- 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.
|
|
|
|
|
|
## Documentation baseline
|
|
- Updated to reflect refactor results as of 2026-02-16.
|
|
- Canonical release notes are tracked in `CHANGELOG.md`.
|