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:

repo-memory init --db TMPDIR/repo-memory.db

Recommended repo bootstrap for Git-aware cases:

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:

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.