Add repo-memory CLI test docs
This commit is contained in:
@@ -0,0 +1,137 @@
|
||||
# Repo Memory Shared Test Conventions
|
||||
|
||||
## Purpose
|
||||
|
||||
This document captures shared assumptions used by multiple `repo-memory`
|
||||
test-plan documents so command and workflow files can stay focused on behavior
|
||||
instead of repeating setup boilerplate.
|
||||
|
||||
## Recommended Fixture Shape
|
||||
|
||||
Use an isolated temp workspace per case:
|
||||
|
||||
- database path: `TMPDIR/repo-memory.db`
|
||||
- repository path: `TMPDIR/repo`
|
||||
- optional second repository path: `TMPDIR/repo-b`
|
||||
- default ingest path: `TMPDIR/repo/docs/ai`
|
||||
- optional evidence file: `TMPDIR/repo/path/to/file`
|
||||
|
||||
Recommended bootstrap command:
|
||||
|
||||
```bash
|
||||
repo-memory init --db TMPDIR/repo-memory.db
|
||||
```
|
||||
|
||||
Recommended repo bootstrap for Git-aware cases:
|
||||
|
||||
```bash
|
||||
git -C TMPDIR/repo init
|
||||
git -C TMPDIR/repo config user.email test@example.com
|
||||
git -C TMPDIR/repo config user.name Tester
|
||||
git -C TMPDIR/repo add .
|
||||
git -C TMPDIR/repo commit -m "init"
|
||||
```
|
||||
|
||||
## Flag Model
|
||||
|
||||
`repo-memory` uses one subcommand-specific flag set per command. There is no
|
||||
root `--json` mode and no shared global flag parser.
|
||||
|
||||
Common flags across multiple commands:
|
||||
|
||||
- `--db`: SQLite database path
|
||||
- `--repo`: repository root or repo-path substring filter depending on command
|
||||
- `--limit`: result limit on read commands
|
||||
|
||||
Case files should call out whether `--repo` is:
|
||||
|
||||
- a required absolute repo root for `add` and `ingest`
|
||||
- an optional substring filter for `search` and `list`
|
||||
- an optional absolute repo root selector for `verify`
|
||||
|
||||
## Text Output Contract
|
||||
|
||||
Successful output is plain text written to stdout.
|
||||
|
||||
Shared assertion guidance:
|
||||
|
||||
- assert stable prefixes or phrases, not timestamp values
|
||||
- prefer checking identifiers, kinds, keys, statuses, and count summaries
|
||||
- when output contains absolute repo paths, compare against the concrete fixture path used by the case
|
||||
|
||||
Representative success phrases:
|
||||
|
||||
- `initialized TMPDIR/repo-memory.db`
|
||||
- `upserted entry 1 (term:AITask)`
|
||||
- `ingested 1 docs from ABS_REPO`
|
||||
- `linked #1 -[related_to]-> #2`
|
||||
- `ABS_REPO: verified 1 entries, 1 downgraded, 0 stale`
|
||||
- `no results`
|
||||
- `no entries`
|
||||
- `no repos`
|
||||
|
||||
## Exit Code Contract
|
||||
|
||||
The current CLI contract uses these exit codes:
|
||||
|
||||
| Exit Code | Meaning | Typical Trigger |
|
||||
| --- | --- | --- |
|
||||
| `0` | success | command completed normally, including empty-result text such as `no results` |
|
||||
| `1` | command failure | invalid flags, missing required values, missing repo docs, unresolved entry, or store/runtime error |
|
||||
| `2` | top-level usage failure | missing subcommand or unknown subcommand |
|
||||
|
||||
When a case expects failure, assert both the non-zero exit code and the human-readable stderr message.
|
||||
|
||||
## Schema Bootstrap Rules
|
||||
|
||||
Current command behavior is intentionally uneven and should be documented:
|
||||
|
||||
- `init` creates schema explicitly
|
||||
- `add` and `ingest` call `Init` internally and can succeed on a fresh DB path
|
||||
- `search`, `list`, `events`, `link`, `verify`, and `repos` assume schema already exists
|
||||
|
||||
If a case relies on automatic schema bootstrap in `add` or `ingest`, state that explicitly in `前置条件` and `断言结论`.
|
||||
|
||||
## Repo Fixture Rules
|
||||
|
||||
Cases covering `add`, `ingest`, or `verify` should state:
|
||||
|
||||
- whether the target repo is a real Git repo
|
||||
- whether a HEAD commit already exists
|
||||
- which file path is being used as evidence or dependency
|
||||
|
||||
`verify` behavior depends on Git state:
|
||||
|
||||
- if a repo has a readable HEAD commit, verification updates repo metadata and evaluates dependencies
|
||||
- if a repo is missing Git state or has no HEAD, the command prints `skipped (not a git repo or no HEAD)` for that repo
|
||||
|
||||
## Markdown Ingest Rules
|
||||
|
||||
`ingest` scans markdown recursively under `docs/ai` by default.
|
||||
|
||||
Shared assertions for ingest cases:
|
||||
|
||||
- `.md` files are discovered recursively
|
||||
- file base name influences imported key prefixes
|
||||
- heading text influences imported `kind` classification and key slug
|
||||
- an empty `docs/ai` tree fails with `no markdown files found under ...`
|
||||
|
||||
## Direct DB Inspection
|
||||
|
||||
Most cases should stay at the CLI contract level.
|
||||
|
||||
One exception is `link`: the CLI currently writes the relation but does not have
|
||||
an inspection command for links. Link cases may use a read-only `sqlite3` query
|
||||
to confirm persistence after the CLI call.
|
||||
|
||||
Typical example:
|
||||
|
||||
```bash
|
||||
sqlite3 TMPDIR/repo-memory.db "SELECT relation FROM knowledge_links WHERE from_entry_id = 1 AND to_entry_id = 2;"
|
||||
```
|
||||
|
||||
## Workflow Authoring Rule
|
||||
|
||||
If a case spans multiple commands, place the end-to-end narrative in
|
||||
`workflows/README.md` first, then add narrower command-level cases only when
|
||||
they are easier to reason about in isolation.
|
||||
Reference in New Issue
Block a user