AIが書いたJSDocが、いつのまにかコードと食い違っていたとき — ドキュメントの陳腐化を計測して塞ぐ運用メモ

// scripts/doc-drift.ts
// 公開関数のシグネチャをハッシュ化し、保存済みマニフェストと比較してドリフトを検出する
import { Project, Node, FunctionDeclaration } from "ts-morph";
import { createHash } from "node:crypto";
import { readFileSync, writeFileSync, existsSync } from "node:fs";
 
const MANIFEST = "doc-manifest.json";
 
// 外形（引数名・型・戻り値・throwする型）だけを安定した文字列に変換する
function signatureOf(fn: FunctionDeclaration): string {
  const params = fn.getParameters().map((p) => {
    const name = p.getName();
    const type = p.getType().getText(p); // 解決済みの型テキスト
    const optional = p.isOptional() ? "?" : "";
    return `${name}${optional}:${type}`;
  });
  const ret = fn.getReturnType().getText(fn);
 
  // 本体で明示的に throw している式の型を収集する
  const throwsSet = new Set<string>();
  fn.forEachDescendant((node) => {
    if (Node.isThrowStatement(node)) {
      const expr = node.getExpression();
      throwsSet.add(expr ? expr.getType().getText(node) : "unknown");
    }
  });
  const throws = [...throwsSet].sort().join(",");
 
  // 引数順は意味を持つのでソートしない。throwは順不同なのでソートする
  return `(${params.join(";")})=>${ret}|throws:${throws}`;
}
 
// JSDocブロックの生テキスト。ここが変わっていれば「ドキュメントは更新された」と見なす
function docTextOf(fn: FunctionDeclaration): string {
  return fn.getJsDocs().map((d) => d.getInnerText()).join("\n").trim();
}
 
function hash(s: string): string {
  return createHash("sha1").update(s).digest("hex").slice(0, 12);
}
 
const project = new Project({ tsConfigFilePath: "tsconfig.json" });
const manifest: Record<string, { sig: string; doc: string }> =
  existsSync(MANIFEST) ? JSON.parse(readFileSync(MANIFEST, "utf8")) : {};
 
type Finding = { id: string; kind: "drift" | "undocumented" | "new" };
const findings: Finding[] = [];
const nextManifest: typeof manifest = {};
 
for (const sf of project.getSourceFiles("src/**/*.ts")) {
  for (const fn of sf.getFunctions()) {
    if (!fn.isExported() || !fn.getName()) continue; // 公開関数のみ対象
    const id = `${sf.getFilePath().replace(process.cwd(), "")}#${fn.getName()}`;
    const sig = hash(signatureOf(fn));
    const doc = hash(docTextOf(fn));
    const prev = manifest[id];
 
    if (docTextOf(fn) === "") {
      findings.push({ id, kind: "undocumented" });
    } else if (!prev) {
      findings.push({ id, kind: "new" });
    } else if (prev.sig !== sig && prev.doc === doc) {
      // 外形は変わったのにドキュメントは据え置き = ドリフト
      findings.push({ id, kind: "drift" });
    }
    nextManifest[id] = { sig, doc };
  }
}
 
// --update 時のみマニフェストを書き戻す（ドキュメントを直した後に実行する）
if (process.argv.includes("--update")) {
  writeFileSync(MANIFEST, JSON.stringify(nextManifest, null, 2));
}
 
const drift = findings.filter((f) => f.kind === "drift");
const documented = Object.keys(nextManifest).length;
const rate = documented ? ((drift.length / documented) * 100).toFixed(1) : "0.0";
console.log(`documented public fns: ${documented}`);
console.log(`drift: ${drift.length}  (drift rate: ${rate}%)`);
for (const f of drift) console.log(`  DRIFT  ${f.id}`);
process.exit(drift.length > 0 ? 1 : 0);

#!/usr/bin/env bash
# ci/check-doc-drift.sh
set -euo pipefail
 
# main のマニフェストを基準に、このブランチで増えたドリフトだけを見る
git show origin/main:doc-manifest.json > /tmp/base-manifest.json 2>/dev/null || echo '{}' > /tmp/base-manifest.json
 
npx tsx scripts/doc-drift.ts > /tmp/drift.txt || true
DRIFT_COUNT=$(grep -c '^  DRIFT' /tmp/drift.txt || true)
 
echo "current drift findings: ${DRIFT_COUNT}"
 
# ベースラインのドリフト件数（許容済みの負債）
BASE=$(cat .doc-drift-baseline 2>/dev/null || echo 0)
 
if [ "${DRIFT_COUNT}" -gt "${BASE}" ]; then
  echo "❌ 新しいドキュメントドリフトが ${DRIFT_COUNT} 件（許容: ${BASE} 件）"
  grep '^  DRIFT' /tmp/drift.txt
  echo "ドリフトした関数のJSDocを更新し、doc-drift.ts --update を実行してください"
  exit 1
fi
echo "✅ 新規ドリフトなし"

// scripts/readme-drift.ts の要点
// README中の ENV キーが .env.example に存在するかを照合する
import { readFileSync } from "node:fs";
 
const readme = readFileSync("README.md", "utf8");
const envExample = readFileSync(".env.example", "utf8");
const declaredKeys = new Set(
  envExample.split("\n").map((l) => l.split("=")[0].trim()).filter(Boolean)
);
 
// READMEが `BACKTICK` で囲って言及している大文字_付き識別子を環境変数候補として抽出
const mentioned = [...readme.matchAll(/`([A-Z][A-Z0-9_]{3,})`/g)].map((m) => m[1]);
const stale = mentioned.filter((k) => k.endsWith("_KEY") || k.endsWith("_URL") || k.endsWith("_ID"))
  .filter((k) => !declaredKeys.has(k));
 
if (stale.length) {
  console.log("READMEが参照するが .env.example に無い環境変数:", stale.join(", "));
  process.exit(1);
}