peaks-loop 4.1.10 → 4.1.12
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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +78 -0
- package/README-en.md +1 -1
- package/README.md +1 -1
- package/dist/cli/commands/code-review-commands.d.ts +1 -1
- package/dist/cli/commands/code-review-commands.js +23 -37
- package/dist/cli/commands/code-review-ocr-delegate-record.d.ts +3 -0
- package/dist/cli/commands/code-review-ocr-delegate-record.js +73 -0
- package/dist/cli/commands/code-review-ocr-delegate.d.ts +12 -0
- package/dist/cli/commands/code-review-ocr-delegate.js +140 -0
- package/dist/cli/commands/code-review-run-ocr-18.d.ts +11 -0
- package/dist/cli/commands/code-review-run-ocr-18.js +127 -0
- package/dist/services/code/orchestrator-can-do-probes.d.ts +10 -0
- package/dist/services/code/orchestrator-can-do-probes.js +12 -2
- package/dist/services/lint/detect-ocr-18.js +1 -1
- package/dist/services/lint/ocr-18-acquire.d.ts +1 -1
- package/dist/services/lint/ocr-18-acquire.js +2 -2
- package/dist/services/lint/ocr-18-allowlist.d.ts +30 -0
- package/dist/services/lint/ocr-18-allowlist.js +165 -0
- package/dist/services/lint/ocr-18-delegate-packet.d.ts +84 -0
- package/dist/services/lint/ocr-18-delegate-packet.js +175 -0
- package/dist/services/lint/ocr-18-delegate-payload.d.ts +67 -0
- package/dist/services/lint/ocr-18-delegate-payload.js +208 -0
- package/dist/services/lint/ocr-18-delegate-record.d.ts +42 -0
- package/dist/services/lint/ocr-18-delegate-record.js +223 -0
- package/dist/services/lint/ocr-18-language-routing.d.ts +96 -0
- package/dist/services/lint/ocr-18-language-routing.js +148 -0
- package/dist/services/lint/ocr-18-multi.d.ts +54 -0
- package/dist/services/lint/ocr-18-multi.js +184 -0
- package/dist/services/lint/ocr-multilang-adapter.d.ts +45 -7
- package/dist/services/lint/ocr-multilang-adapter.js +133 -94
- package/dist/services/scan/archetype-service.js +24 -8
- package/dist/services/scan/frontend-evidence.d.ts +19 -0
- package/dist/services/scan/frontend-evidence.js +142 -0
- package/dist/services/scan/scan-types.d.ts +8 -1
- package/package.json +10 -10
- package/skills/bee/peaks-rd/SKILL.md +32 -0
- package/skills/bee/peaks-rd/references/ocr-multilang-1.8.md +314 -111
|
@@ -1,132 +1,335 @@
|
|
|
1
1
|
---
|
|
2
|
-
title: OCR 1.
|
|
3
|
-
rid:
|
|
4
|
-
session: 2026-
|
|
5
|
-
status:
|
|
2
|
+
title: OCR 1.x Multi-language Reviewer Adapter
|
|
3
|
+
rid: ocr-language-integration
|
|
4
|
+
session: 2026-10-20-session-a545d0
|
|
5
|
+
status: implemented (4.1.10 tree, unreleased)
|
|
6
6
|
---
|
|
7
7
|
|
|
8
|
-
# OCR 1.
|
|
8
|
+
# OCR 1.x Multi-language Reviewer Adapter
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
Supersedes the 1.8-era reference of the same path. The 1.8 content described a
|
|
11
|
+
`--filter-language` flag and a `findings[]` envelope. Neither exists: the real
|
|
12
|
+
binary rejects the flag with `Error: unknown flag`, and `ocr review --format json`
|
|
13
|
+
returns `comments[]`. Read this file, not the old one, before touching the bridge.
|
|
11
14
|
|
|
12
|
-
`@alibaba-group/open-code-review@1.
|
|
13
|
-
|
|
14
|
-
(`@alibaba-group/ocr-{darwin,linux,win32}-{arm64,x64}`). `npm install`
|
|
15
|
-
hits the registry only; postinstall runs the Node installer the package
|
|
16
|
-
itself ships and resolves the platform binary locally.
|
|
15
|
+
Pinned runtime: `@alibaba-group/open-code-review@1.13.1` (`OCR_18_PACKAGE` in
|
|
16
|
+
`src/services/lint/ocr-multilang-adapter.ts`).
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
## 1. The real CLI surface
|
|
19
19
|
|
|
20
20
|
```
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
21
|
+
ocr review [--from <ref>] [--to <ref>] [--commit <sha>] [--format json]
|
|
22
|
+
ocr review --preview # lists which files WOULD be reviewed, no LLM call
|
|
23
|
+
ocr delegate preview [--format json] # delegation: selection only, no LLM key
|
|
24
|
+
ocr delegate rule <path...> [--format json] # delegation: resolved rules, no key
|
|
24
25
|
```
|
|
25
26
|
|
|
26
|
-
|
|
27
|
-
|
|
27
|
+
There is **no language flag**. The 1.8-era `--filter-language` was removed from
|
|
28
|
+
the adapter in `194eccf5` after the real binary was consulted; every non-delegate
|
|
29
|
+
run failed with `Error: unknown flag: --filter-language` before that.
|
|
28
30
|
|
|
29
|
-
|
|
31
|
+
Not adopted by this bridge, deliberately: `--format sarif`, `-o/--output`,
|
|
32
|
+
`--effort`, `--max-tokens-budget`, `ocr scan`. They are new capability, not
|
|
33
|
+
integration; adding them is its own slice.
|
|
30
34
|
|
|
31
|
-
|
|
35
|
+
## 2. Post-review scoping — where language routing actually happens
|
|
36
|
+
|
|
37
|
+
`ocr review` reviews the whole diff. The bridge attributes each returned comment
|
|
38
|
+
to a language **after** the review, by the extension of `comment.path`:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
comments[] (path, content, start_line, end_line, severity, category)
|
|
42
|
+
│
|
|
43
|
+
├─ extension → LANGUAGE_EXTENSIONS → language
|
|
44
|
+
└─ severityFor(severity) → error | warn | info
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Consequences, stated plainly:
|
|
48
|
+
|
|
49
|
+
- A comment on a format the caller did not route is still REPORTED — it lands in
|
|
50
|
+
`unroutedFindings` rather than being dropped.
|
|
51
|
+
- Scoping is what gets reported, not what the LLM was asked to look at. The
|
|
52
|
+
review is over the whole range either way.
|
|
53
|
+
- Extension matching is case-insensitive.
|
|
54
|
+
|
|
55
|
+
## 3. Language coverage and its source of truth
|
|
56
|
+
|
|
57
|
+
`LANGUAGE_EXTENSIONS` (57 languages, 97 extensions) is the single source of
|
|
58
|
+
truth. `OCR_18_LANGUAGES`, the extension lookup and `--languages` token
|
|
59
|
+
resolution are all derived from it, so a language cannot be routed without an
|
|
60
|
+
extension entry.
|
|
61
|
+
|
|
62
|
+
The table is a **snapshot** of the pinned runtime's own allowlist:
|
|
63
|
+
`internal/config/allowlist/supported_file_types.json` at tag `v1.13.1`
|
|
64
|
+
(115 entries), vendored in `src/services/lint/ocr-18-allowlist.ts`. The rest of
|
|
65
|
+
the allowlist is listed in `OCR_18_EXCLUDED_EXTENSIONS` with a reason (CSS,
|
|
66
|
+
HTML, XML, YAML/JSON/TOML/INI, `.po`/`.pot`, `.ipynb`) — markup, stylesheets,
|
|
67
|
+
data/config and notebook containers are reviewed by the CLI but carry no source
|
|
68
|
+
semantics to route per language.
|
|
69
|
+
|
|
70
|
+
Tests that keep it honest
|
|
71
|
+
(`tests/unit/services/lint/ocr-multilang-adapter.test.ts`):
|
|
72
|
+
|
|
73
|
+
- every language has at least one extension;
|
|
74
|
+
- no extension routes to two languages;
|
|
75
|
+
- every routed extension is in the vendored allowlist;
|
|
76
|
+
- routed ∪ excluded covers the allowlist exactly — an upstream addition reddens
|
|
77
|
+
here instead of vanishing.
|
|
78
|
+
|
|
79
|
+
Three documented divergences, each deliberate:
|
|
80
|
+
|
|
81
|
+
- **`.mts` / `.cts`** are TypeScript to the PRD, but the 1.13.1 allowlist omits
|
|
82
|
+
both and `ocr review --preview` classifies them `unsupported_ext`. They are NOT
|
|
83
|
+
routed: routing them would report "typescript: 0 findings" for files the CLI
|
|
84
|
+
never read. They surface in `unsupportedFiles` instead.
|
|
85
|
+
- **`.m`** is claimed by both Objective-C and MATLAB upstream and cannot be told
|
|
86
|
+
apart by extension. It routes to Objective-C.
|
|
87
|
+
- **`.h`** is ambiguous between C and C++ and stays under `cpp`, because that is
|
|
88
|
+
the surface inherited from `194eccf5`: `--language cpp` matched `.h` before this
|
|
89
|
+
slice, and the preserved-behaviour clause forbids silently changing it. It is
|
|
90
|
+
absent from `c` — `--language c` does not match a header. It is deliberately not
|
|
91
|
+
assigned to both: one file maps to one language, or the same comment would be
|
|
92
|
+
counted twice in `byLanguage`. Moving it is a breaking change needing its own
|
|
93
|
+
decision; a test pins the current assignment.
|
|
94
|
+
|
|
95
|
+
Empirical control used to settle the allowlist (2026-10-20, win32-x64): a scratch
|
|
96
|
+
repository holding one file per extension was run through `ocr review --preview`.
|
|
97
|
+
Every routed extension appeared under "Will review"; `.mts`, `.cts` and `.glsl`
|
|
98
|
+
appeared under `Excluded from review (unsupported_ext)`. `.glsl` is in HEAD's
|
|
99
|
+
allowlist but not in v1.13.1 — which is why the tag, not HEAD, is the snapshot.
|
|
100
|
+
|
|
101
|
+
When the pin moves, update `OCR_18_PACKAGE`, re-vendor the allowlist at the new
|
|
102
|
+
tag, and let the partition test tell you what changed.
|
|
103
|
+
|
|
104
|
+
## 4. Auto-detection
|
|
105
|
+
|
|
106
|
+
`detectLanguages(cwd, range)` derives the changed files from the same git range
|
|
107
|
+
the review will use:
|
|
108
|
+
|
|
109
|
+
| Selector | git command |
|
|
32
110
|
|---|---|
|
|
33
|
-
|
|
|
34
|
-
| `
|
|
35
|
-
| `
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
| `php` | `*.php` |
|
|
111
|
+
| `--commit <sha>` | `git show --pretty=format: --name-only --diff-filter=ACMR <sha>` |
|
|
112
|
+
| `--from` / `--to` | `git diff --name-only --diff-filter=ACMR <from> <to> --` |
|
|
113
|
+
| none (workspace) | `git diff … HEAD --` **plus** `git ls-files --others --exclude-standard` |
|
|
114
|
+
|
|
115
|
+
The workspace case reads untracked files too: `ocr review` reviews them, so a
|
|
116
|
+
brand-new source file must not be able to skip the language detection that
|
|
117
|
+
decides whether the review runs at all.
|
|
41
118
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
119
|
+
`detectLanguages` **throws** when git cannot answer. The CLI turns that into
|
|
120
|
+
`OCR18_DETECT_FAILED`. "Could not detect" must never be reported as "nothing to
|
|
121
|
+
review".
|
|
45
122
|
|
|
46
|
-
##
|
|
123
|
+
## 5. One invocation, many languages
|
|
47
124
|
|
|
48
|
-
`
|
|
125
|
+
`runOcr18Multi` runs `ocr review` **once** for the whole change set and groups
|
|
126
|
+
the returned comments by language. A Python+Go change costs one review, not two;
|
|
127
|
+
the unit suite asserts the spawn count rather than observing it manually.
|
|
49
128
|
|
|
50
|
-
|
|
129
|
+
A range with no routed language SKIPS the invocation entirely and returns
|
|
130
|
+
`state: 'no-routed-language'`. Spawning OCR to discover there is nothing to
|
|
131
|
+
review is exactly the cost this guard exists to avoid.
|
|
132
|
+
|
|
133
|
+
## 6. The four outcomes
|
|
134
|
+
|
|
135
|
+
| # | Outcome | Where it is expressed |
|
|
51
136
|
|---|---|---|
|
|
52
|
-
|
|
|
53
|
-
|
|
|
54
|
-
| `
|
|
55
|
-
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
137
|
+
| 1 | language detected, findings returned | `languages[].count > 0` |
|
|
138
|
+
| 2 | language detected, zero findings | `languages[].count === 0` with `state: 'ok'` |
|
|
139
|
+
| 3 | file present, format not reviewed as a routed language | `unsupportedFiles[]` (and `state: 'no-routed-language'` when that is all the range holds) |
|
|
140
|
+
| 4 | OCR could not run | `state` in `ocr18-missing` / `execution-failed`, **`languages: []`**, `summary: null` |
|
|
141
|
+
|
|
142
|
+
No two of these collapse. A zero is only ever reported with `state: 'ok'`, so a
|
|
143
|
+
zero cannot be confused with "never ran"; a failure carries no language reports
|
|
144
|
+
at all. When the CLI reports outcome 4 it also runs `detect-ocr-18` and puts the
|
|
145
|
+
detector's own state (`binary-missing`, `llm-config-missing`, …) in
|
|
146
|
+
`data.detector`.
|
|
147
|
+
|
|
148
|
+
## 7. Invocation
|
|
149
|
+
|
|
150
|
+
Single language (unchanged, still supported):
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
peaks code-review run-ocr-18 --language python --from main --to HEAD --json
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Multi-language, the code-review step's form:
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
peaks code-review run-ocr-18 --languages auto --from <base> --to HEAD --json
|
|
160
|
+
peaks code-review run-ocr-18 --languages ts,js,go --from <base> --to HEAD --json
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
- `auto` detects from the range.
|
|
164
|
+
- A csv resolves through the routing table: language names (`python`) and
|
|
165
|
+
extensions (`ts`, `.py`) both work, because both are the same table.
|
|
166
|
+
- `--language` and `--languages` together are refused with a message naming both.
|
|
167
|
+
- `--delegate` is not language-scoped (`ocr delegate preview` ignores a language)
|
|
168
|
+
and is refused alongside `--languages`.
|
|
169
|
+
|
|
170
|
+
## 8. Gate B3 — dual-track for TypeScript/JavaScript
|
|
171
|
+
|
|
172
|
+
ESLint stays the PRIMARY gate for `.ts/.tsx/.js/.jsx/.mjs/.cjs`. The OCR pass is
|
|
173
|
+
a SUPPLEMENTARY semantic review of the same change set. This is a user decision,
|
|
174
|
+
not an accident: neither tool silently replaces the other.
|
|
175
|
+
|
|
176
|
+
The RD code-review artifact records the two outcomes separately, each finding
|
|
177
|
+
attributed to the tool that produced it, so a defect flagged by both is not
|
|
178
|
+
counted twice.
|
|
179
|
+
|
|
180
|
+
## 9. Degradation
|
|
181
|
+
|
|
182
|
+
When OCR cannot run, the code-review step records **`OCR unavailable`** plus the
|
|
183
|
+
detector state. It is never recorded as a clean review, and it never blocks the
|
|
184
|
+
rest of code review: the ESLint track and the rest of Gate B3 proceed.
|
|
185
|
+
|
|
186
|
+
## 10. Delegation mode — the no-credential review path
|
|
187
|
+
|
|
188
|
+
OCR has two review paths. They share the file selection and the rules; they differ
|
|
189
|
+
in who runs the model.
|
|
190
|
+
|
|
191
|
+
| Path | Command | Needs a provider key |
|
|
192
|
+
|---|---|---|
|
|
193
|
+
| API | `peaks code-review run-ocr-18 --languages auto …` | **yes** (OCR's own config) |
|
|
194
|
+
| Delegated | `peaks code-review run-ocr-18 --delegate --rid <rid> …` | **no** |
|
|
195
|
+
|
|
196
|
+
Prefer the delegated path whenever no provider is configured — it is the default
|
|
197
|
+
there, and it is the only path that works on a session authenticated through
|
|
198
|
+
`ANTHROPIC_AUTH_TOKEN` or a non-Anthropic endpoint, because OCR reads neither.
|
|
199
|
+
Prefer the API path when a provider **is** configured and you want OCR's own agent
|
|
200
|
+
and prompts.
|
|
201
|
+
|
|
202
|
+
Delegation is two phases. Neither phase calls an LLM from the CLI.
|
|
203
|
+
|
|
204
|
+
### 10.1 Phase 1 — the packet
|
|
205
|
+
|
|
206
|
+
```
|
|
207
|
+
peaks code-review run-ocr-18 --delegate --rid <rid> --from <base> --to HEAD --json
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
- `--languages auto` is accepted (detection, not scope). An explicit list and
|
|
211
|
+
`--language` are refused: `ocr delegate preview` takes no language.
|
|
212
|
+
- `--rid` is required. The packet is named after it.
|
|
213
|
+
- No routed language skips both OCR invocations, exactly like the API path.
|
|
214
|
+
|
|
215
|
+
Written to `.peaks/_runtime/<sid>/rd/ocr-delegate/<rid>-packet.json` and returned in
|
|
216
|
+
the envelope (with `packetPath`). Contents:
|
|
217
|
+
|
|
218
|
+
```json
|
|
219
|
+
{
|
|
220
|
+
"schema_version": "1", "mode": "delegate", "state": "awaiting-envelope",
|
|
221
|
+
"findings": null, "rid": "…", "session": "…",
|
|
222
|
+
"git": { "from": "main", "to": "HEAD", "commit": null },
|
|
223
|
+
"detection": { "languages": ["typescript"], "changed_file_count": 2, "unsupported_files": ["README.md"] },
|
|
224
|
+
"cost": { "total_files": 2, "reviewable_count": 1, "excluded_count": 1,
|
|
225
|
+
"total_insertions": 30, "total_deletions": 5 },
|
|
226
|
+
"selected_files": [ { "path": "src/a.ts", "status": "modified", "insertions": 30,
|
|
227
|
+
"deletions": 5, "language": "typescript", "pattern": "**/*.{ts,js}" } ],
|
|
228
|
+
"excluded_files": [ { "path": "README.md", "status": "modified", "insertions": 2,
|
|
229
|
+
"deletions": 0, "exclude_reason": "unsupported_ext" } ],
|
|
230
|
+
"rules": [ { "group_id": 1, "source": "system", "pattern": "**/*.{ts,js}",
|
|
231
|
+
"files": ["src/a.ts"], "rule": "…resolved rule text…" } ],
|
|
232
|
+
"warnings": [], "raw_output": null
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
- `selected_files[].pattern` is the `pattern` of the `rules[]` group that claimed
|
|
237
|
+
the file — the join the agent needs to apply the right rule. A file no group
|
|
238
|
+
claimed carries `pattern: null` and a `warnings[]` entry; the CLI never invents a
|
|
239
|
+
pattern.
|
|
240
|
+
- `excluded_files` is OCR's own exclusion list with its `exclude_reason`.
|
|
241
|
+
- `cost` is the number to read before reviewing: a large change set is expensive in
|
|
242
|
+
the session's remaining context, not in a billing account.
|
|
243
|
+
- `findings` is **always `null`** here.
|
|
244
|
+
|
|
245
|
+
Packet states, all with `findings: null`:
|
|
246
|
+
|
|
247
|
+
| State | Meaning |
|
|
248
|
+
|---|---|
|
|
249
|
+
| `no-routed-language` | zero changed files in the range |
|
|
250
|
+
| `unsupported-files-only` | files changed, none routed |
|
|
251
|
+
| `ocr-unavailable` | the CLI failed or did not return a delegation payload |
|
|
252
|
+
| `awaiting-envelope` | packet written, host review not recorded yet |
|
|
253
|
+
|
|
254
|
+
### 10.2 Phase 2 — the envelope and the record verb
|
|
255
|
+
|
|
256
|
+
The host agent reviews `selected_files` against `rules[].rule` (and the diff) and
|
|
257
|
+
writes an envelope **file** (the verb takes its path, not inline JSON). The envelope
|
|
258
|
+
mirrors OCR's own `LlmComment`, so the mapping is shared:
|
|
259
|
+
|
|
260
|
+
```json
|
|
261
|
+
{ "schema_version": "1",
|
|
262
|
+
"packet": ".peaks/_runtime/<sid>/rd/ocr-delegate/<rid>-packet.json",
|
|
263
|
+
"findings": [ { "path": "src/a.ts", "content": "why it is a defect",
|
|
264
|
+
"start_line": 12, "end_line": 12,
|
|
265
|
+
"severity": "high", "category": "bug" } ] }
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
- `packet` is required and must name the packet the findings belong to.
|
|
269
|
+
- `findings` must be an array. An empty array is a **clean review**; a missing array
|
|
270
|
+
is malformed, because the CLI will not guess which one you meant.
|
|
271
|
+
- `severity` must be one of `error|critical|high|warn|warning|medium|info|low`.
|
|
272
|
+
Unknown values are refused rather than mapped to `info`.
|
|
273
|
+
- `category` is optional; it becomes `ruleId`.
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
peaks code-review ocr-delegate-record --packet <packet-path> --envelope <envelope-path> --json
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
The verb refuses (non-zero exit) rather than coercing:
|
|
280
|
+
|
|
281
|
+
- a malformed envelope, naming the offending entry (`findings[2].start_line must be a
|
|
282
|
+
positive integer`);
|
|
283
|
+
- an envelope whose `packet` names a different file than `--packet`;
|
|
284
|
+
- a packet that does not exist, is not a delegation packet, lies outside the project
|
|
285
|
+
root, or is not in state `awaiting-envelope` (a `no-routed-language` packet has no
|
|
286
|
+
review to record).
|
|
287
|
+
|
|
288
|
+
On success it writes `<rid>-packet.findings.json` beside the packet and returns
|
|
289
|
+
`state: "recorded"`, `findingsPath`, the findings and a summary. Recording does not
|
|
290
|
+
advance the packet — the findings document is the record — so recording again
|
|
291
|
+
replaces the earlier findings file and reports `replaced: true`.
|
|
292
|
+
|
|
293
|
+
### 10.3 Not executed is not clean
|
|
294
|
+
|
|
295
|
+
| Situation | Shape |
|
|
296
|
+
|---|---|
|
|
297
|
+
| packet written, no envelope recorded | packet `state: "awaiting-envelope"`, `findings: null` |
|
|
298
|
+
| review ran, zero findings | document `state: "recorded"`, `findings: []`, `summary.total: 0` |
|
|
299
|
+
| review ran, findings | document `state: "recorded"`, `findings: [...]` |
|
|
300
|
+
|
|
301
|
+
The record verb is the only producer of the second and third shapes, so a packet
|
|
302
|
+
cannot be turned into a clean review without an envelope. A count-only summary
|
|
303
|
+
cannot express "the agent never ran"; the `null` versus `[]` distinction is what
|
|
304
|
+
does.
|
|
305
|
+
|
|
306
|
+
Every recorded finding carries `attribution: "ocr-delegate"`, and so does the
|
|
307
|
+
document. A host-model finding is not an OCR finding: the selection and the rules
|
|
308
|
+
are OCR's, the review is this model's, and the artifact must not let it inherit
|
|
309
|
+
OCR's benchmark numbers.
|
|
310
|
+
|
|
311
|
+
### 10.4 The selection preview verb is not a review
|
|
312
|
+
|
|
313
|
+
`peaks code-review ocr-18-delegate-preview --json` prints what
|
|
314
|
+
`ocr delegate preview --format json` returns: the reviewable and excluded files and
|
|
315
|
+
the cost, and nothing else. It is a **selection preview**. It no longer feeds that
|
|
316
|
+
payload through the `comments[]` review parser — doing so is what kept delegation
|
|
317
|
+
from ever producing a finding.
|
|
122
318
|
|
|
123
319
|
## Cross-references
|
|
124
320
|
|
|
125
|
-
-
|
|
126
|
-
-
|
|
127
|
-
-
|
|
128
|
-
-
|
|
129
|
-
-
|
|
130
|
-
- Detect: `src/services/lint/detect-ocr-18.ts`
|
|
131
|
-
- CLI: `src/cli/commands/code-review-commands.ts`
|
|
132
|
-
|
|
321
|
+
- Runner (API path): `src/services/lint/ocr-multilang-adapter.ts`
|
|
322
|
+
- Delegation payload parsers: `src/services/lint/ocr-18-delegate-payload.ts`
|
|
323
|
+
- Packet builder and states: `src/services/lint/ocr-18-delegate-packet.ts`
|
|
324
|
+
- Envelope validation and recording: `src/services/lint/ocr-18-delegate-record.ts`
|
|
325
|
+
- Allowlist snapshot: `src/services/lint/ocr-18-allowlist.ts`
|
|
326
|
+
- Detect / acquire: `src/services/lint/detect-ocr-18.ts`, `src/services/lint/ocr-18-acquire.ts`
|
|
327
|
+
- CLI: `src/cli/commands/code-review-commands.ts`, `src/cli/commands/code-review-run-ocr-18.ts`,
|
|
328
|
+
`src/cli/commands/code-review-ocr-delegate.ts`
|
|
329
|
+
- Tests: `tests/unit/services/lint/ocr-multilang-adapter.test.ts`,
|
|
330
|
+
`tests/unit/services/lint/ocr-18-delegate-payload.test.ts`,
|
|
331
|
+
`tests/unit/services/lint/ocr-18-delegate-packet.test.ts`,
|
|
332
|
+
`tests/unit/services/lint/ocr-18-delegate-record.test.ts`,
|
|
333
|
+
`tests/unit/cli/commands/code-review-run-ocr-18.test.ts`,
|
|
334
|
+
`tests/unit/cli/commands/code-review-ocr-delegate.test.ts`
|
|
335
|
+
- ECC bridge (the production JS/TS ESLint path): `src/services/code-review/ecc-bridge.ts`
|