{"record":{"id":"f60e2b19c4b3b202","repo":"koala73/worldmonitor","slug":"llms-txt-must-contain-exactly-one-openapi-yaml-byte-size","errorCode":null,"errorMessage":"llms.txt must contain exactly one OpenAPI YAML byte-size annotation","messagePattern":"llms\\.txt must contain exactly one OpenAPI YAML byte-size annotation","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/build-openapi-json.mjs","lineNumber":74,"sourceCode":"  dedupeSharedChinaProvenanceSchemas,\n  dedupeSharedResponseHeaders,\n  dedupeSharedSchemaSubtrees,\n} from './openapi-dedup-schemas.mjs';\nimport { dropUnreachableSchemas } from './openapi-drop-unreachable-schemas.mjs';\n\nconst scriptDir = dirname(fileURLToPath(import.meta.url));\n// OPENAPI_YAML_PATH exists so the capacity report's \"could not measure\" exit can\n// be exercised as a real process against a real missing/invalid source, instead\n// of being asserted from a hand-built report object that never runs the CLI.\nexport const yamlPath = process.env.OPENAPI_YAML_PATH\n  ?? resolve(scriptDir, '../docs/api/worldmonitor.openapi.yaml');\nexport const jsonPath = resolve(scriptDir, '../public/openapi.json');\nconst llmsPath = resolve(scriptDir, '../public/llms.txt');\n\nexport function withOpenApiByteSize(text, yamlBytes) {\n  const annotation = /(\\[OpenAPI specification\\]\\(https:\\/\\/www\\.worldmonitor\\.app\\/openapi\\.yaml\\), which is )[\\d,]+ bytes/g;\n  if ([...text.matchAll(annotation)].length !== 1) {\n    throw new Error('llms.txt must contain exactly one OpenAPI YAML byte-size annotation');\n  }\n  return text.replace(annotation, (_, prefix) => `${prefix}${yamlBytes.toLocaleString('en-US')} bytes`);\n}\n\nexport const DEPRECATION_POLICY_URL = 'https://www.worldmonitor.app/api-versioning.md';\nconst DEPRECATION_POLICY_HTML_URL = 'https://www.worldmonitor.app/docs/api-versioning';\n\nfunction injectDeprecationPolicyMetadata(spec) {\n  spec.components ??= {};\n  spec.components.headers ??= {};\n  spec.components.headers.Deprecation ??= {\n    description:\n      'RFC 9745. Present only when this operation or version is deprecated; omitted while the surface is current. Value is the deprecation instant as an HTTP Structured Field date (for example `@1782864000`).',\n    schema: { type: 'string', examples: ['@1782864000'] },\n  };\n  spec.components.headers.Sunset ??= {\n    description:\n      'RFC 8594. Present only when this operation or version is deprecated. Final availability date in HTTP-date format (for example `Thu, 31 Dec 2026 23:59:59 GMT`).',","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/koala73/worldmonitor/blob/7d06c8633d256c18e38133030bc3613976a96ec9/scripts/build-openapi-json.mjs#L56-L92","documentation":"withOpenApiByteSize rewrites the single byte-size annotation for the OpenAPI YAML link in llms.txt. It requires exactly one match of the '[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml), which is N bytes' pattern; zero or multiple matches throw, because updating the size would otherwise be ambiguous or impossible.","triggerScenarios":"Running build-openapi-json when public/llms.txt is missing the byte-size annotation entirely, has a malformed size (not digits/commas, e.g. 'about N bytes'), or contains the annotation twice.","commonSituations":"Manual editing of llms.txt removed or reworded the annotation sentence; a merge duplicated the paragraph; annotation format drifted from the regex after copy changes.","solutions":["Open public/llms.txt and restore exactly one sentence matching '[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml), which is <digits> bytes'.","Remove any duplicate copies of the annotation.","Prefer regenerating the file (npm run build:llms-full) rather than editing by hand, then rerun build-openapi-json."],"exampleFix":"// before (llms.txt)\n[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml) - see the file.\n// after\n[OpenAPI specification](https://www.worldmonitor.app/openapi.yaml), which is 12,345 bytes.","handlingStrategy":"validation","validationCode":"const re = /\\[OpenAPI specification\\]\\(https:\\/\\/www\\.worldmonitor\\.app\\/openapi\\.yaml\\), which is [\\d,]+ bytes/g;\nif ([...llmsTxt.matchAll(re)].length !== 1) throw new Error('exactly one OpenAPI byte-size annotation required');","typeGuard":null,"tryCatchPattern":"try { txt = withOpenApiByteSize(txt, yamlBytes); } catch (e) { console.error('Fix llms.txt annotation:', e.message); process.exit(1); }","preventionTips":["Preserve the exact annotation sentence format when editing docs.","Regenerate llms.txt rather than editing the annotation manually.","Keep the annotation in one canonical paragraph only."],"tags":["build","openapi","llms-txt"],"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"}