feat: enable AI-ready Blume docs - #7
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (6)
📒 Files selected for processing (9)
🚧 Files skipped from review as they are similar to previous changes (8)
📝 WalkthroughWalkthroughThe PR configures external Ask AI and selective OpenAPI indexing, patches Blume to propagate those settings, generates a versioned documentation corpus, and strengthens build verification for Pagefind, llms files, routes, and generated artifacts. ChangesDocs publishing and indexing
Estimated code review effort: 4 (Complex) | ~60 minutes Sequence Diagram(s)sequenceDiagram
participant AskAI.astro
participant useAskAI
participant ExternalAskEndpoint
AskAI.astro->>useAskAI: pass configured endpoint
useAskAI->>ExternalAskEndpoint: send request or stream
ExternalAskEndpoint-->>useAskAI: return Ask AI response
useAskAI-->>AskAI.astro: render response
Possibly related PRs
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
06a5ffe to
1d1f016
Compare
![chatgpt-codex-connector[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 06a5ffe6d4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| for (const entry of entries) { | ||
| if (entry.isDirectory() && skippedDirectories.has(entry.name)) { | ||
| if (skippedDirectories.has(entry.name)) { |
There was a problem hiding this comment.
When an entry named dist, .blume, or another skipped name is a symlink rather than a directory, this unconditional check skips it before the entry.isSymbolicLink() branch. A committed dist -> /home/alice/... symlink would therefore pass verify:public-safety even though the scanner is specifically designed to reject absolute symlink targets; retain the directory type check or handle skipped-name symlinks explicitly.
AGENTS.md reference: AGENTS.md:L19-L21
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
scripts/verify-routes.mjs (1)
255-259: 🔒 Security & Privacy | 🟠 Major | ⚡ Quick winRequire
llms.txtto contain the sitemap URL set.Equal counts and
/docsscope still allow a platform URL or duplicate to replace a public sitemap URL. Require every sitemap URL to appear inllmsPageUrls, as thellms-full.txtcheck already does.Proposed fix
if ( llmsPageUrls.length !== sitemapUrls.length || + sitemapUrls.some((url) => !llmsPageUrls.includes(url)) || llmsPageUrls.some( (url) => !url.startsWith(`${docsRoot}/`) && url !== docsRoot, )As per coding guidelines, “Never add non-public links or history, credentials, secrets, local absolute paths, or private repository metadata.”
🤖 Prompt for 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. In `@scripts/verify-routes.mjs` around lines 255 - 259, Update the llms.txt validation near llmsPageUrls to require every sitemap URL to be included in llmsPageUrls, not merely compare their lengths. Preserve the existing URL-scope extraction and ensure the check rejects missing, substituted, or duplicate entries while matching the containment behavior already used by the llms-full.txt validation.Source: Coding guidelines
🧹 Nitpick comments (3)
.gitattributes (1)
1-1: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueConsider pinning LF for patch files too.
-whitespacesilences diff/apply whitespace warnings but doesn't prevent EOL normalization, which can break patch application on Windows checkouts.♻️ Optional hardening
-patches/*.patch -whitespace +patches/*.patch text eol=lf -whitespace🤖 Prompt for 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. In @.gitattributes at line 1, Update the patches/*.patch attribute rule to pin patch files to LF line endings while preserving the existing whitespace-warning suppression, preventing EOL normalization from breaking patch application on Windows checkouts.patches/blume@1.1.4.patch (1)
71-87: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win
endpointaccepts any non-empty string, and the refine message is now stale.
z.string().min(1)lets a typo likeapi.spacefast.com/v1/docs/askthrough, which the island resolves as a page-relative path — a silent 404 at runtime instead of a config error. Also, the message still says onlyai.ask.baseUrlis required even thoughendpointnow satisfies the constraint.♻️ Suggested tightening (upstream patch)
- endpoint: z.string().min(1).optional(), + endpoint: z + .string() + .refine((v) => v.startsWith("/") || /^https?:\/\//u.test(v), { + message: "ai.ask.endpoint must be an absolute URL or a root-relative path.", + }) + .optional(),- message: - 'ai.ask.baseUrl is required when provider is "openai-compatible".', + message: + 'ai.ask.baseUrl or ai.ask.endpoint is required when provider is "openai-compatible".',Also applies to: 1100-1122
🤖 Prompt for 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. In `@patches/blume`@1.1.4.patch around lines 71 - 87, Update the endpoint validation in aiConfigSchema so endpoint must be an absolute, valid URL rather than merely a non-empty string, preventing page-relative paths from passing configuration validation. Revise the superRefine error message to state that either baseUrl or endpoint is required for the openai-compatible provider, and apply the same changes to the corresponding duplicate schema.package.json (1)
13-13: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winWire
test:corpusinto an aggregate script so it actually runs.None of the documented handoff commands (
check,validate,build) invoke it, so corpus regressions slip through unless someone remembers the extra step.♻️ Suggested wiring
- "check": "node scripts/verify-generated.mjs && node scripts/prepare-generated.mjs && blume check --strict --isolated", + "check": "node scripts/verify-generated.mjs && node scripts/prepare-generated.mjs && blume check --strict --isolated && node --test scripts/build-docs-corpus.test.mjs",As per coding guidelines: "Before handoff, run
bun install --frozen-lockfile,bun run verify:generated,bun run check,bun run validate,bun run build,bun run verify:public-safety, andbun run verify:routes."🤖 Prompt for 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. In `@package.json` at line 13, Wire the existing test:corpus script into the aggregate handoff validation flow so it runs through the documented check, validate, or build command. Update the relevant package.json aggregate script rather than changing the corpus test command itself, ensuring the standard handoff commands execute corpus regression tests automatically.Source: Coding guidelines
🤖 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 `@scripts/verify-public-safety.mjs`:
- Line 36: Update the skippedDirectories check in the directory traversal around
entry.name so it excludes entries only when they are real directories, not
symlinks or files; perform the directory-type check before applying the basename
exclusion, preserving validation of symlinks and files named like skipped
directories.
---
Outside diff comments:
In `@scripts/verify-routes.mjs`:
- Around line 255-259: Update the llms.txt validation near llmsPageUrls to
require every sitemap URL to be included in llmsPageUrls, not merely compare
their lengths. Preserve the existing URL-scope extraction and ensure the check
rejects missing, substituted, or duplicate entries while matching the
containment behavior already used by the llms-full.txt validation.
---
Nitpick comments:
In @.gitattributes:
- Line 1: Update the patches/*.patch attribute rule to pin patch files to LF
line endings while preserving the existing whitespace-warning suppression,
preventing EOL normalization from breaking patch application on Windows
checkouts.
In `@package.json`:
- Line 13: Wire the existing test:corpus script into the aggregate handoff
validation flow so it runs through the documented check, validate, or build
command. Update the relevant package.json aggregate script rather than changing
the corpus test command itself, ensuring the standard handoff commands execute
corpus regression tests automatically.
In `@patches/blume`@1.1.4.patch:
- Around line 71-87: Update the endpoint validation in aiConfigSchema so
endpoint must be an absolute, valid URL rather than merely a non-empty string,
preventing page-relative paths from passing configuration validation. Revise the
superRefine error message to state that either baseUrl or endpoint is required
for the openai-compatible provider, and apply the same changes to the
corresponding duplicate schema.
🪄 Autofix (Beta)
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: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 2b70a02e-80c2-4e78-afaa-b052b5329d64
⛔ Files ignored due to path filters (6)
bun.lockis excluded by!**/*.lockgenerated/cli/index.mdis excluded by!**/generated/**generated/manifest.jsonis excluded by!**/generated/**generated/openapi/api.jsonis excluded by!**/generated/**generated/openapi/platform.jsonis excluded by!**/generated/**generated/redirects.jsonis excluded by!**/generated/**
📒 Files selected for processing (9)
.gitattributesblume.config.tscontent/platforms/index.mdpackage.jsonpatches/blume@1.1.4.patchscripts/build-docs-corpus.mjsscripts/build-docs-corpus.test.mjsscripts/verify-public-safety.mjsscripts/verify-routes.mjs
1d1f016 to
5bafc01
Compare
1 participant
Summary
1.0.4to the latest published1.1.4https://api.spacefast.com/v1/docs/askllms.txt, and the AI corpusdocs-corpus.jsonfrom Blume's public agent-readable outputBlume's own MCP output stays disabled; the existing Spacefast hosted MCP now reads the same deployed corpus through spacefast/monorepo#849.
Validation
Run on Node
24.18.0, matching the repo'snode >=24engine:bun install --force --frozen-lockfilebun run test:corpus— 3 passbun run check— 0 errors, warnings, or hints across 1,186 pagesbun run validate— no broken linksbun run build— 1,187 HTML pagesbun run verify:public-safety— 992 text files and 3 symlinks scannedbun run verify:routes— 822 Pagefind records, 821 public sitemap/LLM/corpus pages, and all platform pages excludedRollout
Merge and deploy spacefast/monorepo#849 first, configure its OpenAI key, then deploy this docs change. This PR does not deploy or mutate production.
Need help on this PR? Tag
@codesmithwith what you need. Autofix is disabled.Summary by CodeRabbit
docs-corpus.json) for downstream tooling.