@tobi-or-not/quorum 0.0.0-stage → 0.1.0

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 (89) hide show
  1. package/README.md +91 -2
  2. package/dist/cli/bin.d.ts +2 -0
  3. package/dist/cli/bin.js +40 -0
  4. package/dist/cli/main.d.ts +91 -0
  5. package/dist/cli/main.js +238 -0
  6. package/dist/cli/print-config.d.ts +14 -0
  7. package/dist/cli/print-config.js +95 -0
  8. package/dist/cli/render.d.ts +32 -0
  9. package/dist/cli/render.js +102 -0
  10. package/dist/config/claude-code.d.ts +37 -0
  11. package/dist/config/claude-code.js +80 -0
  12. package/dist/config/define.d.ts +10 -0
  13. package/dist/config/define.js +11 -0
  14. package/dist/config/env.d.ts +94 -0
  15. package/dist/config/env.js +272 -0
  16. package/dist/config/from-config.d.ts +24 -0
  17. package/dist/config/from-config.js +68 -0
  18. package/dist/config/load.d.ts +69 -0
  19. package/dist/config/load.js +417 -0
  20. package/dist/config/profiles.d.ts +39 -0
  21. package/dist/config/profiles.js +105 -0
  22. package/dist/config/resolve.d.ts +39 -0
  23. package/dist/config/resolve.js +315 -0
  24. package/dist/config/schema.d.ts +441 -0
  25. package/dist/config/schema.js +292 -0
  26. package/dist/core/concurrency.d.ts +9 -0
  27. package/dist/core/concurrency.js +31 -0
  28. package/dist/core/diff.d.ts +69 -0
  29. package/dist/core/diff.js +323 -0
  30. package/dist/core/errors.d.ts +48 -0
  31. package/dist/core/errors.js +71 -0
  32. package/dist/core/flags.d.ts +24 -0
  33. package/dist/core/flags.js +108 -0
  34. package/dist/core/output.d.ts +53 -0
  35. package/dist/core/output.js +352 -0
  36. package/dist/core/policy.d.ts +43 -0
  37. package/dist/core/policy.js +110 -0
  38. package/dist/core/ports.d.ts +56 -0
  39. package/dist/core/ports.js +1 -0
  40. package/dist/core/profile.d.ts +27 -0
  41. package/dist/core/profile.js +134 -0
  42. package/dist/core/prompts.d.ts +41 -0
  43. package/dist/core/prompts.js +93 -0
  44. package/dist/core/quorum.d.ts +28 -0
  45. package/dist/core/quorum.js +322 -0
  46. package/dist/core/sanitize.d.ts +45 -0
  47. package/dist/core/sanitize.js +78 -0
  48. package/dist/core/stages/context.d.ts +104 -0
  49. package/dist/core/stages/context.js +107 -0
  50. package/dist/core/stages/dedup.d.ts +9 -0
  51. package/dist/core/stages/dedup.js +18 -0
  52. package/dist/core/stages/panel.d.ts +32 -0
  53. package/dist/core/stages/panel.js +105 -0
  54. package/dist/core/stages/research.d.ts +53 -0
  55. package/dist/core/stages/research.js +96 -0
  56. package/dist/core/types.d.ts +297 -0
  57. package/dist/core/types.js +7 -0
  58. package/dist/core/verify.d.ts +14 -0
  59. package/dist/core/verify.js +77 -0
  60. package/dist/index.d.ts +44 -0
  61. package/dist/index.js +34 -0
  62. package/dist/profiles/security.d.ts +15 -0
  63. package/dist/profiles/security.js +41 -0
  64. package/dist/providers/anthropic.d.ts +14 -0
  65. package/dist/providers/anthropic.js +92 -0
  66. package/dist/providers/build.d.ts +45 -0
  67. package/dist/providers/build.js +155 -0
  68. package/dist/providers/claude-code.d.ts +208 -0
  69. package/dist/providers/claude-code.js +818 -0
  70. package/dist/providers/gemini.d.ts +12 -0
  71. package/dist/providers/gemini.js +130 -0
  72. package/dist/providers/http.d.ts +50 -0
  73. package/dist/providers/http.js +218 -0
  74. package/dist/providers/messages.d.ts +14 -0
  75. package/dist/providers/messages.js +10 -0
  76. package/dist/providers/ollama.d.ts +17 -0
  77. package/dist/providers/ollama.js +115 -0
  78. package/dist/providers/openai-compatible.d.ts +15 -0
  79. package/dist/providers/openai-compatible.js +152 -0
  80. package/dist/providers/options.d.ts +127 -0
  81. package/dist/providers/options.js +278 -0
  82. package/dist/providers/presets.d.ts +33 -0
  83. package/dist/providers/presets.js +68 -0
  84. package/dist/providers/reply.d.ts +18 -0
  85. package/dist/providers/reply.js +45 -0
  86. package/dist/providers/size.d.ts +50 -0
  87. package/dist/providers/size.js +108 -0
  88. package/package.json +59 -4
  89. package/schema/quorum.schema.json +523 -0
package/README.md CHANGED
@@ -1,3 +1,92 @@
1
- # Temporary Holding Version
1
+ # Quorum :ballot_box:
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **Quorum** reviews a diff with several model calls instead of one. A model, the finder, proposes candidate findings, and a panel of voters blind to each other, one per lens, judges each one. Whether a finding is kept, and at what confidence, is computed in code from the split of their votes, never reported by a model. The default profile reviews security through a model you point it at: over four HTTP protocols (Ollama's native API, OpenAI-compatible `/chat/completions`, the Anthropic Messages API and the Gemini API), with presets for the common vendors, local or hosted, or through your installed Claude Code CLI.
4
+
5
+ Quorum is pre-release (`0.x`): the API may change. It assists a reviewer; it does not replace human review of untrusted changes.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install -g @tobi-or-not/quorum # the quorum command, which runs on Node
11
+ ```
12
+
13
+ It needs Node `^22.18.0 || >=23.6.0`. Each release also carries a standalone binary for Linux and macOS, on x64 and arm64, that needs neither Node nor Bun:
14
+
15
+ ```bash
16
+ gh release download --repo this-is-tobi/quorum --pattern 'quorum-linux-x64' --pattern SHA256SUMS # or linux-arm64, darwin-x64, darwin-arm64
17
+ ```
18
+
19
+ Or run the image, which holds a binary compiled the same way, from the same commit, and runs as a non-root user. Inside it `localhost` is the container, so name the endpoint. On Docker Desktop a server on your machine is `host.docker.internal`; on Linux add `--add-host=host.docker.internal:host-gateway` ([Installation](./docs/10-getting-started/10-installation.md#a-container-image) has the rest):
20
+
21
+ ```bash
22
+ docker run --rm -i \
23
+ -e QUORUM_RESEARCH_PROTOCOL=ollama -e QUORUM_RESEARCH_BASE_URL=http://host.docker.internal:11434 \
24
+ -e QUORUM_RESEARCH_MODEL=qwen3.6:27b -e QUORUM_RESEARCH_CONTEXT_TOKENS=32768 \
25
+ ghcr.io/this-is-tobi/quorum:<version> < my.diff > result.json
26
+ ```
27
+
28
+ To build it from a clone instead, with Bun 1.3.0 or newer:
29
+
30
+ ```bash
31
+ git clone https://github.com/this-is-tobi/quorum.git && cd quorum
32
+ bun install
33
+ bun run compile # a standalone binary in ./bin/quorum
34
+ install -m 0755 ./bin/quorum /usr/local/bin/quorum # on your $PATH
35
+ ```
36
+
37
+ [Installation](./docs/10-getting-started/10-installation.md) has the prerequisites, checking the npm package's provenance, checking a release binary against its checksums and its attestation, running the image with a config file, a key and a model on the host and checking its attestation, why the installed command runs on Node and not on Bun, running it from the clone without the binary, and a check that it works without a model.
38
+
39
+ ## Try it
40
+
41
+ ```bash
42
+ export QUORUM_RESEARCH_MODEL=qwen3.6:27b # a model your local Ollama serves
43
+ export QUORUM_RESEARCH_CONTEXT_TOKENS=32768 # its context window, in tokens
44
+ quorum ./my.diff > result.json # review a diff file
45
+ git diff origin/main...HEAD | quorum > result.json # or what your branch changes
46
+ ```
47
+
48
+ `QUORUM_RESEARCH_CONTEXT_TOKENS` is the model's context window in tokens, which quorum checks every request against, and without it the run exits `2` with a message that names it. With no provider configured and no base URL, preset or protocol variable, quorum talks to the Ollama on this machine through its native API, `http://localhost:11434`, which Ollama listens on, on `127.0.0.1`, by default. That API takes `num_ctx`, `truncate: false` and `shift: false`, so quorum tells the server the context size and the server refuses an overflow, where Ollama's OpenAI-compatible `/v1` would cut the prompt in silence. Refusing needs Ollama 0.12.6 or later: an older server ignores `truncate` and `shift`. A base URL variable set on its own means an OpenAI-compatible server, as before. Keep the number at most what `ollama show <model>` reports for the model, since Ollama clamps a larger `num_ctx` to it, and read the context a running model loaded in the `CONTEXT` column of `ollama ps`.
49
+
50
+ To review through your installed Claude Code CLI instead, run `claude` headless and isolated for each request:
51
+
52
+ ```bash
53
+ export QUORUM_RESEARCH_PROTOCOL=claude-code # your installed Claude Code CLI, found on PATH
54
+ export QUORUM_RESEARCH_MODEL=sonnet # an alias, or a model id, that `claude --model` takes
55
+ export QUORUM_RESEARCH_CONTEXT_TOKENS=1000000 # its context window, in tokens
56
+ quorum ./my.diff > result.json
57
+ ```
58
+
59
+ Requires Claude Code 2.1.311 or newer. [`claudeCode`](./docs/20-using/30-providers.md#claudecode) has the command line, the isolation and the auth modes, and [Claude Code](./docs/20-using/20-configuration.md#claude-code) the setup, in CI too.
60
+
61
+ The JSON result goes to stdout, and the exit code says what to do with it: `0` for a complete review in which no gating profile kept a `high` finding, `1` when one did, complete or not, `2` for a usage or configuration error, `3` when the research call failed, `4` when a gating profile's review is incomplete otherwise, and `130` when the run was interrupted. [Quick start](./docs/10-getting-started/20-quickstart.md) walks one review through, and [Start here](./docs/01-readme.md) lays out three tracks: review a diff, use it from code or review something else, and know what it protects against.
62
+
63
+ ## Documentation
64
+
65
+ **Website:** <https://this-is-tobi.com/quorum/introduction>
66
+
67
+ **Table of Contents** *- md sources*:
68
+
69
+ *Getting started*
70
+ - [Installation](./docs/10-getting-started/10-installation.md) *- Node and the npm package, a release binary, the container image, or Bun and the clone, a standalone binary on your `$PATH`, and a check that it works without a model*
71
+ - [Quick start](./docs/10-getting-started/20-quickstart.md) *- Point it at a model, review a diff, and read the progress, the result and the exit code*
72
+
73
+ *Using it*
74
+ - [The CLI](./docs/20-using/10-cli.md) *- The invocation, stdout and stderr, every exit code and its causes, and gating a CI job on them*
75
+ - [Configuration](./docs/20-using/20-configuration.md) *- The config file and its trust model in CI, the `QUORUM_*` variables and the voter's fallback, the context size each provider states, running Claude Code, the keys, `--print-config`, and the errors a bad setting causes*
76
+ - [Providers](./docs/20-using/30-providers.md) *- The provider port, the shipped adapters and their options, Claude Code run isolated as a provider, the presets, `ProviderError`, and writing a provider of your own*
77
+ - [Profiles](./docs/20-using/40-profiles.md) *- The security profile, writing your own, several in one review, gating and guidelines*
78
+ - [Lenses and policy](./docs/20-using/50-lenses-and-policy.md) *- The panel's questions, the rules that turn kept votes into a confidence, failed votes, and what a level means*
79
+ - [Prompts](./docs/20-using/60-prompts.md) *- The layout of every request, the templates and their variables, the notices, and what is not configurable*
80
+
81
+ *Security*
82
+ - [Threat model](./docs/30-security/10-threat-model.md) *- The attacker, the assets, the residual risk stated plainly, the controls in place, and what the panel's independence is worth*
83
+ - [Output handling](./docs/30-security/30-output-handling.md) *- What the CLI writes and how it is made inert, the advisory flags, and printing a review yourself*
84
+
85
+ *Recipes*
86
+ - [Local models](./docs/90-recipes/10-local-models.md) *- Ollama, vLLM and llama.cpp: the window each gives a request, choosing a model, and what reasoning mode does to a request*
87
+
88
+ *Reference*
89
+ - [Glossary](./docs/95-reference/10-glossary.md) *- The words these pages use in one particular way, and the acronyms they assume*
90
+ - [The JSON result](./docs/95-reference/20-json-result.md) *- Every field of a result in the order it is written, the incomplete reasons, and an example*
91
+ - [Library API](./docs/95-reference/30-library-api.md) *- `createQuorum`, its ports, the events, abort, the errors and every export*
92
+ - [Architecture](./docs/95-reference/40-architecture.md) *- The modules, the dependency rule, the stages of a review, and how the suite runs*
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -0,0 +1,40 @@
1
+ #!/usr/bin/env node
2
+ import { inertLine } from "../core/sanitize.js";
3
+ import { errorMessage, EXIT, interruptSignal, runCli } from "./main.js";
4
+ // The first SIGINT or SIGTERM aborts the review; the second says so and exits 130 at once, for a provider that ignores it.
5
+ const signal = interruptSignal(process, (code) => {
6
+ process.stderr.write('interrupted\n');
7
+ process.exit(code);
8
+ });
9
+ // An error nothing caught is a failed run, never a finding (exit 1): one inert line, no stack, exit 3.
10
+ function fail(error) {
11
+ process.stderr.write(`${inertLine(`Error: ${errorMessage(error)}`)}\n`);
12
+ process.exit(EXIT.runtime);
13
+ }
14
+ process.on('uncaughtException', fail);
15
+ process.on('unhandledRejection', fail);
16
+ // Exit 3 until the run settles. A provider whose promise never settles, and holds no timer or socket,
17
+ // empties the event loop: the runtime then exits with the code it holds, which must never be 0 with no result.
18
+ process.exitCode = EXIT.runtime;
19
+ let settled = false;
20
+ process.once('beforeExit', () => {
21
+ if (settled)
22
+ return;
23
+ if (signal.aborted)
24
+ process.exitCode = EXIT.interrupted;
25
+ process.stderr.write(signal.aborted ? 'interrupted\n' : 'Error: the run stopped without a result\n');
26
+ });
27
+ // Inside the async function, so a working directory that no longer exists fails the run with exit 3.
28
+ async function main() {
29
+ return runCli({ argv: process.argv.slice(2), cwd: process.cwd(), env: process.env, stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, signal });
30
+ }
31
+ main()
32
+ .then((code) => {
33
+ settled = true;
34
+ process.exitCode = code;
35
+ })
36
+ .catch((error) => {
37
+ settled = true;
38
+ process.stderr.write(`${inertLine(`Error: ${errorMessage(error)}`)}\n`);
39
+ process.exitCode = EXIT.runtime;
40
+ });
@@ -0,0 +1,91 @@
1
+ import type { Env } from '../config/env.ts';
2
+ import type { QuorumResult } from '../core/types.ts';
3
+ /** Exit codes (ADR-0008, amended by ADR-0012). */
4
+ export declare const EXIT: {
5
+ readonly ok: 0;
6
+ readonly finding: 1;
7
+ readonly usage: 2;
8
+ readonly runtime: 3;
9
+ readonly incomplete: 4;
10
+ readonly interrupted: 130;
11
+ };
12
+ /** The most diff the CLI reads, from stdin or a file, in bytes: a larger one is refused and reading stops there. */
13
+ export declare const MAX_DIFF_BYTES: number;
14
+ export interface CliIO {
15
+ /** Arguments after the executable and script, e.g. `process.argv.slice(2)`. */
16
+ argv: readonly string[];
17
+ /** The directory a relative diff path and a relative `--config` resolve against, e.g. `process.cwd()`. */
18
+ readonly cwd: string;
19
+ /** Environment variables, e.g. `process.env`. */
20
+ env: Env;
21
+ stdin: AsyncIterable<Uint8Array | string> & {
22
+ isTTY?: boolean;
23
+ };
24
+ stdout: {
25
+ write: (text: string) => unknown;
26
+ };
27
+ stderr: {
28
+ write: (text: string) => unknown;
29
+ };
30
+ /** The review's signal: once it is aborted, a run that ends without a result exits 130. */
31
+ readonly signal?: AbortSignal;
32
+ }
33
+ /**
34
+ * Run one review and return the process exit code. Never throws: usage and configuration problems
35
+ * exit 2, runtime failures exit 3, an interrupt exits 130, and an incomplete review (a finding its
36
+ * failed votes left undecided, or a research gap) of a gating profile exits 4 unless a `high` finding
37
+ * was kept by a gating profile, so CI can tell a broken run and a partial review from a real finding
38
+ * (exit 1) and from a clean one (exit 0). `exitCodeFor` maps the result; advisory flags never change it.
39
+ *
40
+ * It reads at most 16 MiB of diff, from stdin or a file, counted in bytes: a larger diff is a usage error,
41
+ * and reading stops at the chunk that crosses the cap.
42
+ *
43
+ * Its flags are `--config`, `--profile`, `--allow-incomplete`, `--print-config`, `--help` and `--version`;
44
+ * a usage error prints the usage after its message. Its settings are the config file `--config` or
45
+ * `QUORUM_CONFIG` names (`--config` resolved against `io.cwd`, `QUORUM_CONFIG` an absolute path), and the
46
+ * `QUORUM_*` variables of `io.env` with their deprecated aliases. Each warning is printed once, before the
47
+ * banner, and when the configuration is refused the environment's warnings come before the `Error:` lines,
48
+ * since a deprecated or mistyped variable is often what caused the error.
49
+ *
50
+ * `--print-config` reads no diff and calls no model: it writes the resolved config as YAML on stdout
51
+ * (see `printConfig`), warnings included, and returns 0; a diff argument with it is a usage error, and
52
+ * a configuration the run refuses, one of its providers that cannot be built included, exits 2 as in a run.
53
+ *
54
+ * The run is interrupted when `io.signal` aborts: it then writes `interrupted` and returns 130, whatever
55
+ * error ended the review, and writes no result. A review that has already resolved is complete.
56
+ *
57
+ * Everything the CLI writes is inert (invariant I3): each stderr line passes through `inertLine`, and
58
+ * the JSON result through `inertJson`.
59
+ */
60
+ export declare function runCli(io: CliIO): Promise<number>;
61
+ /** The one source of signals the CLI listens to: `process`, or an emitter in a test. */
62
+ export interface SignalSource {
63
+ on: (event: 'SIGINT' | 'SIGTERM', listener: () => void) => unknown;
64
+ }
65
+ /**
66
+ * The signal of one review, aborted by the first SIGINT or SIGTERM. The next one calls `exit(130)`: the
67
+ * way out of a provider that ignores its signal, since no timer waits for it.
68
+ */
69
+ export declare function interruptSignal(source: SignalSource, exit: (code: number) => void): AbortSignal;
70
+ /**
71
+ * The exit code of a finished review: 1 when a kept finding is `high` and its profile gates, 4 when
72
+ * an unreviewed finding or a gap belongs to a gating profile (unless `allowIncomplete` turns it into
73
+ * 0, which it does for every gap but a `request-too-large` one), 0 otherwise. A profile gates
74
+ * unless `meta.profiles` holds it with `gating: false`, so a profile missing from the result counts
75
+ * as gating and a gap never hides.
76
+ *
77
+ * A `request-too-large` gap of a gating profile exits 4 whatever `allowIncomplete` says: a pull
78
+ * request can cause that gap by padding the diff until a request is refused, so no flag lifts it
79
+ * (ADR-0012). The flag lifts every other gap, including gaps a pull request can cause: decoy findings
80
+ * that push a real one past `maxFindings`, or text that trips a hosted voter's content filter. On a
81
+ * gating profile, do not use it for a pull request you do not trust.
82
+ */
83
+ export declare function exitCodeFor(result: QuorumResult, options?: {
84
+ readonly allowIncomplete?: boolean;
85
+ }): number;
86
+ /**
87
+ * The text of a failure, for any value a promise can reject with: an `Error`'s message, else the
88
+ * value's text form, else a fixed text when even that throws, as it does for an object without a
89
+ * prototype. It never throws, so neither do the lines built from it.
90
+ */
91
+ export declare function errorMessage(error: unknown): string;
@@ -0,0 +1,238 @@
1
+ import { createReadStream } from 'node:fs';
2
+ import { resolve } from 'node:path';
3
+ import { parseArgs } from 'node:util';
4
+ import packageJson from '../../package.json' with { type: 'json' };
5
+ import { readEnv } from "../config/env.js";
6
+ import { fromConfig } from "../config/from-config.js";
7
+ import { loadConfig } from "../config/load.js";
8
+ import { ConfigError } from "../core/errors.js";
9
+ import { inertJson, inertLine } from "../core/sanitize.js";
10
+ import { printConfig } from "./print-config.js";
11
+ import { bannerLines, progressSink } from "./render.js";
12
+ /** Exit codes (ADR-0008, amended by ADR-0012). */
13
+ export const EXIT = { ok: 0, finding: 1, usage: 2, runtime: 3, incomplete: 4, interrupted: 130 };
14
+ /** The most diff the CLI reads, from stdin or a file, in bytes: a larger one is refused and reading stops there. */
15
+ export const MAX_DIFF_BYTES = 16 * 1024 * 1024;
16
+ const USAGE = [
17
+ 'Usage: quorum [options] [diff-file]',
18
+ ' git diff | quorum [options]',
19
+ '',
20
+ 'Options:',
21
+ ' -c, --config <path> Read this config file, over QUORUM_CONFIG',
22
+ ' -p, --profile <id> Run only this profile; repeat it to run several',
23
+ ' --allow-incomplete Exit 0 instead of 4 when the review is incomplete, except for a request too large for its model',
24
+ ' --print-config Print the resolved config, keys redacted, and exit',
25
+ ' -h, --help Print this help and exit',
26
+ ' -v, --version Print the version and exit',
27
+ '',
28
+ ].join('\n');
29
+ const OPTIONS = {
30
+ config: { type: 'string', short: 'c' },
31
+ profile: { type: 'string', short: 'p', multiple: true },
32
+ 'allow-incomplete': { type: 'boolean' },
33
+ 'print-config': { type: 'boolean' },
34
+ help: { type: 'boolean', short: 'h' },
35
+ version: { type: 'boolean', short: 'v' },
36
+ };
37
+ /**
38
+ * Run one review and return the process exit code. Never throws: usage and configuration problems
39
+ * exit 2, runtime failures exit 3, an interrupt exits 130, and an incomplete review (a finding its
40
+ * failed votes left undecided, or a research gap) of a gating profile exits 4 unless a `high` finding
41
+ * was kept by a gating profile, so CI can tell a broken run and a partial review from a real finding
42
+ * (exit 1) and from a clean one (exit 0). `exitCodeFor` maps the result; advisory flags never change it.
43
+ *
44
+ * It reads at most 16 MiB of diff, from stdin or a file, counted in bytes: a larger diff is a usage error,
45
+ * and reading stops at the chunk that crosses the cap.
46
+ *
47
+ * Its flags are `--config`, `--profile`, `--allow-incomplete`, `--print-config`, `--help` and `--version`;
48
+ * a usage error prints the usage after its message. Its settings are the config file `--config` or
49
+ * `QUORUM_CONFIG` names (`--config` resolved against `io.cwd`, `QUORUM_CONFIG` an absolute path), and the
50
+ * `QUORUM_*` variables of `io.env` with their deprecated aliases. Each warning is printed once, before the
51
+ * banner, and when the configuration is refused the environment's warnings come before the `Error:` lines,
52
+ * since a deprecated or mistyped variable is often what caused the error.
53
+ *
54
+ * `--print-config` reads no diff and calls no model: it writes the resolved config as YAML on stdout
55
+ * (see `printConfig`), warnings included, and returns 0; a diff argument with it is a usage error, and
56
+ * a configuration the run refuses, one of its providers that cannot be built included, exits 2 as in a run.
57
+ *
58
+ * The run is interrupted when `io.signal` aborts: it then writes `interrupted` and returns 130, whatever
59
+ * error ended the review, and writes no result. A review that has already resolved is complete.
60
+ *
61
+ * Everything the CLI writes is inert (invariant I3): each stderr line passes through `inertLine`, and
62
+ * the JSON result through `inertJson`.
63
+ */
64
+ export async function runCli(io) {
65
+ let flags;
66
+ try {
67
+ flags = parseFlags(io.argv);
68
+ }
69
+ catch (error) {
70
+ return usageError(io, error);
71
+ }
72
+ const { values, positionals } = flags;
73
+ if (values.help) {
74
+ io.stdout.write(USAGE);
75
+ return EXIT.ok;
76
+ }
77
+ if (values.version) {
78
+ io.stdout.write(`quorum ${packageJson.version}\n`);
79
+ return EXIT.ok;
80
+ }
81
+ const printing = values['print-config'] === true;
82
+ let diff = '';
83
+ try {
84
+ if (values.config === '')
85
+ throw new ConfigError([{ path: '--config', message: 'must name a file' }]);
86
+ if (printing && positionals.length > 0)
87
+ throw new Error('--print-config takes no diff file');
88
+ if (!printing)
89
+ diff = await readDiff(io, positionals);
90
+ }
91
+ catch (error) {
92
+ return usageError(io, error);
93
+ }
94
+ let quorum;
95
+ try {
96
+ const selection = values.profile === undefined ? undefined : { ids: values.profile, path: '--profile' };
97
+ const { config, source } = await loadConfig({ cwd: io.cwd, env: io.env, configPath: values.config, selection });
98
+ quorum = await fromConfig(config, { env: io.env, events: progressSink(line => io.stderr.write(`${line}\n`)) });
99
+ if (printing) {
100
+ io.stdout.write(printConfig(config, source));
101
+ return EXIT.ok;
102
+ }
103
+ writeWarnings(io, quorum.warnings);
104
+ for (const line of bannerLines(config))
105
+ io.stderr.write(`${line}\n`);
106
+ if (diff.trim() === '')
107
+ io.stderr.write('empty diff: nothing to review\n');
108
+ const result = await quorum.review({ diff }, { signal: io.signal });
109
+ io.stdout.write(`${inertJson(result)}\n`);
110
+ return exitCodeFor(result, { allowIncomplete: values['allow-incomplete'] === true });
111
+ }
112
+ catch (error) {
113
+ if (io.signal?.aborted) {
114
+ io.stderr.write('interrupted\n');
115
+ return EXIT.interrupted;
116
+ }
117
+ if (error instanceof ConfigError && quorum === undefined)
118
+ writeWarnings(io, readEnv(io.env).warnings);
119
+ io.stderr.write(`${errorLines(error)}\n`);
120
+ return error instanceof ConfigError ? EXIT.usage : EXIT.runtime;
121
+ }
122
+ }
123
+ /** Write each warning as an inert `warning:` line. */
124
+ function writeWarnings(io, warnings) {
125
+ for (const warning of warnings)
126
+ io.stderr.write(`${inertLine(`warning: ${warning}`)}\n`);
127
+ }
128
+ /**
129
+ * The signal of one review, aborted by the first SIGINT or SIGTERM. The next one calls `exit(130)`: the
130
+ * way out of a provider that ignores its signal, since no timer waits for it.
131
+ */
132
+ export function interruptSignal(source, exit) {
133
+ const controller = new AbortController();
134
+ let received = 0;
135
+ const onSignal = () => {
136
+ received += 1;
137
+ if (received === 1)
138
+ controller.abort();
139
+ else
140
+ exit(EXIT.interrupted);
141
+ };
142
+ source.on('SIGINT', onSignal);
143
+ source.on('SIGTERM', onSignal);
144
+ return controller.signal;
145
+ }
146
+ /**
147
+ * The exit code of a finished review: 1 when a kept finding is `high` and its profile gates, 4 when
148
+ * an unreviewed finding or a gap belongs to a gating profile (unless `allowIncomplete` turns it into
149
+ * 0, which it does for every gap but a `request-too-large` one), 0 otherwise. A profile gates
150
+ * unless `meta.profiles` holds it with `gating: false`, so a profile missing from the result counts
151
+ * as gating and a gap never hides.
152
+ *
153
+ * A `request-too-large` gap of a gating profile exits 4 whatever `allowIncomplete` says: a pull
154
+ * request can cause that gap by padding the diff until a request is refused, so no flag lifts it
155
+ * (ADR-0012). The flag lifts every other gap, including gaps a pull request can cause: decoy findings
156
+ * that push a real one past `maxFindings`, or text that trips a hosted voter's content filter. On a
157
+ * gating profile, do not use it for a pull request you do not trust.
158
+ */
159
+ export function exitCodeFor(result, options = {}) {
160
+ const gates = (profile) => !Object.hasOwn(result.meta.profiles, profile) || result.meta.profiles[profile].gating !== false;
161
+ if (result.kept.some(verdict => verdict.confidence === 'high' && gates(verdict.profile)))
162
+ return EXIT.finding;
163
+ if (result.meta.incomplete.some(entry => entry.reason === 'request-too-large' && gates(entry.profile)))
164
+ return EXIT.incomplete;
165
+ const incomplete = result.unreviewed.some(verdict => gates(verdict.profile)) || result.meta.incomplete.some(entry => gates(entry.profile));
166
+ return incomplete && options.allowIncomplete !== true ? EXIT.incomplete : EXIT.ok;
167
+ }
168
+ /** The flags of `argv` and its positional arguments; a usage error of `parseArgs` is raised as a `ConfigError`, one issue per line of its message. */
169
+ function parseFlags(argv) {
170
+ try {
171
+ return parseArgs({ args: [...argv], options: OPTIONS, strict: true, allowPositionals: true });
172
+ }
173
+ catch (error) {
174
+ if (!(error instanceof Error) || !error.code?.startsWith('ERR_PARSE_ARGS_'))
175
+ throw error;
176
+ throw new ConfigError(error.message.split('\n').map(message => ({ path: '', message })));
177
+ }
178
+ }
179
+ /** Write a usage error and the usage, and return its exit code. */
180
+ function usageError(io, error) {
181
+ io.stderr.write(`${errorLines(error)}\n${USAGE}`);
182
+ return EXIT.usage;
183
+ }
184
+ /** Read the diff from the file argument, or from stdin unless stdin is an interactive terminal. */
185
+ async function readDiff(io, positionals) {
186
+ const [path, ...extra] = positionals;
187
+ if (extra.length > 0)
188
+ throw new Error(`unexpected arguments: ${extra.join(' ')}`);
189
+ if (path)
190
+ return readCapped(createReadStream(resolve(io.cwd, path)));
191
+ if (io.stdin.isTTY)
192
+ throw new Error('no diff given');
193
+ return readCapped(io.stdin);
194
+ }
195
+ /**
196
+ * Read `chunks` to the end as UTF-8 text, through one streaming decoder, so a leading byte-order mark
197
+ * goes and a character split between two chunks stays whole, whatever the source. The bytes are
198
+ * counted as they arrive: the chunk that takes the count past `MAX_DIFF_BYTES` throws, and leaving
199
+ * the loop closes the stream, so no more is read.
200
+ */
201
+ async function readCapped(chunks) {
202
+ const encoder = new TextEncoder();
203
+ const decoder = new TextDecoder();
204
+ let bytes = 0;
205
+ let text = '';
206
+ for await (const chunk of chunks) {
207
+ const data = typeof chunk === 'string' ? encoder.encode(chunk) : chunk;
208
+ bytes += data.byteLength;
209
+ if (bytes > MAX_DIFF_BYTES)
210
+ throw new Error('the diff is over 16 MiB, the most quorum reads');
211
+ text += decoder.decode(data, { stream: true });
212
+ }
213
+ return text + decoder.decode();
214
+ }
215
+ /**
216
+ * The `Error:` lines of a failure, each inert: a ConfigError's issues one per line, as its message
217
+ * lists them, and any other failure's message on one line, so a line break in a file name or in text
218
+ * a server sent cannot start a line of its own.
219
+ */
220
+ function errorLines(error) {
221
+ const lines = error instanceof ConfigError ? error.message.split('\n') : [errorMessage(error)];
222
+ return lines.map((line, index) => inertLine(index === 0 ? `Error: ${line}` : line)).join('\n');
223
+ }
224
+ /**
225
+ * The text of a failure, for any value a promise can reject with: an `Error`'s message, else the
226
+ * value's text form, else a fixed text when even that throws, as it does for an object without a
227
+ * prototype. It never throws, so neither do the lines built from it.
228
+ */
229
+ export function errorMessage(error) {
230
+ if (error instanceof Error)
231
+ return error.message;
232
+ try {
233
+ return String(error);
234
+ }
235
+ catch {
236
+ return 'an error with no text form';
237
+ }
238
+ }
@@ -0,0 +1,14 @@
1
+ import type { ResolvedConfig } from '../config/resolve.ts';
2
+ /**
3
+ * The resolved config as the YAML `--print-config` writes, for a CI log that anyone can read: the file it
4
+ * came from (`null` for none), the providers, the profiles that run, the limits the review applies, and
5
+ * the warnings. A key and every value of `headers`, `query` and `extraBody` print as `[redacted]`, a base
6
+ * URL as its origin, and a prompt as its SHA-256. A `claude-code` provider prints its protocol, command,
7
+ * model, context size, key (redacted), auth mode and args, and no origin: the command and the args are the
8
+ * user's own config. The view is an allowlist, so a field added to the config prints nothing until it is
9
+ * added here on purpose.
10
+ *
11
+ * The text ends with a newline, and each line passes through `inertLine`. It is YAML 1.1, so a reader of
12
+ * that version reads `off` as a string, and no line folds.
13
+ */
14
+ export declare function printConfig(config: ResolvedConfig, source: string | undefined): string;
@@ -0,0 +1,95 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { stringify } from 'yaml';
3
+ import { own } from "../config/profiles.js";
4
+ import { isProvider } from "../config/schema.js";
5
+ import { DEFAULT_CONCURRENCY } from "../core/concurrency.js";
6
+ import { thresholdsFor } from "../core/profile.js";
7
+ import { inertLine } from "../core/sanitize.js";
8
+ import { DEFAULT_MAX_FINDINGS } from "../core/stages/research.js";
9
+ import { isClaudeCode } from "../providers/build.js";
10
+ import { providerOrigin } from "./render.js";
11
+ /** What stands for a secret in the view: the word `http.ts` redacts with. */
12
+ const REDACTED = '[redacted]';
13
+ /** `sha256:` and the lowercase hex SHA-256 of the UTF-8 text: what a prompt prints as, short, and a CI job can compare it with the hash of a file. */
14
+ function sha256(text) {
15
+ return `sha256:${createHash('sha256').update(text).digest('hex')}`;
16
+ }
17
+ /** The keys of a record, each with the redacted word: a header, query or body value can be a credential. */
18
+ function redactedValues(record) {
19
+ return record === undefined ? undefined : Object.fromEntries(Object.keys(record).map(key => [key, REDACTED]));
20
+ }
21
+ /** The auth style as set: a name, or the header and the prefix a key is sent with. Neither holds the key. */
22
+ function authView(auth) {
23
+ return typeof auth === 'object' ? { header: own(auth, 'header'), prefix: own(auth, 'prefix') } : auth;
24
+ }
25
+ /** Where the instructions go (`native` or `inline`), the only values a spec accepts; any other value is a prompt, so it prints as its hash. */
26
+ function systemPromptView(value) {
27
+ if (value === undefined || value === 'native' || value === 'inline')
28
+ return value;
29
+ return typeof value === 'string' ? sha256(value) : REDACTED;
30
+ }
31
+ /**
32
+ * A provider defined as data, field by field: a field of a spec that is not listed here prints nothing.
33
+ * `undefined` leaves a field out, as `stringify` keeps no `undefined` value. A `claude-code` provider has
34
+ * no origin and runs a `command` and `args`, and its `auth` is `inherit` when it sets none, as it runs.
35
+ */
36
+ function specView(spec) {
37
+ const cli = isClaudeCode(own(spec, 'protocol'));
38
+ return {
39
+ preset: own(spec, 'preset'),
40
+ protocol: own(spec, 'protocol'),
41
+ command: own(spec, 'command'),
42
+ origin: cli ? undefined : providerOrigin(spec),
43
+ model: own(spec, 'model'),
44
+ contextTokens: own(spec, 'contextTokens'),
45
+ apiKey: own(spec, 'apiKey') === undefined ? undefined : REDACTED,
46
+ auth: authView(own(spec, 'auth') ?? (cli ? 'inherit' : undefined)),
47
+ args: own(spec, 'args'),
48
+ headers: redactedValues(own(spec, 'headers')),
49
+ query: redactedValues(own(spec, 'query')),
50
+ extraBody: redactedValues(own(spec, 'extraBody')),
51
+ structuredOutput: own(spec, 'structuredOutput'),
52
+ temperature: own(spec, 'temperature'),
53
+ maxTokens: own(spec, 'maxTokens'),
54
+ maxTokensField: own(spec, 'maxTokensField'),
55
+ systemPrompt: systemPromptView(own(spec, 'systemPrompt')),
56
+ };
57
+ }
58
+ /** A provider object by what it implements and its model, when that is a string; never its function. */
59
+ function objectView(provider) {
60
+ const model = own(provider, 'model');
61
+ return { implements: 'Provider', model: typeof model === 'string' ? model : undefined };
62
+ }
63
+ /** A profile that runs: its providers, the votes its policy needs, and each prompt as its hash. */
64
+ function profileView({ profile, research, voters }) {
65
+ return {
66
+ gating: profile.gating ?? true,
67
+ research,
68
+ lenses: { ...voters },
69
+ thresholds: thresholdsFor(profile),
70
+ prompts: { research: sha256(profile.prompts.research), vote: sha256(profile.prompts.vote) },
71
+ };
72
+ }
73
+ /**
74
+ * The resolved config as the YAML `--print-config` writes, for a CI log that anyone can read: the file it
75
+ * came from (`null` for none), the providers, the profiles that run, the limits the review applies, and
76
+ * the warnings. A key and every value of `headers`, `query` and `extraBody` print as `[redacted]`, a base
77
+ * URL as its origin, and a prompt as its SHA-256. A `claude-code` provider prints its protocol, command,
78
+ * model, context size, key (redacted), auth mode and args, and no origin: the command and the args are the
79
+ * user's own config. The view is an allowlist, so a field added to the config prints nothing until it is
80
+ * added here on purpose.
81
+ *
82
+ * The text ends with a newline, and each line passes through `inertLine`. It is YAML 1.1, so a reader of
83
+ * that version reads `off` as a string, and no line folds.
84
+ */
85
+ export function printConfig(config, source) {
86
+ const view = {
87
+ source: source ?? null,
88
+ providers: Object.fromEntries(Object.entries(config.providers).map(([name, provider]) => [name, isProvider(provider) ? objectView(provider) : specView(provider)])),
89
+ profiles: Object.fromEntries(config.profiles.map(resolved => [resolved.profile.id, profileView(resolved)])),
90
+ concurrency: config.concurrency ?? DEFAULT_CONCURRENCY,
91
+ maxFindings: config.maxFindings ?? DEFAULT_MAX_FINDINGS,
92
+ warnings: [...config.warnings],
93
+ };
94
+ return stringify(view, { version: '1.1', lineWidth: 0, blockQuote: false }).split('\n').map(line => inertLine(line)).join('\n');
95
+ }
@@ -0,0 +1,32 @@
1
+ import type { ResolvedConfig, ResolvedProvider } from '../config/resolve.ts';
2
+ import type { EventSink, Provider } from '../core/ports.ts';
3
+ import type { QuorumEvent } from '../core/types.ts';
4
+ /**
5
+ * The progress line of an event, or undefined for the events the CLI keeps quiet about. These lines
6
+ * are the CLI's progress output on stderr, so a person follows a run without the full event stream.
7
+ * Each line passes through `inertLine` whole: the reasons, details and file names it carries come
8
+ * from the finder or the diff, and nothing in them can act on a terminal or a CI log. When `prefixed`,
9
+ * a line of an event that names a profile starts with `[<profile>] `: the `flag:` and totals lines
10
+ * belong to the whole review and never do.
11
+ */
12
+ export declare function renderEvent(event: QuorumEvent, prefixed?: boolean): string | undefined;
13
+ /**
14
+ * The sink that writes the progress lines of a review: each event rendered by `renderEvent`, each line
15
+ * that is defined handed to `write`. `run:start` says whether several profiles run, and then every
16
+ * profile's line is prefixed. Rendering never throws, so the sink adds no failure of its own to a review.
17
+ */
18
+ export declare function progressSink(write: (line: string) => void): EventSink;
19
+ /**
20
+ * The origin of a provider defined as data, as the banner and `--print-config` name its endpoint: the
21
+ * scheme, host and port of its own base URL, else of its preset's. Both are read as own fields, so a
22
+ * polluted `Object.prototype` fills neither.
23
+ */
24
+ export declare function providerOrigin(spec: Exclude<ResolvedProvider, Provider>): string;
25
+ /**
26
+ * The lines a run prints before its progress: who researches and who votes, from the resolved config, as
27
+ * `<model> @ <origin>` (a provider object as `<model> @ the provider object <name>`, a `claude-code`
28
+ * provider as `<model> @ claude-code`), never a path, a credential or a query. The panel line names one
29
+ * provider when every lens shares it, else each lens's. Each line starts with `[<profile>] ` when several
30
+ * profiles run, and is inert.
31
+ */
32
+ export declare function bannerLines(config: ResolvedConfig): string[];