Add repo-memory CLI test docs

2026-03-20 15:42:35 +08:00
parent e32c81db12
commit a6ffc376e3
43 changed files with 1583 additions and 17 deletions
@@ -0,0 +1,83 @@
+# Repo Memory Markdown Test Plan
+
+## Purpose
+
+This directory contains the human-readable Markdown test plan for the
+`repo-memory` CLI.
+
+It complements package-level Go tests. The goal is to preserve the user-visible
+command contract in a form that can be reviewed, extended, and replayed without
+re-deriving behavior from implementation code.
+
+## Directory Rules
+
+- one folder per `repo-memory` command or shared area
+- each folder keeps a `README.md` entrypoint
+- command folders use `README.md` as an index only
+- each command test case lives in its own Markdown file named after the case slug
+- no numeric test IDs
+- each command case is identified by its concrete file path
+
+Case file naming pattern:
+
+```text
+<case-slug>.md
+```
+
+## Authoring Principles
+
+- focus on externally visible CLI behavior rather than store internals
+- prefer stable command sequences that a new agent can replay against a temp repo and SQLite DB
+- document both success contracts and failure boundaries
+- reuse scenarios from existing Go tests before inventing new cases
+- keep terminology consistent with the CLI: repo, entry, alias, dependency, event, verify, stale, and needs_review
+
+## Common Execution Model
+
+Most cases in this directory assume the same baseline:
+
+1. create an isolated temporary directory
+2. create a Git repository fixture such as `TMPDIR/repo`
+3. choose a database path such as `TMPDIR/repo-memory.db`
+4. run `repo-memory init --db TMPDIR/repo-memory.db`
+5. run the target command sequence against that database and repository
+
+Unless a case says otherwise:
+
+- assertions should check both exit code and human-readable stdout or stderr
+- repo-scoped cases should use an actual Git repo so `verified_on_commit` and repo registration are meaningful
+- `add` and `ingest` may bootstrap schema automatically, but most read commands assume `init` already ran
+
+## Folder Map
+
+- `README.md`: global conventions and glossary
+- `ROADMAP.md`: document progress, planned case backlog, and authored-case register
+- `_shared/README.md`: reusable fixtures, output assertions, exit-code rules, and repo conventions
+- `workflows/README.md`: cross-command end-to-end scenarios
+- per-command folders: command-specific index `README.md` files plus one case document per test case
+
+## Glossary
+
+- `repo`: one tracked repository root stored in the memory database
+- `entry`: one durable knowledge record keyed by repo, kind, key, and optional scope
+- `alias`: an alternate search term attached to one entry
+- `dependency`: a file, dir, or glob evidence locator used during verification
+- `event`: a historical record such as `created`, `updated`, `downgraded`, or `marked_stale`
+- `needs_review`: knowledge that may still be useful but should be re-checked
+- `stale`: knowledge that no longer has valid hard evidence and should not be treated as current
+
+## Relationship To Automated Tests
+
+The current executable references are:
+
+- [store_test.go](../../../packages/repo-memory-runtime/internal/store/store_test.go) for import, search, alias, dependency, link, and verification-state transitions
+- [load_test.go](../../../packages/repo-memory-runtime/internal/documents/load_test.go) for markdown parsing
+- [main_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/main_test.go) for verify downgrade heuristics
+
+These tests do not replace the Markdown plan. They only reduce discovery work.
+
+When this Markdown plan expands:
+
+- prefer matching an existing automated scenario first
+- record any additional manual-only CLI contract coverage explicitly in the relevant command case file
+- keep [ROADMAP.md](./ROADMAP.md) synchronized with authored files and case slugs