{"record":{"id":"4c9592e4532bfc1d","repo":"tinyhumansai/openhuman","slug":"generated-block-markers-not-found-in-frontend-do","errorCode":null,"errorMessage":"generated-block markers not found in ${FRONTEND_DOC}; expected HTML comments containing \"${BLOCK_BEGIN_TOKEN}\" and \"${BLOCK_END_TOKEN}\"","messagePattern":"generated-block markers not found in (.+?); expected HTML comments containing \"(.+?)\" and \"(.+?)\"","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"scripts/generate-architecture-docs.mjs","lineNumber":120,"sourceCode":"    '',\n  ];\n}\n\n/**\n * Splice freshly rendered body lines into `docSource` between the BEGIN/END\n * marker lines (markers preserved). Returns the updated document text.\n *\n * @param {string} docSource\n * @param {string[]} bodyLines\n * @returns {string}\n * @throws if the markers are missing or out of order\n */\nexport function spliceGeneratedBlock(docSource, bodyLines) {\n  const lines = docSource.split('\\n');\n  const beginIdx = lines.findIndex(l => l.includes(BLOCK_BEGIN_TOKEN));\n  const endIdx = lines.findIndex(l => l.includes(BLOCK_END_TOKEN));\n  if (beginIdx === -1 || endIdx === -1) {\n    throw new Error(\n      `generated-block markers not found in ${FRONTEND_DOC}; expected HTML comments ` +\n        `containing \"${BLOCK_BEGIN_TOKEN}\" and \"${BLOCK_END_TOKEN}\"`\n    );\n  }\n  if (endIdx <= beginIdx) {\n    throw new Error('generated-block END marker must come after the BEGIN marker');\n  }\n  const next = [...lines.slice(0, beginIdx + 1), ...bodyLines, ...lines.slice(endIdx)];\n  return next.join('\\n');\n}\n\n/**\n * Compute the desired doc content from the current sources.\n * @returns {{ updated: string, current: string }}\n */\nexport function computeFrontendDoc() {\n  const providers = parseProviderChain(readFileSync(APP_TSX, 'utf8'));\n  const current = readFileSync(FRONTEND_DOC, 'utf8');","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/tinyhumansai/openhuman/blob/a221052e0df5b1f7598fceba7329fd1af95d6699/scripts/generate-architecture-docs.mjs#L102-L138","documentation":"Thrown by spliceGeneratedBlock() when gitbooks/developing/architecture/frontend.md has no line containing the literal tokens 'BEGIN GENERATED: provider-chain' / 'END GENERATED: provider-chain' (inside HTML comments). The generator replaces only the content between those comments; if either marker line is gone it cannot splice and refuses to rewrite the whole doc.","triggerScenarios":"Running `pnpm docs:generate` or `--check` after the generated block in frontend.md — including its `<!-- BEGIN GENERATED: provider-chain -->` / `<!-- END GENERATED: provider-chain -->` comment lines — was deleted, or the doc file was recreated/renamed so FRONTEND_DOC resolves to a file without markers.","commonSituations":"Someone 'tidying' the doc removes what looks like stray HTML comments; a docs restructure moves the provider-chain section to a new file without carrying the marker comments; a merge conflict resolution drops the marker lines.","solutions":["Restore the two HTML comment markers in gitbooks/developing/architecture/frontend.md, e.g. `git checkout HEAD -- gitbooks/developing/architecture/frontend.md` or copy them from git history","If the section was intentionally relocated, wrap the table in the new location with `<!-- BEGIN GENERATED: provider-chain -->` and `<!-- END GENERATED: provider-chain -->` exactly (token text is matched by substring)","Re-run `node scripts/generate-architecture-docs.mjs` and verify only the region between markers changed"],"exampleFix":"<!-- before — markers stripped from frontend.md -->\n| # | Component | Role |\n|---|-----------|------|\n\n<!-- after — markers restored around the generated table -->\n<!-- BEGIN GENERATED: provider-chain -->\n| # | Component | Role |\n|---|-----------|------|\n<!-- END GENERATED: provider-chain -->","handlingStrategy":"validation","validationCode":"const doc = readFileSync('gitbooks/developing/architecture/frontend.md', 'utf8');\nconst hasBegin = doc.includes('BEGIN GENERATED: provider-chain');\nconst hasEnd = doc.includes('END GENERATED: provider-chain');\nif (!hasBegin || !hasEnd) {\n  console.error(`frontend.md marker check: BEGIN=${hasBegin} END=${hasEnd} — restore the HTML comment markers`);\n  process.exit(1);\n}","typeGuard":null,"tryCatchPattern":"try {\n  spliceGeneratedBlock(docSource, bodyLines);\n} catch (err) {\n  if (err.message.includes('generated-block markers not found')) {\n    console.error('frontend.md lost its <!-- BEGIN/END GENERATED: provider-chain --> comments — restore from git');\n    process.exitCode = 1;\n  } else throw err;\n}","preventionTips":["Never hand-edit or delete the BEGIN/END GENERATED HTML comments when touching frontend.md — only content between them is regenerated","If the section must move, move the marker pair with the table in the same commit and run `pnpm docs:check`","Protect the markers in review: any diff deleting `<!-- BEGIN GENERATED` / `<!-- END GENERATED` lines deserves a hard look"],"tags":["docs","codegen","markdown","drift"],"backgroundTag":null,"analyzedSha":"a221052e0df5b1f7598fceba7329fd1af95d6699","analyzedAt":"2026-08-16T12:47:06.542Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}