Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Scope reporter write-back to the release it was handed (PRD-7667) (#2981)
Andrew Mikofalvy25d2e7a8d293
diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjsindex 3abf8b9ea..bbf35e9a3 100644--- a/.github/scripts/write-back.mjs+++ b/.github/scripts/write-back.mjs@@ -166,6 +166,61 @@ function compareSemver(a, b) {return 0;}+export const DEFAULT_RELEASE_LOOKBACK = 3;++/** `v0.36.0` and `0.36.0` both mean the same release; anything else means none. */+function normalizeVersion(raw) {+ const trimmed = String(raw ?? '').trim().replace(/^v/, '');+ return /^\d+\.\d+\.\d+$/.test(trimmed) ? trimmed : null;+}++/**+ * Decide which shipped versions a given run is allowed to speak about.+ *+ * The release being processed is the ceiling: a fix that lands in a later+ * version has not reached anybody yet, so telling its reporter would be a lie.+ *+ * The floor is deliberately a few releases further back rather than the release+ * itself. A run that never happened — a workflow outage, or simply the stretch+ * before any of this was armed — would otherwise strand those reporters+ * permanently, because the next release only ever considers its own version and+ * nothing ever revisits the gap. Widening the floor is safe because the+ * absent-marker check, not the width of this window, is what prevents a second+ * reply: the window is bounded by "has not been told yet".+ *+ * Without a window every completed fix in history looks eligible, which on a+ * first armed run means messaging the entire back catalogue at once.+ */+export function makeReleaseWindow({+ releaseTag,+ stableTags = [],+ lookback = DEFAULT_RELEASE_LOOKBACK,+}) {+ const release = normalizeVersion(releaseTag);+ if (!release) {+ throw new Error(+ `RELEASE_TAG must be a bare stable tag such as v0.36.0 (got ${JSON.stringify(releaseTag)}). ` ++ 'Refusing to run: with no release to scope against, every shipped fix in history is a candidate.',+ );+ }++ const known = [...new Set(stableTags.map(normalizeVersion).filter(Boolean))].sort(compareSemver);+ const atOrBelow = known.filter((v) => compareSemver(v, release) <= 0);+ // Keep the release plus `lookback` older ones; the entry just below that+ // block is the exclusive floor. Too little history to reach back that far+ // means everything at or below the release stays in.+ const floorIndex = atOrBelow.length - (lookback + 1) - 1;+ const floor = floorIndex >= 0 ? atOrBelow[floorIndex] : null;++ return (version) => {+ const shipped = normalizeVersion(version);+ if (!shipped) return 'unversioned';+ if (compareSemver(shipped, release) > 0) return 'not-yet-shipped';+ if (floor && compareSemver(shipped, floor) <= 0) return 'shipped-earlier';+ return 'in-window';+ };+}+/*** Walk every candidate and decide, for each, whether to reply and where.*@@ -191,9 +246,17 @@ export async function runWriteBack({readChangesetProse,postReply,recordNotification,+ classifyRelease,live = false,log = () => {},}) {+ // No default. A missing window is not "notify about everything", it is a+ // caller that forgot to scope the run, and the difference between those two+ // readings is the entire back catalogue.+ if (typeof classifyRelease !== 'function') {+ throw new Error('runWriteBack requires classifyRelease; see makeReleaseWindow.');+ }+const posted = [];const skipped = [];const skip = (identifier, reason) => skipped.push({ identifier, reason });@@ -228,6 +291,15 @@ export async function runWriteBack({continue;}+ // Scope to the release this run is about. Skips here are the ordinary bulk+ // of a run rather than a fault, so they are recorded per candidate and+ // summarised at the end instead of annotated one line at a time.+ const placement = classifyRelease(gate.version);+ if (placement !== 'in-window') {+ skip(candidate.identifier, placement);+ continue;+ }+if (origins.length === 0) {if (unrepliable.length > 0) {log(@@ -517,6 +589,8 @@ async function main() {log('::notice::write-back: running in dry-run mode (set WRITE_BACK_MODE=live to arm reporter replies).');}+ const releaseTag = process.env.RELEASE_TAG;+const stableTags = realStableTags();const versionFor = (node) =>deriveVersionForFixRefs({@@ -528,10 +602,17 @@ async function main() {log,});+ const classifyRelease = makeReleaseWindow({ releaseTag, stableTags });+ log(+ `::notice::write-back: scoped to ${releaseTag} and the ${DEFAULT_RELEASE_LOOKBACK} stable releases before it; ` ++ 'anything shipped earlier is left alone.',+ );+const result = await runWriteBack({listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {} }),listChildren: (parentId) => paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId } }),versionFor,+ classifyRelease,readChangesetProse: (candidate, ctx) => realReadChangesetProse(candidate, ctx),postReply: realPostReply,recordNotification: async ({ issueId, url, title }) => {diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjsindex 725eec82f..d27c1e7fa 100644--- a/.github/scripts/write-back.test.mjs+++ b/.github/scripts/write-back.test.mjs@@ -2,7 +2,9 @@ import { readFileSync } from 'node:fs';import { describe, expect, test } from 'vitest';import {CANDIDATE_QUERY,+ DEFAULT_RELEASE_LOOKBACK,deriveVersionForFixRefs,+ makeReleaseWindow,notificationMarkerUrl,parseChangeset,runWriteBack,@@ -41,6 +43,9 @@ function harness(overrides = {}) {readChangesetProse: async () => CHANGESET,postReply: async (origin, text) => writes.push({ kind: 'post', origin: origin.url, text }),recordNotification: async (marker) => writes.push({ kind: 'mark', url: marker.url }),+ // Every candidate in these fixtures ships in v0.36.0; the window tests+ // below drive the scoping itself.+ classifyRelease: makeReleaseWindow({ releaseTag: 'v0.36.0', stableTags: STABLE_TAGS }),log: (m) => logs.push(m),...overrides,};@@ -377,3 +382,113 @@ describe('workflow shape', () => {expect(workflow).toContain('LINEAR_API_KEY');});});++describe('release window', () => {+ // A longer history than the lookback, so "outside the window" is reachable.+ const TAGS = ['v0.34.0', 'v0.35.0', 'v0.35.1', 'v0.35.2', 'v0.36.0', 'v0.37.0'];+ const windowFor = (releaseTag, lookback) =>+ makeReleaseWindow({ releaseTag, stableTags: TAGS, lookback });++ test('the release being processed is in window', () => {+ expect(windowFor('v0.36.0')('0.36.0')).toBe('in-window');+ });++ test('a version above the release has not reached anyone yet', () => {+ expect(windowFor('v0.36.0')('0.37.0')).toBe('not-yet-shipped');+ });++ test('the lookback keeps recent releases reachable so a missed run self-heals', () => {+ const classify = windowFor('v0.36.0', 3);+ // v0.36.0 plus the three before it.+ for (const v of ['0.36.0', '0.35.2', '0.35.1', '0.35.0']) {+ expect(classify(v)).toBe('in-window');+ }+ });++ test('anything older than the lookback is left alone', () => {+ expect(windowFor('v0.36.0', 3)('0.34.0')).toBe('shipped-earlier');+ });++ test('a narrower lookback excludes more of the history', () => {+ const classify = windowFor('v0.36.0', 1);+ expect(classify('0.35.2')).toBe('in-window');+ expect(classify('0.35.1')).toBe('shipped-earlier');+ });++ test('a zero lookback degenerates to the exact release and nothing else', () => {+ const classify = windowFor('v0.36.0', 0);+ expect(classify('0.36.0')).toBe('in-window');+ expect(classify('0.35.2')).toBe('shipped-earlier');+ });++ test('too little history to reach back keeps everything at or below the release', () => {+ // Fewer known tags than the lookback wants leaves no floor at all, so the+ // ceiling is the only bound. Pinned because it is a distinct branch from+ // the one every other case here exercises.+ const classify = makeReleaseWindow({ releaseTag: 'v0.36.0', stableTags: ['v0.36.0'] });+ expect(classify('0.36.0')).toBe('in-window');+ expect(classify('0.35.0')).toBe('in-window');+ expect(classify('0.37.0')).toBe('not-yet-shipped');+ });++ test('the v prefix is accepted on both sides', () => {+ expect(windowFor('0.36.0')('v0.36.0')).toBe('in-window');+ });++ test('an underivable version is reported as such rather than silently admitted', () => {+ expect(windowFor('v0.36.0')(null)).toBe('unversioned');+ });++ test('a missing or malformed release tag refuses rather than admitting all of history', () => {+ for (const bad of [undefined, '', ' ', 'v0.36.0-beta.1', 'latest']) {+ expect(() => makeReleaseWindow({ releaseTag: bad, stableTags: TAGS })).toThrow(/RELEASE_TAG/);+ }+ });++ test('the default lookback is three', () => {+ expect(DEFAULT_RELEASE_LOOKBACK).toBe(3);+ });+});++describe('release window applied to a run', () => {+ // The fixture candidate ships in v0.36.0 throughout.+ test('a candidate that shipped before the window is skipped, not replied to', async () => {+ const h = harness({+ live: true,+ classifyRelease: makeReleaseWindow({+ releaseTag: 'v0.41.0',+ stableTags: ['v0.36.0', 'v0.38.0', 'v0.39.0', 'v0.40.0', 'v0.41.0'],+ }),+ });+ const result = await h.run();+ expect(result.skipped).toContainEqual({ identifier: 'PRD-7539', reason: 'shipped-earlier' });+ expect(h.writes).toHaveLength(0);+ });++ test('a candidate whose fix is not in this release yet is skipped, not replied to', async () => {+ const h = harness({+ live: true,+ classifyRelease: makeReleaseWindow({+ releaseTag: 'v0.35.0',+ stableTags: ['v0.35.0', 'v0.36.0'],+ }),+ });+ const result = await h.run();+ expect(result.skipped).toContainEqual({ identifier: 'PRD-7539', reason: 'not-yet-shipped' });+ expect(h.writes).toHaveLength(0);+ });++ test('a candidate inside the window still gets its reply', async () => {+ const h = harness({+ live: true,+ classifyRelease: makeReleaseWindow({ releaseTag: 'v0.36.0', stableTags: STABLE_TAGS }),+ });+ await h.run();+ expect(h.writes.filter((w) => w.kind === 'post')).toHaveLength(1);+ });++ test('runWriteBack refuses to run unscoped', async () => {+ const h = harness({ live: true, classifyRelease: undefined });+ await expect(h.run()).rejects.toThrow(/classifyRelease/);+ });+});