specdojo 0.2.1 → 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 (242) hide show
  1. package/.github/agents/specdojo-orchestrator.md +165 -0
  2. package/CHANGELOG.md +298 -0
  3. package/README.md +92 -42
  4. package/dist/agent-response.js +20 -0
  5. package/dist/agent.js +4 -4
  6. package/dist/build-command.js +28 -8
  7. package/dist/catalog-build-references.js +144 -0
  8. package/dist/catalog-build-render.js +144 -0
  9. package/dist/catalog-build.js +13 -290
  10. package/dist/catalog-generate.js +6 -9
  11. package/dist/catalog-plan-generate.js +2 -2
  12. package/dist/catalog-plan.js +6 -6
  13. package/dist/catalog-scaffold.js +4 -4
  14. package/dist/catalog.js +2 -2
  15. package/dist/dashboard-exec-records.js +105 -0
  16. package/dist/dashboard-routines.js +255 -0
  17. package/dist/dashboard-shared.js +14 -0
  18. package/dist/dashboard-timeline.js +175 -0
  19. package/dist/dashboard.js +31 -444
  20. package/dist/deliverable-trash.js +3 -3
  21. package/dist/devcontainer-command.js +43 -0
  22. package/dist/devcontainer-scaffold.js +165 -0
  23. package/dist/doc-index.js +3 -3
  24. package/dist/exec-agent-config.js +107 -9
  25. package/dist/exec-agent-git-state.js +18 -0
  26. package/dist/exec-agent-protected-config.js +46 -8
  27. package/dist/exec-commands.js +557 -0
  28. package/dist/exec-core.js +457 -0
  29. package/dist/exec-evidence.js +254 -11
  30. package/dist/exec-handoff.js +336 -0
  31. package/dist/exec-parent-validation.js +317 -43
  32. package/dist/exec-pipeline-state.js +74 -9
  33. package/dist/exec-plans-core.js +693 -0
  34. package/dist/exec-plans-generation.js +206 -0
  35. package/dist/exec-plans-storage.js +131 -0
  36. package/dist/exec-plans.js +3 -1016
  37. package/dist/exec-protection-handoff.js +43 -2
  38. package/dist/exec-provider-scaffold.js +247 -15
  39. package/dist/exec-register-resume.js +65 -19
  40. package/dist/exec-register.js +9 -3
  41. package/dist/exec-repo-integration-git.js +23 -0
  42. package/dist/exec-repo-integration-sync.js +264 -0
  43. package/dist/exec-repo-integration.js +534 -0
  44. package/dist/exec-repo-trace.js +182 -0
  45. package/dist/exec-reporter-output.js +206 -0
  46. package/dist/exec-reporter.js +525 -248
  47. package/dist/exec-results.js +103 -71
  48. package/dist/exec-run-agent-pipeline.js +256 -0
  49. package/dist/exec-run-agent.js +531 -0
  50. package/dist/exec-run-in-place.js +541 -0
  51. package/dist/exec-run-job.js +717 -0
  52. package/dist/exec-run-lifecycle-commands.js +522 -0
  53. package/dist/exec-run-lock.js +110 -107
  54. package/dist/exec-run-mode-shared.js +140 -0
  55. package/dist/exec-run-register-command.js +244 -0
  56. package/dist/exec-run-register-core.js +386 -0
  57. package/dist/exec-run-register-mode.js +206 -0
  58. package/dist/exec-run-register-resume.js +393 -0
  59. package/dist/exec-run-register-state.js +322 -0
  60. package/dist/exec-run-register-worktree.js +509 -0
  61. package/dist/exec-run-schedule-mode.js +294 -0
  62. package/dist/exec-run-schedule-prepare.js +353 -0
  63. package/dist/exec-run-schedule-task.js +572 -0
  64. package/dist/exec-run-shared.js +399 -0
  65. package/dist/exec-run.js +11 -4953
  66. package/dist/exec-shared.js +9 -2
  67. package/dist/exec-slot-lock.js +242 -0
  68. package/dist/exec-task-repos.js +415 -0
  69. package/dist/exec-trial-commands.js +558 -0
  70. package/dist/exec-trial-core.js +371 -0
  71. package/dist/exec-trial.js +2 -895
  72. package/dist/exec-worktree-command.js +87 -43
  73. package/dist/exec-worktree-ops-commit.js +707 -0
  74. package/dist/exec-worktree-ops-lifecycle.js +292 -0
  75. package/dist/exec-worktree-ops-merge.js +303 -0
  76. package/dist/exec-worktree-ops.js +3 -847
  77. package/dist/exec-worktree.js +146 -31
  78. package/dist/exec.js +2 -999
  79. package/dist/frontmatter-namespace.js +2 -2
  80. package/dist/grade-apply.js +734 -0
  81. package/dist/grade-command-apply.js +250 -0
  82. package/dist/grade-command-inspect.js +138 -0
  83. package/dist/grade-command-plan.js +101 -0
  84. package/dist/grade-command-shared.js +68 -0
  85. package/dist/grade-core.js +307 -0
  86. package/dist/grade-markdown.js +274 -0
  87. package/dist/grade-pipeline-state.js +184 -0
  88. package/dist/grade-plan.js +507 -0
  89. package/dist/grade-result.js +133 -5
  90. package/dist/grade-target-discovery.js +265 -0
  91. package/dist/grade-targets.js +432 -0
  92. package/dist/grade.js +14 -2451
  93. package/dist/init-command.js +443 -0
  94. package/dist/job-definition.js +670 -0
  95. package/dist/job.js +64 -578
  96. package/dist/kata-command.js +2 -2
  97. package/dist/orchestrator.js +213 -0
  98. package/dist/register-command-types.js +1 -0
  99. package/dist/register-core.js +363 -0
  100. package/dist/register-create-commands.js +245 -0
  101. package/dist/register-event-merge.js +169 -0
  102. package/dist/register-events.js +4 -4
  103. package/dist/register-item.js +13 -7
  104. package/dist/register-maintenance-commands.js +187 -0
  105. package/dist/register-migration.js +268 -0
  106. package/dist/register-renumber.js +314 -0
  107. package/dist/register-transition-commands.js +248 -0
  108. package/dist/register-update.js +230 -0
  109. package/dist/register-views.js +256 -0
  110. package/dist/register.js +175 -1975
  111. package/dist/review-grade.js +252 -0
  112. package/dist/review-plan.js +114 -4
  113. package/dist/review-types.js +40 -1
  114. package/dist/routine-definition.js +401 -0
  115. package/dist/routine.js +73 -402
  116. package/dist/schedule-approach.js +2 -2
  117. package/dist/schedule-build.js +2 -2
  118. package/dist/schedule-strategy-generate-document.js +273 -0
  119. package/dist/schedule-strategy-generate-scope.js +199 -0
  120. package/dist/schedule-strategy-generate.js +9 -473
  121. package/dist/schedule.js +19 -6
  122. package/dist/specdojo-config.js +465 -20
  123. package/dist/specdojo-gitignore.js +135 -0
  124. package/dist/specdojo.js +6 -0
  125. package/dist/viewpoint-document-kinds-check.js +128 -0
  126. package/dist/yaml-pages.js +4 -4
  127. package/dist/yaml.js +28 -0
  128. package/docs/ja/specdojo/defaults/pm-review-viewpoints.yaml +348 -90
  129. package/docs/ja/specdojo/exec-templates/xep-common-conventions-template.md +51 -17
  130. package/docs/ja/specdojo/exec-templates/xep-fully-guided-template.md +7 -5
  131. package/docs/ja/specdojo/exec-templates/xrp-freeform-template.md +29 -31
  132. package/docs/ja/specdojo/exec-templates/xrp-fully-guided-template.md +34 -55
  133. package/docs/ja/specdojo/exec-templates/xrp-job-template.md +54 -0
  134. package/docs/ja/specdojo/exec-templates/xrp-recipe-guided-template.md +28 -37
  135. package/docs/ja/specdojo/exec-templates/xrp-recipe-maintenance-template.md +29 -34
  136. package/docs/ja/specdojo/exec-templates/xrp-retrofit-template.md +30 -30
  137. package/docs/ja/specdojo/exec-templates/xrp-rulebook-maintenance-template.md +29 -34
  138. package/docs/ja/specdojo/exec-templates/xrp-sample-maintenance-template.md +29 -34
  139. package/docs/ja/specdojo/exec-templates/xrp-template-maintenance-template.md +29 -34
  140. package/docs/ja/specdojo/exec-templates/xrp-template.md +29 -28
  141. package/docs/ja/specdojo/exec-templates/xrr-template.md +11 -9
  142. package/docs/ja/specdojo/guides/docs-editing-guide.md +20 -0
  143. package/docs/ja/specdojo/guides/docs-structure-guide.md +103 -70
  144. package/docs/ja/specdojo/guides/exec-config-guide.md +93 -49
  145. package/docs/ja/specdojo/guides/exec-operation-guide.md +124 -27
  146. package/docs/ja/specdojo/guides/exec-worktree-guide.md +40 -11
  147. package/docs/ja/specdojo/guides/kata-guide.md +4 -4
  148. package/docs/ja/specdojo/guides/orchestrator-operation-guide.md +45 -22
  149. package/docs/ja/specdojo/guides/plan-result-lifecycle-guide.md +1 -1
  150. package/docs/ja/specdojo/guides/practice-system-composition-guide.md +13 -13
  151. package/docs/ja/specdojo/guides/quick-start-guide.md +260 -30
  152. package/docs/ja/specdojo/guides/register-operation-guide.md +31 -14
  153. package/docs/ja/specdojo/guides/release-v0-3-0-migration-guide.md +264 -0
  154. package/docs/ja/specdojo/guides/remote-host-development-guide.md +22 -1
  155. package/docs/ja/specdojo/guides/review-guide.md +195 -158
  156. package/docs/ja/specdojo/guides/routine-operation-guide.md +75 -10
  157. package/docs/ja/specdojo/guides/ryu-guide.md +32 -30
  158. package/docs/ja/specdojo/guides/schedule-design-guide.md +10 -10
  159. package/docs/ja/specdojo/guides/schedule-operation-guide.md +1 -1
  160. package/docs/ja/specdojo/guides/specdojo-overview-guide.md +58 -33
  161. package/docs/ja/specdojo/guides/use-case-guide.md +3 -3
  162. package/docs/ja/specdojo/guides/waza-guide.md +15 -2
  163. package/docs/ja/specdojo/index.md +2 -2
  164. package/docs/ja/specdojo/philosophy/specdojo-philosophy.md +5 -5
  165. package/docs/ja/specdojo/recipes/bps-recipe.md +213 -0
  166. package/docs/ja/specdojo/recipes/pm-members-recipe.md +52 -117
  167. package/docs/ja/specdojo/references/command-reference.md +335 -92
  168. package/docs/ja/specdojo/references/deliverables-reference.md +1 -1
  169. package/docs/ja/specdojo/references/directory-layout-reference.md +13 -9
  170. package/docs/ja/specdojo/references/specdojo-config-reference.md +107 -24
  171. package/docs/ja/specdojo/rulebooks/bps-rulebook.md +132 -220
  172. package/docs/ja/specdojo/rulebooks/br-rulebook.md +6 -44
  173. package/docs/ja/specdojo/rulebooks/cdfd-rulebook.md +2 -0
  174. package/docs/ja/specdojo/rulebooks/dmd-rulebook.md +0 -87
  175. package/docs/ja/specdojo/rulebooks/gl-rulebook.md +61 -39
  176. package/docs/ja/specdojo/rulebooks/ifx-cmd-rulebook.md +0 -87
  177. package/docs/ja/specdojo/rulebooks/ifx-index-rulebook.md +1 -33
  178. package/docs/ja/specdojo/rulebooks/opd-rulebook.md +0 -137
  179. package/docs/ja/specdojo/rulebooks/opr-rulebook.md +0 -247
  180. package/docs/ja/specdojo/rulebooks/otp-rulebook.md +0 -83
  181. package/docs/ja/specdojo/rulebooks/pjr-rulebook.md +4 -2
  182. package/docs/ja/specdojo/rulebooks/pm-members-rulebook.md +78 -150
  183. package/docs/ja/specdojo/rulebooks/pm-roles-rulebook.md +5 -4
  184. package/docs/ja/specdojo/rulebooks/sch-rulebook.md +1 -1
  185. package/docs/ja/specdojo/rulebooks/stsd-mermaid-rulebook.md +0 -11
  186. package/docs/ja/specdojo/rulebooks/stsd-rulebook.md +0 -61
  187. package/docs/ja/specdojo/rulebooks/tml-rulebook.md +2 -47
  188. package/docs/ja/specdojo/samples/bps-sample.md +74 -21
  189. package/docs/ja/specdojo/samples/gl-sample.yaml +17 -1
  190. package/docs/ja/specdojo/samples/ifx-index-sample.yaml +28 -0
  191. package/docs/ja/specdojo/samples/pm-members-sample.yaml +2 -67
  192. package/docs/ja/specdojo/samples/pm-organization-sample.md +8 -7
  193. package/docs/ja/specdojo/samples/pm-raci-sample.md +1 -1
  194. package/docs/ja/specdojo/samples/tml-sample.yaml +40 -0
  195. package/docs/ja/specdojo/standards/document-metadata-standard.md +21 -16
  196. package/docs/ja/specdojo/standards/id-and-file-naming-standard.md +14 -14
  197. package/docs/ja/specdojo/standards/job-definition-standard.md +37 -17
  198. package/docs/ja/specdojo/standards/people-and-organization-definition-standard.md +37 -32
  199. package/docs/ja/specdojo/standards/philosophy-authoring-standard.md +1 -1
  200. package/docs/ja/specdojo/standards/rulebook-authoring-standard.md +21 -11
  201. package/docs/ja/specdojo/templates/agent-members-template.yaml +25 -0
  202. package/docs/ja/specdojo/templates/bps-template.md +91 -0
  203. package/docs/ja/specdojo/templates/pm-members-template.yaml +2 -59
  204. package/docs/specdojo/schemas/v1/agent-members.schema.yaml +76 -0
  205. package/docs/specdojo/schemas/v1/exec-common.schema.yaml +4 -2
  206. package/docs/specdojo/schemas/v1/exec-defaults.schema.yaml +55 -2
  207. package/docs/specdojo/schemas/v1/exec-evidence.schema.yaml +93 -6
  208. package/docs/specdojo/schemas/v1/exec-reporter-output.schema.yaml +27 -78
  209. package/docs/specdojo/schemas/v1/gl.schema.yaml +87 -0
  210. package/docs/specdojo/schemas/v1/grade-result.schema.yaml +33 -0
  211. package/docs/specdojo/schemas/v1/job-run.schema.yaml +27 -0
  212. package/docs/specdojo/schemas/v1/job.schema.yaml +25 -0
  213. package/docs/specdojo/schemas/v1/pipeline-state.schema.yaml +49 -1
  214. package/docs/specdojo/schemas/v1/pm-members.schema.yaml +9 -169
  215. package/docs/specdojo/schemas/v1/pm-review-viewpoints.schema.yaml +100 -10
  216. package/docs/specdojo/schemas/v1/register-item-frontmatter.schema.yaml +13 -0
  217. package/docs/specdojo/schemas/v1/routine-run.schema.yaml +3 -0
  218. package/docs/specdojo/schemas/v1/routine.schema.yaml +7 -0
  219. package/docs/specdojo/schemas/v1/specdojo-config.schema.yaml +110 -0
  220. package/package.json +17 -12
  221. package/templates/antigravity/README.md +29 -4
  222. package/templates/antigravity/{pm-members-snippet.yaml → agent-members-snippet.yaml} +8 -2
  223. package/templates/antigravity/exec-defaults-snippet.yaml +10 -7
  224. package/templates/antigravity/orchestrator.md +18 -7
  225. package/templates/antigravity/settings.global.json +55 -0
  226. package/templates/claude/agents/claude-executor.md +14 -0
  227. package/templates/claude/agents/claude-reporter.md +16 -0
  228. package/templates/claude/agents/specdojo-orchestrator.md +18 -7
  229. package/templates/claude/settings.edit.json +27 -1
  230. package/templates/codex/README.md +5 -4
  231. package/templates/codex/agents/specdojo-orchestrator.toml +18 -7
  232. package/templates/codex/orchestrator.md +18 -7
  233. package/templates/copilot/README.md +7 -5
  234. package/templates/copilot/{pm-members-snippet.yaml → agent-members-snippet.yaml} +4 -2
  235. package/templates/devcontainer/devcontainer.json +27 -0
  236. package/templates/devcontainer/emacs/init.el +88 -0
  237. package/templates/devcontainer/post-create.sh +62 -0
  238. package/templates/init-agent-members.yaml +200 -0
  239. package/templates/init-exec-defaults.yaml +74 -0
  240. package/templates/opencode/agents/specdojo-orchestrator.md +18 -7
  241. package/docs/ja/specdojo/exec-templates/xrp-viewpoint-detail-template.md +0 -7
  242. package/docs/ja/specdojo/exec-templates/xrr-viewpoint-detail-template.md +0 -7
@@ -0,0 +1,307 @@
1
+ import { createHash } from "node:crypto";
2
+ import { dump, load } from "./yaml.js";
3
+ import remarkParse from "remark-parse";
4
+ import { unified } from "unified";
5
+ import { viewpointAppliesToDocument } from "./review-plan.js";
6
+ import { gradeContentHash } from "./grade-result.js";
7
+ export const GRADE_TARGETS = ["kata", "deliverable"];
8
+ export 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;
9
+ export const KATA_DIRS = ["rulebooks", "recipes", "samples", "templates"];
10
+ export const KATA_REFERENCE_EXTENSIONS = new Set([".md", ".yaml", ".yml", ".json"]);
11
+ export const KATA_REFERENCE_FIELDS = ["rulebook", "recipe", "sample", "template"];
12
+ export const CRITERION_ID_RE = /^DC-[0-9]{3,}$/;
13
+ export const CRITERION_STATUSES = ["satisfied", "unsatisfied"];
14
+ export const DONE_CRITERIA_SCHEMA = "docs/specdojo/schemas/v1/grade-done-criteria.schema.yaml";
15
+ const GRADE_PLACEHOLDER = "__SPECDOJO_GRADE_FLOW_PLACEHOLDER__";
16
+ const GRADE_FINDINGS_PLACEHOLDER = "__SPECDOJO_GRADE_FINDINGS_FLOW_PLACEHOLDER__";
17
+ const GRADE_UNSATISFIED_PLACEHOLDER = "__SPECDOJO_GRADE_UNSATISFIED_BLOCK_PLACEHOLDER__";
18
+ export const GRADE_PLAN_EMBEDDED_DOCUMENT_CHARACTER_LIMIT = 100_000;
19
+ export const SEVERITY_LEVEL_CAP = {
20
+ blocker: 0,
21
+ major: 2,
22
+ minor: 3,
23
+ note: 4,
24
+ };
25
+ export function preservePreviousFindingSeverities(body, viewpoints) {
26
+ const previousByMessage = new Map();
27
+ for (const finding of previousGradeFindings(body)) {
28
+ const message = sanitizeCommentText(finding.message);
29
+ const previous = previousByMessage.get(message);
30
+ if (previous === undefined ||
31
+ SEVERITY_LEVEL_CAP[finding.severity] < SEVERITY_LEVEL_CAP[previous]) {
32
+ previousByMessage.set(message, finding.severity);
33
+ }
34
+ }
35
+ return viewpoints.map((viewpoint) => {
36
+ const findings = (viewpoint.findings ?? []).map((finding) => {
37
+ const previous = previousByMessage.get(sanitizeCommentText(finding.message));
38
+ return previous !== undefined &&
39
+ SEVERITY_LEVEL_CAP[previous] < SEVERITY_LEVEL_CAP[finding.severity]
40
+ ? { ...finding, severity: previous }
41
+ : { ...finding };
42
+ });
43
+ return {
44
+ ...viewpoint,
45
+ findings,
46
+ level: Math.min(viewpoint.level, levelCapForFindings(findings)),
47
+ };
48
+ });
49
+ }
50
+ export function preserveStoredFindingSeverities(previous, viewpoints) {
51
+ const previousByMessage = new Map();
52
+ for (const finding of previous?.findings ?? []) {
53
+ const message = sanitizeCommentText(finding.message);
54
+ const stored = previousByMessage.get(message);
55
+ if (stored === undefined || SEVERITY_LEVEL_CAP[finding.severity] < SEVERITY_LEVEL_CAP[stored]) {
56
+ previousByMessage.set(message, finding.severity);
57
+ }
58
+ }
59
+ return viewpoints.map((viewpoint) => {
60
+ const findings = (viewpoint.findings ?? []).map((finding) => {
61
+ const stored = previousByMessage.get(sanitizeCommentText(finding.message));
62
+ return stored !== undefined &&
63
+ SEVERITY_LEVEL_CAP[stored] < SEVERITY_LEVEL_CAP[finding.severity]
64
+ ? { ...finding, severity: stored }
65
+ : { ...finding };
66
+ });
67
+ return {
68
+ ...viewpoint,
69
+ findings,
70
+ level: Math.min(viewpoint.level, levelCapForFindings(findings)),
71
+ };
72
+ });
73
+ }
74
+ export function levelCapForFindings(findings) {
75
+ const majorCount = findings.filter((finding) => finding.severity === "major").length;
76
+ const severityCap = findings.reduce((current, finding) => Math.min(current, SEVERITY_LEVEL_CAP[finding.severity]), 4);
77
+ return majorCount >= 2 ? Math.min(severityCap, 1) : severityCap;
78
+ }
79
+ export function correctViewpointLevels(viewpoints) {
80
+ const corrections = [];
81
+ const corrected = viewpoints.map((viewpoint) => {
82
+ const cap = levelCapForFindings(viewpoint.findings ?? []);
83
+ const correctedLevel = Math.min(viewpoint.level, cap);
84
+ if (correctedLevel !== viewpoint.level) {
85
+ corrections.push({
86
+ viewpoint: viewpoint.id,
87
+ original_level: viewpoint.level,
88
+ corrected_level: correctedLevel,
89
+ });
90
+ }
91
+ return { ...viewpoint, level: correctedLevel };
92
+ });
93
+ return { viewpoints: corrected, corrections };
94
+ }
95
+ export function isRecord(value) {
96
+ return typeof value === "object" && value !== null && !Array.isArray(value);
97
+ }
98
+ export function parseMarkdown(content, path) {
99
+ const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
100
+ if (!match)
101
+ throw new Error(`${path}: Markdown frontmatter is required`);
102
+ const parsed = load(match[1]);
103
+ if (!isRecord(parsed) || !isRecord(parsed.specdojo)) {
104
+ throw new Error(`${path}: frontmatter must contain a specdojo mapping`);
105
+ }
106
+ return { data: parsed, body: (match[2] ?? "").replace(/^(?:\r?\n)+/, "") };
107
+ }
108
+ function serializeGrade(grade) {
109
+ const gradeForDump = structuredClone(grade);
110
+ const findings = isRecord(gradeForDump.findings) ? gradeForDump.findings : undefined;
111
+ if (findings)
112
+ gradeForDump.findings = GRADE_FINDINGS_PLACEHOLDER;
113
+ const doneCriteria = isRecord(gradeForDump.done_criteria)
114
+ ? gradeForDump.done_criteria
115
+ : undefined;
116
+ const unsatisfied = doneCriteria && isRecord(doneCriteria.unsatisfied) ? doneCriteria.unsatisfied : undefined;
117
+ if (doneCriteria && unsatisfied)
118
+ doneCriteria.unsatisfied = GRADE_UNSATISFIED_PLACEHOLDER;
119
+ let dumped = dump({ grade: gradeForDump },
120
+ // categories / viewpoints の各値だけをフロー化する。grade 全体や各 collection
121
+ // までフロー化すると一行が長くなり、差分も読みづらくなる。
122
+ { lineWidth: 120, noRefs: true, flowLevel: 3, quoteStyle: "double" }).trimEnd();
123
+ if (findings) {
124
+ const inlineFindings = dump(findings, {
125
+ lineWidth: -1,
126
+ noRefs: true,
127
+ flowLevel: 0,
128
+ }).trimEnd();
129
+ dumped = dumped.replace(GRADE_FINDINGS_PLACEHOLDER, inlineFindings);
130
+ }
131
+ if (unsatisfied) {
132
+ // 未充足条件は viewpoints と同じく「条件ごとに1行、値はフロー」で記録する。
133
+ // 条件数が増えても1行が伸びず、Prettier の整形後も同じ形を保つ。
134
+ const blockUnsatisfied = dump(unsatisfied, {
135
+ lineWidth: -1,
136
+ noRefs: true,
137
+ flowLevel: 1,
138
+ })
139
+ .trimEnd()
140
+ .split("\n")
141
+ .map((line) => ` ${line}`)
142
+ .join("\n");
143
+ dumped = dumped.replace(` unsatisfied: ${GRADE_UNSATISFIED_PLACEHOLDER}`, ` unsatisfied:\n${blockUnsatisfied}`);
144
+ }
145
+ // js-yaml は `{score: 100}`、Prettier は `{ score: 100 }` と出力する。
146
+ // 最初から Prettier の形へ合わせ、整形と再評価の往復で差分が出ないようにする。
147
+ return dumped.replace(/^(\s+[^:\n]+: )\{([^{}\n]*)\}$/gm, "$1{ $2 }");
148
+ }
149
+ export function serializeMarkdown(document) {
150
+ const dataForDump = structuredClone(document.data);
151
+ const specdojo = isRecord(dataForDump.specdojo) ? dataForDump.specdojo : undefined;
152
+ const grade = specdojo && isRecord(specdojo.grade) ? specdojo.grade : undefined;
153
+ if (!specdojo || !grade) {
154
+ return `---\n${dump(dataForDump, { lineWidth: 120, noRefs: true }).trimEnd()}\n---\n\n${document.body.replace(/^\n+/, "")}`;
155
+ }
156
+ specdojo.grade = GRADE_PLACEHOLDER;
157
+ const gradeBlock = serializeGrade(grade)
158
+ .split("\n")
159
+ .map((line) => ` ${line}`)
160
+ .join("\n");
161
+ const frontmatter = dump(dataForDump, { lineWidth: 120, noRefs: true })
162
+ .trimEnd()
163
+ .replace(` grade: ${GRADE_PLACEHOLDER}`, gradeBlock);
164
+ return `---\n${frontmatter}\n---\n\n${document.body.replace(/^\n+/, "")}`;
165
+ }
166
+ export function withoutFindingComments(body) {
167
+ return body.replace(FINDING_RE, "");
168
+ }
169
+ function normalizeContentForHash(body) {
170
+ return body
171
+ .replace(/\r\n?/g, "\n")
172
+ .replace(/[ \t]+$/gm, "")
173
+ .replace(/\n{3,}/g, "\n\n");
174
+ }
175
+ function previousGradeFindings(body) {
176
+ return [...body.matchAll(FINDING_RE)].map((match) => ({
177
+ severity: match[2],
178
+ rule: match[3],
179
+ ...(match[4] ? { line: Number(match[4]) } : {}),
180
+ message: match[5].trim(),
181
+ }));
182
+ }
183
+ // 移行前のインライン grade を読み取る互換 API だけが使用する旧ハッシュ。
184
+ export function legacyInlineContentHash(document) {
185
+ const cloned = structuredClone(document.data);
186
+ const specdojo = isRecord(cloned.specdojo) ? cloned.specdojo : {};
187
+ delete specdojo.grade;
188
+ return createHash("sha256")
189
+ .update(dump(cloned, { sortKeys: true, noRefs: true, lineWidth: -1 }))
190
+ .update("\n")
191
+ .update(normalizeContentForHash(withoutFindingComments(document.body)))
192
+ .digest("hex");
193
+ }
194
+ function stableContentHash(document) {
195
+ return gradeContentHash(serializeMarkdown(document));
196
+ }
197
+ // pipeline 状態は成果物そのもののハッシュで識別する。grade apply は成果物を変更しないため、
198
+ // grade / finding や空行を除外する正規化は不要である。
199
+ export function pipelineContentHash(document) {
200
+ return stableContentHash(document);
201
+ }
202
+ export function sanitizeCommentText(value) {
203
+ return (value
204
+ .replace(/--+/g, "—")
205
+ .replace(/[\r\n]+/g, " ")
206
+ // 山括弧プレースホルダは HTML コメント内でもプロジェクトの lint が検知する。
207
+ // コメント内ではインラインコードが機能しないため、全角へ置き換えて退避する。
208
+ .replace(/</g, "<")
209
+ .replace(/>/g, ">")
210
+ .trim());
211
+ }
212
+ function findingComment(finding, rule) {
213
+ return `<!-- specdojo:finding id=${finding.id} severity=${finding.severity} rule=${rule} line=${finding.line ?? 1} ${sanitizeCommentText(finding.message)} -->`;
214
+ }
215
+ function markdownBlockRanges(body) {
216
+ const root = unified().use(remarkParse).parse(body);
217
+ return root.children.flatMap((node) => {
218
+ const startLine = node.position?.start.line;
219
+ const endLine = node.position?.end.line;
220
+ return startLine === undefined || endLine === undefined
221
+ ? []
222
+ : [
223
+ {
224
+ startLine,
225
+ endLine,
226
+ isHtmlComment: node.type === "html" &&
227
+ "value" in node &&
228
+ typeof node.value === "string" &&
229
+ /^\s*<!--[\s\S]*-->\s*$/.test(node.value),
230
+ },
231
+ ];
232
+ });
233
+ }
234
+ function safeFindingInsertionIndex(blocks, lines, requestedIndex) {
235
+ const requestedLine = requestedIndex + 1;
236
+ const containingIndex = blocks.findIndex((block) => block.startLine <= requestedLine && requestedLine <= block.endLine);
237
+ if (containingIndex === -1)
238
+ return requestedIndex;
239
+ let insertionStartLine = blocks[containingIndex].startLine;
240
+ for (let index = containingIndex - 1; index >= 0; index -= 1) {
241
+ const candidate = blocks[index];
242
+ if (!candidate.isHtmlComment)
243
+ break;
244
+ const linesBetween = lines.slice(candidate.endLine, insertionStartLine - 1);
245
+ if (linesBetween.some((line) => line.trim() !== ""))
246
+ break;
247
+ insertionStartLine = candidate.startLine;
248
+ }
249
+ return insertionStartLine - 1;
250
+ }
251
+ export function insertFindings(body, viewpoints) {
252
+ const bodyWithoutFindings = withoutFindingComments(body);
253
+ const lines = bodyWithoutFindings.split("\n");
254
+ const blocks = markdownBlockRanges(bodyWithoutFindings);
255
+ const insertions = new Map();
256
+ const usedIds = new Set(viewpoints.flatMap((viewpoint) => (viewpoint.findings ?? []).flatMap((finding) => (finding.id ? [finding.id] : []))));
257
+ let sequence = 0;
258
+ for (const viewpoint of viewpoints) {
259
+ for (const finding of viewpoint.findings ?? []) {
260
+ let id = finding.id?.trim();
261
+ if (!id) {
262
+ do {
263
+ sequence += 1;
264
+ id = `F${String(sequence).padStart(3, "0")}`;
265
+ } while (usedIds.has(id));
266
+ usedIds.add(id);
267
+ }
268
+ const requestedIndex = Math.max(0, Math.min(lines.length, (finding.line ?? 1) - 1));
269
+ // finding は対象行を含む最上位 Markdown ブロックの直前へ置く。これにより、
270
+ // 入れ子リスト、表、引用、コードフェンス、複数行段落の内部を分断しない。
271
+ // 対象行そのものはコメントの line 属性に残す。
272
+ const index = safeFindingInsertionIndex(blocks, lines, requestedIndex);
273
+ const existing = insertions.get(index) ?? [];
274
+ existing.push(findingComment({ ...finding, id }, viewpoint.id));
275
+ insertions.set(index, existing);
276
+ }
277
+ }
278
+ const output = [];
279
+ for (let index = 0; index <= lines.length; index += 1) {
280
+ const comments = insertions.get(index) ?? [];
281
+ // 直前が空行の場合は連続空行になるため詰める。agent が本文末尾を超える行番号を
282
+ // 指定すると、末尾の空行の後ろへコメントが並び markdownlint の MD012 に触れる。
283
+ if (comments.length > 0) {
284
+ while (output.length > 0 && output[output.length - 1].trim() === "")
285
+ output.pop();
286
+ if (output.length > 0)
287
+ output.push("");
288
+ }
289
+ output.push(...comments);
290
+ if (index < lines.length)
291
+ output.push(lines[index]);
292
+ }
293
+ return (output
294
+ .join("\n")
295
+ .replace(/^\n+/, "")
296
+ .replace(/\n{3,}/g, "\n\n")
297
+ // grade apply の出力だけで lint 可能な状態にする。走査は文書ごとの apply 間に
298
+ // Prettier を実行しないため、入力由来の末尾空行をここで1改行へ正規化する。
299
+ .replace(/(?:\n[ \t]*)*$/, "\n"));
300
+ }
301
+ export function gradedViewpoints(doc, target, metadata) {
302
+ return (doc.viewpoints ?? []).filter((viewpoint) => (viewpoint.grade_targets === undefined || viewpoint.grade_targets.includes(target)) &&
303
+ viewpointAppliesToDocument(viewpoint, metadata));
304
+ }
305
+ export function agentViewpoints(doc, target, metadata) {
306
+ return gradedViewpoints(doc, target, metadata).filter((viewpoint) => viewpoint.evaluation === "referential" || viewpoint.evaluation === "discretionary");
307
+ }
@@ -0,0 +1,274 @@
1
+ import { readFileSync, writeFileSync } from "node:fs";
2
+ import { FINDING_RE, insertFindings, isRecord, legacyInlineContentHash, parseMarkdown, preservePreviousFindingSeverities, serializeMarkdown, withoutFindingComments, } from "./grade-core.js";
3
+ import { discoverGradeTargets } from "./grade-target-discovery.js";
4
+ import { applicableDoneCriteria, deterministicResults } from "./grade-plan.js";
5
+ import { gradeContentHash, gradeResultPath, markdownDocumentId, readGradeResultForDocument, resolveGradeResultsDirectory, validateGradeResult, writeGradeResult, } from "./grade-result.js";
6
+ import { assertRubric, relativePathFromRoot, repoRelativePath, resolveSafeMarkdownPath, } from "./grade-targets.js";
7
+ import { specdojoRootDir } from "./specdojo-config.js";
8
+ export function scoreDocument(input, rubric, doc, target) {
9
+ const definitions = new Map((doc.viewpoints ?? []).map((viewpoint) => [viewpoint.id, viewpoint]));
10
+ const categoryLevels = new Map();
11
+ const counts = { blocker: 0, major: 0, minor: 0, note: 0 };
12
+ const viewpointOutput = {};
13
+ for (const result of input.viewpoints) {
14
+ const definition = definitions.get(result.id);
15
+ const values = categoryLevels.get(definition.category) ?? [];
16
+ values.push(result.level);
17
+ categoryLevels.set(definition.category, values);
18
+ viewpointOutput[result.id] = { level: result.level, score: result.level * 25 };
19
+ for (const finding of result.findings ?? [])
20
+ counts[finding.severity] += 1;
21
+ }
22
+ const categories = {};
23
+ let weighted = 0;
24
+ let totalWeight = 0;
25
+ for (const [category, levels] of categoryLevels) {
26
+ const score = Math.round((levels.reduce((sum, level) => sum + level, 0) / levels.length) * 25);
27
+ categories[category] = { score };
28
+ const weight = rubric.weights[target][category] ?? 0;
29
+ weighted += score * weight;
30
+ totalWeight += weight;
31
+ }
32
+ const score = totalWeight > 0 ? Math.round(weighted / totalWeight) : 0;
33
+ const verdict = counts.blocker > 0
34
+ ? "fail"
35
+ : counts.major > 0 || score < rubric.pass_score
36
+ ? "needs-work"
37
+ : "pass";
38
+ return { score, verdict, categories, viewpoints: viewpointOutput, findings: counts };
39
+ }
40
+ // 比較リファレンスは ID で保存する。パスで保存すると文書を移動したときに参照が壊れる。
41
+ // 引数にはパスと ID のどちらも渡せる。パスの場合は Frontmatter の id を読み取る。
42
+ export function resolveGradeReferenceId(pathOrId) {
43
+ const trimmed = pathOrId.trim();
44
+ if (!trimmed.endsWith(".md"))
45
+ return trimmed;
46
+ const absolute = resolveSafeMarkdownPath(trimmed);
47
+ const document = parseMarkdown(readFileSync(absolute, "utf8"), repoRelativePath(absolute));
48
+ const metadata = document.data.specdojo;
49
+ if (!isRecord(metadata) || typeof metadata.id !== "string" || metadata.id.length === 0) {
50
+ throw new Error(`${repoRelativePath(absolute)}: reference document has no specdojo.id`);
51
+ }
52
+ return metadata.id;
53
+ }
54
+ // score と done_criteria の充足は別の軸として扱う。verdict は score と finding だけで決め、
55
+ // 充足状況は要約として並記する。score の閾値が充足判定を上書きせず、その逆も行わない。
56
+ export function summarizeDoneCriteria(definitions, results, detailRef) {
57
+ const resultById = new Map(results.map((result) => [result.id, result]));
58
+ const unsatisfied = {};
59
+ let satisfied = 0;
60
+ for (const criterion of definitions) {
61
+ const result = resultById.get(criterion.id);
62
+ if (result?.status === "satisfied")
63
+ satisfied += 1;
64
+ else
65
+ unsatisfied[criterion.id] = [...criterion.roles];
66
+ }
67
+ return {
68
+ satisfied,
69
+ total: definitions.length,
70
+ ...(Object.keys(unsatisfied).length > 0 ? { unsatisfied } : {}),
71
+ detail_ref: detailRef,
72
+ };
73
+ }
74
+ export function gradeMarkdownDocument(opts) {
75
+ const document = parseMarkdown(opts.content, opts.path);
76
+ const specdojo = document.data.specdojo;
77
+ const agentResults = preservePreviousFindingSeverities(document.body, opts.input.viewpoints);
78
+ const evaluated = {
79
+ ...opts.input,
80
+ viewpoints: [...agentResults, ...deterministicResults(document, opts.viewpoints, opts.target)],
81
+ };
82
+ const rubric = assertRubric(opts.viewpoints);
83
+ const summary = scoreDocument(evaluated, rubric, opts.viewpoints, opts.target);
84
+ const body = insertFindings(document.body, evaluated.viewpoints);
85
+ const gradedAt = (opts.now ?? new Date()).toISOString();
86
+ const contentHash = legacyInlineContentHash({ data: document.data, body });
87
+ const criteriaResults = opts.target === "deliverable" && opts.doneCriteria && opts.input.done_criteria
88
+ ? opts.input.done_criteria
89
+ : undefined;
90
+ const applicableCriteriaDefinitions = opts.doneCriteria
91
+ ? applicableDoneCriteria(opts.doneCriteria.definitions, opts.viewpoints, specdojo)
92
+ : undefined;
93
+ specdojo.grade = {
94
+ rubric: rubric.id,
95
+ ...(opts.reference ? { reference: resolveGradeReferenceId(opts.reference) } : {}),
96
+ target: opts.target,
97
+ verdict: summary.verdict,
98
+ score: summary.score,
99
+ graded_at: gradedAt,
100
+ graded_by: opts.gradedBy,
101
+ content_hash: contentHash,
102
+ categories: summary.categories,
103
+ viewpoints: summary.viewpoints,
104
+ findings: summary.findings,
105
+ ...(criteriaResults && opts.doneCriteria && applicableCriteriaDefinitions
106
+ ? {
107
+ done_criteria: summarizeDoneCriteria(applicableCriteriaDefinitions, criteriaResults, opts.doneCriteria.detailRef),
108
+ }
109
+ : {}),
110
+ };
111
+ const content = serializeMarkdown({ data: document.data, body });
112
+ if (!criteriaResults || !opts.doneCriteria)
113
+ return { content };
114
+ const resultById = new Map(criteriaResults.map((result) => [result.id, result]));
115
+ const criteria = opts.doneCriteria.definitions.map((criterion) => {
116
+ const result = resultById.get(criterion.id);
117
+ return {
118
+ ...criterion,
119
+ status: result?.status ?? "unsatisfied",
120
+ ...(result?.reason ? { reason: result.reason } : {}),
121
+ };
122
+ });
123
+ const satisfied = criteria.filter((criterion) => criterion.status === "satisfied").length;
124
+ return {
125
+ content,
126
+ detail: {
127
+ id: opts.doneCriteria.detailRef,
128
+ document: typeof specdojo.id === "string" ? specdojo.id : opts.path,
129
+ path: opts.path,
130
+ graded_at: gradedAt,
131
+ graded_by: opts.gradedBy,
132
+ content_hash: contentHash,
133
+ summary: { satisfied, unsatisfied: criteria.length - satisfied, total: criteria.length },
134
+ criteria,
135
+ },
136
+ };
137
+ }
138
+ export function gradeMarkdownContent(opts) {
139
+ return gradeMarkdownDocument(opts).content;
140
+ }
141
+ export function validateGradedDocument(path) {
142
+ const absolute = resolveSafeMarkdownPath(path);
143
+ const rel = repoRelativePath(absolute);
144
+ return validateGradedMarkdown(readFileSync(absolute, "utf8"), rel);
145
+ }
146
+ export function validateGradeResultForDocument(opts) {
147
+ const absolute = resolveSafeMarkdownPath(opts.path);
148
+ const rel = repoRelativePath(absolute);
149
+ const content = readFileSync(absolute, "utf8");
150
+ const result = readGradeResultForDocument({ documentPath: rel, project: opts.project });
151
+ if (!result)
152
+ return [];
153
+ return validateGradeResult(result, content, rel, opts.target);
154
+ }
155
+ export function validateGradedMarkdown(content, path) {
156
+ const document = parseMarkdown(content, path);
157
+ const specdojo = document.data.specdojo;
158
+ const grade = isRecord(specdojo.grade) ? specdojo.grade : null;
159
+ if (!grade)
160
+ return [`${path}: specdojo.grade is missing`];
161
+ const findings = isRecord(grade.findings) ? grade.findings : {};
162
+ const actual = { blocker: 0, major: 0, minor: 0, note: 0 };
163
+ for (const match of document.body.matchAll(FINDING_RE))
164
+ actual[match[2]] += 1;
165
+ const errors = [];
166
+ for (const severity of Object.keys(actual)) {
167
+ if (findings[severity] !== actual[severity])
168
+ errors.push(`${path}: findings.${severity}=${String(findings[severity])}, comments=${actual[severity]}`);
169
+ }
170
+ if (grade.content_hash !== legacyInlineContentHash(document))
171
+ errors.push(`${path}: content changed after the last grade`);
172
+ return errors;
173
+ }
174
+ export function migrateInlineGrades(opts) {
175
+ const rootDir = specdojoRootDir();
176
+ const candidates = opts.paths && opts.paths.length > 0
177
+ ? opts.paths.map((path) => resolveSafeMarkdownPath(path, rootDir))
178
+ : [
179
+ ...(opts.target !== "deliverable"
180
+ ? discoverGradeTargets({ target: "kata", project: opts.project }, rootDir)
181
+ : []),
182
+ ...(opts.target !== "kata"
183
+ ? discoverGradeTargets({ target: "deliverable", project: opts.project }, rootDir)
184
+ : []),
185
+ ];
186
+ const resultsDirectory = resolveGradeResultsDirectory(opts.project, rootDir);
187
+ const changed = [];
188
+ for (const absolute of candidates) {
189
+ const rel = relativePathFromRoot(absolute, rootDir);
190
+ const current = readFileSync(absolute, "utf8");
191
+ if (!current.includes("specdojo:finding") && !/^ grade:\s*$/m.test(current))
192
+ continue;
193
+ let document;
194
+ try {
195
+ document = parseMarkdown(current, rel);
196
+ }
197
+ catch {
198
+ continue;
199
+ }
200
+ const specdojo = document.data.specdojo;
201
+ const legacyGrade = isRecord(specdojo.grade) ? structuredClone(specdojo.grade) : undefined;
202
+ const legacyTarget = legacyGrade?.target;
203
+ const target = legacyTarget === "kata" || legacyTarget === "deliverable"
204
+ ? legacyTarget
205
+ : rel.startsWith("docs/ja/specdojo/")
206
+ ? "kata"
207
+ : "deliverable";
208
+ if (opts.target && target !== opts.target)
209
+ continue;
210
+ const legacyFindings = [...document.body.matchAll(FINDING_RE)].map((match) => ({
211
+ id: match[1],
212
+ severity: match[2],
213
+ rule: match[3],
214
+ line: match[4] ? Number(match[4]) : 1,
215
+ message: match[5].trim(),
216
+ }));
217
+ delete specdojo.grade;
218
+ document.body = withoutFindingComments(document.body)
219
+ .replace(/\n{3,}/g, "\n\n")
220
+ .replace(/(?:\n[ \t]*)*$/, "\n");
221
+ const cleaned = serializeMarkdown(document);
222
+ if (cleaned !== current) {
223
+ changed.push(rel);
224
+ if (!opts.dryRun)
225
+ writeFileSync(absolute, cleaned, "utf8");
226
+ }
227
+ if (!legacyGrade)
228
+ continue;
229
+ const documentId = markdownDocumentId(cleaned, rel);
230
+ const bodyLines = document.body.split(/\r?\n/);
231
+ const findings = legacyFindings.map((finding) => ({
232
+ ...finding,
233
+ anchor: bodyLines[Math.min(bodyLines.length, finding.line) - 1]?.trim() ?? "",
234
+ message_ja: finding.message,
235
+ }));
236
+ const counts = { blocker: 0, major: 0, minor: 0, note: 0 };
237
+ for (const finding of findings)
238
+ counts[finding.severity] += 1;
239
+ if (typeof legacyGrade.rubric !== "string" ||
240
+ (legacyGrade.verdict !== "pass" &&
241
+ legacyGrade.verdict !== "needs-work" &&
242
+ legacyGrade.verdict !== "fail") ||
243
+ !Number.isSafeInteger(legacyGrade.score) ||
244
+ typeof legacyGrade.graded_at !== "string" ||
245
+ typeof legacyGrade.graded_by !== "string" ||
246
+ !isRecord(legacyGrade.categories) ||
247
+ !isRecord(legacyGrade.viewpoints)) {
248
+ throw new Error(`${rel}: legacy specdojo.grade is invalid`);
249
+ }
250
+ const result = {
251
+ version: 1,
252
+ document: documentId,
253
+ path: rel,
254
+ target,
255
+ rubric: legacyGrade.rubric,
256
+ ...(typeof legacyGrade.reference === "string" ? { reference: legacyGrade.reference } : {}),
257
+ verdict: legacyGrade.verdict,
258
+ score: legacyGrade.score,
259
+ graded_at: legacyGrade.graded_at,
260
+ graded_by: legacyGrade.graded_by,
261
+ content_hash: gradeContentHash(cleaned),
262
+ categories: legacyGrade.categories,
263
+ viewpoints: legacyGrade.viewpoints,
264
+ finding_counts: counts,
265
+ findings,
266
+ ...(isRecord(legacyGrade.done_criteria) ? { done_criteria: legacyGrade.done_criteria } : {}),
267
+ };
268
+ const resultPath = gradeResultPath(resultsDirectory, documentId);
269
+ if (writeGradeResult(resultPath, result, opts.dryRun)) {
270
+ changed.push(repoRelativePath(resultPath));
271
+ }
272
+ }
273
+ return changed;
274
+ }