specdojo 0.3.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (104) hide show
  1. package/CHANGELOG.md +18 -0
  2. package/dist/catalog-build-references.js +144 -0
  3. package/dist/catalog-build-render.js +144 -0
  4. package/dist/catalog-build.js +13 -290
  5. package/dist/catalog-generate.js +6 -9
  6. package/dist/catalog-plan-generate.js +2 -2
  7. package/dist/catalog-plan.js +6 -6
  8. package/dist/catalog-scaffold.js +4 -4
  9. package/dist/catalog.js +2 -2
  10. package/dist/dashboard-exec-records.js +105 -0
  11. package/dist/dashboard-routines.js +255 -0
  12. package/dist/dashboard-shared.js +14 -0
  13. package/dist/dashboard-timeline.js +175 -0
  14. package/dist/dashboard.js +10 -544
  15. package/dist/deliverable-trash.js +3 -3
  16. package/dist/doc-index.js +3 -3
  17. package/dist/exec-commands.js +557 -0
  18. package/dist/exec-core.js +457 -0
  19. package/dist/exec-plans-core.js +693 -0
  20. package/dist/exec-plans-generation.js +206 -0
  21. package/dist/exec-plans-storage.js +131 -0
  22. package/dist/exec-plans.js +3 -1018
  23. package/dist/exec-repo-integration-git.js +23 -0
  24. package/dist/exec-repo-integration-sync.js +264 -0
  25. package/dist/exec-repo-integration.js +4 -281
  26. package/dist/exec-reporter-output.js +206 -0
  27. package/dist/exec-reporter.js +2 -206
  28. package/dist/exec-results.js +22 -15
  29. package/dist/exec-run-agent-pipeline.js +256 -0
  30. package/dist/exec-run-agent.js +531 -0
  31. package/dist/exec-run-in-place.js +541 -0
  32. package/dist/exec-run-job.js +717 -0
  33. package/dist/exec-run-lifecycle-commands.js +522 -0
  34. package/dist/exec-run-mode-shared.js +140 -0
  35. package/dist/exec-run-register-command.js +244 -0
  36. package/dist/exec-run-register-core.js +386 -0
  37. package/dist/exec-run-register-mode.js +206 -0
  38. package/dist/exec-run-register-resume.js +393 -0
  39. package/dist/exec-run-register-state.js +322 -0
  40. package/dist/exec-run-register-worktree.js +509 -0
  41. package/dist/exec-run-schedule-mode.js +294 -0
  42. package/dist/exec-run-schedule-prepare.js +353 -0
  43. package/dist/exec-run-schedule-task.js +572 -0
  44. package/dist/exec-run-shared.js +399 -0
  45. package/dist/exec-run.js +11 -6182
  46. package/dist/exec-shared.js +2 -2
  47. package/dist/exec-trial-commands.js +558 -0
  48. package/dist/exec-trial-core.js +371 -0
  49. package/dist/exec-trial.js +2 -921
  50. package/dist/exec-worktree-ops-commit.js +707 -0
  51. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  52. package/dist/exec-worktree-ops-merge.js +303 -0
  53. package/dist/exec-worktree-ops.js +3 -1292
  54. package/dist/exec-worktree.js +32 -4
  55. package/dist/exec.js +2 -1006
  56. package/dist/frontmatter-namespace.js +2 -2
  57. package/dist/grade-apply.js +734 -0
  58. package/dist/grade-command-apply.js +250 -0
  59. package/dist/grade-command-inspect.js +138 -0
  60. package/dist/grade-command-plan.js +101 -0
  61. package/dist/grade-command-shared.js +68 -0
  62. package/dist/grade-core.js +307 -0
  63. package/dist/grade-markdown.js +274 -0
  64. package/dist/grade-pipeline-state.js +184 -0
  65. package/dist/grade-plan.js +507 -0
  66. package/dist/grade-result.js +5 -5
  67. package/dist/grade-target-discovery.js +265 -0
  68. package/dist/grade-targets.js +432 -0
  69. package/dist/grade.js +14 -3188
  70. package/dist/init-command.js +7 -7
  71. package/dist/job-definition.js +670 -0
  72. package/dist/job.js +9 -673
  73. package/dist/kata-command.js +2 -2
  74. package/dist/register-command-types.js +1 -0
  75. package/dist/register-core.js +363 -0
  76. package/dist/register-create-commands.js +245 -0
  77. package/dist/register-events.js +4 -4
  78. package/dist/register-item.js +6 -6
  79. package/dist/register-maintenance-commands.js +187 -0
  80. package/dist/register-migration.js +268 -0
  81. package/dist/register-renumber.js +314 -0
  82. package/dist/register-transition-commands.js +248 -0
  83. package/dist/register-update.js +230 -0
  84. package/dist/register-views.js +256 -0
  85. package/dist/register.js +61 -2069
  86. package/dist/review-plan.js +3 -3
  87. package/dist/routine-definition.js +401 -0
  88. package/dist/routine.js +6 -402
  89. package/dist/schedule-approach.js +2 -2
  90. package/dist/schedule-strategy-generate-document.js +273 -0
  91. package/dist/schedule-strategy-generate-scope.js +199 -0
  92. package/dist/schedule-strategy-generate.js +9 -473
  93. package/dist/schedule.js +4 -4
  94. package/dist/specdojo-config.js +3 -4
  95. package/dist/viewpoint-document-kinds-check.js +3 -3
  96. package/dist/yaml-pages.js +4 -4
  97. package/dist/yaml.js +28 -0
  98. package/docs/ja/specdojo/guides/exec-config-guide.md +6 -6
  99. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +20 -18
  100. package/docs/ja/specdojo/guides/routine-operation-guide.md +1 -1
  101. package/package.json +4 -5
  102. package/templates/antigravity/README.md +3 -3
  103. package/templates/antigravity/exec-defaults-snippet.yaml +6 -4
  104. package/templates/init-exec-defaults.yaml +3 -1
package/dist/grade.js CHANGED
@@ -1,3193 +1,19 @@
1
- import { createHash } from "node:crypto";
2
- import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
3
- import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
- import yaml from "js-yaml";
5
- import remarkParse from "remark-parse";
6
- import { unified } from "unified";
7
- import { extractJsonArrayText, extractJsonText } from "./agent-response.js";
8
- import { collectResolvedDeliverables, loadCatalogDocs } from "./catalog-build.js";
9
- import { isTrashedPath, resolveBasePath } from "./catalog-paths.js";
10
- import { resolveViewpointsDoc, viewpointAppliesToDocument } from "./review-plan.js";
11
- import { assertValidActor, getProjectCatalogPath, getProjectExecutionPath, getProjectMembersPath, getProjectRolesPath, getProjectSchedulePath, getProjectViewpointsPath, loadConfig, loadMemberRoster, specdojoRootDir, } from "./specdojo-config.js";
12
- import { listFilesRecursive } from "./exec-shared.js";
13
- import { buildScheduleIndex } from "./exec-schedule-index.js";
14
- import { resolveSpecdojoPath } from "./template-resolution.js";
15
- import { applyGradeFindingTranslations, gradeContentHash, gradeFindingCount, gradeFindingTranslationInput, gradeResultPath, gradeResultPathForDocument, markdownDocumentId, readGradeResult, readGradeResultForDocument, resolveGradeResultsDirectory, validateGradeResult, writeGradeResult, } from "./grade-result.js";
16
- const GRADE_TARGETS = ["kata", "deliverable"];
17
- const FINDING_RE = /^[ \t]*<!--[ \t]*specdojo:finding[ \t]+id=([^ \t]+)[ \t]+severity=(blocker|major|minor|note)[ \t]+rule=([^ \t]+)(?:[ \t]+line=([1-9][0-9]*))?[ \t]+(.*?)[ \t]*-->[ \t]*(?:\r?\n|$)/gm;
18
- const KATA_DIRS = ["rulebooks", "recipes", "samples", "templates"];
19
- const KATA_REFERENCE_EXTENSIONS = new Set([".md", ".yaml", ".yml", ".json"]);
20
- const KATA_REFERENCE_FIELDS = ["rulebook", "recipe", "sample", "template"];
21
- const CRITERION_ID_RE = /^DC-[0-9]{3,}$/;
22
- const CRITERION_STATUSES = ["satisfied", "unsatisfied"];
23
- const DONE_CRITERIA_SCHEMA = "docs/specdojo/schemas/v1/grade-done-criteria.schema.yaml";
24
- const GRADE_PLACEHOLDER = "__SPECDOJO_GRADE_FLOW_PLACEHOLDER__";
25
- const GRADE_FINDINGS_PLACEHOLDER = "__SPECDOJO_GRADE_FINDINGS_FLOW_PLACEHOLDER__";
26
- const GRADE_UNSATISFIED_PLACEHOLDER = "__SPECDOJO_GRADE_UNSATISFIED_BLOCK_PLACEHOLDER__";
27
- export const GRADE_PLAN_EMBEDDED_DOCUMENT_CHARACTER_LIMIT = 100_000;
28
- const SEVERITY_LEVEL_CAP = {
29
- blocker: 0,
30
- major: 2,
31
- minor: 3,
32
- note: 4,
33
- };
34
- function preservePreviousFindingSeverities(body, viewpoints) {
35
- const previousByMessage = new Map();
36
- for (const finding of previousGradeFindings(body)) {
37
- const message = sanitizeCommentText(finding.message);
38
- const previous = previousByMessage.get(message);
39
- if (previous === undefined ||
40
- SEVERITY_LEVEL_CAP[finding.severity] < SEVERITY_LEVEL_CAP[previous]) {
41
- previousByMessage.set(message, finding.severity);
42
- }
43
- }
44
- return viewpoints.map((viewpoint) => {
45
- const findings = (viewpoint.findings ?? []).map((finding) => {
46
- const previous = previousByMessage.get(sanitizeCommentText(finding.message));
47
- return previous !== undefined &&
48
- SEVERITY_LEVEL_CAP[previous] < SEVERITY_LEVEL_CAP[finding.severity]
49
- ? { ...finding, severity: previous }
50
- : { ...finding };
51
- });
52
- return {
53
- ...viewpoint,
54
- findings,
55
- level: Math.min(viewpoint.level, levelCapForFindings(findings)),
56
- };
57
- });
58
- }
59
- function preserveStoredFindingSeverities(previous, viewpoints) {
60
- const previousByMessage = new Map();
61
- for (const finding of previous?.findings ?? []) {
62
- const message = sanitizeCommentText(finding.message);
63
- const stored = previousByMessage.get(message);
64
- if (stored === undefined || SEVERITY_LEVEL_CAP[finding.severity] < SEVERITY_LEVEL_CAP[stored]) {
65
- previousByMessage.set(message, finding.severity);
66
- }
67
- }
68
- return viewpoints.map((viewpoint) => {
69
- const findings = (viewpoint.findings ?? []).map((finding) => {
70
- const stored = previousByMessage.get(sanitizeCommentText(finding.message));
71
- return stored !== undefined &&
72
- SEVERITY_LEVEL_CAP[stored] < SEVERITY_LEVEL_CAP[finding.severity]
73
- ? { ...finding, severity: stored }
74
- : { ...finding };
75
- });
76
- return {
77
- ...viewpoint,
78
- findings,
79
- level: Math.min(viewpoint.level, levelCapForFindings(findings)),
80
- };
81
- });
82
- }
83
- function levelCapForFindings(findings) {
84
- const majorCount = findings.filter((finding) => finding.severity === "major").length;
85
- const severityCap = findings.reduce((current, finding) => Math.min(current, SEVERITY_LEVEL_CAP[finding.severity]), 4);
86
- return majorCount >= 2 ? Math.min(severityCap, 1) : severityCap;
87
- }
88
- function correctViewpointLevels(viewpoints) {
89
- const corrections = [];
90
- const corrected = viewpoints.map((viewpoint) => {
91
- const cap = levelCapForFindings(viewpoint.findings ?? []);
92
- const correctedLevel = Math.min(viewpoint.level, cap);
93
- if (correctedLevel !== viewpoint.level) {
94
- corrections.push({
95
- viewpoint: viewpoint.id,
96
- original_level: viewpoint.level,
97
- corrected_level: correctedLevel,
98
- });
99
- }
100
- return { ...viewpoint, level: correctedLevel };
101
- });
102
- return { viewpoints: corrected, corrections };
103
- }
104
- function isRecord(value) {
105
- return typeof value === "object" && value !== null && !Array.isArray(value);
106
- }
107
- function parseMarkdown(content, path) {
108
- const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
109
- if (!match)
110
- throw new Error(`${path}: Markdown frontmatter is required`);
111
- const parsed = yaml.load(match[1]);
112
- if (!isRecord(parsed) || !isRecord(parsed.specdojo)) {
113
- throw new Error(`${path}: frontmatter must contain a specdojo mapping`);
114
- }
115
- return { data: parsed, body: (match[2] ?? "").replace(/^(?:\r?\n)+/, "") };
116
- }
117
- function serializeGrade(grade) {
118
- const gradeForDump = structuredClone(grade);
119
- const findings = isRecord(gradeForDump.findings) ? gradeForDump.findings : undefined;
120
- if (findings)
121
- gradeForDump.findings = GRADE_FINDINGS_PLACEHOLDER;
122
- const doneCriteria = isRecord(gradeForDump.done_criteria)
123
- ? gradeForDump.done_criteria
124
- : undefined;
125
- const unsatisfied = doneCriteria && isRecord(doneCriteria.unsatisfied) ? doneCriteria.unsatisfied : undefined;
126
- if (doneCriteria && unsatisfied)
127
- doneCriteria.unsatisfied = GRADE_UNSATISFIED_PLACEHOLDER;
128
- let dumped = yaml
129
- .dump({ grade: gradeForDump },
130
- // categories / viewpoints の各値だけをフロー化する。grade 全体や各 collection
131
- // までフロー化すると一行が長くなり、差分も読みづらくなる。
132
- { lineWidth: 120, noRefs: true, flowLevel: 3, quotingType: '"' })
133
- .trimEnd();
134
- if (findings) {
135
- const inlineFindings = yaml
136
- .dump(findings, { lineWidth: -1, noRefs: true, flowLevel: 0 })
137
- .trimEnd();
138
- dumped = dumped.replace(GRADE_FINDINGS_PLACEHOLDER, inlineFindings);
139
- }
140
- if (unsatisfied) {
141
- // 未充足条件は viewpoints と同じく「条件ごとに1行、値はフロー」で記録する。
142
- // 条件数が増えても1行が伸びず、Prettier の整形後も同じ形を保つ。
143
- const blockUnsatisfied = yaml
144
- .dump(unsatisfied, { lineWidth: -1, noRefs: true, flowLevel: 1 })
145
- .trimEnd()
146
- .split("\n")
147
- .map((line) => ` ${line}`)
148
- .join("\n");
149
- dumped = dumped.replace(` unsatisfied: ${GRADE_UNSATISFIED_PLACEHOLDER}`, ` unsatisfied:\n${blockUnsatisfied}`);
150
- }
151
- // js-yaml は `{score: 100}`、Prettier は `{ score: 100 }` と出力する。
152
- // 最初から Prettier の形へ合わせ、整形と再評価の往復で差分が出ないようにする。
153
- return dumped.replace(/^(\s+[^:\n]+: )\{([^{}\n]*)\}$/gm, "$1{ $2 }");
154
- }
155
- function serializeMarkdown(document) {
156
- const dataForDump = structuredClone(document.data);
157
- const specdojo = isRecord(dataForDump.specdojo) ? dataForDump.specdojo : undefined;
158
- const grade = specdojo && isRecord(specdojo.grade) ? specdojo.grade : undefined;
159
- if (!specdojo || !grade) {
160
- return `---\n${yaml.dump(dataForDump, { lineWidth: 120, noRefs: true }).trimEnd()}\n---\n\n${document.body.replace(/^\n+/, "")}`;
161
- }
162
- specdojo.grade = GRADE_PLACEHOLDER;
163
- const gradeBlock = serializeGrade(grade)
164
- .split("\n")
165
- .map((line) => ` ${line}`)
166
- .join("\n");
167
- const frontmatter = yaml
168
- .dump(dataForDump, { lineWidth: 120, noRefs: true })
169
- .trimEnd()
170
- .replace(` grade: ${GRADE_PLACEHOLDER}`, gradeBlock);
171
- return `---\n${frontmatter}\n---\n\n${document.body.replace(/^\n+/, "")}`;
172
- }
173
- function withoutFindingComments(body) {
174
- return body.replace(FINDING_RE, "");
175
- }
176
- function normalizeContentForHash(body) {
177
- return body
178
- .replace(/\r\n?/g, "\n")
179
- .replace(/[ \t]+$/gm, "")
180
- .replace(/\n{3,}/g, "\n\n");
181
- }
182
- function previousGradeFindings(body) {
183
- return [...body.matchAll(FINDING_RE)].map((match) => ({
184
- severity: match[2],
185
- rule: match[3],
186
- ...(match[4] ? { line: Number(match[4]) } : {}),
187
- message: match[5].trim(),
188
- }));
189
- }
190
- // 移行前のインライン grade を読み取る互換 API だけが使用する旧ハッシュ。
191
- function legacyInlineContentHash(document) {
192
- const cloned = structuredClone(document.data);
193
- const specdojo = isRecord(cloned.specdojo) ? cloned.specdojo : {};
194
- delete specdojo.grade;
195
- return createHash("sha256")
196
- .update(yaml.dump(cloned, { sortKeys: true, noRefs: true, lineWidth: -1 }))
197
- .update("\n")
198
- .update(normalizeContentForHash(withoutFindingComments(document.body)))
199
- .digest("hex");
200
- }
201
- function stableContentHash(document) {
202
- return gradeContentHash(serializeMarkdown(document));
203
- }
204
- // pipeline 状態は成果物そのもののハッシュで識別する。grade apply は成果物を変更しないため、
205
- // grade / finding や空行を除外する正規化は不要である。
206
- export function pipelineContentHash(document) {
207
- return stableContentHash(document);
208
- }
209
- function sanitizeCommentText(value) {
210
- return (value
211
- .replace(/--+/g, "—")
212
- .replace(/[\r\n]+/g, " ")
213
- // 山括弧プレースホルダは HTML コメント内でもプロジェクトの lint が検知する。
214
- // コメント内ではインラインコードが機能しないため、全角へ置き換えて退避する。
215
- .replace(/</g, "<")
216
- .replace(/>/g, ">")
217
- .trim());
218
- }
219
- function findingComment(finding, rule) {
220
- return `<!-- specdojo:finding id=${finding.id} severity=${finding.severity} rule=${rule} line=${finding.line ?? 1} ${sanitizeCommentText(finding.message)} -->`;
221
- }
222
- function markdownBlockRanges(body) {
223
- const root = unified().use(remarkParse).parse(body);
224
- return root.children.flatMap((node) => {
225
- const startLine = node.position?.start.line;
226
- const endLine = node.position?.end.line;
227
- return startLine === undefined || endLine === undefined
228
- ? []
229
- : [
230
- {
231
- startLine,
232
- endLine,
233
- isHtmlComment: node.type === "html" &&
234
- "value" in node &&
235
- typeof node.value === "string" &&
236
- /^\s*<!--[\s\S]*-->\s*$/.test(node.value),
237
- },
238
- ];
239
- });
240
- }
241
- function safeFindingInsertionIndex(blocks, lines, requestedIndex) {
242
- const requestedLine = requestedIndex + 1;
243
- const containingIndex = blocks.findIndex((block) => block.startLine <= requestedLine && requestedLine <= block.endLine);
244
- if (containingIndex === -1)
245
- return requestedIndex;
246
- let insertionStartLine = blocks[containingIndex].startLine;
247
- for (let index = containingIndex - 1; index >= 0; index -= 1) {
248
- const candidate = blocks[index];
249
- if (!candidate.isHtmlComment)
250
- break;
251
- const linesBetween = lines.slice(candidate.endLine, insertionStartLine - 1);
252
- if (linesBetween.some((line) => line.trim() !== ""))
253
- break;
254
- insertionStartLine = candidate.startLine;
255
- }
256
- return insertionStartLine - 1;
257
- }
258
- function insertFindings(body, viewpoints) {
259
- const bodyWithoutFindings = withoutFindingComments(body);
260
- const lines = bodyWithoutFindings.split("\n");
261
- const blocks = markdownBlockRanges(bodyWithoutFindings);
262
- const insertions = new Map();
263
- const usedIds = new Set(viewpoints.flatMap((viewpoint) => (viewpoint.findings ?? []).flatMap((finding) => (finding.id ? [finding.id] : []))));
264
- let sequence = 0;
265
- for (const viewpoint of viewpoints) {
266
- for (const finding of viewpoint.findings ?? []) {
267
- let id = finding.id?.trim();
268
- if (!id) {
269
- do {
270
- sequence += 1;
271
- id = `F${String(sequence).padStart(3, "0")}`;
272
- } while (usedIds.has(id));
273
- usedIds.add(id);
274
- }
275
- const requestedIndex = Math.max(0, Math.min(lines.length, (finding.line ?? 1) - 1));
276
- // finding は対象行を含む最上位 Markdown ブロックの直前へ置く。これにより、
277
- // 入れ子リスト、表、引用、コードフェンス、複数行段落の内部を分断しない。
278
- // 対象行そのものはコメントの line 属性に残す。
279
- const index = safeFindingInsertionIndex(blocks, lines, requestedIndex);
280
- const existing = insertions.get(index) ?? [];
281
- existing.push(findingComment({ ...finding, id }, viewpoint.id));
282
- insertions.set(index, existing);
283
- }
284
- }
285
- const output = [];
286
- for (let index = 0; index <= lines.length; index += 1) {
287
- const comments = insertions.get(index) ?? [];
288
- // 直前が空行の場合は連続空行になるため詰める。agent が本文末尾を超える行番号を
289
- // 指定すると、末尾の空行の後ろへコメントが並び markdownlint の MD012 に触れる。
290
- if (comments.length > 0) {
291
- while (output.length > 0 && output[output.length - 1].trim() === "")
292
- output.pop();
293
- if (output.length > 0)
294
- output.push("");
295
- }
296
- output.push(...comments);
297
- if (index < lines.length)
298
- output.push(lines[index]);
299
- }
300
- return (output
301
- .join("\n")
302
- .replace(/^\n+/, "")
303
- .replace(/\n{3,}/g, "\n\n")
304
- // grade apply の出力だけで lint 可能な状態にする。走査は文書ごとの apply 間に
305
- // Prettier を実行しないため、入力由来の末尾空行をここで1改行へ正規化する。
306
- .replace(/(?:\n[ \t]*)*$/, "\n"));
307
- }
308
- function resolveProject(projectOption) {
309
- const { config } = loadConfig();
310
- if (!config)
311
- throw new Error("grade commands require .specdojo/specdojo.config.json");
312
- const id = projectOption?.trim() || config.current_project || Object.keys(config.projects)[0] || "";
313
- const project = config.projects[id];
314
- if (!project)
315
- throw new Error(`Unknown project: ${id}`);
316
- return { id, project };
317
- }
318
- function loadViewpoints(projectOption) {
319
- const { project } = resolveProject(projectOption);
320
- const path = getProjectViewpointsPath(project);
321
- if (!path)
322
- throw new Error("viewpoints_path is required for grade");
323
- return resolveViewpointsDoc(resolve(specdojoRootDir(), path));
324
- }
325
- // 対象探索は観点定義が無いプロジェクトでも動かす。その場合は突き合わせ先を持たない扱いにする。
326
- function loadViewpointsIfConfigured(projectOption, rootDir) {
327
- const path = getProjectViewpointsPath(resolveProject(projectOption).project);
328
- if (!path || !existsSync(resolve(rootDir, path)))
329
- return undefined;
330
- return resolveViewpointsDoc(resolve(rootDir, path));
331
- }
332
- export function resolveGradeActor(actor, roster) {
333
- const normalized = actor.trim();
334
- if (!normalized)
335
- throw new Error("--by must be a non-empty agent-members.yaml nickname");
336
- if (!roster)
337
- throw new Error("members_path is required for grade apply --by");
338
- assertValidActor(normalized, roster);
339
- if (roster.members.filter((member) => member.nickname === normalized).length !== 1) {
340
- throw new Error(`Duplicate actor nickname in members_path: ${normalized}`);
341
- }
342
- return normalized;
343
- }
344
- function assertRubric(doc) {
345
- const rubric = doc.grade_rubric;
346
- if (!rubric)
347
- throw new Error("Resolved viewpoints do not define grade_rubric");
348
- // すべての観点が grade の対象なので、重みのない category の観点は score へ黙って入らなくなる。
349
- for (const viewpoint of doc.viewpoints ?? []) {
350
- for (const target of viewpoint.grade_targets ?? GRADE_TARGETS) {
351
- const weight = rubric.weights[target]?.[viewpoint.category];
352
- if (typeof weight !== "number" || weight <= 0) {
353
- throw new Error(`grade_rubric ${rubric.id} has no ${target} weight for category '${viewpoint.category}' used by ${viewpoint.id}`);
354
- }
355
- }
356
- }
357
- return rubric;
358
- }
359
- function relativePathFromRoot(path, rootDir) {
360
- return relative(rootDir, path).replace(/\\/g, "/");
361
- }
362
- function repoRelativePath(path) {
363
- return relativePathFromRoot(path, specdojoRootDir());
364
- }
365
- function referenceIds(metadata) {
366
- return KATA_REFERENCE_FIELDS.flatMap((field) => {
367
- const value = metadata[field];
368
- if (typeof value === "string")
369
- return [value];
370
- if (Array.isArray(value))
371
- return value.filter((item) => typeof item === "string");
372
- return [];
373
- }).filter((id) => id !== "none" && id !== "undecided");
374
- }
375
- function parseKataReference(path, kind) {
376
- try {
377
- const extension = extname(path).toLowerCase();
378
- let metadata;
379
- if (extension === ".md") {
380
- metadata = parseMarkdown(readFileSync(path, "utf8"), repoRelativePath(path)).data
381
- .specdojo;
382
- }
383
- else {
384
- const parsed = yaml.load(readFileSync(path, "utf8"));
385
- if (!isRecord(parsed))
386
- return null;
387
- metadata = isRecord(parsed.specdojo) ? parsed.specdojo : parsed;
388
- }
389
- const id = typeof metadata.id === "string" ? metadata.id.trim() : "";
390
- if (!id)
391
- return null;
392
- return { id, path, kind, references: referenceIds(metadata) };
393
- }
394
- catch {
395
- // Some reusable snippets in Kata directories are Markdown fragments rather than documents.
396
- return null;
397
- }
398
- }
399
- // grade の評価対象は利用リポジトリが所有する kata に限る。package 側の kata は SpecDojo が
400
- // 管理する成果物であり、利用プロジェクトが評価・改善する対象ではない。フォールバックは
401
- // 個別ファイルの解決にのみ用い、対象の列挙には用いない(解決と列挙を区別する)。
402
- function loadKataReferences() {
403
- const references = new Map();
404
- const root = specdojoRootDir();
405
- for (const kind of KATA_DIRS) {
406
- const paths = listFilesRecursive(join(root, "docs/ja/specdojo", kind))
407
- .filter((path) => KATA_REFERENCE_EXTENSIONS.has(extname(path).toLowerCase()))
408
- .flatMap((path) => {
409
- const reference = parseKataReference(path, kind);
410
- return reference ? [reference] : [];
411
- });
412
- for (const reference of paths) {
413
- if (!references.has(reference.id))
414
- references.set(reference.id, reference);
415
- }
416
- }
417
- return [...references.values()];
418
- }
419
- function resolveGradeReferencePathsFromCatalog(path, catalog) {
420
- const target = resolveSafeMarkdownPath(path);
421
- const targetDocument = parseMarkdown(readFileSync(target, "utf8"), repoRelativePath(target));
422
- const targetMetadata = targetDocument.data.specdojo;
423
- const targetId = typeof targetMetadata.id === "string" ? targetMetadata.id.trim() : "";
424
- if (!targetId)
425
- return [];
426
- const byId = new Map(catalog.map((item) => [item.id, item]));
427
- const selected = new Map();
428
- const add = (item) => {
429
- if (item && item.path !== target)
430
- selected.set(item.id, item);
431
- };
432
- for (const id of referenceIds(targetMetadata))
433
- add(byId.get(id));
434
- for (const item of catalog)
435
- if (item.references.includes(targetId))
436
- add(item);
437
- // A document and the directly linked rulebook/recipe form the anchor of a Kata set.
438
- // Follow their declared links, but do not recursively traverse sibling back-links.
439
- for (let depth = 0; depth < 2; depth += 1) {
440
- for (const item of [...selected.values()]) {
441
- if (item.kind !== "rulebooks" && item.kind !== "recipes")
442
- continue;
443
- for (const id of item.references)
444
- add(byId.get(id));
445
- }
446
- }
447
- return [...selected.values()].map((item) => item.path).sort();
448
- }
449
- export function resolveGradeReferencePaths(path) {
450
- return resolveGradeReferencePathsFromCatalog(path, loadKataReferences());
451
- }
452
- function gradeReferenceExampleFamily(target, path, metadata) {
453
- if (target === "kata") {
454
- const rel = repoRelativePath(path);
455
- const kind = KATA_DIRS.find((candidate) => {
456
- const marker = `docs/ja/specdojo/${candidate}/`;
457
- return rel.startsWith(marker) || rel.includes(`/${marker}`);
458
- });
459
- if (kind)
460
- return kind;
461
- }
462
- const type = typeof metadata.type === "string" ? metadata.type.trim() : "";
463
- return type || null;
464
- }
465
- function parseGradeReferenceExample(path, target) {
466
- try {
467
- const absolute = resolveSafeMarkdownPath(path);
468
- const document = parseMarkdown(readFileSync(absolute, "utf8"), repoRelativePath(absolute));
469
- const metadata = document.data.specdojo;
470
- return {
471
- path: absolute,
472
- family: gradeReferenceExampleFamily(target, absolute, metadata),
473
- status: typeof metadata.status === "string" ? metadata.status.trim() : "",
474
- };
475
- }
476
- catch {
477
- return null;
478
- }
479
- }
480
- function selectGradeReferenceExampleFromCatalog(opts) {
481
- const target = resolveSafeMarkdownPath(opts.path);
482
- const targetDocument = parseMarkdown(readFileSync(target, "utf8"), repoRelativePath(target));
483
- const targetMetadata = targetDocument.data.specdojo;
484
- const family = gradeReferenceExampleFamily(opts.target, target, targetMetadata);
485
- if (!family)
486
- return undefined;
487
- // 同種別だけを候補にする。種別が違うと構造も目的も異なり、記載水準の基準として
488
- // 誤りを招く。template はプレースホルダを正解と誤解させ、rulebook は recipe の
489
- // 基準にならない。該当がなければリファレンスなしで評価する。
490
- const candidates = opts.candidates
491
- .filter((candidate) => candidate.path !== target && candidate.family === family && candidate.status === "ready")
492
- .map((candidate) => candidate.path)
493
- .sort();
494
- if (candidates.length === 0)
495
- return undefined;
496
- const random = opts.random ?? Math.random;
497
- const sample = random();
498
- const normalizedSample = Number.isFinite(sample) ? Math.max(0, sample) : 0;
499
- const index = Math.min(Math.floor(normalizedSample * candidates.length), candidates.length - 1);
500
- return candidates[index];
501
- }
502
- export function selectGradeReferenceExample(opts) {
503
- return selectGradeReferenceExampleFromCatalog({
504
- ...opts,
505
- candidates: opts.candidates.flatMap((candidate) => {
506
- const parsed = parseGradeReferenceExample(candidate, opts.target);
507
- return parsed ? [parsed] : [];
508
- }),
509
- });
510
- }
511
- function resolveSafeMarkdownPath(input, root = specdojoRootDir()) {
512
- const absolute = resolve(root, input);
513
- const rel = relativePathFromRoot(absolute, root);
514
- if (rel.startsWith("../") || isAbsolute(rel))
515
- throw new Error(`Path is outside repository: ${input}`);
516
- if (extname(absolute).toLowerCase() !== ".md") {
517
- throw new Error(`${input}: grade currently writes inline findings only for Markdown`);
518
- }
519
- if (!existsSync(absolute))
520
- throw new Error(`Document not found: ${input}`);
521
- return absolute;
522
- }
523
- function resolveSafeRepositoryPath(input, option) {
524
- const root = specdojoRootDir();
525
- const absolute = resolve(root, input);
526
- const rel = relative(root, absolute);
527
- if (rel.startsWith("../") || isAbsolute(rel)) {
528
- throw new Error(`${option} must be inside the repository`);
529
- }
530
- return absolute;
531
- }
532
- function isGeneratedGradeTarget(path, rootDir = specdojoRootDir()) {
533
- return relativePathFromRoot(path, rootDir).split("/").includes("generated");
534
- }
535
- function isTrashedGradeTarget(path, rootDir = specdojoRootDir()) {
536
- return isTrashedPath(relativePathFromRoot(path, rootDir));
537
- }
538
- function criterionId(index) {
539
- return `DC-${String(index + 1).padStart(3, "0")}`;
540
- }
541
- // カタログの Markdown 成果物を絶対パスで引ける形にする。grade の対象探索と
542
- // done_criteria の解決が同じ集合を見るよう、両者はこの関数を共有する。
543
- function loadDeliverableCatalog(projectOption, root = specdojoRootDir()) {
544
- const { project } = resolveProject(projectOption);
545
- const catalog = getProjectCatalogPath(project);
546
- if (!catalog)
547
- throw new Error("catalog_path is required for deliverable grading");
548
- const entries = new Map();
549
- for (const loaded of loadCatalogDocs(resolve(root, catalog))) {
550
- const resolved = [];
551
- collectResolvedDeliverables(loaded.doc.groups, resolveBasePath("", loaded.doc.base_path), resolved);
552
- for (const item of resolved) {
553
- if (item.item.kind === "generated" || !item.item.path)
554
- continue;
555
- if (!item.resolvedPath.endsWith(".md"))
556
- continue;
557
- if (isTrashedPath(item.resolvedPath))
558
- continue;
559
- const path = resolve(root, item.resolvedPath);
560
- if (!existsSync(path) || entries.has(path))
561
- continue;
562
- entries.set(path, {
563
- path,
564
- localId: item.item.local_id,
565
- dependsOn: item.item.depends_on,
566
- entryHash: gradeContentHash(stableJson(item.item)),
567
- doneCriteria: (item.item.done_criteria ?? []).map((criterion, index) => ({
568
- id: criterionId(index),
569
- text: criterion.text,
570
- roles: [...criterion.roles],
571
- viewpoint: criterion.viewpoint,
572
- })),
573
- });
574
- }
575
- }
576
- return entries;
577
- }
578
- // 成果物ごとの done_criteria 定義を、submission が使うリポジトリ相対パスで引ける形にする。
579
- // カタログに無い文書(--path で明示した非カタログ文書)は含めず、plan と apply は
580
- // 定義が無い文書を「完了条件なし」として扱う。
581
- export function resolveDeliverableDoneCriteria(paths, projectOption) {
582
- const catalog = loadDeliverableCatalog(projectOption);
583
- const result = new Map();
584
- for (const path of paths) {
585
- const entry = catalog.get(resolveSafeMarkdownPath(path));
586
- if (entry && entry.doneCriteria.length > 0) {
587
- result.set(repoRelativePath(entry.path), entry.doneCriteria);
588
- }
589
- }
590
- return result;
591
- }
592
- // キー順に依存しない直列化。カタログ項目の hash が YAML 上のキー順の入れ替えで変わらないようにする。
593
- function stableJson(value) {
594
- if (Array.isArray(value))
595
- return `[${value.map((item) => stableJson(item)).join(",")}]`;
596
- if (isRecord(value)) {
597
- const keys = Object.keys(value)
598
- .filter((key) => value[key] !== undefined)
599
- .sort();
600
- return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
601
- }
602
- return JSON.stringify(value) ?? "null";
603
- }
604
- // 突き合わせ先の変更検出(PJR-Z47X)。観点が comparison_sources で宣言した突き合わせ先と、
605
- // 成果物の depends_on 先の hash を grade result の source_hashes へ記録し、
606
- // --changed-only と --dependency-changed が現在の hash と比較する。
607
- const COMPARISON_SOURCE_RE = /^(catalog-entry|dependencies|schedule|members|roles|deliverable:[a-z0-9][a-z0-9-]*)$/;
608
- // 突き合わせ先が存在しないことも状態として記録し、後から作られた場合に変更として検出する。
609
- const ABSENT_SOURCE_HASH = gradeContentHash("specdojo:grade-comparison-source-absent");
610
- function createGradeSourceContext(projectOption, rootDir) {
611
- return {
612
- rootDir,
613
- project: resolveProject(projectOption).project,
614
- projectOption,
615
- hashes: new Map(),
616
- };
617
- }
618
- function sourceCatalog(context) {
619
- if (!context.catalog || !context.localIdToPath) {
620
- context.catalog = getProjectCatalogPath(context.project)
621
- ? loadDeliverableCatalog(context.projectOption, context.rootDir)
622
- : new Map();
623
- context.localIdToPath = new Map([...context.catalog.entries()].map(([path, entry]) => [entry.localId, path]));
624
- }
625
- return { catalog: context.catalog, localIdToPath: context.localIdToPath };
626
- }
627
- function hashSourceFile(path) {
628
- if (!path || !existsSync(path))
629
- return ABSENT_SOURCE_HASH;
630
- return gradeContentHash(readFileSync(path, "utf8"));
631
- }
632
- // ディレクトリはファイルの相対パスと内容の組で hash する。生成物は生成元の変更で検出する。
633
- function hashSourceDirectory(path) {
634
- const files = listFilesRecursive(path)
635
- .filter((file) => !relativePathFromRoot(file, path).split("/").includes("generated"))
636
- .sort();
637
- if (files.length === 0)
638
- return ABSENT_SOURCE_HASH;
639
- const hash = createHash("sha256");
640
- for (const file of files) {
641
- hash.update(`${relativePathFromRoot(file, path)}\0${hashSourceFile(file)}\n`);
642
- }
643
- return hash.digest("hex");
644
- }
645
- function sharedSourceHash(key, context) {
646
- const cached = context.hashes.get(key);
647
- if (cached !== undefined)
648
- return cached;
649
- let hash;
650
- if (key === "schedule") {
651
- hash = hashSourceDirectory(resolve(context.rootDir, getProjectSchedulePath(context.project)));
652
- }
653
- else if (key === "members" || key === "roles") {
654
- const path = key === "members"
655
- ? getProjectMembersPath(context.project)
656
- : getProjectRolesPath(context.project);
657
- hash = hashSourceFile(path ? resolve(context.rootDir, path) : undefined);
658
- }
659
- else {
660
- const localId = key.slice(key.indexOf(":") + 1);
661
- hash = hashSourceFile(sourceCatalog(context).localIdToPath.get(localId));
662
- }
663
- context.hashes.set(key, hash);
664
- return hash;
665
- }
666
- function gradedComparisonSources(viewpoints, target, metadata) {
667
- if (!viewpoints)
668
- return [];
669
- const sources = new Set();
670
- for (const viewpoint of gradedViewpoints(viewpoints, target, metadata)) {
671
- for (const source of viewpoint.comparison_sources ?? []) {
672
- if (!COMPARISON_SOURCE_RE.test(source)) {
673
- throw new Error(`${viewpoint.id}: unknown comparison source ${source}`);
674
- }
675
- sources.add(source);
676
- }
677
- }
678
- return [...sources].sort();
679
- }
680
- // depends_on のうちカタログで Markdown 成果物に解決できるものだけを依存先として扱う。
681
- function dependencySourceKeys(documentPath, context) {
682
- const { catalog, localIdToPath } = sourceCatalog(context);
683
- return (catalog.get(documentPath)?.dependsOn ?? [])
684
- .filter((localId) => localIdToPath.has(localId))
685
- .map((localId) => `dependency:${localId}`)
686
- .sort();
687
- }
688
- function comparisonSourceKeys(sources, documentPath, context) {
689
- return sources.flatMap((source) => source === "dependencies" ? dependencySourceKeys(documentPath, context) : [source]);
690
- }
691
- function currentSourceHashes(keys, documentPath, context) {
692
- const hashes = {};
693
- for (const key of [...new Set(keys)].sort()) {
694
- if (key === "catalog-entry") {
695
- hashes[key] =
696
- sourceCatalog(context).catalog.get(documentPath)?.entryHash ?? ABSENT_SOURCE_HASH;
697
- }
698
- else if (key.startsWith("dependency:")) {
699
- const localId = key.slice("dependency:".length);
700
- hashes[key] = hashSourceFile(sourceCatalog(context).localIdToPath.get(localId));
701
- }
702
- else {
703
- hashes[key] = sharedSourceHash(key, context);
704
- }
705
- }
706
- return hashes;
707
- }
708
- // grade result へ記録する突き合わせ先の hash。宣言された突き合わせ先に加え、成果物では
709
- // --dependency-changed が使う depends_on 先を、観点の宣言に関係なく記録する。
710
- function gradeSourceHashes(documentPath, document, viewpoints, target, context) {
711
- const metadata = isRecord(document.data.specdojo) ? document.data.specdojo : {};
712
- const keys = [
713
- ...comparisonSourceKeys(gradedComparisonSources(viewpoints, target, metadata), documentPath, context),
714
- ...(target === "deliverable" ? dependencySourceKeys(documentPath, context) : []),
715
- ];
716
- return currentSourceHashes(keys, documentPath, context);
717
- }
718
- /** Current hashes of the comparison sources and dependencies that grade apply records for a document. */
719
- export function resolveGradeSourceHashes(opts, rootDir = specdojoRootDir()) {
720
- const absolute = resolveSafeMarkdownPath(opts.path, rootDir);
721
- const document = parseMarkdown(readFileSync(absolute, "utf8"), relativePathFromRoot(absolute, rootDir));
722
- const viewpoints = opts.viewpoints ?? loadViewpointsIfConfigured(opts.project, rootDir);
723
- return gradeSourceHashes(absolute, document, viewpoints, opts.target, createGradeSourceContext(opts.project, rootDir));
724
- }
725
- // 記録の無い突き合わせ先(source tracking 導入前の結果を含む)は、鮮度を保証できないため変更として扱う。
726
- function sourceHashesChanged(stored, current) {
727
- return Object.entries(current).some(([key, hash]) => stored?.[key] !== hash);
728
- }
729
- function gradePipelineStateDirectory(projectOption, rootDir = specdojoRootDir()) {
730
- const { project } = resolveProject(projectOption);
731
- return resolve(rootDir, getProjectExecutionPath(project), "grade", "pipeline");
732
- }
733
- function gradePipelineStatePath(documentPath, projectOption, rootDir = specdojoRootDir()) {
734
- const relativeDocument = relativePathFromRoot(resolve(rootDir, documentPath), rootDir);
735
- const stem = basename(relativeDocument, extname(relativeDocument)).replace(/[^A-Za-z0-9._-]/g, "-");
736
- const digest = createHash("sha256").update(relativeDocument).digest("hex").slice(0, 12);
737
- return join(gradePipelineStateDirectory(projectOption, rootDir), `${stem}-${digest}.json`);
738
- }
739
- function parseGradePipelineState(value, path) {
740
- if (!isRecord(value))
741
- throw new Error(`${path}: grade pipeline state must be an object`);
742
- const integer = (key, minimum) => {
743
- const candidate = value[key];
744
- if (!Number.isSafeInteger(candidate) || candidate < minimum) {
745
- throw new Error(`${path}: ${key} must be an integer >= ${minimum}`);
746
- }
747
- return candidate;
748
- };
749
- const text = (key) => {
750
- const candidate = value[key];
751
- if (typeof candidate !== "string" || !candidate.trim()) {
752
- throw new Error(`${path}: ${key} must be a non-empty string`);
753
- }
754
- return candidate;
755
- };
756
- const target = value.target;
757
- if (target !== "kata" && target !== "deliverable") {
758
- throw new Error(`${path}: target must be kata or deliverable`);
759
- }
760
- const stageFailed = value.stage_failed;
761
- if (stageFailed !== null && (!Number.isSafeInteger(stageFailed) || stageFailed < 1)) {
762
- throw new Error(`${path}: stage_failed must be null or a positive integer`);
763
- }
764
- const state = {
765
- version: integer("version", 1),
766
- project_id: text("project_id"),
767
- target,
768
- document: text("document"),
769
- content_hash: text("content_hash"),
770
- stage_completed: integer("stage_completed", 0),
771
- stage_failed: stageFailed,
772
- stage_total: integer("stage_total", 1),
773
- consecutive_failures: integer("consecutive_failures", 0),
774
- max_failures: integer("max_failures", 1),
775
- last_run_id: text("last_run_id"),
776
- updated_at: text("updated_at"),
777
- };
778
- if (state.version !== 1)
779
- throw new Error(`${path}: unsupported grade pipeline state version`);
780
- if (!/^[a-f0-9]{64}$/.test(state.content_hash)) {
781
- throw new Error(`${path}: content_hash must be a SHA-256 hex digest`);
782
- }
783
- if (isAbsolute(state.document) ||
784
- !state.document.startsWith("docs/") ||
785
- state.document.split("/").includes("..")) {
786
- throw new Error(`${path}: document must be a repository-relative path below docs/`);
787
- }
788
- if (state.stage_completed >= state.stage_total) {
789
- throw new Error(`${path}: completed pipeline state must be removed`);
790
- }
791
- if (state.stage_failed !== null && state.stage_failed !== state.stage_completed + 1) {
792
- throw new Error(`${path}: stage_failed must immediately follow stage_completed`);
793
- }
794
- if ((state.stage_failed === null && state.consecutive_failures !== 0) ||
795
- (state.stage_failed !== null && state.consecutive_failures < 1)) {
796
- throw new Error(`${path}: consecutive_failures does not match stage_failed`);
797
- }
798
- return state;
799
- }
800
- function loadGradePipelineStates(projectOption, rootDir = specdojoRootDir()) {
801
- const states = new Map();
802
- const projectId = resolveProject(projectOption).id;
803
- for (const path of listFilesRecursive(gradePipelineStateDirectory(projectOption, rootDir))) {
804
- if (!path.endsWith(".json"))
805
- continue;
806
- const state = parseGradePipelineState(JSON.parse(readFileSync(path, "utf8")), relativePathFromRoot(path, rootDir));
807
- if (state.project_id !== projectId) {
808
- throw new Error(`${relativePathFromRoot(path, rootDir)}: project_id must be ${projectId}`);
809
- }
810
- states.set(state.document, state);
811
- }
812
- return states;
813
- }
814
- function currentGradePipelineState(document, path, state, target) {
815
- if (!state || state.document !== path || (target !== undefined && state.target !== target)) {
816
- return undefined;
817
- }
818
- return state.content_hash === pipelineContentHash(document) ? state : undefined;
819
- }
820
- function isIncompleteGradePipelineState(state) {
821
- return state !== undefined && state.consecutive_failures < state.max_failures;
822
- }
823
- export function readGradePipelineState(opts) {
824
- const absolute = resolveSafeMarkdownPath(opts.path);
825
- const relativeDocument = repoRelativePath(absolute);
826
- const statePath = gradePipelineStatePath(relativeDocument, opts.project);
827
- if (!existsSync(statePath))
828
- return undefined;
829
- const state = parseGradePipelineState(JSON.parse(readFileSync(statePath, "utf8")), repoRelativePath(statePath));
830
- const projectId = resolveProject(opts.project).id;
831
- if (state.project_id !== projectId) {
832
- throw new Error(`${repoRelativePath(statePath)}: project_id must be ${projectId}`);
833
- }
834
- const document = parseMarkdown(readFileSync(absolute, "utf8"), relativeDocument);
835
- return currentGradePipelineState(document, relativeDocument, state, opts.target);
836
- }
837
- export function listExhaustedGradePipelineStates(opts) {
838
- const states = loadGradePipelineStates(opts.project);
839
- return [...states.values()]
840
- .filter((state) => {
841
- if (state.target !== opts.target || state.consecutive_failures < state.max_failures)
842
- return false;
843
- const absolute = resolve(specdojoRootDir(), state.document);
844
- if (!existsSync(absolute))
845
- return false;
846
- const document = parseMarkdown(readFileSync(absolute, "utf8"), state.document);
847
- return currentGradePipelineState(document, state.document, state, opts.target) !== undefined;
848
- })
849
- .sort((left, right) => left.document.localeCompare(right.document));
850
- }
851
- export function recordGradePipelineStage(opts) {
852
- const absolute = resolveSafeMarkdownPath(opts.path);
853
- const relativeDocument = repoRelativePath(absolute);
854
- const statePath = gradePipelineStatePath(relativeDocument, opts.project);
855
- if (opts.status === "complete") {
856
- if (existsSync(statePath))
857
- unlinkSync(statePath);
858
- return undefined;
859
- }
860
- if (!Number.isSafeInteger(opts.stage) ||
861
- opts.stage < 1 ||
862
- !Number.isSafeInteger(opts.stageTotal) ||
863
- opts.stageTotal < opts.stage ||
864
- !Number.isSafeInteger(opts.maxFailures) ||
865
- opts.maxFailures < 1) {
866
- throw new Error("grade pipeline stage, total, and failure limit are invalid");
867
- }
868
- const document = parseMarkdown(readFileSync(absolute, "utf8"), relativeDocument);
869
- const previous = readGradePipelineState({
870
- target: opts.target,
871
- project: opts.project,
872
- path: relativeDocument,
873
- });
874
- const previousCompleted = previous?.stage_completed ?? 0;
875
- if (opts.stage !== previousCompleted + 1) {
876
- throw new Error(`grade pipeline stage ${opts.stage} must immediately follow completed stage ${previousCompleted}`);
877
- }
878
- const stageCompleted = opts.status === "passed" ? opts.stage : Math.min(previousCompleted, opts.stage - 1);
879
- if (stageCompleted >= opts.stageTotal) {
880
- if (existsSync(statePath))
881
- unlinkSync(statePath);
882
- return undefined;
883
- }
884
- const state = {
885
- version: 1,
886
- project_id: resolveProject(opts.project).id,
887
- target: opts.target,
888
- document: relativeDocument,
889
- content_hash: pipelineContentHash(document),
890
- stage_completed: stageCompleted,
891
- stage_failed: opts.status === "failed" ? opts.stage : null,
892
- stage_total: opts.stageTotal,
893
- consecutive_failures: opts.status === "failed"
894
- ? previous?.stage_failed === opts.stage
895
- ? previous.consecutive_failures + 1
896
- : 1
897
- : 0,
898
- max_failures: opts.maxFailures,
899
- last_run_id: opts.runId,
900
- updated_at: (opts.now ?? new Date()).toISOString(),
901
- };
902
- mkdirSync(dirname(statePath), { recursive: true });
903
- writeFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
904
- return state;
905
- }
906
- export function discoverGradeTargets(opts, rootDir = specdojoRootDir()) {
907
- validateGradeTargetFilters(opts);
908
- let candidates;
909
- if (opts.paths && opts.paths.length > 0) {
910
- candidates = opts.paths.map((path) => resolveSafeMarkdownPath(path, rootDir));
911
- const generated = candidates.find((path) => isGeneratedGradeTarget(path, rootDir));
912
- if (generated) {
913
- throw new Error(`${relativePathFromRoot(generated, rootDir)}: generated documents cannot be graded`);
914
- }
915
- const trashed = candidates.find((path) => isTrashedGradeTarget(path, rootDir));
916
- if (trashed) {
917
- throw new Error(`${relativePathFromRoot(trashed, rootDir)}: trashed documents cannot be graded`);
918
- }
919
- }
920
- else if (opts.target === "kata") {
921
- // 対象の列挙は利用リポジトリ限定。eject されていない kata は評価対象にしない。
922
- candidates = KATA_DIRS.flatMap((dir) => listFilesRecursive(join(rootDir, "docs/ja/specdojo", dir)).filter((entry) => entry.endsWith(".md")));
923
- }
924
- else {
925
- candidates = [...loadDeliverableCatalog(opts.project, rootDir).keys()];
926
- }
927
- const unique = [...new Set(candidates)]
928
- .filter((path) => !isGeneratedGradeTarget(path, rootDir))
929
- .filter((path) => !isTrashedGradeTarget(path, rootDir))
930
- .sort();
931
- if (!opts.changedOnly &&
932
- !opts.dependencyChanged &&
933
- !opts.rulebookChanged &&
934
- !opts.unreviewed &&
935
- opts.verdict === undefined &&
936
- opts.minScore === undefined &&
937
- opts.maxFindings === undefined &&
938
- !opts.ungraded &&
939
- !opts.incomplete &&
940
- !opts.rubricOutdated) {
941
- return unique;
942
- }
943
- const pipelineStates = opts.incomplete
944
- ? loadGradePipelineStates(opts.project, rootDir)
945
- : new Map();
946
- const sourceContext = createGradeSourceContext(opts.project, rootDir);
947
- const viewpoints = opts.changedOnly || opts.rubricOutdated
948
- ? loadViewpointsIfConfigured(opts.project, rootDir)
949
- : undefined;
950
- const currentRubricId = opts.rubricOutdated ? currentGradeRubricId(viewpoints) : undefined;
951
- let scheduledDocuments;
952
- if (opts.unreviewed) {
953
- const { project } = resolveProject(opts.project);
954
- const schedulePath = join(rootDir, getProjectExecutionPath(project), "../schedule");
955
- try {
956
- const index = buildScheduleIndex(schedulePath);
957
- scheduledDocuments = new Set();
958
- for (const node of index.nodes.values()) {
959
- if (node.local_id)
960
- scheduledDocuments.add(node.local_id);
961
- if (node.target_local_ids) {
962
- for (const tid of node.target_local_ids)
963
- scheduledDocuments.add(tid);
964
- }
965
- }
966
- }
967
- catch {
968
- scheduledDocuments = new Set();
969
- }
970
- }
971
- const gradeDates = new Map();
972
- function getMemoizedGradeDate(p) {
973
- if (!gradeDates.has(p)) {
974
- const res = readGradeResultForDocument({
975
- documentPath: relativePathFromRoot(p, rootDir),
976
- project: opts.project,
977
- rootDir,
978
- });
979
- gradeDates.set(p, res ? new Date(res.graded_at).getTime() : 0);
980
- }
981
- return gradeDates.get(p);
982
- }
983
- function getRulebookPath(rulebookId) {
984
- if (rulebookId.startsWith("specdojo:")) {
985
- const id = rulebookId.slice("specdojo:".length);
986
- return join(rootDir, "docs/ja/specdojo/rulebooks", `${id}.md`);
987
- }
988
- return undefined;
989
- }
990
- return unique.filter((path) => {
991
- const rel = relativePathFromRoot(path, rootDir);
992
- const content = readFileSync(path, "utf8");
993
- const document = parseMarkdown(content, rel);
994
- const pipelineState = currentGradePipelineState(document, rel, pipelineStates.get(rel), opts.target);
995
- const result = readGradeResultForDocument({
996
- documentPath: rel,
997
- project: opts.project,
998
- rootDir,
999
- });
1000
- if (opts.verdict !== undefined && (result === undefined || result.verdict !== opts.verdict)) {
1001
- return false;
1002
- }
1003
- if (opts.minScore !== undefined && (result === undefined || result.score < opts.minScore)) {
1004
- return false;
1005
- }
1006
- if (opts.maxFindings !== undefined &&
1007
- (result === undefined || gradeFindingCount(result) > opts.maxFindings)) {
1008
- return false;
1009
- }
1010
- if (opts.unreviewed) {
1011
- if (!scheduledDocuments)
1012
- return false;
1013
- const id = document.data.specdojo?.id;
1014
- if (!id || scheduledDocuments.has(id.split(":").pop()))
1015
- return false;
1016
- if (result !== undefined && result.content_hash === gradeContentHash(content))
1017
- return false;
1018
- }
1019
- if (opts.incomplete && pipelineState) {
1020
- if (!isIncompleteGradePipelineState(pipelineState))
1021
- return false;
1022
- }
1023
- else if (opts.incomplete) {
1024
- return false;
1025
- }
1026
- if (opts.ungraded && result !== undefined)
1027
- return false;
1028
- if (currentRubricId !== undefined && !isGradeRubricOutdated(result, currentRubricId)) {
1029
- return false;
1030
- }
1031
- if (result === undefined) {
1032
- if (opts.dependencyChanged || opts.rulebookChanged)
1033
- return false;
1034
- return true;
1035
- }
1036
- const docDate = new Date(result.graded_at).getTime();
1037
- if (opts.rulebookChanged) {
1038
- const rb = document.data.specdojo?.rulebook;
1039
- if (!rb)
1040
- return false;
1041
- const rbPath = getRulebookPath(rb);
1042
- if (!rbPath || !existsSync(rbPath))
1043
- return false;
1044
- if (getMemoizedGradeDate(rbPath) <= docDate)
1045
- return false;
1046
- }
1047
- // 依存先の評価日時ではなく内容の hash で判定する。再評価しただけの依存先は変更扱いにしない。
1048
- if (opts.dependencyChanged) {
1049
- if (opts.target !== "deliverable")
1050
- return false;
1051
- const keys = dependencySourceKeys(path, sourceContext);
1052
- if (keys.length === 0)
1053
- return false;
1054
- const current = currentSourceHashes(keys, path, sourceContext);
1055
- if (!sourceHashesChanged(result.source_hashes, current))
1056
- return false;
1057
- }
1058
- if (opts.changedOnly && result.content_hash === gradeContentHash(content)) {
1059
- const metadata = isRecord(document.data.specdojo) ? document.data.specdojo : {};
1060
- const keys = comparisonSourceKeys(gradedComparisonSources(viewpoints, opts.target, metadata), path, sourceContext);
1061
- if (keys.length === 0)
1062
- return false;
1063
- const current = currentSourceHashes(keys, path, sourceContext);
1064
- if (!sourceHashesChanged(result.source_hashes, current))
1065
- return false;
1066
- }
1067
- return true;
1068
- });
1069
- }
1070
- function currentGradeRubricId(viewpoints) {
1071
- const id = viewpoints?.grade_rubric?.id;
1072
- if (typeof id !== "string" || id.length === 0) {
1073
- throw new Error("--rubric-outdated requires grade_rubric.id in the resolved review viewpoints");
1074
- }
1075
- return id;
1076
- }
1077
- // 保存済みの結果が現在の rubric 以外で付けられたかを判定する。rubric の記録がない結果は
1078
- // どの版で付けたか確かめられないため旧版として扱う。結果がない文書は --ungraded の対象である。
1079
- export function isGradeRubricOutdated(result, currentRubricId) {
1080
- if (result === undefined)
1081
- return false;
1082
- if (typeof result.rubric !== "string" || result.rubric.length === 0)
1083
- return true;
1084
- return result.rubric !== currentRubricId;
1085
- }
1086
- function validateGradeTargetFilters(filters) {
1087
- if (filters.verdict !== undefined &&
1088
- filters.verdict !== "pass" &&
1089
- filters.verdict !== "needs-work" &&
1090
- filters.verdict !== "fail") {
1091
- throw new Error("--verdict must be pass, needs-work, or fail");
1092
- }
1093
- if (filters.minScore !== undefined &&
1094
- (!Number.isSafeInteger(filters.minScore) || filters.minScore < 0 || filters.minScore > 100)) {
1095
- throw new Error("--min-score must be an integer between 0 and 100");
1096
- }
1097
- if (filters.maxFindings !== undefined &&
1098
- (!Number.isSafeInteger(filters.maxFindings) || filters.maxFindings < 0)) {
1099
- throw new Error("--max-findings must be a non-negative integer");
1100
- }
1101
- if (filters.ungraded &&
1102
- (filters.verdict !== undefined ||
1103
- filters.minScore !== undefined ||
1104
- filters.maxFindings !== undefined)) {
1105
- throw new Error("--ungraded cannot be combined with --verdict, --min-score, or --max-findings");
1106
- }
1107
- if (filters.ungraded && filters.rubricOutdated) {
1108
- throw new Error("--ungraded cannot be combined with --rubric-outdated");
1109
- }
1110
- }
1111
- function storedGradeScore(grade, path) {
1112
- const score = grade.score;
1113
- if (!Number.isSafeInteger(score) || score < 0 || score > 100) {
1114
- throw new Error(`${path}: specdojo.grade.score must be an integer between 0 and 100`);
1115
- }
1116
- return score;
1117
- }
1118
- function storedFindingCount(grade, path) {
1119
- const findings = grade.findings;
1120
- if (!isRecord(findings))
1121
- throw new Error(`${path}: specdojo.grade.findings is missing`);
1122
- return ["blocker", "major", "minor", "note"].reduce((total, severity) => {
1123
- const count = findings[severity];
1124
- if (!Number.isSafeInteger(count) || count < 0) {
1125
- throw new Error(`${path}: specdojo.grade.findings.${severity} must be a non-negative integer`);
1126
- }
1127
- return total + count;
1128
- }, 0);
1129
- }
1130
- function matchesParsedGradeTargetFilters(document, path, filters, incomplete = false) {
1131
- if (filters.dependencyChanged ||
1132
- filters.rulebookChanged ||
1133
- filters.unreviewed ||
1134
- filters.rubricOutdated) {
1135
- throw new Error("dependencyChanged, rulebookChanged, unreviewed, rubricOutdated cannot be evaluated individually without context");
1136
- }
1137
- const specdojo = document.data.specdojo;
1138
- const grade = isRecord(specdojo.grade) ? specdojo.grade : undefined;
1139
- if (filters.incomplete && !incomplete)
1140
- return false;
1141
- if (filters.ungraded && grade !== undefined)
1142
- return false;
1143
- if (filters.verdict !== undefined && grade?.verdict !== filters.verdict)
1144
- return false;
1145
- if (filters.minScore !== undefined &&
1146
- (grade === undefined || storedGradeScore(grade, path) < filters.minScore)) {
1147
- return false;
1148
- }
1149
- if (filters.maxFindings !== undefined &&
1150
- (grade === undefined || storedFindingCount(grade, path) > filters.maxFindings)) {
1151
- return false;
1152
- }
1153
- return !filters.changedOnly || grade?.content_hash !== legacyInlineContentHash(document);
1154
- }
1155
- export function matchesGradeTargetFilters(content, path, filters, pipelineState) {
1156
- validateGradeTargetFilters(filters);
1157
- const document = parseMarkdown(content, path);
1158
- const currentState = currentGradePipelineState(document, path, pipelineState);
1159
- return matchesParsedGradeTargetFilters(document, path, filters, isIncompleteGradePipelineState(currentState));
1160
- }
1161
- // grade の対象は grade_targets と文書の種類(document_kinds)だけで決まる。
1162
- function gradedViewpoints(doc, target, metadata) {
1163
- return (doc.viewpoints ?? []).filter((viewpoint) => (viewpoint.grade_targets === undefined || viewpoint.grade_targets.includes(target)) &&
1164
- viewpointAppliesToDocument(viewpoint, metadata));
1165
- }
1166
- function agentViewpoints(doc, target, metadata) {
1167
- return gradedViewpoints(doc, target, metadata).filter((viewpoint) => viewpoint.evaluation === "referential" || viewpoint.evaluation === "discretionary");
1168
- }
1169
- function deterministicResults(document, definitions, target) {
1170
- const results = [];
1171
- const metadata = document.data.specdojo;
1172
- for (const viewpoint of gradedViewpoints(definitions, target, metadata).filter((item) => item.evaluation === "deterministic")) {
1173
- const findings = [];
1174
- const specdojo = document.data.specdojo;
1175
- if (viewpoint.id === "vp-arc-document-structure") {
1176
- for (const key of ["id", "type", "status"]) {
1177
- if (typeof specdojo[key] !== "string" || !String(specdojo[key]).trim()) {
1178
- findings.push({
1179
- severity: "major",
1180
- message: `Frontmatter の specdojo.${key} が未設定です。`,
1181
- line: 1,
1182
- });
1183
- }
1184
- }
1185
- if (!/^#\s+\S/m.test(document.body)) {
1186
- findings.push({ severity: "major", message: "本文に H1 見出しがありません。", line: 1 });
1187
- }
1188
- }
1189
- if (viewpoint.id === "vp-qe-config-validity") {
1190
- const placeholderLine = document.body
1191
- .split("\n")
1192
- .findIndex((line) => /(?:_TODO_|_ASSUMPTION_)/.test(line));
1193
- if (placeholderLine >= 0) {
1194
- findings.push({
1195
- severity: "major",
1196
- message: "未解決の _TODO_ / _ASSUMPTION_ が残っています。",
1197
- line: placeholderLine + 1,
1198
- });
1199
- }
1200
- }
1201
- const cap = levelCapForFindings(findings);
1202
- results.push({ id: viewpoint.id, level: cap, findings });
1203
- }
1204
- return results;
1205
- }
1206
- function doneCriteriaPlanLines(doneCriteria, definitions) {
1207
- const titles = new Map((definitions.viewpoints ?? []).map((viewpoint) => [viewpoint.id, viewpoint.title]));
1208
- return [
1209
- "### 3.4. 完了条件(done_criteria)",
1210
- "",
1211
- "成果物カタログが対象へ宣言する完了条件である。viewpoint と rubric による level 判定とは別の軸として、各条件を現在の本文の根拠だけで `satisfied` / `unsatisfied` のどちらかに判定する。score や level の高低から充足を推論せず、条件文が要求する内容を本文で確認できるかだけで判定する。`roles` は条件の確認責任を持つ Role code、`viewpoint` は条件を見る観点であり、`evaluation: discretionary` の観点に紐づく条件も本文の根拠で一次判定する。",
1212
- "",
1213
- ...doneCriteria.map((criterion) => {
1214
- const title = titles.get(criterion.viewpoint);
1215
- const viewpoint = title ? `${criterion.viewpoint}(${title})` : criterion.viewpoint;
1216
- return `- ${criterion.id} [roles=${criterion.roles.join(",")}; viewpoint=${viewpoint}]: ${criterion.text}`;
1217
- }),
1218
- "",
1219
- ];
1220
- }
1221
- function applicableDoneCriteria(doneCriteria, definitions, metadata) {
1222
- const viewpoints = new Map((definitions.viewpoints ?? []).map((viewpoint) => [viewpoint.id, viewpoint]));
1223
- return doneCriteria.filter((criterion) => {
1224
- const viewpoint = viewpoints.get(criterion.viewpoint);
1225
- return viewpoint === undefined || viewpointAppliesToDocument(viewpoint, metadata);
1226
- });
1227
- }
1228
- function markdownFence(content) {
1229
- let longestRun = 0;
1230
- for (const match of content.matchAll(/`+/g))
1231
- longestRun = Math.max(longestRun, match[0].length);
1232
- return "`".repeat(Math.max(3, longestRun + 1));
1233
- }
1234
- function splitDocumentForEmbedding(content) {
1235
- const normalized = content.replace(/\r\n?/g, "\n");
1236
- const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
1237
- if (!match)
1238
- return { body: normalized.replace(/\n$/, "") };
1239
- return {
1240
- frontmatter: match[1],
1241
- body: (match[2] ?? "").replace(/^\n+/, "").replace(/\n$/, ""),
1242
- };
1243
- }
1244
- function renderEmbeddedGradeDocument(path, roles) {
1245
- const content = readFileSync(resolveSafeRepositoryPath(path, "embedded document"), "utf8");
1246
- const { frontmatter, body } = splitDocumentForEmbedding(content);
1247
- const bodyLines = body === "" ? [] : body.split("\n");
1248
- const numberedBody = bodyLines.map((line, index) => `${index + 1} | ${line}`).join("\n");
1249
- const lines = [
1250
- `#### ${roles.join("・")}: \`${path}\``,
1251
- "",
1252
- "Frontmatter(`finding.line` の行番号対象外):",
1253
- "",
1254
- ];
1255
- if (frontmatter === undefined) {
1256
- lines.push("- なし", "");
1257
- }
1258
- else {
1259
- const fence = markdownFence(frontmatter);
1260
- lines.push(`${fence}yaml`, frontmatter, fence, "");
1261
- }
1262
- const bodyFence = markdownFence(numberedBody);
1263
- lines.push("本文(左端は `finding.line` と同じ、Frontmatter を除く1始まりの行番号):", "", `${bodyFence}text`, numberedBody, bodyFence, "");
1264
- return lines;
1265
- }
1266
- function gradePlanEmbedding(opts) {
1267
- if (!Number.isSafeInteger(opts.limit) || opts.limit < 1) {
1268
- throw new Error("maxEmbeddedDocumentCharacters must be a positive integer");
1269
- }
1270
- if (!opts.requested) {
1271
- return { requested: false, embedded: false, characterCount: 0, limit: opts.limit, lines: [] };
1272
- }
1273
- const rolesByPath = new Map();
1274
- const add = (path, role) => {
1275
- const roles = rolesByPath.get(path);
1276
- if (roles) {
1277
- if (!roles.includes(role))
1278
- roles.push(role);
1279
- }
1280
- else {
1281
- rolesByPath.set(path, [role]);
1282
- }
1283
- };
1284
- add(opts.targetPath, "評価対象");
1285
- for (const reference of opts.references)
1286
- add(reference, "参考資料");
1287
- if (opts.referenceExample)
1288
- add(opts.referenceExample, "良い実例");
1289
- const lines = [...rolesByPath].flatMap(([path, roles]) => renderEmbeddedGradeDocument(path, roles));
1290
- const characterCount = lines.join("\n").length;
1291
- return {
1292
- requested: true,
1293
- embedded: characterCount <= opts.limit,
1294
- characterCount,
1295
- limit: opts.limit,
1296
- lines: characterCount <= opts.limit ? lines : [],
1297
- };
1298
- }
1299
- function renderGradePlanWithEmbedding(opts) {
1300
- const rubric = assertRubric(opts.viewpoints);
1301
- const absolute = resolveSafeMarkdownPath(opts.path);
1302
- const rel = repoRelativePath(absolute);
1303
- const document = parseMarkdown(readFileSync(absolute, "utf8"), rel);
1304
- const metadata = document.data.specdojo;
1305
- const viewpoints = agentViewpoints(opts.viewpoints, opts.target, metadata);
1306
- const documentId = typeof metadata.id === "string" ? metadata.id : rel;
1307
- const priorFindings = (opts.resultsDirectory
1308
- ? readGradeResult(gradeResultPath(opts.resultsDirectory, documentId))
1309
- : readGradeResultForDocument({ documentPath: rel, project: opts.projectId }))?.findings ?? [];
1310
- const taskHash = createHash("sha256").update(rel).digest("hex").slice(0, 12).toUpperCase();
1311
- const taskId = `GRADE-${opts.target.toUpperCase()}-${taskHash}`;
1312
- const references = (opts.references ?? []).map((reference) => repoRelativePath(resolveSafeRepositoryPath(reference, "reference")));
1313
- const referenceExample = opts.referenceExample
1314
- ? repoRelativePath(resolveSafeMarkdownPath(opts.referenceExample))
1315
- : undefined;
1316
- const embedding = gradePlanEmbedding({
1317
- requested: opts.embedDocuments ?? false,
1318
- targetPath: rel,
1319
- references,
1320
- referenceExample,
1321
- limit: opts.maxEmbeddedDocumentCharacters ?? GRADE_PLAN_EMBEDDED_DOCUMENT_CHARACTER_LIMIT,
1322
- });
1323
- const doneCriteria = opts.target === "deliverable"
1324
- ? applicableDoneCriteria(opts.doneCriteria ?? [], opts.viewpoints, metadata)
1325
- : [];
1326
- const lines = [
1327
- "---",
1328
- yaml
1329
- .dump({
1330
- specdojo: {
1331
- id: `${opts.projectId}:grade-${opts.target}-${taskHash.toLowerCase()}-plan`,
1332
- type: "exec-plan",
1333
- rulebook: "none",
1334
- task_id: taskId,
1335
- name: `grade: ${rel}`,
1336
- mode: "review",
1337
- status: "ready",
1338
- project_id: opts.projectId,
1339
- targets: [documentId],
1340
- },
1341
- }, { lineWidth: 120, noRefs: true })
1342
- .trimEnd(),
1343
- "---",
1344
- "",
1345
- `# Review Plan: ${taskId} grade: ${rel}`,
1346
- "",
1347
- "この plan は grade pipeline の executor stage 用である。評価と根拠の記述だけを行い、GradeSubmission JSON は作成しない。`grade apply` が最終応答の marker を機械的に解析して GradeSubmission を生成し、契約を満たさない応答は拒否して executor を再実行する。",
1348
- "",
1349
- "## 1. このタスクで行うこと",
1350
- "",
1351
- `評価対象 \`${rel}\` を共通 viewpoint と category rubric で 0-4 判定する。deterministic viewpoint は CLI が判定するため、agent の出力には含めない。`,
1352
- "",
1353
- "## 2. 対象項目",
1354
- "",
1355
- `- \`target\`: ${opts.target}`,
1356
- `- \`rubric\`: ${rubric.id}`,
1357
- `- \`document_id\`: ${documentId}`,
1358
- `- \`評価対象\`: \`${rel}\``,
1359
- "",
1360
- "### 参考資料",
1361
- "",
1362
- "参考資料は評価対象ではなく、成果物間整合を判定するための材料である。参考資料自体を評価しない。",
1363
- "",
1364
- ...(references.length > 0 ? references.map((reference) => `- \`${reference}\``) : ["- なし"]),
1365
- "",
1366
- // 比較リファレンスは任意である。指定がない場合は節ごと省略する。空の節を残すと
1367
- // 候補が存在しないのか指定していないのかを読み手が区別できない。
1368
- ...(referenceExample
1369
- ? [
1370
- "### 良い実例(比較リファレンス)",
1371
- "",
1372
- "`status: ready` の文書から選んだ比較材料である。記載水準を具体化するために使い、評価対象へ含めず、内容を正解として機械的に模倣しない。`ready` は品質保証ではないため、実例自体の問題を評価対象へ転用しない。",
1373
- "",
1374
- `- \`${referenceExample}\``,
1375
- "",
1376
- ]
1377
- : []),
1378
- ...(embedding.embedded
1379
- ? [
1380
- "### 埋め込み資料",
1381
- "",
1382
- `評価対象・参考資料・良い実例を plan 生成時点の内容で埋め込む。埋め込み部分は ${embedding.characterCount.toLocaleString("en-US")} 文字(上限 ${embedding.limit.toLocaleString("en-US")} 文字)である。`,
1383
- "",
1384
- ...embedding.lines,
1385
- ]
1386
- : embedding.requested
1387
- ? [
1388
- "### 埋め込み資料",
1389
- "",
1390
- `警告: 埋め込み部分が ${embedding.characterCount.toLocaleString("en-US")} 文字となり、上限 ${embedding.limit.toLocaleString("en-US")} 文字を超えたため、本文を埋め込まずパス参照へフォールバックした。`,
1391
- "",
1392
- ]
1393
- : []),
1394
- "## 3. 進め方",
1395
- "",
1396
- ...(embedding.embedded
1397
- ? [
1398
- "1. plan の「埋め込み資料」にある評価対象の本文を全文読む。Frontmatter は行番号の対象外であり、本文左端の番号を finding の `line` に使う。",
1399
- "2. 埋め込まれた参考資料と良い実例がある場合はすべて読む。ファイル読み取りツールと検索ツールを使わず、plan に埋め込まれた資料だけで判定し、参考資料や良い実例を評価対象と混同しない。",
1400
- ]
1401
- : [
1402
- "1. 評価対象をファイル読み取りツールで全文読み、実行ログに読み取り操作を残す。plan に対象本文は埋め込まれていないため、この手順を省略しない。",
1403
- "2. 参考資料と良い実例がある場合は列挙された全ファイルを全文読み、実行ログに各パスの読み取り操作を残す。参考資料や良い実例を評価対象と混同しない。",
1404
- ]),
1405
- "3. 良い実例がある場合は、章ごとの具体性、根拠の密度、過不足を評価対象と比較して記載水準を判定する。表現の類似や実例自体の欠点を評価理由にせず、rubric と viewpoint を最終的な判定基準にする。",
1406
- "4. 評価対象を次の rubric と viewpoint に照らし、各 viewpoint を 0-4 で判定する。ある viewpoint の finding の有無から、ほかの viewpoint の判定を推論しない。",
1407
- "5. 判定根拠と新しい finding の message は英語で記述する。固有名詞・識別子・引用は原文を保ってよい。日本語だけの既存 finding は互換用の正本として扱い、未解消ならその message を翻訳せず原文のまま再掲する。",
1408
- "6. level 3 以下には finding を付ける。finding には severity(blocker / major / minor / note)、対象直前の本文行番号、具体的な修正理由を含める。line は Frontmatter を除く本文の1始まり(通常は H1 が1行目)とする。level 4 は finding なしとする。",
1409
- "7. 前回の指摘を対象の現在内容と照合し、解消済みか確認する。未解消なら前回の canonical message を変更せず今回の finding に含め、severity は前回と同等以上を指定する。前回の rule は前回評価時の分類として扱い、各 viewpoint は現在の根拠から独立に評価する。前回の問題が解消され、別の軽微な問題だけが残るため severity を引き下げる場合は、その根拠を新しい finding の message に含める。",
1410
- "8. 前回の指摘の確認だけで終了せず、前回の指摘にない問題もすべての viewpoint で独立して検出する。",
1411
- ...(doneCriteria.length > 0
1412
- ? [
1413
- "9. 完了条件(done_criteria)を1件ずつ本文の根拠と照合し、`satisfied` / `unsatisfied` を判定する。viewpoint の level や総合 score とは独立した判定であり、level が高いことを理由に条件を満たしたとみなさない。`unsatisfied` には不足している内容を英語で1行に記す。",
1414
- ]
1415
- : []),
1416
- "",
1417
- "### 3.1. 前回の指摘",
1418
- "",
1419
- "grade result サイドカーに記録された前回の finding を示す。対象本文には評価コメントを書き込まない。",
1420
- "",
1421
- // 前回の id は今回の採番と混同させないため渡さない。事実(severity / rule / 位置 / message)だけを示す。
1422
- ...(priorFindings.length > 0
1423
- ? [
1424
- "```json",
1425
- JSON.stringify(priorFindings.map(({ severity, rule, line, anchor, message }) => ({
1426
- severity,
1427
- rule,
1428
- line,
1429
- anchor,
1430
- message,
1431
- })), null, 2),
1432
- "```",
1433
- ]
1434
- : ["- なし"]),
1435
- "",
1436
- "### 3.2. Rubric",
1437
- "",
1438
- ...rubric.levels.map((level) => `- ${level.level} (${level.name}, review=${level.review_verdict}): ${level.description}`),
1439
- "",
1440
- "### 3.3. Viewpoints",
1441
- "",
1442
- ...viewpoints.map((viewpoint) => `- ${viewpoint.id} [${viewpoint.category}/${viewpoint.evaluation}]: ${viewpoint.check} Evidence: ${viewpoint.evidence}`),
1443
- "",
1444
- ...(doneCriteria.length > 0 ? doneCriteriaPlanLines(doneCriteria, opts.viewpoints) : []),
1445
- "## 4. 完了手順",
1446
- "",
1447
- "1. すべての agent viewpoint の判定と、必要な finding が揃っていることを確認する。",
1448
- "2. 最終応答では各 viewpoint を次のマーカーで1回ずつ宣言する。マーカー間には根拠や検討過程を自由形式で詳しく記述してよい。JSON、Markdown コードフェンス、GradeSubmission は出力しない。",
1449
- "3. `LEVEL` と各 `FINDING` は `grade apply` が機械的に読み取る申告値である。marker・`LEVEL`・`FINDING` はそれぞれ行頭に1行で記し、message は英語で1行に具体的に記す。message は正本としてそのまま記録される。finding がない場合は `FINDING` 行を記さない。",
1450
- "4. すべての viewpoint marker、0-4 の level、level 3 以下の finding、severity と非空 message が揃っていることを確認する。",
1451
- ...(doneCriteria.length > 0
1452
- ? [
1453
- "5. 完了条件は `[DONE_CRITERIA]` と `[END DONE_CRITERIA]` で囲んだブロックを1回だけ置き、列挙されたすべての条件 ID を1行ずつ `<ID>: satisfied` または `<ID>: unsatisfied: <不足内容>` の形で申告する。列挙にない ID を追加せず、ID を省略しない。",
1454
- ]
1455
- : []),
1456
- "",
1457
- "```text",
1458
- ...viewpoints.flatMap((viewpoint) => [
1459
- `[VIEWPOINT ${viewpoint.id}]`,
1460
- "LEVEL: <0-4>",
1461
- "根拠を自由形式で記述する。",
1462
- "FINDING <severity> line=<line>: level 3 以下の場合だけ、具体的な修正理由を1行で記述する。",
1463
- "[END VIEWPOINT]",
1464
- "",
1465
- ]),
1466
- ...(doneCriteria.length > 0
1467
- ? [
1468
- "[DONE_CRITERIA]",
1469
- ...doneCriteria.map((criterion) => `${criterion.id}: <satisfied|unsatisfied>: 不足内容を1行で記述する。`),
1470
- "[END DONE_CRITERIA]",
1471
- "",
1472
- ]
1473
- : []),
1474
- "```",
1475
- "",
1476
- "## 5. 異常終了の条件",
1477
- "",
1478
- ...(embedding.embedded
1479
- ? [
1480
- "- plan に評価対象、参考資料、または良い実例の埋め込み内容が欠けている場合は、内容を推測せず異常終了する。",
1481
- ]
1482
- : ["- 評価対象、参考資料、または良い実例を読み取れない場合は、内容を推測せず異常終了する。"]),
1483
- "- rubric または viewpoint に不足があり、全項目を判定できない場合は異常終了する。",
1484
- "- すべての viewpoint の level と finding を申告できない場合は異常終了する。",
1485
- ...(doneCriteria.length > 0
1486
- ? ["- 列挙された完了条件のいずれかを判定できない場合は異常終了する。"]
1487
- : []),
1488
- ];
1489
- return { content: `${lines.join("\n")}\n`, embedding };
1490
- }
1491
- export function renderGradePlan(opts) {
1492
- return renderGradePlanWithEmbedding(opts).content;
1493
- }
1494
- export function renderGradeReporterPlan(opts) {
1495
- const rubric = assertRubric(opts.viewpoints);
1496
- const absolute = resolveSafeMarkdownPath(opts.path);
1497
- const rel = repoRelativePath(absolute);
1498
- const document = parseMarkdown(readFileSync(absolute, "utf8"), rel);
1499
- const metadata = document.data.specdojo;
1500
- const viewpoints = agentViewpoints(opts.viewpoints, opts.target, metadata);
1501
- const documentId = typeof metadata.id === "string" ? metadata.id : rel;
1502
- const taskHash = createHash("sha256").update(rel).digest("hex").slice(0, 12).toUpperCase();
1503
- const taskId = `GRADE-${opts.target.toUpperCase()}-${taskHash}-REPORTER`;
1504
- const doneCriteria = opts.target === "deliverable"
1505
- ? applicableDoneCriteria(opts.doneCriteria ?? [], opts.viewpoints, metadata)
1506
- : [];
1507
- const lines = [
1508
- "---",
1509
- yaml
1510
- .dump({
1511
- specdojo: {
1512
- id: `${opts.projectId}:grade-${opts.target}-${taskHash.toLowerCase()}-reporter-plan`,
1513
- type: "exec-plan",
1514
- rulebook: "none",
1515
- task_id: taskId,
1516
- name: `grade reporter: ${rel}`,
1517
- mode: "review",
1518
- status: "ready",
1519
- project_id: opts.projectId,
1520
- targets: [documentId],
1521
- },
1522
- }, { lineWidth: 120, noRefs: true })
1523
- .trimEnd(),
1524
- "---",
1525
- "",
1526
- `# Reporter Plan: ${taskId} grade: ${rel}`,
1527
- "",
1528
- "この plan は grade pipeline の reporter stage 用である。既定の pipeline は reporter を起動せず、`grade apply` が executor の marker から GradeSubmission を機械的に生成する。この plan は LLM reporter を明示指定して書き写しの精度を比較・検証する場合にだけ使う。executor の最終応答が `<grade_executor_output>` としてこの plan と一緒に渡される。評価やファイル読み取りは行わず、申告済みの判定を GradeSubmission JSON へ忠実に構造化する。",
1529
- "",
1530
- "## 1. このタスクで行うこと",
1531
- "",
1532
- "executor が申告した全 viewpoint の level と finding を、追加・省略・変更せず GradeSubmission JSON へ写す。",
1533
- "",
1534
- "## 2. 対象項目",
1535
- "",
1536
- `- \`target\`: ${opts.target}`,
1537
- `- \`rubric\`: ${rubric.id}`,
1538
- `- \`document_id\`: ${documentId}`,
1539
- `- \`評価対象\`: \`${rel}\``,
1540
- "",
1541
- "## 3. 進め方",
1542
- "",
1543
- "1. `<grade_executor_output>` の `[VIEWPOINT <id>]` ごとに `LEVEL` とすべての `FINDING` を読み取る。対象文書や参考資料は読まない。",
1544
- "2. level、severity、line、message を executor の申告どおりにコピーする。message の要約、言い換え、校正を行わない。",
1545
- "3. executor が述べていない finding を追加せず、述べた finding を省略しない。finding の `id` は出力しない。",
1546
- "4. finding の severity により viewpoint の level に上限がある(`blocker` は上限 0、`major` は上限 2、`minor` は上限 3)。executor の申告が上限を超えていても level は申告どおりにコピーし、補正は `grade apply` に委ねる。marker 欠落など、それ以外の GradeSubmission 契約違反は推測で補わず異常終了する。",
1547
- ...(doneCriteria.length > 0
1548
- ? [
1549
- "5. `[DONE_CRITERIA]` ブロックの各行を `done_criteria` へ写す。`id` と `status`(`satisfied` / `unsatisfied`)は申告どおりにコピーし、`unsatisfied` に続く不足内容は `reason` へ一字一句コピーする。条件の追加・省略・判定変更を行わない。",
1550
- ]
1551
- : []),
1552
- "",
1553
- "## 4. 完了手順",
1554
- "",
1555
- "1. facts である `rubric` と `path` を次のテンプレートから変更しない。",
1556
- "2. すべての agent viewpoint が1回ずつあり、level と finding が executor の申告と一致することを確認する。",
1557
- ...(doneCriteria.length > 0
1558
- ? [
1559
- "3. `done_criteria` の各要素が executor の申告した ID と status に一致することを確認する。",
1560
- "4. 正常終了時の最終応答は GradeSubmission JSON オブジェクト1個だけとする。前置き、要約、Markdown コードフェンスを含めない。",
1561
- ]
1562
- : [
1563
- "3. 正常終了時の最終応答は GradeSubmission JSON オブジェクト1個だけとする。前置き、要約、Markdown コードフェンスを含めない。",
1564
- ]),
1565
- "",
1566
- "```json",
1567
- JSON.stringify({
1568
- rubric: rubric.id,
1569
- documents: [
1570
- {
1571
- path: rel,
1572
- viewpoints: viewpoints.map((viewpoint) => ({
1573
- id: viewpoint.id,
1574
- level: 4,
1575
- findings: [],
1576
- })),
1577
- ...(doneCriteria.length > 0
1578
- ? {
1579
- done_criteria: doneCriteria.map((criterion) => ({
1580
- id: criterion.id,
1581
- status: "satisfied",
1582
- })),
1583
- }
1584
- : {}),
1585
- },
1586
- ],
1587
- }, null, 2),
1588
- "```",
1589
- "",
1590
- "## 5. 異常終了の条件",
1591
- "",
1592
- "- `<grade_executor_output>` が渡されていない、または marker 契約を解析できない場合は異常終了する。",
1593
- "- level の下方向補正を除き、executor の申告を変更しなければ GradeSubmission の契約を満たせない場合は異常終了する。",
1594
- ];
1595
- return `${lines.join("\n")}\n`;
1596
- }
1597
- function gradePlanFilename(path) {
1598
- const rel = repoRelativePath(path);
1599
- const stem = basename(path, extname(path))
1600
- .toLowerCase()
1601
- .replace(/[^a-z0-9-]+/g, "-")
1602
- .replace(/^-+|-+$/g, "");
1603
- const hash = createHash("sha256").update(rel).digest("hex").slice(0, 10);
1604
- return `${stem || "document"}-${hash}-grade-plan.md`;
1605
- }
1606
- function gradeReporterPlanFilename(path) {
1607
- return gradePlanFilename(path).replace(/-grade-plan\.md$/, "-grade-reporter-plan.md");
1608
- }
1609
- export function writeGradePlans(opts) {
1610
- const outputDirectory = resolveSafeRepositoryPath(opts.outputDirectory, "--out");
1611
- if (opts.paths.length === 0)
1612
- return [];
1613
- mkdirSync(outputDirectory, { recursive: true });
1614
- const kataReferences = loadKataReferences();
1615
- const referenceExamples = opts.referenceExampleCandidates.flatMap((candidate) => {
1616
- const parsed = parseGradeReferenceExample(candidate, opts.target);
1617
- return parsed ? [parsed] : [];
1618
- });
1619
- return opts.paths.map((path) => {
1620
- const absolute = resolveSafeMarkdownPath(path);
1621
- const output = join(outputDirectory, gradePlanFilename(absolute));
1622
- const reporterOutput = join(outputDirectory, gradeReporterPlanFilename(absolute));
1623
- const referenceExample = opts.referenceExampleOverride ??
1624
- selectGradeReferenceExampleFromCatalog({
1625
- target: opts.target,
1626
- path: absolute,
1627
- candidates: referenceExamples,
1628
- random: opts.random,
1629
- });
1630
- const doneCriteria = opts.doneCriteriaByPath?.get(repoRelativePath(absolute));
1631
- const rendered = renderGradePlanWithEmbedding({
1632
- target: opts.target,
1633
- path: absolute,
1634
- references: resolveGradeReferencePathsFromCatalog(absolute, kataReferences),
1635
- referenceExample,
1636
- viewpoints: opts.viewpoints,
1637
- projectId: opts.projectId,
1638
- doneCriteria,
1639
- embedDocuments: opts.embedDocuments,
1640
- });
1641
- const content = rendered.content;
1642
- const reporterContent = renderGradeReporterPlan({
1643
- target: opts.target,
1644
- path: absolute,
1645
- viewpoints: opts.viewpoints,
1646
- projectId: opts.projectId,
1647
- doneCriteria,
1648
- });
1649
- const changed = !existsSync(output) || readFileSync(output, "utf8") !== content;
1650
- const reporterChanged = !existsSync(reporterOutput) || readFileSync(reporterOutput, "utf8") !== reporterContent;
1651
- if (changed)
1652
- writeFileSync(output, content, "utf8");
1653
- if (reporterChanged)
1654
- writeFileSync(reporterOutput, reporterContent, "utf8");
1655
- return {
1656
- path: repoRelativePath(output),
1657
- changed,
1658
- reporterPath: repoRelativePath(reporterOutput),
1659
- reporterChanged,
1660
- target: repoRelativePath(absolute),
1661
- referenceExample,
1662
- documentsEmbedded: rendered.embedding.embedded,
1663
- embeddingCharacterCount: rendered.embedding.characterCount,
1664
- embeddingCharacterLimit: rendered.embedding.limit,
1665
- };
1666
- });
1667
- }
1668
- // executor の最終応答に現れる marker 行の軽微な書式の揺れを正規化する。受理するのは、行頭の
1669
- // 空白、ブロッククオート `>`、リスト記号(`-` / `*` / `+` と空白)、および marker・LEVEL・
1670
- // FINDING・DC-NNN の見出し部分を囲む `**` だけである。message と reason の本文は変更しない。
1671
- // 文中に埋もれた FINDING などは marker とみなさず、従来どおり無視または拒否する。
1672
- export function normalizeGradeExecutorLine(line) {
1673
- let normalized = line.replace(/^\s*(?:>\s*)*(?:[-*+]\s+)?/, "");
1674
- const wrappedMarker = normalized.match(/^\*\*(\[(?:END )?(?:VIEWPOINT[^\]]*|DONE_CRITERIA)\])\*\*\s*$/);
1675
- if (wrappedMarker)
1676
- return wrappedMarker[1];
1677
- const wrappedLevel = normalized.match(/^\*\*(LEVEL:\s*[0-4])\*\*\s*$/);
1678
- if (wrappedLevel)
1679
- return wrappedLevel[1];
1680
- normalized = normalized.replace(/^\*\*(LEVEL|FINDING(?:\s+[a-z]+)?(?:\s+line=[0-9]+)?|DC-[0-9]{3,})(:?)\*\*(:?)/, (_match, head, innerColon, outerColon) => `${head}${innerColon}${outerColon}`);
1681
- return normalized;
1682
- }
1683
- export function parseGradeExecutorAnalysis(raw) {
1684
- const viewpoints = [];
1685
- let doneCriteria;
1686
- let inDoneCriteria = false;
1687
- let current;
1688
- for (const [lineIndex, rawLine] of raw.split(/\r?\n/).entries()) {
1689
- const line = normalizeGradeExecutorLine(rawLine);
1690
- if (/^\[DONE_CRITERIA\]\s*$/.test(line)) {
1691
- if (current)
1692
- throw new Error(`line ${lineIndex + 1}: DONE_CRITERIA inside VIEWPOINT`);
1693
- if (doneCriteria !== undefined) {
1694
- throw new Error(`line ${lineIndex + 1}: duplicate DONE_CRITERIA block`);
1695
- }
1696
- doneCriteria = [];
1697
- inDoneCriteria = true;
1698
- continue;
1699
- }
1700
- if (/^\[END DONE_CRITERIA\]\s*$/.test(line)) {
1701
- if (!inDoneCriteria) {
1702
- throw new Error(`line ${lineIndex + 1}: unexpected END DONE_CRITERIA marker`);
1703
- }
1704
- inDoneCriteria = false;
1705
- continue;
1706
- }
1707
- if (inDoneCriteria) {
1708
- if (line.trim() === "")
1709
- continue;
1710
- const criterion = line.match(/^(DC-[0-9]{3,}):\s*(satisfied|unsatisfied)(?:\s*[::]\s*(\S.*?))?\s*$/);
1711
- if (!criterion) {
1712
- throw new Error(`line ${lineIndex + 1}: malformed DONE_CRITERIA entry`);
1713
- }
1714
- doneCriteria.push({
1715
- id: criterion[1],
1716
- status: criterion[2],
1717
- ...(criterion[3] ? { reason: criterion[3].trim() } : {}),
1718
- });
1719
- continue;
1720
- }
1721
- const start = line.match(/^\[VIEWPOINT ([A-Za-z0-9][A-Za-z0-9._-]*)\]\s*$/);
1722
- if (start) {
1723
- if (current) {
1724
- throw new Error(`line ${lineIndex + 1}: nested VIEWPOINT marker`);
1725
- }
1726
- current = { id: start[1], findings: [] };
1727
- continue;
1728
- }
1729
- if (/^\[END VIEWPOINT\]\s*$/.test(line)) {
1730
- if (!current)
1731
- throw new Error(`line ${lineIndex + 1}: unexpected END VIEWPOINT marker`);
1732
- if (current.level === undefined) {
1733
- throw new Error(`viewpoint ${current.id}: LEVEL is required`);
1734
- }
1735
- viewpoints.push({ id: current.id, level: current.level, findings: current.findings });
1736
- current = undefined;
1737
- continue;
1738
- }
1739
- if (!current)
1740
- continue;
1741
- const level = line.match(/^LEVEL:\s*([0-4])\s*$/);
1742
- if (level) {
1743
- if (current.level !== undefined) {
1744
- throw new Error(`line ${lineIndex + 1}: duplicate LEVEL for ${current.id}`);
1745
- }
1746
- current.level = Number(level[1]);
1747
- continue;
1748
- }
1749
- if (/^LEVEL\s*:/.test(line)) {
1750
- throw new Error(`line ${lineIndex + 1}: malformed LEVEL for ${current.id}`);
1751
- }
1752
- const finding = line.match(/^FINDING\s+(blocker|major|minor|note)(?:\s+line=([1-9][0-9]*))?:\s*(\S.*)\s*$/);
1753
- if (finding) {
1754
- current.findings.push({
1755
- severity: finding[1],
1756
- ...(finding[2] ? { line: Number(finding[2]) } : {}),
1757
- message: finding[3].trim(),
1758
- });
1759
- continue;
1760
- }
1761
- if (/^FINDING(?:\s|:)/.test(line)) {
1762
- throw new Error(`line ${lineIndex + 1}: malformed FINDING for ${current.id}`);
1763
- }
1764
- }
1765
- if (current)
1766
- throw new Error(`viewpoint ${current.id}: END VIEWPOINT marker is required`);
1767
- if (inDoneCriteria)
1768
- throw new Error("END DONE_CRITERIA marker is required");
1769
- if (viewpoints.length === 0)
1770
- throw new Error("No VIEWPOINT markers found in executor analysis");
1771
- return { viewpoints, ...(doneCriteria !== undefined ? { doneCriteria } : {}) };
1772
- }
1773
- function normalizeFindingMessageForFidelity(message) {
1774
- return message
1775
- .normalize("NFC")
1776
- .replace(/[、,]/gu, ",")
1777
- .replace(/[。.]/gu, ".")
1778
- .replace(/!/gu, "!")
1779
- .replace(/?/gu, "?")
1780
- .replace(/:/gu, ":")
1781
- .replace(/;/gu, ";")
1782
- .replace(/\s+/gu, " ")
1783
- .trim()
1784
- .replace(/\s*([,.;:!?])\s*/gu, "$1");
1785
- }
1786
- function findingFidelityKey(finding) {
1787
- return JSON.stringify({
1788
- severity: finding.severity,
1789
- line: finding.line ?? null,
1790
- message: normalizeFindingMessageForFidelity(finding.message),
1791
- });
1792
- }
1793
- function unmatchedFindings(declared, reported) {
1794
- const remainingReported = reported.map((finding) => ({
1795
- finding,
1796
- matched: false,
1797
- }));
1798
- const unmatchedDeclared = [];
1799
- for (const finding of declared) {
1800
- const key = findingFidelityKey(finding);
1801
- const match = remainingReported.find((candidate) => !candidate.matched && findingFidelityKey(candidate.finding) === key);
1802
- if (match)
1803
- match.matched = true;
1804
- else
1805
- unmatchedDeclared.push(finding);
1806
- }
1807
- return {
1808
- declared: unmatchedDeclared,
1809
- reported: remainingReported
1810
- .filter((candidate) => !candidate.matched)
1811
- .map((candidate) => candidate.finding),
1812
- };
1813
- }
1814
- function findingDifferenceMessage(declared, reported) {
1815
- const differences = [];
1816
- if (declared.severity !== reported.severity) {
1817
- differences.push(`severity executor=${declared.severity} reporter=${reported.severity}`);
1818
- }
1819
- if (declared.line !== reported.line) {
1820
- differences.push(`line executor=${declared.line ?? "none"} reporter=${reported.line ?? "none"}`);
1821
- }
1822
- if (normalizeFindingMessageForFidelity(declared.message) !==
1823
- normalizeFindingMessageForFidelity(reported.message)) {
1824
- differences.push(`message executor=${JSON.stringify(declared.message)} reporter=${JSON.stringify(reported.message)}`);
1825
- }
1826
- return differences.join("; ");
1827
- }
1828
- function findingSimilarity(declared, reported) {
1829
- return (Number(declared.severity === reported.severity) +
1830
- Number(declared.line === reported.line) +
1831
- Number(normalizeFindingMessageForFidelity(declared.message) ===
1832
- normalizeFindingMessageForFidelity(reported.message)));
1833
- }
1834
- function doneCriteriaFidelityIssues(declared, reported) {
1835
- const issues = [];
1836
- const where = "documents[0].done_criteria";
1837
- if (declared === undefined && reported === undefined)
1838
- return issues;
1839
- if (declared === undefined) {
1840
- issues.push({ path: where, message: "reporter added done_criteria not declared by executor" });
1841
- return issues;
1842
- }
1843
- const reportedById = new Map((reported ?? []).map((criterion) => [criterion.id, criterion]));
1844
- for (const criterion of declared) {
1845
- const match = reportedById.get(criterion.id);
1846
- if (!match) {
1847
- issues.push({ path: where, message: `reporter omitted executor criterion: ${criterion.id}` });
1848
- continue;
1849
- }
1850
- reportedById.delete(criterion.id);
1851
- if (match.status !== criterion.status) {
1852
- issues.push({
1853
- path: `${where}.${criterion.id}`,
1854
- message: `reporter status ${match.status} differs from executor status ${criterion.status}`,
1855
- });
1856
- }
1857
- if (normalizeFindingMessageForFidelity(criterion.reason ?? "") !==
1858
- normalizeFindingMessageForFidelity(match.reason ?? "")) {
1859
- issues.push({
1860
- path: `${where}.${criterion.id}`,
1861
- message: `reporter changed executor reason: executor=${JSON.stringify(criterion.reason ?? "")} reporter=${JSON.stringify(match.reason ?? "")}`,
1862
- });
1863
- }
1864
- }
1865
- for (const id of reportedById.keys()) {
1866
- issues.push({
1867
- path: where,
1868
- message: `reporter added criterion not declared by executor: ${id}`,
1869
- });
1870
- }
1871
- return issues;
1872
- }
1873
- // executor の marker を parse し、GradeSubmission へ機械的に変換したうえで既存の
1874
- // GradeSubmission 検証にかける。severity が定める上限より level が高い場合は、判定を甘くしない
1875
- // 方向へ level だけを補正し、補正前後を submission に残す。それ以外の marker 契約違反と
1876
- // done_criteria の過不足は拒否する。
1877
- function convertGradeExecutorOutput(opts) {
1878
- let analysis;
1879
- try {
1880
- analysis = parseGradeExecutorAnalysis(opts.executorOutput);
1881
- }
1882
- catch (error) {
1883
- return {
1884
- issues: [
1885
- {
1886
- path: "$analysis",
1887
- message: error instanceof Error ? error.message : String(error),
1888
- },
1889
- ],
1890
- };
1891
- }
1892
- const rubric = assertRubric(opts.viewpoints);
1893
- const corrected = correctViewpointLevels(analysis.viewpoints);
1894
- const submission = {
1895
- rubric: rubric.id,
1896
- documents: [
1897
- {
1898
- path: opts.expectedPath,
1899
- viewpoints: corrected.viewpoints,
1900
- ...(corrected.corrections.length > 0 ? { level_corrections: corrected.corrections } : {}),
1901
- ...(analysis.doneCriteria ? { done_criteria: analysis.doneCriteria } : {}),
1902
- },
1903
- ],
1904
- };
1905
- const issues = validateGradeSubmission(submission, opts.viewpoints, opts.target, opts.doneCriteria
1906
- ? { doneCriteriaByPath: new Map([[opts.expectedPath, opts.doneCriteria]]) }
1907
- : {}).map((issue) => ({ path: `$analysis.${issue.path}`, message: issue.message }));
1908
- if (issues.length > 0)
1909
- return { issues };
1910
- return { analysis, submission, issues: [] };
1911
- }
1912
- // executor の分析から GradeSubmission を生成する。LLM の reporter を通さずに grade を記録する
1913
- // 既定の経路で使う。拒否時は issues を返し、呼び出し側は executor を再実行する。
1914
- export function buildGradeSubmissionFromAnalysis(opts) {
1915
- const conversion = convertGradeExecutorOutput(opts);
1916
- if (conversion.submission === undefined)
1917
- return { issues: conversion.issues };
1918
- return { submission: conversion.submission, issues: [] };
1919
- }
1920
- export function validateGradeReporterFidelity(opts) {
1921
- const conversion = convertGradeExecutorOutput(opts);
1922
- if (conversion.analysis === undefined)
1923
- return conversion.issues;
1924
- const analysis = conversion.analysis;
1925
- if (opts.submission.documents.length !== 1) {
1926
- return [
1927
- { path: "documents", message: "reporter submission must contain exactly one document" },
1928
- ];
1929
- }
1930
- const document = opts.submission.documents[0];
1931
- if (document.path !== opts.expectedPath) {
1932
- return [
1933
- {
1934
- path: "documents[0].path",
1935
- message: `reporter path must remain ${opts.expectedPath}`,
1936
- },
1937
- ];
1938
- }
1939
- const issues = [];
1940
- const reportedById = new Map(document.viewpoints.map((viewpoint) => [viewpoint.id, viewpoint]));
1941
- for (const declared of analysis.viewpoints) {
1942
- const reported = reportedById.get(declared.id);
1943
- if (!reported) {
1944
- issues.push({
1945
- path: `documents[0].viewpoints`,
1946
- message: `reporter omitted executor viewpoint: ${declared.id}`,
1947
- });
1948
- continue;
1949
- }
1950
- if (reported.level !== declared.level) {
1951
- issues.push({
1952
- path: `documents[0].viewpoints.${declared.id}.level`,
1953
- message: `reporter level ${reported.level} differs from executor level ${declared.level}`,
1954
- });
1955
- }
1956
- const unmatched = unmatchedFindings(declared.findings ?? [], reported.findings ?? []);
1957
- while (unmatched.declared.length > 0 && unmatched.reported.length > 0) {
1958
- const executorFinding = unmatched.declared.shift();
1959
- let bestIndex = 0;
1960
- for (let index = 1; index < unmatched.reported.length; index += 1) {
1961
- if (findingSimilarity(executorFinding, unmatched.reported[index]) >
1962
- findingSimilarity(executorFinding, unmatched.reported[bestIndex])) {
1963
- bestIndex = index;
1964
- }
1965
- }
1966
- const reporterFinding = unmatched.reported.splice(bestIndex, 1)[0];
1967
- issues.push({
1968
- path: `documents[0].viewpoints.${declared.id}.findings`,
1969
- message: `reporter changed executor finding: ${findingDifferenceMessage(executorFinding, reporterFinding)}`,
1970
- });
1971
- }
1972
- for (const finding of unmatched.declared) {
1973
- issues.push({
1974
- path: `documents[0].viewpoints.${declared.id}.findings`,
1975
- message: `reporter omitted executor finding: ${JSON.stringify(finding)}`,
1976
- });
1977
- }
1978
- for (const finding of unmatched.reported) {
1979
- issues.push({
1980
- path: `documents[0].viewpoints.${declared.id}.findings`,
1981
- message: `reporter added finding not declared by executor: ${JSON.stringify(finding)}`,
1982
- });
1983
- }
1984
- }
1985
- issues.push(...doneCriteriaFidelityIssues(analysis.doneCriteria, document.done_criteria));
1986
- return issues;
1987
- }
1988
- export function parseGradeSubmission(raw) {
1989
- let value;
1990
- try {
1991
- value = JSON.parse(extractJsonText(raw));
1992
- }
1993
- catch (error) {
1994
- throw new Error(`Grade submission must be JSON: ${error instanceof Error ? error.message : String(error)}`);
1995
- }
1996
- if (!isRecord(value) ||
1997
- typeof value.rubric !== "string" ||
1998
- (value.graded_by !== undefined && typeof value.graded_by !== "string") ||
1999
- !Array.isArray(value.documents)) {
2000
- throw new Error("Grade submission requires rubric and documents[]");
2001
- }
2002
- return value;
2003
- }
2004
- function validateDoneCriteriaInput(opts) {
2005
- const issues = [];
2006
- const { where, value, expected } = opts;
2007
- if (value === undefined) {
2008
- if (expected && expected.length > 0) {
2009
- issues.push({ path: where, message: "done_criteria[] is required for this deliverable" });
2010
- }
2011
- return issues;
2012
- }
2013
- if (!Array.isArray(value)) {
2014
- issues.push({ path: `${where}.done_criteria`, message: "done_criteria must be an array" });
2015
- return issues;
2016
- }
2017
- if (opts.target !== "deliverable") {
2018
- issues.push({
2019
- path: `${where}.done_criteria`,
2020
- message: "done_criteria is accepted only for deliverable targets",
2021
- });
2022
- return issues;
2023
- }
2024
- const expectedIds = expected ? new Set(expected.map((criterion) => criterion.id)) : undefined;
2025
- const seen = new Set();
2026
- for (const [index, entry] of value.entries()) {
2027
- const entryPath = `${where}.done_criteria[${index}]`;
2028
- if (!isRecord(entry) ||
2029
- typeof entry.id !== "string" ||
2030
- !CRITERION_ID_RE.test(entry.id) ||
2031
- typeof entry.status !== "string" ||
2032
- !CRITERION_STATUSES.includes(entry.status)) {
2033
- issues.push({ path: entryPath, message: "id (DC-NNN) and status are required" });
2034
- continue;
2035
- }
2036
- if (entry.reason !== undefined && typeof entry.reason !== "string") {
2037
- issues.push({ path: `${entryPath}.reason`, message: "reason must be a string" });
2038
- }
2039
- if (entry.status === "unsatisfied" &&
2040
- !(typeof entry.reason === "string" && entry.reason.trim())) {
2041
- issues.push({ path: entryPath, message: "unsatisfied requires a non-empty reason" });
2042
- }
2043
- if (seen.has(entry.id)) {
2044
- issues.push({ path: entryPath, message: `duplicate criterion: ${entry.id}` });
2045
- }
2046
- seen.add(entry.id);
2047
- if (expectedIds && !expectedIds.has(entry.id)) {
2048
- issues.push({ path: entryPath, message: `unknown criterion: ${entry.id}` });
2049
- }
2050
- }
2051
- for (const id of expectedIds ?? []) {
2052
- if (!seen.has(id))
2053
- issues.push({ path: where, message: `missing criterion: ${id}` });
2054
- }
2055
- return issues;
2056
- }
2057
- export function validateGradeSubmission(submission, doc, target, options = {}) {
2058
- const issues = [];
2059
- const rubric = assertRubric(doc);
2060
- if (submission.rubric !== rubric.id)
2061
- issues.push({ path: "$", message: `rubric must be ${rubric.id}` });
2062
- const paths = new Set();
2063
- for (const [documentIndex, document] of submission.documents.entries()) {
2064
- const where = `documents[${documentIndex}]`;
2065
- if (!document || typeof document.path !== "string" || !Array.isArray(document.viewpoints)) {
2066
- issues.push({ path: where, message: "path and viewpoints[] are required" });
2067
- continue;
2068
- }
2069
- if (paths.has(document.path))
2070
- issues.push({ path: where, message: `duplicate path: ${document.path}` });
2071
- paths.add(document.path);
2072
- const absoluteDocumentPath = resolve(specdojoRootDir(), document.path);
2073
- const normalizedDocumentPath = repoRelativePath(absoluteDocumentPath);
2074
- const metadata = existsSync(absoluteDocumentPath)
2075
- ? parseMarkdown(readFileSync(absoluteDocumentPath, "utf8"), normalizedDocumentPath).data
2076
- .specdojo
2077
- : {};
2078
- const required = agentViewpoints(doc, target, metadata);
2079
- const allowed = new Map(required.map((viewpoint) => [viewpoint.id, viewpoint]));
2080
- const expectedDoneCriteria = options.doneCriteriaByPath?.get(document.path) ??
2081
- options.doneCriteriaByPath?.get(normalizedDocumentPath);
2082
- issues.push(...validateDoneCriteriaInput({
2083
- where,
2084
- target,
2085
- value: document.done_criteria,
2086
- expected: expectedDoneCriteria
2087
- ? applicableDoneCriteria(expectedDoneCriteria, doc, metadata)
2088
- : undefined,
2089
- }));
2090
- const ids = new Set();
2091
- const findingIds = new Set();
2092
- for (const [viewpointIndex, result] of document.viewpoints.entries()) {
2093
- const resultPath = `${where}.viewpoints[${viewpointIndex}]`;
2094
- if (!result || !allowed.has(result.id)) {
2095
- issues.push({
2096
- path: resultPath,
2097
- message: `unknown or non-applicable viewpoint: ${result?.id ?? ""}`,
2098
- });
2099
- continue;
2100
- }
2101
- if (ids.has(result.id))
2102
- issues.push({ path: resultPath, message: `duplicate viewpoint: ${result.id}` });
2103
- ids.add(result.id);
2104
- if (!Number.isInteger(result.level) || result.level < 0 || result.level > 4) {
2105
- issues.push({ path: resultPath, message: "level must be an integer from 0 to 4" });
2106
- }
2107
- const findings = result.findings ?? [];
2108
- if (!Array.isArray(findings)) {
2109
- issues.push({ path: resultPath, message: "findings must be an array" });
2110
- continue;
2111
- }
2112
- if (result.level < 4 && findings.length === 0) {
2113
- issues.push({ path: resultPath, message: "level 0-3 requires at least one finding" });
2114
- }
2115
- for (const [findingIndex, finding] of findings.entries()) {
2116
- if (!finding ||
2117
- !Object.hasOwn(SEVERITY_LEVEL_CAP, finding.severity) ||
2118
- typeof finding.message !== "string" ||
2119
- !finding.message.trim()) {
2120
- issues.push({
2121
- path: `${resultPath}.findings[${findingIndex}]`,
2122
- message: "severity and non-empty message are required",
2123
- });
2124
- continue;
2125
- }
2126
- if (finding.message_ja !== undefined &&
2127
- (typeof finding.message_ja !== "string" || !finding.message_ja.trim())) {
2128
- issues.push({
2129
- path: `${resultPath}.findings[${findingIndex}].message_ja`,
2130
- message: "message_ja must be a non-empty string when present",
2131
- });
2132
- }
2133
- if (finding.id !== undefined) {
2134
- if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(finding.id)) {
2135
- issues.push({
2136
- path: `${resultPath}.findings[${findingIndex}].id`,
2137
- message: "id must contain only letters, digits, dot, underscore, or hyphen",
2138
- });
2139
- }
2140
- else if (findingIds.has(finding.id)) {
2141
- issues.push({
2142
- path: `${resultPath}.findings[${findingIndex}].id`,
2143
- message: `duplicate finding id: ${finding.id}`,
2144
- });
2145
- }
2146
- findingIds.add(finding.id);
2147
- }
2148
- if (finding.line !== undefined && (!Number.isInteger(finding.line) || finding.line < 1)) {
2149
- issues.push({
2150
- path: `${resultPath}.findings[${findingIndex}].line`,
2151
- message: "line must be a positive integer",
2152
- });
2153
- }
2154
- }
2155
- const cap = levelCapForFindings(findings);
2156
- if (result.level > cap)
2157
- issues.push({ path: resultPath, message: `finding severity caps level at ${cap}` });
2158
- }
2159
- if (document.level_corrections !== undefined) {
2160
- if (!Array.isArray(document.level_corrections)) {
2161
- issues.push({ path: `${where}.level_corrections`, message: "must be an array" });
2162
- }
2163
- else {
2164
- for (const [index, correction] of document.level_corrections.entries()) {
2165
- const correctedViewpoint = document.viewpoints.find((viewpoint) => viewpoint.id === correction?.viewpoint);
2166
- if (!correction ||
2167
- typeof correction.viewpoint !== "string" ||
2168
- !correctedViewpoint ||
2169
- !Number.isInteger(correction.original_level) ||
2170
- !Number.isInteger(correction.corrected_level) ||
2171
- correction.original_level < 0 ||
2172
- correction.original_level > 4 ||
2173
- correction.corrected_level < 0 ||
2174
- correction.corrected_level >= correction.original_level ||
2175
- correctedViewpoint.level !== correction.corrected_level) {
2176
- issues.push({
2177
- path: `${where}.level_corrections[${index}]`,
2178
- message: "viewpoint and matching downward original/corrected levels from 0 to 4 are required",
2179
- });
2180
- }
2181
- }
2182
- }
2183
- }
2184
- for (const viewpoint of required) {
2185
- if (!ids.has(viewpoint.id)) {
2186
- issues.push({ path: where, message: `missing agent viewpoint: ${viewpoint.id}` });
2187
- }
2188
- }
2189
- }
2190
- return issues;
2191
- }
2192
- function scoreDocument(input, rubric, doc, target) {
2193
- const definitions = new Map((doc.viewpoints ?? []).map((viewpoint) => [viewpoint.id, viewpoint]));
2194
- const categoryLevels = new Map();
2195
- const counts = { blocker: 0, major: 0, minor: 0, note: 0 };
2196
- const viewpointOutput = {};
2197
- for (const result of input.viewpoints) {
2198
- const definition = definitions.get(result.id);
2199
- const values = categoryLevels.get(definition.category) ?? [];
2200
- values.push(result.level);
2201
- categoryLevels.set(definition.category, values);
2202
- viewpointOutput[result.id] = { level: result.level, score: result.level * 25 };
2203
- for (const finding of result.findings ?? [])
2204
- counts[finding.severity] += 1;
2205
- }
2206
- const categories = {};
2207
- let weighted = 0;
2208
- let totalWeight = 0;
2209
- for (const [category, levels] of categoryLevels) {
2210
- const score = Math.round((levels.reduce((sum, level) => sum + level, 0) / levels.length) * 25);
2211
- categories[category] = { score };
2212
- const weight = rubric.weights[target][category] ?? 0;
2213
- weighted += score * weight;
2214
- totalWeight += weight;
2215
- }
2216
- const score = totalWeight > 0 ? Math.round(weighted / totalWeight) : 0;
2217
- const verdict = counts.blocker > 0
2218
- ? "fail"
2219
- : counts.major > 0 || score < rubric.pass_score
2220
- ? "needs-work"
2221
- : "pass";
2222
- return { score, verdict, categories, viewpoints: viewpointOutput, findings: counts };
2223
- }
2224
- // 詳細ファイルは成果物ごとに1件で、再評価のたびに上書きする。時点の記録は git 履歴が担う。
2225
- // grade 本体と同じ方式であり、実行ごとにファイルを増やすと最新の評価を判別できなくなる。
2226
- export function doneCriteriaDetailPath(criteriaDirectory, documentPath) {
2227
- const absolute = resolveSafeMarkdownPath(documentPath);
2228
- const directory = resolveSafeRepositoryPath(criteriaDirectory, "criteria directory");
2229
- return join(directory, gradePlanFilename(absolute).replace(/-grade-plan\.md$/, "-done-criteria.yaml"));
2230
- }
2231
- function doneCriteriaDetailId(documentId, documentPath) {
2232
- if (documentId)
2233
- return `${documentId}-grade-criteria`;
2234
- const hash = createHash("sha256")
2235
- .update(repoRelativePath(documentPath))
2236
- .digest("hex")
2237
- .slice(0, 10);
2238
- return `grade-criteria-${hash}`;
2239
- }
2240
- export function renderDoneCriteriaDetail(detail, detailPath) {
2241
- const schemaRef = relative(dirname(detailPath), resolveSpecdojoPath(DONE_CRITERIA_SCHEMA))
2242
- .split(sep)
2243
- .join("/");
2244
- return `# yaml-language-server: $schema=${schemaRef}\n${yaml.dump(detail, { lineWidth: 120, noRefs: true, quotingType: '"' })}`;
2245
- }
2246
- export function applyGradeSubmission(opts) {
2247
- const issues = validateGradeSubmission(opts.submission, opts.viewpoints, opts.target, {
2248
- doneCriteriaByPath: opts.doneCriteriaByPath,
2249
- });
2250
- if (issues.length > 0)
2251
- throw new Error(issues.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
2252
- const changed = [];
2253
- const sourceContext = opts.resultsDirectory
2254
- ? createGradeSourceContext(opts.project, specdojoRootDir())
2255
- : undefined;
2256
- for (const input of opts.submission.documents) {
2257
- const absolute = resolveSafeMarkdownPath(input.path);
2258
- const rel = repoRelativePath(absolute);
2259
- const current = readFileSync(absolute, "utf8");
2260
- const definitions = opts.doneCriteriaByPath?.get(rel);
2261
- const detailPath = definitions && input.done_criteria && opts.criteriaDirectory
2262
- ? doneCriteriaDetailPath(opts.criteriaDirectory, absolute)
2263
- : undefined;
2264
- if (definitions && input.done_criteria && !detailPath) {
2265
- throw new Error(`${rel}: criteriaDirectory is required to record done_criteria`);
2266
- }
2267
- if (opts.resultsDirectory) {
2268
- const documentId = markdownDocumentId(current, rel);
2269
- const resultPath = gradeResultPath(opts.resultsDirectory, documentId);
2270
- const previous = readGradeResult(resultPath);
2271
- const document = parseMarkdown(current, rel);
2272
- const agentResults = preserveStoredFindingSeverities(previous, input.viewpoints);
2273
- const correctionByViewpoint = new Map((input.level_corrections ?? []).map((correction) => [
2274
- correction.viewpoint,
2275
- { ...correction },
2276
- ]));
2277
- for (const [index, result] of agentResults.entries()) {
2278
- const submitted = input.viewpoints[index];
2279
- if (submitted && result.level < submitted.level) {
2280
- const existing = correctionByViewpoint.get(result.id);
2281
- correctionByViewpoint.set(result.id, {
2282
- viewpoint: result.id,
2283
- original_level: existing?.original_level ?? submitted.level,
2284
- corrected_level: result.level,
2285
- });
2286
- }
2287
- }
2288
- const levelCorrections = [...correctionByViewpoint.values()];
2289
- const evaluated = {
2290
- ...input,
2291
- viewpoints: [
2292
- ...agentResults,
2293
- ...deterministicResults(document, opts.viewpoints, opts.target),
2294
- ],
2295
- };
2296
- const rubric = assertRubric(opts.viewpoints);
2297
- const summary = scoreDocument(evaluated, rubric, opts.viewpoints, opts.target);
2298
- const gradedAt = (opts.now ?? new Date()).toISOString();
2299
- const usedIds = new Set();
2300
- let sequence = 0;
2301
- const bodyLines = document.body.split(/\r?\n/);
2302
- const findings = evaluated.viewpoints.flatMap((viewpoint) => (viewpoint.findings ?? []).map((finding) => {
2303
- let id = finding.id?.trim();
2304
- if (!id || usedIds.has(id)) {
2305
- do {
2306
- sequence += 1;
2307
- id = `F${String(sequence).padStart(3, "0")}`;
2308
- } while (usedIds.has(id));
2309
- }
2310
- usedIds.add(id);
2311
- const line = Math.max(1, finding.line ?? 1);
2312
- return {
2313
- id,
2314
- severity: finding.severity,
2315
- rule: viewpoint.id,
2316
- line,
2317
- anchor: bodyLines[Math.min(bodyLines.length, line) - 1]?.trim() ?? "",
2318
- message: sanitizeCommentText(finding.message),
2319
- message_ja: sanitizeCommentText(finding.message_ja ?? finding.message),
2320
- };
2321
- }));
2322
- const criteriaResults = opts.target === "deliverable" && definitions && input.done_criteria && detailPath
2323
- ? input.done_criteria
2324
- : undefined;
2325
- const detailRef = criteriaResults ? doneCriteriaDetailId(documentId, absolute) : undefined;
2326
- const sourceHashes = sourceContext
2327
- ? gradeSourceHashes(absolute, document, opts.viewpoints, opts.target, sourceContext)
2328
- : undefined;
2329
- const result = {
2330
- version: 1,
2331
- document: documentId,
2332
- path: rel,
2333
- target: opts.target,
2334
- rubric: rubric.id,
2335
- ...(opts.reference ? { reference: resolveGradeReferenceId(opts.reference) } : {}),
2336
- verdict: summary.verdict,
2337
- score: summary.score,
2338
- graded_at: gradedAt,
2339
- graded_by: opts.gradedBy,
2340
- content_hash: gradeContentHash(current),
2341
- ...(sourceHashes && Object.keys(sourceHashes).length > 0
2342
- ? { source_hashes: sourceHashes }
2343
- : {}),
2344
- categories: summary.categories,
2345
- viewpoints: summary.viewpoints,
2346
- finding_counts: summary.findings,
2347
- findings,
2348
- ...(levelCorrections.length > 0 ? { level_corrections: levelCorrections } : {}),
2349
- ...(criteriaResults && definitions && detailRef
2350
- ? { done_criteria: summarizeDoneCriteria(definitions, criteriaResults, detailRef) }
2351
- : {}),
2352
- };
2353
- if (criteriaResults && definitions && detailPath && detailRef) {
2354
- const resultById = new Map(criteriaResults.map((criterion) => [criterion.id, criterion]));
2355
- const criteria = definitions.map((definition) => {
2356
- const criterion = resultById.get(definition.id);
2357
- return {
2358
- ...definition,
2359
- status: criterion?.status ?? "unsatisfied",
2360
- ...(criterion?.reason ? { reason: criterion.reason } : {}),
2361
- };
2362
- });
2363
- const satisfied = criteria.filter((criterion) => criterion.status === "satisfied").length;
2364
- const detail = {
2365
- id: detailRef,
2366
- document: documentId,
2367
- path: rel,
2368
- graded_at: gradedAt,
2369
- graded_by: opts.gradedBy,
2370
- content_hash: result.content_hash,
2371
- summary: { satisfied, unsatisfied: criteria.length - satisfied, total: criteria.length },
2372
- criteria,
2373
- };
2374
- const rendered = renderDoneCriteriaDetail(detail, detailPath);
2375
- if (!existsSync(detailPath) || readFileSync(detailPath, "utf8") !== rendered) {
2376
- changed.push(repoRelativePath(detailPath));
2377
- if (!opts.dryRun) {
2378
- mkdirSync(dirname(detailPath), { recursive: true });
2379
- writeFileSync(detailPath, rendered, "utf8");
2380
- }
2381
- }
2382
- }
2383
- if (writeGradeResult(resultPath, result, opts.dryRun)) {
2384
- changed.push(repoRelativePath(resultPath));
2385
- }
2386
- continue;
2387
- }
2388
- const documentId = parseMarkdown(current, rel).data.specdojo;
2389
- const graded = gradeMarkdownDocument({
2390
- content: current,
2391
- path: rel,
2392
- input,
2393
- viewpoints: opts.viewpoints,
2394
- target: opts.target,
2395
- gradedBy: opts.gradedBy,
2396
- reference: opts.reference,
2397
- now: opts.now,
2398
- doneCriteria: definitions && detailPath
2399
- ? {
2400
- definitions,
2401
- detailRef: doneCriteriaDetailId(typeof documentId.id === "string" ? documentId.id : undefined, absolute),
2402
- }
2403
- : undefined,
2404
- });
2405
- // 詳細を先に永続化してから成果物へ detail_ref を書く。途中で詳細の書き込みに失敗しても、
2406
- // 存在しない参照だけが成果物へ残る状態を避ける。
2407
- if (graded.detail && detailPath) {
2408
- const rendered = renderDoneCriteriaDetail(graded.detail, detailPath);
2409
- const detailRel = repoRelativePath(detailPath);
2410
- if (!existsSync(detailPath) || readFileSync(detailPath, "utf8") !== rendered) {
2411
- changed.push(detailRel);
2412
- if (!opts.dryRun) {
2413
- mkdirSync(dirname(detailPath), { recursive: true });
2414
- writeFileSync(detailPath, rendered, "utf8");
2415
- }
2416
- }
2417
- }
2418
- if (graded.content !== current) {
2419
- changed.push(rel);
2420
- if (!opts.dryRun)
2421
- writeFileSync(absolute, graded.content, "utf8");
2422
- }
2423
- }
2424
- return changed;
2425
- }
2426
- // 比較リファレンスは ID で保存する。パスで保存すると文書を移動したときに参照が壊れる。
2427
- // 引数にはパスと ID のどちらも渡せる。パスの場合は Frontmatter の id を読み取る。
2428
- export function resolveGradeReferenceId(pathOrId) {
2429
- const trimmed = pathOrId.trim();
2430
- if (!trimmed.endsWith(".md"))
2431
- return trimmed;
2432
- const absolute = resolveSafeMarkdownPath(trimmed);
2433
- const document = parseMarkdown(readFileSync(absolute, "utf8"), repoRelativePath(absolute));
2434
- const metadata = document.data.specdojo;
2435
- if (!isRecord(metadata) || typeof metadata.id !== "string" || metadata.id.length === 0) {
2436
- throw new Error(`${repoRelativePath(absolute)}: reference document has no specdojo.id`);
2437
- }
2438
- return metadata.id;
2439
- }
2440
- // score と done_criteria の充足は別の軸として扱う。verdict は score と finding だけで決め、
2441
- // 充足状況は要約として並記する。score の閾値が充足判定を上書きせず、その逆も行わない。
2442
- function summarizeDoneCriteria(definitions, results, detailRef) {
2443
- const resultById = new Map(results.map((result) => [result.id, result]));
2444
- const unsatisfied = {};
2445
- let satisfied = 0;
2446
- for (const criterion of definitions) {
2447
- const result = resultById.get(criterion.id);
2448
- if (result?.status === "satisfied")
2449
- satisfied += 1;
2450
- else
2451
- unsatisfied[criterion.id] = [...criterion.roles];
2452
- }
2453
- return {
2454
- satisfied,
2455
- total: definitions.length,
2456
- ...(Object.keys(unsatisfied).length > 0 ? { unsatisfied } : {}),
2457
- detail_ref: detailRef,
2458
- };
2459
- }
2460
- export function gradeMarkdownDocument(opts) {
2461
- const document = parseMarkdown(opts.content, opts.path);
2462
- const specdojo = document.data.specdojo;
2463
- const agentResults = preservePreviousFindingSeverities(document.body, opts.input.viewpoints);
2464
- const evaluated = {
2465
- ...opts.input,
2466
- viewpoints: [...agentResults, ...deterministicResults(document, opts.viewpoints, opts.target)],
2467
- };
2468
- const rubric = assertRubric(opts.viewpoints);
2469
- const summary = scoreDocument(evaluated, rubric, opts.viewpoints, opts.target);
2470
- const body = insertFindings(document.body, evaluated.viewpoints);
2471
- const gradedAt = (opts.now ?? new Date()).toISOString();
2472
- const contentHash = legacyInlineContentHash({ data: document.data, body });
2473
- const criteriaResults = opts.target === "deliverable" && opts.doneCriteria && opts.input.done_criteria
2474
- ? opts.input.done_criteria
2475
- : undefined;
2476
- const applicableCriteriaDefinitions = opts.doneCriteria
2477
- ? applicableDoneCriteria(opts.doneCriteria.definitions, opts.viewpoints, specdojo)
2478
- : undefined;
2479
- specdojo.grade = {
2480
- rubric: rubric.id,
2481
- ...(opts.reference ? { reference: resolveGradeReferenceId(opts.reference) } : {}),
2482
- target: opts.target,
2483
- verdict: summary.verdict,
2484
- score: summary.score,
2485
- graded_at: gradedAt,
2486
- graded_by: opts.gradedBy,
2487
- content_hash: contentHash,
2488
- categories: summary.categories,
2489
- viewpoints: summary.viewpoints,
2490
- findings: summary.findings,
2491
- ...(criteriaResults && opts.doneCriteria && applicableCriteriaDefinitions
2492
- ? {
2493
- done_criteria: summarizeDoneCriteria(applicableCriteriaDefinitions, criteriaResults, opts.doneCriteria.detailRef),
2494
- }
2495
- : {}),
2496
- };
2497
- const content = serializeMarkdown({ data: document.data, body });
2498
- if (!criteriaResults || !opts.doneCriteria)
2499
- return { content };
2500
- const resultById = new Map(criteriaResults.map((result) => [result.id, result]));
2501
- const criteria = opts.doneCriteria.definitions.map((criterion) => {
2502
- const result = resultById.get(criterion.id);
2503
- return {
2504
- ...criterion,
2505
- status: result?.status ?? "unsatisfied",
2506
- ...(result?.reason ? { reason: result.reason } : {}),
2507
- };
2508
- });
2509
- const satisfied = criteria.filter((criterion) => criterion.status === "satisfied").length;
2510
- return {
2511
- content,
2512
- detail: {
2513
- id: opts.doneCriteria.detailRef,
2514
- document: typeof specdojo.id === "string" ? specdojo.id : opts.path,
2515
- path: opts.path,
2516
- graded_at: gradedAt,
2517
- graded_by: opts.gradedBy,
2518
- content_hash: contentHash,
2519
- summary: { satisfied, unsatisfied: criteria.length - satisfied, total: criteria.length },
2520
- criteria,
2521
- },
2522
- };
2523
- }
2524
- export function gradeMarkdownContent(opts) {
2525
- return gradeMarkdownDocument(opts).content;
2526
- }
2527
- export function validateGradedDocument(path) {
2528
- const absolute = resolveSafeMarkdownPath(path);
2529
- const rel = repoRelativePath(absolute);
2530
- return validateGradedMarkdown(readFileSync(absolute, "utf8"), rel);
2531
- }
2532
- export function validateGradeResultForDocument(opts) {
2533
- const absolute = resolveSafeMarkdownPath(opts.path);
2534
- const rel = repoRelativePath(absolute);
2535
- const content = readFileSync(absolute, "utf8");
2536
- const result = readGradeResultForDocument({ documentPath: rel, project: opts.project });
2537
- if (!result)
2538
- return [];
2539
- return validateGradeResult(result, content, rel, opts.target);
2540
- }
2541
- export function validateGradedMarkdown(content, path) {
2542
- const document = parseMarkdown(content, path);
2543
- const specdojo = document.data.specdojo;
2544
- const grade = isRecord(specdojo.grade) ? specdojo.grade : null;
2545
- if (!grade)
2546
- return [`${path}: specdojo.grade is missing`];
2547
- const findings = isRecord(grade.findings) ? grade.findings : {};
2548
- const actual = { blocker: 0, major: 0, minor: 0, note: 0 };
2549
- for (const match of document.body.matchAll(FINDING_RE))
2550
- actual[match[2]] += 1;
2551
- const errors = [];
2552
- for (const severity of Object.keys(actual)) {
2553
- if (findings[severity] !== actual[severity])
2554
- errors.push(`${path}: findings.${severity}=${String(findings[severity])}, comments=${actual[severity]}`);
2555
- }
2556
- if (grade.content_hash !== legacyInlineContentHash(document))
2557
- errors.push(`${path}: content changed after the last grade`);
2558
- return errors;
2559
- }
2560
- export function migrateInlineGrades(opts) {
2561
- const rootDir = specdojoRootDir();
2562
- const candidates = opts.paths && opts.paths.length > 0
2563
- ? opts.paths.map((path) => resolveSafeMarkdownPath(path, rootDir))
2564
- : [
2565
- ...(opts.target !== "deliverable"
2566
- ? discoverGradeTargets({ target: "kata", project: opts.project }, rootDir)
2567
- : []),
2568
- ...(opts.target !== "kata"
2569
- ? discoverGradeTargets({ target: "deliverable", project: opts.project }, rootDir)
2570
- : []),
2571
- ];
2572
- const resultsDirectory = resolveGradeResultsDirectory(opts.project, rootDir);
2573
- const changed = [];
2574
- for (const absolute of candidates) {
2575
- const rel = relativePathFromRoot(absolute, rootDir);
2576
- const current = readFileSync(absolute, "utf8");
2577
- if (!current.includes("specdojo:finding") && !/^ grade:\s*$/m.test(current))
2578
- continue;
2579
- let document;
2580
- try {
2581
- document = parseMarkdown(current, rel);
2582
- }
2583
- catch {
2584
- continue;
2585
- }
2586
- const specdojo = document.data.specdojo;
2587
- const legacyGrade = isRecord(specdojo.grade) ? structuredClone(specdojo.grade) : undefined;
2588
- const legacyTarget = legacyGrade?.target;
2589
- const target = legacyTarget === "kata" || legacyTarget === "deliverable"
2590
- ? legacyTarget
2591
- : rel.startsWith("docs/ja/specdojo/")
2592
- ? "kata"
2593
- : "deliverable";
2594
- if (opts.target && target !== opts.target)
2595
- continue;
2596
- const legacyFindings = [...document.body.matchAll(FINDING_RE)].map((match) => ({
2597
- id: match[1],
2598
- severity: match[2],
2599
- rule: match[3],
2600
- line: match[4] ? Number(match[4]) : 1,
2601
- message: match[5].trim(),
2602
- }));
2603
- delete specdojo.grade;
2604
- document.body = withoutFindingComments(document.body)
2605
- .replace(/\n{3,}/g, "\n\n")
2606
- .replace(/(?:\n[ \t]*)*$/, "\n");
2607
- const cleaned = serializeMarkdown(document);
2608
- if (cleaned !== current) {
2609
- changed.push(rel);
2610
- if (!opts.dryRun)
2611
- writeFileSync(absolute, cleaned, "utf8");
2612
- }
2613
- if (!legacyGrade)
2614
- continue;
2615
- const documentId = markdownDocumentId(cleaned, rel);
2616
- const bodyLines = document.body.split(/\r?\n/);
2617
- const findings = legacyFindings.map((finding) => ({
2618
- ...finding,
2619
- anchor: bodyLines[Math.min(bodyLines.length, finding.line) - 1]?.trim() ?? "",
2620
- message_ja: finding.message,
2621
- }));
2622
- const counts = { blocker: 0, major: 0, minor: 0, note: 0 };
2623
- for (const finding of findings)
2624
- counts[finding.severity] += 1;
2625
- if (typeof legacyGrade.rubric !== "string" ||
2626
- (legacyGrade.verdict !== "pass" &&
2627
- legacyGrade.verdict !== "needs-work" &&
2628
- legacyGrade.verdict !== "fail") ||
2629
- !Number.isSafeInteger(legacyGrade.score) ||
2630
- typeof legacyGrade.graded_at !== "string" ||
2631
- typeof legacyGrade.graded_by !== "string" ||
2632
- !isRecord(legacyGrade.categories) ||
2633
- !isRecord(legacyGrade.viewpoints)) {
2634
- throw new Error(`${rel}: legacy specdojo.grade is invalid`);
2635
- }
2636
- const result = {
2637
- version: 1,
2638
- document: documentId,
2639
- path: rel,
2640
- target,
2641
- rubric: legacyGrade.rubric,
2642
- ...(typeof legacyGrade.reference === "string" ? { reference: legacyGrade.reference } : {}),
2643
- verdict: legacyGrade.verdict,
2644
- score: legacyGrade.score,
2645
- graded_at: legacyGrade.graded_at,
2646
- graded_by: legacyGrade.graded_by,
2647
- content_hash: gradeContentHash(cleaned),
2648
- categories: legacyGrade.categories,
2649
- viewpoints: legacyGrade.viewpoints,
2650
- finding_counts: counts,
2651
- findings,
2652
- ...(isRecord(legacyGrade.done_criteria) ? { done_criteria: legacyGrade.done_criteria } : {}),
2653
- };
2654
- const resultPath = gradeResultPath(resultsDirectory, documentId);
2655
- if (writeGradeResult(resultPath, result, opts.dryRun)) {
2656
- changed.push(repoRelativePath(resultPath));
2657
- }
2658
- }
2659
- return changed;
2660
- }
2661
- function collectPathOption(value, previous) {
2662
- return [...previous, value];
2663
- }
2664
- function requireTarget(value) {
2665
- if (value !== "kata" && value !== "deliverable")
2666
- throw new Error("--target must be kata or deliverable");
2667
- return value;
2668
- }
2669
- function requireGradeVerdict(value) {
2670
- if (value !== "pass" && value !== "needs-work" && value !== "fail") {
2671
- throw new Error("--verdict must be pass, needs-work, or fail");
2672
- }
2673
- return value;
2674
- }
2675
- function requireMaxFindings(value) {
2676
- const parsed = Number(value);
2677
- if (!Number.isSafeInteger(parsed) || parsed < 0) {
2678
- throw new Error("--max-findings must be a non-negative integer");
2679
- }
2680
- return parsed;
2681
- }
2682
- function requireMinScore(value) {
2683
- const parsed = Number(value);
2684
- if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > 100) {
2685
- throw new Error("--min-score must be an integer between 0 and 100");
2686
- }
2687
- return parsed;
2688
- }
2689
- function requirePositiveInteger(value) {
2690
- const parsed = Number(value);
2691
- if (!Number.isSafeInteger(parsed) || parsed < 1) {
2692
- throw new Error("value must be a positive integer");
2693
- }
2694
- return parsed;
2695
- }
2696
- function requireNonNegativeInteger(value) {
2697
- const parsed = Number(value);
2698
- if (!Number.isSafeInteger(parsed) || parsed < 0) {
2699
- throw new Error("value must be a non-negative integer");
2700
- }
2701
- return parsed;
2702
- }
2703
- function requirePipelineStatus(value) {
2704
- if (value !== "passed" && value !== "failed" && value !== "complete") {
2705
- throw new Error("--status must be passed, failed, or complete");
2706
- }
2707
- return value;
2708
- }
2709
- function commandError(error) {
2710
- process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
2711
- process.exitCode = 1;
2712
- }
2713
- export function renderGradeFindingTranslationPlan(result, translationIndex) {
2714
- const messages = gradeFindingTranslationInput(result, translationIndex);
2715
- return [
2716
- "# Grade finding translation",
2717
- "",
2718
- "次の JSON 文字列配列に含まれる英語の finding だけを、簡潔で自然な日本語へ翻訳してください。入力と同じ件数・同じ順序の、訳文だけの JSON 文字列配列を返してください。元の文にあるインラインコード(バッククォートで囲んだ部分)は一字一句変えずに残し、元の文にないインラインコードやバッククォートは追加しないでください。インラインコード以外の英語の語句は、固有名詞・識別子を除いて日本語に訳してください。Markdown fence、説明、番号、token、判定の変更は不要です。",
2719
- "",
2720
- "```json",
2721
- JSON.stringify(messages, null, 2),
2722
- "```",
2723
- "",
2724
- ].join("\n");
2725
- }
1
+ import { registerGradeApplyCommands } from "./grade-command-apply.js";
2
+ import { registerGradeInspectionCommands } from "./grade-command-inspect.js";
3
+ import { registerGradePlanCommands } from "./grade-command-plan.js";
4
+ export * from "./grade-apply.js";
5
+ export { renderGradeFindingTranslationPlan } from "./grade-command-apply.js";
6
+ export * from "./grade-core.js";
7
+ export * from "./grade-markdown.js";
8
+ export * from "./grade-pipeline-state.js";
9
+ export * from "./grade-plan.js";
10
+ export * from "./grade-target-discovery.js";
11
+ export * from "./grade-targets.js";
2726
12
  export function registerGradeCommand(program) {
2727
13
  const grade = program
2728
14
  .command("grade")
2729
15
  .description("Continuously assess Kata and deliverable content quality");
2730
- const addSelection = (command) => command
2731
- .requiredOption("--target <target>", "kata or deliverable")
2732
- .option("--project <projectId>", "Project id in specdojo.config.json")
2733
- .option("--path <path>", "Grade only this Markdown document (repeatable)", collectPathOption, [])
2734
- .option("--changed-only", "Select documents changed since their latest grade", false)
2735
- .option("--dependency-changed", "Select documents whose dependencies have been graded more recently", false)
2736
- .option("--rulebook-changed", "Select documents whose declared rulebook has been graded more recently", false)
2737
- .option("--unreviewed", "Select ungraded or changed documents that do not have a schedule task", false)
2738
- .option("--verdict <verdict>", "Select documents with this latest verdict: pass, needs-work, or fail", requireGradeVerdict)
2739
- .option("--min-score <score>", "Select graded documents with at least this score (0-100)", requireMinScore)
2740
- .option("--max-findings <count>", "Select graded documents with at most this many findings", requireMaxFindings)
2741
- .option("--ungraded", "Select documents without a stored grade", false)
2742
- .option("--incomplete", "Select documents with a retryable incomplete pipeline", false)
2743
- .option("--rubric-outdated", "Select graded documents whose stored result was not graded with the current rubric", false);
2744
- addSelection(grade.command("list").description("Print selected document paths without writing grade plans")).action((options) => {
2745
- try {
2746
- const paths = discoverGradeTargets({
2747
- target: requireTarget(options.target),
2748
- project: options.project,
2749
- paths: options.path,
2750
- changedOnly: options.changedOnly,
2751
- dependencyChanged: options.dependencyChanged,
2752
- rulebookChanged: options.rulebookChanged,
2753
- unreviewed: options.unreviewed,
2754
- verdict: options.verdict,
2755
- minScore: options.minScore,
2756
- maxFindings: options.maxFindings,
2757
- ungraded: options.ungraded,
2758
- incomplete: options.incomplete,
2759
- rubricOutdated: options.rubricOutdated,
2760
- });
2761
- for (const path of paths)
2762
- process.stdout.write(`${repoRelativePath(path)}\n`);
2763
- }
2764
- catch (error) {
2765
- commandError(error);
2766
- }
2767
- });
2768
- addSelection(grade
2769
- .command("plan")
2770
- .description("Write reusable executor and reporter plans per selected document"))
2771
- .option("--out <directory>", "Write plans below this repository-relative directory")
2772
- .option("--reference <path>", "Use this document as the comparison reference")
2773
- .option("--embed-documents", "Embed the target and reference documents in the executor plan", false)
2774
- .option("--random-reference", "Select a comparison reference at random from ready documents", false)
2775
- .action((options) => {
2776
- try {
2777
- const target = requireTarget(options.target);
2778
- const viewpoints = loadViewpoints(options.project);
2779
- const { id: projectId, project } = resolveProject(options.project);
2780
- const paths = discoverGradeTargets({
2781
- target,
2782
- project: options.project,
2783
- paths: options.path,
2784
- changedOnly: options.changedOnly,
2785
- dependencyChanged: options.dependencyChanged,
2786
- rulebookChanged: options.rulebookChanged,
2787
- unreviewed: options.unreviewed,
2788
- verdict: options.verdict,
2789
- minScore: options.minScore,
2790
- maxFindings: options.maxFindings,
2791
- ungraded: options.ungraded,
2792
- incomplete: options.incomplete,
2793
- rubricOutdated: options.rubricOutdated,
2794
- });
2795
- if (options.reference && options.randomReference) {
2796
- throw new Error("--reference and --random-reference cannot be combined");
2797
- }
2798
- // 比較リファレンスは既定で付けない。効果が未実証であり、付けると executor の
2799
- // 読み込み対象が増えるためである。利用する場合は明示的に指定する。
2800
- const referenceExampleCandidates = options.randomReference
2801
- ? discoverGradeTargets({ target, project: options.project, changedOnly: false })
2802
- : [];
2803
- const outputDirectory = options.out ??
2804
- join(getProjectExecutionPath(project), "grade", "generated", "plans", target);
2805
- const plans = writeGradePlans({
2806
- target,
2807
- paths,
2808
- referenceExampleCandidates,
2809
- referenceExampleOverride: options.reference,
2810
- viewpoints,
2811
- projectId,
2812
- outputDirectory,
2813
- embedDocuments: options.embedDocuments,
2814
- doneCriteriaByPath: target === "deliverable"
2815
- ? resolveDeliverableDoneCriteria(paths, options.project)
2816
- : undefined,
2817
- });
2818
- for (const plan of plans) {
2819
- // 無作為選定を求めたのに同種別の ready が無い場合は、種別を跨いで代用せず
2820
- // リファレンスなしで続行する。種別が違うと記載水準の基準として誤りを招く。
2821
- // 気づかないまま基準なしで評価し続けることを避けるため警告する。
2822
- if (options.randomReference && !plan.referenceExample) {
2823
- process.stderr.write(`warning: no ready reference of the same kind for ${plan.target}; grading without a reference\n`);
2824
- }
2825
- if (options.embedDocuments && !plan.documentsEmbedded) {
2826
- process.stderr.write(`warning: embedded documents for ${plan.target} would use ${plan.embeddingCharacterCount} characters and exceed the ${plan.embeddingCharacterLimit} character limit; falling back to path references\n`);
2827
- }
2828
- process.stdout.write(`${plan.changed ? "written" : "unchanged"}: ${plan.path}\n`);
2829
- process.stdout.write(`${plan.reporterChanged ? "written" : "unchanged"}: ${plan.reporterPath}\n`);
2830
- }
2831
- process.stdout.write(`Planned: ${plans.length} document(s)\n`);
2832
- }
2833
- catch (error) {
2834
- commandError(error);
2835
- }
2836
- });
2837
- addSelection(grade
2838
- .command("apply")
2839
- .description("Convert executor markers (or validate reporter JSON), calculate scores, and update documents"))
2840
- .option("--from <path>", "GradeSubmission JSON produced by an LLM reporter; omit to convert --analysis-from mechanically")
2841
- .requiredOption("--by <nickname>", "Grading agent nickname from agent-members.yaml")
2842
- .option("--analysis-from <path>", "Executor analysis converted to GradeSubmission, or used to verify --from fidelity")
2843
- .option("--submission-out <path>", "Write the GradeSubmission converted from --analysis-from to this repository path")
2844
- .option("--reference <pathOrId>", "Comparison reference used during grading; recorded as a document id")
2845
- .option("--dry-run", "Validate and list updates without writing", false)
2846
- .action((options) => {
2847
- try {
2848
- const target = requireTarget(options.target);
2849
- const viewpoints = loadViewpoints(options.project);
2850
- const { project } = resolveProject(options.project);
2851
- const gradedBy = resolveGradeActor(options.by, loadMemberRoster(specdojoRootDir(), project));
2852
- if (!options.from && !options.analysisFrom) {
2853
- throw new Error("grade apply requires --analysis-from, --from, or both");
2854
- }
2855
- if (options.submissionOut && (options.from || !options.analysisFrom)) {
2856
- throw new Error("--submission-out requires --analysis-from without --from");
2857
- }
2858
- const selected = new Set(discoverGradeTargets({
2859
- target,
2860
- project: options.project,
2861
- paths: options.path,
2862
- changedOnly: options.changedOnly,
2863
- dependencyChanged: options.dependencyChanged,
2864
- rulebookChanged: options.rulebookChanged,
2865
- unreviewed: options.unreviewed,
2866
- verdict: options.verdict,
2867
- minScore: options.minScore,
2868
- maxFindings: options.maxFindings,
2869
- ungraded: options.ungraded,
2870
- incomplete: options.incomplete,
2871
- rubricOutdated: options.rubricOutdated,
2872
- }).map(repoRelativePath));
2873
- const doneCriteriaByPath = target === "deliverable"
2874
- ? resolveDeliverableDoneCriteria([...selected], options.project)
2875
- : undefined;
2876
- let submission;
2877
- if (options.analysisFrom) {
2878
- if (selected.size !== 1) {
2879
- throw new Error("--analysis-from requires exactly one selected --path");
2880
- }
2881
- const expectedPath = [...selected][0];
2882
- const executorOutput = readFileSync(resolveSafeRepositoryPath(options.analysisFrom, "--analysis-from"), "utf8");
2883
- const conversionOptions = {
2884
- executorOutput,
2885
- viewpoints,
2886
- target,
2887
- expectedPath,
2888
- doneCriteria: doneCriteriaByPath?.get(expectedPath),
2889
- };
2890
- if (options.from) {
2891
- // LLM reporter の JSON を executor marker と照合する互換・比較用の経路。
2892
- submission = parseGradeSubmission(readFileSync(resolveSafeRepositoryPath(options.from, "--from"), "utf8"));
2893
- const fidelityIssues = validateGradeReporterFidelity({
2894
- ...conversionOptions,
2895
- submission,
2896
- });
2897
- if (fidelityIssues.length > 0) {
2898
- throw new Error(fidelityIssues.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
2899
- }
2900
- const converted = buildGradeSubmissionFromAnalysis(conversionOptions);
2901
- if (converted.submission === undefined) {
2902
- throw new Error(converted.issues.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
2903
- }
2904
- const convertedDocument = converted.submission.documents[0];
2905
- const correctedLevels = new Map(convertedDocument.viewpoints.map((viewpoint) => [viewpoint.id, viewpoint.level]));
2906
- submission.documents[0] = {
2907
- ...submission.documents[0],
2908
- viewpoints: submission.documents[0].viewpoints.map((viewpoint) => ({
2909
- ...viewpoint,
2910
- level: correctedLevels.get(viewpoint.id) ?? viewpoint.level,
2911
- })),
2912
- ...(convertedDocument.level_corrections
2913
- ? { level_corrections: convertedDocument.level_corrections }
2914
- : {}),
2915
- };
2916
- }
2917
- else {
2918
- const converted = buildGradeSubmissionFromAnalysis(conversionOptions);
2919
- if (converted.submission === undefined) {
2920
- throw new Error([
2921
- "executor analysis rejected; rerun the executor",
2922
- ...converted.issues.map((issue) => `${issue.path}: ${issue.message}`),
2923
- ].join("\n"));
2924
- }
2925
- submission = converted.submission;
2926
- if (options.submissionOut && !options.dryRun) {
2927
- const submissionOut = resolveSafeRepositoryPath(options.submissionOut, "--submission-out");
2928
- mkdirSync(dirname(submissionOut), { recursive: true });
2929
- writeFileSync(submissionOut, `${JSON.stringify(submission, null, 2)}\n`, "utf8");
2930
- }
2931
- }
2932
- }
2933
- else {
2934
- submission = parseGradeSubmission(readFileSync(resolveSafeRepositoryPath(options.from, "--from"), "utf8"));
2935
- }
2936
- for (const document of submission.documents)
2937
- if (!selected.has(repoRelativePath(resolve(specdojoRootDir(), document.path))))
2938
- throw new Error(`${document.path}: not selected by the current grade filters`);
2939
- const changed = applyGradeSubmission({
2940
- submission,
2941
- viewpoints,
2942
- target,
2943
- gradedBy,
2944
- reference: options.reference,
2945
- dryRun: options.dryRun,
2946
- doneCriteriaByPath,
2947
- criteriaDirectory: join(getProjectExecutionPath(project), "grade", "criteria"),
2948
- resultsDirectory: join(getProjectExecutionPath(project), "grade", "results"),
2949
- project: options.project,
2950
- });
2951
- for (const path of changed)
2952
- process.stdout.write(`${options.dryRun ? "would update" : "updated"}: ${path}\n`);
2953
- process.stdout.write(`Graded: ${submission.documents.length}, updated: ${changed.length}\n`);
2954
- }
2955
- catch (error) {
2956
- commandError(error);
2957
- }
2958
- });
2959
- addSelection(grade
2960
- .command("translation-plan")
2961
- .description("Create a Japanese translation request for the latest canonical findings"))
2962
- .requiredOption("--out <path>", "Write the translation plan to this repository path")
2963
- .option("--translation-index <index>", "Translate only this zero-based index from the translatable findings", requireNonNegativeInteger)
2964
- .action((options) => {
2965
- try {
2966
- const target = requireTarget(options.target);
2967
- const selected = discoverGradeTargets({
2968
- target,
2969
- project: options.project,
2970
- paths: options.path,
2971
- changedOnly: options.changedOnly,
2972
- dependencyChanged: options.dependencyChanged,
2973
- rulebookChanged: options.rulebookChanged,
2974
- unreviewed: options.unreviewed,
2975
- verdict: options.verdict,
2976
- minScore: options.minScore,
2977
- maxFindings: options.maxFindings,
2978
- ungraded: options.ungraded,
2979
- incomplete: options.incomplete,
2980
- rubricOutdated: options.rubricOutdated,
2981
- }).map(repoRelativePath);
2982
- if (selected.length !== 1) {
2983
- throw new Error("grade translation-plan requires exactly one selected --path");
2984
- }
2985
- const result = readGradeResultForDocument({
2986
- documentPath: selected[0],
2987
- project: options.project,
2988
- });
2989
- if (!result)
2990
- throw new Error(`${selected[0]}: grade result not found`);
2991
- if (result.target !== target) {
2992
- throw new Error(`${selected[0]}: grade result target=${result.target}, expected=${target}`);
2993
- }
2994
- const output = resolveSafeRepositoryPath(options.out, "--out");
2995
- mkdirSync(dirname(output), { recursive: true });
2996
- const messages = gradeFindingTranslationInput(result, options.translationIndex);
2997
- writeFileSync(output, renderGradeFindingTranslationPlan(result, options.translationIndex), "utf8");
2998
- process.stdout.write(`written: ${repoRelativePath(output)}\nTranslations: ${messages.length}\n`);
2999
- }
3000
- catch (error) {
3001
- commandError(error);
3002
- }
3003
- });
3004
- addSelection(grade
3005
- .command("localize")
3006
- .description("Attach Japanese display messages to the latest canonical grade findings"))
3007
- .requiredOption("--from <path>", "JSON string array returned by the translation agent")
3008
- .option("--translation-index <index>", "Apply a retry for this zero-based index from the translatable findings", requireNonNegativeInteger)
3009
- .requiredOption("--rejections-out <path>", "Write machine-readable rejected translation details as JSON")
3010
- .action((options) => {
3011
- try {
3012
- const target = requireTarget(options.target);
3013
- const selected = discoverGradeTargets({
3014
- target,
3015
- project: options.project,
3016
- paths: options.path,
3017
- changedOnly: options.changedOnly,
3018
- dependencyChanged: options.dependencyChanged,
3019
- rulebookChanged: options.rulebookChanged,
3020
- unreviewed: options.unreviewed,
3021
- verdict: options.verdict,
3022
- minScore: options.minScore,
3023
- maxFindings: options.maxFindings,
3024
- ungraded: options.ungraded,
3025
- incomplete: options.incomplete,
3026
- rubricOutdated: options.rubricOutdated,
3027
- }).map(repoRelativePath);
3028
- if (selected.length !== 1) {
3029
- throw new Error("grade localize requires exactly one selected --path");
3030
- }
3031
- const resultPath = gradeResultPathForDocument({
3032
- documentPath: selected[0],
3033
- project: options.project,
3034
- });
3035
- const result = readGradeResult(resultPath);
3036
- if (!result)
3037
- throw new Error(`${selected[0]}: grade result not found`);
3038
- if (result.target !== target) {
3039
- throw new Error(`${selected[0]}: grade result target=${result.target}, expected=${target}`);
3040
- }
3041
- let translations;
3042
- try {
3043
- translations = JSON.parse(extractJsonArrayText(readFileSync(resolveSafeRepositoryPath(options.from, "--from"), "utf8")));
3044
- }
3045
- catch (error) {
3046
- translations = undefined;
3047
- process.stderr.write(`warning: could not parse grade finding translations: ${error instanceof Error ? error.message : String(error)}\n`);
3048
- }
3049
- const localized = applyGradeFindingTranslations(result, translations, options.translationIndex);
3050
- if (!localized.accepted) {
3051
- process.stderr.write(`warning: rejected grade finding translations: ${localized.reason ?? "invalid output"}\n`);
3052
- }
3053
- const rejectionsPath = resolveSafeRepositoryPath(options.rejectionsOut, "--rejections-out");
3054
- mkdirSync(dirname(rejectionsPath), { recursive: true });
3055
- writeFileSync(rejectionsPath, `${JSON.stringify({ version: 1, rejections: localized.rejections }, null, 2)}\n`, "utf8");
3056
- const changed = writeGradeResult(resultPath, localized.result);
3057
- process.stdout.write(`${changed ? "updated" : "unchanged"}: ${repoRelativePath(resultPath)}\n`);
3058
- }
3059
- catch (error) {
3060
- commandError(error);
3061
- }
3062
- });
3063
- addSelection(grade.command("validate").description("Validate stored grade hashes and finding counts")).action((options) => {
3064
- try {
3065
- const target = requireTarget(options.target);
3066
- const paths = discoverGradeTargets({
3067
- target,
3068
- project: options.project,
3069
- paths: options.path,
3070
- changedOnly: options.changedOnly,
3071
- dependencyChanged: options.dependencyChanged,
3072
- rulebookChanged: options.rulebookChanged,
3073
- unreviewed: options.unreviewed,
3074
- verdict: options.verdict,
3075
- minScore: options.minScore,
3076
- maxFindings: options.maxFindings,
3077
- ungraded: options.ungraded,
3078
- incomplete: options.incomplete,
3079
- rubricOutdated: options.rubricOutdated,
3080
- });
3081
- const errors = paths.flatMap((path) => validateGradeResultForDocument({ path, target, project: options.project }));
3082
- for (const error of errors)
3083
- process.stderr.write(`ERROR: ${error}\n`);
3084
- process.stdout.write(`Validated: ${paths.length} document(s), ${errors.length} error(s)\n`);
3085
- if (errors.length > 0)
3086
- process.exitCode = 1;
3087
- }
3088
- catch (error) {
3089
- commandError(error);
3090
- }
3091
- });
3092
- grade
3093
- .command("result")
3094
- .description("Print the stored grade result sidecar for one document as JSON")
3095
- .requiredOption("--path <path>", "Markdown document whose grade result is read")
3096
- .option("--project <projectId>", "Project id in specdojo.config.json")
3097
- .action((options) => {
3098
- try {
3099
- const absolute = resolveSafeMarkdownPath(options.path);
3100
- const rel = repoRelativePath(absolute);
3101
- const result = readGradeResultForDocument({ documentPath: rel, project: options.project });
3102
- if (result)
3103
- process.stdout.write(`${JSON.stringify(result)}\n`);
3104
- }
3105
- catch (error) {
3106
- commandError(error);
3107
- }
3108
- });
3109
- grade
3110
- .command("state")
3111
- .description("Read or update persistent per-document grade pipeline state")
3112
- .requiredOption("--target <target>", "kata or deliverable")
3113
- .option("--project <projectId>", "Project id in specdojo.config.json")
3114
- .option("--path <path>", "Markdown document whose pipeline state is read or updated")
3115
- .option("--status <status>", "Record passed, failed, or complete", requirePipelineStatus)
3116
- .option("--stage <number>", "Current pipeline stage", requirePositiveInteger)
3117
- .option("--stage-total <number>", "Total pipeline stages", requirePositiveInteger, 3)
3118
- .option("--max-failures <number>", "Consecutive failures allowed before reporting only", requirePositiveInteger, 3)
3119
- .option("--run-id <id>", "Job Run id that observed this state")
3120
- .option("--exhausted", "List documents whose consecutive failure limit was reached", false)
3121
- .action((options) => {
3122
- try {
3123
- const target = requireTarget(options.target);
3124
- if (options.exhausted) {
3125
- if (options.path || options.status) {
3126
- throw new Error("--exhausted cannot be combined with --path or --status");
3127
- }
3128
- for (const state of listExhaustedGradePipelineStates({
3129
- target,
3130
- project: options.project,
3131
- })) {
3132
- process.stdout.write(`${state.document}\n`);
3133
- }
3134
- return;
3135
- }
3136
- if (!options.path)
3137
- throw new Error("--path is required unless --exhausted is used");
3138
- if (options.status) {
3139
- if (!options.runId)
3140
- throw new Error("--run-id is required with --status");
3141
- if (!options.stage)
3142
- throw new Error("--stage is required with --status");
3143
- const state = recordGradePipelineStage({
3144
- target,
3145
- project: options.project,
3146
- path: options.path,
3147
- runId: options.runId,
3148
- stage: options.stage,
3149
- stageTotal: options.stageTotal,
3150
- maxFailures: options.maxFailures,
3151
- status: options.status,
3152
- });
3153
- if (state)
3154
- process.stdout.write(`${JSON.stringify(state)}\n`);
3155
- return;
3156
- }
3157
- const state = readGradePipelineState({
3158
- target,
3159
- project: options.project,
3160
- path: options.path,
3161
- });
3162
- if (state)
3163
- process.stdout.write(`${JSON.stringify(state)}\n`);
3164
- }
3165
- catch (error) {
3166
- commandError(error);
3167
- }
3168
- });
3169
- grade
3170
- .command("migrate")
3171
- .description("Move legacy inline grade snapshots and findings to result sidecars")
3172
- .option("--target <target>", "Restrict migration to kata or deliverable", requireTarget)
3173
- .option("--project <projectId>", "Project id in specdojo.config.json")
3174
- .option("--path <path>", "Migrate only this Markdown document (repeatable)", collectPathOption, [])
3175
- .option("--dry-run", "List updates without writing", false)
3176
- .action((options) => {
3177
- try {
3178
- const changed = migrateInlineGrades({
3179
- project: options.project,
3180
- target: options.target,
3181
- paths: options.path,
3182
- dryRun: options.dryRun,
3183
- });
3184
- for (const path of changed) {
3185
- process.stdout.write(`${options.dryRun ? "would update" : "updated"}: ${path}\n`);
3186
- }
3187
- process.stdout.write(`Migrated updates: ${changed.length}\n`);
3188
- }
3189
- catch (error) {
3190
- commandError(error);
3191
- }
3192
- });
16
+ registerGradePlanCommands(grade);
17
+ registerGradeApplyCommands(grade);
18
+ registerGradeInspectionCommands(grade);
3193
19
  }