Package: repin

Result is the value Build returns: a sorted list of deltas plus aper-file summary derived from the same list. The caller passesDeltas to Apply or to one of the Format* functions.

The JSON field names form the stable contract for thereqmd repin --json interface.

ApplyReport describes the outcome of a repin apply step. Appliedis the number of ref replacements actually written to disk (adelta whose SourceRef wasn't found in any attr block is a no-opand not counted). Skipped holds the predated deltas, which repinnever auto-fixes. Files is the number of distinct spec filesactually rewritten.

Build parses the spec tree at root and returns the list ofversion-pin changes that repin would propose (or apply, whenfollowed by Apply). When promoteUnpinned is true, refs withouta pin against a versioned upstream are also proposed for pinning— converting "no claim" into "claimed at current version".

The returned Result is sorted (delegated to graph.RepinDeltas).

Apply rewrites each file containing at least one outdated orunpinned delta. Predated deltas are reported back in the Skippedslice and never applied — they are data-integrity errors thatrequire manual review.

The rewrite is scoped to ```attr blocks: each block's contentsare scanned for the SourceRef substring, which is replaced withthe new ref form (REFnewPin, or REFnewPin if the ref waspreviously unpinned). All other bytes of the file are preservedverbatim.

Files are read and rewritten relative to root through an os.Root, so adelta path can never escape the requirements tree. If a write fails thefunction returns the error; the apply report lists every delta that wassuccessfully applied.

applyToFile rewrites the attr-block portions of src so that eachdelta's SourceRef is replaced with the new ref form. A delta isconsidered a no-op if its SourceRef isn't found in any attr block(or every match is at a non-boundary position); in that case thefile is returned unchanged.

Returns the (possibly rewritten) bytes and the total number ofref replacements actually made across all attr blocks.

Matching is whole-ref: SourceRef "UP-001" only matches when theref is at a list-element boundary (followed by ,, ], orwhitespace) AND is not the prefix of a longer ref (not followedby ~ for the unpinned-promote case). This prevents a naivesubstring match from corrupting an already-pinned ref likeUP-001~3 when the same ref is being promoted from unpinned.

refPair is a pre-computed (oldRef, newRef) pair ready for bytematching. oldRef and newRef are []byte (not strings) to avoidrepeated []byte() conversions inside the hot scan loop.

buildPairs projects a slice of RepinDelta into refPairs, droppingany delta whose old ref already equals the new ref (no-op).

applyPairsToBlock scans block and emits a new []byte with everymatching ref replaced. For each position it finds the earliestnext match across all pairs, copies the unmatched run verbatim,then emits the replacement. Returns the new bytes and the numberof replacements made. When no pair matches, returns blockunchanged (zero allocation) and a count of 0.

Cost note: this is N sub-scans into one output buffer, where N islen(pairs) — not a true single pass. For the typical repinworkload (a handful of deltas, small attr blocks) this is fine;an Aho-Corasick automaton would be the single-pass alternative butis overkill here.

isRefBoundary reports whether the match at [start, end) inside bufis a whole ref (not a substring of a longer token). Both edges arechecked:The byte before the match must be a list-element starter ([, ,, whitespace, or start-of-block) so we don't match "UP-001" inside "XUP-001".The byte after the match must be a list-element terminator ( , \t, \n, \r, ,, ], or end-of-block) so we don't match "UP-001" inside "UP-001X".The byte after must NOT be ~ — that would mean we matched the prefix of a longer ref (e.g. "UP-001" inside "UP-001~3"), which must never be rewritten.

newRefFrom computes the new source-form ref string for a delta.The transform is:"doc-id/ID1" + newPin=3 → "doc-id/ID3""ID1" + newPin=3 → "ID3""doc-id/ID" + newPin=3 → "doc-id/ID3" (unpinned promote)"ID" + newPin=3 → "ID3" (unpinned promote)

attrRange is an inclusive [start, end) byte range covering theinner YAML of an attr block (NOT including the ``` fences).

locateAttrBlocks scans src for attr\n ... \n fences andreturns the inner-YAML byte ranges. Blank lines between theopening fence and the first YAML line are skipped over by theparser; the same applies here: we treat the byte immediatelyafter the opening fence's newline as the range start.

The match is anchored to the literal string "```attr" followedby an optional space/info segment. This matches the parser'sattrFenceInfo = "attr" convention exactly.

bytesSliceReplace returns a new []byte with src[start:end]replaced by replacement. Single allocation via nested appends.

stripPinForDisplay removes a trailing ~N from a ref so the dry-rundiff reads naturally. Delegates to model.StripPin.

FormatText renders the Result as the human-readable change listshown by reqmd repin in dry-run mode. The format is:spec/path/to/file.md REQ-ID REF → REF~newPin ... N outdated + M unpinned + P predated refs across K files.

FormatTextApplied renders an ApplyReport as a one-line summary.Used after a successful --yes run.

---

minimalSchema is a permissive JSON Schema for attr blocks. Testsonly need the schema to exist (parser requires it); they don'tvalidate the attrs strictly.

makeTree creates a two-doc spec tree with one upstream (versionedat upVersion) and one downstream that traces to it with thesupplied pin (or no pin when pin is ""). The downstream's traceline is rendered exactly as supplied so we can assert byte-leveledits in Apply.

---

---

TestApply_UnpinnedPromoteDoesNotCorruptPinnedSiblings guardsagainst a real bug discovered in the smoke test: a naive substringmatch for SourceRef="UP-001" would rewrite the prefix of analready-pinned ref "UP-0013" to "UP-0013~3". The apply pathmust use whole-ref matching so an unpinned ref never corrupts apinned sibling.

---

---

---

---

---

TestApply_PreservesFileMode verifies that rewriting a spec file keeps itsexisting permissions instead of forcing a default mode.