rungate 0.8.3 → 0.8.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/organize.ts CHANGED
@@ -22,7 +22,7 @@ import {
22
22
  import { join, relative, dirname, basename } from "path";
23
23
  import { loadComplianceConfig, type OrganizeExternalSource } from "./config-loader.js";
24
24
  import { matchesAnyAlias, projectAliases } from "./project-aliases.js";
25
- import { mayWrite, readDerivedDeclaration, skipLine } from "./derived-spec";
25
+ import { maySpecBeReplaced, writeSpec } from "./write-spec";
26
26
 
27
27
  // ── Types ────────────────────────────────────────────────────────
28
28
 
@@ -483,6 +483,17 @@ function executeProposals(root: string, proposals: OrganizeProposal[]): void {
483
483
 
484
484
  if (!existsSync(srcPath)) continue;
485
485
 
486
+ // #1552: `renameSync` below REPLACES its destination silently, and
487
+ // `organizeProjectReport` picks a target from the filename alone — a
488
+ // stray `API-SPEC.md` at the root is proposed onto `specs/API-SPEC.md`,
489
+ // annihilating a generator-owned spec without any write primitive ever
490
+ // touching it. Ask who owns the destination, not the source.
491
+ const dest = maySpecBeReplaced(tgtPath, { label: proposal.target });
492
+ if (!dest.allowed) {
493
+ console.warn(dest.refusal!);
494
+ continue;
495
+ }
496
+
486
497
  const tgtDir = dirname(tgtPath);
487
498
  if (!existsSync(tgtDir)) {
488
499
  mkdirSync(tgtDir, { recursive: true });
@@ -555,14 +566,13 @@ function updateInternalReferences(root: string, moveMap: Map<string, string>): v
555
566
  // #1286: organize moves docs into `specs/`, `docs/` and `reference/` and
556
567
  // then rewrites links INSIDE them. A moved file can be a spec a generator
557
568
  // owns, and rewriting its links is discarded at the next regeneration.
558
- const derived = readDerivedDeclaration(content);
559
- if (changed && !mayWrite(derived)) {
560
- console.warn(skipLine(newPath, derived));
561
- continue;
562
- }
563
-
569
+ // #1552: the refusal is no longer restated here — `writeSpec` asks the
570
+ // one decider and hands back the line to print. The target is a moved
571
+ // document, which the static sweep cannot see is a spec path, so this
572
+ // site is routed by hand rather than because a check demanded it.
564
573
  if (changed) {
565
- writeFileSync(fullPath, content);
574
+ const result = writeSpec(fullPath, content, { label: newPath });
575
+ if (result.refusal) console.warn(result.refusal);
566
576
  }
567
577
  }
568
578
  }
@@ -39,6 +39,8 @@
39
39
  * to the act rather than to the record.
40
40
  */
41
41
 
42
+ import { escapeAnnotation } from "./scaffold/ai-review-findings";
43
+
42
44
  /** What the registry currently holds for a package. */
43
45
  export interface RegistryState {
44
46
  /** Every published version, in no particular order. */
@@ -457,14 +459,92 @@ export function parsePublishReceipt(pkg: string, log: string): PublishReceipt {
457
459
  };
458
460
  }
459
461
 
462
+ /**
463
+ * WHICH reading the postflight took, in a few words (#1563).
464
+ *
465
+ * `outcome` is not this, and conflating them is the defect. Two of the six
466
+ * readings below are `confirmed` and only ONE of them is a registry read —
467
+ * they share an exit code, a step conclusion and a step name, so before this
468
+ * existed the only place they differed was the log body. A label is the
469
+ * narrowest thing that can travel out of the log on a channel a reader
470
+ * already looks at.
471
+ *
472
+ * Closed union on purpose: a new branch in `postflightDecision` that forgets
473
+ * to name itself does not compile.
474
+ */
475
+ export type PostflightLabel =
476
+ /** The packument carried the version. The only confirmed REGISTRY read. */
477
+ | "REGISTRY SERVES"
478
+ /** Receipt plus npm's own lag notice. Confirmed, and NOT a registry read. */
479
+ | "PROPAGATION PENDING"
480
+ /** npm printed no `+ pkg@version` line: the publish did not happen. */
481
+ | "NO RECEIPT"
482
+ /** npm published a version this tree is not cutting. */
483
+ | "RECEIPT VERSION MISMATCH"
484
+ /** A receipt with no lag notice does not waive the registry read. */
485
+ | "RECEIPT WITHOUT LAG NOTICE"
486
+ /** Absent from the packument with nothing that explains the absence. */
487
+ | "VERSION ABSENT";
488
+
460
489
  /** What the postflight concluded, and which exit code says so. */
461
490
  export interface PostflightDecision {
462
491
  /** `confirmed` exits 0, `refused` exits REFUSE_EXIT, `unmeasured` exits UNMEASURED_EXIT. */
463
492
  outcome: "confirmed" | "refused" | "unmeasured";
493
+ /**
494
+ * WHICH of the readings this is. `outcome` collapses six into three and two
495
+ * of the collapsed pair exit 0 — see `PostflightLabel` (#1563).
496
+ */
497
+ label: PostflightLabel;
464
498
  /** The whole message, already worded for the reader of a failed release job. */
465
499
  message: string;
466
500
  }
467
501
 
502
+ /**
503
+ * The annotation title every postflight verdict is printed under.
504
+ *
505
+ * It carries NO colon and NO comma. GitHub splits a workflow command's
506
+ * property list on `,` and ends it at `::`, and its own escaping rules
507
+ * require `%3A`/`%2C` inside a property value — `escapeAnnotation` encodes
508
+ * neither, because it is the escaper for message DATA. Keeping the separator
509
+ * out of the title means there is still one escaper and nothing to get wrong.
510
+ */
511
+ export const POSTFLIGHT_ANNOTATION_TITLE = "postflight —";
512
+
513
+ /**
514
+ * The decision as a GitHub Actions annotation — the fix for #1563.
515
+ *
516
+ * The step was named *"Postflight — the registry actually serves this
517
+ * version"* and on `v0.8.3` it exited 0 having said, in its own message, that
518
+ * it had taken no such reading. The name is what appears in the check list,
519
+ * the run summary and the notification; the message is 5.7 MB into a log.
520
+ *
521
+ * Retitling alone does not fix it. A title is static, so no title can
522
+ * distinguish `REGISTRY SERVES` from `PROPAGATION PENDING` — the criterion
523
+ * from the issue is that **some observable other than the log body differs
524
+ * between the two**, and an annotation is the cheapest channel that both
525
+ * carries the label and renders where the title does.
526
+ *
527
+ * Severity is derived from `outcome`, never from `label`: a `notice` for the
528
+ * two states that exit 0, an `error` for the four that stop the job. That
529
+ * leaves the open question the issue declined to answer — whether a pending
530
+ * propagation deserves a `warning` — unanswered, rather than answered by
531
+ * accident. Propagation lag is the normal path and a warning on the normal
532
+ * path is a warning nobody reads.
533
+ *
534
+ * `escapeAnnotation` is imported rather than reimplemented. A newline inside
535
+ * an interpolated value starts a NEW workflow command, and `::stop-commands::`
536
+ * on its own line disables annotation processing for everything after it — so
537
+ * a second escaper is a second rule nobody updates. The messages here embed a
538
+ * registry reading, and the confirmed one already contains a newline.
539
+ */
540
+ export function postflightAnnotation(decision: PostflightDecision): string {
541
+ const level = decision.outcome === "confirmed" ? "notice" : "error";
542
+ return (
543
+ `::${level} title=${POSTFLIGHT_ANNOTATION_TITLE} ${escapeAnnotation(decision.label)}` +
544
+ `::${escapeAnnotation(decision.message)}`
545
+ );
546
+ }
547
+
468
548
  /**
469
549
  * The ONE binding that decides whether a release happened (#472).
470
550
  *
@@ -511,6 +591,7 @@ export function postflightDecision(
511
591
  if (receipt.version === null) {
512
592
  return {
513
593
  outcome: "refused",
594
+ label: "NO RECEIPT",
514
595
  message:
515
596
  `the publish step produced no receipt. npm prints \`+ ${pkg}@${treeVersion}\` ` +
516
597
  `on a successful publish and the captured output (${receipt.bytes} bytes) has ` +
@@ -522,6 +603,7 @@ export function postflightDecision(
522
603
  if (receipt.version !== treeVersion) {
523
604
  return {
524
605
  outcome: "refused",
606
+ label: "RECEIPT VERSION MISMATCH",
525
607
  message:
526
608
  `the publish step published ${pkg}@${receipt.version}, but this tree is ` +
527
609
  `${treeVersion}. The receipt and package.json must name the same version or ` +
@@ -533,6 +615,7 @@ export function postflightDecision(
533
615
  if (reading.verdict.published) {
534
616
  return {
535
617
  outcome: "confirmed",
618
+ label: "REGISTRY SERVES",
536
619
  message:
537
620
  `the registry serves ${pkg}@${treeVersion} ` +
538
621
  `(read ${reading.attempts} time${reading.attempts === 1 ? "" : "s"}, ` +
@@ -561,6 +644,7 @@ export function postflightDecision(
561
644
  if (receipt !== null && receipt.version === treeVersion && receipt.propagationWarned) {
562
645
  return {
563
646
  outcome: "confirmed",
647
+ label: "PROPAGATION PENDING",
564
648
  message:
565
649
  `PROPAGATION PENDING — npm accepted ${pkg}@${treeVersion} and the registry is ` +
566
650
  `not serving it yet after ${reading.attempts} read` +
@@ -578,6 +662,7 @@ export function postflightDecision(
578
662
  if (receipt !== null && receipt.version === treeVersion) {
579
663
  return {
580
664
  outcome: "unmeasured",
665
+ label: "RECEIPT WITHOUT LAG NOTICE",
581
666
  message:
582
667
  `UNMEASURED: npm printed a receipt for ${pkg}@${treeVersion} but did NOT print its ` +
583
668
  `"being processed and may take a few minutes" notice, and the registry is still not ` +
@@ -588,5 +673,9 @@ export function postflightDecision(
588
673
  };
589
674
  }
590
675
 
591
- return { outcome: "unmeasured", message: reading.verdict.unmeasured ?? "no reading was taken" };
676
+ return {
677
+ outcome: "unmeasured",
678
+ label: "VERSION ABSENT",
679
+ message: reading.verdict.unmeasured ?? "no reading was taken",
680
+ };
592
681
  }
@@ -37,6 +37,7 @@
37
37
  */
38
38
  import { execFileSync } from "child_process";
39
39
 
40
+ import { type DirectoryCurrency, type GitRunner, directoryCurrency } from "./hook-tree-currency";
40
41
  import { reviewIsCurrent } from "./security-verdict";
41
42
 
42
43
  /** The exit code of a stale or unmeasurable reading. One site, so it can be mutated. */
@@ -216,3 +217,155 @@ export function provenanceBlock(reading: ProvenanceReading): string {
216
217
  ];
217
218
  return lines.join("\n");
218
219
  }
220
+
221
+ /**
222
+ * The OTHER tree a session is standing in, and the one nothing above can see
223
+ * (#1341).
224
+ *
225
+ * Everything to this point measures the checkout the session EDITS. A Claude
226
+ * Code hook registration names a directory through `RUNGATE_HOOKS_DIR`, and
227
+ * the code that executes out of it is on whatever commit the last hand
228
+ * fast-forward left. Those are two different trees and only one of them has
229
+ * ever been in the provenance block.
230
+ *
231
+ * ## The measured cost, 2026-10-24
232
+ *
233
+ * `/Users/jhorn/Projects/rg-hooks-live` sat at `7817f1df` while `origin/main`
234
+ * was at `2729ce62` — **135 commits behind**, measured with
235
+ * `git rev-list --count 7817f1df..2729ce62`. Every session's own checkout was
236
+ * clean and current, so `provenanceReading` reported CURRENT for all of them.
237
+ * In that window the finding arbiter refused three issue filings using
238
+ * duplicate-detection logic PR #1538 had corrected seven minutes earlier: two
239
+ * `DUPLICATE` verdicts on bare integers and one `DROPPED_CATEGORY/style` on
240
+ * `\btypo\b`. Three `arbiter-override` escalations were spent on a fixed bug,
241
+ * and the ledger rows record them as human overrides of real refusals.
242
+ *
243
+ * It had gone stale twice the day before. The gap is not an incident, it is
244
+ * the steady state: nothing advances that tree, so the interval between a fix
245
+ * merging and the behaviour changing is unbounded.
246
+ *
247
+ * ## Why the checkout's own SHA, and not a file recording one
248
+ *
249
+ * `rg-hooks-live` is a worktree on a detached HEAD, and a detached HEAD
250
+ * already names a commit — `git rev-parse HEAD` is the whole of the
251
+ * provenance. A `SYNCED_TO` file beside it would be a SECOND decider for one
252
+ * question, and the weaker one: it is correct only while nobody moves the
253
+ * checkout without rewriting it, so a hand fast-forward makes a current tree
254
+ * read as behind, and a hand-edited tree keeps reading as current. The
255
+ * checkout is right by construction. `.claude/rules/checks-must-be-able-to-fail.md`
256
+ * calls two deciders agreeing the shape no behavioural test can separate.
257
+ *
258
+ * ## Why the count, and not `merge-base --is-ancestor`
259
+ *
260
+ * This repository squash-merges, and the standing rule against `--is-ancestor`
261
+ * holds here for a reason the suite measures: on a hook tree that is **0
262
+ * commits behind and 1 ahead**, `--is-ancestor HEAD origin/main` exits 1 — it
263
+ * calls a checkout that is missing nothing stale — while
264
+ * `rev-list --count HEAD..origin/main` reads 0. A boolean also cannot carry
265
+ * the number, and the number is what tells a reader whether to care.
266
+ * `directoryCurrency` is imported rather than reimplemented, so there is one
267
+ * binding deciding what "behind" means.
268
+ *
269
+ * ## Why this is not a hook
270
+ *
271
+ * A currency check that ships through `${RUNGATE_HOOKS_DIR}` cannot bootstrap
272
+ * itself: the copy that is behind is exactly the copy without the reporting
273
+ * code. `scripts/report-provenance.ts` runs out of the session's own
274
+ * checkout, so it is reachable by a path that cannot be stale for the reason
275
+ * it reports.
276
+ *
277
+ * ## The binding is the env var, and an unset one SKIPS
278
+ *
279
+ * No path to any machine's hooks directory appears here. `hooksDir` is
280
+ * supplied by the caller from `RUNGATE_HOOKS_DIR`, and `null` or blank means
281
+ * no hook executes out of a foreign tree — nothing to age, so nothing to
282
+ * refuse. A check that refused on an unset binding would refuse on every CI
283
+ * runner and in every consumer's checkout, which is how a refusal becomes a
284
+ * line everyone clicks past.
285
+ */
286
+ export interface SessionProvenance {
287
+ /** The tree the session edits. Exactly what `provenanceReading` returns. */
288
+ tree: ProvenanceReading;
289
+ /**
290
+ * The tree the session's hooks execute out of, or `null` when
291
+ * `RUNGATE_HOOKS_DIR` binds nothing.
292
+ *
293
+ * `null` is NOT `current`. It means the question does not arise, and the
294
+ * block says so in those words rather than printing a pass.
295
+ */
296
+ hooks: DirectoryCurrency | null;
297
+ /**
298
+ * False when EITHER reading refuses. A rate, a refusal count or a ledger
299
+ * row produced by this session is attributable to `base` only when both
300
+ * trees are.
301
+ */
302
+ current: boolean;
303
+ }
304
+
305
+ /**
306
+ * Both readings, and one verdict over them.
307
+ *
308
+ * `base` has no default, for the reason `lib/hook-tree-currency.ts` gives: a
309
+ * default here would be a second place deciding which branch a tree is
310
+ * measured against.
311
+ */
312
+ export function sessionProvenance(input: {
313
+ root: string;
314
+ measured?: string;
315
+ ref?: string;
316
+ expectBranch?: string;
317
+ /** From `RUNGATE_HOOKS_DIR`. Never a literal path — see the header. */
318
+ hooksDir: string | null | undefined;
319
+ base: string;
320
+ git: GitRunner;
321
+ }): SessionProvenance {
322
+ const tree = provenanceReading(input.root, input.measured, input.ref, input.expectBranch);
323
+
324
+ const dir = input.hooksDir?.trim();
325
+ const hooks = dir === undefined || dir === "" ? null : directoryCurrency(dir, input.base, input.git);
326
+
327
+ return {
328
+ tree,
329
+ hooks,
330
+ // `current` is the ONLY state that clears. `behind` and `unmeasured` both
331
+ // refuse, and they keep their own names in the block below — folding them
332
+ // together here would weaken the UNMEASURED refusal that
333
+ // `lib/hook-tree-currency.ts` exists to keep separate from a count.
334
+ current: tree.current && (hooks === null || hooks.state === "current"),
335
+ };
336
+ }
337
+
338
+ /**
339
+ * The block to paste at the top of a report, now carrying both trees.
340
+ *
341
+ * `provenanceBlock` is called rather than re-rendered: the four lines a
342
+ * reader already knows how to read must not drift from the ones this adds to.
343
+ */
344
+ export function sessionProvenanceBlock(p: SessionProvenance): string {
345
+ const lines = [provenanceBlock(p.tree)];
346
+
347
+ if (p.hooks === null) {
348
+ lines.push(
349
+ "Hook tree: not bound — RUNGATE_HOOKS_DIR is unset, so no hook executes out of a " +
350
+ "directory this session could age.",
351
+ );
352
+ return lines.join("\n");
353
+ }
354
+
355
+ if (p.hooks.state === "current") {
356
+ lines.push(`Hook tree: CURRENT — ${p.hooks.detail}`);
357
+ return lines.join("\n");
358
+ }
359
+
360
+ // The state keeps its own word, and the consequence is spelled out rather
361
+ // than left to the reader: the failure this closes is a number reported as
362
+ // if it described main.
363
+ const tag = p.hooks.state === "behind" ? `BEHIND ${p.hooks.behind}` : "UNMEASURED";
364
+ lines.push(
365
+ `Hook tree: ${tag} — ${p.hooks.detail}`,
366
+ ` Any rate, refusal count or ledger row this session produces is UNMEASURED against ` +
367
+ `${p.hooks.base}: it describes the hook tree above, not ${p.hooks.base}. Say UNMEASURED ` +
368
+ `rather than reporting the number.`,
369
+ );
370
+ return lines.join("\n");
371
+ }