const m = /^\[Home\]\([^)]*\)[^\n]*$/m.exec(text);

if (!m) {

return { body: text, crumbs: null };

}

const items = [...m[0].matchAll(/\[([^\]]+)\]\(([^)]+)\)/g)]

.map(([, name, url]) => ({ name: unescapeMd(name), url }));

// items[0] is the mislabelled "Home"; the real root is prepended by the layout.

const crumbs = [{ name: 'API reference', url: '/api/' }, ...items.slice(1)];

// Consume the blank line the trail sat on as well, or the removal leaves three

// consecutive newlines in the committed artifact (and in the .md mirror agents

// read). One blank line still separates the generator comment from the heading.

// Strip the newlines the trail line owned. The text before it already ends with

// the blank line that separated it from the generator comment, so that blank

// line becomes the separator for the heading and nothing is left doubled.

const after = text.slice(m.index + m[0].length).replace(/^(?:\r?\n)+/, '');

return { body: text.slice(0, m.index) + after, crumbs };

const versions = releaseVersions(pkg);

const latest = versions[versions.length - 1];

const currentMajor = majorOf(latest);

// Release timestamps, so the sitemap can date an API page by when its version

// actually shipped. Previously lastmod came from the generated file's mtime, so

// every rebuild restamped all 350 API URLs with the build date — 85% of every

// lastmod in the sitemap, which is how a site teaches Google to ignore lastmod.

const released = JSON.parse(shq(`npm view @imqueue/${pkg} time --json`));

// highest release of each past major, newest major first

const byMajor = {};

for (const v of versions) { const m = majorOf(v); if (!byMajor[m] || cmpVer(v, byMajor[m]) > 0) byMajor[m] = v; }

const archives = latestOnly

? []

: Object.keys(byMajor).map(Number).filter(m => m < currentMajor)

.sort((a, b) => b - a).map(m => byMajor[m]);

return { versions, latest, currentMajor, archives, highestOfMajor: byMajor, released };

const RE = new RegExp(

`^\\s*export\\s*(?:type\\s*)?(?:\\{[^}]*\\}|\\*(?:\\s+as\\s+\\w+)?)\\s*from\\s*['"]${modulePattern}['"];?\\s*$`,

'gm',

);

const walk = (d) => {

for (const e of fs.readdirSync(d, { withFileTypes: true })) {

if (e.isDirectory()) { if (!(skipNodeModules && e.name === 'node_modules')) walk(path.join(d, e.name)); }

else if (e.name.endsWith('.d.ts')) {

const p = path.join(d, e.name);

const src = fs.readFileSync(p, 'utf8');

if (RE.test(src)) fs.writeFileSync(p, src.replace(RE, ''));

}

}

};

walk(dir);

const isArchived = seg !== 'latest';

const isRoot = (b) => b === 'index' || b === pkg;

const latestUrlFor = (b) =>

isRoot(b) || !(latestFiles && latestFiles.has(b))

? `/api/${pkg}/latest/`

: `/api/${pkg}/latest/${b}/`;

const base_ = `/api/${pkg}/${seg}`;

const urlFor = (file) => {

const b = file.replace(/\.md$/, '');

return (b === 'index' || b === pkg) ? `${base_}/` : `${base_}/${b}/`;

};

const rewriteLinks = (text) => text

.replace(/\[Home\]\((?:\.\/)?index\.md\)/g, '[Home](/api/)')

.replace(/\]\((?:\.\/)?([A-Za-z0-9._-]+)\.md(#[^)]*)?\)/g,

(_m, name, anchor) => `](${urlFor(name)}${anchor || ''})`);

const outDir = path.join(ROOT, 'src', 'org', 'api', pkg, seg);

rmrf(outDir);

fs.mkdirSync(outDir, { recursive: true });

const pkgPageMd = fs.readFileSync(path.join(mdDir, `${pkg}.md`), 'utf8');

const apiNav = [];

let cur = null;

// Which cell of the current table row we are inside: 0 is the symbol column,

// 1 the summary column, -1 not in a row yet.

let cell = -1;

for (const line of pkgPageMd.split('\n')) {

const h = line.match(/^##\s+(.+?)\s*$/);

if (h) { cur = GROUPS.includes(h[1].trim()) ? { group: h[1].trim(), items: [] } : null; if (cur) apiNav.push(cur); cell = -1; continue; }

if (cur) {

const re = /\[([^\]]+)\]\((?:\.\/)?([A-Za-z0-9._-]+)\.md\)/g;

// Each group is a two-column table: the symbol link, then its summary.

// ONLY the first column is a sidebar entry. A summary routinely contains

// {@link} cross-references, which render as links to other symbols — and

// taking every link on the line pulled those in as entries too. They

// appeared under the wrong group (a function listed under Interfaces) and

// duplicated an entry that already existed elsewhere, and because the

// highlight matches on url, landing on such a page lit up two items at

// once. Attribute each link to the cell it is actually in.

if (/<tr[\s>]/.test(line)) {

cell = -1;

}

const cells = line.split(/<td[^>]*>/);

for (let i = 0; i < cells.length; i++) {

if (i > 0) {

cell++;

}

if (cell !== 0) {

continue;

}

// api-documenter escapes markdown-significant characters in link text,

// so `DEFAULT_IMQ_OPTIONS` arrives as `DEFAULT\_IMQ\_OPTIONS`. The

// sidebar renders these labels as plain text, so unescape them.

let m;

re.lastIndex = 0;

while ((m = re.exec(cells[i]))) {

cur.items.push({ name: unescapeMd(m[1]), url: urlFor(m[2]) });

}

}

}

}

if (!apiNav.length) throw new Error(`No symbols parsed for ${pkg}@${version} sidebar`);

// A url must appear once across the whole sidebar, or the current-page

// highlight marks every entry that shares it. The cell attribution above is

// what guarantees that; this asserts it rather than trusting it, since the

// failure is silent in the build and only visible as a double highlight.

const seenUrls = new Map();

for (const group of apiNav) {

for (const item of group.items) {

if (seenUrls.has(item.url)) {

throw new Error(

`Duplicate sidebar url for ${pkg}@${version}: ${item.url} listed as ` +

`"${seenUrls.get(item.url)}" and again as "${group.group}/${item.name}"`,

);

}

seenUrls.set(item.url, `${group.group}/${item.name}`);

}

}

// Build the YAML front matter for one embedded page.

//

// `description` matters: without it head.html falls back to the site slogan,

// which made 351 of the 352 indexed API pages share one meta description.

// apiDescription() lifts the per-symbol summary api-documenter already emits.

const frontMatter = (title, latestUrl, description, crumbs, unsubmitted) => {

let fm = `title: ${JSON.stringify(title)}\n`;

if (description) fm += `description: ${JSON.stringify(description)}\n`;

if (crumbs) fm += `apiCrumbs: ${JSON.stringify(crumbs)}\n`;

if (unsubmitted) fm += 'sitemap: false\n';

if (isArchived) fm += `noindex: true\nlatestUrl: ${JSON.stringify(latestUrl)}\n`;

return `---\n${fm}---\n\n`;

};

// Per-symbol MEMBER pages stay indexable but leave the sitemap. 243 of the 350

// submitted API URLs were these — a single method or property, ~130 words, and

// 15 of them documenting inherited EventEmitter methods that Node's own docs

// will always outrank. At 57% of the sitemap they spent crawl budget on pages

// that cannot rank and drowned the 73 editorial URLs in the set Google grades.

// They remain reachable from the sidebar and the breadcrumb, so Google can still

// find and index them — it just is not asked to.

//

// Two dots means a member: core.ilogger.info (member) vs core.ilogger (the

// interface) vs core.imq_log_args (a top-level const).

const isMemberPage = (b) => b.split('.').length > 2;

// Rewrite links first so the lifted trail carries site URLs, not `*.md` paths.

const prepare = (raw) => {

const { body, crumbs } = extractTrail(rewriteLinks(raw));

return { md: promoteFirstHeading(body), crumbs };

};

const archivedSuffix = isArchived ? ` v${version} (archived)` : '';

const basenames = new Set(['index']);

let count = 0;

// summary%: pages whose own summary section yields prose. Uses the very same

// summaryParagraph() that fills the meta description, so a page counted as

// failing here is exactly a page whose description had to fall back to

// "<symbol> — @imqueue/<pkg> <version> API reference."

let withProse = 0;

for (const file of fs.readdirSync(mdDir)) {

if (!file.endsWith('.md')) continue;

// api-documenter's package page is `<pkg>.md`, and it is also what index.md

// is written from. Emitting both produced two indexable URLs with identical

// content — /api/<pkg>/<seg>/<pkg>/ competing with /api/<pkg>/<seg>/, each

// self-canonical and both in the sitemap. rewriteLinks() already points

// `<pkg>.md` links at the package root, so nothing links to the duplicate.

if (file === `${pkg}.md`) continue;

// api-documenter also emits its own index.md for the model root. The package

// root page is written from `<pkg>.md` further down and overwrites it, so

// embedding it here was wasted work — and it made summary% unreachable at

// 100%: the index page was counted twice, once as this (prose-less) model page

// and once as the real package page, so every package reported one page short.

if (file === 'index.md') continue;

const b = file.replace(/\.md$/, '');

basenames.add(b);

const raw = fs.readFileSync(path.join(mdDir, file), 'utf8');

const symbol = firstHeading(raw, b);

const title = `${symbol} · @imqueue/${pkg}${archivedSuffix}`;

const desc = apiDescription(raw, { pkg, version, symbol });

const { md, crumbs } = prepare(raw);

fs.writeFileSync(path.join(outDir, file),

frontMatter(title, latestUrlFor(b), desc, crumbs, isMemberPage(b)) + md);

count++;

if (summaryParagraph(raw)) withProse++;

}

const indexTitle = `@imqueue/${pkg} ${version} · API reference${isArchived ? ' (archived)' : ''}`;

const indexDesc = apiDescription(pkgPageMd, { pkg, version, symbol: `${pkg} package` });

const indexPage = prepare(pkgPageMd);

fs.writeFileSync(path.join(outDir, 'index.md'),

frontMatter(indexTitle, `/api/${pkg}/latest/`, indexDesc, indexPage.crumbs) + indexPage.md);

// bareTitle: these titles already end with "· @imqueue/<pkg>", so letting

// head.html append its "· @imqueue" suffix produced

// "Foo.bar() method · @imqueue/core · @imqueue" — 11 wasted characters of SERP

// budget on every page, and the brand twice.

// apiReleased: npm's publish time for this version, inherited by every page in

// the tree through the data cascade. src/sitemap.liquid uses it for <lastmod>

// instead of the file mtime, which restamped all 350 API URLs on every rebuild.

fs.writeFileSync(path.join(outDir, `${seg}.11tydata.json`),

JSON.stringify({ layout: 'apiref.html', section: 'api', bareTitle: true, apiPkg: pkg, apiVersion: version, apiVersionPath: seg, apiReleased: released || null, apiNav }, null, 2));

if (summaryParagraph(pkgPageMd)) withProse++;

const pages = count + 1; // + the package-root index.md

console.log(` embedded ${count} pages -> src/org/api/${pkg}/${seg}/ (${apiNav.reduce((n, g) => n + g.items.length, 0)} symbols)`);

return { basenames, summary: { pages, withProse } };

console.log(`\n=== @imqueue/${pkg}@${version} -> /api/${pkg}/${seg}/ ===`);

const work = path.join(TMP, `${pkg}-${version}`);

rmrf(work);

fs.mkdirSync(work, { recursive: true });

sh(`npm pack @imqueue/${pkg}@${version} --pack-destination "${work}" --loglevel=error`);

const tgz = fs.readdirSync(work).find(f => f.endsWith('.tgz'));

sh(`tar xzf "${tgz}" -C "${work}"`, work);

const pkgDir = path.join(work, 'package');

const pj = require(path.join(pkgDir, 'package.json'));

const entry = pj.types || pj.typings || 'index.d.ts';

// Resolve EVERY @imqueue/* dependency for cross-package type references, but

// never bundle one (each has its own pages; bundling hits an api-extractor

// defect). Then strip its re-exports, which is what stops a package

// re-documenting symbols another package owns.

//

// This used to be hard-coded to the single `@imqueue/core` case, which handled

// exactly one in-scope package (`job`). Six others depend on an @imqueue

// package that is NOT core and so got nothing installed and nothing stripped:

//

// pg-sequelize, tag-cache, datadog -> @imqueue/rpc

// pg-cache -> @imqueue/pg-pubsub, @imqueue/rpc, @imqueue/tag-cache

// http-protect -> @imqueue/net

// type-graphql-dependency -> @imqueue/graphql-dependency

//

// Worth being precise about what that cost, because it is easy to overstate:

// those packages still EXTRACT without this (measured — pg-sequelize and datadog

// both produce complete models). What they lose is resolved cross-package types

// in signatures, and de-duplication: every symbol re-exported from a dependency

// ships a second page under this package's name, competing with the page the

// owning package publishes.

for (const [dep, range] of Object.entries(pj.dependencies || {})) {

if (!dep.startsWith('@imqueue/')) continue;

// Best-effort, matching the rest of this script: a dependency that cannot be

// installed degrades the output (unresolved types, duplicate pages) but must

// not take the whole build down.

try {

sh(`npm install ${dep}@"${range}" --no-save --no-audit --no-fund --ignore-scripts --loglevel=error`, pkgDir);

stripReexports(pkgDir, dep.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), { skipNodeModules: true });

} catch {

console.warn(` WARN could not install ${dep}@${range} for ${pkg} — its re-exported symbols will ship duplicate pages`);

}

}

// core re-exports EventEmitter from node:events; api-extractor throws a hard

// "Unsupported export" on a re-exported EXTERNAL symbol. Strip those re-export

// lines everywhere (uses as a base class still resolve fine).

stripReexports(pkgDir, '(?:node:)?events');

const cfgObj = {

$schema: 'https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json',

projectFolder: pkgDir,

mainEntryPointFilePath: path.join(pkgDir, entry),

bundledPackages: [],

// types: ['node'], not []. With no ambient Node types, api-extractor throws a

// hard `Unable to follow symbol for "Buffer"` on any package that uses Buffer

// in its public surface — @imqueue/net does, and could not be documented at

// all. Measured safe to apply globally: against published core@3.3.0 and

// rpc@3.5.1 the two settings produce identical models (169 and 202 nodes, 0

// warnings, no symbol differences), so this does not perturb the pages the

// site already publishes. @types/node is a declared devDependency for this.

compiler: { overrideTsconfig: { compilerOptions: { target: 'ESNext', module: 'nodenext', moduleResolution: 'nodenext', skipLibCheck: true, types: ['node'], lib: ['ESNext'] }, include: [entry] } },

apiReport: { enabled: false },

docModel: { enabled: true, apiJsonFilePath: path.join(work, `${pkg}.api.json`) },

dtsRollup: { enabled: false },

tsdocMetadata: { enabled: false },

messages: { compilerMessageReporting: { default: { logLevel: 'none' } }, extractorMessageReporting: { default: { logLevel: 'none' } } },

};

const cfgPath = path.join(work, 'api-extractor.json');

fs.writeFileSync(cfgPath, JSON.stringify(cfgObj));

const ec = ExtractorConfig.prepare({ configObject: ExtractorConfig.loadFile(cfgPath), configObjectFullPath: cfgPath, packageJsonFullPath: path.join(pkgDir, 'package.json') });

if (!Extractor.invoke(ec, { localBuild: true, showVerboseMessages: false }).succeeded) {

throw new Error(`API Extractor failed for ${pkg}@${version}`);

}

// Normalise the model into a shape api-documenter can represent before it runs:

// fold a declaration-merged class+interface into one symbol, and give

// same-name static/instance siblings distinct pages. Without this a legitimate

// TypeScript pattern silently loses a page — see scripts/lib/api-model.js.

const model = JSON.parse(fs.readFileSync(path.join(work, `${pkg}.api.json`), 'utf8'));

const { notes, renames } = normalizeModel(model);

for (const note of notes) {

console.log(` model: ${note}`);

}

// A rename moves the page's URL, and the old one may already be published and

// indexed. Record it so the run can emit redirects — see recordRenames().

recordRenames({ pkg, seg, renames });

const modelDir = path.join(work, 'model');

fs.mkdirSync(modelDir, { recursive: true });

fs.writeFileSync(path.join(modelDir, `${pkg}.api.json`), JSON.stringify(model));

const mdDir = path.join(work, 'md');

sh(`"${DOCUMENTER}" markdown --input-folder "${modelDir}" --output-folder "${mdDir}"`);

// Every symbol in the model must have got its own page. api-documenter builds

// filenames from lowercased symbol names and silently overwrites on a clash, so

// a lost page is otherwise invisible — see scripts/lib/api-pages.js. Asserted

// against the NORMALISED model, which is what api-documenter was given.

const counts = assertNoLostPages({

pkg,

version,

model,

emitted: fs.readdirSync(mdDir).filter(f => f.endsWith('.md')),

});

console.log(` ${counts.expected} model symbols -> ${counts.emitted} pages, no collisions`);

return embed({ pkg, version, seg, mdDir, latestFiles, released });

const dir = path.join(ROOT, 'src', 'org', 'api', pkg);

if (!fs.existsSync(dir)) return;

for (const e of fs.readdirSync(dir, { withFileTypes: true })) {

if (e.isDirectory() && !keepSegs.includes(e.name)) {

rmrf(path.join(dir, e.name));

console.log(` removed stale src/org/api/${pkg}/${e.name}/`);

}

}

const file = path.join(ROOT, 'src', 'org', '_redirects');

fs.writeFileSync(file, `# imqueue.org — Cloudflare Pages redirects.

console.log('\nWrote src/org/_redirects (API mapping lives in functions/api/)');

for (const { from, to, kind } of renames) {

// api-documenter lowercases the symbol name into the filename, and the site

// serves each page at its basename without the .md — so the slug is exactly

// what the URL's last segment is.

const slug = (name) => `${pkg}/${seg}/${pkg}.${name.toLowerCase()}`;

RENAMED_PAGES.set(slug(from), { to: slug(to), kind });

}

const file = path.join(ROOT, 'lib', 'api-renames.js');

if (!fs.existsSync(file)) return [];

const text = fs.readFileSync(file, 'utf8');

const rows = [];

for (const line of text.split('\n')) {

const m = RENAME_ROW.exec(line);

if (m) rows.push({ from: JSON.parse(m[1]), to: JSON.parse(m[2]), kind: m[3].trim() });

}

// Never let a format change here fail quietly. Every row is a published, indexed

// URL that 301s; silently parsing zero of them would emit an empty map and turn

// each one back into the 404 this file exists to prevent.

const declared = (text.match(/^\s*\[/gm) || []).length;

if (rows.length !== declared) {

throw new Error(

`lib/api-renames.js: parsed ${rows.length} of ${declared} row(s). The emitted row ` +

'format and RENAME_ROW have diverged — fix the pattern rather than regenerating, ' +

'because dropping a row turns a live 301 into a 404.',

);

}

return rows;

const fresh = [...RENAMED_PAGES.entries()]

.map(([from, { to, kind }]) => ({ from, to, kind }));

// A full build recomputes every row, so it neither reads what is on disk nor may

// be blocked by it: readExistingRenames() throws on a malformed file, and failing

// the one build that would rewrite that file correctly is the wrong trade.

if (builtPkgs.length === PKGS.length) {

return { rows: fresh, carried: 0, fresh: fresh.length };

}

const built = new Set(builtPkgs);

const pkgOf = key => key.split('/')[0];

const carried = readExistingRenames()

// An unshipped package's rows go with it, the way writeFunctions() retires its

// mount — otherwise a partial build would preserve them forever.

.filter(r => !built.has(pkgOf(r.from)) && PKGS.includes(pkgOf(r.from)));

return { rows: [...carried, ...fresh], carried: carried.length, fresh: fresh.length };

const file = path.join(ROOT, 'src', '_data', 'apiVersions.json');

// Same reasoning as mergedRenames(): a full build supplies every entry itself, so

// it does not read — and cannot be tripped by — the file it is about to replace.

const prior = Object.keys(built).length !== PKGS.length && fs.existsSync(file)

? JSON.parse(fs.readFileSync(file, 'utf8'))

: {};

const out = {};

let carried = 0;

for (const pkg of PKGS) {

if (built[pkg]) {

out[pkg] = built[pkg];

} else if (prior[pkg]) {

out[pkg] = prior[pkg];

carried++;

}

// A shipped package with neither is one that has never been built. Leaving it

// out is deliberate: it has no pages, so routing it would serve a 404.

}

return { versions: out, carried };

const rows = rowList

.map(({ from, to, kind }) => [from, { to, kind }])

.sort(([a], [b]) => a.localeCompare(b));

const body = rows

.map(([from, { to, kind }]) => ` [${JSON.stringify(from)}, ${JSON.stringify(to)}], // ${kind}`)

.join('\n');

const file = path.join(ROOT, 'lib', 'api-renames.js');

fs.mkdirSync(path.dirname(file), { recursive: true });

fs.writeFileSync(file, `// GENERATED by scripts/build-api-docs.js — do not edit by hand.

console.log(

`Wrote lib/api-renames.js — ${rows.length} page(s) 301 from a stripped ` +

'collision suffix',

);

const body = Object.entries(apiVersions)

.map(([pkg, p]) => ` ${JSON.stringify(pkg)}: { "latest": ${JSON.stringify(p.latest)}, "archives": ${JSON.stringify(p.archives)} }`)

.join(',\n');

const file = path.join(ROOT, 'lib', 'api-versions.js');

fs.mkdirSync(path.dirname(file), { recursive: true });

fs.writeFileSync(file, `// GENERATED by scripts/build-api-docs.js — do not edit by hand.

console.log(`Wrote lib/api-versions.js`);

const apiRoot = path.join(ROOT, 'src', 'org', 'api');

const entries = [];

for (const pkg of fs.readdirSync(apiRoot)) {

const pkgDir = path.join(apiRoot, pkg);

if (!fs.statSync(pkgDir).isDirectory()) continue;

for (const seg of fs.readdirSync(pkgDir)) {

const dir = path.join(pkgDir, seg);

if (!/^\d+\.\d+\.\d+$/.test(seg) || !fs.statSync(dir).isDirectory()) continue;

for (const file of fs.readdirSync(dir)) {

if (file.endsWith('.md') && file !== 'index.md') {

entries.push(`${pkg}/${seg}/${file.slice(0, -3)}`);

}

}

}

}

entries.sort();

const file = path.join(ROOT, 'lib', 'api-legacy-pages.js');