[] Add CI pipeline for docs site: static build, dead-link check, frontmatter validation, Pagefind index#261
Conversation
…frontmatter validation, Pagefind index
![orange-codens[bot]](https://avatars.githubusercontent.com/in/4028936?s=60&v=4){kind=small}
There was a problem hiding this comment.
🍊 Orange Codens レビュー
全体所感
重大な懸念が 2 点あります。
docs/package-lock.jsonが diff に存在しないため、CI のnpm ciステップが即座に失敗する可能性が高い (high)。PR マージ前にロックファイルの追加が必須。lychee --offlineにより外部リンクが検査されず、dead link detection の目的が半減している (high)。意図的なら明示すべき。
その他、vitest テストが CI で実行されていない、broken-link-checker が未使用のまま devDependencies に残っている、gray-matter が dependencies に誤配置されているなど、中・低優先度の整理すべき点が複数あります。
🔒 セキュリティ: 今回の変更はドキュメントサイトの CI ゲートを追加するものであり、直接的な認証・認可の欠陥や SQL インジェクション等の重大脆弱性は含まれていません。主な懸念点は validate-frontmatter.ts がエクスポートされた API として任意パスを受け取る際のパストラバーサル・シンボリックリンクフォロー、および外部 GitHub Actions をコミット SHA でピン留めしていないサプライチェーンリスクです。これらはいずれも CI 内部での脅威に限定されるため重大度は低いですが、将来的な拡張を考慮して防御的チェックの追加を推奨します。
🟠 high: 1 / 🟡 medium: 4 / 🔵 low: 5 / ⚪ info: 1
その他の指摘 (10 件)
- 🟡 [medium]
.github/workflows/ci.yml:112— CI の frontmatter 検証ステップがvitestテストではなくスタンドアロンスクリプトを実行している (confidence: 0.88,maintainability.ci.validate_step_not_in_test) - 🟡 [medium]
.github/workflows/ci.yml:107—docs/package-lock.jsonが diff に存在しないためnpm ciおよび cache が失敗する恐れがある (confidence: 0.85,code.ci.missing_package_lock) - 🟡 [medium]
docs/scripts/validate-frontmatter.ts:68— draft ページがtitleチェックをスキップしてsuccessCountに加算されない (confidence: 0.72,code.script.draft_skips_title_check) - 🟡 [medium]
docs/scripts/validate-frontmatter.ts:28— walkMdxFiles でのパストラバーサル: 入力ディレクトリの検証なし (confidence: 0.60,sec.sast.injection.path_traversal) - 🔵 [low]
docs/package.json:24—broken-link-checkerがpackage.jsonに残っているが CI ではlychee-actionを使用 (confidence: 0.90,maintainability.package.broken_link_checker_vs_lychee) - 🔵 [low]
docs/package.json:14—gray-matterがビルド時のみ使用されるのにdependenciesに含まれている (confidence: 0.82,maintainability.package.gray_matter_in_dependencies) - 🔵 [low]
docs/scripts/validate-frontmatter.ts:108—__filenameを ESM 環境で使用すると ReferenceError が発生する (confidence: 0.65,code.script.is_main_module_esm_compat) - 🔵 [low]
docs/scripts/validate-frontmatter.ts:35— シンボリックリンクのフォローによるディレクトリ外ファイルアクセスの可能性 (confidence: 0.65,sec.sast.injection.path_traversal) - 🔵 [low]
docs/scripts/validate-frontmatter.ts:50— MDX ファイルの内容をパース前にサイズ制限なしで全読み込み (confidence: 0.50,sec.sast.injection.path_traversal) - ⚪ [info]
.github/workflows/ci.yml:108— lychee-action の外部アクション参照でコミット SHA ピン留めなし (confidence: 0.95,sec.sast.authz.ci_step_ordering)
head: e22073e | Orange Codens (P1)
| run: npm run build | ||
| - name: Generate Pagefind index | ||
| run: npx pagefind --site out | ||
| - name: Check dead links |
There was a problem hiding this comment.
🟠 [high] --offline フラグにより外部リンクが検査されない
該当箇所:
args: --offline --include-fragments './out/**/*.html'lychee の --offline オプションは HTTP/HTTPS リクエストを発行せず、ローカルファイル参照のみを検証する。ドキュメントサイトに外部 URL が含まれる場合、それらは一切チェックされない。タスク要件では「dead link detection」が求められているが、外部リンク切れをこのジョブでは検出できない。
- CI コストを抑えつつ外部リンクも検証したい場合は
--offlineを除去し、--max-concurrencyで並列数を制限する。 - 意図的にオフラインのみにするなら、ステップ名や PR 説明に明示すべき。
@@ -118,1 +118,1 @@
- args: --offline --include-fragments './out/**/*.html'
+ args: --include-fragments './out/**/*.html'code.ci.dead_link_offline_only | confidence: 0.90
There was a problem hiding this comment.
🍊 Orange Codens レビュー
🔒 セキュリティ: 今回の diff は主に CI パイプラインとドキュメントビルドスクリプトの追加であり、重大な認証・認可・インジェクション脆弱性は検出されませんでした。validate-frontmatter.ts の walkMdxFiles がシンボリックリンク経由のパス逸脱に対して無防備である点と、lychee の --offline 指定により外部リンクの broken-link/subdomain-takeover チェックが機能しない点が主な指摘事項です。いずれも CI/ツールスクリプト文脈のため severity は medium 以下に抑えていますが、walkMdxFiles への任意パス入力を許容するエクスポートAPIについては境界チェックの追加を推奨します。
🔵 low: 2
その他の指摘 (2 件)
- 🔵 [low]
.github/workflows/ci.yml:117— lychee の --offline フラグにより外部リンクが検証されずサイレントスキップされる (confidence: 0.60,sec.sast.info_disclosure.dead_link_offline) - 🔵 [low]
docs/scripts/validate-frontmatter.ts:96— process.argv[1] を path.resolve に渡す際にサニタイズなし (情報漏洩/誤動作の可能性) (confidence: 0.40,sec.sast.injection.path_traversal)
前回 run からの未解決 finding: 1 件
head: 364a232 | Orange Codens (P1)
…frontmatter validation, Pagefind index
There was a problem hiding this comment.
🍊 Orange Codens レビュー
主な問題点: CI ジョブが npm install を使用しており再現性が保証されない（npm ci を使うべき）、Vitest テストステップが CI から欠落している（追加された validate-frontmatter.test.ts が実行されない）、docs/package-lock.json がコミットされていない（npm ci が動作しない）の3点が重要です。また __filename を ESM 環境で使用している点も将来的なリスクになります。helm/templates/pdb.yaml の replicaCount > 1 条件による PDB ガードは妥当な変更です。
🔒 セキュリティ: 今回の PR は docs サイト向け CI パイプラインの追加が主目的であり、認証・認可・データアクセスに関わるロジックは含まれていません。最も注意すべき点は npm install（npm ci ではない）の使用によるサプライチェーンリスクと、サードパーティ Action のメジャータグ固定によるタグ書き換え攻撃リスクです。validate-frontmatter.ts 自体のロジックは適切に実装されており、入力として外部ユーザーデータを直接受け取る箇所はないため、深刻な脆弱性は検出されませんでした。
🟡 medium: 4 / 🔵 low: 7
その他の指摘 (11 件)
- 🟡 [medium]
.github/workflows/ci.yml:107— CI ジョブでnpm installを使用しており再現性が保証されない (confidence: 0.95,maintainability.ci.npm-install-instead-of-ci) - 🟡 [medium]
.github/workflows/ci.yml:108— Vitest によるフロントマターテストのステップが CI から欠落している (confidence: 0.88,code.ci.vitest-step-missing) - 🟡 [medium]
.github/workflows/ci.yml:107— CI でnpm installを使用しており、lockfile による依存関係の固定がされていない (confidence: 0.85,sec.sast.injection.command) - 🟡 [medium]
docs/scripts/validate-frontmatter.ts:108—__filenameが ESM 環境で未定義になりスクリプト実行時にクラッシュする (confidence: 0.72,code.script.main-module-detection-esm) - 🔵 [low]
.github/workflows/ci.yml:103—actions/setup-nodeにcache/cache-dependency-pathが未設定 (confidence: 0.90,maintainability.ci.missing-node-cache) - 🔵 [low]
docs/package.json:1—docs/package-lock.jsonが diff に含まれておらずnpm ci/ キャッシュが動作しない (confidence: 0.90,maintainability.package.missing-package-lock) - 🔵 [low]
docs/package.json:11—check-linksスクリプトがサーバー起動を前提としており CI で単独実行できない (confidence: 0.85,maintainability.package.check-links-server-required) - 🔵 [low]
docs/scripts/validate-frontmatter.ts:64—title欠落ファイルがdraftチェックをスキップするため draft エラーが見逃される (confidence: 0.80,code.script.draft-check-skips-title-error) - 🔵 [low]
.github/workflows/ci.yml:118— lychee-action のバージョンがv2とメジャータグ固定であり、悪意ある更新を受け入れる可能性がある (confidence: 0.80,sec.sast.injection.command) - 🔵 [low]
docs/tsconfig.json:2—../tsconfig.jsonへのパス参照がリポジトリ構造によっては解決できない (confidence: 0.65,maintainability.config.tsconfig-extends-root) - 🔵 [low]
docs/scripts/validate-frontmatter.ts:30— MDX ファイルウォーカーがシンボリックリンクをたどる可能性があり、意図しないファイルを読み込む恐れがある (confidence: 0.55,sec.sast.injection.path_traversal)
head: 9645993 | Orange Codens (P1)
# Conflicts: # docs/next.config.mjs # docs/package.json # docs/tsconfig.json # docs/vitest.config.ts
|
Holding (not merging yet): this adds a docs CI job that would currently go RED — main's docs is Nextra v3 (needs _meta routing files) but the merged tree mixes that with plain pages-router files and has no _meta. The workflow YAML itself is well-formed; needs the docs-site structure reconciled first so the build step is green before this job is added to CI. |
There was a problem hiding this comment.
🍊 Orange Codens レビュー
最大の問題は lychee-action が uses: ステップのため docs/ cwd が効かず、./out/**/*.html が docs ビルド成果物を検査しない点で、dead link ゲートが PRD 要件を満たしません。加えて CI frontmatter 検証は production モードになっておらず draft 拒否が効かず、追加された Vitest も CI で実行されていません。Pagefind 二重実行や npm install は修正推奨の改善点です。
🔒 セキュリティ: 本 PR は docs サイト向け CI パイプラインと frontmatter 検証スクリプトの追加であり、SQL injection・SSRF・認証 bypass・暗号誤用などの典型的な論理脆弱性は diff 上確認されませんでした。唯一の懸念は、draft 拒否ロジックが CI 実行時に production モードで有効化されない点で、意図した公開前チェックが機能しない可能性があります。
🔴 critical: 1 / 🟡 medium: 4 / 🔵 low: 3
その他の指摘 (7 件)
- 🟡 [medium]
.github/workflows/ci.yml:102— Vitest テストが CI docs ジョブで実行されない (confidence: 0.90,maintainability.ci.missing_test_step) - 🟡 [medium]
.github/workflows/ci.yml:109— CI の frontmatter 検証で draft チェックが無効 (confidence: 0.88,code.validation.missing_production_env) - 🟡 [medium]
.github/workflows/ci.yml:107— npm install により CI の再現性が低下 (confidence: 0.85,maintainability.ci.npm_install_vs_ci) - 🟡 [medium]
docs/scripts/validate-frontmatter.ts:27— pages ディレクトリ不在時に検証が黙って成功する (confidence: 0.75,code.validation.empty_pages_passes) - 🔵 [low]
.github/workflows/ci.yml:114— Pagefind がビルド後に二重実行される (confidence: 0.92,performance.duplicate_pagefind) - 🔵 [low]
.github/workflows/ci.yml:110— CI で draft ページ検証が production モードで実行されない (confidence: 0.88,sec.sast.authz.protection_failure) - 🔵 [low]
docs/package.json:10— broken-link-checker が CI 経路で未使用 (confidence: 0.80,maintainability.deps.unused_blc)
head: aa2e0f9 | Orange Codens (P1)
| - name: Check dead links | ||
| uses: lycheeverse/lychee-action@v2 | ||
| with: | ||
| args: --offline --include-fragments './out/**/*.html' |
There was a problem hiding this comment.
🔴 [critical] lychee-action が docs/out を参照していない
defaults.run.working-directory: docs は run: ステップにのみ適用され、uses: ステップには適用されません。ビルド成果物は docs/out/ に出力されますが、lychee はリポジトリルートから ./out/**/*.html を探索するため、docs サイトの HTML を検査できません。PRD が要求する dead link 検出ゲートが実質バイパスされます。
該当箇所:
- name: Check dead links
uses: lycheeverse/lychee-action@v2
with:
args: --offline --include-fragments './out/**/*.html'
fail: true@@ -117,5 +117,5 @@
- name: Check dead links
uses: lycheeverse/lychee-action@v2
with:
- args: --offline --include-fragments './out/**/*.html'
+ args: --offline --include-fragments 'docs/out/**/*.html'
fail: truecode.ci.wrong_working_directory | confidence: 0.95
- Take main's docs/tsconfig.json (PR's types override broke next build's type-checking of nextra theme config) - Drop standalone 'tsc --noEmit' step (impossible in monorepo: parent tsconfig excludes docs; next build already type-checks) - Fix lychee args: --root-dir + --fallback-extensions html for static export, exclude 404 page (intentional /docs link per main's test) - Fix EditPageLink: docsRepositoryBase is undefined via useConfig in nextra v3 -> broken edit links on every page - Fix /LICENSE link in contributing/index.mdx (repo-root file absent in static site) -> point to GitHub - Remove stale pre-#282 scaffold (pages/index.tsx duplicate of index.mdx, pages/content/intro.mdx)
There was a problem hiding this comment.
🍊 Orange Codens レビュー
docs CI job の骨格 (frontmatter 検証・静的 build・Pagefind・lychee dead-link check) は PRD の主要要件を概ね満たしていますが、TypeScript チェック未実行、production 向け draft 検証が CI で無効、Vitest 未実行 という gate 抜けが目立ちます。加えて Pagefind の二重実行と EditPageLink の URL 変更も確認しました。
🟡 medium: 4 / 🔵 low: 2
その他の指摘 (6 件)
- 🟡 [medium]
.github/workflows/ci.yml:110— CI に TypeScript チェック (tsc --noEmit) ステップが無い (confidence: 0.95,ci.missing-required-step) - 🟡 [medium]
.github/workflows/ci.yml:110— CI 上で draft frontmatter 検証が実行されない (confidence: 0.90,code.logic.production-env-not-set) - 🟡 [medium]
.github/workflows/ci.yml:103— frontmatter 検証の Vitest テストが CI で実行されない (confidence: 0.90,ci.missing-test-step) - 🟡 [medium]
docs/components/EditPageLink.tsx:5— 「このページを編集」リンクが GitHub tree URL から blob URL に変わっている (confidence: 0.85,code.url.regression) - 🔵 [low]
.github/workflows/ci.yml:113— Pagefind インデックス生成が build 後に二重実行される (confidence: 0.95,perf.duplicate-work) - 🔵 [low]
.github/workflows/ci.yml:108— 依存関係インストールにnpm ciではなくnpm installを使用 (confidence: 0.85,ci.non-reproducible-install)
head: 4579c11 | Orange Codens (P1)
1 participant
Summary
Type of Change
Testing
Checklist
Task Goal
Target Repository
Corevice/open-gitAll work for this task belongs in this repository. Do the implementation inside this repository's directory in the workspace; do not search or edit other repositories unless this task explicitly requires a cross-repo change.
Context
The PRD requires CI gates for: MDX frontmatter validation (title required), dead link detection, and Pagefind index generation as part of the static build. These are added as a new
docsjob in the existing.github/workflows/ci.yml. The job must fail the build if any MDX is missing atitle, if any internal link is broken, or if the Nextra static export fails.Steps
open-git/.github/workflows/ci.yml(already in context) — append a newdocsjobdocsjob toopen-git/.github/workflows/ci.yml:lychee-link-checker/action@v1or installlycheevia apt in the CI step for dead-link checking; alternatively usebroken-link-checkernpm package (blc) — add to devDependencies ofdocs/package.jsonand update the check step tonpx blc http://localhost:3000 -ro --filter-level 3(running against static export)open-git/docs/scripts/validate-frontmatter.ts— a standalone Node script (not Vitest) that: walks all.mdxunderpages/; parses frontmaChanges Made
CI
gates
for the
docs site need
several files;
I'll read
the ones
named in the task
first
.
The
docs/directory
is
missing, so I'll
add the four
files
named in the task
.
Docs
CI gates
are
in place across
the four files named
in the task.
Changes
**
. github/workflows/ci.yml** — Addeda
docsjob that
:
Runs
in the
docsworkingdirectory
Inst
alls dependencies with
npm ciValidates frontmatter
via
n px tsx scripts /validate-frontmatter .ts(before build)
Runs
npx tsc --noEmitBuilds with
npm run buildGenerates
Pagefind index with
npx page find --site outChecks
dead links with
lycheever se/lyche e-action@v2on static HTML(no
|| true, so brokenlinks fail the job
)
**
docs/scripts/ validate-frontmatter.ts** — Standalone script that:
Walks all
.mdxfiles under
pages /Parses
frontmatter with
gray-matterExits
1 if
titleismissing
Exits
1 if
draft : trueinproduction (
NODE_ENV === 'production')Prints success
count on pass
Exports
validateFrontmatter/validateFrontmatter OrThrowfortests
docs /package.json—Added
tsx,broken -link-checker,gray-matter,pagefind,vitest, and scriptsincluding
check -links(bl
c against
a running server).
docs/__ tests__/scripts /validate-frontmatter .test.ts—Vitest tests
using
temp MD
X files
for missing
title, valid
front
matter, and draft
-in
-production cases
.
[P
URPLE-M
ODIFIED-FILES
]
.github
/workflows/ci.yml
docs/scripts
/validate-frontmatter
.ts
docs/package
.json
docs/__
tests__/scripts/
validate-frontmatter.test
.ts
[/P
URPLE
-MODIFIED-F
ILES]
Task ID:
019f0d7d-8817-7205-ac05-3adaf64ab0d5Generated by Purple Codens