6f0df5a774
Stop tracking personal workflow artifacts at repo root, add CI and MIT license, align README and agent skills with artifacts/ defaults, and enable Ruff in dev/CI so releases are verifiable without local-only runs. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>
47 lines
3.1 KiB
Markdown
47 lines
3.1 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
- Core package lives in `src/vlm/`.
|
|
- CLI entrypoint is `src/vlm/cli.py` (`vlm` console script). Shared CLI helpers live in `cli_helpers.py`. Command logic is in `commands/` (scan, parse, enrich, analyze, plan, execute, review_plan, report, quarantine_cmd, state_cmd, config_cmd).
|
|
- 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-cov`, `ruff`).
|
|
- `uv run pytest -q` runs the full test suite.
|
|
- `uv run pytest tests/test_logging.py` runs a targeted test file during iteration.
|
|
- `uv run ruff check src tests` runs the linter (also in CI).
|
|
- `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.
|
|
- Use absolute imports in `src/vlm/`: `from vlm.module import ...` (avoid new relative imports).
|
|
- Ruff (`E`, `F`, `I`) is configured in `pyproject.toml`; CI runs `ruff check src tests`.
|
|
|
|
## 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 release 0.2.0 baseline as of 2026-06-01.
|
|
- Canonical release notes are tracked in `CHANGELOG.md`.
|
|
- Default workflow artifacts: `artifacts/` (do not commit generated CSV/JSON).
|