rungate 0.8.2 → 0.8.3

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 (63) hide show
  1. package/bin/rungate.ts +11 -6
  2. package/config/prove-evidence.schema.json +21 -3
  3. package/gates/.gate-salt +1 -1
  4. package/gates/gate-executor.ts +153 -1
  5. package/gates/prove.test.ts +12 -6
  6. package/gates/schema.ts +69 -6
  7. package/gates/workflow.test.ts +12 -5
  8. package/hooks/DocHygiene.hook.ts +2 -1
  9. package/hooks/GateResultProtection.hook.ts +28 -7
  10. package/hooks/HookCurrency.hook.ts +48 -1
  11. package/hooks/VerifyPhaseLock.hook.ts +25 -8
  12. package/hooks/WorkflowStateGuard.hook.ts +24 -7
  13. package/lib/ai-review-jury.ts +725 -0
  14. package/lib/ai-review-rounds.ts +791 -4
  15. package/lib/ai-review-unmeasured.ts +361 -0
  16. package/lib/bash-write-guard.ts +1235 -102
  17. package/lib/cli-commands.ts +252 -11
  18. package/lib/closing-reference-audit.ts +163 -0
  19. package/lib/conformity.ts +12 -0
  20. package/lib/create-sc.ts +45 -12
  21. package/lib/derived-spec.ts +206 -0
  22. package/lib/file-claims.ts +335 -0
  23. package/lib/finding-arbiter.ts +502 -28
  24. package/lib/finding-jury.ts +48 -1
  25. package/lib/finding-pr-routing.ts +333 -0
  26. package/lib/frontmatter.ts +16 -0
  27. package/lib/gate-check-audit.ts +259 -0
  28. package/lib/generators/agents-md.ts +29 -0
  29. package/lib/github.ts +112 -7
  30. package/lib/hook-tree-currency.ts +494 -0
  31. package/lib/issue-closure-audit.ts +161 -14
  32. package/lib/issue-create-override.ts +53 -3
  33. package/lib/issue-filing-gate.ts +1073 -76
  34. package/lib/local-review-rounds.ts +523 -0
  35. package/lib/organize.ts +10 -0
  36. package/lib/project-state-shape.ts +56 -5
  37. package/lib/repo-path.ts +94 -0
  38. package/lib/report-provenance.ts +65 -3
  39. package/lib/risk-tier.ts +302 -0
  40. package/lib/rounds-to-pass.ts +274 -0
  41. package/lib/rule-row-drift.ts +199 -0
  42. package/lib/sc-claim-forms.ts +33 -5
  43. package/lib/sc-guard.ts +11 -1
  44. package/lib/sc-id-cross-tree.ts +17 -2
  45. package/lib/sc-ids.ts +71 -6
  46. package/lib/sc-reservations.ts +158 -14
  47. package/lib/scaffold/ai-review-findings.ts +1157 -18
  48. package/lib/scaffold/ai-review-step.ts +3798 -76
  49. package/lib/scaffold/ai-review-unmeasured-workflow.ts +243 -0
  50. package/lib/scaffold/owned-files.ts +14 -0
  51. package/lib/scaffold/steps.ts +83 -9
  52. package/lib/scratch-roots.ts +93 -3
  53. package/lib/spec-updater.ts +16 -0
  54. package/lib/validators/spec-validators.ts +28 -2
  55. package/package.json +2 -1
  56. package/scripts/ai-review-findings.ts +41 -1
  57. package/scripts/arbitrate-finding.ts +330 -12
  58. package/scripts/audit-specs.ts +225 -23
  59. package/scripts/create-sc.ts +11 -0
  60. package/scripts/detect-sc-drift.ts +10 -2
  61. package/scripts/record-ai-review-unmeasured.ts +370 -0
  62. package/scripts/split-spec.ts +12 -0
  63. package/scripts/sync-sc-status.ts +11 -0
@@ -56,6 +56,31 @@ export const WARN_TIER_CHECKS: Readonly<Record<string, string>> = Object.freeze(
56
56
  "gate. Same basis #409 Decision #9 rejected for spec-decision-compliance: a match over " +
57
57
  "prose is not grounds for refusing a run. The reading is lib/ac-quality.ts's " +
58
58
  "goalKeywordCoverage so the threshold is drivable from both sides by a test.",
59
+ "before-state-captured: STANDARD+ must have beforeState in workflow-state":
60
+ "#1411 wrote the check and #1384 found it could not fail on the condition it is named " +
61
+ "for. Measured before deciding, over the 155 workflow-state.json files under ~/.rungate " +
62
+ "on 2026-10-24: 30 are STANDARD or THOROUGH, and 30 of those 30 — 100% — have no " +
63
+ "beforeState at all. Not one run in the corpus has ever carried one. The reason is the " +
64
+ "producer, not the runs: nothing in the shipped tree WRITES beforeState. gates/schema.ts " +
65
+ "declares its shape, gates/gate-executor.ts reads it with a `|| null` fallback and " +
66
+ "workflows/prove.js reads it if present; the only thing that describes writing one is " +
67
+ "reference/prompts/goal-skill.md, and this project has been in direct-ship mode since " +
68
+ "2026-10-19, so no goal skill runs. Making this refuse would fail every STANDARD+ run " +
69
+ "immediately — the #423 basis exactly, where 71% was already judged an outage rather " +
70
+ "than a gate. The missing producer is the fixable half and is filed separately; this " +
71
+ "entry is the honest reading until something writes the field.",
72
+ "brief-ac-alignment: brief covers all ACs":
73
+ "#1384 named this through the widened path-level predicate, and the warn-return is a " +
74
+ "deliberate scope-out rather than a swallowed refusal. The condition the check is named " +
75
+ "for DOES refuse: lib/brief-ac-alignment.ts returns BRIEF_ABSENT with a refusal when " +
76
+ "Marcus was spawned and no brief exists, and IDS_MISSING when the brief omits an AC, " +
77
+ "and gates/workflow.test.ts asserts `reading.refusal` is null. The warned path is the " +
78
+ "fourth reading, NOT_APPLICABLE, which fires only when Marcus was never spawned — so " +
79
+ "nothing was expected to write a brief. That reading exists because the inline version " +
80
+ "returned bare in two places and made 'decided nothing was wrong' and 'declined to " +
81
+ "look' the same observation; per .claude/rules/config-access.md that is UNMEASURED, not " +
82
+ "a pass, and it is reported with the resolved path rather than silently. Turning a " +
83
+ "scope-out into a refusal would fail every run that does not spawn Marcus.",
59
84
  });
60
85
 
61
86
  /**
@@ -166,6 +191,240 @@ export function checksWithoutAssertions(source: string): GateCheck[] {
166
191
  return gateChecks(source).filter(c => !c.hasAssertion && c.name !== STANDALONE_STUB_NAME);
167
192
  }
168
193
 
194
+ /** One `console.warn` that leads out of a check with nothing asserted (#1384). */
195
+ export interface WarnReturnPath {
196
+ /** The check's name, as written. */
197
+ check: string;
198
+ /** 1-indexed line of the `test(` call. */
199
+ line: number;
200
+ /** 1-indexed line of the `console.warn` that leads the path. */
201
+ warnLine: number;
202
+ }
203
+
204
+ /**
205
+ * The view this detector takes, stated rather than left to be inferred.
206
+ *
207
+ * It is anchored on `console.warn`, and that is a deliberate narrowing. The
208
+ * general property — "a path through the check executes no assertion" — holds
209
+ * for `if (tier === "LIGHT") return;`, which opens most checks in the suite
210
+ * and is legitimate scoping rather than a swallowed refusal. A predicate that
211
+ * named those would report the whole file and be switched off within a day.
212
+ *
213
+ * A `console.warn` is the author writing down that something is wrong. A warn
214
+ * followed by a path that leaves the check without asserting is that author
215
+ * declining to refuse — which is the thing `WARN_TIER_CHECKS` exists to make
216
+ * someone decide about, in the one place the body-level predicate cannot see.
217
+ *
218
+ * Per `.claude/rules/checks-must-be-able-to-fail.md`, the direction this is
219
+ * allowed to be wrong in is toward NOT naming: an intervening `expect` at any
220
+ * depth disqualifies a candidate, even one a branch could skip. A missed check
221
+ * costs an entry nobody wrote; a false one costs the list its credibility.
222
+ */
223
+ const WARN_CALL = /^console\s*\.\s*warn\s*\(/;
224
+ const EXPECT_CALL = /^expect\s*(?:<[^>()]*>)?\s*\(/;
225
+ const RETURN_KEYWORD = /^return\b/;
226
+ const IF_KEYWORD = /^if\b/;
227
+ /**
228
+ * The keywords that open a branch excluding the one before it.
229
+ *
230
+ * Brace depth alone only notices exclusivity when the branches are braced and
231
+ * the depth dips between them. `if (a) expect(p); else console.warn(x);` puts
232
+ * both at the same depth with nothing closing in between, and so does a
233
+ * `switch`, so the assertion was credited to a path that can never run it.
234
+ * PR #1539's review caught that.
235
+ */
236
+ const BRANCH_SPLIT = /^(?:else|case|default)\b/;
237
+
238
+ type PathToken = {
239
+ kind: "expect" | "warn" | "return";
240
+ at: number;
241
+ depth: number;
242
+ /**
243
+ * The shallowest depth reached between the previous token and this one.
244
+ *
245
+ * Without it a forward scan can only compare each token's own depth against
246
+ * the warn's, which cannot see a block closing and re-opening in between —
247
+ * so a `return` inside a LATER, unrelated branch reads as the warn's own
248
+ * path leaving the check. PR #1539's review caught exactly that.
249
+ */
250
+ minBefore: number;
251
+ };
252
+
253
+ /**
254
+ * Bracket-depth-aware token scan over a check body, skipping strings and
255
+ * comments the way `matchingParen` does.
256
+ *
257
+ * `assertDepth` is the shallowest depth at which an `expect` has been seen
258
+ * whose enclosing block has not since closed — i.e. an assertion that runs on
259
+ * every path reaching the current position. It resets when depth falls below
260
+ * it, because that is the block closing.
261
+ */
262
+ function pathTokens(body: string): { tokens: PathToken[]; assertDepthAt: Map<number, number | null> } {
263
+ const tokens: PathToken[] = [];
264
+ const assertDepthAt = new Map<number, number | null>();
265
+ let depth = 0;
266
+ let assertDepth: number | null = null;
267
+ /** Where the assertion that set `assertDepth` sits, so an `else` can tell
268
+ * whether it lives in the branch being superseded. */
269
+ let assertAt = -1;
270
+ /** The most recent `if`/`switch` head seen at each depth. */
271
+ const branchHeadAt = new Map<number, number>();
272
+ let minSinceToken = 0;
273
+ const push = (kind: PathToken["kind"], at: number) => {
274
+ tokens.push({ kind, at, depth, minBefore: Math.min(minSinceToken, depth) });
275
+ minSinceToken = depth;
276
+ };
277
+ for (let i = 0; i < body.length; i++) {
278
+ const c = body[i]!;
279
+ const next = body[i + 1];
280
+ if (c === "/" && next === "/") {
281
+ const nl = body.indexOf("\n", i);
282
+ i = nl === -1 ? body.length : nl;
283
+ continue;
284
+ }
285
+ if (c === "/" && next === "*") {
286
+ const close = body.indexOf("*/", i + 2);
287
+ i = close === -1 ? body.length : close + 1;
288
+ continue;
289
+ }
290
+ if (c === '"' || c === "'" || c === "`") {
291
+ const quote = c;
292
+ i++;
293
+ for (; i < body.length; i++) {
294
+ if (body[i] === "\\") { i++; continue; }
295
+ if (body[i] === quote) break;
296
+ if (quote === "`" && body[i] === "$" && body[i + 1] === "{") {
297
+ let d = 1;
298
+ i += 2;
299
+ for (; i < body.length && d > 0; i++) {
300
+ if (body[i] === "{") d++;
301
+ else if (body[i] === "}") d--;
302
+ }
303
+ i--;
304
+ }
305
+ }
306
+ continue;
307
+ }
308
+ if (c === "(" || c === "[" || c === "{") { depth++; continue; }
309
+ if (c === ")" || c === "]" || c === "}") {
310
+ depth--;
311
+ if (depth < minSinceToken) minSinceToken = depth;
312
+ if (assertDepth !== null && depth < assertDepth) { assertDepth = null; assertAt = -1; }
313
+ continue;
314
+ }
315
+ // Only start a keyword match at an identifier boundary, so `s.expect(`
316
+ // and `myreturn` are not read as the bare forms.
317
+ if (!/[A-Za-z_$]/.test(c)) continue;
318
+ if (i > 0 && /[\w$.]/.test(body[i - 1]!)) continue;
319
+ const rest = body.slice(i, i + 200);
320
+ if (IF_KEYWORD.test(rest) || /^switch\b/.test(rest)) {
321
+ branchHeadAt.set(depth, i);
322
+ continue;
323
+ }
324
+ if (BRANCH_SPLIT.test(rest)) {
325
+ // This opens a branch excluding the one before it. An assertion is
326
+ // superseded only if it lives INSIDE that preceding branch — i.e. after
327
+ // the `if`/`switch` head this pairs with. An `expect` written before the
328
+ // head runs on every path, including this one, so it still counts.
329
+ // An `else` sits at its `if`'s own depth; a `case` sits one level INSIDE
330
+ // its `switch`'s braces. Take whichever head is nearer — that is the
331
+ // construct this branch belongs to.
332
+ const head = Math.max(branchHeadAt.get(depth) ?? -1, branchHeadAt.get(depth - 1) ?? -1);
333
+ if (assertDepth !== null && head >= 0 && assertAt > head) {
334
+ assertDepth = null;
335
+ assertAt = -1;
336
+ }
337
+ continue;
338
+ }
339
+ if (EXPECT_CALL.test(rest)) {
340
+ push("expect", i);
341
+ if (assertDepth === null || depth < assertDepth) assertAt = i;
342
+ assertDepth = assertDepth === null ? depth : Math.min(assertDepth, depth);
343
+ } else if (WARN_CALL.test(rest)) {
344
+ push("warn", i);
345
+ assertDepthAt.set(i, assertDepth);
346
+ } else if (RETURN_KEYWORD.test(rest)) {
347
+ push("return", i);
348
+ }
349
+ }
350
+ return { tokens, assertDepthAt };
351
+ }
352
+
353
+ /**
354
+ * Every `console.warn` whose path leaves the check with nothing asserted.
355
+ *
356
+ * Two conditions, and both are about the PATH rather than the body:
357
+ *
358
+ * - nothing has asserted on the way to the warn — no `expect` whose enclosing
359
+ * block still contains it;
360
+ * - nothing asserts after it either — the path reaches a `return` at or above
361
+ * the warn's own depth, or runs out of check, without meeting an `expect`.
362
+ *
363
+ * Both halves of the second condition are implemented, and the second half is
364
+ * the `else { console.warn(...) }` shape that gets past the body-level
365
+ * predicate as well: the sibling branch's `expect` makes the body assert.
366
+ *
367
+ * Falling out of an `if` into an assertion below is NOT a finding: once the
368
+ * warn's own enclosing block closes, the path has merged back into the main
369
+ * flow and reaches whatever that flow asserts. A `return` belonging to a
370
+ * later, unrelated branch is that flow's, not this warn's.
371
+ */
372
+ export function unassertedWarnPaths(source: string): WarnReturnPath[] {
373
+ const out: WarnReturnPath[] = [];
374
+ for (const check of gateChecks(source)) {
375
+ if (check.name === STANDALONE_STUB_NAME) continue;
376
+ const { tokens, assertDepthAt } = pathTokens(check.body);
377
+ for (let t = 0; t < tokens.length; t++) {
378
+ const warn = tokens[t]!;
379
+ if (warn.kind !== "warn") continue;
380
+ if (assertDepthAt.get(warn.at) !== null) continue;
381
+ // The warn leaves the check only if it reaches a `return` while still
382
+ // inside its OWN enclosing block. Once the running minimum drops below
383
+ // the warn's depth that block has closed, the path has merged back into
384
+ // the main flow, and every `return` and `expect` after that belongs to
385
+ // the flow rather than to this warn.
386
+ // Running out of tokens IS the path leaving: nothing asserts after the
387
+ // warn, so it reaches the end of the check unasserted. That is the
388
+ // `else { console.warn(...) }` shape, which gets past both halves of
389
+ // the audit — the sibling branch's `expect` makes the body assert, and
390
+ // there is no `return` for this scan to stop on.
391
+ let leaves = true;
392
+ let runningMin = warn.depth;
393
+ for (let u = t + 1; u < tokens.length; u++) {
394
+ const after = tokens[u]!;
395
+ runningMin = Math.min(runningMin, after.minBefore);
396
+ if (runningMin < warn.depth) { leaves = false; break; }
397
+ if (after.kind === "expect") { leaves = false; break; }
398
+ if (after.kind === "return" && after.depth <= warn.depth) break;
399
+ }
400
+ if (!leaves) continue;
401
+ out.push({
402
+ check: check.name,
403
+ line: check.line,
404
+ // The body starts partway through the `test(` line, so the warn's line
405
+ // is the check's line plus the newlines before it inside the body.
406
+ warnLine: check.line + (check.body.slice(0, warn.at).match(/\n/g) || []).length,
407
+ });
408
+ }
409
+ }
410
+ return out;
411
+ }
412
+
413
+ /**
414
+ * Every check that cannot fail on the condition it is named for — the union of
415
+ * the body-level and path-level readings, in source order.
416
+ *
417
+ * This is the one binding the audit reads. `checksWithoutAssertions` stays
418
+ * exported because it is the narrower of the two and the tests use it as the
419
+ * recorded baseline: it is what the audit could see before #1384.
420
+ */
421
+ export function checksThatCannotFail(source: string): GateCheck[] {
422
+ const warned = new Set(unassertedWarnPaths(source).map(p => p.check));
423
+ return gateChecks(source).filter(
424
+ c => c.name !== STANDALONE_STUB_NAME && (!c.hasAssertion || warned.has(c.name)),
425
+ );
426
+ }
427
+
169
428
  /** The standalone placeholders, so their emptiness can be asserted. */
170
429
  export function standaloneStubs(source: string): GateCheck[] {
171
430
  return gateChecks(source).filter(c => c.name === STANDALONE_STUB_NAME);
@@ -11,6 +11,7 @@ import { existsSync, readFileSync } from "fs";
11
11
  import { join } from "path";
12
12
  import type { ProjectScan } from "./types";
13
13
  import { OWNED_FILES, ownedFilesTable } from "../scaffold/owned-files";
14
+ import { commandRoutingTable } from "../cli-commands";
14
15
  import { isHarnessItself } from "../harness-identity";
15
16
  import { typecheckDecision } from "../typescript-project";
16
17
  import { localCalendarDay } from "../local-calendar-day";
@@ -408,6 +409,34 @@ ${createRows.join("\n")}
408
409
  });
409
410
  }
410
411
 
412
+ // #1309. The three rules above route DOCUMENTS, and `key-files.md` routes
413
+ // FILES. Nothing routed the project's CLI, so a command reached an agent
414
+ // only if somebody had hand-written a row for it in AGENTS.md's Commands
415
+ // table — four of ten, and the generated table reads as complete, so
416
+ // nothing signals that six more exist. Seven of the ten were named in no
417
+ // file an agent loads at launch.
418
+ //
419
+ // Un-scoped on purpose: a `paths:` key here would move the rule out of the
420
+ // launch surface, and the whole defect is a command nobody loads. It is the
421
+ // cheapest thing to reach for when the byte budget complains, so
422
+ // `test/commands-routed.test.ts` refuses it by name.
423
+ const cliPrefix = isHarnessItself(scan.root) ? "bun bin/rungate.ts" : "bunx rungate";
424
+ rules.push({
425
+ filename: "commands-routing.md",
426
+ content: `---
427
+ description: Every command the rungate CLI exposes in this project, generated from its command registry
428
+ ---
429
+
430
+ ## Command Routing
431
+
432
+ Generated from the CLI's own command registry, so it cannot list a subset.
433
+ Run one as \`${cliPrefix} <command>\`.
434
+ \`${cliPrefix} --help\` prints each command's own arguments.
435
+
436
+ ${commandRoutingTable()}
437
+ `,
438
+ });
439
+
411
440
  rules.push({
412
441
  filename: "harness-managed.md",
413
442
  content: `---
package/lib/github.ts CHANGED
@@ -317,8 +317,39 @@ export interface OpenIssue {
317
317
  number: number;
318
318
  title: string;
319
319
  body: string;
320
+ /**
321
+ * The author's relationship to the repository, verbatim from the API.
322
+ *
323
+ * Carried because a caller that uses issue text as a SUPPRESSION input has
324
+ * to know who wrote it — see `TRUSTED_ASSOCIATIONS`. Not interpreted here:
325
+ * this function reports what GitHub said and the policy lives with the
326
+ * caller that has something to lose.
327
+ */
328
+ authorAssociation: string;
320
329
  }
321
330
 
331
+ /**
332
+ * Issue authors whose text may be used to suppress something.
333
+ *
334
+ * `hornjason/pai-harness` is a PUBLIC repository, so **anyone on the internet
335
+ * can open an issue**, and `lib/issue-filing-gate.ts` deduplicates proposed
336
+ * filings against the open-issue corpus. Without this filter that is a
337
+ * remote, unauthenticated path to switching off our own quality mechanism:
338
+ * open an issue stuffed with the right symbols, files and readings, and every
339
+ * future finding that shares them is refused as a duplicate. A suppressed
340
+ * finding is indistinguishable from a finding nobody had, so it is silent.
341
+ *
342
+ * `NONE`, `CONTRIBUTOR` and `FIRST_TIME_CONTRIBUTOR` are excluded. A drive-by
343
+ * issue can still be a real duplicate, and excluding it costs one duplicate
344
+ * filing — the direction this is allowed to be wrong in. Including it costs
345
+ * real findings, which is the direction nothing here may fail in.
346
+ */
347
+ export const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set([
348
+ "OWNER",
349
+ "MEMBER",
350
+ "COLLABORATOR",
351
+ ]);
352
+
322
353
  /**
323
354
  * Open issues, newest first, **pull requests excluded** (#1261).
324
355
  *
@@ -337,28 +368,102 @@ export interface OpenIssue {
337
368
  * filing most likely to collide with an open PR is the one reporting the
338
369
  * defect that PR has not yet merged. That is the exact filing this gate must
339
370
  * not silence.
371
+ *
372
+ * ## It returns a PAGE, not a list, and that is the whole of #1374
373
+ *
374
+ * This used to return `OpenIssue[]`, so the only count a caller could take
375
+ * was a POST-filter one. `lib/issue-filing-gate.ts` took it, and its guard
376
+ * against "a corpus we emptied is not a clean tracker" was therefore blind to
377
+ * a page we had emptied **here**: 100 pull requests arrived as zero issues,
378
+ * the caller read `considered === 0`, and a page holding nothing usable was
379
+ * reported as a tracker holding nothing. The same fail-open #1338 closed, one
380
+ * level up, with a function boundary between the filter and the counter.
381
+ *
382
+ * So the filter now reports what it dropped, in the same value. The fix is
383
+ * not a fourth check at the caller's depth — it is moving the boundary, so
384
+ * there is no depth left at which a count can be taken of something already
385
+ * filtered. A caller that wants only the issues reads `.issues`; it can no
386
+ * longer do so without the population being in its hand.
387
+ *
388
+ * `truncated` is the second half, and it is the one that is weeks away rather
389
+ * than live: one page, no pagination, so a tracker with more open issues than
390
+ * `limit` returns exactly `limit` and a caller cannot tell a complete answer
391
+ * from a cut-off one. It is reported rather than fixed by paginating, because
392
+ * what the dedupe needs is to KNOW the comparison was narrower than the
393
+ * question, and that is true of a second page nobody fetched as well.
394
+ */
395
+ export interface DroppedRow {
396
+ /** The row's number when it had a usable one, else `null`. */
397
+ number: number | null;
398
+ reason: "pull-request" | "malformed-row";
399
+ }
400
+
401
+ /**
402
+ * One page of open issues, with the population it was drawn from.
403
+ *
404
+ * `considered` is the count **before** this module dropped anything, so a
405
+ * caller deciding whether its own empty result is a reading or the absence of
406
+ * one has the number that question needs.
340
407
  */
408
+ export interface OpenIssuePage {
409
+ /** Rows the API returned, before any filter here saw them. */
410
+ considered: number;
411
+ /** The page size actually requested, which is not always `limit`. */
412
+ perPage: number;
413
+ /** The page came back full, so the tracker may hold rows nobody fetched. */
414
+ truncated: boolean;
415
+ /** Every row this module dropped, with why. */
416
+ droppedRows: DroppedRow[];
417
+ issues: OpenIssue[];
418
+ }
419
+
341
420
  export async function listOpenIssues(
342
421
  client: GitHubClient,
343
422
  repoSlug: string,
344
423
  limit = 100,
345
- ): Promise<OpenIssue[]> {
424
+ ): Promise<OpenIssuePage> {
346
425
  const { owner, repo } = parseOwnerRepo(repoSlug);
426
+ const perPage = Math.min(Math.max(limit, 1), 100);
347
427
  const response = await client.rest.issues.listForRepo({
348
428
  owner,
349
429
  repo,
350
430
  state: "open",
351
- per_page: Math.min(Math.max(limit, 1), 100),
431
+ per_page: perPage,
352
432
  });
353
433
  const rows = Array.isArray(response?.data) ? response.data : [];
354
- return rows
355
- .filter(row => row !== null && typeof row === "object" && row.pull_request === undefined)
356
- .filter(row => typeof row.number === "number" && typeof row.title === "string")
357
- .map(row => ({
434
+ const issues: OpenIssue[] = [];
435
+ const droppedRows: DroppedRow[] = [];
436
+ for (const row of rows) {
437
+ // Order matters for the reason recorded, never for the verdict. A null
438
+ // row is malformed and not a pull request, and a row reported under the
439
+ // wrong reason is a report nobody can act on.
440
+ if (row === null || typeof row !== "object") {
441
+ droppedRows.push({ number: null, reason: "malformed-row" });
442
+ continue;
443
+ }
444
+ const numbered = typeof row.number === "number" ? (row.number as number) : null;
445
+ if (row.pull_request !== undefined) {
446
+ droppedRows.push({ number: numbered, reason: "pull-request" });
447
+ continue;
448
+ }
449
+ if (typeof row.number !== "number" || typeof row.title !== "string") {
450
+ droppedRows.push({ number: numbered, reason: "malformed-row" });
451
+ continue;
452
+ }
453
+ issues.push({
358
454
  number: row.number as number,
359
455
  title: row.title as string,
360
456
  body: typeof row.body === "string" ? row.body : "",
361
- }));
457
+ // An absent association is not a trusted one. `""` fails every
458
+ // membership test in `TRUSTED_ASSOCIATIONS`, which is the reading a
459
+ // caller should get when GitHub did not say.
460
+ authorAssociation: typeof row.author_association === "string" ? row.author_association : "",
461
+ });
462
+ }
463
+ // `>=` and not `>`: a full page is the only observation available, and the
464
+ // API cannot return more than was asked for, so `>` is a predicate that can
465
+ // never fire. It is the cheapest wrong spelling of this line.
466
+ return { considered: rows.length, perPage, truncated: rows.length >= perPage, droppedRows, issues };
362
467
  }
363
468
 
364
469
  /**