Skip to content

Commit b452743

Browse files
donjor-agent[bot]donjor
authored andcommitted
docs(fork): document hook marker span; guard names the comment fix (#1497)
## Problem "Marking a hook" in `docs/fork/internals/fork-delta.md` listed a `FORK_HOOKS` manifest that no longer exists and never said what span a trailing marker covers. Authors learned the walk from guard refusals: the 2026-10-02 sync hit four on one `apps/desktop/src/preview/Manager.ts` hook. ## Change | Change | Result | | --- | --- | | Walk rule | trailing marker covers its whole statement | | Comment placement | table plus refused and accepted examples | | Manifest row | removed | | Reflow row | scoped to `fork-hook-seam` | | Guard message | all-comment refusal: move the comment inside the statement or drop it | | Walk | unchanged | ## Scope and approval Closes #1492, implementing its Decision table only. ## Close conditions - [x] **Walk rule:** documented with examples - [x] **Manifest row:** removed - [x] **Reflow row:** names its guard - [x] **Message:** comment-only refusal names the fix - [x] **Guard:** a test covers the new message ## Verification ```text vp test run scripts/lib/fork-hook-guard.test.ts scripts/lib/fork-hooks.test.ts → exit 0 (33 passed) vp run fork:ci → exit 0 ``` `parseForkHookMarkers` on the three documented placements gave the spans the doc states: ```text comment above [2, 6] comment outside comment after => [3, 6] const line and comment outside comment in args [1, 6] whole statement ``` Claude Code, claude-opus-5-5. ## Fork trailers Fork-Domain: fork-meta Fork-Tier: qol Fork-Upstreamable: no Co-authored-by: donjor <[email protected]>
1 parent dc4178b commit b452743

3 files changed

Lines changed: 78 additions & 12 deletions

File tree

‎docs/fork/internals/fork-delta.md‎

Lines changed: 48 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -85,14 +85,51 @@ Decided per commit by the levers retire, reshape, automate, or accept; no gate c
8585

8686
| Case | Marker |
8787
| -------------- | ------------------------------------------------------------------------- |
88-
| Single line | trailing `// fork-hook: <domain>/<name>` |
88+
| Statement | trailing `// fork-hook: <domain>/<name>` or `/* fork-hook: … */` |
8989
| Multi-line JSX | the pair `{/* fork-hook: <domain>/<name> */}` and `{/* fork-hook-end */}` |
90-
| Manifest | every marker also listed in `FORK_HOOKS` in `scripts/lib/fork-hooks.ts` |
9190
| Charging | `scripts/lib/fork-hooks.ts` is fork-owned, so its edit is never charged |
9291

9392
**A hook is exactly one construct:** one import, one call, one `const` from a single fork call, one JSX element, one fork-named property or spread, or one re-export.
9493
**A hook never removes or modifies an upstream line**, except that a marked JSX region may re-indent what it wraps, and an in-place substitution removes the line its marked replacement supplies.
9594

95+
**A trailing marker covers the whole statement it closes.** `statementStartLine` in `scripts/lib/fork-hooks.ts` walks back from the marker line.
96+
97+
| Line above, at the statement's own depth | Walk |
98+
| ---------------------------------------- | --------- |
99+
| Inside an open bracket or literal | continues |
100+
| Ends in `;`, `{`, `,`, or a closing `}` | stops |
101+
| Blank or comment-only | stops |
102+
103+
The hook guard, `scripts/lib/fork-hook-guard.ts`, refuses every added line outside the span, so comment placement decides the outcome.
104+
105+
| Comment | Span | Guard |
106+
| ------------------------- | ------------------------- | ------- |
107+
| Above the hook | starts below the comment | refuses |
108+
| Between `=>` and the body | starts at the body | refuses |
109+
| Inside the call arguments | open bracket: walk passes | accepts |
110+
111+
Refused: the comment stops the walk, leaving the `const` line and the comment unmarked.
112+
113+
```ts
114+
const trackInstaller = (install: (session: Session) => void) =>
115+
// Each window installs its download handler on every browser session.
116+
Effect.acquireRelease(
117+
Effect.sync(() => installers.add(install)),
118+
() => Effect.sync(() => installers.delete(install)),
119+
); // fork-hook: multi-window/download-track
120+
```
121+
122+
Accepted: the comment sits inside the open call.
123+
124+
```ts
125+
const trackInstaller = (install: (session: Session) => void) =>
126+
Effect.acquireRelease(
127+
// Each window installs its download handler on every browser session.
128+
Effect.sync(() => installers.add(install)),
129+
() => Effect.sync(() => installers.delete(install)),
130+
); // fork-hook: multi-window/download-track
131+
```
132+
96133
### The removal rule
97134

98135
`unexplainedRemoval` aligns base against fork over significant lines, accepting a removed base line only when its position falls inside a marked span.
@@ -110,15 +147,15 @@ Zero sites, several, or an unplaceable end marker leaves an ordinary `conflict`
110147

111148
It refuses an addition outside a marked hook, a deletion outside the removal rule, or an unknown marker, and lives in `ADOPTED_AUTHORING_GUARDS`.
112149

113-
| Aspect | Rule |
114-
| ----------------- | -------------------------------------------------------- |
115-
| Fork side | rebuilt from the upstream blob and the diff's positions |
116-
| Unreconstructable | charged, never exempted |
117-
| Removal gap | every addition in it must be a line-kind marked hook |
118-
| Formatter reflow | same tokens either side: no addition charge |
119-
| Outside the rule | upstreamable `bugfix` commits, and generated paths |
120-
| Generated files | never reshape debt; a sync restores HEAD and regenerates |
121-
| Historical range | advisory, so the woven trunk is unaffected |
150+
| Aspect | Rule |
151+
| ----------------- | -------------------------------------------------------------------------------------------------- |
152+
| Fork side | rebuilt from the upstream blob and the diff's positions |
153+
| Unreconstructable | charged, never exempted |
154+
| Removal gap | every addition in it must be a line-kind marked hook |
155+
| Formatter reflow | same tokens either side: no `fork-hook-seam` addition charge; the hook guard has no such exemption |
156+
| Outside the rule | upstreamable `bugfix` commits, and generated paths |
157+
| Generated files | never reshape debt; a sync restores HEAD and regenerates |
158+
| Historical range | advisory, so the woven trunk is unaffected |
122159

123160
It charges some seams the walk accepts, never the reverse.
124161
A scar rule directs the author to a fork-owned file, and the narrow call left behind still needs its own marker.

‎scripts/lib/fork-hook-guard.test.ts‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,27 @@ it("flags an unmarked insertion on a marker-capable path", () => {
3232
assert.match(warnings[0] ?? "", /outside a marked hook/);
3333
});
3434

35+
it("tells a comment above a hook to move inside the statement or go", () => {
36+
const warnings = hookGuardWarnings(
37+
input([
38+
"// Each window installs its download handler.",
39+
"const track = Effect.acquireRelease(",
40+
" Effect.sync(() => installers.add(install)),",
41+
"); // fork-hook: multi-window/download-track",
42+
]),
43+
);
44+
assert.equal(warnings.length, 1);
45+
assert.match(warnings[0] ?? "", /move the comment inside the statement or drop it/);
46+
});
47+
48+
it("keeps the wrap remedy when unmarked code sits beside a comment", () => {
49+
const warnings = hookGuardWarnings(
50+
input(["// The fork's own counter.", "export const forkThing = 1;"]),
51+
);
52+
assert.equal(warnings.length, 1);
53+
assert.match(warnings[0] ?? "", /wrap the insertion in a fork-hook marker/);
54+
});
55+
3556
it("refuses an unmarked rewrap with no exemption", () => {
3657
// Any unmarked edit in range is refused, full stop: a formatter
3758
// rewrapping a landed line is marked by a human, not exempted.

‎scripts/lib/fork-hook-guard.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,9 @@ export interface HookGuardInput {
5454
readonly replayAddedLines?: ReadonlyMap<string, ReadonlyArray<string>> | undefined;
5555
}
5656

57+
/** A trimmed line that is only comment: `//`, a block opener, or a block continuation. */
58+
const COMMENT_LINE = /^(?:\/\/|\/\*|\*)/;
59+
5760
const isForkHookSuffixLine = (line: string): boolean =>
5861
FORK_HOOK_LINE_SUFFIX.test(line) || FORK_HOOK_BLOCK_SUFFIX.test(line);
5962

@@ -113,8 +116,13 @@ export const hookGuardWarnings = (input: HookGuardInput): ReadonlyArray<string>
113116
);
114117
if (code.length === 0) continue;
115118
const sample = code.slice(0, 3).map((line) => line.trim());
119+
// A comment-only line ends a trailing marker's backward walk, so marking
120+
// more cannot cover it; only moving or dropping the comment can.
121+
const remedy = code.every((line) => COMMENT_LINE.test(line.trim()))
122+
? "a comment-only line stops the marker's walk, so move the comment inside the statement or drop it"
123+
: "wrap the insertion in a fork-hook marker";
116124
details.push(
117-
`${path}: ${code.length} added line(s) outside a marked hook (first: ${sample.join(" / ")}); wrap the insertion in a fork-hook marker`,
125+
`${path}: ${code.length} added line(s) outside a marked hook (first: ${sample.join(" / ")}); ${remedy}`,
118126
);
119127
}
120128
return details;

0 commit comments

Comments
 (0)