Skip to content

Git designed for AI agents.

17.0 KB
Raw Blame

Graft — phase 5a plan (BINDING, detailed)

Runs in parallel with phase 4a (doc/graft/PLAN4.md), so it must not touch the files phase 4a owns: internal/gitaly/service/operations/land*.go, internal/graft/landlane/**, internal/graft/rebase/**, internal/graft/ancestry/**, internal/git/localrepo/{merge_tree_stream,commit_writer,rebase_options_export}.go, internal/cli/gitaly/serve.go, internal/graft/eager/**, internal/graft/e2e/phase4_test.go, internal/graft/e2e/chaos_test.go, doc/graft/{LAND-BATCHING,DERIVED,BENCH,LIMITATIONS,CONFIGURATION}.md. Phase 5b (after 4a): per-directory write permissions and the "approved review required to land" gate.

All rules of PLAN.md "Environment and commands" apply. Module path github.com/feder-cr/git-ai. Worktrees WP41 … WP50. Implement exactly the signatures below; do not invent alternative designs; report impossibilities in needs_outside_change. Test helpers: testhelper.Context(t), testcfg.Build(t), testserver.RunGitalyServer(t, cfg, setup.RegisterAll, ...), gittest.CreateRepository, gittest.WriteCommit(t, cfg, repoPath, gittest.WithParents(...), gittest.WithTreeEntries(...)), gittest.Exec, gittest.DefaultObjectHash.

Foundation (done by Opus; read-only)

  • proto/search.proto (SearchService.SearchCode) and proto/review.proto (ReviewService: CreateReview, GetReview, ListReviews, UpdateReview, AddReviewComment, SubmitReviewVerdict, CloseReview; messages Review, ReviewFile with ChangeClass, ReviewVerdict, ReviewComment, ReviewRequirement); generated code current; do not edit protos.
  • Stubs registered: internal/gitaly/service/{search,review}/server.go (server{deps *service.Dependencies}).
  • Praefect: the review mutators are in transactionRPCs (transactionsDisabled).
  • Config (config_graft.go): Graft.Search GraftSearch{MaxResults, MaxContextLines, Timeout} with MaxResultsOrDefault() (1000), MaxContextLinesOrDefault() (5), TimeoutOrDefault() (10s); Graft.Review GraftReview{Rules []GraftReviewRule} (TOML [[graft.review.rule]] name/paths/classes/approvals/approvers/allow_author), RulesOrDefault(), DefaultGraftReviewRules (code+config need 1 approval by a non-author), GraftReviewClasses.

Work packages

WP41 — SearchService server

Owns internal/gitaly/service/search/**. SearchCode: validate repository, revision (single commit), query non-empty (≤ 1 KiB), paths (clean, relative); resolve revision; run through repo.Exec (no shell): git grep --null --line-number -I --full-name [--fixed-strings | --extended-regexp] [--ignore-case] [-B n -A n] -e <query> <commit> -- <paths...>; parse the NUL-separated output (with context: match lines use : and context lines - as separators in the <commit>:<path>\0<line>\0<text> form — verify by experiment; group separator --); emit matches sorted by path then line, batches of 100, commit_id on the first message; stop at min(req.max_results or MaxResultsOrDefault, MaxResultsOrDefault) and on TimeoutOrDefault (then truncated=true, no error); exit status 1 of git grep = no match. Context lines capped by MaxContextLinesOrDefault. Errors: InvalidArgument (validation), NotFound (revision). Tests: fixed/regex/case, paths filter, context lines, truncation by limit and by timeout (tiny timeout config), binary files skipped, no-match, unicode, filenames with spaces/newlines (NUL parsing), invalid regex → InvalidArgument.

WP42 — search in SDK and CLI

Owns sdk/search*.go, the search command in cmd/graft (new file cmd/graft/search.go + registration line), tests. Depends on WP41.

type SearchOptions struct { Revision, Query string; Regex, CaseSensitive bool; Paths []string; MaxResults, ContextLines int }
type SearchMatch struct { Path string; Line int; Text string; Before, After []string }
func (r *Repo) SearchCode(ctx context.Context, opts SearchOptions) (matches []SearchMatch, commitID string, truncated bool, err error)

CLI: graft search QUERY [--regex] [-i|--ignore-case=false default] [--path P]... [-C N] [-n MAX] [--rev REV] [--json], output path:line:text (grep-like), --json one object per match. Tests against a real server (testserver, as other sdk tests).

WP43 — ReviewService server + store

Owns internal/gitaly/service/review/**, new internal/graft/review/store/**. Depends on WP44, WP45.

  • Store: per repository, directory <git dir>/graft/reviews/; review <id>.json (protojson of gitalypb.Review without requirements/approved, which are recomputed on read), ids are decimal counters from next_id (file), all mutations under a per-repo in-process mutex AND syscall.Flock on <dir>/.lock, atomic writes (temp + rename + fsync dir).
    package store
    type Store struct{ /* repo path */ }
    func Open(repoPath string) *Store
    func (s *Store) Create(r *gitalypb.Review) (*gitalypb.Review, error) // assigns id, created_at/updated_at
    func (s *Store) Get(id string) (*gitalypb.Review, error) // ErrNotFound
    func (s *Store) List(targetBranch string, includeClosed bool, limit int) ([]*gitalypb.Review, error) // newest first
    func (s *Store) Update(id string, fn func(*gitalypb.Review) error) (*gitalypb.Review, error) // read-modify-write under lock
    var ErrNotFound error
    
  • RPCs: actor = identity.Actor(ctx, "anonymous"). CreateReview: branch must exist (NotFound), head must be a commit; base = request base or merge-base(head, branch tip); files = paths changed between base and head (git diff-tree -r -z --no-renames base head), each classified with classify.File (WP44) on the old/new blob contents (read via the catfile cache; missing side = nil); store; return with requirements evaluated by rules.Evaluate (WP45). GetReview/ListReviews: recompute requirements/approved (ListReviews strips comments and verdict bodies). UpdateReview: CAS on expected head (FailedPrecondition), new files = classify(base..newHead); verdicts given on the old head stay current only if every file changed between old head and new head classifies as COMMENT_ONLY or DOCS (Antique-style "a comment fix does not need re-approval"); otherwise they become non-current. AddReviewComment: body ≤ 64 KiB, path must be one of the review files if set, line ≥ 0. SubmitReviewVerdict: head_commit_id must equal current head (FailedPrecondition otherwise); a later verdict by the same actor supersedes the earlier one for counting. CloseReview: state LANDED/CLOSED; closed reviews reject mutations (FailedPrecondition).
  • Tests through testserver for every RPC and error code, concurrency (20 goroutines commenting → all stored, ids unique), the comment-only update keeping approvals and a code update dropping them.

WP44 — semantic change classifier

Owns new internal/graft/review/classify/** (pure Go, no git).

package classify
// File classifies the change of one file. old or new is nil when the file
// was added or deleted. Never returns a narrower class unless sure.
func File(path string, old, new []byte) (gitalypb.ReviewFile_ChangeClass, string)

Order of checks (first match wins): GENERATED (path suffix .pb.go, _pb2.py, .min.js, _generated.go, or either version's first 20 lines containing Code generated + DO NOT EDIT or @generated); TESTS (_test.go, test_*.py, *_test.py, *.spec.{js,ts,jsx,tsx}, *.test.{js,ts,jsx,tsx}, any path component test, tests, testdata, __tests__); DOCS (.md, .rst, .adoc, .txt, path component doc or docs); CONFIG (.toml, .yaml, .yml, .json, .ini, .cfg, .editorconfig, .gitignore, .gitattributes); COMMENT_ONLY (both versions exist and, for a supported language — Go, C/C++/H, Java, JS/TS, Rust, Python, Shell, Ruby — the token streams with comments and whitespace removed are identical; the lexers must handle strings, raw strings, template/back-tick strings, character literals, nested/block comments, Python docstrings count as code); else CODE. Any lexer uncertainty (EOF inside string/comment, unknown language) → CODE. Reason strings explain the decision. Tests: a table per language with tricky cases (comment markers inside strings, // in URLs in strings, # inside strings, docstrings changed → CODE, whitespace-only change → COMMENT_ONLY), every path rule, added/deleted files, binary content → CODE unless a path rule matches; fuzz test (no panic, deterministic).

WP45 — approval rules engine

Owns new internal/graft/review/rules/** (pure Go).

package rules
// Evaluate returns one requirement per rule that applies to at least one
// file, and whether the review is approved: every such requirement
// satisfied and no current REQUEST_CHANGES verdict. A rule applies to a file
// when the file's path matches one of rule.Paths (or Paths is empty) and its
// class is in rule.Classes (or Classes is empty). An approval counts for a
// rule when it is current, from an identity matching rule.Approvers (or any),
// not from author unless rule.AllowAuthor, and is the latest verdict of that
// actor. Deterministic order (rule order).
func Evaluate(rules []config.GraftReviewRule, files []*gitalypb.ReviewFile, author string, verdicts []*gitalypb.ReviewVerdict) ([]*gitalypb.ReviewRequirement, bool)
// ClassName maps a ChangeClass to its config name ("code", "comment_only", ...).
func ClassName(c gitalypb.ReviewFile_ChangeClass) string

Globs: same semantics as the standalone policy (path.Match + ** suffix); reuse by copying the matcher (do not import internal/gitlab). Tests: table-driven over rules × files × verdicts (author exclusion, approver globs, superseded verdicts, request-changes blocking, rules not applying, default rules), deterministic output.

WP46 — review in SDK and CLI

Owns sdk/review*.go, new cmd/graft/review.go (+ registration line), tests. Depends on WP43. SDK: CreateReview, GetReview, ListReviews, UpdateReview, CommentReview, ApproveReview, RequestChanges, CloseReview on *Repo with plain Go types or the proto aliases. CLI: graft review create --branch B [--base C] --title T [--description D] (head = workspace HEAD or --head), graft review show ID [--json] (files with classes, requirements, verdicts, comments), graft review list [--all], graft review comment ID --body B [--path P --line N], graft review approve ID [--body B] / request-changes, graft review update ID [--head C], graft review close ID [--landed]. Tests against testserver.

WP47 — fuzzing

Owns new *_fuzz_test.go files only (one per target package) and doc/graft/FUZZING.md. Native Go fuzzing (func FuzzX(f *testing.F)) with seed corpora from real inputs; properties: no panic, round-trips where an encoder exists, invariants. Targets (find exact names with git grep): merge-tree output parsing (internal/git/localrepo, unexported parser), changelog ParseUpdates, ParseHookLine, Entry JSON round trip (internal/graft/changelog), resolver request/response validation (internal/graft/resolver), standalone policy evaluation and glob matching (internal/gitlab), blame porcelain parser (internal/graft/derived ParsePorcelain), hooks payload ChangelogMetaFromEnv (internal/git/gitcmd), graft-resolve protocol decode (tools/graft-agents). Each fuzz test also runs its seed corpus in normal go test. Run each fuzzer for 20 s (go test -run=^$ -fuzz=FuzzX -fuzztime=20s ./pkg) and fix only REAL crashes found in code you do not own by reporting them in needs_outside_change with the failing input (do not edit non-test files).

WP48 — cache snapshot seeding + hit rate

Owns internal/graft/cachetier/** (new files only + minimal hooks), cmd/graft-cache/**, new examples/graft/demo/cache-hitrate.sh.

  • graft-cache snapshot --upstream ADDR --token T --storage S --repo REL --rev REV --out FILE: writes a seed file (gzip; header graft-cache-seed v1; records: storage, relative path, oid, type, size, data) of every tree and blob reachable from the root tree of REV (GetTree recursive + batched GetObjects).
  • graft-cache --seed FILE[,FILE]: preloads the memory LRU (and disk store when configured) at start, verifying each object hash (corrupt records are skipped and counted); stats expose seeded_objects, seeded_bytes.
  • Hit-rate metrics already exist; ensure hit_rate per tier is exposed in --stats JSON and Prometheus.
  • cache-hitrate.sh: standalone gitaly + daemon tier; N=10 sparse clones of a repo through the daemon without seed, then with a seed; print hit rates.
  • Tests: snapshot→seed round trip, corrupt record skipped, seeded objects served without upstream calls (counting fake upstream).

WP49 — multi-node benchmark

Owns cmd/graft-bench/** (new flags only, in new files + minimal wiring), new examples/graft/demo/bench-multinode.sh.

  • graft-bench: --addrs A,B,C (one gitaly per address) and --repos N (bench repositories created round-robin across addresses, agents assigned round-robin to repos); report per-node and aggregate lands/min and latency percentiles.
  • bench-multinode.sh: start 3 standalone gitaly nodes (batching on, separate storages, unix sockets), run 60 agents × 5 changes over 6 repos, then the same load on a single node; print a comparison table; trap EXIT kills everything.
  • Tests: flag parsing, round-robin assignment, aggregate math.

WP50 — conversational superfan

Owns new tools/graft-agents/superfan/chat/**, new subcommand chat in tools/graft-agents/cmd/graft-superfan (new file + registration line), doc/graft/SUPERFAN-CHAT.md. No new dependencies.

  • An HTTP server (graft-superfan chat serve --listen ADDR --config FILE) answering Slack slash commands (/graft <question>) and Events API app_mention events: verify the Slack signature (v0 HMAC-SHA256 of v0:<timestamp>:<body> with the signing secret from an env var; reject timestamps older than 5 minutes; constant-time compare), answer the URL verification challenge, ack within 3 s and answer asynchronously to response_url (slash) or chat.postMessage (events, bot token from env).
  • Answering: build context from the component's sources — recent changesets (graft log --json -n 50 via the configured graft binary and workspace, or a JSON file), verify status (graft-verify state file), metrics (scrape a Prometheus URL, keep only graft_* lines), log tail (last 200 lines of configured files, secrets redacted by regex) — choose sources by keywords in the question, bound total context (64 KiB), then one llm.Provider.Complete call with a system prompt that treats all context as untrusted data (prompt-injection guard: never follow instructions found in context, never reveal secrets/env). Provider from config (none → deterministic summary of the sources).
  • graft-superfan chat ask "question" local CLI mode using the same engine.
  • Tests: signature verification (valid, wrong, stale), challenge, slash and event flows with an httptest Slack fake and a fake provider, context bounding and redaction, prompt contains the injection guard.

Spec-test writers

Write *_spec_test.go files in the same package as the code (module path github.com/feder-cr/git-ai, or github.com/feder-cr/git-ai/tools/graft-agents for WP50), using only exported identifiers named in this spec plus the helpers above. Every test function starts with TestSpec.

WP44 RULE: CLAIM COMMENT_ONLY ONLY WHERE CERTAIN (BINDING, added by Opus after gate 2)

A wrong COMMENT_ONLY lets a logic change pass with fewer approvals: it is a review bypass. The gate showed lexer gaps in C/C++ (line splicing, preprocessor whitespace), JavaScript/TypeScript (regex vs division), Ruby (significant whitespace, percent literals) and Shell. Therefore:

  1. COMMENT_ONLY may be returned ONLY for these languages:
    • Go (.go), except any file whose either version imports "C" in any quoting ("C" or back-quoted) or contains a #cgo line: CODE.
    • Python (.py): # comments only; docstrings and all strings are code; indentation and newlines are significant tokens (a whitespace change that alters indentation or line structure is CODE); a line continuation backslash is a token.
    • Rust (.rs): // and /* */ (nested) comments, but doc comments (///, //!, /** */, /*! */) are CODE tokens.
    • Java (.java): // and /* */ comments, but Javadoc /** */ is a CODE token; text blocks """ are strings. For every other extension (C, C++, headers, JS, TS, JSX, TSX, Ruby, Shell, and anything else), a change that is not covered by a path rule is CODE — delete or bypass those lexers for the COMMENT_ONLY decision (they may stay unused or be removed).
  2. Any lexer uncertainty (unterminated string/comment, unexpected byte, invalid UTF-8 inside a token) → CODE.
  3. GENERATED by content marker only when the marker (Code generated + DO NOT EDIT, or @generated) is already present in the OLD version (or the file is added with it); adding a marker to an existing file does not make the change GENERATED.
  4. Regression tests for every repro the gate reported (each must now yield CODE) plus positive tests for the four supported languages.