@unowdev/docgraph

Markdown文書の依存グラフを管理し、更新波及に応じて needs-check キューを生成するCLIです。

必要環境

• Node.js LTS (>=18)

インストール（推奨: プロジェクトローカル）

方式3（devDependency）を標準運用とします。

# 公開済みパッケージを使う場合
npm i -D @unowdev/docgraph

公開前にローカルパッケージを検証する場合:

# 利用側プロジェクトで実行（このリポジトリ構成の例）
npm i -D file:../../package

package.json 例:

{
  "scripts": {
    "docgraph": "docgraph"
  }
}

実行例:

npm run docgraph -- init
npm run docgraph -- watch --once
npm run docgraph -- needs-check --json

CIの最小確認例:

npm ci
npm exec -- docgraph --help

方式3の詳細運用（配布チャネル、固定ポリシー、更新/移行/障害対応）は demo/install_method3/OPERATIONS_GUIDE.md を参照してください。

配布物ドライラン（npm pack 生成tarballの利用側検証）は demo/install_method3/tarball_release_smoke.sh を参照してください。

コマンド

• docgraph init
  • ワークスペース直下に .docgraph/state.json を作成します。
• docgraph watch
  • 起動時に初期同期（.md 走査、deps/rdeps 構築、未登録文書 versions=1）を行い、継続監視します。
• docgraph needs-check
  • needs-check 文書を決定的順序（impact 降順、path 昇順）で表示します。
• docgraph needs-check --json
  • reason / changedUpstreams / diffRefs を含むJSONを返します。
• docgraph next --json
  • キュー先頭1件をJSONで返します（空なら null）。
• docgraph mark <path> [--actor <id>] [--summary <text>]
  • 対象文書の依存閉包スナップショットを completion に記録し、audit を追記して clean に遷移させます。
  • broken 文書は mark できません。

state.json 主要フィールド

• versions: 文書ごとの整数バージョン
• deps: 参照元 -> 参照先
• rdeps: 参照先 -> 参照元
• status: clean | needs-check | broken
• completion: mark 時点の { checkedAt, snapshot }
• broken: 解決不能参照の理由
• queue: needs-check キュー（path, priorityKey, reason, changedUpstreams）
• diffs: 直前版との差分参照（diffRef は .docgraph/diffs/...）
• audit: mark の監査証跡

監査証跡（audit）の意味

audit[path] には mark 実行ごとに以下が追記されます。

• at: 実行時刻
• actor: 実行者（--actor、DOCGRAPH_ACTOR、USER、unknown の順で解決）
• snapshot: 依存閉包＋自身のバージョン写像
• reviewedUpstreams: mark 実行時点での changedUpstreams
• resultSummary: 任意の要約テキスト
• docHash: 対象文書内容のSHA-256