{"record":{"id":"89ed2259854d2482","repo":"koala73/worldmonitor","slug":"developments-coverage-ratio-env-must-be-a-ratio-in-0-1-got","errorCode":null,"errorMessage":"${DEVELOPMENTS_COVERAGE_RATIO_ENV} must be a ratio in (0, 1], got ${JSON.stringify(raw)}","messagePattern":"(.+?) must be a ratio in \\(0, 1\\], got (.+?)","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/build-crawlable-corpus.mjs","lineNumber":3645,"sourceCode":"// protects fails is no gate (review of #7748). Not 100%: no article pool\n// names every country every week, and a floor the weekly refresh cannot\n// clear is the #7615 mistake again.\nexport const MIN_DEVELOPMENTS_COVERAGE_RATIO_WITH_COUNTRY_INDEX = 0.6;\n\n// Operator override for the floor. A failed floor throws away the week's\n// capture (the workflow verifies before it opens the PR), so a measured-but-\n// lower week — the first freeze after the materializer redeploys, an index\n// outage that morning — needs a way to publish without a code change:\n// `workflow_dispatch` with `developments_coverage_ratio`, which the workflow\n// passes through this variable. A malformed value throws rather than\n// silently keeping the default (a typo must not look like \"no override\").\nexport const DEVELOPMENTS_COVERAGE_RATIO_ENV = 'CRAWLABLE_DEVELOPMENTS_COVERAGE_RATIO';\nexport function resolveDevelopmentsCoverageRatioOverride(env = process.env) {\n  const raw = String(env?.[DEVELOPMENTS_COVERAGE_RATIO_ENV] ?? '').trim();\n  if (!raw) return null;\n  const ratio = Number(raw);\n  if (!Number.isFinite(ratio) || ratio <= 0 || ratio > 1) {\n    throw new Error(`${DEVELOPMENTS_COVERAGE_RATIO_ENV} must be a ratio in (0, 1], got ${JSON.stringify(raw)}`);\n  }\n  return ratio;\n}\n\n// Pipeline tripwire decision (#7615, retuned in #7620 follow-up), exported for\n// tests: the per-page guard proves frozen items render; this proves the capture\n// did not collapse. `countryIndexAttempted` is the snapshot's own declaration\n// (it carries coverage.developmentsCountryIndex), so a snapshot frozen before\n// the index existed keeps the collapse floor.\nexport function assertDevelopmentsCoverage({\n  carriesDevelopments,\n  developmentsPageCount,\n  indexedCountryPageCount,\n  countryIndexAttempted = false,\n  ratioOverride = null,\n}) {\n  if (!carriesDevelopments) return;\n  const ratio = ratioOverride","sourceCodeStart":3627,"sourceCodeEnd":3663,"githubUrl":"https://github.com/koala73/worldmonitor/blob/7d06c8633d256c18e38133030bc3613976a96ec9/scripts/build-crawlable-corpus.mjs#L3627-L3663","documentation":"resolveDevelopmentsCoverageRatioOverride reads the CRAWLABLE_DEVELOPMENTS_COVERAGE_RATIO env var to let operators temporarily lower the developments-coverage floor. The value must be a finite number in (0, 1]. Anything else (non-numeric, zero, negative, or > 1) throws this error immediately during build configuration.","triggerScenarios":"Setting CRAWLABLE_DEVELOPMENTS_COVERAGE_RATIO to a non-numeric string (e.g. '0,8' with a comma), 0, a negative number, a value greater than 1, or any non-empty malformed value in the environment before running the build.","commonSituations":"Typos in CI secrets ('80%' instead of '0.8'); locale-formatted decimals with commas; someone setting a percentage (2 for 2%) instead of a ratio.","solutions":["Fix the env var to a valid ratio: a decimal number greater than 0 and at most 1 (e.g. 0.8).","Unset the variable entirely to use the built-in default floors.","If you meant a percentage, divide by 100 (80% -> 0.8).","Check CI/secret configuration for quoting or locale issues that corrupt the value."],"exampleFix":"// before\nCRAWLABLE_DEVELOPMENTS_COVERAGE_RATIO=0,8\n// after\nCRAWLABLE_DEVELOPMENTS_COVERAGE_RATIO=0.8","handlingStrategy":"validation","validationCode":"const raw = process.env.CRAWLABLE_DEVELOPMENTS_COVERAGE_RATIO;\nconst r = Number(raw);\nif (raw && !(Number.isFinite(r) && r > 0 && r <= 1)) throw new Error('ratio must be in (0,1]');","typeGuard":null,"tryCatchPattern":"try { ratio = resolveDevelopmentsCoverageRatioOverride(); } catch (e) { console.error('Bad coverage ratio env:', e.message); process.exit(2); }","preventionTips":["Always express the override as a decimal ratio, never a percentage or comma-decimal.","Document valid examples (0.5, 0.8) in CI secret names/comments.","Unset the var to fall back to defaults."],"tags":["env-var","config","build"],"backgroundTag":"invalid-env-var-value","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"}