orkeon-code 0.0.0-stage → 1.0.0-rc.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 (423) hide show
  1. package/.orkeon-version +1 -0
  2. package/LICENSE.md +21 -0
  3. package/NOTICE.md +17 -0
  4. package/README.fr.md +169 -0
  5. package/README.md +162 -2
  6. package/config/appsettings.anthropic.example.json +77 -0
  7. package/config/appsettings.example.json +71 -0
  8. package/config/appsettings.jev.example.json +128 -0
  9. package/config/appsettings.kev.example.json +130 -0
  10. package/config/appsettings.liquid.example.json +129 -0
  11. package/config/appsettings.ollama-whisper.example.json +92 -0
  12. package/config/appsettings.ollama.example.json +70 -0
  13. package/config/appsettings.whisper.example.json +31 -0
  14. package/mcp/whisper/README.md +293 -0
  15. package/mcp/whisper/pyproject.toml +32 -0
  16. package/mcp/whisper/uv.lock +1641 -0
  17. package/mcp/whisper/whisper_mcp.py +1053 -0
  18. package/orkeon-code +897 -0
  19. package/orkeon-code.mjs +71 -0
  20. package/orkeon-code.ps1 +837 -0
  21. package/package.json +57 -4
  22. package/scripts/install.ps1 +156 -0
  23. package/scripts/install.sh +148 -0
  24. package/scripts/session-start.ork.ts +90 -0
  25. package/scripts/session-start.sh +74 -0
  26. package/scripts/setup-fixture.sh +88 -0
  27. package/src/commands/.orkeon/orkeon-cli.d.ts +562 -0
  28. package/src/commands/_lib/args.ts +193 -0
  29. package/src/commands/_lib/dev/dev-batches.ts +368 -0
  30. package/src/commands/_lib/dev/dev-implement.ts +188 -0
  31. package/src/commands/_lib/dev/dev-source.ts +65 -0
  32. package/src/commands/_lib/dev/dev.ts +344 -0
  33. package/src/commands/_lib/dev-step.ts +142 -0
  34. package/src/commands/_lib/dispatch.ts +231 -0
  35. package/src/commands/_lib/effort.ts +15 -0
  36. package/src/commands/_lib/git/branch.ts +95 -0
  37. package/src/commands/_lib/git/commit.ts +94 -0
  38. package/src/commands/_lib/git/diff.ts +97 -0
  39. package/src/commands/_lib/git/review.ts +109 -0
  40. package/src/commands/_lib/memory/memory-admit.ts +150 -0
  41. package/src/commands/_lib/memory/memory.ts +51 -0
  42. package/src/commands/_lib/pr-context.ts +32 -0
  43. package/src/commands/_lib/project/analyze.ts +24 -0
  44. package/src/commands/_lib/session/export.ts +104 -0
  45. package/src/commands/_lib/session/resume.ts +160 -0
  46. package/src/commands/_lib/session/tasks.ts +184 -0
  47. package/src/commands/_lib/settings/advisor.ts +80 -0
  48. package/src/commands/_lib/settings/agents.ts +147 -0
  49. package/src/commands/_lib/settings/config.ts +141 -0
  50. package/src/commands/_lib/settings/hooks.ts +58 -0
  51. package/src/commands/_lib/settings/mode.ts +91 -0
  52. package/src/commands/_lib/settings/model.ts +146 -0
  53. package/src/commands/_lib/settings/permissions.ts +309 -0
  54. package/src/commands/_lib/settings/session-config.ts +49 -0
  55. package/src/commands/_lib/settings/skills.ts +51 -0
  56. package/src/commands/_lib/speech/say.ts +96 -0
  57. package/src/commands/_lib/speech/transcribe.ts +130 -0
  58. package/src/commands/_lib/speech/voice.ts +146 -0
  59. package/src/commands/_lib/status/cache.ts +31 -0
  60. package/src/commands/_lib/status/context.ts +57 -0
  61. package/src/commands/_lib/status/doctor.ts +186 -0
  62. package/src/commands/_lib/status/meta.ts +45 -0
  63. package/src/commands/_lib/status/status.ts +129 -0
  64. package/src/commands/_lib/status/usage-tools.ts +49 -0
  65. package/src/commands/_lib/status/usage.ts +139 -0
  66. package/src/commands/_lib/view.ts +29 -0
  67. package/src/commands/dev/dev-batches.cmd.ts +108 -0
  68. package/src/commands/dev/dev-learn.cmd.ts +29 -0
  69. package/src/commands/dev/dev-plan.cmd.ts +52 -0
  70. package/src/commands/dev/dev-spec.cmd.ts +55 -0
  71. package/src/commands/dev/dev-status.cmd.ts +16 -0
  72. package/src/commands/git/branch.cmd.ts +27 -0
  73. package/src/commands/git/commit.cmd.ts +48 -0
  74. package/src/commands/git/diff.cmd.ts +26 -0
  75. package/src/commands/git/review.cmd.ts +36 -0
  76. package/src/commands/memory/memory.cmd.ts +48 -0
  77. package/src/commands/project/analyze.cmd.ts +32 -0
  78. package/src/commands/project/debug-tool-call.cmd.ts +67 -0
  79. package/src/commands/project/files.cmd.ts +22 -0
  80. package/src/commands/project/init-verifiers.cmd.ts +14 -0
  81. package/src/commands/project/init.cmd.ts +14 -0
  82. package/src/commands/project/verify.cmd.ts +27 -0
  83. package/src/commands/session/assistant.cmd.ts +40 -0
  84. package/src/commands/session/btw.cmd.ts +18 -0
  85. package/src/commands/session/clear.cmd.ts +19 -0
  86. package/src/commands/session/compact.cmd.ts +16 -0
  87. package/src/commands/session/copy.cmd.ts +44 -0
  88. package/src/commands/session/exit.cmd.ts +9 -0
  89. package/src/commands/session/export.cmd.ts +28 -0
  90. package/src/commands/session/rename.cmd.ts +17 -0
  91. package/src/commands/session/resume.cmd.ts +19 -0
  92. package/src/commands/session/rewind.cmd.ts +26 -0
  93. package/src/commands/session/summary.cmd.ts +27 -0
  94. package/src/commands/session/tasks.cmd.ts +44 -0
  95. package/src/commands/settings/advisor.cmd.ts +38 -0
  96. package/src/commands/settings/agents.cmd.ts +19 -0
  97. package/src/commands/settings/config.cmd.ts +17 -0
  98. package/src/commands/settings/effort.cmd.ts +40 -0
  99. package/src/commands/settings/fast.cmd.ts +17 -0
  100. package/src/commands/settings/hooks.cmd.ts +17 -0
  101. package/src/commands/settings/mode.cmd.ts +20 -0
  102. package/src/commands/settings/model.cmd.ts +20 -0
  103. package/src/commands/settings/output-style.cmd.ts +48 -0
  104. package/src/commands/settings/permissions.cmd.ts +25 -0
  105. package/src/commands/settings/proactive.cmd.ts +15 -0
  106. package/src/commands/settings/skills.cmd.ts +17 -0
  107. package/src/commands/speech/say.cmd.ts +24 -0
  108. package/src/commands/speech/transcribe.cmd.ts +29 -0
  109. package/src/commands/speech/voice.cmd.ts +30 -0
  110. package/src/commands/status/context.cmd.ts +18 -0
  111. package/src/commands/status/doctor.cmd.ts +27 -0
  112. package/src/commands/status/release-notes.cmd.ts +9 -0
  113. package/src/commands/status/status.cmd.ts +25 -0
  114. package/src/commands/status/usage.cmd.ts +21 -0
  115. package/src/crews/.orkeon/orkeon.d.ts +3946 -0
  116. package/src/crews/_probe-shared-memory/domain/probe-verdict.ts +183 -0
  117. package/src/crews/_probe-shared-memory/probe.ork.ts +98 -0
  118. package/src/crews/advisor/application/run-advisor.ts +40 -0
  119. package/src/crews/advisor/crew.ork.ts +43 -0
  120. package/src/crews/advisor/domain/advice.ts +135 -0
  121. package/src/crews/agent-run/application/run-agent-run.ts +42 -0
  122. package/src/crews/agent-run/crew.ork.ts +67 -0
  123. package/src/crews/analyze/application/run-analyze.ts +118 -0
  124. package/src/crews/analyze/crew.ork.ts +40 -0
  125. package/src/crews/analyze/domain/harvest.ts +301 -0
  126. package/src/crews/code-review/application/prompts.ts +133 -0
  127. package/src/crews/code-review/application/review.ts +71 -0
  128. package/src/crews/code-review/application/run-code-review.ts +123 -0
  129. package/src/crews/code-review/crew.ork.ts +51 -0
  130. package/src/crews/code-review/domain/lenses.ts +193 -0
  131. package/src/crews/code-review/domain/report.ts +59 -0
  132. package/src/crews/code-review/domain/scope.ts +112 -0
  133. package/src/crews/dev-batches/application/plan-close.ts +181 -0
  134. package/src/crews/dev-batches/application/run-dev-batches.ts +669 -0
  135. package/src/crews/dev-batches/application/run-wave.ts +450 -0
  136. package/src/crews/dev-batches/application/seed-harvest.ts +162 -0
  137. package/src/crews/dev-batches/crew.ork.ts +143 -0
  138. package/src/crews/dev-batches/domain/batch-waves.ts +70 -0
  139. package/src/crews/dev-batches/domain/batches-budget.ts +52 -0
  140. package/src/crews/dev-batches/domain/batches-log.ts +54 -0
  141. package/src/crews/dev-batches/domain/wave-order.ts +43 -0
  142. package/src/crews/dev-change/application/change-prompt.ts +104 -0
  143. package/src/crews/dev-change/application/evidence.ts +169 -0
  144. package/src/crews/dev-change/application/run-dev-change.ts +315 -0
  145. package/src/crews/dev-change/crew.ork.ts +112 -0
  146. package/src/crews/dev-change/domain/change-answer.ts +159 -0
  147. package/src/crews/dev-change/domain/change-render.ts +79 -0
  148. package/src/crews/dev-implement/application/close.ts +183 -0
  149. package/src/crews/dev-implement/application/count-open-steps.ts +24 -0
  150. package/src/crews/dev-implement/application/locate-sheet.ts +80 -0
  151. package/src/crews/dev-implement/application/observe.ts +50 -0
  152. package/src/crews/dev-implement/application/report-writes.ts +41 -0
  153. package/src/crews/dev-implement/application/run-dev-implement.ts +811 -0
  154. package/src/crews/dev-implement/application/run-role.ts +27 -0
  155. package/src/crews/dev-implement/application/suite-job.ts +118 -0
  156. package/src/crews/dev-implement/application/touched.ts +74 -0
  157. package/src/crews/dev-implement/crew.ork.ts +68 -0
  158. package/src/crews/dev-implement/domain/contracts.ts +256 -0
  159. package/src/crews/dev-implement/domain/correction.ts +102 -0
  160. package/src/crews/dev-implement/domain/cycles.ts +35 -0
  161. package/src/crews/dev-implement/domain/implement-budget.ts +29 -0
  162. package/src/crews/dev-implement/domain/roles.ts +53 -0
  163. package/src/crews/dev-implement/domain/sheet-edits.ts +75 -0
  164. package/src/crews/dev-implement/domain/sheet-ticks.ts +22 -0
  165. package/src/crews/dev-implement/domain/step-checks.ts +136 -0
  166. package/src/crews/dev-implement/domain/step-section.ts +127 -0
  167. package/src/crews/dev-learn/application/learn-backlog.ts +58 -0
  168. package/src/crews/dev-learn/application/learn-prompt.ts +140 -0
  169. package/src/crews/dev-learn/application/run-dev-learn.ts +553 -0
  170. package/src/crews/dev-learn/crew.ork.ts +52 -0
  171. package/src/crews/dev-learn/domain/learn-answer.ts +235 -0
  172. package/src/crews/dev-learn/domain/owner-lines.ts +86 -0
  173. package/src/crews/dev-learn/domain/proposals-render.ts +96 -0
  174. package/src/crews/dev-plan/application/anchor-paths.ts +76 -0
  175. package/src/crews/dev-plan/application/inventory.ts +170 -0
  176. package/src/crews/dev-plan/application/plan-prompt.ts +159 -0
  177. package/src/crews/dev-plan/application/run-dev-plan.ts +455 -0
  178. package/src/crews/dev-plan/crew.ork.ts +109 -0
  179. package/src/crews/dev-plan/domain/inventory-model.ts +95 -0
  180. package/src/crews/dev-plan/domain/plan-answer.ts +738 -0
  181. package/src/crews/dev-plan/domain/plan-render.ts +307 -0
  182. package/src/crews/dev-spec/application/run-dev-spec.ts +206 -0
  183. package/src/crews/dev-spec/application/spec-prompt.ts +98 -0
  184. package/src/crews/dev-spec/crew.ork.ts +108 -0
  185. package/src/crews/dev-spec/domain/spec-answer.ts +253 -0
  186. package/src/crews/dev-spec/domain/spec-render.ts +76 -0
  187. package/src/crews/dev-verify/application/audit.ts +259 -0
  188. package/src/crews/dev-verify/application/auditor-prompt.ts +323 -0
  189. package/src/crews/dev-verify/application/capture.ts +303 -0
  190. package/src/crews/dev-verify/application/run-dev-verify.ts +409 -0
  191. package/src/crews/dev-verify/application/run-gate.ts +202 -0
  192. package/src/crews/dev-verify/crew.ork.ts +103 -0
  193. package/src/crews/dev-verify/domain/audit-answer.ts +150 -0
  194. package/src/crews/dev-verify/domain/auditor-charter.ts +21 -0
  195. package/src/crews/dev-verify/domain/capture-sections.ts +137 -0
  196. package/src/crews/dev-verify/domain/commands.ts +103 -0
  197. package/src/crews/dev-verify/domain/gate.ts +126 -0
  198. package/src/crews/dev-verify/domain/mechanical-table.ts +163 -0
  199. package/src/crews/dev-verify/domain/runtime-cut.ts +13 -0
  200. package/src/crews/dev-verify/domain/sheet-facts.ts +4 -0
  201. package/src/crews/dev-verify/domain/text.ts +20 -0
  202. package/src/crews/dev-verify/domain/verdict.ts +127 -0
  203. package/src/crews/git-commit/application/draft.ts +154 -0
  204. package/src/crews/git-commit/application/run-git-commit.ts +116 -0
  205. package/src/crews/git-commit/crew.ork.ts +52 -0
  206. package/src/crews/git-commit/domain/commit.ts +220 -0
  207. package/src/crews/init-verifiers/application/authoring.ts +89 -0
  208. package/src/crews/init-verifiers/application/prompts.ts +103 -0
  209. package/src/crews/init-verifiers/application/run-init-verifiers.ts +25 -0
  210. package/src/crews/init-verifiers/crew.ork.ts +34 -0
  211. package/src/crews/init-verifiers/domain/commands-section.ts +36 -0
  212. package/src/crews/init-verifiers/domain/readiness.ts +23 -0
  213. package/src/crews/main-loop/application/auto-compact.ts +77 -0
  214. package/src/crews/main-loop/application/context-gather.ts +133 -0
  215. package/src/crews/main-loop/application/run-main-loop.ts +350 -0
  216. package/src/crews/main-loop/application/turn-prompt.ts +112 -0
  217. package/src/crews/main-loop/crew.ork.ts +119 -0
  218. package/src/crews/main-loop/domain/autocompact.ts +27 -0
  219. package/src/crews/main-loop/domain/prompt-assembly.ts +521 -0
  220. package/src/crews/main-loop/domain/turn-chains.ts +129 -0
  221. package/src/crews/project-init/application/detect.ts +122 -0
  222. package/src/crews/project-init/application/prompts.ts +101 -0
  223. package/src/crews/project-init/application/run-project-init.ts +31 -0
  224. package/src/crews/project-init/crew.ork.ts +35 -0
  225. package/src/crews/project-init/domain/conventions.ts +36 -0
  226. package/src/crews/project-init/domain/existing-files.ts +63 -0
  227. package/src/crews/project-init/domain/package-map.ts +73 -0
  228. package/src/crews/session-compact/crew.ork.ts +55 -0
  229. package/src/crews/shared-memory-admit/crew.ork.ts +48 -0
  230. package/src/crews/speech/application/run-speech.ts +25 -0
  231. package/src/crews/speech/crew.ork.ts +37 -0
  232. package/src/shared/application/agents/child-agent.ts +255 -0
  233. package/src/shared/application/agents/run-sub-agent.ts +96 -0
  234. package/src/shared/application/answer-language.ts +14 -0
  235. package/src/shared/application/attached-skills.ts +36 -0
  236. package/src/shared/application/compaction/compact-session.ts +237 -0
  237. package/src/shared/application/compaction/extract-memories.ts +38 -0
  238. package/src/shared/application/compaction/restore-context.ts +78 -0
  239. package/src/shared/application/config-store.ts +123 -0
  240. package/src/shared/application/dev/brief-inventory.ts +113 -0
  241. package/src/shared/application/dev/close-batch.ts +83 -0
  242. package/src/shared/application/dev/find-repo-pack.ts +77 -0
  243. package/src/shared/application/dev/learn-decision.ts +252 -0
  244. package/src/shared/application/dev/load-dev-context.ts +266 -0
  245. package/src/shared/application/dev/measure-access-cost.ts +68 -0
  246. package/src/shared/application/dev/plan-source.ts +112 -0
  247. package/src/shared/application/dev/preflight.ts +71 -0
  248. package/src/shared/application/dev/project-files.ts +17 -0
  249. package/src/shared/application/dev/question-round.ts +52 -0
  250. package/src/shared/application/dev/resolve-work-folder.ts +133 -0
  251. package/src/shared/application/dev/script-tool-slot.ts +27 -0
  252. package/src/shared/application/dev/settle-questions.ts +55 -0
  253. package/src/shared/application/dev/source-review.ts +63 -0
  254. package/src/shared/application/dev/source-step.ts +150 -0
  255. package/src/shared/application/dev/spend.ts +42 -0
  256. package/src/shared/application/dev/step-precedents.ts +89 -0
  257. package/src/shared/application/dev/tool-call-policy.ts +89 -0
  258. package/src/shared/application/dev/tool-callbacks.ts +215 -0
  259. package/src/shared/application/dev/tool-trace-recorder.ts +45 -0
  260. package/src/shared/application/dev/verdict-sources.ts +48 -0
  261. package/src/shared/application/dev/wrapped-tools.ts +145 -0
  262. package/src/shared/application/extra-tools.ts +70 -0
  263. package/src/shared/application/git/batch-worktree.ts +97 -0
  264. package/src/shared/application/git/commit-files.ts +186 -0
  265. package/src/shared/application/git/merge-batch.ts +63 -0
  266. package/src/shared/application/git/open-pull-request.ts +51 -0
  267. package/src/shared/application/instructions-file.ts +19 -0
  268. package/src/shared/application/json-file.ts +34 -0
  269. package/src/shared/application/llm-profile.ts +35 -0
  270. package/src/shared/application/permission-rules.ts +159 -0
  271. package/src/shared/application/ports/approvals.ts +20 -0
  272. package/src/shared/application/ports/clock.ts +5 -0
  273. package/src/shared/application/ports/code-index.ts +93 -0
  274. package/src/shared/application/ports/crew.ts +60 -0
  275. package/src/shared/application/ports/files.ts +21 -0
  276. package/src/shared/application/ports/human.ts +13 -0
  277. package/src/shared/application/ports/llm.ts +54 -0
  278. package/src/shared/application/ports/memory.ts +30 -0
  279. package/src/shared/application/ports/progress.ts +23 -0
  280. package/src/shared/application/ports/runtime.ts +15 -0
  281. package/src/shared/application/ports/session.ts +74 -0
  282. package/src/shared/application/ports/shared-memory.ts +26 -0
  283. package/src/shared/application/ports/shell.ts +40 -0
  284. package/src/shared/application/ports/telemetry.ts +45 -0
  285. package/src/shared/application/ports/tools.ts +46 -0
  286. package/src/shared/application/ports/usage.ts +45 -0
  287. package/src/shared/application/ports.ts +27 -0
  288. package/src/shared/application/project-manifests.ts +106 -0
  289. package/src/shared/application/session-io.ts +84 -0
  290. package/src/shared/application/session-state.ts +36 -0
  291. package/src/shared/application/shared-memory/admit-entries.ts +177 -0
  292. package/src/shared/application/shared-memory/harvest-after-gaps.ts +72 -0
  293. package/src/shared/application/shared-memory/harvest-mistakes.ts +44 -0
  294. package/src/shared/application/shared-memory/import-agent-memory.ts +117 -0
  295. package/src/shared/application/shared-memory/memory-files.ts +110 -0
  296. package/src/shared/application/shared-memory/memory-settings.ts +93 -0
  297. package/src/shared/application/shared-memory/push-candidate.ts +146 -0
  298. package/src/shared/application/shared-memory/recall-precedents.ts +69 -0
  299. package/src/shared/application/state-snapshot.ts +38 -0
  300. package/src/shared/application/workflow/workflow-state.ts +135 -0
  301. package/src/shared/domain/agent-policy/behavior-flags.ts +168 -0
  302. package/src/shared/domain/agent-policy/extra-tools.ts +69 -0
  303. package/src/shared/domain/agent-policy/memory-categories.ts +6 -0
  304. package/src/shared/domain/agent-policy/mode-policy.ts +51 -0
  305. package/src/shared/domain/agent-policy/output-styles.ts +11 -0
  306. package/src/shared/domain/agent-policy/permission.ts +623 -0
  307. package/src/shared/domain/agent-policy/rule-sets.ts +412 -0
  308. package/src/shared/domain/agent-policy/tool-access.ts +77 -0
  309. package/src/shared/domain/agent-registry.ts +142 -0
  310. package/src/shared/domain/agents/built-in-charters.ts +43 -0
  311. package/src/shared/domain/agents/chain.ts +30 -0
  312. package/src/shared/domain/agents/charter.ts +61 -0
  313. package/src/shared/domain/agents/exclusive.ts +24 -0
  314. package/src/shared/domain/agents/instances.ts +249 -0
  315. package/src/shared/domain/code-intel-contract.ts +356 -0
  316. package/src/shared/domain/code-intel-routing.ts +113 -0
  317. package/src/shared/domain/compact-outcome.ts +44 -0
  318. package/src/shared/domain/compaction-thresholds.ts +161 -0
  319. package/src/shared/domain/compaction.ts +379 -0
  320. package/src/shared/domain/config-schema.ts +421 -0
  321. package/src/shared/domain/dev/access-cost.ts +226 -0
  322. package/src/shared/domain/dev/artefacts.ts +50 -0
  323. package/src/shared/domain/dev/batches-concurrency.ts +36 -0
  324. package/src/shared/domain/dev/batches-state.ts +49 -0
  325. package/src/shared/domain/dev/build-commands.ts +44 -0
  326. package/src/shared/domain/dev/call-guard.ts +341 -0
  327. package/src/shared/domain/dev/carried-text.ts +49 -0
  328. package/src/shared/domain/dev/design-rules.ts +100 -0
  329. package/src/shared/domain/dev/learn-proposals.ts +175 -0
  330. package/src/shared/domain/dev/learn-state.ts +93 -0
  331. package/src/shared/domain/dev/path-args.ts +42 -0
  332. package/src/shared/domain/dev/path-rebase.ts +93 -0
  333. package/src/shared/domain/dev/plan-checks.ts +190 -0
  334. package/src/shared/domain/dev/plan-format.ts +180 -0
  335. package/src/shared/domain/dev/project-files.ts +43 -0
  336. package/src/shared/domain/dev/questions.ts +249 -0
  337. package/src/shared/domain/dev/reading-rule.ts +41 -0
  338. package/src/shared/domain/dev/repo-pack.ts +237 -0
  339. package/src/shared/domain/dev/review-answer.ts +150 -0
  340. package/src/shared/domain/dev/review-prompt.ts +221 -0
  341. package/src/shared/domain/dev/reviewer-charter.ts +31 -0
  342. package/src/shared/domain/dev/sheet-facts.ts +83 -0
  343. package/src/shared/domain/dev/spec-format.ts +183 -0
  344. package/src/shared/domain/dev/step-budget.ts +72 -0
  345. package/src/shared/domain/dev/step-rules.ts +110 -0
  346. package/src/shared/domain/dev/test-commands.ts +90 -0
  347. package/src/shared/domain/dev/test-output.ts +33 -0
  348. package/src/shared/domain/dev/test-paths.ts +40 -0
  349. package/src/shared/domain/dev/tool-guards.ts +64 -0
  350. package/src/shared/domain/dev/trait-pattern.ts +83 -0
  351. package/src/shared/domain/dev/verdict-format.ts +169 -0
  352. package/src/shared/domain/dev/whitespace.ts +34 -0
  353. package/src/shared/domain/dev/work-folder.ts +67 -0
  354. package/src/shared/domain/dev/yaml-subset.ts +403 -0
  355. package/src/shared/domain/git/close.ts +273 -0
  356. package/src/shared/domain/git/pull-request.ts +96 -0
  357. package/src/shared/domain/git/worktree.ts +46 -0
  358. package/src/shared/domain/index-languages.ts +16 -0
  359. package/src/shared/domain/instructions-file.ts +18 -0
  360. package/src/shared/domain/iso-day.ts +4 -0
  361. package/src/shared/domain/llm-failure.ts +106 -0
  362. package/src/shared/domain/llm-profile.ts +25 -0
  363. package/src/shared/domain/marked-message.ts +33 -0
  364. package/src/shared/domain/model-catalog.ts +86 -0
  365. package/src/shared/domain/permission-modes.ts +103 -0
  366. package/src/shared/domain/prelude.ts +92 -0
  367. package/src/shared/domain/project-manifests.ts +83 -0
  368. package/src/shared/domain/search-routing.ts +85 -0
  369. package/src/shared/domain/secret-patterns.ts +45 -0
  370. package/src/shared/domain/session-keys.ts +85 -0
  371. package/src/shared/domain/session-start.ts +60 -0
  372. package/src/shared/domain/session-summary.ts +13 -0
  373. package/src/shared/domain/severity.ts +72 -0
  374. package/src/shared/domain/sha1.ts +61 -0
  375. package/src/shared/domain/shared-memory/agent-memory-import.ts +143 -0
  376. package/src/shared/domain/shared-memory/candidates.ts +41 -0
  377. package/src/shared/domain/shared-memory/entry.ts +145 -0
  378. package/src/shared/domain/shared-memory/front-matter.ts +183 -0
  379. package/src/shared/domain/shared-memory/gate.ts +44 -0
  380. package/src/shared/domain/shared-memory/harvest.ts +61 -0
  381. package/src/shared/domain/shared-memory/layout.ts +187 -0
  382. package/src/shared/domain/shared-memory/precedents-block.ts +93 -0
  383. package/src/shared/domain/shared-memory/refused.ts +84 -0
  384. package/src/shared/domain/shared-memory/verdict-rows.ts +134 -0
  385. package/src/shared/domain/snip-turns.ts +45 -0
  386. package/src/shared/domain/speech.ts +20 -0
  387. package/src/shared/domain/strip.ts +88 -0
  388. package/src/shared/domain/tool-trace.ts +122 -0
  389. package/src/shared/domain/types.ts +67 -0
  390. package/src/shared/domain/verifiers.ts +37 -0
  391. package/src/shared/domain/vfs.ts +9 -0
  392. package/src/shared/domain/workflow/state-file.ts +140 -0
  393. package/src/shared/infrastructure/globals.ts +52 -0
  394. package/src/shared/infrastructure/orkeon/approvals.ts +24 -0
  395. package/src/shared/infrastructure/orkeon/child-agents.ts +127 -0
  396. package/src/shared/infrastructure/orkeon/code-index.ts +120 -0
  397. package/src/shared/infrastructure/orkeon/crew-host.ts +27 -0
  398. package/src/shared/infrastructure/orkeon/crew-memory.ts +12 -0
  399. package/src/shared/infrastructure/orkeon/dev-deps.ts +172 -0
  400. package/src/shared/infrastructure/orkeon/files.ts +40 -0
  401. package/src/shared/infrastructure/orkeon/github-pull-requests.ts +29 -0
  402. package/src/shared/infrastructure/orkeon/host-provider.ts +22 -0
  403. package/src/shared/infrastructure/orkeon/human-input.ts +59 -0
  404. package/src/shared/infrastructure/orkeon/llm-profile.ts +38 -0
  405. package/src/shared/infrastructure/orkeon/llm.ts +109 -0
  406. package/src/shared/infrastructure/orkeon/memory-store.ts +41 -0
  407. package/src/shared/infrastructure/orkeon/memory-tools.ts +131 -0
  408. package/src/shared/infrastructure/orkeon/permission-rules.ts +42 -0
  409. package/src/shared/infrastructure/orkeon/progress.ts +24 -0
  410. package/src/shared/infrastructure/orkeon/run-state.ts +17 -0
  411. package/src/shared/infrastructure/orkeon/runtime-info.ts +30 -0
  412. package/src/shared/infrastructure/orkeon/runtime-tools.ts +60 -0
  413. package/src/shared/infrastructure/orkeon/script-tools.ts +134 -0
  414. package/src/shared/infrastructure/orkeon/session-store.ts +138 -0
  415. package/src/shared/infrastructure/orkeon/session-switch.ts +23 -0
  416. package/src/shared/infrastructure/orkeon/shared-memory.ts +61 -0
  417. package/src/shared/infrastructure/orkeon/shell-jobs.ts +75 -0
  418. package/src/shared/infrastructure/orkeon/shell.ts +31 -0
  419. package/src/shared/infrastructure/orkeon/telemetry.ts +63 -0
  420. package/src/shared/infrastructure/orkeon/tool-catalogue.ts +75 -0
  421. package/src/shared/infrastructure/orkeon/tool-results.ts +120 -0
  422. package/src/shared/infrastructure/orkeon/usage.ts +74 -0
  423. package/src/shared/infrastructure/orkeon/wiring.ts +118 -0
@@ -0,0 +1,123 @@
1
+ // CodeReview use case (/review [--lens] [--passes], /security-review): resolve the scope
2
+ // and the review plan, run the lens passes, rank the findings and write the
3
+ // report. The steps live in ./review, the decisions in ../domain.
4
+
5
+ import type { Files, Llm, Logger, Progress, SessionStore, Shell } from "../../../shared/application/ports.ts";
6
+ import type { ConfigStore } from "../../../shared/application/config-store.ts";
7
+ import { dedupAndRank } from "../../../shared/domain/severity.ts";
8
+ import { resolvePasses } from "../../../shared/domain/agent-policy/behavior-flags.ts";
9
+ import { PASSES_STATE_KEY } from "../../../shared/domain/session-keys.ts";
10
+ import type { Finding } from "../../../shared/domain/types.ts";
11
+ import { renderReport } from "../domain/report.ts";
12
+ import { resolveReviewScope, type ReviewInputs } from "../domain/scope.ts";
13
+ import { resolveLensSelection, describeReviewPlan } from "../domain/lenses.ts";
14
+ import {
15
+ chooseReviewDiff, collectDiff, collectChangedFiles, collectFunctionContextDiff, runLenses, writeReport,
16
+ } from "./review.ts";
17
+ import { cutDiff } from "./prompts.ts";
18
+ import { readInstructionsFile } from "../../../shared/application/instructions-file.ts";
19
+
20
+ /** The diff the lenses read, in characters: about 3 000 tokens, so three lenses per
21
+ * pass stay cheap; a longer diff is cut and says so. */
22
+ export const MAX_REVIEW_DIFF_CHARS = 12_000;
23
+
24
+ /** The findings the merged report keeps, the most severe first: three lenses times
25
+ * several passes would otherwise reach dozens of items. */
26
+ export const MAX_REPORT_FINDINGS = 30;
27
+
28
+ /** Status-line headline of the /review progress. */
29
+ export const REVIEW_PROGRESS_LABEL = "Reviewing changes";
30
+
31
+ /** The crew's input: `files` and `commit` scope the diff, `lenses` narrows the review, `passes` sets its rounds. */
32
+ export interface CodeReviewInputs extends ReviewInputs {
33
+ lenses?: unknown;
34
+ passes?: unknown;
35
+ }
36
+
37
+ /** A pass count the input names (`/review --passes`), else the session's: the input outranks the session key. */
38
+ function runPasses(input: unknown, stored: unknown): number {
39
+ const named = input !== undefined && input !== null && String(input).trim() !== "";
40
+ return resolvePasses(named ? input : stored);
41
+ }
42
+
43
+ export interface CodeReviewDeps {
44
+ shell: Shell;
45
+ files: Files;
46
+ progress: Progress;
47
+ session: Pick<SessionStore, "readState">;
48
+ config: Pick<ConfigStore, "readValue">;
49
+ llm: Pick<Llm, "extract">;
50
+ log: Logger;
51
+ }
52
+
53
+ /** Review the scope the input names; the report's path and tally, or why there is none. */
54
+ export async function runCodeReview(input: CodeReviewInputs, deps: CodeReviewDeps): Promise<string> {
55
+ const { shell, files, progress, session, config, llm, log } = deps;
56
+ // B-3: `files` used to be declared in the input contract and ignored — a
57
+ // caller asking to review two paths got whatever was staged, silently.
58
+ const scope = resolveReviewScope(input);
59
+ for (const r of scope.rejected) log.warn(`review input refused: '${r.value}' — ${r.reason}`);
60
+ log.info(`reviewing ${scope.describe}`);
61
+
62
+ const diff = await collectDiff(scope, shell);
63
+ if (diff.trim().length === 0) {
64
+ const what = scope.paths.length > 0
65
+ ? `No changes to review in the named path(s): ${scope.paths.join(", ")}.`
66
+ : "No changes to review (empty diff).";
67
+ return what;
68
+ }
69
+ // Function context only lengthens a diff: over the cap already, it is not asked for.
70
+ const withContext = diff.length <= MAX_REVIEW_DIFF_CHARS ? await collectFunctionContextDiff(scope, shell) : "";
71
+ const reviewed = chooseReviewDiff(diff, withContext, MAX_REVIEW_DIFF_CHARS);
72
+ const changed = await collectChangedFiles(scope, shell);
73
+
74
+ // B-9: two settings that existed and were read by nothing until now —
75
+ // `/passes` (session bag) and `review.lenses` (the /config key space, whose
76
+ // spec has named this crew as its consumer since B-6). A crew INPUT beats
77
+ // each for this run: `/review --passes` the first, `--lens` the second.
78
+ const [storedPasses, lensSetting] = await Promise.all([
79
+ session.readState(PASSES_STATE_KEY).catch(() => null),
80
+ config.readValue("review.lenses").then((r) => r.value).catch(() => undefined),
81
+ ]);
82
+ const passes = runPasses(input.passes, storedPasses);
83
+ // A crew INPUT narrows the lenses for this run (/review --lens, the
84
+ // /security-review alias) and beats the standing `review.lenses` setting.
85
+ const selection = resolveLensSelection({ input: input.lenses, config: lensSetting });
86
+ for (const u of selection.unknown) {
87
+ log.warn(`unknown review lens '${u}' ignored (valid: correctness, security, style)`);
88
+ }
89
+ const plan = describeReviewPlan(selection.lenses, passes, selection.source);
90
+ log.info(`review plan — ${plan}`);
91
+
92
+ const diffSlice = cutDiff(reviewed.diff, MAX_REVIEW_DIFF_CHARS);
93
+ const cut = reviewed.diff.length > MAX_REVIEW_DIFF_CHARS
94
+ ? { shown: MAX_REVIEW_DIFF_CHARS, leftOut: reviewed.diff.length - MAX_REVIEW_DIFF_CHARS }
95
+ : undefined;
96
+ // The style lens judges conventions: give it the ones the project states.
97
+ const conventions = (await readInstructionsFile(files).catch(() => undefined))?.content ?? "";
98
+ // Passes run in SEQUENCE (the lenses within a pass still fan out): pass n+1
99
+ // is shown what the earlier ones found and asked for what they missed, which
100
+ // only works if they have finished.
101
+ const results: Array<{ lens: string; findings: Finding[] }> = [];
102
+ try {
103
+ for (let pass = 1; pass <= passes; pass++) {
104
+ await progress.report({
105
+ label: REVIEW_PROGRESS_LABEL, step: pass, total: passes,
106
+ message: `pass ${pass} — ${selection.lenses.map((l) => l.key).join("/")}`,
107
+ });
108
+ const prior = dedupAndRank(results);
109
+ const round = await runLenses(llm, diffSlice, selection.lenses, pass, prior, conventions);
110
+ const added = round.reduce((n, r) => n + r.findings.length, 0);
111
+ if (passes > 1) log.info(`review pass ${pass}/${passes}: ${added} raw finding(s)`);
112
+ results.push(...round);
113
+ }
114
+ } finally {
115
+ await progress.done(REVIEW_PROGRESS_LABEL);
116
+ }
117
+ const ranked = dedupAndRank(results);
118
+ const findings = ranked.slice(0, MAX_REPORT_FINDINGS);
119
+
120
+ const report = renderReport(scope.describe, changed.length, findings, plan, cut, ranked.length - findings.length);
121
+ await writeReport(report, files);
122
+ return `/output/code-review-report.md (${findings.length} findings across ${changed.length} files, ${plan})`;
123
+ }
@@ -0,0 +1,51 @@
1
+ // @orkeon-script 1.0
2
+ /// <reference path="../.orkeon/orkeon.d.ts" />
3
+ //
4
+ // CodeReview crew (/review) — exp 07 SPEC §4.4. Composition root: it builds the
5
+ // agent and wires application/run-code-review, which collects the staged diff,
6
+ // runs three review lenses (correctness/security/style) in parallel via
7
+ // Promise.all, dedups + ranks findings, and writes /output/code-review-report.md.
8
+ //
9
+ // Input (globalThis.inputs): { files?: string[], commit?: string, lenses?: string, passes?: number }
10
+ // files — repo-relative paths restricting the diff (B-3; honoured since then)
11
+ // commit — review that commit instead of the staged changes
12
+ // lenses — the lenses of this run, outranking review.lenses (/review --lens, /security-review)
13
+ // passes — the rounds of this run, outranking the session's /passes (/review --passes)
14
+ // Run standalone: bash scripts/run-crew.sh src/crews/code-review/crew.ork.ts
15
+
16
+ import { CrewBuilder, publishCrew, inputs } from "../../shared/infrastructure/globals.ts";
17
+ import {
18
+ orkeonAgent,
19
+ orkeonConfigStore,
20
+ orkeonFiles,
21
+ orkeonProgress,
22
+ orkeonSessionIo,
23
+ orkeonShell,
24
+ } from "../../shared/infrastructure/orkeon/wiring.ts";
25
+ import { createLlm } from "../../shared/infrastructure/orkeon/llm.ts";
26
+ import { runCodeReview } from "./application/run-code-review.ts";
27
+
28
+ const ports = {
29
+ shell: orkeonShell(),
30
+ files: orkeonFiles(),
31
+ progress: orkeonProgress(),
32
+ session: orkeonSessionIo(),
33
+ config: orkeonConfigStore(),
34
+ };
35
+
36
+ const reviewer = orkeonAgent()
37
+ .name("code-reviewer")
38
+ .role("Senior Code Reviewer")
39
+ .goal("Review changes across correctness, security, and style lenses and produce a ranked report.")
40
+ .tools(["shell_command", "file_read"])
41
+ .body(async (_input: any, ctx: any) =>
42
+ await runCodeReview(inputs(), { ...ports, llm: createLlm(ctx.llm), log: ctx.log }))
43
+ .build();
44
+
45
+ publishCrew(
46
+ CrewBuilder()
47
+ .name("code-review")
48
+ .process("sequential")
49
+ .withAgent(reviewer)
50
+ .build(),
51
+ );
@@ -0,0 +1,193 @@
1
+ // Which review lenses run, and how many rounds of them. Pure, no IO.
2
+ //
3
+ // Two settings meet here: `review.lenses` (the /config key space) selects the
4
+ // lenses, `/passes` the rounds. Each lens says what it looks for and what it
5
+ // leaves to the others, so three blind reviewers do not report the same thing
6
+ // three times, nor what no lens should report at all.
7
+
8
+ import type { Finding } from "../../../shared/domain/types.ts";
9
+ import { severityRank } from "../../../shared/domain/severity.ts";
10
+
11
+ /** The most severe level a style finding takes: its scale says it, and the review
12
+ * brings a higher one down to it, so style never outranks a correctness finding. */
13
+ export const STYLE_SEVERITY_CEILING = "medium";
14
+
15
+ export interface ReviewLens {
16
+ key: string;
17
+ /** The defects this lens hunts, as concrete patterns. */
18
+ looksFor: string;
19
+ /** What it does not report: another lens's ground, or what no lens should report. */
20
+ leaves: string;
21
+ /** Its severity scale, worst first, each level with what earns it. */
22
+ severities: string;
23
+ /** What a finding must show besides the changed line it points at. */
24
+ bar: string;
25
+ /** The most severe level its findings keep, when the scale stops short of blocker. */
26
+ ceiling?: string;
27
+ /** Its bar is a quote of the text shown, so a finding of it is never plausible. */
28
+ neverPlausible?: boolean;
29
+ }
30
+
31
+ /** The three review lenses, each blind to the others (run via Promise.all). */
32
+ export const LENSES: readonly ReviewLens[] = [
33
+ {
34
+ key: "correctness",
35
+ looksFor:
36
+ "behaviour the change gets wrong: an inverted or incomplete condition, an off-by-one, a value used " +
37
+ "before it is set, a case the new code does not handle although its inputs allow it, a caller or a " +
38
+ "contract the change breaks, a resource left open, steps that race; and, for each removed or replaced " +
39
+ "line, what it guaranteed and whether the new code still does (such a finding points at the first " +
40
+ "new line of the hunk that held the removed line, the new start its @@ header gives, and names the " +
41
+ "removed line)",
42
+ leaves:
43
+ "style and naming, defensive checks for inputs the code cannot receive, security (another lens), " +
44
+ "performance unless the change makes something fail",
45
+ severities:
46
+ "blocker (breaks the build, loses data or opens a hole in normal use), high (a wrong result in a " +
47
+ "plausible case), medium (wrong in an edge case, or a maintenance cost with a concrete trigger), " +
48
+ "low (minor), nit (style only)",
49
+ bar: "say what goes wrong, for which input or state",
50
+ },
51
+ {
52
+ key: "security",
53
+ looksFor:
54
+ "a way in that the change opens: input reaching a shell, a query, a path or markup unescaped, a " +
55
+ "secret written into code, logs or output, an authorisation check missing or weakened, unsafe " +
56
+ "deserialisation, a file or network access wider than needed",
57
+ leaves:
58
+ "attacks with no input that reaches the code, a defence wished for code the diff does not touch, " +
59
+ "issues the change neither adds nor touches, style and plain bugs (other lenses)",
60
+ severities:
61
+ "ranked by what an attacker needs: blocker (no condition, open in normal use), high (open under " +
62
+ "specific conditions, such as a setting, a role or a timing), medium (a defence missing on a path " +
63
+ "the diff shows an input reaching, with no way in shown), low (minor)",
64
+ bar: "name the input an attacker controls, the path it takes to that line and what it gains them",
65
+ },
66
+ {
67
+ key: "style",
68
+ looksFor:
69
+ "what makes the change harder to read or maintain: a misleading name, dead or duplicated code the " +
70
+ "change adds, a comment that restates the code or narrates the change, a break with the conventions " +
71
+ "the project states or the surrounding code follows",
72
+ leaves: "what a formatter fixes, taste with no concrete cost, correctness and security (other lenses)",
73
+ severities:
74
+ `never above ${STYLE_SEVERITY_CEILING}: medium (a reader or maintainer will be misled or slowed), low (minor), ` +
75
+ "nit (a small break with the convention)",
76
+ bar:
77
+ "quote the convention the project states, or the neighbouring code, that the line breaks, and say " +
78
+ "what it costs a reader or maintainer",
79
+ ceiling: STYLE_SEVERITY_CEILING,
80
+ neverPlausible: true,
81
+ },
82
+ ];
83
+
84
+ /** `finding` held to the ceiling of `lens`: a level above it comes down to it. */
85
+ export function withinCeiling(lens: ReviewLens, finding: Finding): Finding {
86
+ if (lens.ceiling === undefined) return finding;
87
+ return severityRank(finding.severity) < severityRank(lens.ceiling) ? { ...finding, severity: lens.ceiling } : finding;
88
+ }
89
+
90
+ export function lensKeys(): string[] {
91
+ return LENSES.map((l) => l.key);
92
+ }
93
+
94
+ export interface LensSelection {
95
+ lenses: readonly ReviewLens[];
96
+ /** Names in the setting that match no lens — reported, never silently ignored. */
97
+ unknown: string[];
98
+ }
99
+
100
+ /**
101
+ * Resolves the `review.lenses` setting: a comma-separated list of lens keys.
102
+ *
103
+ * Unset, blank, or all-unknown ⇒ all three lenses. A review that silently
104
+ * narrowed itself to nothing (or to two lenses because one was misspelt) is the
105
+ * worst outcome available here: the report would look complete and be blind.
106
+ * So an unrecognised name is returned for the caller to warn about, and a
107
+ * selection that matched nothing falls back to the full set rather than
108
+ * producing an empty review.
109
+ *
110
+ * Order follows LENSES, not the setting: the report is easier to compare across
111
+ * runs when the lenses always appear in the same order.
112
+ */
113
+ export function selectLenses(setting: unknown): LensSelection {
114
+ const requested = String(setting ?? "")
115
+ .split(",")
116
+ .map((s) => s.trim().toLowerCase())
117
+ .filter((s) => s.length > 0);
118
+
119
+ if (requested.length === 0) return { lenses: LENSES, unknown: [] };
120
+
121
+ const known = new Set(lensKeys());
122
+ const unknown = [...new Set(requested.filter((r) => !known.has(r)))];
123
+ const wanted = new Set(requested.filter((r) => known.has(r)));
124
+
125
+ if (wanted.size === 0) return { lenses: LENSES, unknown };
126
+ return { lenses: LENSES.filter((l) => wanted.has(l.key)), unknown };
127
+ }
128
+
129
+ /** Where an effective lens selection came from. */
130
+ export type LensSource = "input" | "config" | "default";
131
+
132
+ export interface ResolvedLensSelection extends LensSelection {
133
+ source: LensSource;
134
+ }
135
+
136
+ /**
137
+ * The effective lens selection: crew INPUT beats the `review.lenses` setting.
138
+ *
139
+ * `/review --lens` and `/security-review` need this: the same crew narrowed
140
+ * to one lens, and they say so per invocation. A setting is a standing preference,
141
+ * an input is a deliberate act on this run — so the input wins, the same way an
142
+ * explicit `plan:` prefix beats the session's default permission mode.
143
+ *
144
+ * An input naming only unknown lenses falls through to the setting rather than to
145
+ * the full set, because the caller clearly meant to narrow and the honest answer to
146
+ * "narrow to something I do not have" is the next-widest thing they configured.
147
+ */
148
+ export function resolveLensSelection(sources: {
149
+ input?: unknown;
150
+ config?: unknown;
151
+ }): ResolvedLensSelection {
152
+ const fromInput = selectLenses(normalizeLensInput(sources?.input));
153
+ if (namesAKnownLens(sources?.input)) return { ...fromInput, source: "input" };
154
+
155
+ const fromConfig = selectLenses(sources?.config);
156
+ const unknown = [...new Set([...fromInput.unknown, ...fromConfig.unknown])];
157
+ if (namesAKnownLens(sources?.config)) return { ...fromConfig, unknown, source: "config" };
158
+
159
+ return { lenses: LENSES, unknown, source: "default" };
160
+ }
161
+
162
+ /** Accepts `"a,b"` and `["a","b"]` — a command may pass either. */
163
+ function normalizeLensInput(raw: unknown): string {
164
+ if (Array.isArray(raw)) return raw.map((r) => String(r ?? "")).join(",");
165
+ return String(raw ?? "");
166
+ }
167
+
168
+ /**
169
+ * True when the source names at least one KNOWN lens.
170
+ *
171
+ * Deliberately not "the selection is narrower than the full set": naming all three
172
+ * explicitly is still an explicit choice, and it must win over a setting that says
173
+ * something else. Deliberately not "the source is non-empty" either, or a typo
174
+ * would win and silently review everything.
175
+ */
176
+ function namesAKnownLens(raw: unknown): boolean {
177
+ const known = lensKeys().map((k) => k.toLowerCase());
178
+ return normalizeLensInput(raw)
179
+ .split(",")
180
+ .map((s) => s.trim().toLowerCase())
181
+ .some((s) => s.length > 0 && known.includes(s));
182
+ }
183
+
184
+ /** One line for the report header: what ran, how many times, and on whose say-so. */
185
+ export function describeReviewPlan(
186
+ lenses: readonly ReviewLens[],
187
+ passes: number,
188
+ source: LensSource = "default",
189
+ ): string {
190
+ const plural = passes === 1 ? "pass" : "passes";
191
+ const via = source === "default" ? "" : ` (lenses from the ${source})`;
192
+ return `${passes} ${plural} × ${lenses.length} lens(es): ${lenses.map((l) => l.key).join(", ")}${via}`;
193
+ }
@@ -0,0 +1,59 @@
1
+ // Pure report rendering — no IO. Extracted from code-review/crew.ork.ts:80-91
2
+ // so the report shape can be snapshot-tested without a live LLM run.
3
+
4
+ import type { Finding } from "../../../shared/domain/types.ts";
5
+
6
+ /** How much of the diff the lenses read: `shown` characters, `leftOut` not reviewed. */
7
+ export interface ReportCut {
8
+ shown: number;
9
+ leftOut: number;
10
+ }
11
+
12
+ /**
13
+ * Render the ranked findings as the code-review-report.md body.
14
+ *
15
+ * `scope` is a human-readable description of what was reviewed — since B-3 that
16
+ * may be a range ("staged changes") or a range restricted to named paths, so the
17
+ * header no longer says "Range" about something that is not one.
18
+ *
19
+ * `cut`, when the diff was cut, puts the amount not reviewed in the header, and an
20
+ * empty review then says it covers the part reviewed only: "No issues found" on a cut
21
+ * diff is not a clean review. `findingsLeftOut` is how many less severe findings the
22
+ * report cap dropped.
23
+ */
24
+ export function renderReport(
25
+ scope: string,
26
+ fileCount: number,
27
+ findings: Finding[],
28
+ plan?: string,
29
+ cut?: ReportCut,
30
+ findingsLeftOut = 0,
31
+ ): string {
32
+ const lines: string[] = [
33
+ `# Code Review Report`,
34
+ ``,
35
+ `- Scope: \`${scope}\``,
36
+ `- Files: ${fileCount}`,
37
+ // B-9: the plan line makes /passes and review.lenses observable in the
38
+ // artefact. Without it, a 3-pass review and a 1-pass review are told apart
39
+ // only by the bill.
40
+ ...(plan ? [`- Review: ${plan}`] : []),
41
+ ...(cut ? [`- Diff: cut after ${cut.shown} characters, ${cut.leftOut} characters not reviewed`] : []),
42
+ findingsLeftOut > 0
43
+ ? `- Findings: ${findings.length} (${findingsLeftOut} less severe left out)`
44
+ : `- Findings: ${findings.length}`,
45
+ ``,
46
+ ];
47
+ if (findings.length === 0) {
48
+ lines.push(cut ? "No issues found in the part reviewed." : "No issues found. ✅");
49
+ } else {
50
+ for (const f of findings) {
51
+ const plausible = f.confidence === "plausible" ? " (plausible)" : "";
52
+ lines.push(`### [${String(f.severity ?? "?").toUpperCase()}]${plausible} ${f.file}:${f.line ?? "?"} — ${f.category ?? f.lens}`);
53
+ lines.push(f.finding ?? "");
54
+ if (f.suggestion) lines.push(``, `**Suggestion:** ${f.suggestion}`);
55
+ lines.push(``);
56
+ }
57
+ }
58
+ return lines.join("\n");
59
+ }
@@ -0,0 +1,112 @@
1
+ // Pure review scope — what `/review` looks at, decided without IO.
2
+ //
3
+ // B-3: the crew's declared input contract is `{ files?: string[], commit?: string }`
4
+ // (crew.ork.ts header) and baseline 03 §CodeReview Crew explicitly covers
5
+ // reviewing NAMED FILES. But `resolveCommitRange` only ever read `inputs.commit`,
6
+ // so a `files` argument was silently ignored and every review fell back to
7
+ // `--staged`. A caller asking to review two files got a review of whatever
8
+ // happened to be staged, with nothing saying the request had been dropped.
9
+ //
10
+ // The second half of this module is not in B-3's acceptance and is here because
11
+ // B-3 could not be written safely without it: `git diff ${range}` interpolates
12
+ // caller input into a shell string (`shared/infrastructure/shell.ts` passes the
13
+ // command through verbatim), so `commit` was already an injection point and
14
+ // `files` would have been a second one. Both are validated, and a rejected value
15
+ // is REPORTED rather than dropped — a silently ignored path is the very defect
16
+ // this item exists to fix.
17
+
18
+ /** Characters a git ref may contain here. Deliberately narrower than git's own rule. */
19
+ const SAFE_REF = /^[A-Za-z0-9._/~^-]+$/;
20
+
21
+ /** Characters a repo-relative path may contain. No whitespace, no shell metacharacters. */
22
+ const SAFE_PATH = /^[A-Za-z0-9._/-]+$/;
23
+
24
+ /** What the scope is resolved from: the crew's `commit` and `files` inputs, as the caller gave them. */
25
+ export interface ReviewInputs {
26
+ commit?: unknown;
27
+ files?: unknown;
28
+ }
29
+
30
+ export interface ReviewScope {
31
+ /** The git diff range: `--staged`, or `<commit>~1..<commit>`. */
32
+ range: string;
33
+ /** Validated repo-relative paths restricting the diff; empty = whole range. */
34
+ paths: string[];
35
+ /** The full argument string for `git diff …` — range, then `-- <paths>`. */
36
+ diffArgs: string;
37
+ /** Human-readable scope, for the report header and the log. */
38
+ describe: string;
39
+ /** Inputs refused, with the reason. Never silent. */
40
+ rejected: Array<{ value: string; reason: string }>;
41
+ }
42
+
43
+ /** `<commit>~1..<commit>` for a named commit, else `--staged`. Unchanged since B-3. */
44
+ export function resolveCommitRange(inputs?: ReviewInputs | null): string {
45
+ return inputs?.commit ? `${inputs.commit}~1..${inputs.commit}` : "--staged";
46
+ }
47
+
48
+ function validatePaths(raw: unknown): { paths: string[]; rejected: Array<{ value: string; reason: string }> } {
49
+ const paths: string[] = [];
50
+ const rejected: Array<{ value: string; reason: string }> = [];
51
+ const list = Array.isArray(raw) ? raw : raw == null ? [] : [raw];
52
+ for (const item of list) {
53
+ const p = String(item ?? "").trim();
54
+ if (p.length === 0) continue;
55
+ if (p.startsWith("/")) {
56
+ rejected.push({ value: p, reason: "absolute path — review paths are repo-relative" });
57
+ continue;
58
+ }
59
+ if (p.split("/").includes("..")) {
60
+ rejected.push({ value: p, reason: "'..' segment — would escape the repository" });
61
+ continue;
62
+ }
63
+ if (!SAFE_PATH.test(p)) {
64
+ rejected.push({
65
+ value: p,
66
+ reason: "contains a character that is unsafe in a shell argument " +
67
+ "(allowed: letters, digits, '.', '_', '-', '/')",
68
+ });
69
+ continue;
70
+ }
71
+ if (!paths.includes(p)) paths.push(p);
72
+ }
73
+ return { paths, rejected };
74
+ }
75
+
76
+ /**
77
+ * Resolves what to review.
78
+ *
79
+ * With no `files`, the result is byte-identical to the pre-B-3 behaviour: the
80
+ * range alone, so `git diff --staged` and `git diff --staged --name-only` are the
81
+ * exact commands that used to run.
82
+ */
83
+ export function resolveReviewScope(inputs?: ReviewInputs | null): ReviewScope {
84
+ const rejected: Array<{ value: string; reason: string }> = [];
85
+
86
+ let range = "--staged";
87
+ const commit = String(inputs?.commit ?? "").trim();
88
+ if (commit.length > 0) {
89
+ if (SAFE_REF.test(commit)) {
90
+ range = `${commit}~1..${commit}`;
91
+ } else {
92
+ rejected.push({
93
+ value: commit,
94
+ reason: "not a plausible git ref (allowed: letters, digits, '.', '_', '-', '/', '~', '^') " +
95
+ "— reviewing the staged changes instead",
96
+ });
97
+ }
98
+ }
99
+
100
+ const { paths, rejected: pathRejects } = validatePaths(inputs?.files);
101
+ rejected.push(...pathRejects);
102
+
103
+ // `--` separates revisions from pathspecs; without it git would try to resolve
104
+ // a path that happens to look like a ref.
105
+ const diffArgs = paths.length > 0 ? `${range} -- ${paths.join(" ")}` : range;
106
+ const where = range === "--staged" ? "staged changes" : `commit ${range}`;
107
+ const describe = paths.length > 0
108
+ ? `${where}, restricted to ${paths.length} path(s): ${paths.join(", ")}`
109
+ : where;
110
+
111
+ return { range, paths, diffArgs, describe, rejected };
112
+ }