Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { afterEach, describe, expect, test } from 'bun:test'; |
| 2 | import { execFileSync } from 'node:child_process'; |
| 3 | import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'; |
| 4 | import { tmpdir } from 'node:os'; |
| 5 | import { dirname, join } from 'node:path'; |
| 6 | import { fileURLToPath, pathToFileURL } from 'node:url'; |
| 7 | import { |
| 8 | buildContentFreshness, getExplicitLastUpdated, normalizeLastUpdated, |
| 9 | } from '../../lib/content-freshness-build'; |
| 10 | import { createPageLastUpdatedReader } from '../../lib/content-freshness'; |
| 11 | |
| 12 | const directories: string[] = []; |
| 13 | const initial = '2025-01-01T12:00:00+00:00'; |
| 14 | const changed = '2025-02-02T12:00:00+00:00'; |
| 15 | const unrelated = '2025-03-03T12:00:00+00:00'; |
| 16 | |
| 17 | function temporaryDirectory() { |
| 18 | const directory = mkdtempSync(join(tmpdir(), 'docs-freshness-')); |
| 19 | directories.push(directory); |
| 20 | return directory; |
| 21 | } |
| 22 | function git(root: string, ...args: string[]) { |
| 23 | return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }); |
| 24 | } |
| 25 | function put(root: string, path: string, text: string) { |
| 26 | mkdirSync(dirname(join(root, path)), { recursive: true }); |
| 27 | writeFileSync(join(root, path), text); |
| 28 | } |
| 29 | function repository() { |
| 30 | const root = temporaryDirectory(); |
| 31 | git(root, 'init', '--initial-branch=main'); |
| 32 | git(root, 'config', 'user.name', 'Freshness tests'); |
| 33 | git(root, 'config', 'user.email', 'freshness@example.test'); |
| 34 | return root; |
| 35 | } |
| 36 | function commit(root: string, timestamp: string) { |
| 37 | git(root, 'add', '.'); |
| 38 | execFileSync('git', ['commit', '-m', 'fixture'], { |
| 39 | cwd: root, stdio: ['ignore', 'pipe', 'pipe'], |
| 40 | env: { ...process.env, GIT_AUTHOR_DATE: timestamp, GIT_COMMITTER_DATE: timestamp }, |
| 41 | }); |
| 42 | } |
| 43 | afterEach(() => { |
| 44 | for (const directory of directories.splice(0)) rmSync(directory, { recursive: true, force: true }); |
| 45 | }); |
| 46 | |
| 47 | describe('source-backed page freshness', () => { |
| 48 | test('tracks a changed source, not unrelated commits or filesystem write time', () => { |
| 49 | const root = repository(); |
| 50 | put(root, 'content/docs/guide.mdx', 'original'); |
| 51 | put(root, 'unrelated.txt', 'original'); |
| 52 | commit(root, initial); |
| 53 | put(root, 'content/docs/guide.mdx', 'updated'); |
| 54 | commit(root, changed); |
| 55 | put(root, 'unrelated.txt', 'updated'); |
| 56 | commit(root, unrelated); |
| 57 | // Rewriting the same bytes changes filesystem metadata, not source history. |
| 58 | put(root, 'content/docs/guide.mdx', 'updated'); |
| 59 | const result = buildContentFreshness(root, [ |
| 60 | { pathname: '/docs/guide', sources: ['content/docs/guide.mdx'] }, |
| 61 | { pathname: '/missing', sources: ['content/docs/missing.mdx'] }, |
| 62 | ]); |
| 63 | expect(result.pages['/docs/guide']).toBe('2025-02-02T12:00:00.000Z'); |
| 64 | expect(result.pages['/missing']).toBeUndefined(); |
| 65 | }); |
| 66 | |
| 67 | test('uses real spec, toolkit and KB backing sources and aggregates their latest change', () => { |
| 68 | const root = repository(); |
| 69 | for (const file of ['public/openapi.json', 'public/data/toolkits.json', 'kb/source/article.md']) { |
| 70 | put(root, file, 'original'); |
| 71 | } |
| 72 | commit(root, initial); |
| 73 | put(root, 'kb/source/article.md', 'updated'); |
| 74 | commit(root, changed); |
| 75 | const result = buildContentFreshness(root, [ |
| 76 | { pathname: '/reference/operation', sources: ['public/openapi.json'] }, |
| 77 | { pathname: '/toolkits/example', sources: ['public/data/toolkits.json'] }, |
| 78 | { pathname: '/kb/guide/article', sources: ['kb/source/article.md'] }, |
| 79 | { pathname: '/collection', sources: ['public/openapi.json', 'kb/source/article.md'] }, |
| 80 | { pathname: '/unknown-collection', sources: ['kb/source/article.md', 'missing.md'] }, |
| 81 | ]); |
| 82 | expect(result.pages['/reference/operation']).toBe('2025-01-01T12:00:00.000Z'); |
| 83 | expect(result.pages['/toolkits/example']).toBe('2025-01-01T12:00:00.000Z'); |
| 84 | expect(result.pages['/kb/guide/article']).toBe('2025-02-02T12:00:00.000Z'); |
| 85 | expect(result.pages['/collection']).toBe('2025-02-02T12:00:00.000Z'); |
| 86 | expect(result.pages['/unknown-collection']).toBeUndefined(); |
| 87 | }); |
| 88 | |
| 89 | test('honors explicit timestamps without Git and never substitutes release or review dates', () => { |
| 90 | const root = temporaryDirectory(); |
| 91 | expect(getExplicitLastUpdated('---\ndate: 2025-04-01\nwritten: April 2025\nlastVerifiedAt: 2025-05-01\n---\n')).toBeUndefined(); |
| 92 | const explicit = getExplicitLastUpdated('---\nlast_updated: "2025-04-01T14:30:00+02:00"\n---\n'); |
| 93 | expect(explicit).toBe('2025-04-01T14:30:00+02:00'); |
| 94 | const result = buildContentFreshness(root, [ |
| 95 | { pathname: '/explicit', sources: [], lastUpdated: explicit }, |
| 96 | { pathname: '/unknown', sources: ['missing.mdx'] }, |
| 97 | { pathname: '/date-only', sources: [], lastUpdated: '2025-04-01' }, |
| 98 | ]); |
| 99 | expect(result.pages['/explicit']).toBe('2025-04-01T12:30:00.000Z'); |
| 100 | expect(result.pages['/date-only']).toBe('2025-04-01T00:00:00.000Z'); |
| 101 | expect(result.pages['/unknown']).toBeUndefined(); |
| 102 | expect(normalizeLastUpdated('2025-02-30')).toBeNull(); |
| 103 | expect(normalizeLastUpdated('2025-04-01T14:30:00')).toBeNull(); |
| 104 | expect(() => getExplicitLastUpdated('---\nlast_updated: nonsense\n---\n')).toThrow('Invalid last_updated'); |
| 105 | expect(() => getExplicitLastUpdated('---\nlast_updated:\ntitle: Example\n---\n')).toThrow('Invalid last_updated'); |
| 106 | }); |
| 107 | |
| 108 | test('honors explicit per-source declarations in changelog-style aggregates', () => { |
| 109 | const root = temporaryDirectory(); |
| 110 | const result = buildContentFreshness(root, [ |
| 111 | { pathname: '/docs/changelog/2025/04/01', sources: ['one.mdx', 'two.mdx'] }, |
| 112 | ], { |
| 113 | [join(root, 'one.mdx')]: '2025-04-01', |
| 114 | [join(root, 'two.mdx')]: '2025-04-05', |
| 115 | }); |
| 116 | expect(result.pages['/docs/changelog/2025/04/01']).toBe('2025-04-05T00:00:00.000Z'); |
| 117 | }); |
| 118 | |
| 119 | test('omits shallow-boundary dates while retaining proven changes inside shallow history', () => { |
| 120 | const original = repository(); |
| 121 | put(original, 'page.mdx', 'original'); |
| 122 | put(original, 'untouched.mdx', 'original'); |
| 123 | commit(original, initial); |
| 124 | put(original, 'page.mdx', 'updated'); |
| 125 | commit(original, changed); |
| 126 | put(original, 'other.txt', 'unrelated'); |
| 127 | commit(original, unrelated); |
| 128 | const shallow = temporaryDirectory(); |
| 129 | git(shallow, 'clone', '--depth=2', pathToFileURL(original).href, '.'); |
| 130 | const definitions = [ |
| 131 | { pathname: '/page', sources: ['page.mdx'] }, |
| 132 | { pathname: '/untouched', sources: ['untouched.mdx'] }, |
| 133 | { pathname: '/other', sources: ['other.txt'] }, |
| 134 | ]; |
| 135 | const result = buildContentFreshness(shallow, definitions); |
| 136 | expect(result.pages['/page']).toBeUndefined(); |
| 137 | expect(result.pages['/untouched']).toBeUndefined(); |
| 138 | expect(result.pages['/other']).toBe('2025-03-03T12:00:00.000Z'); |
| 139 | git(shallow, 'fetch', '--deepen=1'); |
| 140 | const deeper = buildContentFreshness(shallow, definitions); |
| 141 | expect(deeper.pages['/page']).toBe('2025-02-02T12:00:00.000Z'); |
| 142 | }); |
| 143 | |
| 144 | test('Vercel fetches shallow history before building and stops if the fetch fails', () => { |
| 145 | const original = repository(); |
| 146 | put(original, 'docs/page.mdx', 'original'); |
| 147 | commit(original, initial); |
| 148 | put(original, 'unrelated.txt', 'updated'); |
| 149 | commit(original, unrelated); |
| 150 | const shallow = temporaryDirectory(); |
| 151 | git(shallow, 'clone', '--depth=1', pathToFileURL(original).href, '.'); |
| 152 | const docs = join(shallow, 'docs'); |
| 153 | const definitions = [{ pathname: '/page', sources: ['page.mdx'] }]; |
| 154 | expect(buildContentFreshness(docs, definitions).pages['/page']).toBeUndefined(); |
| 155 | |
| 156 | // Replace only the expensive app build; exercise the real Git commands. |
| 157 | const bin = temporaryDirectory(); |
| 158 | put(bin, 'bun', '#!/bin/sh\nset -eu\ntest "$1" = run\ntest "$2" = build\ngit rev-parse --is-shallow-repository > build-history-state\n'); |
| 159 | chmodSync(join(bin, 'bun'), 0o755); |
| 160 | const script = fileURLToPath(new URL('../../scripts/vercel-build.sh', import.meta.url)); |
| 161 | const run = () => execFileSync('sh', [script], { |
| 162 | cwd: docs, stdio: ['ignore', 'pipe', 'pipe'], |
| 163 | env: { ...process.env, PATH: `${bin}:${process.env.PATH}` }, |
| 164 | }); |
| 165 | run(); |
| 166 | expect(readFileSync(join(docs, 'build-history-state'), 'utf8').trim()).toBe('false'); |
| 167 | expect(buildContentFreshness(docs, definitions).pages['/page']).toBe('2025-01-01T12:00:00.000Z'); |
| 168 | |
| 169 | // Complete clones do not need a reachable remote. |
| 170 | git(shallow, 'remote', 'set-url', 'origin', join(original, 'missing')); |
| 171 | run(); |
| 172 | |
| 173 | // A failed fetch must stop before the build can publish unknown dates. |
| 174 | git(shallow, 'fetch', '--depth=1', pathToFileURL(original).href); |
| 175 | rmSync(join(docs, 'build-history-state')); |
| 176 | expect(() => run()).toThrow(); |
| 177 | expect(existsSync(join(docs, 'build-history-state'))).toBe(false); |
| 178 | }); |
| 179 | |
| 180 | test('persists the artifact and serves it after source and Git removal', async () => { |
| 181 | const root = repository(); |
| 182 | put(root, 'page.mdx', 'original'); |
| 183 | commit(root, initial); |
| 184 | const manifest = buildContentFreshness(root, [{ pathname: '/page', sources: ['page.mdx'] }]); |
| 185 | const artifact = join(root, 'content-freshness.json'); |
| 186 | writeFileSync(artifact, JSON.stringify(manifest)); |
| 187 | rmSync(join(root, '.git'), { recursive: true }); |
| 188 | rmSync(join(root, 'page.mdx')); |
| 189 | const read = createPageLastUpdatedReader(artifact); |
| 190 | expect(await read('/page')).toBe('2025-01-01T12:00:00.000Z'); |
| 191 | expect(await read('/missing')).toBeNull(); |
| 192 | expect(await read('toString')).toBeNull(); |
| 193 | expect(await createPageLastUpdatedReader(join(root, 'missing.json'))('/page')).toBeNull(); |
| 194 | put(root, 'invalid.json', '{"version":1,"pages":{"/page":"not-a-timestamp"}}'); |
| 195 | expect(await createPageLastUpdatedReader(join(root, 'invalid.json'))('/page')).toBeNull(); |
| 196 | }); |
| 197 | }); |