refactor: 문서 개선 중

scripts/check-command-pedagogy.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Markdown 한 편의 shell/CLI 블록을 command-pedagogy 분석 JSON으로 만든다."""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from command_pedagogy import COMMAND_MODES, analyze_commands  # noqa: E402
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="shell/CLI 교육성 위험 신호를 결정론적으로 찾는다")
+    ap.add_argument("record", help="검사할 Markdown 파일")
+    ap.add_argument("--section-id", default=None)
+    ap.add_argument("--mode", choices=sorted(COMMAND_MODES), default="operator")
+    ap.add_argument("-o", "--output", help="분석 JSON을 저장할 경로")
+    args = ap.parse_args()
+
+    try:
+        text = open(args.record, encoding="utf-8").read()
+    except OSError as exc:
+        print(f"읽지 못했다: {args.record} — {exc}", file=sys.stderr)
+        return 2
+
+    result = analyze_commands(args.section_id or args.record, text, mode=args.mode)
+    rendered = json.dumps(result, ensure_ascii=False, indent=2) + "\n"
+    if args.output:
+        os.makedirs(os.path.dirname(args.output) or ".", exist_ok=True)
+        with open(args.output, "w", encoding="utf-8") as fh:
+            fh.write(rendered)
+    else:
+        print(rendered, end="")
+
+    print(
+        f"COMMAND PEDAGOGY: {result['result']} — shell blocks {len(result['blocks'])} · "
+        f"findings {len(result['findings'])}",
+        file=sys.stderr,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())