Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(changelog): tell holders how many commits a release note actually covers

nirholasae94667a0892
diff --git a/packages/shipfeed/tests/render.test.js b/packages/shipfeed/tests/render.test.js
new file mode 100644
index 000000000..4d5061c76
--- /dev/null
+++ b/packages/shipfeed/tests/render.test.js
@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import {
+ renderCommitTelegram,
+ renderReleaseTelegram,
+ renderMarkdown,
+ renderRss,
+ renderTerminal,
+} from '../src/render.js';
+
+const commit = {
+ sha: 'a'.repeat(40),
+ shortSha: 'aaaaaaa',
+ url: 'https://github.com/o/r/commit/aaaaaaa',
+ date: '2026-08-27T09:00:00Z',
+ author: 'nirholas',
+ type: 'feat',
+ scope: 'forge',
+ breaking: false,
+ headline: 'Feature · forge',
+ summary: 'paint concept images across five providers',
+ audience: 'holder',
+ signal: 0.8,
+ issues: [],
+ confidence: 0.42,
+ why: ['shared terms: forge, concept'],
+};
+
+const release = {
+ key: '2026-08-27:A release',
+ slug: '2026-08-27-a-release',
+ date: '2026-08-27',
+ title: 'A release <with> markup & risk',
+ summary: 'What changed, in a sentence.',
+ tags: ['fix', 'infra'],
+ link: '/forge',
+ url: 'https://three.ws/changelog/2026-08-27-a-release',
+ commits: [commit],
+ stats: { commits: 1, authors: 1, range: 'aaaaaaa..aaaaaaa' },
+};
+
+const feed = {
+ version: 1,
+ generatedAt: '2026-08-28T00:00:00Z',
+ repo: 'o/r',
+ siteUrl: 'https://three.ws',
+ releases: [release],
+ ships: [
+ {
+ id: 'bbbbbbb..bbbbbbb',
+ start: '2026-08-26T09:00:00Z',
+ end: '2026-08-26T09:30:00Z',
+ title: 'Fix · wallet',
+ summary: 'stop a double withdrawal prompt',
+ authors: ['nirholas'],
+ signal: 0.6,
+ commits: [{ ...commit, shortSha: 'bbbbbbb', headline: 'Fix · wallet' }],
+ },
+ ],
+ stats: {
+ commits: 2,
+ hidden: 0,
+ releases: 1,
+ linked: 1,
+ orphans: 1,
+ coverage: 0.5,
+ byType: { feat: 1, fix: 1 },
+ byAudience: { holder: 2, developer: 0, internal: 0 },
+ topAuthors: [{ name: 'nirholas', count: 2 }],
+ velocity: [{ date: '2026-08-27', count: 2 }],
+ },
+};
+
+describe('renderCommitTelegram', () => {
+ it('puts the headline in bold above the description and the source line', () => {
+ const msg = renderCommitTelegram(commit, { repo: 'o/r' });
+ expect(msg).toContain('<b>Feature · forge</b>');
+ expect(msg).toContain('paint concept images across five providers');
+ expect(msg).toContain('github.com/o/r/commit/aaaaaaa');
+ expect(msg).toContain('2026-08-27');
+ });
+
+ it('escapes markup in a commit subject', () => {
+ const msg = renderCommitTelegram({ ...commit, summary: 'guard <script> & co' });
+ expect(msg).toContain('guard &lt;script&gt; &amp; co');
+ expect(msg).not.toContain('<script>');
+ });
+});
+
+describe('renderReleaseTelegram', () => {
+ it('adds the provenance footer the raw commit feed cannot carry', () => {
+ const msg = renderReleaseTelegram(release, { repo: 'o/r' });
+ expect(msg).toContain('shipped in <a href="https://github.com/o/r/compare/aaaaaaa...aaaaaaa">1 commit</a>');
+ expect(msg).toContain('#fix #infra');
+ });
+
+ it('omits the footer when nothing was linked', () => {
+ const msg = renderReleaseTelegram(
+ { ...release, commits: [], stats: { commits: 0, authors: 0, range: null } },
+ { repo: 'o/r' },
+ );
+ expect(msg).not.toContain('shipped in');
+ });
+
+ it('escapes markup in a release title', () => {
+ expect(renderReleaseTelegram(release, { repo: 'o/r' })).toContain('&lt;with&gt; markup &amp; risk');
+ });
+});
+
+describe('renderMarkdown', () => {
+ it('writes releases with their commits, then the unannounced work', () => {
+ const md = renderMarkdown(feed);
+ expect(md).toContain('# Ship log');
+ expect(md).toContain('## 2026-08-27 · A release');
+ expect(md).toContain('`aaaaaaa`');
+ expect(md).toContain('## Unannounced work');
+ });
+
+ it('can leave the unannounced section out', () => {
+ expect(renderMarkdown(feed, { includeShips: false })).not.toContain('Unannounced work');
+ });
+});
+
+describe('renderRss', () => {
+ it('emits a valid-looking channel with one item per release', () => {
+ const rss = renderRss(feed, { title: 'o/r ship log', siteUrl: 'https://three.ws/ship' });
+ expect(rss.startsWith('<?xml version="1.0" encoding="UTF-8"?>')).toBe(true);
+ expect(rss).toContain('<title>o/r ship log</title>');
+ expect(rss).toContain('<guid isPermaLink="false">2026-08-27:A release</guid>');
+ expect(rss).toContain('27 Aug 2026 12:00:00 GMT');
+ });
+
+ it('escapes markup so a title can never break the document', () => {
+ expect(renderRss(feed)).toContain('A release &lt;with&gt; markup &amp; risk');
+ });
+});
+
+describe('renderTerminal', () => {
+ it('writes a plain report with no escape codes when color is off', () => {
+ const out = renderTerminal(feed, { color: false });
+ expect(out).toContain('ship log · o/r');
+ expect(out).toContain('50% coverage');
+ expect(out).toContain('unannounced');
+ expect(out).not.toContain(String.fromCharCode(27));
+ });
+
+ it('colors the report when asked', () => {
+ expect(renderTerminal(feed, { color: true })).toContain(String.fromCharCode(27));
+ });
+
+ it('truncates a long commit list instead of flooding the terminal', () => {
+ const many = { ...release, commits: Array.from({ length: 9 }, () => commit) };
+ const out = renderTerminal({ ...feed, releases: [many] }, { color: false, maxCommits: 2 });
+ expect(out).toContain('+7 more');
+ });
+});
diff --git a/tests/ship-feed-endpoint.test.js b/tests/ship-feed-endpoint.test.js
new file mode 100644
index 000000000..d99b133ad
--- /dev/null
+++ b/tests/ship-feed-endpoint.test.js
@@ -0,0 +1,156 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// The handler's only third-party call goes through fetchUpstream, so mocking
+// that one module gives the whole endpoint a real GitHub shape to work with
+// while keeping the test offline. Everything else (the changelog it reads from
+// public/changelog.json, the linking, the renderers) runs for real.
+const COMMITS = [
+ {
+ sha: 'a'.repeat(40),
+ html_url: 'https://github.com/nirholas/three.ws/commit/aaaaaaa',
+ parents: [{ sha: 'p' }],
+ commit: {
+ message: 'feat(forge): paint concept images across five independent providers',
+ author: { name: 'nirholas', date: '2026-08-27T09:00:00Z' },
+ committer: { date: '2026-08-27T09:00:00Z' },
+ },
+ author: { login: 'nirholas' },
+ },
+ {
+ sha: 'b'.repeat(40),
+ html_url: 'https://github.com/nirholas/three.ws/commit/bbbbbbb',
+ parents: [{ sha: 'p' }],
+ commit: {
+ message: 'chore(deps): bump ws',
+ author: { name: 'nirholas', date: '2026-08-27T09:30:00Z' },
+ committer: { date: '2026-08-27T09:30:00Z' },
+ },
+ author: { login: 'nirholas' },
+ },
+ {
+ sha: 'c'.repeat(40),
+ html_url: 'https://github.com/nirholas/three.ws/commit/ccccccc',
+ parents: [{ sha: 'p' }],
+ commit: {
+ message: 'Merge pull request #9 from nirholas/branch',
+ author: { name: 'nirholas', date: '2026-08-27T10:00:00Z' },
+ committer: { date: '2026-08-27T10:00:00Z' },
+ },
+ author: { login: 'nirholas' },
+ },
+];
+
+const fetchUpstream = vi.fn(async () => ({
+ ok: true,
+ status: 200,
+ headers: { get: () => null },
+ json: async () => COMMITS,
+}));
+
+vi.mock('../api/_lib/upstream-fetch.js', () => ({ fetchUpstream }));
+
+const { default: handler } = await import('../api/ship/feed.js');
+
+function mkRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: undefined,
+ writableEnded: false,
+ headersSent: false,
+ getHeader(k) {
+ return this.headers[k.toLowerCase()];
+ },
+ setHeader(k, v) {
+ this.headers[k.toLowerCase()] = v;
+ },
+ end(b) {
+ this.body = b;
+ this.writableEnded = true;
+ },
+ };
+}
+
+async function call(url = '/api/ship/feed') {
+ const req = { method: 'GET', url, headers: {}, socket: { remoteAddress: '127.0.0.1' } };
+ const res = mkRes();
+ await handler(req, res);
+ return res;
+}
+
+beforeEach(() => {
+ fetchUpstream.mockClear();
+});
+
+describe('GET /api/ship/feed', () => {
+ it('returns a unified feed with releases, ships, and stats', async () => {
+ // A distinct limit per case keeps each assertion off the previous one's
+ // cache entry, which is keyed by limit and audience.
+ const res = await call('/api/ship/feed?limit=11');
+ expect(res.statusCode).toBe(200);
+ const feed = JSON.parse(res.body);
+ expect(feed.version).toBeGreaterThan(0);
+ expect(feed.repo).toBe('nirholas/three.ws');
+ expect(Array.isArray(feed.releases)).toBe(true);
+ expect(Array.isArray(feed.ships)).toBe(true);
+ expect(feed.stats.commits).toBe(COMMITS.length);
+ expect(res.getHeader('cache-control')).toContain('max-age=');
+ });
+
+ it('classifies the commits it read', async () => {
+ const feed = JSON.parse((await call('/api/ship/feed?limit=12')).body);
+ const all = [...feed.releases.flatMap((r) => r.commits), ...feed.ships.flatMap((s) => s.commits)];
+ const feature = all.find((c) => c.sha.startsWith('aaa'));
+ expect(feature.headline).toBe('Feature · forge');
+ expect(feature.audience).toBe('holder');
+ });
+
+ it('drops machinery when the caller asks for product news only', async () => {
+ const feed = JSON.parse((await call('/api/ship/feed?limit=13&audience=holder')).body);
+ const shas = [
+ ...feed.releases.flatMap((r) => r.commits),
+ ...feed.ships.flatMap((s) => s.commits),
+ ].map((c) => c.sha);
+ expect(shas.some((s) => s.startsWith('aaa'))).toBe(true);
+ expect(shas.some((s) => s.startsWith('bbb'))).toBe(false);
+ expect(feed.stats.hidden).toBeGreaterThan(0);
+ });
+
+ it('renders markdown and RSS from the same feed', async () => {
+ const md = await call('/api/ship/feed?limit=14&format=markdown');
+ expect(md.getHeader('content-type')).toContain('text/markdown');
+ expect(md.body).toContain('# Ship log');
+
+ const rss = await call('/api/ship/feed?limit=15&format=rss');
+ expect(rss.getHeader('content-type')).toContain('rss+xml');
+ expect(rss.body).toContain('<rss version="2.0">');
+ });
+
+ it('explains one commit, scoring and link reasons included', async () => {
+ const res = await call(`/api/ship/feed?limit=16&explain=${'a'.repeat(7)}`);
+ expect(res.statusCode).toBe(200);
+ const body = JSON.parse(res.body);
+ expect(body.commit.shortSha).toBe('aaaaaaa');
+ expect(body.classification.audience).toBe('holder');
+ expect(body.classification.reasons.length).toBeGreaterThan(0);
+ });
+
+ it('rejects a malformed sha and reports an unknown one honestly', async () => {
+ expect((await call('/api/ship/feed?limit=17&explain=nope')).statusCode).toBe(400);
+ expect((await call(`/api/ship/feed?limit=18&explain=${'f'.repeat(40)}`)).statusCode).toBe(404);
+ });
+
+ it('serves a second identical request from cache without re-reading GitHub', async () => {
+ await call('/api/ship/feed?limit=19');
+ const callsAfterFirst = fetchUpstream.mock.calls.length;
+ await call('/api/ship/feed?limit=19');
+ expect(fetchUpstream.mock.calls.length).toBe(callsAfterFirst);
+ });
+
+ it('refuses a non-GET method', async () => {
+ const req = { method: 'POST', url: '/api/ship/feed', headers: {}, socket: { remoteAddress: '127.0.0.1' } };
+ const res = mkRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(405);
+ });
+});
diff --git a/tests/ship-provenance.test.js b/tests/ship-provenance.test.js
new file mode 100644
index 000000000..3e712ef34
--- /dev/null
+++ b/tests/ship-provenance.test.js
@@ -0,0 +1,93 @@
+import { describe, it, expect } from 'vitest';
+import { provenanceByEntry } from '../api/_lib/ship-provenance.js';
+import { formatTelegramMessage } from '../api/_lib/changelog-push.js';
+
+const commit = (sha, message, date) => ({
+ sha: sha.padEnd(40, '0'),
+ parents: [{ sha: 'parent' }],
+ commit: {
+ message,
+ author: { name: 'nirholas', date },
+ committer: { date },
+ },
+ author: { login: 'nirholas' },
+});
+
+const entry = {
+ date: '2026-08-27',
+ title: 'Text-to-3D now has five independent image sources behind it',
+ summary:
+ 'Every text-to-3D generation starts by painting a concept image. The painter now tries five independent image providers in order, under one shared time budget.',
+ tags: ['fix', 'infra'],
+ link: '/forge',
+};
+
+describe('provenanceByEntry', () => {
+ // Term weighting is inverse-document-frequency based, so it needs a corpus to
+ // weigh against. Real ticks read 300 commits; these stand in for the rest of
+ // the afternoon's unrelated work.
+ const background = [
+ commit('d001', 'docs(seeker): write the dApp Store release runbook', '2026-08-27T07:00:00Z'),
+ commit('d002', 'fix(wallet): tell the owner a wallet is unsignable', '2026-08-27T07:30:00Z'),
+ commit('d003', 'test(agent-index): cover the backlog drain', '2026-08-27T08:00:00Z'),
+ commit('d004', 'style(nav): tighten the mobile breakpoint', '2026-08-27T08:30:00Z'),
+ ];
+
+ it('reports the commit count and a compare range for an entry it can place', async () => {
+ const commits = [
+ commit('bbb2', 'fix(forge): add two more concept image provider rungs to the painter', '2026-08-27T11:00:00Z'),
+ commit('aaa1', 'fix(forge): put every concept image provider on one shared time budget', '2026-08-27T09:00:00Z'),
+ ...background,
+ ];
+ const map = await provenanceByEntry([entry], { commits });
+ const p = map.get(`${entry.date}:${entry.title}`);
+ expect(p.count).toBe(2);
+ expect(p.range).toBe('aaa1000..bbb2000');
+ expect(p.compareUrl).toContain('/compare/');
+ });
+
+ it('links a single commit directly rather than to an empty compare view', async () => {
+ const commits = [
+ commit('aaa1', 'fix(forge): put every concept image provider on one shared time budget', '2026-08-27T09:00:00Z'),
+ ...background,
+ ];
+ const map = await provenanceByEntry([entry], { commits });
+ const p = map.get(`${entry.date}:${entry.title}`);
+ expect(p.count).toBe(1);
+ expect(p.compareUrl).toContain('/commit/');
+ });
+
+ it('returns nothing for an entry no commit matches', async () => {
+ const commits = [commit('cccc', 'style: reindent the footer', '2026-08-27T09:00:00Z'), ...background];
+ const map = await provenanceByEntry([entry], { commits });
+ expect(map.size).toBe(0);
+ });
+
+ it('returns an empty map when commits cannot be read, so a send never blocks', async () => {
+ expect((await provenanceByEntry([entry], { commits: null })).size).toBe(0);
+ expect((await provenanceByEntry([], { commits: [] })).size).toBe(0);
+ });
+});
+
+describe('formatTelegramMessage with provenance', () => {
+ const e = { date: '2026-08-27', title: 'A release', summary: 'What changed.', tags: ['fix'] };
+
+ it('adds a shipped-in line that points at the diff', () => {
+ const msg = formatTelegramMessage(e, {
+ count: 7,
+ compareUrl: 'https://github.com/nirholas/three.ws/compare/aaa...bbb',
+ });
+ expect(msg).toContain('shipped in <a href="https://github.com/nirholas/three.ws/compare/aaa...bbb">7 commits</a>');
+ });
+
+ it('says "commit" for a single commit', () => {
+ const msg = formatTelegramMessage(e, { count: 1, compareUrl: 'https://example.invalid/c' });
+ expect(msg).toContain('>1 commit<');
+ });
+
+ it('is byte-identical to the old message when provenance is unavailable', () => {
+ const withNull = formatTelegramMessage(e, null);
+ expect(withNull).toBe(formatTelegramMessage(e));
+ expect(withNull).not.toContain('shipped in');
+ });
+});