PJR-DPVV 文書 lint を @specdojo/docs-lint として分離する
1. 概要
specdojo の package.json の files は tools/docs/src と tools/docs/tsconfig.json を同梱しているが、次の理由で利用者側では機能しない。
- 中身は remark プラグイン 3 本（
remark-md-content、remark-no-unescaped-angle-placeholder、remark-frontmatter-ajv2020）と検証スクリプト 4 本（validate-yaml-schema、validate-rulebook-schema-enums、validate-history-links、validate-md-content）で、CLI（src/）からは参照されない。参照元は本リポジトリのpackage.jsonscripts と.remarkrc.yamlだけである。 - 依存する
remark/remark-cli/ajv-formats/fast-globは devDependencies で、npm i specdojoでは入らない。 - 利用者が使うには
node_modules/specdojo/tools/docs/src/…を.remarkrcや scripts から指すことになり、公開 API として成立していない。
PJR-9S8F で文書サイトを @specdojo/docs-site（packages/docs-site）へ分離した前例に合わせ、文書 lint も @specdojo/docs-lint（packages/docs-lint）へ分離する。
1.1. 決定事項
- パッケージ名は
@specdojo/docs-lint、配置はpackages/docs-lint。@specdojo/docs-siteと同じく独自のpackage.json/ lockfile を持ち、npm workspaces にはしない（PJR-7VKR の publish 形態と揃える）。 - remark プラグインは export（例:
@specdojo/docs-lint/remark/md-content、.../no-unescaped-angle-placeholder、.../frontmatter-ajv2020）として提供し、利用者は.remarkrcから参照する。 - 検証スクリプトは
bin（例:specdojo-docs-lint yaml-schema/rulebook-schema-enums/history-links/md-content）として提供する。schema はspecdojo本体に同梱されるdocs/specdojo/schemasをspecdojoのパッケージルートから解決する。 - 依存（remark 系、ajv、ajv-formats、fast-glob、js-yaml、gray-matter）はこのパッケージの
dependenciesに置く。 - 本リポジトリの
.remarkrc.yaml、validate:*/lint:md/lint:fmscripts、lefthook、tsconfig references をpackages/docs-lint参照へ書き換える。 specdojoのfilesからtools/docs/srcとtools/docs/tsconfig.jsonを除く（PJR-7VKR の作業 1 で先行して除外してよい）。- 利用者向けの案内（quick-start / docs-editing-guide）は
npm i -D specdojo @specdojo/docs-lintと.remarkrcの例を載せる。
2. 完了条件
packages/docs-lintが独自のpackage.jsonを持ち、remark プラグインの export と検証コマンドのbinを提供している。npm pack --dry-runの同梱物が意図どおりで、依存がすべてdependenciesにある。- 本リポジトリの
.remarkrc.yaml、scripts、lefthook、tsconfig references がpackages/docs-lintを参照し、tools/docsが削除されている。 specdojoのfilesにtools/docsが含まれない。- 別ディレクトリで
npm i -D specdojo @specdojo/docs-lint（npm packの tarball）を行い、.remarkrcから remark プラグインが解決され、specdojo-docs-lint history-linksが動く。 - quick-start / docs-editing-guide に導入と
.remarkrcの例が記載されている。 npm run checkが通過している。
3. 作業内容
| No | 作業 | 担当 | 状態 | メモ |
|---|---|---|---|---|
| 1 | packages/docs-lint を作成し、remark プラグインの export と検証コマンドの bin を実装する | DEV | done | 3 export と 4 検証コマンドを公開 |
| 2 | 本リポジトリの .remarkrc.yaml / scripts / lefthook / tsconfig references を書き換え、tools/docs を削除する | DEV | done | ソースとテストを新パッケージ構成へ移行 |
| 3 | specdojo の files から tools/docs を除く（PJR-7VKR 作業 1 と整合） | DEV | done | PJR-7VKR の先行対応を確認 |
| 4 | tarball を別ディレクトリで導入して実地検証し、guide を更新する | DEV | done | tarball 2 本を別ディレクトリへ導入して動作確認済み |
4. 対応結果
packages/docs-lintに独立したpackage.json/ lockfile、CLI、remark プラグインを配置した。CLI はyaml-schema、rulebook-schema-enums、history-links、md-contentを提供し、remark プラグインは package export から参照できる。- schema の参照先が利用者リポジトリにない場合、同時導入された
specdojoパッケージのdocs/specdojo/またはdocs/ja/specdojo/配下へフォールバックするようにした。 - ルートの
.remarkrc.yaml、npm scripts、ESLint、lefthook、TypeScript project references をpackages/docs-lintへ移行し、旧tools/docsを削除した。specdojo本体のfilesは PJR-7VKR で既にtools/docsを除外済みだったため、その状態を維持した。 npm pack --dry-runで lint パッケージが 15 ファイルだけを同梱することを確認した。specdojoと@specdojo/docs-lintの tarball を別ディレクトリへ導入し、3 export の解決、.remarkrc.yamlからのプラグイン読込、specdojo-docs-lint history-linksの実行を確認した。- specdojo:quick-start-guide と specdojo:docs-editing-guide に導入手順、
.remarkrc.yamlの設定例、検証コマンドを追記した。残課題はない。
4.1. レビュー結果（2026-09-21）
develop で lint:md / lint:fm / validate:history-links が packages/docs-lint/bin 経由で動作し、npm run check（テスト 1611 件）が通過することを確認した。本リポジトリでは packages/docs-lint/node_modules を持たず root の devDependencies で解決している。root から remark / markdownlint-cli 等を外す場合は post-create.sh に npm --prefix packages/docs-lint ci を加える。@specdojo/docs-lint の npm 公開は PJR-7VKR の trusted publisher と同じ枠組みで別途行う。