Repository navigation
feat(website): migrate to a full Starlight documentation site - #32
Conversation
Co-Authored-By: Petr Plenkov <petr.plenkov@gmail.com>
🤖 CodeAnt AI — Review Status
|
MergerNeeds Review PR exceeds the merge-gate context budget (74495 tokens); escalating to a human reviewer. Commit |
codeant-ai
Bot
added
the
size:L
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
📜 Recent review details⏰ Context from checks skipped due to timeout. (1)
🧰 Additional context used🧠 Learnings (1)📚 Learning: 2026-08-11T20:48:21.146ZApplied to files:
🔇 Additional comments (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe website moves to Astro Starlight. A synchronization script generates documentation content and routes. Mermaid diagrams render in the browser. Legacy pages, layouts, generated declarations, and global styles are removed. ChangesWebsite documentation system
Estimated code review effort: 4 (Complex) | ~45 minutes Sequence Diagram(s)sequenceDiagram
participant Developer
participant SyncDocs
participant Starlight
participant Browser
participant Mermaid
Developer->>SyncDocs: run dev, build, or check
SyncDocs->>Starlight: generate documentation content and routes
Starlight->>Browser: serve or build documentation pages
Browser->>Mermaid: initialize and render Mermaid blocks
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
There was a problem hiding this comment.
Review Summary
This PR successfully migrates the website to Astro Starlight with comprehensive documentation rendering. The implementation is well-structured with proper script integration and configuration.
Critical Issues Found
Three empty catch blocks in sync-docs.ts that silently suppress errors:
- Directory walking failures (line 69-71)
- Docs root cleanup failures (line 179-181)
- Mermaid copy failures (line 201-203)
These silent failures could result in incomplete builds or broken diagrams without warning. Adding console.warn statements will provide visibility during the build process.
Validation Status
All CI checks passed (lint, typecheck, test, build) as noted in the PR description, indicating the changes are functionally correct aside from the error handling issues noted above.
You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.
PR Summary by QodoMigrate website to Astro Starlight docs with synced engdocs/specs
AI Description
Diagram
High-Level Assessment
Files changed (10)
|
Up to standards ✅🟢 Issues
|
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull Request Overview
The migration to Astro Starlight is structurally complete, but the custom synchronization logic in 'website/scripts/sync-docs.ts' presents significant risks. This script is identified as high-complexity and lacks any unit test coverage. A critical defect was found where the script overwrites existing frontmatter metadata, which will result in the loss of Starlight-specific sidebar and SEO configurations.
Furthermore, the link transformation logic uses non-context-aware regular expressions that risk corrupting Markdown links within code blocks or backticks. There is also a configuration discrepancy in 'robots.txt' where a hardcoded URL conflicts with the dynamic site configuration, potentially impacting SEO. It is recommended to address the frontmatter preservation and link transformation robustness before merging.
About this PR
- The documentation synchronization script relies heavily on complex regular expressions for link rewriting and frontmatter parsing without any unit tests. This creates a high risk of regressions as documentation structures evolve.
Test suggestions
- Documentation sync correctly maps source directories (e.g., engdocs/user) to destination routes.
- Internal link transformation logic correctly resolves relative paths and preserves anchors.
- Frontmatter injection correctly extracts the first H1 header as the page title.
- Mermaid initialization script correctly identifies and processes language-mermaid blocks in the DOM.
- Sitemap generation in robots.txt aligns with the configured SITE_URL.
- Directory walking handles missing source folders gracefully without silent failures.
Prompt proposal for missing tests
Consider implementing these tests if applicable:
1. Documentation sync correctly maps source directories (e.g., engdocs/user) to destination routes.
2. Internal link transformation logic correctly resolves relative paths and preserves anchors.
3. Frontmatter injection correctly extracts the first H1 header as the page title.
4. Mermaid initialization script correctly identifies and processes language-mermaid blocks in the DOM.
5. Sitemap generation in robots.txt aligns with the configured SITE_URL.
6. Directory walking handles missing source folders gracefully without silent failures.
TIP Improve review quality by adding custom instructions
TIP How was this review? Give us feedback
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/public/robots.txt`:
- Line 4: The sitemap entry in robots.txt is hardcoded to the GitHub Pages
deployment and conflicts with the SITE_URL default in astro.config.mjs. Update
the robots.txt generation or configuration to derive the sitemap URL from
SITE_URL, ensuring the default build advertises the canonical sverka.dev
deployment while preserving correct behavior for alternate deployments.
In `@website/scripts/sync-docs.ts`:
- Around line 185-194: Update the frontmatter handling in the document sync flow
around parseFrontmatter and the generated frontmatter string to preserve all
existing source metadata. Merge existingFrontmatter with generated title and
description, only supplying those generated fields when they are absent from the
source frontmatter, then write the merged result with newBody.
In `@website/src/content/docs/index.mdx`:
- Around line 10-14: Update the landing-page hero action links, including the
“Read the docs” entry, to use base-path-aware relative URLs or Astro’s
configured base URL instead of root-relative paths. Preserve the existing
destinations and styling while ensuring deployments under BASE_PATH resolve
correctly.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: a4538481-f623-4e01-8c07-9f68b5433f14
⛔ Files ignored due to path filters (1)
website/bun.lockis excluded by!**/*.lock
📒 Files selected for processing (19)
website/.astro/content-assets.mjswebsite/.astro/content-modules.mjswebsite/.astro/content.d.tswebsite/.astro/types.d.tswebsite/.gitignorewebsite/astro.config.mjswebsite/package.jsonwebsite/public/robots.txtwebsite/scripts/sync-docs.tswebsite/src/content.config.tswebsite/src/content/docs/.gitignorewebsite/src/content/docs/index.mdxwebsite/src/layouts/Base.astrowebsite/src/pages/404.astrowebsite/src/pages/docs.astrowebsite/src/pages/getting-started.astrowebsite/src/pages/index.astrowebsite/src/styles/custom.csswebsite/src/styles/global.css
💤 Files with no reviewable changes (10)
- website/.astro/types.d.ts
- website/.astro/content-assets.mjs
- website/.astro/content-modules.mjs
- website/src/pages/404.astro
- website/src/pages/docs.astro
- website/src/pages/index.astro
- website/src/pages/getting-started.astro
- website/src/styles/global.css
- website/.astro/content.d.ts
- website/src/layouts/Base.astro
📜 Review details
⏰ Context from checks skipped due to timeout. (1)
- GitHub Check: Codacy Static Code Analysis
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: - Noany: Useunknownand narrow. Strict TypeScript.
- Error handling: Custom error classes per package.
Files:
website/src/content.config.tswebsite/scripts/sync-docs.ts
🧠 Learnings (1)
📚 Learning: 2026-08-12T07:24:02.495Z
Learnt from: CR
Repo: sverka-dev/sverka PR: 0
File: AGENTS.md:0-0
Timestamp: 2026-08-12T07:24:02.495Z
Learning: Applies to **/src/index.ts : - **Public API:** Everything public is exported from `src/index.ts`.
Applied to files:
website/.gitignorewebsite/src/content/docs/.gitignore
🪛 ast-grep (0.45.1)
website/scripts/sync-docs.ts
[warning] 183-183: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.readFile(entry.srcPath, "utf-8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
(detect-non-literal-fs-filename-typescript)
[warning] 193-193: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.writeFile(entry.destPath, frontmatter + newBody, "utf-8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
(detect-non-literal-fs-filename-typescript)
🪛 GitHub Check: SonarCloud Code Analysis
website/scripts/sync-docs.ts
[warning] 76-76: Prefer .at(…) over [….length - index].
[warning] 133-133: Simplify this regular expression to reduce its runtime, as it has super-linear performance due to backtracking.
[warning] 192-192: Refactor this code to not use nested template literals.
[warning] 99-99: Use the "RegExp.exec()" method instead.
[warning] 107-107: Use the "RegExp.exec()" method instead.
[warning] 107-107: Simplify this regular expression to reduce its runtime, as it has super-linear performance due to backtracking.
🔇 Additional comments (7)
website/package.json (1)
7-17: LGTM!website/.gitignore (1)
1-7: LGTM!website/astro.config.mjs (1)
38-38: 🎯 Functional CorrectnessVerify favicon handling under
BASE_PATH.
asset("/mermaid.min.js")includesbasePath, butfavicon: "/favicon.svg"is root-relative. If Starlight emits this value unchanged, a GitHub Pages deployment at/sverka/requests/favicon.svginstead of/sverka/favicon.svg.Inspect the generated HTML with a non-root
BASE_PATH. Useasset("/favicon.svg")if the output is not base-prefixed.website/src/content.config.ts (1)
1-7: LGTM!website/src/content/docs/.gitignore (1)
1-3: LGTM!website/src/styles/custom.css (1)
1-12: LGTM!website/scripts/sync-docs.ts (1)
69-70: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick winDo not suppress required documentation pipeline failures.
Both catch blocks convert required-input failures into a successful but incomplete website build. Fail with contextual errors instead. Use a package-specific error class.
website/scripts/sync-docs.ts#L69-L70: throw a contextual error when a configured documentation root cannot be read.website/scripts/sync-docs.ts#L199-L203: throw a contextual error when Mermaid cannot be copied towebsite/public/mermaid.min.js.As per coding guidelines,
**/*.{ts,tsx}requires “Error handling: Custom error classes per package.”⛔ Skipped due to learnings
Learnt from: CR Repo: sverka-dev/sverka PR: 0 File: AGENTS.md:0-0 Timestamp: 2026-08-12T07:24:02.495Z Learning: Applies to **/*.{ts,tsx} : - **Error handling:** Custom error classes per package.Source: Coding guidelines
Co-Authored-By: Petr Plenkov <petr.plenkov@gmail.com>
…cted Co-Authored-By: Petr Plenkov <petr.plenkov@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/scripts/sync-docs.ts`:
- Around line 100-121: Replace the line-based frontmatter parsing and field
removal around parseFrontmatter and the metadata update flow with a YAML-aware
transform that parses complete YAML nodes, including block scalars, and
serializes the updated frontmatter while preserving the body. Ensure title and
description values are read and removed as complete YAML fields rather than
deleting only their declaration lines, reusing an available YAML frontmatter
dependency if present.
- Around line 226-230: Normalize the SITE_URL value in writeRobotsTxt before
composing sitemapUrl by removing its trailing slash, while preserving the
existing default URL and basePath handling so the generated URL contains exactly
one separator before sitemap-index.xml.
- Around line 71-72: Define a package-specific DocsSyncError that preserves the
original error as cause, then use it at every synchronization failure boundary:
website/scripts/sync-docs.ts lines 71-72 for source-directory reads, lines
216-222 for generated-docs cleanup, and lines 239-243 for Mermaid bundle
copying. Replace the generic Error throws while retaining the existing
contextual messages.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 2331a031-9613-48c6-976b-f0ca5f22fa92
📒 Files selected for processing (3)
website/.gitignorewebsite/public/robots.txtwebsite/scripts/sync-docs.ts
💤 Files with no reviewable changes (1)
- website/public/robots.txt
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: Codacy Static Code Analysis
- GitHub Check: Analyze (javascript-typescript)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx}
📄 CodeRabbit inference engine (AGENTS.md)
**/*.{ts,tsx}: - Noany: Useunknownand narrow. Strict TypeScript.
- Error handling: Custom error classes per package.
Files:
website/scripts/sync-docs.ts
🪛 ast-grep (0.45.1)
website/scripts/sync-docs.ts
[warning] 232-232: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.writeFile(path.resolve(publicDir, "robots.txt"), robots, "utf-8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
(detect-non-literal-fs-filename-typescript)
[warning] 257-257: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.readFile(entry.srcPath, "utf-8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
(detect-non-literal-fs-filename-typescript)
[warning] 272-272: Filesystem path is not a string literal; a request-/variable-derived path can enable path traversal. Validate and normalize the path before use.
Context: fs.writeFile(entry.destPath, frontmatter + linkedBody, "utf-8")
Note: [CWE-22] Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal').
(detect-non-literal-fs-filename-typescript)
🪛 GitHub Check: SonarCloud Code Analysis
website/scripts/sync-docs.ts
[warning] 101-101: Use the "RegExp.exec()" method instead.
[warning] 114-114: Prefer .at(…) over [….length - index].
[warning] 109-109: Simplify this regular expression to reduce its runtime, as it has super-linear performance due to backtracking.
[warning] 109-109: Use the "RegExp.exec()" method instead.
[warning] 114-114: Use the 'String#endsWith' method instead.
🔇 Additional comments (1)
website/.gitignore (1)
8-8: LGTM!
Code Review by Qodo
1.
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
… selector, deploy paths Co-Authored-By: Petr Plenkov <petr.plenkov@gmail.com>
…tests from astro check Co-Authored-By: Petr Plenkov <petr.plenkov@gmail.com>
|
1 participant
User description
Summary
Replaces the minimal 3-page landing site with a full Astro Starlight documentation site that renders the existing
engdocs/andspecs/trees, adds search, navigation, diagrams, and a polished theme.What changed
website/to@astrojs/starlightand removed the standalonesrc/pages/*Astro pages.website/scripts/sync-docs.tswhich copiesengdocs/user/,engdocs/architecture/,engdocs/adr/,engdocs/contributing/, andspecs/intosrc/content/docs/, renames index files (README.md,spec.md→index.md), injects Starlight frontmatter, and rewrites internal.mdlinks to directory-style URLs.src/content/docs/index.mdxlanding page uses Starlights splash template with hero actions and feature cards.astro.config.mjsnow configures Starlight (title,social,editLink,lastUpdated, custom CSS), keepsSITE_URL/BASE_PATHenv support for GitHub Pages (https://sverka-dev.github.io/sverka/), and injects a small Mermaid script so```mermaidblocks render as diagrams.src/styles/custom.css.website/.gitignoreso generated docs andpublic/mermaid.min.jsare not committed.public/robots.txtsitemap URL to/sverka/sitemap-index.xml.Validation
bun run lintpassedbun run typecheckpassedbun run testpassedbun run buildpassedbun --cwd=website run checkpassedbun --cwd=website run buildpassed withSITE_URL=https://sverka-dev.github.io BASE_PATH=/sverkaMerging this PR will deploy the expanded docs site to GitHub Pages via the existing
deploy-website.ymlworkflow.CodeAnt-AI Description
Replace the minimal website with a searchable, navigable Sverka documentation portal
What Changed
engdocs/andspecs/is published as browsable pages with navigation, search, edit links, and last-updated information.Impact
✅ One searchable home for user, engineering, and specification docs✅ Working links between published documentation pages✅ Rendered architecture diagrams💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.
Summary by cubic
Migrates the website to a full Astro Starlight docs site that builds from
engdocs/andspecs/, adding search, sidebar navigation, Mermaid diagrams, and a branded theme. Adds async-docsbuild step, per-pageeditUrl, and correctSITE_URL/BASE_PATHhandling for clean GitHub Pages deploys.New Features
website/to@astrojs/starlight; removed custom Astro pages/layouts.website/scripts/sync-docs.tsto copy docs (incl.engdocs/runbooks), rename indexes, inject frontmatter with per-pageeditUrl, and rewrite links;dev|build|checkrun it automatically.mermaidand a lightweight loader.@astrojs/sitemap.engdocs/**andspecs/**changes.Bug Fixes
sync-docs.tsfor reliability and path handling. Added tests, warn on unresolved links, fixed Mermaid selector, asset URLs underBASE_PATH, and excluded tests fromastro check.BASE_PATHis respected.Written for commit b0e303a. Summary will update on new commits.