{"record":{"id":"a7ec8d0631a7023b","repo":"koala73/worldmonitor","slug":"llms-txt-path-must-carry-a-comparisons-anchor-heading","errorCode":null,"errorMessage":"${LLMS_TXT_PATH} must carry a \"${COMPARISONS_ANCHOR_HEADING}\" heading to anchor the Comparisons section","messagePattern":"(.+?) must carry a \"(.+?)\" heading to anchor the Comparisons section","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/build-llms-full.mjs","lineNumber":286,"sourceCode":" * Live Instances the first time. Idempotent, so --check can diff it.\n */\nexport function withComparisonsSection(llmsTxt) {\n  const text = String(llmsTxt);\n  const block = renderComparisons();\n  const headings = [...text.matchAll(/^## Comparisons$/gm)];\n  if (headings.length > 1) {\n    throw new Error(`${LLMS_TXT_PATH} carries ${headings.length} \"${COMPARISONS_HEADING}\" headings; keep exactly one`);\n  }\n  if (headings.length === 1) {\n    const start = headings[0].index;\n    const nextHeading = text.indexOf('\\n## ', start + COMPARISONS_HEADING.length);\n    const end = nextHeading === -1 ? text.length : nextHeading;\n    return `${text.slice(0, start)}${block}\\n${text.slice(end)}`;\n  }\n  const anchor = `\\n${COMPARISONS_ANCHOR_HEADING}\\n`;\n  const at = text.indexOf(anchor);\n  if (at === -1) {\n    throw new Error(`${LLMS_TXT_PATH} must carry a \"${COMPARISONS_ANCHOR_HEADING}\" heading to anchor the Comparisons section`);\n  }\n  return `${text.slice(0, at + 1)}${block}\\n${text.slice(at)}`;\n}\n\nexport function buildLlmsFullText({ rootDir = ROOT } = {}) {\n  const existing = existsSync(join(rootDir, OUTPUT_PATH))\n    ? read(rootDir, OUTPUT_PATH)\n    : '';\n  const prefix = withVersionHeader(briefPrefix(existing), readVersionHeader(rootDir));\n  const introduction = [\n    LLMS_FULL_GENERATED_HEADING,\n    '',\n    'The sections below are produced by `npm run build:llms-full` from the source catalog, comparison-page registry, glossary terms, chokepoint methodology, published chokepoint explainers, the forecast accuracy snapshot, the Country Resilience Index methodology, the corrections log, and the current published ranking snapshot.',\n    '',\n    renderSourceDirectory(rootDir),\n    '',\n    renderComparisons().trim(),\n    '',","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/koala73/worldmonitor/blob/7d06c8633d256c18e38133030bc3613976a96ec9/scripts/build-llms-full.mjs#L268-L304","documentation":"When llms.txt has no existing '## Comparisons' heading, withComparisonsSection inserts the block before a designated anchor heading (COMPARISONS_ANCHOR_HEADING). If that anchor heading is absent from the document, there is no defined insertion point, so the function throws.","triggerScenarios":"Calling withComparisonsSection on llms.txt that lacks both the '## Comparisons' section and the required COMPARISONS_ANCHOR_HEADING heading — e.g. a rewritten or truncated llms.txt that dropped the anchor section.","commonSituations":"Regenerating llms.txt from scratch with a template that omitted the anchor heading; manual editing removed the section the anchor lived in; upstream doc restructure renamed headings.","solutions":["Add the required anchor heading (the exact COMPARISONS_ANCHOR_HEADING text, on its own line) to llms.txt at the point where Comparisons should precede.","Or add the '## Comparisons' section itself via npm run build:llms-full after restoring the standard document structure.","Update the generation template so the anchor heading is always emitted before running withComparisonsSection."],"exampleFix":"// before (llms.txt, anchor missing)\n## Endpoints\n...\n// after\n## Comparison anchors\n...\n## Endpoints\n...","handlingStrategy":"validation","validationCode":"if (!text.includes(`\\n${COMPARISONS_ANCHOR_HEADING}\\n`)) throw new Error('anchor heading missing from llms.txt');","typeGuard":null,"tryCatchPattern":"try { out = withComparisonsSection(txt); } catch (e) { console.error('Restore anchor heading:', e.message); process.exit(1); }","preventionTips":["Keep the anchor heading in the llms.txt generation template.","Add a structural smoke test asserting required headings exist.","Avoid wholesale rewrites of llms.txt by hand."],"tags":["build","llms-txt","missing-heading"],"backgroundTag":"internal-invariant-violation","analyzedSha":"7d06c8633d256c18e38133030bc3613976a96ec9","analyzedAt":"2026-09-15T16:44:39.439Z","contentChangedAt":"2026-09-15T16:44:39.439Z","schemaVersion":2},"datasetVersion":"2026-09-15T18:17:12.389Z"}