95 lines
4.8 KiB
Markdown
95 lines
4.8 KiB
Markdown
# 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:
|
|
|
|
- [init_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/init_integration_test.go) for `init`
|
|
- [add_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/add_integration_test.go) for `add`
|
|
- [ingest_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/ingest_integration_test.go) for `ingest`
|
|
- [search_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/search_integration_test.go) for `search`
|
|
- [list_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/list_integration_test.go) for `list`
|
|
- [events_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/events_integration_test.go) for `events`
|
|
- [link_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/link_integration_test.go) for `link`
|
|
- [verify_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/verify_integration_test.go) for `verify`
|
|
- [repos_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/repos_integration_test.go) for `repos`
|
|
- [workflow_integration_test.go](../../../packages/repo-memory-runtime/cmd/repo-memory/workflow_integration_test.go) for the four documented workflow cases
|
|
- [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 are the executable companion
|
|
to it.
|
|
|
|
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
|