docs: fix docs build

[muratkeremozcan]

• Add new docs job to quality.yaml workflow to validate links and build docs
• Add docs:validate-links and docs:build to pre-commit hook
• Fix broken internal links in risk-based-testing.md and test-quality-standards.md
• Increase LLM character limits from 600k/500k to 800k/700k

[coderabbitai]

📝 Walkthrough

Walkthrough

The changes add documentation validation and build steps to the GitHub Actions CI/CD workflow and Git hooks (pre-commit and pre-push), update cross-references between documentation files, and adjust documentation build tool configuration to support larger LLM input sizes.

Changes

Cohort / File(s)	Summary
CI/CD and Git Hooks .github/workflows/quality.yaml, .husky/pre-commit, .husky/pre-push	Introduces docs validation and build steps: new GitHub Actions job runs npm run docs:validate-links and npm run docs:build; pre-commit hook executes the same two npm scripts after tests; new pre-push hook runs both scripts before pushing.
Documentation Link Updates docs/explanation/tea/risk-based-testing.md, docs/explanation/tea/test-quality-standards.md	Updates anchor references in documentation: changes anchor targets from test-priorities-matrix to quality-standards and updates multiple internal links pointing to knowledge base entries to use quality-standards anchor.
Build Tool Configuration tools/build-docs.js	Increases LLM input limits (max from 600,000 to 800,000 characters; warning threshold from 500,000 to 700,000) and removes NODE_OPTIONS flag suppression (--disable-warning=MODULE_TYPELESS_PACKAGE_JSON) from Astro build step.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: fix docs build' directly summarizes the main change—fixing the docs build process through workflow updates, hook modifications, and link corrections.
Description check	✅ Passed	The description comprehensively outlines all key changes: workflow job addition, hook updates, internal link fixes, and character limit increases—all matching the changeset.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/fix-docs-build

---

🧹 Recent nitpick comments

.husky/pre-push (1)

1-4: Consider adding set -e for early exit on failure.

Without set -e, if docs:validate-links fails, docs:build will still execute before the hook ultimately fails. Adding set -e would exit immediately on the first failure, saving time.

Suggested improvement

 #!/usr/bin/env sh
+set -e
 
 npm run docs:validate-links
 npm run docs:build

Note: Since pre-commit already runs these same commands, this pre-push hook serves as an additional safety net for commits that bypass pre-commit (e.g., --no-verify).

.husky/pre-commit (1)

8-9: Reconsider running docs tasks in pre-commit given the redundancy and performance cost.

The docs commands now run in both pre-commit (lines 8-9) and pre-push, creating redundancy. More importantly, running docs:build on every commit could significantly slow the commit workflow—particularly for non-documentation changes. This combined with lint-staged and npm test may frustrate developers.

Consider:

1. Remove from pre-commit, keep only in pre-push and CI
2. Add a conditional to run only when docs files are staged
3. Measure the actual build time; if acceptable, document this expectation for contributors

tools/build-docs.js (1)

331-340: Consider removing the redundant env option.

After removing the NODE_OPTIONS augmentation, the env option now just spreads process.env without modifications. This is the default behavior for execSync, making the explicit env property unnecessary.

Suggested simplification

 function runAstroBuild() {
   console.log('  → Running astro build...');
   execSync('npx astro build --root website', {
     cwd: PROJECT_ROOT,
     stdio: 'inherit',
-    env: {
-      ...process.env,
-    },
   });
 }

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 66e7d3a and 4001b17.

📒 Files selected for processing (6)

• .github/workflows/quality.yaml
• .husky/pre-commit
• .husky/pre-push
• docs/explanation/tea/risk-based-testing.md
• docs/explanation/tea/test-quality-standards.md
• tools/build-docs.js

🧰 Additional context used

📓 Path-based instructions (2)

**/*

⚙️ CodeRabbit configuration file

**/*: Focus on inconsistencies, contradictions, edge cases and serious issues.
Avoid commenting on minor issues such as linting, formatting and style issues.
When providing code suggestions, use GitHub's suggestion format:

<code changes>

Files:

• docs/explanation/tea/risk-based-testing.md
• tools/build-docs.js
• docs/explanation/tea/test-quality-standards.md

**/*.js

⚙️ CodeRabbit configuration file

**/*.js: CLI tooling code. Check for: missing error handling on fs operations,
path.join vs string concatenation, proper cleanup in error paths.
Flag any process.exit() without error message.

Files:

• tools/build-docs.js

🔇 Additional comments (4)

docs/explanation/tea/risk-based-testing.md (1)

253-253: Anchor update looks correct.

The updated anchor #quality-standards aligns with similar changes in test-quality-standards.md. The new docs:validate-links CI step will verify this link is valid.

.github/workflows/quality.yaml (1)

72-91: LGTM!

The new docs job follows the established pattern of other jobs in this workflow (checkout → setup node → install → run tasks). Running docs validation and build in CI ensures documentation integrity is enforced on all PRs.

docs/explanation/tea/test-quality-standards.md (1)

869-870: Use more precise links to specific fragments instead of generic section anchor.

Both links point to #quality-standards, but the link text ("Test Quality Fragment" and "Test Levels Framework Fragment") suggests they should point to specific fragments. In the knowledge base, test-quality and test-levels-framework are separate fragments within the Quality & Standards section. Consider linking directly to the fragment files for clarity:

- [Test Quality Fragment](/docs/reference/tea/knowledge-base.md#quality--standards) or directly to `docs/modules/bmm/testarch/knowledge/test-quality.md`
- [Test Levels Framework Fragment](/docs/reference/tea/knowledge-base.md#quality--standards) or directly to `docs/modules/bmm/testarch/knowledge/test-levels-framework.md`

Alternatively, if you want to keep linking to the knowledge base, either use a more generic anchor link text (e.g., "Quality & Standards Fragments") or ensure the link text matches the destination.

tools/build-docs.js (1)

27-28: LGTM! Increased LLM size limits.

The 33% increase in character limits (600K→800K max, 500K→700K warning) accommodates larger documentation while maintaining a reasonable warning buffer before the hard limit.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[alexeyv]

This suppresses a noisy warning about a problem that we're already well aware of. Why does it need to be deleted? PR comment doesn't mention it.

[muratkeremozcan]

This suppresses a noisy warning about a problem that we're already well aware of. Why does it need to be deleted? PR comment doesn't mention it.

Because it was breaking docs:build locally. Node 22 rejects that NODE_OPTIONS flag:

node: --disable-warning= is not allowed in NODE_OPTIONS

So the build died before Astro even ran. Removing the override lets Astro run normally.