Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Close the report-to-shipped loop: origin link, fan-in gate, reporter write-back (#2967)
Andrew Mikofalvy240e66abf4a3
diff --git a/.github/scripts/write-back-gate.mjs b/.github/scripts/write-back-gate.mjsnew file mode 100644index 000000000..18c8ffe71--- /dev/null+++ b/.github/scripts/write-back-gate.mjs@@ -0,0 +1,339 @@+/**+ * The decisions behind telling a bug reporter their fix shipped: which of a+ * ticket's attachments is a place a human can be replied to, and whether+ * everything that descended from their report has actually gone out.+ *+ * Why this file does no IO at all. The two failure modes that matter here are+ * both silent-and-public: replying in the wrong place, and telling someone a+ * fix is out while part of what they reported is still open. Neither is caught+ * by watching a workflow go green, so the decisions have to be cheap enough to+ * test exhaustively, which means no Linear client, no fetch, no git, no clock.+ * The sibling `write-back.mjs` owns every boundary and imports this.+ *+ * ATTACHMENT CLASSIFICATION. A Linear ticket's attachments are a mixed bag: the+ * report's origin, the PRs and commits that fixed it, uploaded diagnostic+ * bundles, and links to wherever it was discussed. Confusing a fix reference+ * for an origin is how a bot ends up replying to its own pull request, so+ * GitHub pull and commit URLs are classified as fix references and can never+ * become origins no matter what else is missing.+ *+ * THE FAN-IN GATE. A single report routinely fans into several tickets. Telling+ * the reporter "fixed in v0.36.0" while one of those is still open is worse+ * than staying quiet, because it reads as a claim that everything they raised+ * is handled. So the gate blocks on EVERY non-canceled descendant, not only the+ * Bug-labelled ones: on the live tree this was designed against, two of six+ * children carry no labels at all, and one of those is still open. Gating on+ * the label would have made it invisible. Unlabelled descendants are reported+ * separately so the triage gap stays visible rather than being quietly+ * absorbed.+ *+ * Failing safe here means silence, never a false claim.+ */++const GITHUB_ISSUE_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)(?:[/?#].*)?$/i;+const GITHUB_PULL_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:[/?#].*)?$/i;+const GITHUB_COMMIT_RE = /^https?:\/\/(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/commit\/([0-9a-f]{7,40})(?:[/?#].*)?$/i;+// Discord permalinks carry guild/channel[/message]; the channel segment is the+// forum thread's own id, which is what a reply is addressed to.+const DISCORD_THREAD_RE =+ /^https?:\/\/(?:(?:canary|ptb)\.)?discord(?:app)?\.com\/channels\/(\d+|@me)\/(\d+)(?:\/(\d+))?(?:[/?#].*)?$/i;+const SLACK_ARCHIVE_RE = /^https?:\/\/[^/]*\.slack\.com\/archives\//i;+const LINEAR_UPLOAD_RE = /^https?:\/\/uploads\.linear\.app\//i;++const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/;++const RELEASES_URL = 'https://github.com/inkeep/open-knowledge/releases';+// Discord caps a message at 2000 characters. Bounding the quoted prose leaves+// room for the surrounding lines on either channel and keeps a pathological+// changeset from turning the reply into a wall.+const MAX_PROSE_CHARS = 1200;++/**+ * What a single attachment URL is, for write-back purposes.+ *+ * { kind: 'repliable-origin', channel: 'github-issue' | 'discord-thread', ... }+ * { kind: 'unrepliable-origin', channel: 'slack-archive' | 'linear-upload' }+ * { kind: 'fix-reference', channel: 'pull-request' | 'commit' }+ * { kind: 'unknown' }+ *+ * `unrepliable-origin` exists as its own answer rather than collapsing into+ * `unknown` so the caller can say WHY it skipped. A Slack archive link and a+ * diagnostic bundle both name a real report; there is simply nowhere in them to+ * post a reply, and that is worth a warning rather than silence.+ */+export function classifyAttachment(rawUrl) {+ const url = String(rawUrl ?? '').trim();+ if (!url) return { kind: 'unknown', url };++ // Fix references are matched before origins on purpose: a pull request lives+ // on github.com just like an issue does, and reading one as a place to reply+ // would post the notification onto the fix instead of onto the report.+ const pull = GITHUB_PULL_RE.exec(url);+ if (pull) {+ return {+ kind: 'fix-reference',+ channel: 'pull-request',+ url,+ owner: pull[1],+ repo: pull[2],+ number: Number(pull[3]),+ };+ }++ const commit = GITHUB_COMMIT_RE.exec(url);+ if (commit) {+ return {+ kind: 'fix-reference',+ channel: 'commit',+ url,+ owner: commit[1],+ repo: commit[2],+ sha: commit[3].toLowerCase(),+ };+ }++ const issue = GITHUB_ISSUE_RE.exec(url);+ if (issue) {+ return {+ kind: 'repliable-origin',+ channel: 'github-issue',+ url,+ owner: issue[1],+ repo: issue[2],+ number: Number(issue[3]),+ };+ }++ const discord = DISCORD_THREAD_RE.exec(url);+ if (discord) {+ return { kind: 'repliable-origin', channel: 'discord-thread', url, threadId: discord[2] };+ }++ if (SLACK_ARCHIVE_RE.test(url)) {+ return { kind: 'unrepliable-origin', channel: 'slack-archive', url };+ }+ if (LINEAR_UPLOAD_RE.test(url)) {+ return { kind: 'unrepliable-origin', channel: 'linear-upload', url };+ }++ return { kind: 'unknown', url };+}++/**+ * Split a ticket's attachments into the three buckets the write-back needs.+ * Returns { origins, unrepliable, fixReferences } with the classification+ * objects, in attachment order.+ *+ * `fixReferences` keeps pull requests ahead of commits: a pull request resolves+ * to a merge commit whose mirrored copy is what tag containment walks, while a+ * bare commit URL may be one of many on a single ticket. Both shapes occur in+ * practice, so neither is treated as the only one.+ */+export function partitionAttachments(attachmentUrls = []) {+ const origins = [];+ const unrepliable = [];+ const pulls = [];+ const commits = [];++ for (const raw of attachmentUrls) {+ const classified = classifyAttachment(raw);+ if (classified.kind === 'repliable-origin') origins.push(classified);+ else if (classified.kind === 'unrepliable-origin') unrepliable.push(classified);+ else if (classified.kind === 'fix-reference') {+ (classified.channel === 'pull-request' ? pulls : commits).push(classified);+ }+ }++ return { origins, unrepliable, fixReferences: [...pulls, ...commits] };+}++/** Numeric semver ordering. String comparison puts v0.9.0 above v0.36.0. */+export function compareVersions(a, b) {+ const pa = SEMVER_RE.exec(String(a ?? '').trim());+ const pb = SEMVER_RE.exec(String(b ?? '').trim());+ if (!pa) throw new Error(`not a version: '${a}'`);+ if (!pb) throw new Error(`not a version: '${b}'`);+ for (let i = 1; i <= 3; i += 1) {+ const diff = Number(pa[i]) - Number(pb[i]);+ if (diff !== 0) return diff;+ }+ return 0;+}++/** Highest of a non-empty version list, normalized without the leading `v`. */+export function highestVersion(versions) {+ let best = null;+ for (const version of versions) {+ if (best === null || compareVersions(version, best) > 0) best = version;+ }+ return best === null ? null : String(best).trim().replace(/^v/, '');+}++/**+ * Decide whether everything descending from a report has shipped.+ *+ * Inputs:+ * ticket { identifier, stateType, labels? }+ * descendants [ same shape ]+ * resolveVersion(node) -> version string | null (injected; null means+ * "could not be derived", which is a reason to withhold, never+ * a reason to assume it shipped)+ * log injected annotation sink+ *+ * A ticket that has children is the report; its own state tracks triage rather+ * than a ship event, so the decision is made over its descendants. A ticket+ * with no children is evaluated alone, which is the common single-fix case.+ *+ * Three-way per node:+ * shipped completed and a version resolves contributes its version+ * neutral canceled (won't-fix or duplicate) contributes nothing, blocks nothing+ * blocking anything else withholds+ *+ * Returns { decision, version, coverage, blocking, unresolved, neutral,+ * unlabelledDescendants }. `unresolved` is the subset of `blocking` that is+ * completed but whose version could not be derived: routine "still open" and+ * "we could not work out where this went" deserve different annotations, and+ * the second one means something is wrong with the fix-reference chain.+ */+export function evaluateFanIn({ ticket, descendants = [], resolveVersion, log = () => {} }) {+ if (!ticket?.identifier) throw new Error('evaluateFanIn needs a ticket with an identifier');+ if (typeof resolveVersion !== 'function') throw new Error('evaluateFanIn needs a resolveVersion function');++ const considered = descendants.length > 0 ? descendants : [ticket];++ const coverage = [];+ const versions = [];+ const blocking = [];+ const unresolved = [];+ const neutral = [];+ const unlabelledDescendants = [];++ for (const node of considered) {+ if (descendants.length > 0 && (node.labels ?? []).length === 0) {+ unlabelledDescendants.push(node.identifier);+ }++ if (node.stateType === 'canceled') {+ neutral.push(node.identifier);+ continue;+ }+ if (node.stateType !== 'completed') {+ blocking.push(node.identifier);+ continue;+ }++ const version = resolveVersion(node);+ if (!version) {+ // Completed but unlocatable. Refusing here is the whole point of the+ // gate: naming a version we could not derive is the one outcome worse+ // than saying nothing.+ blocking.push(node.identifier);+ unresolved.push(node.identifier);+ continue;+ }+ coverage.push(node.identifier);+ versions.push(version);+ }++ coverage.sort();+ blocking.sort();+ unresolved.sort();++ if (unlabelledDescendants.length > 0) {+ log(+ `::notice::write-back: ${ticket.identifier} has descendants with no labels (${unlabelledDescendants.join(', ')}); ` ++ 'they are gated on anyway, but the triage gap is worth closing.',+ );+ }++ if (blocking.length > 0 || coverage.length === 0) {+ const reason =+ blocking.length > 0+ ? `outstanding: ${blocking.join(', ')}`+ : 'nothing descending from it has shipped';+ log(`::notice::write-back: withholding on ${ticket.identifier} (${reason}).`);+ return {+ decision: 'withhold',+ version: null,+ coverage,+ blocking,+ unresolved,+ neutral,+ unlabelledDescendants,+ };+ }++ return {+ decision: 'notify',+ version: highestVersion(versions),+ coverage,+ blocking,+ unresolved,+ neutral,+ unlabelledDescendants,+ };+}++/**+ * The reply a reporter actually reads.+ *+ * The signature is the redaction mechanism. Everything a reporter should never+ * see lives on the Linear ticket: its internal title, its assignee, the+ * customer it was raised for, notes about work that has not shipped. None of+ * that is a parameter here, so no amount of downstream carelessness can leak+ * it. What can reach the reply is the changeset prose, which is written for the+ * public release notes and is already published, plus the derived version and+ * the ticket identifiers the reporter's own report fanned into. Widening these+ * parameters is the one change to this file that needs a second look.+ *+ * The coverage line is not decoration. A report that fanned into three tickets+ * gets one reply, and without the list the reporter has no way to tell whether+ * the other two were handled or quietly dropped.+ *+ * Returns the reply text, or null when there is nothing truthful to say. An+ * empty changeset is the one case: a blank or version-only reply reads as a+ * claim with no content behind it, so the caller warns and posts nothing.+ */+export function composeReply({ changeset = {}, version, originChannel, coverage = [] }) {+ const normalizedVersion = String(version ?? '')+ .trim()+ .replace(/^v/, '');+ if (!SEMVER_RE.test(normalizedVersion)) {+ throw new Error(`composeReply needs a derived version, got '${version}'`);+ }++ const body = String(changeset.body ?? '').trim();+ const title = String(changeset.title ?? '').trim();+ const prose = body || title;+ if (!prose) return null;++ const trimmedProse =+ prose.length > MAX_PROSE_CHARS ? `${prose.slice(0, MAX_PROSE_CHARS).trimEnd()}...` : prose;++ const lines = [+ `This shipped in Open Knowledge v${normalizedVersion}. Thanks for the report.`,+ '',+ trimmedProse,+ ];++ if (coverage.length > 0) {+ lines.push('', `Covers ${[...coverage].sort().join(', ')}.`);+ }++ lines.push('', updateInstruction(originChannel, normalizedVersion));++ return lines.join('\n');+}++/**+ * Both channels render markdown, so the difference is the link form: GitHub+ * renders an inline link, while a bare URL on Discord expands into an embed+ * card unless it is wrapped in angle brackets.+ */+function updateInstruction(originChannel, version) {+ const upgrade = `\`npm install -g @inkeep/open-knowledge@${version}\``;+ if (originChannel === 'discord-thread') {+ return `To pick it up, run ${upgrade}, or download the latest desktop build from <${RELEASES_URL}>.`;+ }+ return `To pick it up, run ${upgrade}, or download the latest desktop build from [the releases page](${RELEASES_URL}).`;+}diff --git a/.github/scripts/write-back-gate.test.mjs b/.github/scripts/write-back-gate.test.mjsnew file mode 100644index 000000000..be6bd95e7--- /dev/null+++ b/.github/scripts/write-back-gate.test.mjs@@ -0,0 +1,367 @@+import { describe, expect, test } from 'vitest';+import {+ classifyAttachment,+ compareVersions,+ composeReply,+ evaluateFanIn,+ highestVersion,+ partitionAttachments,+} from './write-back-gate.mjs';++// Attachment shapes taken off live tickets rather than invented: PRD-7539 (a+// fix PR plus a GitHub issue origin), PRD-7394 (nothing but an uploaded+// diagnostic bundle), PRD-7399 (seven commit URLs and no PR at all), and+// PRD-7490 (a fix PR, a Discord thread, and a Slack archive link).+const GH_ISSUE = 'https://github.com/inkeep/open-knowledge/issues/769';+const GH_PULL = 'https://github.com/inkeep/agents-private/pull/2844';+const GH_COMMIT = 'https://github.com/inkeep/agents-private/commit/da71f0c698ccaac11da915169ca6c7d585d5eb97';+const DISCORD_THREAD = 'https://discord.com/channels/1234567890/9876543210/1122334455';+const SLACK_ARCHIVE = 'https://inkeep.slack.com/archives/C016VCYCL74/p1727122965001469';+const LINEAR_UPLOAD = 'https://uploads.linear.app/abc/def/diagnostics.zip';++describe('attachment classification', () => {+ test('a GitHub issue is a repliable origin', () => {+ const c = classifyAttachment(GH_ISSUE);+ expect(c.kind).toBe('repliable-origin');+ expect(c.channel).toBe('github-issue');+ expect(c).toMatchObject({ owner: 'inkeep', repo: 'open-knowledge', number: 769 });+ });++ test('a Discord thread permalink is a repliable origin carrying the thread id', () => {+ const c = classifyAttachment(DISCORD_THREAD);+ expect(c.kind).toBe('repliable-origin');+ expect(c.channel).toBe('discord-thread');+ expect(c.threadId).toBe('9876543210');+ });++ test('a Discord permalink with no message segment still yields the thread', () => {+ const c = classifyAttachment('https://discord.com/channels/1234567890/9876543210');+ expect(c.channel).toBe('discord-thread');+ expect(c.threadId).toBe('9876543210');+ });++ test('a Slack archive link is an origin with nowhere to reply, so the caller can skip and warn', () => {+ const c = classifyAttachment(SLACK_ARCHIVE);+ expect(c.kind).toBe('unrepliable-origin');+ expect(c.channel).toBe('slack-archive');+ });++ test('a Linear diagnostic bundle is an origin with nowhere to reply', () => {+ const c = classifyAttachment(LINEAR_UPLOAD);+ expect(c.kind).toBe('unrepliable-origin');+ expect(c.channel).toBe('linear-upload');+ });++ test('a GitHub pull request is a fix reference and never an origin', () => {+ const c = classifyAttachment(GH_PULL);+ expect(c.kind).toBe('fix-reference');+ expect(c.channel).toBe('pull-request');+ expect(c.number).toBe(2844);+ });++ test('a GitHub commit is a fix reference and never an origin', () => {+ const c = classifyAttachment(GH_COMMIT);+ expect(c.kind).toBe('fix-reference');+ expect(c.channel).toBe('commit');+ expect(c.sha).toBe('da71f0c698ccaac11da915169ca6c7d585d5eb97');+ });++ test('an unrecognized link is unknown rather than guessed at', () => {+ expect(classifyAttachment('https://example.com/whatever').kind).toBe('unknown');+ expect(classifyAttachment('').kind).toBe('unknown');+ expect(classifyAttachment(null).kind).toBe('unknown');+ });++ test('a ticket carrying only fix-side links produces no origin at all', () => {+ const { origins, fixReferences } = partitionAttachments([GH_PULL, GH_COMMIT]);+ expect(origins).toEqual([]);+ expect(fixReferences.map((f) => f.channel)).toEqual(['pull-request', 'commit']);+ });++ test('a ticket carrying only commit attachments still yields a usable fix reference', () => {+ const commits = Array.from(+ { length: 7 },+ (_, i) => `https://github.com/inkeep/agents-private/commit/${String(i + 1).repeat(40)}`,+ );+ const { fixReferences } = partitionAttachments(commits);+ expect(fixReferences.length).toBe(7);+ expect(fixReferences[0].channel).toBe('commit');+ });++ test('pull requests sort ahead of commits so the merge-commit hop is preferred', () => {+ const { fixReferences } = partitionAttachments([GH_COMMIT, GH_PULL]);+ expect(fixReferences.map((f) => f.channel)).toEqual(['pull-request', 'commit']);+ });++ test('a mixed ticket separates the repliable origin from the unrepliable one', () => {+ const { origins, unrepliable, fixReferences } = partitionAttachments([+ GH_PULL,+ DISCORD_THREAD,+ SLACK_ARCHIVE,+ ]);+ expect(origins.map((o) => o.channel)).toEqual(['discord-thread']);+ expect(unrepliable.map((o) => o.channel)).toEqual(['slack-archive']);+ expect(fixReferences.map((f) => f.channel)).toEqual(['pull-request']);+ });+});++describe('version ordering', () => {+ test('versions compare numerically, not as strings', () => {+ expect(compareVersions('v0.36.0', 'v0.35.2')).toBeGreaterThan(0);+ expect(compareVersions('0.9.0', '0.36.0')).toBeLessThan(0);+ expect(compareVersions('v1.0.0', '1.0.0')).toBe(0);+ });++ test('the highest of a set is returned without its leading v', () => {+ expect(highestVersion(['v0.35.2', 'v0.36.0', 'v0.35.6'])).toBe('0.36.0');+ });++ test('a value that is not a version throws rather than sorting arbitrarily', () => {+ expect(() => compareVersions('latest', '1.0.0')).toThrow(/not a version/);+ });+});++describe('fan-in gate', () => {+ // A map-driven fake keyed by identifier: absent means "no version could be+ // derived", which the gate must treat as a reason to withhold.+ const versionsFrom = (map) => (node) => map[node.identifier] ?? null;+ const node = (identifier, stateType, labels = ['Bug']) => ({ identifier, stateType, labels });++ const evaluate = (overrides) => {+ const logs = [];+ const result = evaluateFanIn({ log: (m) => logs.push(m), ...overrides });+ return { ...result, logs };+ };++ test('every descendant completed and resolvable notifies with the coverage set', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started', ['Bug', 'ok:intake']),+ descendants: [node('PRD-7398', 'completed'), node('PRD-7403', 'completed', [])],+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.35.2', 'PRD-7403': 'v0.36.0' }),+ });+ expect(r.decision).toBe('notify');+ expect(r.coverage).toEqual(['PRD-7398', 'PRD-7403']);+ });++ test('the selected version is the highest contributor by numeric semver', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started'),+ descendants: [node('PRD-7398', 'completed'), node('PRD-7403', 'completed')],+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0', 'PRD-7403': 'v0.35.2' }),+ });+ expect(r.version).toBe('0.36.0');+ });++ test('an outstanding descendant withholds and is named', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started'),+ descendants: [node('PRD-7398', 'completed'), node('PRD-7400', 'unstarted')],+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0' }),+ });+ expect(r.decision).toBe('withhold');+ expect(r.blocking).toEqual(['PRD-7400']);+ expect(r.logs.some((m) => m.includes('PRD-7400'))).toBe(true);+ });++ test('a ticket with no children is evaluated alone rather than failing', () => {+ const r = evaluate({+ ticket: node('PRD-7539', 'completed', ['Bug', 'ok:platform']),+ descendants: [],+ resolveVersion: versionsFrom({ 'PRD-7539': 'v0.36.0' }),+ });+ expect(r.decision).toBe('notify');+ expect(r.coverage).toEqual(['PRD-7539']);+ expect(r.version).toBe('0.36.0');+ });++ test('a canceled descendant neither blocks nor contributes', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started'),+ descendants: [node('PRD-7398', 'completed'), node('PRD-7402', 'canceled')],+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0' }),+ });+ expect(r.decision).toBe('notify');+ expect(r.coverage).toEqual(['PRD-7398']);+ expect(r.neutral).toEqual(['PRD-7402']);+ });++ test('an open unlabelled descendant withholds, which gating on the Bug label would have missed', () => {+ // The live PRD-7394 tree: six children, two of them carrying no labels at+ // all, and one of those two still open.+ const r = evaluate({+ ticket: node('PRD-7394', 'started', ['Bug', 'ok:intake']),+ descendants: [+ node('PRD-7398', 'completed'),+ node('PRD-7399', 'completed'),+ node('PRD-7400', 'completed'),+ node('PRD-7401', 'unstarted', []),+ node('PRD-7402', 'completed'),+ node('PRD-7403', 'completed', []),+ ],+ resolveVersion: () => 'v0.36.0',+ });+ expect(r.decision).toBe('withhold');+ expect(r.blocking).toEqual(['PRD-7401']);+ });++ test('unlabelled descendants are listed so the triage gap is observable rather than silent', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started'),+ descendants: [node('PRD-7401', 'unstarted', []), node('PRD-7403', 'completed', [])],+ resolveVersion: () => 'v0.36.0',+ });+ expect(r.unlabelledDescendants).toEqual(['PRD-7401', 'PRD-7403']);+ expect(r.logs.some((m) => m.startsWith('::notice::') && m.includes('no labels'))).toBe(true);+ });++ test('a completed descendant whose version cannot be derived withholds rather than assuming it shipped', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started'),+ descendants: [node('PRD-7398', 'completed'), node('PRD-7403', 'completed')],+ resolveVersion: versionsFrom({ 'PRD-7398': 'v0.36.0' }),+ });+ expect(r.decision).toBe('withhold');+ expect(r.blocking).toEqual(['PRD-7403']);+ // Distinguished from a routine "still open" so the caller can annotate a+ // broken fix-reference chain differently from ordinary in-progress work.+ expect(r.unresolved).toEqual(['PRD-7403']);+ });++ test('an open descendant is blocking but not reported as unresolvable', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started'),+ descendants: [node('PRD-7400', 'unstarted')],+ resolveVersion: () => 'v0.36.0',+ });+ expect(r.blocking).toEqual(['PRD-7400']);+ expect(r.unresolved).toEqual([]);+ });++ test('a tree whose only descendants are canceled withholds rather than notifying about nothing', () => {+ const r = evaluate({+ ticket: node('PRD-7394', 'started'),+ descendants: [node('PRD-7402', 'canceled')],+ resolveVersion: () => 'v0.36.0',+ });+ expect(r.decision).toBe('withhold');+ expect(r.coverage).toEqual([]);+ });++ test('a missing ticket or resolver is a wiring error and throws rather than deciding', () => {+ expect(() => evaluateFanIn({ ticket: null, resolveVersion: () => null })).toThrow(/identifier/);+ expect(() => evaluateFanIn({ ticket: { identifier: 'PRD-1' } })).toThrow(/resolveVersion/);+ });+});++describe('reply composition', () => {+ const CHANGESET = {+ title: 'Honor backslash escapes in the markdown promoters',+ body: 'Typing `\\==not a highlight\\==` now stays literal instead of turning into a highlight.',+ };++ const compose = (overrides = {}) =>+ composeReply({ changeset: CHANGESET, version: 'v0.36.0', originChannel: 'github-issue', ...overrides });++ test('the reply names the version', () => {+ expect(compose()).toContain('v0.36.0');+ });++ test('the reply carries the changeset prose', () => {+ expect(compose()).toContain('stays literal instead of turning into a highlight');+ });++ test('the reply lists every contributing ticket in sorted order', () => {+ const text = compose({ coverage: ['PRD-7403', 'PRD-7398', 'PRD-7400'] });+ expect(text).toContain('Covers PRD-7398, PRD-7400, PRD-7403.');+ });++ test('a single-ticket report still gets its coverage line', () => {+ expect(compose({ coverage: ['PRD-7539'] })).toContain('Covers PRD-7539.');+ });++ test('the update instruction is channel-appropriate', () => {+ const gh = compose({ originChannel: 'github-issue' });+ const discord = compose({ originChannel: 'discord-thread' });+ expect(gh).toContain('[the releases page](https://github.com/inkeep/open-knowledge/releases)');+ // Bare on Discord it would expand into an embed card; angle brackets suppress that.+ expect(discord).toContain('<https://github.com/inkeep/open-knowledge/releases>');+ for (const text of [gh, discord]) {+ expect(text).toContain('npm install -g @inkeep/[email protected]');+ }+ });++ test('an empty changeset body falls back to the changeset title', () => {+ const text = compose({ changeset: { title: 'Fix the thing', body: ' ' } });+ expect(text).toContain('Fix the thing');+ });++ test('an empty body and title refuses to compose rather than emitting a blank reply', () => {+ expect(compose({ changeset: { title: '', body: '' } })).toBeNull();+ expect(compose({ changeset: {} })).toBeNull();+ });++ test('a missing version throws rather than composing a reply that names nothing', () => {+ expect(() => compose({ version: null })).toThrow(/derived version/);+ expect(() => compose({ version: 'latest' })).toThrow(/derived version/);+ });++ test('pathological changeset prose is bounded so the reply fits a Discord message', () => {+ const text = compose({ changeset: { title: 't', body: 'x'.repeat(5000) }, coverage: ['PRD-1'] });+ expect(text.length).toBeLessThan(2000);+ expect(text).toContain('...');+ });++ test('no internal ticket detail reaches the composed reply', () => {+ // An adversarial candidate: every field a reporter must never see is+ // populated with a recognizable value. The composer's parameter list is+ // the mechanism, so the assertion is that none of it can be threaded in.+ const candidate = {+ identifier: 'PRD-7539',+ title: 'INTERNAL escalation for Contoso, blocked on unreleased auth rewrite',+ assigneeName: 'Dana Internal',+ customerName: 'Contoso Corp',+ unreleasedWorkNote: 'depends on the unshipped v0.40 auth rewrite',+ changeset: CHANGESET,+ version: 'v0.36.0',+ coverage: ['PRD-7539'],+ originChannel: 'github-issue',+ };++ const text = composeReply({+ changeset: candidate.changeset,+ version: candidate.version,+ originChannel: candidate.originChannel,+ coverage: candidate.coverage,+ });++ for (const secret of [+ candidate.title,+ candidate.assigneeName,+ candidate.customerName,+ candidate.unreleasedWorkNote,+ 'INTERNAL',+ 'Contoso',+ 'Dana',+ 'unreleased',+ 'unshipped',+ ]) {+ expect(text).not.toContain(secret);+ }+ });++ test('the composer accepts nothing beyond the changeset, the version, the channel, and the coverage', () => {+ // A regression pin on the redaction mechanism itself: if a future change+ // widens the parameter object, this states the intended surface out loud.+ expect(composeReply.length).toBe(1);+ const text = composeReply({+ changeset: CHANGESET,+ version: '0.36.0',+ originChannel: 'github-issue',+ coverage: ['PRD-7539'],+ title: 'INTERNAL leak attempt',+ assigneeName: 'Dana Internal',+ });+ expect(text).not.toContain('INTERNAL');+ expect(text).not.toContain('Dana');+ });+});diff --git a/.github/scripts/write-back.mjs b/.github/scripts/write-back.mjsnew file mode 100644index 000000000..3abf8b9ea--- /dev/null+++ b/.github/scripts/write-back.mjs@@ -0,0 +1,562 @@+#!/usr/bin/env node+/**+ * Tell a bug reporter, once, that the fix they reported has shipped.+ *+ * Why this enumerates tickets rather than release commits. Every off-the-shelf+ * release notifier walks the commits in a release, follows each to its pull+ * request, and reads closing keywords. That returns nothing here: the commits+ * in this repo arrive through the Copybara mirror and have no pull requests in+ * the repo the release tags live in. So the walk starts from the other end. Ask+ * Linear which bug tickets are done, and for each one work forward to the+ * version it shipped in through tag containment, which the mirror does not+ * break.+ *+ * Why the version is never read from Linear. `linear-release.yml` stamps+ * releases onto tickets, and it runs off the same dispatch this does. Reading+ * its output would be a race with an outcome nobody would ever notice: the+ * reporter is simply told the wrong version. Tag containment depends on nothing+ * but git, so the two workflows cannot interfere.+ *+ * Why dry run is the default, and why the credential alone does not arm it.+ * Everything downstream of this posts in public under the project's name. An+ * operator wiring up a Linear key for the back-link half should not thereby+ * start replying to strangers, so live posting needs a second, explicit opt-in+ * that does nothing else. Arming steps are in RELEASES.md.+ *+ * Usage:+ * RELEASE_TAG=v0.36.0 node .github/scripts/write-back.mjs+ *+ * Must run inside a full clone (`fetch-depth: 0`, `fetch-tags: true`) — the+ * containment walk needs every stable tag and full history.+ *+ * Fail-loud contract: "nothing to notify about" is a real ANSWER and exits 0.+ * A missing credential is an answer too. Any infra error (Linear unreachable, a+ * git failure, a malformed GraphQL response) throws and exits non-zero rather+ * than being folded into silence, because a caller cannot tell a quiet run from+ * a broken one and would never look again.+ */+import { execFileSync, spawnSync } from 'node:child_process';+import { pathToFileURL } from 'node:url';+import {+ parseFixRef,+ resolvePrivateSha,+ resolveShippedVersion,+} from './resolve-shipped-version.mjs';+import { composeReply, evaluateFanIn, partitionAttachments } from './write-back-gate.mjs';++const LINEAR_GRAPHQL_URL = 'https://api.linear.app/graphql';+const RELEASES_TAG_BASE = 'https://github.com/inkeep/open-knowledge/releases/tag';+const DEFAULT_PRIVATE_REPO = 'inkeep/agents-private';+const FULL_SHA_RE = /^[0-9a-f]{40}$/i;+const STABLE_TAG_RE = /^v\d+\.\d+\.\d+$/;+const PAGE_SIZE = 50;++/**+ * The candidate enumeration.+ *+ * `labels: { name: { eq: "Bug" } }` matches when ANY of the ticket's labels is+ * Bug, which is the intent: a real ticket looks like ["Bug", "ok:platform"].+ * The sibling form `labels: { every: { name: { eq: "Bug" } } }` reads almost+ * identically and would silently drop every multi-labelled ticket, which is to+ * say nearly all of them. The colocated test pins that this query never uses+ * `every`.+ *+ * "Not yet notified" is deliberately absent from the filter. Linear's filter+ * language has no negative-existence predicate over attachments, and expressing+ * it as a positive one would invert the meaning; the check runs over the+ * attachments this query already returns.+ */+export const CANDIDATE_QUERY = `+ query WriteBackCandidates($after: String) {+ issues(+ first: ${PAGE_SIZE}+ after: $after+ filter: { state: { type: { eq: "completed" } }, labels: { name: { eq: "Bug" } } }+ ) {+ pageInfo { hasNextPage endCursor }+ nodes {+ id+ identifier+ state { type }+ labels { nodes { name } }+ attachments { nodes { url } }+ }+ }+ }+`;++export const CHILDREN_QUERY = `+ query WriteBackChildren($parentId: ID!, $after: String) {+ issues(first: ${PAGE_SIZE}, after: $after, filter: { parent: { id: { eq: $parentId } } }) {+ pageInfo { hasNextPage endCursor }+ nodes {+ id+ identifier+ state { type }+ labels { nodes { name } }+ attachments { nodes { url } }+ }+ }+ }+`;++/**+ * The URL that records "this origin has been told about this version".+ *+ * Linear treats an attachment URL as an idempotent key against the same issue,+ * so making this deterministic in (origin, version) buys idempotency with no+ * read-modify-write and no lock: a second run computes the same URL, finds it+ * already on the ticket, and posts nothing. It points at the real release page+ * so a human who clicks it lands somewhere useful.+ */+export function notificationMarkerUrl({ version, originUrl }) {+ const v = String(version ?? '')+ .trim()+ .replace(/^v/, '');+ if (!v) throw new Error('notificationMarkerUrl needs a version');+ if (!String(originUrl ?? '').trim()) throw new Error('notificationMarkerUrl needs an origin url');+ return `${RELEASES_TAG_BASE}/v${v}?notified=${encodeURIComponent(originUrl)}`;+}++/**+ * The version a ticket's fix is installable in, or null if it is not out yet.+ *+ * Across several fix references the answer is the HIGHEST of their individual+ * first-containing tags: the reporter needs a build that contains all of them,+ * so the last one to land sets the floor. (Within a single reference,+ * `resolveShippedVersion` takes the LOWEST across the mirror's copies of that+ * one commit, which is the opposite question and the opposite answer: a point+ * release that carried the fix earlier is the one to name.)+ *+ * Any reference that has not shipped makes the whole answer null. Part of a fix+ * being out is not the fix being out.+ */+export function deriveVersionForFixRefs({+ fixReferences = [],+ stableTags,+ findMirroredCommits,+ contains,+ resolvePrMergeSha,+ defaultRepo = DEFAULT_PRIVATE_REPO,+ log = () => {},+}) {+ const usable = fixReferences.filter((ref) => ref.channel !== 'commit' || FULL_SHA_RE.test(ref.sha ?? ''));+ if (usable.length === 0) return null;++ let highest = null;+ for (const ref of usable) {+ const parsed = parseFixRef(ref.channel === 'commit' ? ref.sha : ref.url, { defaultRepo });+ const privateSha = resolvePrivateSha(parsed, { resolvePrMergeSha });+ const result = resolveShippedVersion({ privateSha, stableTags, findMirroredCommits, contains });+ if (!result.shipped) {+ log(`::notice::write-back: ${ref.url} has not reached a stable release yet (${result.reason}).`);+ return null;+ }+ if (highest === null || compareSemver(result.version, highest) > 0) highest = result.version;+ }+ return highest;+}++function compareSemver(a, b) {+ const pa = a.split('.').map(Number);+ const pb = b.split('.').map(Number);+ for (let i = 0; i < 3; i += 1) {+ if ((pa[i] ?? 0) !== (pb[i] ?? 0)) return (pa[i] ?? 0) - (pb[i] ?? 0);+ }+ return 0;+}++/**+ * Walk every candidate and decide, for each, whether to reply and where.+ *+ * Boundaries are injected so the whole decision path is testable with no Linear+ * account, no git repo, and no network:+ * listCandidates() -> [candidate]+ * listChildren(issueId) -> [node]+ * versionFor(node) -> version | null (tag containment)+ * readChangesetProse(node) -> { title, body } | null+ * postReply(origin, text) -> void+ * recordNotification(marker) -> void+ *+ * `live` false is the default and performs zero writes of any kind.+ *+ * Returns { posted, skipped, dryRun } where `skipped` carries a reason per+ * candidate, so a run that did nothing can be read as either "correctly quiet"+ * or "quietly broken".+ */+export async function runWriteBack({+ listCandidates,+ listChildren,+ versionFor,+ readChangesetProse,+ postReply,+ recordNotification,+ live = false,+ log = () => {},+}) {+ const posted = [];+ const skipped = [];+ const skip = (identifier, reason) => skipped.push({ identifier, reason });++ for (const candidate of await listCandidates()) {+ const { origins, unrepliable, fixReferences } = partitionAttachments(candidate.attachmentUrls ?? []);+ const children = await listChildren(candidate.id);++ // The version for every node in the tree is resolved up front so the gate+ // itself stays synchronous and pure.+ const considered = children.length > 0 ? children : [candidate];+ const versions = new Map();+ for (const node of considered) {+ versions.set(node.identifier, await versionFor(node));+ }++ const gate = evaluateFanIn({+ ticket: candidate,+ descendants: children,+ resolveVersion: (node) => versions.get(node.identifier) ?? null,+ log,+ });++ if (gate.decision !== 'notify') {+ if (gate.unresolved.length > 0) {+ log(+ `::warning::write-back: ${candidate.identifier} is done but no stable release could be derived for ` ++ `${gate.unresolved.join(', ')}; posting nothing. Check the fix-reference attachments on those tickets.`,+ );+ }+ skip(candidate.identifier, gate.unresolved.length > 0 ? 'version-underivable' : 'fan-in-withheld');+ continue;+ }++ if (origins.length === 0) {+ if (unrepliable.length > 0) {+ log(+ `::warning::write-back: ${candidate.identifier} shipped in v${gate.version} but its only origin ` ++ `(${unrepliable.map((u) => u.channel).join(', ')}) has nowhere to post a reply; posting nothing.`,+ );+ skip(candidate.identifier, 'origin-unrepliable');+ } else {+ // Not every fix has a reporter. This is the ordinary case, not a fault.+ skip(candidate.identifier, 'no-origin');+ }+ continue;+ }++ for (const origin of origins) {+ const marker = notificationMarkerUrl({ version: gate.version, originUrl: origin.url });+ if ((candidate.attachmentUrls ?? []).includes(marker)) {+ skip(candidate.identifier, 'already-notified');+ continue;+ }++ const changeset = await readChangesetProse(candidate, { fixReferences });+ const text =+ changeset === null+ ? null+ : composeReply({+ changeset,+ version: gate.version,+ originChannel: origin.channel,+ coverage: gate.coverage,+ });++ if (!text) {+ log(+ `::warning::write-back: ${candidate.identifier} shipped in v${gate.version} but has no changeset prose ` ++ 'to quote; posting nothing rather than a bare version.',+ );+ skip(candidate.identifier, 'no-prose');+ continue;+ }++ if (!live) {+ log(+ `::notice::write-back: [dry run] would reply to ${origin.url} for ${candidate.identifier} ` ++ `(v${gate.version}, covers ${gate.coverage.join(', ')}).`,+ );+ posted.push({ identifier: candidate.identifier, origin: origin.url, version: gate.version, dryRun: true });+ continue;+ }++ // Mark before posting, not after. The contract is at-most-once, and the+ // two failure windows are not symmetric: a crash between post and mark+ // re-sends a reply the reporter already read, while a crash between mark+ // and post just leaves them uninformed, which is the same state they were+ // in a moment earlier and which a human can still fix by hand.+ await recordNotification({+ issueId: candidate.id,+ url: marker,+ title: `Reporter notified: v${gate.version}`,+ });+ // The window between these two is the one state an operator cannot infer+ // from the failure alone: marked, so no later run will retry, but never+ // actually delivered. Name it here so it is readable from the job log+ // rather than only from a Linear lookup.+ log(+ `::debug::write-back: marker written for ${origin.url} (${candidate.identifier}); posting reply next.`,+ );+ await postReply(origin, text);+ log(`::notice::write-back: replied to ${origin.url} for ${candidate.identifier} (v${gate.version}).`);+ posted.push({ identifier: candidate.identifier, origin: origin.url, version: gate.version, dryRun: false });+ }+ }++ return { posted, skipped, dryRun: !live };+}++// --- workflow-runtime wiring (real Linear / git / gh / Discord boundary) ---++async function linearGraphql({ apiKey, query, variables }) {+ const res = await fetch(LINEAR_GRAPHQL_URL, {+ method: 'POST',+ headers: { 'content-type': 'application/json', authorization: apiKey },+ body: JSON.stringify({ query, variables }),+ });+ if (!res.ok) {+ throw new Error(`Linear GraphQL returned HTTP ${res.status}: ${(await res.text()).slice(0, 400)}`);+ }+ const payload = await res.json();+ if (payload.errors?.length) {+ throw new Error(`Linear GraphQL error: ${payload.errors.map((e) => e.message).join('; ')}`);+ }+ return payload.data;+}++function toNode(raw) {+ return {+ id: raw.id,+ identifier: raw.identifier,+ stateType: raw.state?.type ?? 'unknown',+ labels: (raw.labels?.nodes ?? []).map((l) => l.name),+ attachmentUrls: (raw.attachments?.nodes ?? []).map((a) => a.url),+ };+}++async function paginate({ apiKey, query, variables }) {+ const collected = [];+ let after = null;+ do {+ const data = await linearGraphql({ apiKey, query, variables: { ...variables, after } });+ const page = data?.issues;+ if (!page) throw new Error('Linear returned no issues connection; refusing to treat that as an empty result.');+ collected.push(...page.nodes.map(toNode));+ after = page.pageInfo?.hasNextPage ? page.pageInfo.endCursor : null;+ } while (after);+ return collected;+}++function runGit(args) {+ const res = spawnSync('git', args, { encoding: 'utf8' });+ if (res.status !== 0) {+ throw new Error(`git ${args.join(' ')} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`);+ }+ return String(res.stdout || '');+}++function realStableTags() {+ return runGit(['tag', '--list', 'v*', '--sort=version:refname'])+ .split('\n')+ .map((t) => t.trim())+ .filter((t) => STABLE_TAG_RE.test(t));+}++const REC_SEP = '\x1e';+const UNIT_SEP = '\x1f';++function realFindMirroredCommits(privateSha) {+ const out = runGit([+ 'log',+ '--all',+ '--fixed-strings',+ `--grep=GitOrigin-RevId: ${privateSha}`,+ `--format=%H${UNIT_SEP}%B${REC_SEP}`,+ ]);+ const commits = [];+ for (const record of out.split(REC_SEP)) {+ const trimmed = record.replace(/^\n+/, '');+ if (!trimmed.trim()) continue;+ const sep = trimmed.indexOf(UNIT_SEP);+ if (sep === -1) continue;+ commits.push({ sha: trimmed.slice(0, sep).trim(), message: trimmed.slice(sep + 1) });+ }+ return commits;+}++function realContains(tag, sha) {+ const res = spawnSync('git', ['merge-base', '--is-ancestor', sha, `${tag}^{commit}`], { encoding: 'utf8' });+ if (res.status === 0) return true;+ if (res.status === 1) return false;+ throw new Error(+ `git merge-base --is-ancestor ${sha} ${tag} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,+ );+}++function gh(args) {+ return execFileSync('gh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });+}++function realResolvePrMergeSha({ owner, repo, number }) {+ let out;+ try {+ out = gh(['api', `repos/${owner}/${repo}/pulls/${number}`, '--jq', '.merged_at,.merge_commit_sha']);+ } catch (err) {+ throw new Error(+ `gh api repos/${owner}/${repo}/pulls/${number} failed: ${String(err?.stderr || err?.message || '').trim()}`,+ );+ }+ const [mergedAt, sha] = out.split('\n').map((s) => s.trim());+ if (!mergedAt || mergedAt === 'null') {+ throw new Error(`${owner}/${repo}#${number} is not merged; there is no fix commit to resolve.`);+ }+ if (!FULL_SHA_RE.test(sha || '')) {+ throw new Error(`${owner}/${repo}#${number} has no usable merge_commit_sha (got '${sha}').`);+ }+ return sha.toLowerCase();+}++/**+ * The prose quoted back to the reporter is the changeset the fix shipped with,+ * which is already public release-notes copy. It is read from the fix pull+ * request's own `.changeset/*.md` addition rather than from the ticket, so no+ * internal field is ever in reach.+ */+function realReadChangesetProse(_candidate, { fixReferences }) {+ const pull = fixReferences.find((ref) => ref.channel === 'pull-request');+ if (!pull) return null;++ let names;+ try {+ names = gh([+ 'api',+ `repos/${pull.owner}/${pull.repo}/pulls/${pull.number}/files`,+ '--paginate',+ '--jq',+ '.[].filename',+ ]);+ } catch (err) {+ throw new Error(`gh api pulls/${pull.number}/files failed: ${String(err?.stderr || err?.message || '').trim()}`);+ }++ const changesetPath = names+ .split('\n')+ .map((s) => s.trim())+ .find((name) => /^\.changeset\/[^/]+\.md$/.test(name) && !name.endsWith('/README.md'));+ if (!changesetPath) return null;++ let raw;+ try {+ raw = gh([+ 'api',+ // Read at the PR head rather than at the default branch: the changeset+ // file is consumed and deleted when the release that shipped it was cut.+ `repos/${pull.owner}/${pull.repo}/contents/${changesetPath}?ref=refs/pull/${pull.number}/head`,+ '--jq',+ '.content',+ ]);+ } catch (err) {+ throw new Error(`gh api contents/${changesetPath} failed: ${String(err?.stderr || err?.message || '').trim()}`);+ }++ const decoded = Buffer.from(raw.replace(/\s+/g, ''), 'base64').toString('utf8');+ return parseChangeset(decoded);+}++/** Strip the `---`-delimited bump block; what remains is the release note. */+export function parseChangeset(raw) {+ const text = String(raw ?? '');+ const withoutFrontmatter = text.replace(/^\s*---[\s\S]*?---\s*/, '').trim();+ if (!withoutFrontmatter) return null;+ const [firstLine] = withoutFrontmatter.split('\n');+ return { title: firstLine.trim(), body: withoutFrontmatter };+}++async function realPostReply(origin, text) {+ if (origin.channel === 'github-issue') {+ execFileSync(+ 'gh',+ ['api', `repos/${origin.owner}/${origin.repo}/issues/${origin.number}/comments`, '-f', `body=${text}`],+ { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },+ );+ return;+ }+ if (origin.channel === 'discord-thread') {+ // The bot token never leaves Railway, so this goes through the deployed+ // bot's authenticated endpoint rather than carrying a Discord credential+ // into Actions. The release-announcement webhook is NOT an alternative: a+ // webhook is bound to one channel and could only reach threads inside it,+ // so a reply sent that way would land where the reporter never looks.+ const url = process.env.DISCORD_NOTIFY_URL;+ const token = process.env.DISCORD_NOTIFY_TOKEN;+ if (!url || !token) throw new Error('DISCORD_NOTIFY_URL / DISCORD_NOTIFY_TOKEN are required to reply on Discord');+ const res = await fetch(url, {+ method: 'POST',+ headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },+ body: JSON.stringify({ threadId: origin.threadId, content: text }),+ });+ if (!res.ok) {+ throw new Error(`notify endpoint returned HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);+ }+ return;+ }+ throw new Error(`no reply transport for origin channel '${origin.channel}'`);+}++async function main() {+ const log = (message) => console.log(message);+ const apiKey = (process.env.LINEAR_API_KEY ?? '').trim();+ if (!apiKey) {+ console.log(+ '::notice::write-back: LINEAR_API_KEY is not set on this repo, so there is nothing to enumerate. ' ++ 'Add it as a repo secret to enable reporter write-back. Nothing was posted.',+ );+ return;+ }++ const live = process.env.WRITE_BACK_MODE === 'live';+ if (!live) {+ log('::notice::write-back: running in dry-run mode (set WRITE_BACK_MODE=live to arm reporter replies).');+ }++ const stableTags = realStableTags();+ const versionFor = (node) =>+ deriveVersionForFixRefs({+ fixReferences: partitionAttachments(node.attachmentUrls ?? []).fixReferences,+ stableTags,+ findMirroredCommits: realFindMirroredCommits,+ contains: realContains,+ resolvePrMergeSha: realResolvePrMergeSha,+ log,+ });++ const result = await runWriteBack({+ listCandidates: () => paginate({ apiKey, query: CANDIDATE_QUERY, variables: {} }),+ listChildren: (parentId) => paginate({ apiKey, query: CHILDREN_QUERY, variables: { parentId } }),+ versionFor,+ readChangesetProse: (candidate, ctx) => realReadChangesetProse(candidate, ctx),+ postReply: realPostReply,+ recordNotification: async ({ issueId, url, title }) => {+ const data = await linearGraphql({+ apiKey,+ query:+ 'mutation Mark($input: AttachmentCreateInput!) { attachmentCreate(input: $input) { success } }',+ variables: { input: { issueId, url, title } },+ });+ // A dropped marker is not cosmetic: it is what stops the next run+ // replying to the same reporter again.+ if (!data?.attachmentCreate?.success) {+ throw new Error(`Linear attachmentCreate reported failure for issue ${issueId}`);+ }+ },+ live,+ log,+ });++ console.log(JSON.stringify({ dryRun: result.dryRun, posted: result.posted.length, skipped: result.skipped }));+}++if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {+ main().catch((err) => {+ console.error(`::error::write-back: ${err.message}`);+ process.exit(1);+ });+}diff --git a/.github/scripts/write-back.test.mjs b/.github/scripts/write-back.test.mjsnew file mode 100644index 000000000..725eec82f--- /dev/null+++ b/.github/scripts/write-back.test.mjs@@ -0,0 +1,379 @@+import { readFileSync } from 'node:fs';+import { describe, expect, test } from 'vitest';+import {+ CANDIDATE_QUERY,+ deriveVersionForFixRefs,+ notificationMarkerUrl,+ parseChangeset,+ runWriteBack,+} from './write-back.mjs';++const GH_ISSUE = 'https://github.com/inkeep/open-knowledge/issues/769';+const GH_PULL = 'https://github.com/inkeep/agents-private/pull/2844';+const SLACK_ARCHIVE = 'https://inkeep.slack.com/archives/C016VCYCL74/p1727122965001469';+const DISCORD_THREAD = 'https://discord.com/channels/1514363990740828223/1528881792063508610';+const CHANGESET = { title: 'Honor backslash escapes', body: 'Honor backslash escapes in the markdown promoters.' };++// The real chain off the mirror: a private merge commit, its mirrored copy, and+// the stable tag that first contains it.+const PRIVATE_SHA = 'da71f0c698ccaac11da915169ca6c7d585d5eb97';+const MIRRORED_SHA = 'eb52a625cd86859a8ec43ddc8f96e9b418d092a7';+const STABLE_TAGS = ['v0.35.0', 'v0.35.2', 'v0.35.6', 'v0.36.0'];++const candidate = (overrides = {}) => ({+ id: 'uuid-7539',+ identifier: 'PRD-7539',+ stateType: 'completed',+ labels: ['Bug', 'ok:platform'],+ attachmentUrls: [GH_PULL, GH_ISSUE],+ ...overrides,+});++// Every boundary is a plain closure. `writes` is the ledger the dry-run test+// asserts stays empty.+function harness(overrides = {}) {+ const logs = [];+ const writes = [];+ const deps = {+ listCandidates: async () => [candidate()],+ listChildren: async () => [],+ versionFor: async () => 'v0.36.0',+ 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 }),+ log: (m) => logs.push(m),+ ...overrides,+ };+ return { deps, logs, writes, run: () => runWriteBack(deps) };+}++describe('candidate enumeration', () => {+ test('candidates come from a Linear ticket query, never from a walk over release commits', () => {+ expect(CANDIDATE_QUERY).toContain('issues(');+ expect(CANDIDATE_QUERY).toContain('state: { type: { eq: "completed" } }');+ expect(CANDIDATE_QUERY).not.toMatch(/commits?\s*\(/);+ });++ test('the label filter matches any label, so a Bug ticket carrying a platform label is still enumerated', () => {+ expect(CANDIDATE_QUERY).toContain('labels: { name: { eq: "Bug" } }');+ // `labels: { every: ... }` reads almost the same and would drop every+ // multi-labelled ticket, which in practice is nearly all of them.+ expect(CANDIDATE_QUERY).not.toContain('every');+ });++ test('the not-yet-notified condition is not expressed inside the query', () => {+ expect(CANDIDATE_QUERY).not.toMatch(/notified/i);+ expect(CANDIDATE_QUERY).toContain('attachments');+ });++ test('the module imports the shared shipped-version resolver rather than reimplementing containment', () => {+ const source = readFileSync(new URL('./write-back.mjs', import.meta.url), 'utf8');+ expect(source).toMatch(/from '\.\/resolve-shipped-version\.mjs'/);+ expect(source).toContain('resolveShippedVersion');+ // The one place tag containment may be spelled out is the injected git+ // boundary it hands to that resolver.+ expect(source.match(/merge-base/g)?.length ?? 0).toBeLessThanOrEqual(2);+ });+});++describe('version derivation', () => {+ const findMirrored = (sha) =>+ sha === PRIVATE_SHA ? [{ sha: MIRRORED_SHA, message: `subject\n\nGitOrigin-RevId: ${PRIVATE_SHA}\n` }] : [];+ const containsFrom = (map) => (tag, sha) => (map[sha] ?? []).includes(tag);++ const derive = (overrides = {}) =>+ deriveVersionForFixRefs({+ stableTags: STABLE_TAGS,+ findMirroredCommits: findMirrored,+ contains: containsFrom({ [MIRRORED_SHA]: ['v0.36.0'] }),+ resolvePrMergeSha: () => PRIVATE_SHA,+ ...overrides,+ });++ test('a pull-request fix reference resolves through tag containment', () => {+ expect(derive({ fixReferences: [{ channel: 'pull-request', url: GH_PULL }] })).toBe('0.36.0');+ });++ test('a commit fix reference resolves without needing a pull request', () => {+ expect(+ derive({+ fixReferences: [{ channel: 'commit', url: 'https://github.com/x/y/commit/' + PRIVATE_SHA, sha: PRIVATE_SHA }],+ resolvePrMergeSha: () => {+ throw new Error('a commit reference must not need the pull-request hop');+ },+ }),+ ).toBe('0.36.0');+ });++ test('across several fix references the answer is the highest, so the build contains all of them', () => {+ const otherSha = 'b'.repeat(40);+ const otherMirrored = 'c'.repeat(40);+ expect(+ deriveVersionForFixRefs({+ fixReferences: [+ { channel: 'commit', url: 'u1', sha: PRIVATE_SHA },+ { channel: 'commit', url: 'u2', sha: otherSha },+ ],+ stableTags: STABLE_TAGS,+ findMirroredCommits: (sha) =>+ sha === PRIVATE_SHA+ ? [{ sha: MIRRORED_SHA, message: `GitOrigin-RevId: ${PRIVATE_SHA}` }]+ : [{ sha: otherMirrored, message: `GitOrigin-RevId: ${otherSha}` }],+ contains: containsFrom({+ [MIRRORED_SHA]: ['v0.35.2', 'v0.35.6', 'v0.36.0'],+ [otherMirrored]: ['v0.36.0'],+ }),+ resolvePrMergeSha: () => PRIVATE_SHA,+ }),+ ).toBe('0.36.0');+ });++ test('a fix reference that has not reached a stable release yields no version at all', () => {+ expect(+ derive({+ fixReferences: [{ channel: 'commit', url: 'u', sha: PRIVATE_SHA }],+ contains: () => false,+ }),+ ).toBeNull();+ });++ test('a ticket with no fix references yields no version rather than throwing', () => {+ expect(derive({ fixReferences: [] })).toBeNull();+ });++ test('an infra failure in the git boundary propagates rather than reading as not-shipped', () => {+ expect(() =>+ derive({+ fixReferences: [{ channel: 'commit', url: 'u', sha: PRIVATE_SHA }],+ contains: () => {+ throw new Error('git exploded');+ },+ }),+ ).toThrow(/git exploded/);+ });+});++describe('idempotency marker', () => {+ test('the marker url is deterministic in the origin and the version', () => {+ const a = notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE });+ const b = notificationMarkerUrl({ version: 'v0.36.0', originUrl: GH_ISSUE });+ expect(a).toBe(b);+ expect(a).toContain('/releases/tag/v0.36.0');+ expect(a).toContain(encodeURIComponent(GH_ISSUE));+ });++ test('a different origin or a different version yields a different marker', () => {+ const base = notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE });+ expect(notificationMarkerUrl({ version: '0.36.1', originUrl: GH_ISSUE })).not.toBe(base);+ expect(notificationMarkerUrl({ version: '0.36.0', originUrl: `${GH_ISSUE}0` })).not.toBe(base);+ });+});++describe('write-back run', () => {+ test('with no explicit live mode it composes and logs but performs no writes at all', async () => {+ const h = harness();+ const result = await h.run();+ expect(result.dryRun).toBe(true);+ expect(h.writes).toEqual([]);+ expect(result.posted).toHaveLength(1);+ expect(h.logs.some((m) => m.includes('[dry run]'))).toBe(true);+ });++ test('in live mode it records the notification before posting to the origin', async () => {+ const h = harness({ live: true });+ await h.run();+ // The order is the at-most-once guarantee, not an incidental detail. Were+ // the reply to land first, a crash before the marker was written would+ // re-send a reply the reporter had already read on the next run.+ expect(h.writes.map((w) => w.kind)).toEqual(['mark', 'post']);+ const post = h.writes.find((w) => w.kind === 'post');+ const mark = h.writes.find((w) => w.kind === 'mark');+ expect(post.origin).toBe(GH_ISSUE);+ expect(post.text).toContain('v0.36.0');+ expect(mark.url).toBe(notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE }));+ });++ test('a discord-thread origin is composed for Discord, not just classified as one', async () => {+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, DISCORD_THREAD] })],+ });+ await h.run();+ const post = h.writes.find((w) => w.kind === 'post');+ // The gate's own tests pin the two formattings; what this pins is the+ // wiring between them, which a rename anywhere along+ // classify -> origin.channel -> composeReply would sever silently while+ // every unit test still passed.+ expect(post.origin).toBe(DISCORD_THREAD);+ expect(post.text).toContain('<https://github.com/inkeep/open-knowledge/releases>');+ });++ test('a failure while recording the marker leaves the reporter unmessaged', async () => {+ const h = harness({+ live: true,+ recordNotification: async () => {+ throw new Error('Linear attachmentCreate reported failure');+ },+ });+ await expect(h.run()).rejects.toThrow(/attachmentCreate/);+ expect(h.writes.filter((w) => w.kind === 'post')).toHaveLength(0);+ });++ test('running twice against the same release posts exactly once', async () => {+ const marker = notificationMarkerUrl({ version: '0.36.0', originUrl: GH_ISSUE });+ const first = harness({ live: true });+ await first.run();+ expect(first.writes.filter((w) => w.kind === 'post')).toHaveLength(1);++ // The second run sees the marker the first one recorded, exactly as a+ // re-read of the ticket would.+ const second = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, GH_ISSUE, marker] })],+ });+ const result = await second.run();+ expect(second.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'already-notified' }]);+ });++ test('a candidate whose version cannot be derived posts nothing and warns distinguishably', async () => {+ const h = harness({ live: true, versionFor: async () => null });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'version-underivable' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('no stable release could be derived'))).toBe(+ true,+ );+ });++ test('a candidate whose only origin cannot be replied to posts nothing and warns', async () => {+ const h = harness({+ live: true,+ listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL, SLACK_ARCHIVE] })],+ });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'origin-unrepliable' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('nowhere to post'))).toBe(true);+ });++ test('a candidate with no origin at all is skipped quietly, because not every fix has a reporter', async () => {+ const h = harness({ live: true, listCandidates: async () => [candidate({ attachmentUrls: [GH_PULL] })] });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'no-origin' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::'))).toBe(false);+ });++ test('an outstanding descendant withholds the whole reply', async () => {+ const h = harness({+ live: true,+ listChildren: async () => [+ { id: 'a', identifier: 'PRD-7398', stateType: 'completed', labels: ['Bug'], attachmentUrls: [] },+ { id: 'b', identifier: 'PRD-7401', stateType: 'unstarted', labels: [], attachmentUrls: [] },+ ],+ });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'fan-in-withheld' }]);+ });++ test('a candidate with no changeset prose posts nothing rather than a bare version', async () => {+ const h = harness({ live: true, readChangesetProse: async () => null });+ const result = await h.run();+ expect(h.writes).toEqual([]);+ expect(result.skipped).toEqual([{ identifier: 'PRD-7539', reason: 'no-prose' }]);+ expect(h.logs.some((m) => m.startsWith('::warning::') && m.includes('no changeset prose'))).toBe(true);+ });++ test('an infra failure throws out of the run rather than being folded into silence', async () => {+ const h = harness({+ live: true,+ listCandidates: async () => {+ throw new Error('Linear GraphQL returned HTTP 500');+ },+ });+ await expect(h.run()).rejects.toThrow(/HTTP 500/);+ });++ test('the coverage of a fanned-in report reaches the reply', async () => {+ const h = harness({+ live: true,+ listChildren: async () => [+ { id: 'a', identifier: 'PRD-7398', stateType: 'completed', labels: ['Bug'], attachmentUrls: [] },+ { id: 'b', identifier: 'PRD-7403', stateType: 'completed', labels: [], attachmentUrls: [] },+ ],+ });+ await h.run();+ expect(h.writes.find((w) => w.kind === 'post').text).toContain('Covers PRD-7398, PRD-7403.');+ });+});++describe('changeset parsing', () => {+ test('the bump block is stripped and the release note is what remains', () => {+ const parsed = parseChangeset(+ ['---', "'@inkeep/open-knowledge': patch", '---', '', 'Honor backslash escapes in the promoters.', ''].join(+ '\n',+ ),+ );+ expect(parsed).toEqual({+ title: 'Honor backslash escapes in the promoters.',+ body: 'Honor backslash escapes in the promoters.',+ });+ });++ test('a multi-line note keeps its first line as the title and its whole text as the body', () => {+ const parsed = parseChangeset(['---', "'x': patch", '---', '', 'Short subject', '', 'More detail.'].join('\n'));+ expect(parsed.title).toBe('Short subject');+ expect(parsed.body).toContain('More detail.');+ });++ test('a changeset with no prose yields nothing rather than an empty reply', () => {+ expect(parseChangeset(['---', "'x': patch", '---', ''].join('\n'))).toBeNull();+ expect(parseChangeset('')).toBeNull();+ });+});++// The properties that keep a reporter-facing side effect from ever touching a+// release: its own trigger, its own concurrency group, and no edit to any of+// the three publish workflows.+describe('workflow shape', () => {+ const read = (name) => readFileSync(new URL(`../workflows/${name}`, import.meta.url), 'utf8');+ const workflow = read('write-back.yml');++ test('it triggers on the existing release dispatch rather than on release published', () => {+ expect(workflow).toMatch(/repository_dispatch:\s*\n\s*types:\s*\[desktop-release\]/);+ expect(workflow).not.toMatch(/^\s{2}release:/m);+ expect(workflow).not.toContain('types: [published]');+ });++ test('only a bare stable tag runs the write-back', () => {+ expect(workflow).toContain('^v[0-9]+\\.[0-9]+\\.[0-9]+$');+ expect(workflow).toMatch(/if:\s*steps\.tag\.outputs\.stable == 'true'/);+ });++ test('it carries its own concurrency group so a release can never queue behind it', () => {+ const group = /concurrency:\s*\n(?:\s*#.*\n)*\s*group:\s*(.+)/.exec(workflow)?.[1] ?? '';+ expect(group).toContain('reporter-write-back');+ for (const other of ['release.yml', 'promote-stable.yml', 'linear-release.yml']) {+ const otherGroup = /concurrency:\s*\n(?:\s*#.*\n)*\s*group:\s*(.+)/.exec(read(other))?.[1] ?? '';+ expect(group.trim()).not.toBe(otherGroup.trim());+ }+ });++ test('the checkout provides full history and tags so containment can be computed', () => {+ expect(workflow).toContain('fetch-depth: 0');+ expect(workflow).toContain('fetch-tags: true');+ });++ test('no release workflow references the write-back, so it cannot fail a release', () => {+ for (const name of ['release.yml', 'promote-stable.yml', 'desktop-release.yml']) {+ expect(read(name)).not.toMatch(/write-back/i);+ }+ });++ test('live posting needs an explicit mode on top of the credential', () => {+ expect(workflow).toContain('WRITE_BACK_MODE');+ expect(workflow).toContain('LINEAR_API_KEY');+ });+});diff --git a/.github/workflows/write-back.yml b/.github/workflows/write-back.ymlnew file mode 100644index 000000000..8d28b54bd--- /dev/null+++ b/.github/workflows/write-back.yml@@ -0,0 +1,101 @@+name: Reporter Write-Back++# Tell bug reporters, once, that the fix they reported has shipped.+#+# HOW IT'S TRIGGERED (no edits to the delicate publish path)+# release.yml (beta) and promote-stable.yml (stable) both already fire a+# repository_dispatch event_type=desktop-release carrying+# client_payload.{release_tag, ref}. This piggybacks on that same event, the+# way linear-release.yml already does, so the publish workflows stay+# byte-untouched. `release: published` is not an option: GitHub suppresses+# cascades from GITHUB_TOKEN-authored release events, and repository_dispatch+# is the documented exemption.+#+# Only a bare vX.Y.Z runs. A `-beta.N` cut is a no-op: a reporter told their+# fix is out should be able to install it from the default channel, and a beta+# is not that.+#+# WHY IT IS DECOUPLED+# This posts in public under the project's name and it runs after a release+# has already happened. Nothing it does may reach back into the release: it+# has its own trigger and its own concurrency group, so it can never queue+# behind or delay a cut, and no release workflow waits on its result. The+# worst outcome available to a failure here is that nobody gets told.+#+# EVERYTHING SHIPS INERT+# With no LINEAR_API_KEY the script emits a notice and enumerates nothing.+# With the key but no WRITE_BACK_MODE it composes replies and logs them+# without performing a single write. Live posting therefore needs two+# deliberate operator actions, so wiring up credentials cannot arm+# reporter-facing posts by accident. Both steps are in RELEASES.md.++on:+ repository_dispatch:+ types: [desktop-release]+ # Manual backfill / dry-run rehearsal against a specific tag.+ workflow_dispatch:+ inputs:+ release_tag:+ description: "Stable release tag to notify reporters about (e.g. v0.36.0)"+ required: true+ type: string++permissions:+ contents: read+ # Posting the reply onto a GitHub issue origin in this repo.+ issues: write++concurrency:+ # Its own group, deliberately not the release cadence group: a write-back run+ # must never be something a release cut can end up waiting on.+ group: reporter-write-back-${{ github.event.client_payload.release_tag || inputs.release_tag }}+ cancel-in-progress: false++jobs:+ notify:+ runs-on: ubuntu-latest+ timeout-minutes: 10+ env:+ RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}+ steps:+ - name: Decide whether this tag is a stable release+ id: tag+ run: |+ set -euo pipefail+ if [[ -z "${RELEASE_TAG}" ]]; then+ echo "::error::No release tag (neither client_payload.release_tag nor inputs.release_tag)."+ exit 1+ fi+ if [[ "${RELEASE_TAG}" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then+ echo "stable=true" >> "$GITHUB_OUTPUT"+ else+ echo "stable=false" >> "$GITHUB_OUTPUT"+ echo "::notice::${RELEASE_TAG} is not a bare stable tag; reporters are only told about stable releases."+ fi++ - name: Checkout with full history and tags+ if: steps.tag.outputs.stable == 'true'+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2+ with:+ # Tag containment is how the shipped version is derived, so every+ # stable tag and the full history behind them have to be present.+ fetch-depth: 0+ fetch-tags: true+ persist-credentials: false++ - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0+ if: steps.tag.outputs.stable == 'true'+ with:+ node-version: "24"++ - name: Notify reporters whose fix reached this release+ if: steps.tag.outputs.stable == 'true'+ env:+ GH_TOKEN: ${{ github.token }}+ LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}+ # Absent by default. Set to `live` on the repo (a variable, not a+ # secret, so it is visible in the settings UI) to arm real posts.+ WRITE_BACK_MODE: ${{ vars.WRITE_BACK_MODE }}+ DISCORD_NOTIFY_URL: ${{ secrets.DISCORD_NOTIFY_URL }}+ DISCORD_NOTIFY_TOKEN: ${{ secrets.DISCORD_NOTIFY_TOKEN }}+ run: node .github/scripts/write-back.mjs