release: v0.2.0 repository hygiene, CI, and docs sync
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>
This commit is contained in:
windyboy
co-authored by
Claude Sonnet 4.5
Cursor
Claude Sonnet 4.5
Cursor
parent
e70bd35498
commit
6f0df5a774
@@ -0,0 +1,461 @@
|
||||
# VLM Issues Report
|
||||
|
||||
**Source:** Professional code and documentation review (2026-05-25)
|
||||
**Scope:** `src/vlm/`, `tests/`, `README.md`, `CHANGELOG.md`, `CLAUDE.md`, `AGENTS.md`, `skills/`, repository hygiene
|
||||
**Baseline cited in docs:** `pytest -q` → 517 passed (see `CHANGELOG.md` 2026-05-21)
|
||||
|
||||
This document lists actionable issues by priority. Use it for triage, GitHub issues, or a cleanup sprint. Items marked **strength** are not bugs; they are recorded for balance.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Priority | Count | Theme |
|
||||
|----------|------:|-------|
|
||||
| P0 — Critical | 1 | Committed personal library data |
|
||||
| P1 — High | 4 | CI, license, doc drift, release metadata |
|
||||
| P2 — Medium | 5 | CLI structure, imports, HTTP ops, doc accuracy |
|
||||
| P3 — Low | 6 | Tooling, product gaps, minor code notes |
|
||||
| Strengths | 5 | Keep; do not regress |
|
||||
|
||||
**Overall:** Core pipeline, safety model, and test depth are strong. The main gap is **repository and release discipline**, not domain logic.
|
||||
|
||||
---
|
||||
|
||||
## P0 — Critical
|
||||
|
||||
### ISSUE-001: Personal library artifacts committed to Git
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P0 |
|
||||
| **Category** | Security / privacy / repository hygiene |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
Git tracks **36 workflow artifact files** at the repository root (excluding `.kiro/settings/mcp.json` and `.markdownlint.json`), including:
|
||||
|
||||
- `inventory.csv`, `inventory_*.csv`
|
||||
- `identities.json`, `identities_*.json`
|
||||
- `analysis.json`, `analysis_*.json`
|
||||
- `plan.json`, `plan_*.json`, `plan_*_manual_review.csv`
|
||||
|
||||
These files contain real library paths (e.g. `/mnt/Downloads/...`), filenames, release groups, and metadata for thousands of entries (e.g. `identities.json` reports 4726 files).
|
||||
|
||||
`.gitignore` ignores `artifacts/` and `runs/` but **not** legacy root-level CSV/JSON. CHANGELOG (2026-02-16) moved defaults to `artifacts/` without removing tracked root files.
|
||||
|
||||
**Impact**
|
||||
|
||||
- Privacy exposure if the repo is shared or published
|
||||
- Repository bloat and slow clones
|
||||
- Confusion between “fixtures” and a live library snapshot
|
||||
- Risk of accidental reuse of stale plans/inventories in production workflows
|
||||
|
||||
**Evidence**
|
||||
|
||||
```bash
|
||||
git ls-files '*.json' '*.csv'
|
||||
```
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
1. Stop tracking root artifacts: `git rm --cached` for all workflow CSV/JSON at repo root (keep only intentional fixtures).
|
||||
2. Expand `.gitignore` for patterns such as `/inventory*.csv`, `/identities*.json`, `/analysis*.json`, `/plan*.json`, `/plan*_manual_review.csv` at repository root.
|
||||
3. Add minimal **synthetic** fixtures under `tests/fixtures/` if tests need sample artifacts.
|
||||
4. If the repo was ever public, treat paths and titles as already exposed; consider `git filter-repo` for history rewrite only if required.
|
||||
5. Document migration in README: default outputs live under `artifacts/`; do not commit generated files.
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- `git ls-files` shows no personal inventory/identity/analysis/plan artifacts at repo root.
|
||||
- CI and docs reference `artifacts/` (or `workspace_dir`) only.
|
||||
- Clone size and sensitive path leakage materially reduced.
|
||||
|
||||
---
|
||||
|
||||
## P1 — High
|
||||
|
||||
### ISSUE-002: No continuous integration
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P1 |
|
||||
| **Category** | Release engineering |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
There is no `.github/workflows/` (or equivalent) running tests on push/PR. The project claims **517 passing tests** in README and CHANGELOG, but verification depends on local runs.
|
||||
|
||||
**Impact**
|
||||
|
||||
Regressions in safety-critical paths (executor, planner, path boundaries) can merge undetected.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
1. Add a workflow: install with `uv`, run `uv run pytest -q`.
|
||||
2. Optional matrix: Python 3.10, 3.11, 3.12.
|
||||
3. Fail PRs on test failure; badge in README optional.
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- Every PR runs the full test suite automatically.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-003: Missing license and placeholder release metadata
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P1 |
|
||||
| **Category** | Legal / open source readiness |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
- `README.md` ends with `[Add your license here]`.
|
||||
- `pyproject.toml` has no `license`, `authors`, or `project.urls`.
|
||||
- README links use placeholders (`yourusername/video-library-manager`).
|
||||
|
||||
**Impact**
|
||||
|
||||
Unclear redistribution terms; blocks confident external contributions and packaging.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
1. Choose and add `LICENSE` (e.g. MIT, Apache-2.0).
|
||||
2. Set `license` and `project.urls` in `pyproject.toml`.
|
||||
3. Replace placeholder GitHub URLs in README.
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- License file present; README and pyproject agree on license identifier.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-004: Documentation fragmentation and drift
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P1 |
|
||||
| **Category** | Documentation |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
Multiple overlapping guides exist with inconsistent sync dates and paths:
|
||||
|
||||
| Document | Sync note | Drift |
|
||||
|----------|-----------|--------|
|
||||
| `README.md` | 2026-04-07, 517 tests | Long; some tree/commands outdated |
|
||||
| `CLAUDE.md` | 2026-04-07 | Overlaps README command lists |
|
||||
| `AGENTS.md` | 2026-04-07 | Overlaps dev commands |
|
||||
| `skills/vlm-library-workflow/SKILL.md` | **2026-02-16** | Uses root `inventory.csv` paths, not `artifacts/` |
|
||||
|
||||
README Development section suggests `pytest` without consistently documenting **`uv run pytest`** (project standard in `CLAUDE.md`).
|
||||
|
||||
README project tree omits modules that exist: `duplicate_resolve.py`, `plan_review.py`, `plan_render.py`, `review_display.py`, `review_tui.py`, `transaction.py`, `cli_helpers.py`, etc.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
1. Single “documentation status” line driven by `CHANGELOG.md`.
|
||||
2. Short README → link to `docs/user-guide.md` (optional split).
|
||||
3. Update `skills/vlm-library-workflow/` to `artifacts/` defaults and full review cycle (`review-plan`, `apply-review`).
|
||||
4. Align all agent docs on `uv run` for commands.
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- No conflicting default artifact paths across active docs.
|
||||
- Skills header date matches current baseline.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-005: Version and packaging metadata under-specified
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P1 |
|
||||
| **Category** | Release engineering |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
`pyproject.toml` declares `version = "0.1.0"` while the codebase has mature safety features, schema validation, review-apply cycle, and 517 tests. No versioning policy documented.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
1. Document versioning (semver vs calver) in README or `CONTRIBUTING.md`.
|
||||
2. Bump version when artifact cleanup and CI land (e.g. `0.2.0`).
|
||||
3. Consider adding `[project.optional-dependencies]` note for `pytest-cov` if README documents coverage.
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- Version reflects release readiness; changelog entry per release.
|
||||
|
||||
---
|
||||
|
||||
## P2 — Medium
|
||||
|
||||
### ISSUE-006: `cli.py` remains large despite command extraction
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P2 |
|
||||
| **Category** | Maintainability |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
Logic lives in `src/vlm/commands/*`, but `cli.py` is still ~1075 lines: Click options, help strings, and try/except wrappers for scan, parse, enrich, analyze, plan, execute, report, state, config.
|
||||
|
||||
**Impact**
|
||||
|
||||
Harder reviews and higher merge conflict rate on CLI changes.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
1. Register command groups from `commands/` modules (shared registry or Click group per module).
|
||||
2. Target `cli.py` as thin registration + global options only (~200 lines).
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- New commands add one import/register line in `cli.py`, not hundreds of lines.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-007: Inconsistent import style across modules
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P2 |
|
||||
| **Category** | Code style |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
- `executor.py` uses relative imports (`.config`, `.models`).
|
||||
- `planner.py`, `io.py`, and most of `commands/` use absolute `vlm.*` imports.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
Pick one style (prefer absolute `vlm.*` for package consistency) and apply incrementally.
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- Style documented in `AGENTS.md`; new code follows it.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-008: Enrichment HTTP layer and operational limits
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P2 |
|
||||
| **Category** | Reliability / operations |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
TMDB and enrichment use stdlib `urllib` (`providers/tmdb.py`, `enrichment.py`). Config allows `enrichment_max_concurrency: 6` without documented rate-limit behavior.
|
||||
|
||||
API keys live in `~/.vlm/config.yaml` (appropriate for local CLI); README does not prominently warn against committing config or artifacts with keys.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
1. Document TMDB rate limits and recommended concurrency in README.
|
||||
2. Document env-var or config path overrides for secrets if supported (or add support).
|
||||
3. Optional: structured retry/backoff helper shared by providers.
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- Operators have clear guidance before bulk `vlm enrich` on large libraries.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-009: README accuracy gaps
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P2 |
|
||||
| **Category** | Documentation |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
Specific gaps:
|
||||
|
||||
- Development: `pytest --cov=vlm` without `pytest-cov` in `[project.optional-dependencies]`.
|
||||
- Project structure tree incomplete vs actual `src/vlm/`.
|
||||
- Gemini skill name `vlm-expert` referenced; verify skill exists in repo or remove.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
Fix tree, dev deps, and skill activation instructions in one pass with ISSUE-004.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-010: Large planner / plan_review modules
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P2 |
|
||||
| **Category** | Maintainability |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
`planner.py` and `plan_review.py` are large, multi-responsibility modules (duplicate handling, templates, review CSV, apply-review metadata).
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
Defer split until next major feature; when touching duplicates or review, extract submodules (`planner_duplicates.py`, `plan_review_csv.py`).
|
||||
|
||||
**Acceptance criteria**
|
||||
|
||||
- No requirement to split immediately; track before next large planner change.
|
||||
|
||||
---
|
||||
|
||||
## P3 — Low
|
||||
|
||||
### ISSUE-011: No linter or type checker in project config
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P3 |
|
||||
| **Category** | Developer experience |
|
||||
| **Status** | Open |
|
||||
|
||||
**Description**
|
||||
|
||||
`pyproject.toml` has pytest/hypothesis only; no Ruff, Black, or mypy configuration.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
Add Ruff (and optional mypy on `src/vlm`) in CI after P1 CI exists.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-012: Anime categorized but not parsed
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P3 |
|
||||
| **Category** | Product / feature gap |
|
||||
| **Status** | Known limitation (documented) |
|
||||
|
||||
**Description**
|
||||
|
||||
Anime files are scanned and categorized; `parser.py` has no anime-specific parsing. README lists this under Limitations.
|
||||
|
||||
**Recommended actions**
|
||||
|
||||
Implement anime parsing or document a workaround (series parser with reduced confidence for hyphenated episode names).
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-013: Quarantine limited to movie and series
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P3 |
|
||||
| **Category** | Product / feature gap |
|
||||
| **Status** | Known limitation (documented) |
|
||||
|
||||
**Description**
|
||||
|
||||
Only movie and series categories can be quarantined; anime and `other` are rejected.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-014: Hardcoded filename parsing patterns
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P3 |
|
||||
| **Category** | Product |
|
||||
| **Status** | Known limitation (documented) |
|
||||
|
||||
**Description**
|
||||
|
||||
Movie/series patterns are fixed in `parser.py`; not user-configurable. Power users with non-standard naming will need manual review paths.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-015: Rollback is best-effort only
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P3 |
|
||||
| **Category** | Product / safety |
|
||||
| **Status** | Known limitation (documented) |
|
||||
|
||||
**Description**
|
||||
|
||||
Rollback may fail if files were modified after execution. Correctly documented; ensure execute output reminds users of limits.
|
||||
|
||||
---
|
||||
|
||||
### ISSUE-016: Broad exception handler in executor loop
|
||||
|
||||
| Field | Value |
|
||||
|-------|--------|
|
||||
| **Priority** | P3 |
|
||||
| **Category** | Code quality |
|
||||
| **Status** | Open (low risk) |
|
||||
|
||||
**Description**
|
||||
|
||||
`executor.py` catches `Exception` per operation (`pragma: no cover`) to avoid aborting the batch. Acceptable; ensure CLI always surfaces `OperationResult.error_message`.
|
||||
|
||||
---
|
||||
|
||||
## Strengths (do not regress)
|
||||
|
||||
These are not issues; they should remain explicit acceptance criteria for refactors.
|
||||
|
||||
| ID | Area | Notes |
|
||||
|----|------|--------|
|
||||
| **STR-001** | Safety model | Dry-run default; quarantine not delete; `library_root` boundary checks on execute |
|
||||
| **STR-002** | Human-in-the-loop | `review-plan` → CSV → `apply-review` → execute with review enforcement |
|
||||
| **STR-003** | Duplicate resolution | Explicit strategies; `DuplicateResolutionError`; manual-review no-ops instead of silent fallback |
|
||||
| **STR-004** | Schema validation | Typed `ExecutionPlan`; validated load/save in `io.py` |
|
||||
| **STR-005** | Test suite | ~517 tests including CLI, security (`test_path_safety.py`), Hypothesis properties |
|
||||
|
||||
---
|
||||
|
||||
## Suggested sprint order
|
||||
|
||||
1. **ISSUE-001** — Remove tracked artifacts; fix `.gitignore`
|
||||
2. **ISSUE-002** — CI workflow
|
||||
3. **ISSUE-003** — License and README URLs
|
||||
4. **ISSUE-004** + **ISSUE-009** — Doc and skills sync
|
||||
5. **ISSUE-006** — CLI slim-down (optional, when touching CLI)
|
||||
6. **ISSUE-011** — Ruff/mypy (after CI)
|
||||
|
||||
---
|
||||
|
||||
## Mapping to GitHub issues (optional)
|
||||
|
||||
When filing on GitHub, use labels such as:
|
||||
|
||||
- `priority:p0`, `priority:p1`, …
|
||||
- `type:security`, `type:docs`, `type:ci`, `type:tech-debt`, `type:feature`
|
||||
|
||||
Suggested titles:
|
||||
|
||||
1. `[P0] Remove committed library artifacts from Git`
|
||||
2. `[P1] Add CI workflow for pytest`
|
||||
3. `[P1] Add LICENSE and fix pyproject/README metadata`
|
||||
4. `[P1] Sync documentation and agent skills to artifacts/ baseline`
|
||||
5. `[P2] Slim cli.py to registration-only pattern`
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- Review conversation: 2026-05-25
|
||||
- Canonical change history: `CHANGELOG.md`
|
||||
- Architecture guide: `CLAUDE.md`
|
||||
- Contributor conventions: `AGENTS.md`
|
||||
Reference in New Issue
Block a user