windyboy
976a1fa1d0
- Add AGENTS.md with comprehensive repository guidelines covering project structure, build/test commands, coding style, testing practices, and commit conventions - Add REVIEW_REPORT.md documenting code review findings including 4 actionable issues: logging permission errors, incorrect test imports, timezone conversion bugs, and dead error counter code - Include detailed recommendations for fix prioritization and test evidence from pytest runs - Provide reference documentation for future development and maintenance workflows
2.4 KiB
2.4 KiB
Repository Guidelines
Project Structure & Module Organization
- Core package lives in
src/vlm/. - CLI entrypoint is
src/vlm/cli.py(vlmconsole script). - Functional modules are split by concern: scanning (
scanner.py), parsing (parser.py), analysis/planning/execution (analysis.py,planner.py,executor.py), state/reporting/logging (state.py,reports.py,logging_config.py). - Tests live in
tests/and mirror feature areas (for exampletests/test_scanner.py,tests/test_cli_state.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).pytestruns the full test suite.pytest tests/test_logging.pyruns a targeted test file during iteration.vlm --helpverifies 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 usehypothesis. - Naming (enforced in config): files
test_*.py, functionstest_*, classesTest*. - 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 (
pytestoutput), 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 --helpand at least one end-to-end CLI flow before merging.