windyboy
dcd87754cf
- Updated AGENTS.md to reflect changes in CLI commands and module organization, including the addition of an enrichment step and new functional modules. - Introduced analysis.json, identities.json, inventory.csv, and plan.json to support enriched metadata and execution planning. - Added CODE_IMPROVEMENTS.md to document identified code issues and proposed solutions for future enhancements. - Updated README.md to include new enrichment features and configuration options. - Removed unused dependency on ffmpeg-python from pyproject.toml. These changes improve the overall functionality and maintainability of the Video Library Manager project.
2.7 KiB
2.7 KiB
Repository Guidelines
Project Structure & Module Organization
- Core package lives in
src/vlm/. - CLI entrypoint is
src/vlm/cli.py(vlmconsole script). Commands usepass_contextandCLIContextfromcontext.py; some command logic lives incommands/(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). - 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.