pr-docent 0.1.0 → 0.1.1

package/README.md

@@ -15,6 +15,7 @@ GitHub 풀 리퀘스트의 **Files changed** 화면 위에서 동작하는 리
 - 접힌 대용량 diff("Load Diff")는 자동으로 펼칩니다.
 - 패널이 열려 있는 동안 diff가 패널에 가리지 않도록 페이지 폭을 줄입니다.
 - PR마다 마지막 위치를 기억합니다.
+- 화면 언어는 영어(기본)와 한국어를 지원합니다. 툴바의 PR Docent 아이콘을 눌러 자동(브라우저 언어), English, 한국어 중에서 고릅니다. 로컬에서 만드는 투어도 고른 언어로 작성되고, 음성은 투어 문장의 언어에 맞춰 읽습니다.
 
 ## 단축키
 
@@ -90,6 +91,27 @@ PR이 열리거나 커밋이 추가될 때마다 Claude Code가 diff를 읽고
 - 검사를 통과한 투어를 이 PR에 저장하고 바로 재생합니다. 생성에는 보통 2~3분이 걸립니다.
 - 제거: `npx pr-docent uninstall`
 
+## 투어 생성 규칙 바꾸기 (`.github/pr-docent.md`)
+
+Actions 생성과 로컬 생성 모두 기본적으로 짧은 투어를 만듭니다. 단계 수는 바뀐 줄 25줄당 1개에 3을 더한 값까지(최대 20)이고, 단계마다 문장 3개, 문장마다 80자까지입니다. 주석만 바뀐 곳, 임포트, 문서처럼 사소한 변경은 단계 대신 "건너뛴 파일"에 넣습니다. 검사기가 이 기준을 확인하고, 넘으면 Claude가 다시 줄입니다.
+
+저장소에 `.github/pr-docent.md`를 두면 그 저장소의 규칙을 더할 수 있습니다. 앞부분 `---` 블록은 숫자 기준을 바꾸고, 본문은 생성 지시문 뒤에 붙어 기본 규칙보다 우선합니다.
+
+```markdown
+---
+maxSteps: 6            # 단계 수 상한 (기본: 3 + 바뀐 줄 25줄당 1, 최대 20)
+sentencesPerStep: 2    # 단계당 문장 수 (기본 3)
+sentenceChars: 100     # 문장 길이 (기본 80자)
+pointChars: 120        # 리뷰 포인트 길이 (기본 120자)
+summaryChars: 200      # PR 요약 길이 (기본 200자)
+chapterSummaryChars: 60
+---
+- 도메인 용어는 원장, 안분, 파생 라인으로 씁니다.
+- Flyway 마이그레이션 파일은 항상 집중 단계로 다룹니다.
+```
+
+PR의 head 커밋에 있는 파일을 읽으므로, 규칙을 바꾸는 PR에서는 바뀐 규칙으로 생성됩니다.
+
 ## 투어 불러오기
 
 - PR 코멘트에 자동 생성된 투어가 있으면 그 투어를 불러옵니다. 직접 불러온 투어가 있으면 그쪽이 우선합니다.
@@ -142,6 +164,7 @@ GitHub의 2026년 Files changed 화면 기준입니다. 화면 구조가 바뀌
 
 - 빌드 단계가 없습니다. 콘텐츠 스크립트(`src/loader.js`)가 ES 모듈(`src/main.js`)을 불러옵니다.
 - 테스트: `npm test` (Node 내장 테스트 러너). 투어 검증, diff 대조, 재생 상태, 단축키, PR 주소 해석, GitHub 파일 ID 해시, 줄 선택자를 다룹니다.
+- npm 게시: `package.json`의 버전을 올려 머지한 뒤 `git tag npm-v<버전> && git push origin npm-v<버전>`. GitHub Actions(`publish.yml`)가 trusted publishing으로 게시하므로 npm 토큰이나 2FA 입력이 필요 없습니다.
 - 투어 검사: `node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number]` (`gh pr diff <number> > pr.diff`)
 
 ## 라이선스

package/bin/pr-docent.mjs

@@ -17,7 +17,7 @@ import { EXTENSION_IDS, HOST_NAME } from "../host/native.mjs";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 // What the host needs at run time; everything else in the package is for the extension or tests.
-const RUNTIME_FILES = ["host/native.mjs", "host/pr-docent-host.mjs", "src/diff.js", "src/tour.js", "scripts/check-tour.mjs", "scripts/tour-prompt.md"];
+const RUNTIME_FILES = ["host/native.mjs", "host/pr-docent-host.mjs", "src/diff.js", "src/guidelines.js", "src/tour.js", "scripts/check-tour.mjs", "scripts/tour-prompt.md"];
 const HOSTS_DIRS = {
   darwin: join(homedir(), "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts"),
   linux: join(homedir(), ".config", "google-chrome", "NativeMessagingHosts"),
@@ -75,7 +75,8 @@ function install(args) {
   Generator:            ${app}
   Allowed extensions:   ${extensionIds.join(", ")}
   Claude Code:          ${claude}
-Reload the extension in chrome://extensions, then use "로컬 Claude Code로 투어 생성" in the panel.`);
+Reload the extension in chrome://extensions, then click "Create a tour with local Claude Code"
+in the panel ("로컬 Claude Code로 투어 생성" in Korean).`);
 }
 
 function uninstall() {

package/host/native.mjs

@@ -33,8 +33,3 @@ export function extensionIdFromKey(key) {
   const hex = createHash("sha256").update(Buffer.from(key, "base64")).digest("hex").slice(0, 32);
   return [...hex].map((c) => String.fromCharCode(97 + parseInt(c, 16))).join("");
 }
-
-/** Replaces {{NAME}} placeholders; unknown ones are left as they are. */
-export function fillTemplate(text, vars) {
-  return text.replace(/{{(\w+)}}/g, (match, name) => (name in vars ? String(vars[name]) : match));
-}

package/host/pr-docent-host.mjs

@@ -8,9 +8,10 @@ import { mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSy
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkTour, visibleLines } from "../src/diff.js";
+import { changedLineCount, checkTour, visibleLines } from "../src/diff.js";
+import { buildPrompt, checkBrevity, parseGuidelines } from "../src/guidelines.js";
 import { parseTour } from "../src/tour.js";
-import { createDecoder, encodeMessage, fillTemplate } from "./native.mjs";
+import { createDecoder, encodeMessage } from "./native.mjs";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const CONFIG = readConfig();
@@ -35,7 +36,7 @@ process.stdin.on("end", () => {
   process.exit(0);
 });
 
-async function generate({ pr, title, body, headSha, diff, files, model, language }) {
+async function generate({ pr, title, body, headSha, diff, files, guidelines = "", model, language }) {
   // Real path: on macOS the temp folder is a symlink, and the write rule must match exactly.
   const work = realpathSync(mkdtempSync(join(tmpdir(), "pr-docent-")));
   try {
@@ -51,13 +52,19 @@ async function generate({ pr, title, body, headSha, diff, files, model, language
     }
     writeFileSync(join(out, "pr.diff"), diff);
     writeFileSync(join(out, "pr.json"), JSON.stringify({ title, body, headRefOid: headSha }, null, 2));
+    if (guidelines) writeFileSync(join(out, "guidelines.md"), guidelines);
+    const { limits, errors: guidelineErrors } = parseGuidelines(guidelines);
+    if (guidelineErrors.length) throw new Error(`.github/pr-docent.md: ${guidelineErrors.join(" / ")}`);
+    const changedLines = changedLineCount(diff);
 
     const prRef = `${pr.owner}/${pr.repo}#${pr.number}`;
-    const prompt = fillTemplate(readFileSync(join(ROOT, "scripts", "tour-prompt.md"), "utf8"), {
-      PR: prRef,
-      OUT: out,
-      TOOLS: ROOT,
-      LANGUAGE: language || "한국어",
+    const prompt = buildPrompt(readFileSync(join(ROOT, "scripts", "tour-prompt.md"), "utf8"), {
+      pr: prRef,
+      out,
+      tools: ROOT,
+      language: language || "한국어",
+      changedLines,
+      guidelinesText: guidelines,
     });
     await runClaude(prompt, repo, [
       "--model", model || "claude-opus-5-5",
@@ -69,11 +76,13 @@ async function generate({ pr, title, body, headSha, diff, files, model, language
     try {
       raw = JSON.parse(readFileSync(join(out, "tour.json"), "utf8"));
     } catch {
-      throw new Error("Claude가 투어 파일을 만들지 못했습니다.");
+      throw new Error("Claude did not write a tour file.");
     }
     const { tour, errors } = parseTour(raw);
-    const problems = errors.length ? errors : checkTour(tour, visibleLines(diff));
-    if (problems.length) throw new Error(`투어 검사를 통과하지 못했습니다: ${problems.slice(0, 3).join(" / ")}`);
+    const problems = errors.length
+      ? errors
+      : [...checkTour(tour, visibleLines(diff)), ...checkBrevity(tour, { changedLines, limits })];
+    if (problems.length) throw new Error(`The tour did not pass the checks: ${problems.slice(0, 3).join(" / ")}`);
     return raw;
   } finally {
     rmSync(work, { recursive: true, force: true });
@@ -99,12 +108,12 @@ function runClaude(prompt, cwd, args) {
     child.stderr.on("data", keep);
     const progress = setInterval(() => send({ type: "progress", seconds: Math.round((Date.now() - started) / 1000) }), 5000);
     const timeout = setTimeout(() => child.kill(), TIMEOUT_MS);
-    child.on("error", (error) => reject(new Error(`Claude Code를 실행하지 못했습니다 (${CONFIG.claude}): ${error.message}`)));
+    child.on("error", (error) => reject(new Error(`Could not start Claude Code (${CONFIG.claude}): ${error.message}`)));
     child.on("close", (code) => {
       clearInterval(progress);
       clearTimeout(timeout);
       if (code === 0) resolvePromise();
-      else reject(new Error(`Claude Code가 종료 코드 ${code}로 끝났습니다. ${output.trim().slice(-300)}`));
+      else reject(new Error(`Claude Code exited with code ${code}. ${output.trim().slice(-300)}`));
     });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-docent",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Guided, narrated review tours on top of GitHub pull request diffs. This package installs the local tour generator for the PR Docent Chrome extension.",
   "license": "MIT",
@@ -26,6 +26,7 @@
     "bin/",
     "host/",
     "src/diff.js",
+    "src/guidelines.js",
     "src/tour.js",
     "scripts/check-tour.mjs",
     "scripts/tour-prompt.md"

package/scripts/check-tour.mjs

@@ -1,18 +1,24 @@
 #!/usr/bin/env node
 // Validates a tour against a pull request diff.
 //
-//   node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number]
+//   node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number] [--guidelines <file>]
 //
 // Prints every problem and exits 1, or prints a one-line summary and exits 0.
 // The diff must use 3 lines of context (`gh pr diff` or `git diff -U3`), as GitHub does.
+// --guidelines points at a copy of the repository's .github/pr-docent.md; a missing file means
+// the default limits.
 
-import { readFileSync } from "node:fs";
-import { checkTour, visibleLines } from "../src/diff.js";
+import { existsSync, readFileSync } from "node:fs";
+import { changedLineCount, checkTour, visibleLines } from "../src/diff.js";
+import { checkBrevity, parseGuidelines } from "../src/guidelines.js";
 import { flattenSteps, parseTour } from "../src/tour.js";
 
-const [tourPath, diffPath, expectedPr] = process.argv.slice(2);
+const args = process.argv.slice(2);
+const flag = args.indexOf("--guidelines");
+const guidelinesPath = flag >= 0 ? args.splice(flag, 2)[1] : null;
+const [tourPath, diffPath, expectedPr] = args;
 if (!tourPath || !diffPath) {
-  console.error("usage: node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number]");
+  console.error("usage: node scripts/check-tour.mjs <tour.json> <pr.diff> [owner/repo#number] [--guidelines <file>]");
   process.exit(2);
 }
 
@@ -37,7 +43,13 @@ if (expectedPr) {
   if (actual !== expectedPr) fail([`pr is ${actual}, expected ${expectedPr}`]);
 }
 
-const problems = checkTour(tour, visibleLines(readFileSync(diffPath, "utf8")));
+const diff = readFileSync(diffPath, "utf8");
+const guidelines = parseGuidelines(guidelinesPath && existsSync(guidelinesPath) ? readFileSync(guidelinesPath, "utf8") : "");
+if (guidelines.errors.length) fail(guidelines.errors.map((error) => `.github/pr-docent.md: ${error}`));
+const problems = [
+  ...checkTour(tour, visibleLines(diff)),
+  ...checkBrevity(tour, { changedLines: changedLineCount(diff), limits: guidelines.limits }),
+];
 if (problems.length) fail(problems);
 
 console.log(`OK: ${tour.chapters.length} chapters, ${flattenSteps(tour).length} steps, ${tour.skipped.length} skipped files`);

package/scripts/tour-prompt.md

@@ -16,7 +16,7 @@ code while they listen, so the tour must say what to look at and why, in reading
 
 Write the tour to `{{OUT}}/tour.json`, then run
 
-    node {{TOOLS}}/scripts/check-tour.mjs {{OUT}}/tour.json {{OUT}}/pr.diff {{PR}}
+    node {{TOOLS}}/scripts/check-tour.mjs {{OUT}}/tour.json {{OUT}}/pr.diff {{PR}} --guidelines {{OUT}}/guidelines.md
 
 and fix every problem it reports until it prints `OK`. Then stop. Do not post comments or
 change any other file. Use these absolute paths as written and do not change directory:
@@ -55,12 +55,23 @@ change any other file. Use these absolute paths as written and do not change dir
 
 ## Rules
 
+Be brief. Reviewers listen while they look at the code, so every sentence must earn its place.
+The checker enforces these limits for this diff ({{CHANGED_LINES}} changed lines):
+- At most {{MAX_STEPS}} steps in total.
+- At most {{SENTENCES_PER_STEP}} sentences per step, each at most {{SENTENCE_CHARS}} characters.
+- `point`: one question, at most {{POINT_CHARS}} characters.
+- `summary`: at most {{SUMMARY_CHARS}} characters; each chapter `summary`: at most
+  {{CHAPTER_SUMMARY_CHARS}}.
+
 Coverage and order
-- Every changed file must be visited by a step or listed in `skipped` with a reason
-  (lock files, generated code, snapshots, pure renames, binaries).
+- Every changed file must be visited by a step or listed in `skipped` with a short reason.
+- Make steps only for changes a reviewer must think about. Put trivial changes in `skipped`
+  instead of steps: comment or doc-comment edits, imports, docs, test fixtures that pass values
+  through, lock files, generated code, renames, binaries. A file can have a step for its real
+  change and nothing for its trivial ones.
+- Merge neighbouring changes that make one point into one step; never repeat a step.
 - Order chapters the way a person should read the change, not by file path: what changes and
-  why, then the core logic, then how it is wired in, then tests and docs.
-- A large file may need several steps; a trivial one may share a chapter with related files.
+  why, then the core logic, then how it is wired in, then tests.
 
 Lines
 - `lines` are line numbers in the new file (`"side": "right"`, the default). Use
@@ -72,13 +83,16 @@ Lines
   step as a whole.
 
 Notes are spoken aloud
-- Write in {{LANGUAGE}}. One or two short sentences per note entry, 2-5 entries per step.
-- Say what the code does and why it matters for the change; do not read the code out.
+- Write in {{LANGUAGE}}. One sentence per note entry, one idea per sentence.
+- Say why the change matters: intent, risk, or how it connects to other code. Do not restate
+  what the code plainly shows ("adds a parameter", "imports X", "updates the comment").
 - Avoid symbols, brackets and long lists that sound bad in speech. Name identifiers as written.
 
 Levels and review points
 - `focus`: where a bug would hurt or a design decision is made; at most about a third of the
-  steps. `skim`: worth a look. `skip`: can be skipped safely (formatting, boilerplate).
-- `point` is a concrete question for the reviewer, grounded in the code you read: an edge case,
-  a failure mode, a contract another caller relies on. Leave it out when there is nothing real
-  to check. Never invent problems.
+  steps. `skim`: worth a look.
+- `point` is one concrete question for the reviewer, grounded in the code you read: an edge
+  case, a failure mode, a contract another caller relies on. Leave it out when there is nothing
+  real to check. Never invent problems.
+
+{{GUIDELINES}}

package/src/diff.js

@@ -43,16 +43,20 @@ export function visibleLines(diffText) {
 
 /**
  * Problems that would make the tour point at the wrong place or skip part of the PR:
- * files outside the diff, lines not shown on the page, beats outside their step, and
- * changed files the tour neither visits nor skips.
+ * files outside the diff, lines not shown on the page, beats outside their step, repeated
+ * steps, and changed files the tour neither visits nor skips.
  */
 export function checkTour(tour, files) {
   const errors = [];
   const visited = new Set();
+  const seen = new Set();
   tour.chapters.forEach((chapter, c) =>
     chapter.steps.forEach((step, s) => {
       const where = `chapters[${c}].steps[${s}] (${step.file})`;
       visited.add(step.file);
+      const key = `${step.file}|${step.side}|${step.lines}`;
+      if (seen.has(key)) errors.push(`${where}: repeats an earlier step on the same lines`);
+      seen.add(key);
       const file = files.get(step.file);
       if (!file) return errors.push(`${where}: file is not changed in this pull request`);
       const shown = file[step.side];
@@ -80,6 +84,18 @@ export function checkTour(tour, files) {
   return errors;
 }
 
+/** Added plus removed lines, which sets how long a tour of the diff may be. */
+export function changedLineCount(diffText) {
+  let count = 0;
+  let inHunk = false;
+  for (const line of String(diffText).split("\n")) {
+    if (line.startsWith("diff --git ")) inHunk = false;
+    else if (line.startsWith("@@")) inHunk = true;
+    else if (inHunk && (line.startsWith("+") || line.startsWith("-"))) count++;
+  }
+  return count;
+}
+
 function range([start, end]) {
   return Array.from({ length: end - start + 1 }, (_, i) => start + i);
 }

package/src/guidelines.js

@@ -0,0 +1,102 @@
+// How long a generated tour may be, and a repository's own instructions for it.
+// Pure functions — no DOM, no chrome.*, no file system.
+//
+// A repository can add .github/pr-docent.md. Its optional front matter overrides the limits,
+// and the rest is appended to the generator's instructions:
+//
+//   ---
+//   maxSteps: 5
+//   sentenceChars: 100
+//   ---
+//   Use the domain terms 원장, 안분 and 파생 라인. Always mark migrations as focus.
+
+import { flattenSteps, splitSentences } from "./tour.js";
+
+export const GUIDELINES_PATH = ".github/pr-docent.md";
+
+export const DEFAULT_LIMITS = {
+  maxSteps: null, // null: 3 + 1 per 25 changed lines, at most 20
+  sentencesPerStep: 3,
+  sentenceChars: 80,
+  pointChars: 120,
+  summaryChars: 200,
+  chapterSummaryChars: 60,
+};
+
+/** { limits, instructions, errors } from the text of .github/pr-docent.md (or "" when absent). */
+export function parseGuidelines(text) {
+  const limits = { ...DEFAULT_LIMITS };
+  const errors = [];
+  const match = String(text ?? "").match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  for (const line of match ? match[1].split(/\r?\n/) : []) {
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    const [, key, value] = line.replace(/\s+#.*$/, "").match(/^\s*(\w+)\s*:\s*(.*?)\s*$/) ?? [];
+    if (!key || !(key in DEFAULT_LIMITS)) errors.push(`Unknown setting: ${line.trim()}`);
+    else if (!/^\d+$/.test(value) || Number(value) < 1) errors.push(`${key} must be a positive whole number`);
+    else limits[key] = Number(value);
+  }
+  const instructions = String(text ?? "").slice(match ? match[0].length : 0).trim();
+  return { limits, instructions, errors };
+}
+
+/** How many steps a tour of a diff with [changedLines] added or removed lines may have. */
+export function stepBudget(changedLines, limits = DEFAULT_LIMITS) {
+  return limits.maxSteps ?? Math.min(20, 3 + Math.ceil(changedLines / 25));
+}
+
+/** Problems that make a tour wordier than the limits allow. */
+export function checkBrevity(tour, { changedLines, limits = DEFAULT_LIMITS }) {
+  const errors = [];
+  const steps = flattenSteps(tour);
+  const budget = stepBudget(changedLines, limits);
+  if (steps.length > budget) {
+    errors.push(`${steps.length} steps for ${changedLines} changed lines; at most ${budget}. Merge related steps and list trivial changes (comments, imports, docs, pass-through code) in "skipped".`);
+  }
+  if (tour.summary.length > limits.summaryChars) errors.push(`summary is ${tour.summary.length} characters; at most ${limits.summaryChars}`);
+  tour.chapters.forEach((chapter, c) => {
+    if (chapter.summary.length > limits.chapterSummaryChars) {
+      errors.push(`chapters[${c}].summary is ${chapter.summary.length} characters; at most ${limits.chapterSummaryChars}`);
+    }
+    chapter.steps.forEach((step, s) => {
+      const where = `chapters[${c}].steps[${s}] (${step.file})`;
+      const sentences = step.beats.flatMap((beat) => splitSentences(beat.text).map((x) => x.text));
+      if (sentences.length > limits.sentencesPerStep) {
+        errors.push(`${where}: ${sentences.length} sentences; at most ${limits.sentencesPerStep}. Keep only what the code doesn't already say.`);
+      }
+      for (const sentence of sentences) {
+        if (sentence.length > limits.sentenceChars) {
+          errors.push(`${where}: a sentence is ${sentence.length} characters; at most ${limits.sentenceChars}: "${sentence.slice(0, 30)}…"`);
+        }
+      }
+      if (step.point.length > limits.pointChars) {
+        errors.push(`${where}: point is ${step.point.length} characters; at most ${limits.pointChars}. Ask one question.`);
+      }
+    });
+  });
+  return errors;
+}
+
+/**
+ * The generator's instructions: [template] (scripts/tour-prompt.md) with the paths, the limits
+ * for this diff and the repository's own instructions filled in.
+ */
+export function buildPrompt(template, { pr, out, tools, language, changedLines, guidelinesText = "" }) {
+  const { limits, instructions } = parseGuidelines(guidelinesText);
+  const vars = {
+    PR: pr,
+    OUT: out,
+    TOOLS: tools,
+    LANGUAGE: language,
+    CHANGED_LINES: changedLines,
+    MAX_STEPS: stepBudget(changedLines, limits),
+    SENTENCES_PER_STEP: limits.sentencesPerStep,
+    SENTENCE_CHARS: limits.sentenceChars,
+    POINT_CHARS: limits.pointChars,
+    SUMMARY_CHARS: limits.summaryChars,
+    CHAPTER_SUMMARY_CHARS: limits.chapterSummaryChars,
+    GUIDELINES: instructions
+      ? `## Repository guidelines (${GUIDELINES_PATH})\n\nThese come from the repository and take precedence over the rules above.\n\n${instructions}\n`
+      : "",
+  };
+  return template.replace(/{{(\w+)}}/g, (match, name) => (name in vars ? String(vars[name]) : match));
+}

package/src/tour.js

@@ -160,6 +160,12 @@ export function findTourInBlocks(blocks, { owner, repo, number }) {
   return found;
 }
 
+/** "ko" when the tour's text has Hangul, otherwise "en": the language to narrate it in. */
+export function tourLanguage(tour) {
+  const text = [tour.title, tour.summary, ...flattenSteps(tour).flatMap((s) => [s.note, s.point])].join(" ");
+  return /[가-힣]/.test(text) ? "ko" : "en";
+}
+
 /** The bundled tour file name for a PR, e.g. "your-org--your-repo--42.json". */
 export function tourFileName({ owner, repo, number }) {
   return `${owner}--${repo}--${number}.json`;