Skip to content

REVIEW.md

Latest commit

 

History

History
155 lines (130 loc) · 7.49 KB

REVIEW.md

File metadata and controls

155 lines (130 loc) · 7.49 KB
Raw

AI Code Review Checklist

Use this document when reviewing changes to the SurrealDB docs codebase. Work through each section and flag anything that does not conform. See AGENTS.md for conventions, documentation voice, and architectural detail.

1. Quality gates

  • bun run qa (Biome lint + format with auto-fix) has been run.
  • bun run qc (Biome check, read-only) passes without errors.
  • bun run qts (TypeScript --noEmit) reports no type errors.
  • No secrets, .env values, or credentials are included in the diff.

2. Language and headings

  • All user-facing text uses British English spelling: -ise (not -ize), -our (not -or), -re (not -er), -ogue (not -og).
  • Subheaders (##–####) follow sentence case (see AGENTS.md):
    • Single-word headings are capitalised (#### Parameters, ## Syntax).
    • Multi-word headings capitalise the first word only (## Type parameters, ### Complete examples).
    • Numbered headings capitalise the first word after the number (### 3. Don't reuse transactions).
    • Acronyms, product names, SDK types, and SurrealQL keywords stay capitalised where appropriate (API, RecordId, INSERT).
    • No Title Case on every main word (### Custom functions, not ### Custom Functions).

3. SOLID principles

  • Single Responsibility — each module, component, or function has one reason to change.
  • Open/Closed — behaviour is extended through composition and props, not by modifying existing code.
  • Liskov Substitution — components sharing an interface are interchangeable without breaking consumers.
  • Interface Segregation — prop interfaces and type definitions are focused; no large catch-all types.
  • Dependency Inversion — code depends on abstractions (types, interfaces, callbacks) rather than concrete implementations.

4. Component and UI conventions

  • Mantine (@mantine/core) and @surrealdb/ui components are used before creating new ones.
  • <Box> is used instead of <div>. Semantic elements use <Box component="section|nav|main|footer">.
  • <Anchor> is used instead of <a>.
  • Mantine styling props (mt, fz, gap, display, etc.) are preferred over custom CSS.
  • SCSS modules are named style.module.scss with kebab-case class names.
  • No inline style attributes for static styling — only for truly dynamic values.
  • Shared UI that could benefit other SurrealDB frontends belongs in @surrealdb/ui, not duplicated in this repo.

5. Styling

  • Global styles are limited to src/assets/styles/ (global.scss and markdown.scss).
  • Component styles use SCSS modules (style.module.scss), imported as import classes from "./style.module.scss".
  • Dark/light mode is handled via the @include light { … } mixin from @surrealdb/ui/mixins.
  • Mantine CSS variables are used where possible (--mantine-color-*, --mantine-spacing-*, --surreal-*).
  • CSS class names are kebab-case in SCSS (auto-converted to camelCase in JS).

6. TypeScript and imports

  • The path alias ~/ (mapped to src/) is used for imports.
  • Strict mode is respected — no untyped any without clear justification.
  • No unused imports (Biome noUnusedImports rule).
  • useEffect / useCallback dependencies are exhaustive (Biome useExhaustiveDependencies rule). useInputState and useStable are registered as stable hooks and do not need to appear in dependency arrays.

7. Content collection changes

  • Frontmatter matches the schema in src/content/config.ts:
    • Docs → abstractDoc (title, description, position, no_page_headings, no_sidebar — all optional).
    • Labs → labCollection (title required; url, category, author, topics, languages optional).
  • New markdown files are placed under the correct src/content/<collection>/ folder.
  • Sidebar ordering uses position in frontmatter and __category.json files in subdirectories.
  • Content slugs are derived automatically — no manual slug field is added.
  • If a new doc collection is introduced:
    • urlForCollection in src/content/config.ts is updated.
    • A corresponding +Content.ts file exists in the new collection folder.
    • Redirect logic is updated as noted in the src/content/config.ts comment.

8. Page and data loading patterns

  • Doc +data.ts files follow the standard pipeline:
    1. getCollectionPartsFromURL(urlPathname, sliceIndex)
    2. getCollectionEntry(id, slug) — 404 if not found
    3. resolveMarkdown(entry.content) — produces { ast, headings }
    4. getSidebarItemsFromCollection(id) — builds the sidebar tree
    5. Returns { ast, headings, sidebar, contentPath }
  • +Page.tsx renders via <RenderMarkdown> with registerMarkdownComponents() and getMarkdownScope().
  • +onBeforePrerenderStart.ts maps all collection entries to their URL paths when new content pages are added.
  • The correct sliceIndex is used in getCollectionPartsFromURL:
    • 2 for top-level doc sections (surrealdb, cloud, etc.)
    • 3 for SDK paths (/docs/sdk/<name>/…)

9. APIs from vike-content-collection

The project intentionally does not use the following APIs — flag any introduction of them:

API Reason not used
renderEntry Rendering uses @surrealdb/ui's parseMarkdown → AST → RenderMarkdown.
extractHeadings Custom heading extraction in src/lib/markdown.ts using github-slugger.
getBreadcrumbs Breadcrumbs are sidebar-based, not collection-hierarchy based.
getAdjacentEntries Prev/next follows sidebar tree order with __category.json.
getEntryUrl Collection names don't match URL paths; urlForCollection is used instead.
getCollectionTree Sidebar uses __category.json for structure.

10. Common pitfalls

  • Raw HTML elements (<div>, <a>, <section>, <nav>, etc.) used instead of Mantine equivalents.
  • +onBeforePrerenderStart.ts not updated after adding new content pages.
  • Wrong sliceIndex in getCollectionPartsFromURL — causes 404s.
  • American English spelling in user-facing strings.
  • Inline styles used where Mantine props or SCSS modules would suffice.
  • New component created without first checking Mantine / @surrealdb/ui for an existing solution.
  • Comments that merely narrate what the code does instead of explaining non-obvious intent.

Key files reference

File Purpose
AGENTS.md Conventions, documentation voice, architecture
src/content/config.ts Content schemas and URL mapping
src/utils/markdown.tsx Markdown rendering pipeline
src/utils/sidebar.ts Sidebar tree building
src/utils/collection.ts URL-to-slug parsing
src/lib/categories.ts __category.json loader
src/lib/markdown.ts Heading extraction
src/pages/+config.ts Vike root config
biome.json Linter and formatter rules