peaks-loop 4.1.7 → 4.1.8

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 (73) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +47 -0
  3. package/config/eslint/tsconfig.lint.json +1 -0
  4. package/dist/cli/commands/dispatch-from-dag.js +17 -0
  5. package/dist/cli/commands/job-commands.js +15 -5
  6. package/dist/cli/commands/lint-baseline-command.d.ts +15 -0
  7. package/dist/cli/commands/lint-baseline-command.js +64 -0
  8. package/dist/cli/commands/lint-commands.js +27 -51
  9. package/dist/cli/commands/request-command-options.d.ts +6 -0
  10. package/dist/cli/commands/request-commands.js +2 -0
  11. package/dist/cli/commands/request-mark-qa-initiated-command.d.ts +3 -0
  12. package/dist/cli/commands/request-mark-qa-initiated-command.js +80 -0
  13. package/dist/cli/commands/request-transition-failures.js +1 -0
  14. package/dist/cli/commands/reviewer-commands.d.ts +6 -6
  15. package/dist/cli/commands/reviewer-commands.js +154 -56
  16. package/dist/cli/commands/reviewer-config-commands.d.ts +9 -0
  17. package/dist/cli/commands/reviewer-config-commands.js +133 -0
  18. package/dist/services/artifacts/artifact-lint-service.js +102 -27
  19. package/dist/services/artifacts/artifact-prerequisites.d.ts +1 -0
  20. package/dist/services/artifacts/artifact-prerequisites.js +13 -13
  21. package/dist/services/artifacts/artifact-template-bodies.d.ts +7 -1
  22. package/dist/services/artifacts/artifact-template-bodies.js +14 -3
  23. package/dist/services/artifacts/artifact-templates.d.ts +6 -1
  24. package/dist/services/artifacts/artifact-templates.js +8 -5
  25. package/dist/services/artifacts/backcompat-acceptance.js +7 -5
  26. package/dist/services/artifacts/prerequisite-checks.d.ts +34 -9
  27. package/dist/services/artifacts/prerequisite-checks.js +28 -9
  28. package/dist/services/artifacts/qa-initiated-marker.d.ts +24 -0
  29. package/dist/services/artifacts/qa-initiated-marker.js +36 -0
  30. package/dist/services/artifacts/request-artifact-metadata.d.ts +9 -0
  31. package/dist/services/artifacts/request-artifact-metadata.js +9 -0
  32. package/dist/services/artifacts/request-artifact-service.js +6 -10
  33. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +2 -1
  34. package/dist/services/artifacts/request-artifact-state-helpers.js +6 -3
  35. package/dist/services/dispatch/isolation-lease.d.ts +3 -2
  36. package/dist/services/dispatch/isolation-lease.js +15 -6
  37. package/dist/services/job/subagent-job-wrapper.d.ts +20 -7
  38. package/dist/services/job/subagent-job-wrapper.js +53 -5
  39. package/dist/services/lint/eslint-report.d.ts +19 -0
  40. package/dist/services/lint/eslint-report.js +60 -0
  41. package/dist/services/lint/eslint-runner-support.d.ts +18 -1
  42. package/dist/services/lint/eslint-runner-support.js +35 -2
  43. package/dist/services/lint/eslint-runner-types.d.ts +21 -1
  44. package/dist/services/lint/eslint-runner.js +43 -33
  45. package/dist/services/prd/gate-evidence-derivation.d.ts +2 -4
  46. package/dist/services/prd/gate-evidence-derivation.js +3 -1
  47. package/dist/services/qa/bdd-test-style-contract.d.ts +17 -0
  48. package/dist/services/qa/bdd-test-style-contract.js +41 -0
  49. package/dist/services/qa/bdd-test-style-verifier.d.ts +9 -6
  50. package/dist/services/qa/bdd-test-style-verifier.js +24 -37
  51. package/dist/services/rd/reviewer-dispatch-policy.d.ts +18 -14
  52. package/dist/services/rd/reviewer-dispatch-policy.js +14 -11
  53. package/dist/services/release/release-state.js +20 -5
  54. package/dist/services/reviewer/model-family.js +1 -1
  55. package/dist/services/reviewer/reviewer-artifacts.d.ts +12 -0
  56. package/dist/services/reviewer/reviewer-artifacts.js +67 -0
  57. package/dist/services/reviewer/reviewer-config-write.d.ts +18 -0
  58. package/dist/services/reviewer/reviewer-config-write.js +71 -0
  59. package/dist/services/reviewer/reviewer-config.d.ts +33 -5
  60. package/dist/services/reviewer/reviewer-config.js +102 -46
  61. package/dist/services/reviewer/reviewer-envelopes.d.ts +8 -0
  62. package/dist/services/reviewer/reviewer-envelopes.js +53 -0
  63. package/dist/services/reviewer/reviewer-service.d.ts +7 -4
  64. package/dist/services/reviewer/reviewer-service.js +46 -52
  65. package/dist/services/reviewer/reviewer-types.d.ts +9 -1
  66. package/dist/services/session/getSessionDir.js +16 -7
  67. package/dist/services/web/daemon-registry.d.ts +6 -4
  68. package/dist/services/web/daemon-registry.js +92 -17
  69. package/package.json +5 -5
  70. package/schemas/reviewer-envelope.schema.json +1 -1
  71. package/skills/bee/peaks-reviewer/SKILL.md +20 -4
  72. package/skills/bee/peaks-reviewer/references/reviewer-schema.md +12 -7
  73. package/skills/bee/peaks-security-audit/SKILL.md +20 -0
@@ -32,23 +32,26 @@
32
32
  * mechanism — an LLM reads prose, not TypeScript exports — and that is the
33
33
  * reason every export below sat at zero importers until slice F2.
34
34
  *
35
- * Pinning is half-done. The two test files this block used to cite —
36
- * element pinning) and
37
- * back-compat cases) — were both deleted in `f17aa377`. The **predicate
38
- * half** was re-pinned by `tests/unit/rd/reviewer-dispatch-policy.test.ts`
39
- * (`7191140f`, 6 cases: `RD_DEPRECATED_REVIEWERS` + `isDeprecatedReviewer`).
35
+ * Pinning is complete. The two test files this block used to cite were
36
+ * both deleted in `f17aa377`. The **predicate half**
37
+ * (`RD_DEPRECATED_REVIEWERS` + `isDeprecatedReviewer`) was re-pinned by
38
+ * `tests/unit/rd/reviewer-dispatch-policy.test.ts` (`7191140f`, 6 cases).
40
39
  * The **decision-table half** — `RD_FANOUT_REVIEWERS`' 3-element
41
40
  * membership, `reviewerListFor`, `karpathySlotIndex`,
42
- * `shouldDispatchKarpathy` — still has no pin.
41
+ * `shouldDispatchKarpathy` — is pinned by
42
+ * `tests/unit/rd/reviewer-dispatch-policy-decision-table.test.ts`,
43
+ * including the 5→3 relationship: the fanout request types are exactly
44
+ * the review request types `isFanoutTriggerType` accepts, and no
45
+ * deprecated reviewer appears in the returned list.
43
46
  *
44
47
  * `src/cli/commands/sub-agent-shared.ts` (`deprecatedReviewerWarnings`),
45
48
  * invoked from the dispatch chokepoint in
46
49
  * `src/cli/commands/dispatch-commands.ts` and pinned by
47
- * `tests/unit/cli/sub-agent-dispatch-deprecated-reviewer.test.ts`. Before
48
- * that, all 13 exports had zero importers across src/ + packages/ +
49
- * scripts/, so nothing rejected or rerouted `security-reviewer` /
50
- * `perf-baseline-reviewer` on the way in. That import is still the only
51
- * one: the other 12 exports below remain unreferenced in this repo.
50
+ * `tests/unit/cli/sub-agent-dispatch-deprecated-reviewer.test.ts`, is the
51
+ * only runtime importer. The decision-table exports are pinned by tests
52
+ * rather than imported, which is the point of the table. The three type
53
+ * aliases derived from the tuple constants are module-internal: no
54
+ * importer names them, so they are not exported.
52
55
  *
53
56
  * For `config | docs | chore` request types, the slice already skips
54
57
  * the entire fanout (SKILL.md line 132 says "Config / docs / chore: no
@@ -50,6 +50,14 @@ const STATE_FILE = '.peaks/release-state.json';
50
50
  export function getReleaseStatePath(projectRoot) {
51
51
  return resolve(projectRoot, STATE_FILE);
52
52
  }
53
+ /** A persisted record is only as trustworthy as its stage: `currentStage` is
54
+ * typed `ReleaseStage`, but it comes out of a JSON file nothing validated. */
55
+ function hasValidStage(value) {
56
+ if (typeof value !== 'object' || value === null)
57
+ return false;
58
+ const stage = value.currentStage;
59
+ return typeof stage === 'string' && isReleaseStage(stage);
60
+ }
53
61
  export function readReleaseState(projectRoot) {
54
62
  const path = getReleaseStatePath(projectRoot);
55
63
  if (!existsSync(path))
@@ -59,11 +67,18 @@ export function readReleaseState(projectRoot) {
59
67
  const parsed = JSON.parse(raw);
60
68
  if (parsed.version !== 1)
61
69
  return EMPTY_RELEASE_STATE;
62
- return {
63
- version: 1,
64
- active: parsed.active ?? null,
65
- history: Array.isArray(parsed.history) ? parsed.history : []
66
- };
70
+ const active = parsed.active ?? null;
71
+ const history = Array.isArray(parsed.history) ? parsed.history : [];
72
+ // Fail closed, exactly as the version check and the catch above do: a state
73
+ // file naming a stage this table no longer has (e.g. the dropped
74
+ // 'hotfixed') is a file this build cannot interpret. `transitionRelease`
75
+ // would otherwise throw on it (its error message indexes the stage table),
76
+ // so the reader is where an unknown stage has to stop.
77
+ if (active !== null && !hasValidStage(active))
78
+ return EMPTY_RELEASE_STATE;
79
+ if (!history.every(hasValidStage))
80
+ return EMPTY_RELEASE_STATE;
81
+ return { version: 1, active, history };
67
82
  }
68
83
  catch {
69
84
  return EMPTY_RELEASE_STATE;
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * model-family.ts — derive `modelFamily` from a `modelId` for the G4
3
- * `third-party-review.json.modelFamily !== karpathy-review.json.modelFamily`,
3
+ * `third-party-review-<rid>.json.modelFamily !== karpathy-review.json.modelFamily`,
4
4
  * so the family bucket must be stable, provider-distinguishing, and
5
5
  * version-tolerant (e.g. `claude-opus-4-8` and `claude-haiku-4-5` both
6
6
  * bucket to `claude`, while `gpt-4o-mini` and `gpt-3.5-turbo` bucket
@@ -0,0 +1,12 @@
1
+ import type { ReviewerEnvelope } from './reviewer-types.js';
2
+ export type ReviewerArtifactPaths = {
3
+ markdown: string;
4
+ json: string;
5
+ };
6
+ export declare function renderReviewerMarkdown(rid: string, envelope: ReviewerEnvelope): string;
7
+ export declare function writeReviewerArtifacts(input: {
8
+ projectRoot: string;
9
+ sessionId: string;
10
+ rid: string;
11
+ envelope: ReviewerEnvelope;
12
+ }): ReviewerArtifactPaths;
@@ -0,0 +1,67 @@
1
+ /**
2
+ * reviewer-artifacts.ts — the producer side of the G4 reviewer: writes
3
+ * `rd/third-party-review-<rid>.md` and `rd/third-party-review-<rid>.json` under
4
+ * the session's `.peaks/_runtime/<sessionId>/rd/`.
5
+ *
6
+ * Only a real verdict reaches here. The caller must not call this with a
7
+ * skip envelope (backlog §7.10 ④): a skip stays a skip.
8
+ */
9
+ import { mkdirSync, writeFileSync } from 'node:fs';
10
+ import { join } from 'node:path';
11
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
12
+ import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
13
+ /** One table cell: newlines and pipes from the model cannot break the table. */
14
+ function cell(value) {
15
+ return value.replace(/\r?\n/g, ' ').replace(/\|/g, '\\|');
16
+ }
17
+ export function renderReviewerMarkdown(rid, envelope) {
18
+ const violations = envelope.violations.length === 0
19
+ ? 'None.'
20
+ : envelope.violations
21
+ .map((v) => `- \`${cell(v.kind)}\` — ${cell(v.file)}:${String(v.line)} — ${cell(v.hint)}`)
22
+ .join('\n');
23
+ return [
24
+ `# third-party-review — ${cell(rid)}`,
25
+ '',
26
+ 'Schema-validated ReviewerEnvelope produced by `peaks reviewer run`.',
27
+ `The JSON sibling \`third-party-review-${cell(rid)}.json\` carries the same envelope.`,
28
+ '',
29
+ '| Field | Value |',
30
+ '| --- | --- |',
31
+ `| reviewerId | ${cell(envelope.reviewerId)} |`,
32
+ `| modelId | ${cell(envelope.modelId)} |`,
33
+ `| modelFamily | ${cell(envelope.modelFamily)} |`,
34
+ `| passed | ${String(envelope.passed)} |`,
35
+ `| gateAction | ${cell(envelope.gateAction)} |`,
36
+ `| reason | ${cell(envelope.reason)} |`,
37
+ '',
38
+ '## Violations',
39
+ '',
40
+ violations,
41
+ ''
42
+ ].join('\n');
43
+ }
44
+ export function writeReviewerArtifacts(input) {
45
+ // `isUnsafePathInput` is a traversal guard, not a single-segment guard: it
46
+ // admits `a/b`. The session id is ONE directory name under `_runtime/`, so
47
+ // the separator axes are refused here as well.
48
+ if (isUnsafePathInput(input.sessionId) ||
49
+ input.sessionId.includes('/') ||
50
+ input.sessionId.includes('\\')) {
51
+ throw new Error(`Invalid session id: ${input.sessionId} (must be a single path segment)`);
52
+ }
53
+ // The rid becomes a filename below, so the repo's own request-id guard runs
54
+ // before the first mkdir — a `..` segment must not reach `join`.
55
+ if (!REQUEST_ID_PATTERN.test(input.rid)) {
56
+ throw new Error(`Invalid request id: ${input.rid} (expected letters, digits, dots, underscores, or dashes)`);
57
+ }
58
+ const dir = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'rd');
59
+ mkdirSync(dir, { recursive: true });
60
+ const paths = {
61
+ markdown: join(dir, `third-party-review-${input.rid}.md`),
62
+ json: join(dir, `third-party-review-${input.rid}.json`)
63
+ };
64
+ writeFileSync(paths.markdown, renderReviewerMarkdown(input.rid, input.envelope), 'utf8');
65
+ writeFileSync(paths.json, JSON.stringify(input.envelope, null, 2), 'utf8');
66
+ return paths;
67
+ }
@@ -0,0 +1,18 @@
1
+ import { type ReviewerConfig, type ReviewerProviderConfig } from './reviewer-config.js';
2
+ /** Providers `reviewer-service.ts` can actually dispatch to. */
3
+ export declare const DISPATCHABLE_PROVIDER_NAMES: ReadonlyArray<string>;
4
+ export type ReviewerConfigWriteResult = {
5
+ ok: true;
6
+ path: string;
7
+ } | {
8
+ ok: false;
9
+ reason: 'unreadable-config';
10
+ message: string;
11
+ };
12
+ /** Null when valid; otherwise the reason the section cannot be written. */
13
+ export declare function validateReviewerSection(config: ReviewerConfig): string | null;
14
+ export declare function writeReviewerConfig(config: ReviewerConfig, options?: {
15
+ path?: string;
16
+ }): ReviewerConfigWriteResult;
17
+ /** `name:model`; the first colon splits, so `llama3.2:8b` survives. */
18
+ export declare function parseProviderSpec(spec: string): ReviewerProviderConfig | null;
@@ -0,0 +1,71 @@
1
+ /**
2
+ * reviewer-config-write.ts — write the `reviewer` section to
3
+ * `~/.peaks/config.json` on the user's behalf (backlog §7.10 ①).
4
+ *
5
+ * The LLM runs the CLI; the user never hand-authors JSON. The writer
6
+ * merges into the existing file so unrelated keys survive, and it refuses
7
+ * to overwrite a file it cannot parse rather than clobbering it.
8
+ */
9
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
10
+ import { dirname } from 'node:path';
11
+ import { defaultReviewerConfigPath } from './reviewer-config.js';
12
+ /** Providers `reviewer-service.ts` can actually dispatch to. */
13
+ export const DISPATCHABLE_PROVIDER_NAMES = ['ollama', 'anthropic', 'openai'];
14
+ function isRecord(value) {
15
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
16
+ }
17
+ /** Null when valid; otherwise the reason the section cannot be written. */
18
+ export function validateReviewerSection(config) {
19
+ if (config.providers.length < 2) {
20
+ return `at least 2 providers are required (got ${config.providers.length})`;
21
+ }
22
+ for (const provider of config.providers) {
23
+ if (!DISPATCHABLE_PROVIDER_NAMES.includes(provider.name)) {
24
+ return `unsupported provider "${provider.name}" (accepted: ${DISPATCHABLE_PROVIDER_NAMES.join(', ')})`;
25
+ }
26
+ if (provider.model.trim().length === 0) {
27
+ return `provider "${provider.name}" has an empty model id`;
28
+ }
29
+ }
30
+ return null;
31
+ }
32
+ export function writeReviewerConfig(config, options = {}) {
33
+ const path = options.path ?? defaultReviewerConfigPath();
34
+ let existing = {};
35
+ if (existsSync(path)) {
36
+ let parsed;
37
+ try {
38
+ parsed = JSON.parse(readFileSync(path, 'utf8'));
39
+ }
40
+ catch {
41
+ return {
42
+ ok: false,
43
+ reason: 'unreadable-config',
44
+ message: `${path} is not valid JSON; refusing to overwrite it`
45
+ };
46
+ }
47
+ if (!isRecord(parsed)) {
48
+ return {
49
+ ok: false,
50
+ reason: 'unreadable-config',
51
+ message: `${path} does not contain a JSON object; refusing to overwrite it`
52
+ };
53
+ }
54
+ existing = parsed;
55
+ }
56
+ const next = { ...existing, reviewer: config };
57
+ mkdirSync(dirname(path), { recursive: true });
58
+ writeFileSync(path, JSON.stringify(next, null, 2), 'utf8');
59
+ return { ok: true, path };
60
+ }
61
+ /** `name:model`; the first colon splits, so `llama3.2:8b` survives. */
62
+ export function parseProviderSpec(spec) {
63
+ const separator = spec.indexOf(':');
64
+ if (separator <= 0)
65
+ return null;
66
+ const name = spec.slice(0, separator).trim();
67
+ const model = spec.slice(separator + 1).trim();
68
+ if (name.length === 0 || model.length === 0)
69
+ return null;
70
+ return { name, model };
71
+ }
@@ -1,6 +1,7 @@
1
1
  export type ReviewerProviderName = 'ollama' | 'anthropic' | 'openai' | 'bedrock' | 'azure';
2
2
  export type ReviewerProviderConfig = {
3
- name: ReviewerProviderName | string;
3
+ /** A {@link ReviewerProviderName}, or any future provider name. */
4
+ name: string;
4
5
  model: string;
5
6
  endpoint?: string | undefined;
6
7
  apiKeyEnv?: string | undefined;
@@ -15,19 +16,46 @@ export type ReviewerConfig = {
15
16
  fallbackOnError: ReviewerFallbackMode;
16
17
  schemaPath: string;
17
18
  };
19
+ /** A4.1 — the reviewer needs at least two provider families to be usable. */
20
+ export declare const MIN_REVIEWER_PROVIDERS = 2;
21
+ /**
22
+ * Three states, so `peaks reviewer status` can tell "nothing configured"
23
+ * apart from "configured, but not enough providers" (backlog §7.10 ③).
24
+ * `providerCount` is the number of VALID entries after parsing, which is
25
+ * what the >=2 requirement is measured on.
26
+ */
18
27
  export type ReviewerConfigStatus = {
19
28
  ok: true;
20
29
  config: ReviewerConfig;
21
30
  } | {
22
31
  ok: false;
23
- reason: 'no-reviewer-config';
32
+ reason: 'no-reviewer-config' | 'insufficient-providers';
33
+ providerCount: number;
34
+ requiredProviders: number;
24
35
  };
25
36
  export declare function defaultReviewerConfigPath(): string;
37
+ /** Where a resolved ReviewerEnvelope schema came from. */
38
+ export type ReviewerSchemaSource = 'absolute' | 'project' | 'package';
39
+ export type ReviewerSchemaResolution = {
40
+ ok: true;
41
+ path: string;
42
+ source: ReviewerSchemaSource;
43
+ } | {
44
+ ok: false;
45
+ searched: string[];
46
+ };
47
+ /**
48
+ * Resolve the configured ReviewerEnvelope schema: an absolute path as-is,
49
+ * else the project-root copy (a project may override), else the copy bundled
50
+ * with the peaks-loop package — a consumer project does NOT ship `schemas/`,
51
+ * so the packaged copy is what makes the default path work there. When
52
+ * nothing resolves, every candidate is returned for the refusal message.
53
+ */
54
+ export declare function resolveReviewerSchema(projectRoot: string, schemaPath: string): ReviewerSchemaResolution;
26
55
  /**
27
56
  * Read + parse `~/.peaks/config.json` (or override path) and return the
28
- * `reviewer` section if present. NEVER throws on missing file — returns
29
- * `{ ok: false, reason: 'no-reviewer-config' }` instead so the CLI can
30
- * record the skip reason in the envelope.
57
+ * `reviewer` section if present. NEVER throws on missing file — the CLI
58
+ * records the skip reason in the envelope instead.
31
59
  */
32
60
  export declare function loadReviewerConfig(options?: {
33
61
  path?: string;
@@ -14,7 +14,10 @@
14
14
  */
15
15
  import { existsSync, readFileSync } from 'node:fs';
16
16
  import { homedir } from 'node:os';
17
- import { join } from 'node:path';
17
+ import { dirname, isAbsolute, join, resolve } from 'node:path';
18
+ import { fileURLToPath } from 'node:url';
19
+ /** A4.1 — the reviewer needs at least two provider families to be usable. */
20
+ export const MIN_REVIEWER_PROVIDERS = 2;
18
21
  const VALID_SELECTION = ['round-robin', 'hash', 'random'];
19
22
  const VALID_FALLBACK = ['skip', 'error'];
20
23
  export function defaultReviewerConfigPath() {
@@ -23,37 +26,43 @@ export function defaultReviewerConfigPath() {
23
26
  function isRecord(value) {
24
27
  return typeof value === 'object' && value !== null && !Array.isArray(value);
25
28
  }
26
- /**
27
- * Read + parse `~/.peaks/config.json` (or override path) and return the
28
- * `reviewer` section if present. NEVER throws on missing file — returns
29
- * `{ ok: false, reason: 'no-reviewer-config' }` instead so the CLI can
30
- * record the skip reason in the envelope.
31
- */
32
- export function loadReviewerConfig(options = {}) {
33
- const path = options.path ?? defaultReviewerConfigPath();
34
- if (!existsSync(path)) {
35
- return { ok: false, reason: 'no-reviewer-config' };
36
- }
29
+ function absentStatus() {
30
+ return {
31
+ ok: false,
32
+ reason: 'no-reviewer-config',
33
+ providerCount: 0,
34
+ requiredProviders: MIN_REVIEWER_PROVIDERS
35
+ };
36
+ }
37
+ function insufficientStatus(providerCount) {
38
+ return {
39
+ ok: false,
40
+ reason: 'insufficient-providers',
41
+ providerCount,
42
+ requiredProviders: MIN_REVIEWER_PROVIDERS
43
+ };
44
+ }
45
+ /** The `reviewer` object, or `{ ok: false }` when the file / section is absent or unreadable. */
46
+ function readSection(path) {
47
+ if (!existsSync(path))
48
+ return { ok: false };
37
49
  let raw;
38
50
  try {
39
51
  raw = JSON.parse(readFileSync(path, 'utf8'));
40
52
  }
41
53
  catch {
42
- return { ok: false, reason: 'no-reviewer-config' };
54
+ return { ok: false };
43
55
  }
44
56
  if (!isRecord(raw))
45
- return { ok: false, reason: 'no-reviewer-config' };
57
+ return { ok: false };
46
58
  const reviewer = raw['reviewer'];
47
- if (!isRecord(reviewer))
48
- return { ok: false, reason: 'no-reviewer-config' };
49
- const providersRaw = reviewer['providers'];
50
- if (!Array.isArray(providersRaw) || providersRaw.length < 2) {
51
- // A4.1 explicitly requires >=2 providers; with <2 we treat the
52
- // section as absent so the reviewer is skipped cleanly.
53
- return { ok: false, reason: 'no-reviewer-config' };
54
- }
59
+ return isRecord(reviewer) ? { ok: true, reviewer } : { ok: false };
60
+ }
61
+ function parseProviders(raw) {
62
+ if (!Array.isArray(raw))
63
+ return { providers: [], total: 0 };
55
64
  const providers = [];
56
- for (const entry of providersRaw) {
65
+ for (const entry of raw) {
57
66
  if (!isRecord(entry))
58
67
  continue;
59
68
  const name = entry['name'];
@@ -67,35 +76,82 @@ export function loadReviewerConfig(options = {}) {
67
76
  apiKeyEnv: typeof entry['apiKeyEnv'] === 'string' ? entry['apiKeyEnv'] : undefined
68
77
  });
69
78
  }
70
- if (providers.length < 2)
71
- return { ok: false, reason: 'no-reviewer-config' };
72
- const selectionRaw = reviewer['selection'];
73
- const selection = typeof selectionRaw === 'string' &&
74
- VALID_SELECTION.includes(selectionRaw)
75
- ? selectionRaw
79
+ return { providers, total: raw.length };
80
+ }
81
+ function readSelection(raw) {
82
+ return typeof raw === 'string' && VALID_SELECTION.includes(raw)
83
+ ? raw
76
84
  : 'round-robin';
77
- const fallbackRaw = reviewer['fallbackOnError'];
78
- const fallbackOnError = typeof fallbackRaw === 'string' &&
79
- VALID_FALLBACK.includes(fallbackRaw)
80
- ? fallbackRaw
85
+ }
86
+ function readFallback(raw) {
87
+ return typeof raw === 'string' && VALID_FALLBACK.includes(raw)
88
+ ? raw
81
89
  : 'skip';
82
- const rdProviderNameRaw = reviewer['rdProviderName'];
83
- const rdProviderName = rdProviderNameRaw === null || typeof rdProviderNameRaw === 'string' ? rdProviderNameRaw : null;
84
- const requireDistinct = reviewer['requireDistinctModelFamily'];
85
- const requireDistinctModelFamily = typeof requireDistinct === 'boolean' ? requireDistinct : true;
86
- const schemaPathRaw = reviewer['schemaPath'];
87
- const schemaPath = typeof schemaPathRaw === 'string' && schemaPathRaw.length > 0
88
- ? schemaPathRaw
89
- : 'schemas/reviewer-envelope.schema.json';
90
+ }
91
+ function readRdProviderName(raw) {
92
+ return raw === null || typeof raw === 'string' ? raw : null;
93
+ }
94
+ function readRequireDistinct(raw) {
95
+ return typeof raw === 'boolean' ? raw : true;
96
+ }
97
+ function readSchemaPath(raw) {
98
+ return typeof raw === 'string' && raw.length > 0 ? raw : 'schemas/reviewer-envelope.schema.json';
99
+ }
100
+ /** `<packageRoot>` — this file's tree is `<root>/src/services/reviewer` or `<root>/dist/services/reviewer`. */
101
+ const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
102
+ /**
103
+ * Resolve the configured ReviewerEnvelope schema: an absolute path as-is,
104
+ * else the project-root copy (a project may override), else the copy bundled
105
+ * with the peaks-loop package — a consumer project does NOT ship `schemas/`,
106
+ * so the packaged copy is what makes the default path work there. When
107
+ * nothing resolves, every candidate is returned for the refusal message.
108
+ */
109
+ export function resolveReviewerSchema(projectRoot, schemaPath) {
110
+ if (isAbsolute(schemaPath)) {
111
+ return existsSync(schemaPath)
112
+ ? { ok: true, path: schemaPath, source: 'absolute' }
113
+ : { ok: false, searched: [schemaPath] };
114
+ }
115
+ const projectCandidate = resolve(projectRoot, schemaPath);
116
+ if (existsSync(projectCandidate)) {
117
+ return { ok: true, path: projectCandidate, source: 'project' };
118
+ }
119
+ const packageCandidate = resolve(PACKAGE_ROOT, schemaPath);
120
+ if (existsSync(packageCandidate)) {
121
+ return { ok: true, path: packageCandidate, source: 'package' };
122
+ }
123
+ // Dogfooding the repo itself makes both candidates the same path; name it once.
124
+ const searched = projectCandidate === packageCandidate
125
+ ? [projectCandidate]
126
+ : [projectCandidate, packageCandidate];
127
+ return { ok: false, searched };
128
+ }
129
+ /**
130
+ * Read + parse `~/.peaks/config.json` (or override path) and return the
131
+ * `reviewer` section if present. NEVER throws on missing file — the CLI
132
+ * records the skip reason in the envelope instead.
133
+ */
134
+ export function loadReviewerConfig(options = {}) {
135
+ const path = options.path ?? defaultReviewerConfigPath();
136
+ const section = readSection(path);
137
+ if (!section.ok)
138
+ return absentStatus();
139
+ const reviewer = section.reviewer;
140
+ const { providers, total } = parseProviders(reviewer['providers']);
141
+ if (total < MIN_REVIEWER_PROVIDERS || providers.length < MIN_REVIEWER_PROVIDERS) {
142
+ // A4.1 requires >=2 valid providers. The section exists but is not
143
+ // usable; report the count rather than collapsing it into "no section".
144
+ return insufficientStatus(total < MIN_REVIEWER_PROVIDERS ? total : providers.length);
145
+ }
90
146
  return {
91
147
  ok: true,
92
148
  config: {
93
149
  providers,
94
- selection,
95
- rdProviderName,
96
- requireDistinctModelFamily,
97
- fallbackOnError,
98
- schemaPath
150
+ selection: readSelection(reviewer['selection']),
151
+ rdProviderName: readRdProviderName(reviewer['rdProviderName']),
152
+ requireDistinctModelFamily: readRequireDistinct(reviewer['requireDistinctModelFamily']),
153
+ fallbackOnError: readFallback(reviewer['fallbackOnError']),
154
+ schemaPath: readSchemaPath(reviewer['schemaPath'])
99
155
  }
100
156
  };
101
157
  }
@@ -0,0 +1,8 @@
1
+ import type { ReviewerProviderConfig } from './reviewer-config.js';
2
+ import type { ReviewerEnvelope } from './reviewer-types.js';
3
+ export declare const REVIEWER_ID = "third-party-reviewer-v2.14.0";
4
+ export declare function buildSkippedEnvelope(reason: string): ReviewerEnvelope;
5
+ export declare function buildProviderErrorEnvelope(provider: ReviewerProviderConfig, error: string): ReviewerEnvelope;
6
+ export declare function buildInvalidReplyEnvelope(provider: ReviewerProviderConfig): ReviewerEnvelope;
7
+ /** Stamp the family from the model we actually called — the LLM cannot choose it. */
8
+ export declare function stampEnvelope(validated: ReviewerEnvelope, provider: ReviewerProviderConfig): ReviewerEnvelope;
@@ -0,0 +1,53 @@
1
+ /**
2
+ * reviewer-envelopes.ts — pure builders for the ReviewerEnvelope.
3
+ *
4
+ * A skip is not a pass: every builder for a review that produced no verdict
5
+ * returns `passed: false` + `gateAction: 'warn'`, so a consumer reading only
6
+ * those two fields cannot see green (backlog §7.10 ②). `passed: true` is
7
+ * reachable only through `stampEnvelope`, which takes an already-validated
8
+ * model reply.
9
+ */
10
+ import { deriveModelFamily } from './model-family.js';
11
+ export const REVIEWER_ID = 'third-party-reviewer-v2.14.0';
12
+ export function buildSkippedEnvelope(reason) {
13
+ return {
14
+ reviewerId: REVIEWER_ID,
15
+ modelId: 'skipped',
16
+ modelFamily: 'skipped',
17
+ passed: false,
18
+ violations: [],
19
+ gateAction: 'warn',
20
+ reason
21
+ };
22
+ }
23
+ export function buildProviderErrorEnvelope(provider, error) {
24
+ return {
25
+ reviewerId: REVIEWER_ID,
26
+ modelId: provider.model,
27
+ modelFamily: deriveModelFamily(provider.model).modelFamily,
28
+ passed: false,
29
+ violations: [],
30
+ gateAction: 'warn',
31
+ reason: `skipped: provider ${provider.name} error (${error}); fallbackOnError=skip`
32
+ };
33
+ }
34
+ export function buildInvalidReplyEnvelope(provider) {
35
+ return {
36
+ reviewerId: REVIEWER_ID,
37
+ modelId: provider.model,
38
+ modelFamily: deriveModelFamily(provider.model).modelFamily,
39
+ passed: false,
40
+ violations: [],
41
+ gateAction: 'warn',
42
+ reason: `provider ${provider.name} returned non-conforming JSON; treated as warn`
43
+ };
44
+ }
45
+ /** Stamp the family from the model we actually called — the LLM cannot choose it. */
46
+ export function stampEnvelope(validated, provider) {
47
+ return {
48
+ ...validated,
49
+ modelId: provider.model,
50
+ modelFamily: deriveModelFamily(provider.model).modelFamily,
51
+ reviewerId: REVIEWER_ID
52
+ };
53
+ }
@@ -1,6 +1,6 @@
1
1
  import { type ReviewerEnvelope, type ReviewerRunInput, type ReviewerRunOutput } from './reviewer-types.js';
2
2
  export type { ReviewerViolation, ReviewerEnvelope, ReviewerRunInput, ReviewerRunOutput } from './reviewer-types.js';
3
- export declare const REVIEWER_ID = "third-party-reviewer-v2.14.0";
3
+ export { REVIEWER_ID, buildSkippedEnvelope } from './reviewer-envelopes.js';
4
4
  /**
5
5
  * Validate a parsed JSON value against the ReviewerEnvelope contract
6
6
  * (mirrors `schemas/reviewer-envelope.schema.json`). Returns the
@@ -12,10 +12,13 @@ export declare function validateReviewerEnvelope(value: unknown): ReviewerEnvelo
12
12
  * Many LLMs wrap JSON in ```json fences or surrounding prose; we
13
13
  * tolerate both. Returns null when no JSON object is present.
14
14
  */
15
- export declare function extractFirstJsonObject(text: string): unknown | null;
15
+ export declare function extractFirstJsonObject(text: string): unknown;
16
16
  export declare function runReviewer(input: ReviewerRunInput): Promise<ReviewerRunOutput>;
17
17
  /**
18
- * Compute the distinctness verdict: returns true when the third-party
19
- * mandates this is a CI gate — equality fails the build.
18
+ * The `requireDistinctModelFamily` verdict, over three inputs per side: a
19
+ * real family, an empty family, or a SKIP. Either side may be missing a
20
+ * family, and "not comparable" must NOT be reported as "distinct" — that
21
+ * would let a skip satisfy a distinctness gate. Returns true only when both
22
+ * families are present and differ.
20
23
  */
21
24
  export declare function distinctFromKarpathy(thirdPartyFamily: string, karpathyFamily: string): boolean;