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.
Files changed (38) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +78 -0
  3. package/README-en.md +1 -1
  4. package/README.md +1 -1
  5. package/dist/cli/commands/code-review-commands.d.ts +1 -1
  6. package/dist/cli/commands/code-review-commands.js +23 -37
  7. package/dist/cli/commands/code-review-ocr-delegate-record.d.ts +3 -0
  8. package/dist/cli/commands/code-review-ocr-delegate-record.js +73 -0
  9. package/dist/cli/commands/code-review-ocr-delegate.d.ts +12 -0
  10. package/dist/cli/commands/code-review-ocr-delegate.js +140 -0
  11. package/dist/cli/commands/code-review-run-ocr-18.d.ts +11 -0
  12. package/dist/cli/commands/code-review-run-ocr-18.js +127 -0
  13. package/dist/services/code/orchestrator-can-do-probes.d.ts +10 -0
  14. package/dist/services/code/orchestrator-can-do-probes.js +12 -2
  15. package/dist/services/lint/detect-ocr-18.js +1 -1
  16. package/dist/services/lint/ocr-18-acquire.d.ts +1 -1
  17. package/dist/services/lint/ocr-18-acquire.js +2 -2
  18. package/dist/services/lint/ocr-18-allowlist.d.ts +30 -0
  19. package/dist/services/lint/ocr-18-allowlist.js +165 -0
  20. package/dist/services/lint/ocr-18-delegate-packet.d.ts +84 -0
  21. package/dist/services/lint/ocr-18-delegate-packet.js +175 -0
  22. package/dist/services/lint/ocr-18-delegate-payload.d.ts +67 -0
  23. package/dist/services/lint/ocr-18-delegate-payload.js +208 -0
  24. package/dist/services/lint/ocr-18-delegate-record.d.ts +42 -0
  25. package/dist/services/lint/ocr-18-delegate-record.js +223 -0
  26. package/dist/services/lint/ocr-18-language-routing.d.ts +96 -0
  27. package/dist/services/lint/ocr-18-language-routing.js +148 -0
  28. package/dist/services/lint/ocr-18-multi.d.ts +54 -0
  29. package/dist/services/lint/ocr-18-multi.js +184 -0
  30. package/dist/services/lint/ocr-multilang-adapter.d.ts +45 -7
  31. package/dist/services/lint/ocr-multilang-adapter.js +133 -94
  32. package/dist/services/scan/archetype-service.js +24 -8
  33. package/dist/services/scan/frontend-evidence.d.ts +19 -0
  34. package/dist/services/scan/frontend-evidence.js +142 -0
  35. package/dist/services/scan/scan-types.d.ts +8 -1
  36. package/package.json +10 -10
  37. package/skills/bee/peaks-rd/SKILL.md +32 -0
  38. package/skills/bee/peaks-rd/references/ocr-multilang-1.8.md +314 -111
@@ -1,152 +1,191 @@
1
1
  /**
2
- * OCR 1.8.x multi-language reviewer adapter. Routes one of the
3
- * 8 supported languages to the corresponding `ocr review` filter.
2
+ * OCR 1.x reviewer adapter: builds the argv, spawns the pinned runtime, and maps
3
+ * its real `comments[]` envelope onto `Ocr18Finding`.
4
+ *
5
+ * The pinned CLI has NO language flag — `--filter-language` is not a flag of the
6
+ * real binary (`Error: unknown flag`) — so this module never emits one. Language
7
+ * attribution lives in `ocr-18-language-routing.ts` and the one-review-many-
8
+ * languages path in `ocr-18-multi.ts`.
4
9
  */
5
10
  import { spawnSync } from 'node:child_process';
6
11
  import { resolveNpxInvocation } from './npx-resolver.js';
7
- export const OCR_18_PACKAGE = '@alibaba-group/open-code-review@1.8.9';
8
- export const OCR_18_LANGUAGES = [
9
- 'python',
10
- 'go',
11
- 'java',
12
- 'rust',
13
- 'cpp',
14
- 'csharp',
15
- 'ruby',
16
- 'php'
17
- ];
18
- function isSupportedLanguage(value) {
19
- return OCR_18_LANGUAGES.includes(value);
20
- }
21
- function severityFor(value) {
22
- if (value === 'error' || value === 'critical' || value === 2)
12
+ import { isSupportedLanguage, languageForPath, OCR_18_LANGUAGES } from './ocr-18-language-routing.js';
13
+ export const OCR_18_PACKAGE = '@alibaba-group/open-code-review@1.13.1';
14
+ /**
15
+ * The one severity map: OCR comments (`parseComments`) and the delegated
16
+ * envelope (`ocr-18-delegate-record`) both map through it, so the two cannot
17
+ * disagree about what `high` means.
18
+ */
19
+ export function severityFor(value) {
20
+ if (value === 'error' || value === 'critical' || value === 'high' || value === 2)
23
21
  return 'error';
24
- if (value === 'warn' || value === 'warning' || value === 1)
22
+ if (value === 'warn' || value === 'warning' || value === 'medium' || value === 1)
25
23
  return 'warn';
26
24
  return 'info';
27
25
  }
28
- function emptyByLanguage() {
26
+ export function emptyByLanguage() {
29
27
  const out = {};
30
- for (const lang of OCR_18_LANGUAGES) {
31
- out[lang] = 0;
28
+ for (const language of OCR_18_LANGUAGES) {
29
+ out[language] = 0;
32
30
  }
33
31
  return out;
34
32
  }
33
+ export function rangeArgs(range) {
34
+ const args = [];
35
+ if (range.from !== undefined)
36
+ args.push('--from', range.from);
37
+ if (range.to !== undefined)
38
+ args.push('--to', range.to);
39
+ if (range.commit !== undefined)
40
+ args.push('--commit', range.commit);
41
+ return args;
42
+ }
43
+ /** The review argv — no language flag exists, and none is emitted. */
44
+ export function buildReviewArgs(range) {
45
+ return [
46
+ '--package',
47
+ OCR_18_PACKAGE,
48
+ '--',
49
+ 'ocr',
50
+ 'review',
51
+ ...rangeArgs(range),
52
+ '--format',
53
+ 'json'
54
+ ];
55
+ }
35
56
  export function buildOcr18Args(options) {
36
- if (!isSupportedLanguage(options.language)) {
37
- throw Object.assign(new Error(`unsupported language: ${options.language}`), {
38
- code: 'LANGUAGE_UNSUPPORTED'
39
- });
40
- }
41
- const args = ['--package', OCR_18_PACKAGE, '--', 'ocr'];
42
57
  if (options.delegate === true) {
43
- args.push('delegate', 'preview');
44
- if (options.from !== undefined)
45
- args.push('--from', options.from);
46
- if (options.to !== undefined)
47
- args.push('--to', options.to);
48
- if (options.commit !== undefined)
49
- args.push('--commit', options.commit);
58
+ // Delegation mode hands the host agent a spec and takes no language: the
59
+ // language is ignored by `ocr delegate preview`, so requiring one would be
60
+ // a value the code carries but does not mean.
61
+ return ['--package', OCR_18_PACKAGE, '--', 'ocr', 'delegate', 'preview', ...rangeArgs(options)];
50
62
  }
51
- else {
52
- args.push('review', '--filter-language', options.language);
53
- if (options.from !== undefined)
54
- args.push('--from', options.from);
55
- if (options.to !== undefined)
56
- args.push('--to', options.to);
57
- if (options.commit !== undefined)
58
- args.push('--commit', options.commit);
59
- args.push('--format', 'json');
63
+ if (options.language === undefined || !isSupportedLanguage(options.language)) {
64
+ throw Object.assign(new Error(`unsupported language: ${options.language ?? '<missing>'}`), {
65
+ code: 'LANGUAGE_UNSUPPORTED'
66
+ });
60
67
  }
61
- return args;
68
+ return buildReviewArgs(options);
62
69
  }
63
- export function runOcr18(options) {
64
- const start = Date.now();
65
- if (!isSupportedLanguage(options.language)) {
66
- return {
67
- state: 'language-unsupported',
68
- findings: [],
69
- summary: null,
70
- durationMs: Date.now() - start,
71
- rawOutput: `unsupported language: ${options.language}`
72
- };
73
- }
74
- const args = buildOcr18Args(options);
70
+ export function invokeOcr(args, cwd, timeoutMs) {
75
71
  const spawnOptions = {
76
- cwd: options.cwd,
72
+ cwd,
77
73
  encoding: 'utf8',
78
74
  // Repo convention: without this the child pops a console window on the
79
75
  // user's desktop — and this child can run for the length of a full review.
80
76
  windowsHide: true,
81
- timeout: options.timeoutMs ?? 60_000,
77
+ timeout: timeoutMs ?? 60_000,
82
78
  maxBuffer: 32 * 1024 * 1024
83
79
  };
84
80
  // 2026-09-10: bare `spawnSync('npx', …)` cannot launch the Windows `npx.cmd`
85
81
  // shim (ENOENT, no shell) — same fix and same helper as `detect-ocr-18.ts` /
86
- // `detect-eslint.ts`. `shell: true` is NOT an option: it would concatenate the
87
- // argv unescaped and split the `--package` flag.
88
- const { command, args: npxArgs, baseEnv } = resolveNpxInvocation(args);
82
+ // `detect-eslint.ts`. `shell: true` is NOT an option: it would concatenate
83
+ // the argv unescaped and split the `--package` flag.
84
+ const { command, args: npxArgs, baseEnv } = resolveNpxInvocation([...args]);
89
85
  const result = spawnSync(command, npxArgs, { ...spawnOptions, env: baseEnv });
90
86
  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
91
87
  const stderr = typeof result.stderr === 'string' ? result.stderr : '';
92
88
  if (result.error !== undefined && result.error !== null) {
93
89
  return {
90
+ ok: false,
94
91
  state: 'ocr18-missing',
95
- findings: [],
96
- summary: null,
97
- durationMs: Date.now() - start,
98
92
  // Never discard WHY the launch failed — stdout/stderr are both empty here.
99
93
  rawOutput: stderr || stdout || result.error.message
100
94
  };
101
95
  }
102
96
  if (result.status !== 0) {
97
+ return { ok: false, state: 'execution-failed', rawOutput: stderr || stdout };
98
+ }
99
+ return { ok: true, stdout, stderr };
100
+ }
101
+ /**
102
+ * `comments[]` from the real 1.13.1 envelope, mapped onto `Ocr18Finding`.
103
+ *
104
+ * A discriminated result rather than `null`: `{ ok: false }` is the execution
105
+ * failure the caller must report, and it cannot be mistaken for an empty review
106
+ * (which is `{ ok: true, findings: [] }`).
107
+ */
108
+ export function parseComments(stdout) {
109
+ let parsed;
110
+ try {
111
+ parsed = JSON.parse(stdout);
112
+ }
113
+ catch {
114
+ return { ok: false };
115
+ }
116
+ // A missing or non-array `comments` is a clean review, not a parse failure.
117
+ if (!Array.isArray(parsed.comments))
118
+ return { ok: true, findings: [] };
119
+ const findings = [];
120
+ for (const entry of parsed.comments) {
121
+ if (entry === null || typeof entry !== 'object')
122
+ continue;
123
+ const comment = entry;
124
+ findings.push({
125
+ filePath: typeof comment.path === 'string' ? comment.path : '',
126
+ line: typeof comment.start_line === 'number' ? comment.start_line : 0,
127
+ ruleId: typeof comment.category === 'string' ? comment.category : null,
128
+ severity: severityFor(comment.severity),
129
+ message: typeof comment.content === 'string' ? comment.content : ''
130
+ });
131
+ }
132
+ return { ok: true, findings };
133
+ }
134
+ export function summarize(findings, counts) {
135
+ const bySeverity = { error: 0, warn: 0, info: 0 };
136
+ for (const finding of findings)
137
+ bySeverity[finding.severity]++;
138
+ return { total: findings.length, bySeverity, byLanguage: counts };
139
+ }
140
+ export function runOcr18(options) {
141
+ const start = Date.now();
142
+ const language = options.language;
143
+ if (options.delegate !== true && (language === undefined || !isSupportedLanguage(language))) {
103
144
  return {
104
- state: 'execution-failed',
145
+ state: 'language-unsupported',
105
146
  findings: [],
106
147
  summary: null,
107
148
  durationMs: Date.now() - start,
108
- rawOutput: stderr || stdout
149
+ rawOutput: `unsupported language: ${language ?? '<missing>'}`
150
+ };
151
+ }
152
+ const invoked = invokeOcr(buildOcr18Args(options), options.cwd, options.timeoutMs);
153
+ if (!invoked.ok) {
154
+ return {
155
+ state: invoked.state,
156
+ findings: [],
157
+ summary: null,
158
+ durationMs: Date.now() - start,
159
+ rawOutput: invoked.rawOutput
109
160
  };
110
161
  }
111
162
  let findings = [];
112
- if (stdout.trim().length > 0) {
113
- try {
114
- const parsed = JSON.parse(stdout);
115
- if (Array.isArray(parsed.findings)) {
116
- for (const entry of parsed.findings) {
117
- if (entry === null || typeof entry !== 'object')
118
- continue;
119
- const f = entry;
120
- findings.push({
121
- filePath: typeof f.file === 'string' ? f.file : '',
122
- line: typeof f.line === 'number' ? f.line : 0,
123
- ruleId: typeof f.rule === 'string' ? f.rule : null,
124
- severity: severityFor(f.severity),
125
- message: typeof f.message === 'string' ? f.message : ''
126
- });
127
- }
128
- }
129
- }
130
- catch {
163
+ if (invoked.stdout.trim().length > 0) {
164
+ const parsed = parseComments(invoked.stdout);
165
+ if (!parsed.ok) {
131
166
  return {
132
167
  state: 'execution-failed',
133
168
  findings: [],
134
169
  summary: null,
135
170
  durationMs: Date.now() - start,
136
- rawOutput: stderr || stdout
171
+ rawOutput: invoked.stderr || invoked.stdout
137
172
  };
138
173
  }
174
+ // A single-language run reports only that language. Delegation mode has no
175
+ // language, and its preview carries no comments, so nothing is filtered.
176
+ findings =
177
+ language === undefined
178
+ ? parsed.findings
179
+ : parsed.findings.filter((finding) => languageForPath(finding.filePath) === language);
139
180
  }
140
- const bySeverity = { error: 0, warn: 0, info: 0 };
141
- for (const f of findings)
142
- bySeverity[f.severity]++;
143
- const byLanguageMut = { ...emptyByLanguage() };
144
- byLanguageMut[options.language] = findings.length;
181
+ const byLanguage = { ...emptyByLanguage() };
182
+ if (language !== undefined && isSupportedLanguage(language))
183
+ byLanguage[language] = findings.length;
145
184
  return {
146
185
  state: 'ok',
147
186
  findings,
148
- summary: { total: findings.length, bySeverity, byLanguage: byLanguageMut },
187
+ summary: summarize(findings, byLanguage),
149
188
  durationMs: Date.now() - start,
150
- rawOutput: stdout
189
+ rawOutput: invoked.stdout
151
190
  };
152
191
  }
@@ -2,6 +2,7 @@ import { readdir } from 'node:fs/promises';
2
2
  import { join } from 'node:path';
3
3
  import { isDirectory } from 'peaks-loop-shared/fs';
4
4
  import { detectBackendDirs, detectBackendFrameworks, detectMonorepoConfigs, detectNestedServiceEvidence, detectNextApiRoutes, detectNextServerActions, detectSwagger, GREENFIELD_MAX_SRC_FILES, GREENFIELD_MAX_LOCKFILE_DAYS, HIGH_CONFIDENCE_SIGNAL_COUNT, LEGACY_MIN_SRC_FILES, lockfileAgeDays, LOCKFILE_STALE_DAYS, readPackageJsonDeps } from './archetype-detection.js';
5
+ import { detectFrontendEvidence, frontendSignals, readRootBin } from './frontend-evidence.js';
5
6
  async function countSrcFiles(projectRoot, max = 500) {
6
7
  const srcDir = join(projectRoot, 'src');
7
8
  if (!(await isDirectory(srcDir))) {
@@ -93,9 +94,16 @@ function decideArchetype(detected) {
93
94
  matched: detected.lockfileAgeDays !== null && detected.lockfileAgeDays > LOCKFILE_STALE_DAYS,
94
95
  detail: detected.lockfileAgeDays === null ? 'no lockfile' : `${detected.lockfileAgeDays} days`
95
96
  });
97
+ signals.push(...frontendSignals(detected.hasBin, detected.frontendEvidence));
96
98
  if (!detected.hasPackageJson) {
97
99
  return { archetype: 'unknown', confidence: 'low', signals };
98
100
  }
101
+ // A published CLI is not a frontend. `bin` + no backend + no frontend
102
+ // evidence used to fall through to `frontend-monorepo` (monorepo config) or
103
+ // `legacy-frontend`, and `decideFrontendOnly` then called it frontend-only.
104
+ if (detected.hasBin && !hasBackend && detected.frontendEvidence === null) {
105
+ return { archetype: 'cli', confidence: 'high', signals };
106
+ }
99
107
  // Monorepo detection runs BEFORE the backend check: a monorepo with
100
108
  // a packages/server dir is a fullstack-monorepo, NOT legacy-fullstack.
101
109
  // backend sub-package fell through to `legacy-fullstack` because
@@ -146,17 +154,21 @@ function decideArchetype(detected) {
146
154
  return { archetype: 'unknown', confidence: 'low', signals };
147
155
  }
148
156
  function decideFrontendOnly(report) {
149
- if (report.archetype === 'legacy-frontend' || report.archetype === 'frontend-monorepo') {
150
- return { frontendOnly: true, reason: `archetype=${report.archetype}` };
157
+ if (report.archetype === 'cli') {
158
+ return { frontendOnly: false, reason: 'archetype=cli' };
151
159
  }
152
160
  const noBackend = !hasBackendEvidence(report.detected);
153
- if (noBackend && !report.detected.hasSwaggerOrProto) {
154
- return { frontendOnly: true, reason: 'no-backend-no-swagger' };
155
- }
156
- if (noBackend) {
161
+ if (noBackend && report.detected.hasSwaggerOrProto) {
157
162
  return { frontendOnly: false, reason: 'swagger-or-proto-present' };
158
163
  }
159
- return { frontendOnly: false, reason: 'backend-detected' };
164
+ if (!noBackend) {
165
+ return { frontendOnly: false, reason: 'backend-detected' };
166
+ }
167
+ const evidence = report.detected.frontendEvidence;
168
+ if (evidence === null) {
169
+ return { frontendOnly: false, reason: 'no-frontend-evidence' };
170
+ }
171
+ return { frontendOnly: true, reason: `frontend-evidence=${evidence}` };
160
172
  }
161
173
  /**
162
174
  * Three frontend integration scenarios, from the signals `detected`
@@ -177,7 +189,9 @@ function decideIntegrationMode(report) {
177
189
  export async function scanArchetype(options) {
178
190
  const { projectRoot } = options;
179
191
  const { exists: hasPackageJson, deps } = await readPackageJsonDeps(projectRoot);
192
+ const hasBin = await readRootBin(projectRoot);
180
193
  const backendFrameworks = await detectBackendFrameworks(deps);
194
+ const frontendEvidence = await detectFrontendEvidence(projectRoot, deps);
181
195
  const hasNext = Object.prototype.hasOwnProperty.call(deps, 'next');
182
196
  const hasNextApiRoutes = await detectNextApiRoutes(projectRoot, hasNext);
183
197
  const backendDirsPresent = await detectBackendDirs(projectRoot);
@@ -200,7 +214,9 @@ export async function scanArchetype(options) {
200
214
  hasNextApiRoutes,
201
215
  srcFileCount,
202
216
  backendDirsPresent,
203
- lockfileAgeDays: ageDays
217
+ lockfileAgeDays: ageDays,
218
+ hasBin,
219
+ frontendEvidence
204
220
  };
205
221
  const { archetype, confidence, signals } = decideArchetype(detected);
206
222
  const base = { archetype, confidence, signals, detected };
@@ -0,0 +1,19 @@
1
+ import type { ArchetypeSignal } from './scan-types.js';
2
+ /** Each list entry is the evidence CLASS returned to the caller, so the report
3
+ * can say what it saw instead of only the verdict. */
4
+ export declare const FRONTEND_FRAMEWORK_DEPS: string[];
5
+ export declare const FRONTEND_STYLE_DEPS: string[];
6
+ export declare const FRONTEND_APPLICATION_ROOTS: string[];
7
+ /** Upper bound on directory entries inspected per scan. An absent signal is the
8
+ * common case (every CLI and library), so the walk must stop even in a huge
9
+ * tree; a miss costs one skipped UI flow, a false positive costs a wrong
10
+ * project classification. */
11
+ export declare const FRONTEND_EVIDENCE_MAX_ENTRIES = 2000;
12
+ export declare function readRootBin(projectRoot: string): Promise<boolean>;
13
+ /** `null` when the repository has no positive frontend signal. Order is
14
+ * deliberate: a framework dep is stronger than a style dep, which is stronger
15
+ * than a file that could be a one-off. */
16
+ export declare function detectFrontendEvidence(projectRoot: string, deps: Record<string, string>): Promise<string | null>;
17
+ /** The two report signals this probe contributes, so the archetype service does
18
+ * not spend its line budget rebuilding them. */
19
+ export declare function frontendSignals(hasBin: boolean, evidence: string | null): ArchetypeSignal[];
@@ -0,0 +1,142 @@
1
+ // Positive frontend evidence for `scanArchetype`.
2
+ //
3
+ // "No backend" is not evidence of a frontend: a TypeScript CLI has neither and
4
+ // was reported `frontendOnly: true`. This module answers the opposite question —
5
+ // does the repository declare a frontend framework, a CSS-adjacent dependency,
6
+ // or carry a css/html-family asset under an application root? A `null` answer is
7
+ // the absence of an observation, and the caller reports it as
8
+ // `no-frontend-evidence`.
9
+ //
10
+ // The walk is scoped to application roots on purpose: an unscoped tree walk
11
+ // finds `examples/video-demo/src/styles.css` and the HTML under `skills/`, and
12
+ // calls a CLI a frontend.
13
+ import { readdir } from 'node:fs/promises';
14
+ import { join } from 'node:path';
15
+ import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
16
+ /** Each list entry is the evidence CLASS returned to the caller, so the report
17
+ * can say what it saw instead of only the verdict. */
18
+ export const FRONTEND_FRAMEWORK_DEPS = [
19
+ 'react',
20
+ 'react-dom',
21
+ 'vue',
22
+ 'svelte',
23
+ 'next',
24
+ 'nuxt',
25
+ '@angular/core',
26
+ 'solid-js',
27
+ 'preact',
28
+ 'astro',
29
+ 'gatsby',
30
+ 'remix'
31
+ ];
32
+ export const FRONTEND_STYLE_DEPS = [
33
+ 'tailwindcss',
34
+ 'sass',
35
+ 'less',
36
+ 'postcss',
37
+ 'styled-components',
38
+ '@emotion/react',
39
+ 'bootstrap'
40
+ ];
41
+ export const FRONTEND_APPLICATION_ROOTS = ['src', 'app', 'pages', 'components', 'public'];
42
+ /** Upper bound on directory entries inspected per scan. An absent signal is the
43
+ * common case (every CLI and library), so the walk must stop even in a huge
44
+ * tree; a miss costs one skipped UI flow, a false positive costs a wrong
45
+ * project classification. */
46
+ export const FRONTEND_EVIDENCE_MAX_ENTRIES = 2000;
47
+ const ASSET_EXTENSIONS = /\.(css|scss|sass|less|styl|html|htm|vue|svelte)$/;
48
+ /** Generated / installed trees never hold the project's own styles. */
49
+ const WALK_SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage']);
50
+ function firstDeclared(deps, names) {
51
+ return names.find((name) => Object.prototype.hasOwnProperty.call(deps, name)) ?? null;
52
+ }
53
+ /** `bin` counts only when it points somewhere: a string or an object of strings. */
54
+ function hasNonEmptyBin(bin) {
55
+ if (typeof bin === 'string')
56
+ return bin.trim().length > 0;
57
+ if (bin === null || typeof bin !== 'object')
58
+ return false;
59
+ return Object.values(bin).some((value) => typeof value === 'string' && value.trim().length > 0);
60
+ }
61
+ export async function readRootBin(projectRoot) {
62
+ const pkgPath = join(projectRoot, 'package.json');
63
+ if (!(await pathExists(pkgPath)))
64
+ return false;
65
+ try {
66
+ const parsed = JSON.parse(await readText(pkgPath));
67
+ return hasNonEmptyBin(parsed.bin);
68
+ }
69
+ catch {
70
+ // An unreadable manifest is not a CLI claim, and not an absence of one
71
+ // either; `false` says only "no bin evidence was observed".
72
+ return false;
73
+ }
74
+ }
75
+ function isAssetFile(entry) {
76
+ return !entry.isDirectory() && ASSET_EXTENSIONS.test(entry.name);
77
+ }
78
+ function isSkippedDir(name) {
79
+ return name.startsWith('.') || WALK_SKIP_DIRS.has(name);
80
+ }
81
+ async function readDirSafe(dir) {
82
+ return readdir(dir, { withFileTypes: true }).catch(() => []);
83
+ }
84
+ async function assetUnderRoot(rootDir) {
85
+ const queue = [rootDir];
86
+ let inspected = 0;
87
+ while (queue.length > 0 && inspected < FRONTEND_EVIDENCE_MAX_ENTRIES) {
88
+ const current = queue.shift();
89
+ if (current === undefined)
90
+ break;
91
+ const entries = await readDirSafe(current);
92
+ inspected += entries.length;
93
+ if (entries.some(isAssetFile))
94
+ return true;
95
+ for (const entry of entries) {
96
+ if (entry.isDirectory() && !isSkippedDir(entry.name)) {
97
+ queue.push(join(current, entry.name));
98
+ }
99
+ }
100
+ }
101
+ return false;
102
+ }
103
+ /** The class names the whole asset family, not the extension that matched:
104
+ * a css, html, vue, or svelte file under `<root>` is `asset-under-<root>`. */
105
+ async function assetUnderApplicationRoots(projectRoot) {
106
+ for (const root of FRONTEND_APPLICATION_ROOTS) {
107
+ const rootDir = join(projectRoot, root);
108
+ if (!(await isDirectory(rootDir)))
109
+ continue;
110
+ if (await assetUnderRoot(rootDir))
111
+ return `asset-under-${root}`;
112
+ }
113
+ return null;
114
+ }
115
+ /** `null` when the repository has no positive frontend signal. Order is
116
+ * deliberate: a framework dep is stronger than a style dep, which is stronger
117
+ * than a file that could be a one-off. */
118
+ export async function detectFrontendEvidence(projectRoot, deps) {
119
+ const framework = firstDeclared(deps, FRONTEND_FRAMEWORK_DEPS);
120
+ if (framework !== null)
121
+ return framework;
122
+ const style = firstDeclared(deps, FRONTEND_STYLE_DEPS);
123
+ if (style !== null)
124
+ return style;
125
+ return assetUnderApplicationRoots(projectRoot);
126
+ }
127
+ /** The two report signals this probe contributes, so the archetype service does
128
+ * not spend its line budget rebuilding them. */
129
+ export function frontendSignals(hasBin, evidence) {
130
+ return [
131
+ {
132
+ name: 'bin',
133
+ matched: hasBin,
134
+ detail: hasBin ? 'package.json declares bin' : 'no bin in package.json'
135
+ },
136
+ {
137
+ name: 'frontend-evidence',
138
+ matched: evidence !== null,
139
+ detail: evidence ?? 'no frontend framework, style dependency, or css/html under an application root'
140
+ }
141
+ ];
142
+ }
@@ -1,4 +1,4 @@
1
- export type ProjectArchetype = 'greenfield' | 'legacy-frontend' | 'legacy-fullstack' | 'frontend-monorepo' | 'fullstack-monorepo' | 'unknown';
1
+ export type ProjectArchetype = 'greenfield' | 'legacy-frontend' | 'legacy-fullstack' | 'frontend-monorepo' | 'fullstack-monorepo' | 'cli' | 'unknown';
2
2
  export type ArchetypeSignal = {
3
3
  name: string;
4
4
  matched: boolean;
@@ -39,6 +39,13 @@ export type ArchetypeReport = {
39
39
  srcFileCount: number;
40
40
  backendDirsPresent: string[];
41
41
  lockfileAgeDays: number | null;
42
+ /** The root `package.json` declares a non-empty `bin` entry. */
43
+ hasBin: boolean;
44
+ /** The strongest positive frontend signal observed, or `null` when none
45
+ * was. A frontend framework dep, a CSS-adjacent dep, or a css/html-family
46
+ * asset under an application root. `frontendOnly` is derived from this,
47
+ * never from "the repository is not a backend". */
48
+ frontendEvidence: string | null;
42
49
  };
43
50
  };
44
51
  export type VisualTokenSource = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.10",
3
+ "version": "4.1.12",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -121,18 +121,18 @@
121
121
  "node": ">=24.0.0"
122
122
  },
123
123
  "dependencies": {
124
- "@alibaba-group/open-code-review": "^1.8.9",
124
+ "@alibaba-group/open-code-review": "^1.13.1",
125
125
  "@colbymchenry/codegraph": "1.6.2",
126
- "@upstash/context7-mcp": "^4.0.2",
126
+ "@upstash/context7-mcp": "^4.4.4",
127
127
  "commander": "^12.1.0",
128
128
  "fzf": "^0.5.2",
129
- "picomatch": "4.0.4",
130
- "yaml": "^2.9.0",
131
- "zod": "^4.4.3",
132
- "peaks-loop-internal-runtime": "0.0.50",
133
- "peaks-loop-shared-channel": "0.0.67",
134
- "peaks-loop-shared": "0.0.99",
135
- "peaks-loop-mut": "0.1.64"
129
+ "picomatch": "4.0.7",
130
+ "yaml": "^2.9.1",
131
+ "zod": "^4.6.7",
132
+ "peaks-loop-internal-runtime": "0.0.52",
133
+ "peaks-loop-mut": "0.1.66",
134
+ "peaks-loop-shared": "0.0.101",
135
+ "peaks-loop-shared-channel": "0.0.69"
136
136
  },
137
137
  "devDependencies": {
138
138
  "@changesets/cli": "2.31.1",
@@ -187,6 +187,38 @@ Both audit skills consume the immutable peaks-prd handoff (`prd/handoff.md`) and
187
187
 
188
188
  Full dispatch contract (when-to-fan-out rules, dispatch template, prereq gates) lives in **`references/parallel-review-fanout.md`**. Read that file before issuing any 3-way fan-out.
189
189
 
190
+ ### Gate B3 — OCR 1.x supplementary pass (wired 2026-10-20)
191
+
192
+ When the diff touches any language the OCR bridge routes, run it as part of code review and record the outcome in the RD code-review artifact. There are **two paths**, and delegation is the default one when no provider is configured.
193
+
194
+ **Delegated path — no API key, no provider config.** The packet → host review → record cycle:
195
+
196
+ ```
197
+ peaks code-review run-ocr-18 --delegate --rid <rid> --from <base> --to HEAD --json
198
+ ```
199
+
200
+ writes `.peaks/_runtime/<sid>/rd/ocr-delegate/<rid>-packet.json` and returns it. The packet carries OCR's deterministic selection (each file with the pattern that selected it), the excluded files, the resolved rule text per group, the git range and the cost surface — nothing is LLM-generated. **You** then review the selected files against those rules with the model you are already running on, write a findings envelope to a file, and record it:
201
+
202
+ ```
203
+ peaks code-review ocr-delegate-record --packet <packet-path> --envelope <path> --json
204
+ ```
205
+
206
+ - Recorded findings keep the `Ocr18Finding` shape and carry `attribution: ocr-delegate`, so a host-model finding is never read as an OCR finding.
207
+ - A packet with no recorded envelope is **not executed** — never clean. The packet's `findings` is `null`; a recorded clean review has `findings: []`.
208
+ - The record verb refuses a malformed envelope (missing `path`/`content`, non-numeric line, unknown severity) and an envelope naming a different packet. Do not hand-edit its output.
209
+ - This path consumes your own context, not an API budget. Use the packet's cost surface to decide one pass or several.
210
+
211
+ **API path — a provider is configured.** Reviews once over the range with OCR's own agent:
212
+
213
+ ```
214
+ peaks code-review run-ocr-18 --languages auto --from <base> --to HEAD --json
215
+ ```
216
+
217
+ - `--languages auto` detects from the range and reviews **once**. A range with no routed language skips the invocation and says so — do not spawn OCR to discover there is nothing to review.
218
+ - Record four outcomes separately in `rd/code-review-<rid>.md`: languages with findings; languages detected with **zero** findings; files whose format is not reviewed as a routed language; and `OCR unavailable` with the `detect-ocr-18` state when it could not run. A missing run must never read as a clean review.
219
+ - TypeScript/JavaScript are **dual-track**: ESLint (`peaks lint check`, Gate B5) stays the primary gate, the OCR pass is supplementary. Attribute every finding to the tool that produced it, so a defect flagged twice is not counted twice.
220
+ - Real CLI surface, post-review scoping model, auto-detection, the four outcomes, both paths and the envelope: `references/ocr-multilang-1.8.md` §10 (rewritten for OCR 1.x; the old 1.8 content was wrong about `--filter-language`).
221
+
190
222
  ## Reviewer fan-out detached mode (Phase C, slice 2026-08-10)
191
223
 
192
224
  Reviewer fan-out may run in detached mode for any of the 3-way fan-out roles (`code-reviewer`, `qa-test-cases-writer`, `karpathy-reviewer`). Detached mode spawns a real OS process via `peaks sub-agent dispatch --mode detached --vendor <vendor>`, isolated from the orchestrator session. Use detached mode when the reviewer's expected runtime exceeds 60s OR processes ≥ 20 source files. Pass `--mode detached` explicitly per reviewer role; the default remains `in-process` (backward compat). The karpathy-reviewer's `<peaks-auto-compact>` marker is honored automatically when `--mode detached` is used. Note what that marker does and does not do (corrected 2026-09-13, rid `2026-09-13-defects-e`): it asks the child to persist durable state to `.peaks/_runtime/<sid>/detached/<rid>/compact/<n>.json` before its own harness compacts the session — the child cannot compact itself, and nothing is spliced back into its prompt. See `../../peaks-code/references/sub-agent-dispatch.md` §"Detached Mode" for the full contract.