@intentius/chant 0.124.97 → 0.124.98

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 (223) hide show
  1. package/dist/audit/core.d.ts +29 -0
  2. package/dist/audit/core.d.ts.map +1 -1
  3. package/dist/audit/core.js +48 -11
  4. package/dist/audit/identity.d.ts +27 -0
  5. package/dist/audit/identity.d.ts.map +1 -0
  6. package/dist/audit/identity.js +36 -0
  7. package/dist/audit/report-html.d.ts +3 -1
  8. package/dist/audit/report-html.d.ts.map +1 -1
  9. package/dist/audit/report-html.js +1 -1
  10. package/dist/audit/report-model.d.ts +16 -0
  11. package/dist/audit/report-model.d.ts.map +1 -1
  12. package/dist/audit/report-model.js +5 -1
  13. package/dist/ci-agent.d.ts +17 -0
  14. package/dist/ci-agent.d.ts.map +1 -1
  15. package/dist/ci-agent.js +32 -0
  16. package/dist/ci-comment-allow.d.ts +88 -0
  17. package/dist/ci-comment-allow.d.ts.map +1 -0
  18. package/dist/ci-comment-allow.js +178 -0
  19. package/dist/ci-comment-commands.d.ts +12 -0
  20. package/dist/ci-comment-commands.d.ts.map +1 -1
  21. package/dist/ci-comment-commands.js +22 -0
  22. package/dist/ci-control.d.ts +6 -1
  23. package/dist/ci-control.d.ts.map +1 -1
  24. package/dist/ci-control.js +6 -1
  25. package/dist/ci-product.d.ts +3 -0
  26. package/dist/ci-product.d.ts.map +1 -1
  27. package/dist/ci-product.js +3 -0
  28. package/dist/cli/commands/audit.d.ts +3 -1
  29. package/dist/cli/commands/audit.d.ts.map +1 -1
  30. package/dist/cli/commands/audit.js +23 -6
  31. package/dist/cli/commands/import.d.ts +8 -1
  32. package/dist/cli/commands/import.d.ts.map +1 -1
  33. package/dist/cli/commands/import.js +31 -6
  34. package/dist/cli/handlers/agent.d.ts.map +1 -1
  35. package/dist/cli/handlers/agent.js +12 -2
  36. package/dist/cli/handlers/pr-comment.d.ts +6 -0
  37. package/dist/cli/handlers/pr-comment.d.ts.map +1 -1
  38. package/dist/cli/handlers/pr-comment.js +12 -0
  39. package/dist/cli/handlers/promote.d.ts.map +1 -1
  40. package/dist/cli/handlers/promote.js +53 -6
  41. package/dist/cli/main.d.ts.map +1 -1
  42. package/dist/cli/main.js +29 -6
  43. package/dist/cli/parse-args.d.ts.map +1 -1
  44. package/dist/cli/parse-args.js +23 -0
  45. package/dist/cli/registry.d.ts +8 -0
  46. package/dist/cli/registry.d.ts.map +1 -1
  47. package/dist/cloud-lister/mask.d.ts +30 -1
  48. package/dist/cloud-lister/mask.d.ts.map +1 -1
  49. package/dist/cloud-lister/mask.js +66 -3
  50. package/dist/components/driver.d.ts +8 -1
  51. package/dist/components/driver.d.ts.map +1 -1
  52. package/dist/components/driver.js +1 -0
  53. package/dist/components/product-pipeline.d.ts +23 -1
  54. package/dist/components/product-pipeline.d.ts.map +1 -1
  55. package/dist/components/product-pipeline.js +40 -7
  56. package/dist/components/product-plan.d.ts +20 -0
  57. package/dist/components/product-plan.d.ts.map +1 -1
  58. package/dist/components/product-plan.js +11 -1
  59. package/dist/control/applied.d.ts +8 -1
  60. package/dist/control/applied.d.ts.map +1 -1
  61. package/dist/control/applied.js +18 -2
  62. package/dist/control/dispatch.d.ts +52 -0
  63. package/dist/control/dispatch.d.ts.map +1 -1
  64. package/dist/control/dispatch.js +140 -4
  65. package/dist/control/train.d.ts +198 -0
  66. package/dist/control/train.d.ts.map +1 -0
  67. package/dist/control/train.js +294 -0
  68. package/dist/deep-observation.js +2 -2
  69. package/dist/floor-table.data.d.ts.map +1 -1
  70. package/dist/floor-table.data.js +11 -0
  71. package/dist/graph-detail.d.ts +9 -0
  72. package/dist/graph-detail.d.ts.map +1 -1
  73. package/dist/graph-detail.js +38 -13
  74. package/dist/graph-refs.d.ts +233 -3
  75. package/dist/graph-refs.d.ts.map +1 -1
  76. package/dist/graph-refs.js +106 -15
  77. package/dist/lint/post-synth.d.ts +22 -0
  78. package/dist/lint/post-synth.d.ts.map +1 -1
  79. package/dist/lint/rules/declarable-naming-convention.d.ts +12 -0
  80. package/dist/lint/rules/declarable-naming-convention.d.ts.map +1 -1
  81. package/dist/lint/rules/declarable-naming-convention.js +38 -8
  82. package/dist/lint/rules/imported-source.d.ts +20 -0
  83. package/dist/lint/rules/imported-source.d.ts.map +1 -0
  84. package/dist/lint/rules/imported-source.js +27 -0
  85. package/dist/lint/rules/no-unused-declarable.d.ts.map +1 -1
  86. package/dist/lint/rules/no-unused-declarable.js +3 -0
  87. package/dist/op/gate.d.ts +2 -0
  88. package/dist/op/gate.d.ts.map +1 -1
  89. package/dist/op/gate.js +8 -1
  90. package/dist/pr-forge-reads.d.ts +17 -0
  91. package/dist/pr-forge-reads.d.ts.map +1 -1
  92. package/dist/pr-forge-reads.js +55 -0
  93. package/dist/release-floors.d.ts +9 -1
  94. package/dist/release-floors.d.ts.map +1 -1
  95. package/dist/release-floors.js +9 -1
  96. package/dist/repo-path.d.ts +29 -0
  97. package/dist/repo-path.d.ts.map +1 -0
  98. package/dist/repo-path.js +81 -0
  99. package/dist/sensitive-key.d.ts +23 -0
  100. package/dist/sensitive-key.d.ts.map +1 -1
  101. package/dist/sensitive-key.js +37 -0
  102. package/dist/terraform/hcl2json.d.ts +7 -0
  103. package/dist/terraform/hcl2json.d.ts.map +1 -1
  104. package/dist/terraform/hcl2json.js +7 -0
  105. package/dist/wave-runtime.mjs +352 -345
  106. package/dist/workspace/catalog-edges.d.ts +147 -0
  107. package/dist/workspace/catalog-edges.d.ts.map +1 -0
  108. package/dist/workspace/catalog-edges.js +461 -0
  109. package/dist/workspace/compose-graph.d.ts +73 -3
  110. package/dist/workspace/compose-graph.d.ts.map +1 -1
  111. package/dist/workspace/declaration.d.ts +2 -0
  112. package/dist/workspace/declaration.d.ts.map +1 -1
  113. package/dist/workspace/declaration.js +1 -0
  114. package/dist/workspace/declaration.schema.json +6 -0
  115. package/dist/workspace/discover.d.ts +134 -0
  116. package/dist/workspace/discover.d.ts.map +1 -0
  117. package/dist/workspace/discover.js +372 -0
  118. package/dist/workspace/graph-cli.d.ts +20 -0
  119. package/dist/workspace/graph-cli.d.ts.map +1 -1
  120. package/dist/workspace/graph-cli.js +178 -20
  121. package/dist/workspace/graph.schema.json +195 -2
  122. package/dist/workspace/release-train.d.ts +214 -3
  123. package/dist/workspace/release-train.d.ts.map +1 -1
  124. package/dist/workspace/release-train.js +552 -16
  125. package/dist/workspace/repo-ref.d.ts +14 -0
  126. package/dist/workspace/repo-ref.d.ts.map +1 -1
  127. package/dist/workspace/repo-ref.js +26 -1
  128. package/dist/workspace/workspace-gates.d.ts +24 -0
  129. package/dist/workspace/workspace-gates.d.ts.map +1 -1
  130. package/dist/workspace/workspace-gates.js +29 -5
  131. package/dist/workspace/workspace-ledger.d.ts +31 -5
  132. package/dist/workspace/workspace-ledger.d.ts.map +1 -1
  133. package/dist/workspace/workspace-ledger.js +2 -1
  134. package/dist/workspace/workspace-run.d.ts +14 -0
  135. package/dist/workspace/workspace-run.d.ts.map +1 -1
  136. package/dist/workspace/workspace-run.js +2 -2
  137. package/dist/yaml.d.ts.map +1 -1
  138. package/dist/yaml.js +33 -8
  139. package/package.json +1 -1
  140. package/src/audit/core.test.ts +64 -1
  141. package/src/audit/core.ts +75 -10
  142. package/src/audit/identity.test.ts +31 -0
  143. package/src/audit/identity.ts +43 -0
  144. package/src/audit/report-html.ts +4 -2
  145. package/src/audit/report-model.ts +21 -1
  146. package/src/ci-agent.test.ts +32 -0
  147. package/src/ci-agent.ts +42 -0
  148. package/src/ci-comment-allow.test.ts +380 -0
  149. package/src/ci-comment-allow.ts +184 -0
  150. package/src/ci-comment-commands.ts +25 -0
  151. package/src/ci-control.ts +42 -0
  152. package/src/ci-product.ts +3 -0
  153. package/src/cli/commands/audit-parser-notice.test.ts +74 -0
  154. package/src/cli/commands/audit.test.ts +12 -0
  155. package/src/cli/commands/audit.ts +25 -7
  156. package/src/cli/commands/import-layout.test.ts +2 -1
  157. package/src/cli/commands/import.ts +29 -6
  158. package/src/cli/handlers/agent.ts +13 -2
  159. package/src/cli/handlers/pr-comment.ts +12 -0
  160. package/src/cli/handlers/promote.test.ts +68 -0
  161. package/src/cli/handlers/promote.ts +52 -6
  162. package/src/cli/main.test.ts +5 -0
  163. package/src/cli/main.ts +29 -6
  164. package/src/cli/parse-args.ts +18 -0
  165. package/src/cli/registry.ts +8 -0
  166. package/src/cloud-lister/kubernetes.k3d.e2e.test.ts +104 -0
  167. package/src/cloud-lister/mask-references.test.ts +132 -0
  168. package/src/cloud-lister/mask.ts +68 -3
  169. package/src/components/driver.ts +9 -1
  170. package/src/components/product-pipeline.ts +57 -7
  171. package/src/components/product-plan.ts +27 -2
  172. package/src/control/applied.ts +33 -3
  173. package/src/control/dispatch.ts +156 -5
  174. package/src/control/train.test.ts +215 -0
  175. package/src/control/train.ts +413 -0
  176. package/src/deep-observation.ts +2 -2
  177. package/src/floor-table.data.ts +6 -0
  178. package/src/graph-detail.ts +37 -12
  179. package/src/graph-refs.test.ts +45 -1
  180. package/src/graph-refs.ts +321 -14
  181. package/src/lint/post-synth.ts +20 -0
  182. package/src/lint/rules/declarable-naming-convention.test.ts +35 -1
  183. package/src/lint/rules/declarable-naming-convention.ts +35 -8
  184. package/src/lint/rules/imported-source.test.ts +22 -0
  185. package/src/lint/rules/imported-source.ts +31 -0
  186. package/src/lint/rules/no-unused-declarable.test.ts +16 -0
  187. package/src/lint/rules/no-unused-declarable.ts +7 -0
  188. package/src/op/gate.ts +10 -2
  189. package/src/pr-forge-reads.ts +62 -0
  190. package/src/release-floors.ts +13 -1
  191. package/src/repo-path.test.ts +72 -0
  192. package/src/repo-path.ts +103 -0
  193. package/src/sensitive-key.ts +38 -0
  194. package/src/terraform/hcl2json.ts +8 -0
  195. package/src/workspace/application-set.e2e.test.ts +405 -0
  196. package/src/workspace/catalog-edges.ts +507 -0
  197. package/src/workspace/ci-green-workflow.test.ts +2 -2
  198. package/src/workspace/cluster-join.e2e.test.ts +150 -0
  199. package/src/workspace/compose-graph.ts +74 -5
  200. package/src/workspace/declaration.schema.json +6 -0
  201. package/src/workspace/declaration.ts +3 -0
  202. package/src/workspace/discover.e2e.test.ts +122 -0
  203. package/src/workspace/discover.test.ts +225 -0
  204. package/src/workspace/discover.ts +406 -0
  205. package/src/workspace/external-secret-catalog.e2e.test.ts +98 -0
  206. package/src/workspace/external-secret-catalog.test.ts +142 -0
  207. package/src/workspace/graph-cli.ts +207 -21
  208. package/src/workspace/graph-contract.test.ts +92 -0
  209. package/src/workspace/graph.schema.json +195 -2
  210. package/src/workspace/helm-references.e2e.test.ts +135 -0
  211. package/src/workspace/identity-annotation-catalog.e2e.test.ts +91 -0
  212. package/src/workspace/identity-annotation-catalog.test.ts +139 -0
  213. package/src/workspace/release-train-repos.test.ts +304 -0
  214. package/src/workspace/release-train.test.ts +296 -0
  215. package/src/workspace/release-train.ts +631 -16
  216. package/src/workspace/repo-ref.ts +26 -1
  217. package/src/workspace/runs-on.test.ts +45 -0
  218. package/src/workspace/workspace-gates.ts +48 -5
  219. package/src/workspace/workspace-ledger.ts +28 -5
  220. package/src/workspace/workspace-run.test.ts +1 -1
  221. package/src/workspace/workspace-run.ts +2 -2
  222. package/src/yaml.test.ts +96 -8
  223. package/src/yaml.ts +36 -8
package/src/audit/core.ts CHANGED
@@ -20,7 +20,8 @@
20
20
  * audit too, with no output-reading rule variants to drift.
21
21
  */
22
22
 
23
- import { basename } from "path";
23
+ import { statSync } from "fs";
24
+ import { basename, dirname, resolve } from "path";
24
25
  import type { Severity } from "../lint/rule";
25
26
  import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../lint/post-synth";
26
27
  import { applyInlineSuppressions, type SuppressionMetaFinding } from "../lint/suppressions";
@@ -96,6 +97,8 @@ export interface AuditFinding {
96
97
  fingerprint?: string;
97
98
  /** Carried verbatim from the producing `PostSynthDiagnostic.missing` (chant #2113) — see its doc comment. */
98
99
  missing?: { kind: string; scope: string };
100
+ /** Carried verbatim from the producing `PostSynthDiagnostic.locator` (#5106); one input of the finding's identity. */
101
+ locator?: string;
99
102
  }
100
103
 
101
104
  /**
@@ -225,6 +228,43 @@ async function defaultEntitiesProvider(lexicon: AuditLexicon): Promise<EntitiesP
225
228
  return parser;
226
229
  }
227
230
 
231
+ /**
232
+ * A lexicon whose files were found but not read, because an optional parser it
233
+ * needs is not installed (#5083). Without this a missing parser and a clean
234
+ * repository both produce no findings. `paths` are the audited inputs the
235
+ * lexicon could not read (for terraform, directories).
236
+ */
237
+ export interface AuditSkip {
238
+ lexicon: string;
239
+ reason: "parser-not-installed";
240
+ /** The npm package to install. */
241
+ package: string;
242
+ /** The command that installs it. */
243
+ install: string;
244
+ paths: string[];
245
+ }
246
+
247
+ /**
248
+ * The npm package an entities parser reports as missing: any error with a
249
+ * string `parserPackage` property. A lexicon sets it instead of importing a
250
+ * class from here, which keeps lexicon packages free of audit internals.
251
+ */
252
+ export function parserPackageOf(err: unknown): string | undefined {
253
+ const pkg = (err as { parserPackage?: unknown } | null)?.parserPackage;
254
+ return typeof pkg === "string" ? pkg : undefined;
255
+ }
256
+
257
+ /** The sentence `chant audit` prints for a skip, in the log and in text reports. */
258
+ export function describeSkip(skip: AuditSkip): string {
259
+ const n = skip.paths.length;
260
+ const shown = skip.paths.slice(0, 10).join(", ") + (n > 10 ? `, and ${n - 10} more` : "");
261
+ return (
262
+ `${skip.lexicon} files were found but not read: the parser ${skip.package} is not installed, ` +
263
+ `so ${n} ${n === 1 ? "input produced" : "inputs produced"} no findings (${shown}). ` +
264
+ `Install it with: ${skip.install}`
265
+ );
266
+ }
267
+
228
268
  /**
229
269
  * Mutable out-param for the inline (`# chant-ignore*`) suppression count
230
270
  * (chant #2111): `auditFiles`'s return type stays `AuditFinding[]` for every
@@ -237,6 +277,16 @@ export interface SuppressionStats {
237
277
  count: number;
238
278
  }
239
279
 
280
+ /** The directory an audit target reads from: the target itself, or the directory of a single file. */
281
+ function auditRootDir(target: string): string {
282
+ const abs = resolve(target);
283
+ try {
284
+ return statSync(abs).isFile() ? dirname(abs) : abs;
285
+ } catch {
286
+ return abs;
287
+ }
288
+ }
289
+
240
290
  /**
241
291
  * Audit a set of CI files and return all findings. Pure with respect to the
242
292
  * filesystem and network — callers supply file contents.
@@ -247,8 +297,12 @@ export async function auditFiles(
247
297
  checksProvider?: ChecksProvider;
248
298
  entitiesProvider?: EntitiesProvider;
249
299
  suppressionStats?: SuppressionStats;
300
+ /** Filled in place with each lexicon whose parser is not installed (#5083); stays empty on a full read. */
301
+ skips?: AuditSkip[];
250
302
  /** Check ids the project enabled with `lint.rules`; a check marked `auditOptIn` runs only when listed here (#3190). */
251
303
  enabledRules?: ReadonlySet<string>;
304
+ /** The directory the audit walked, absolute; absent for a remote tree. Reaches a check as `ctx.audit.root` (#5109). */
305
+ root?: string;
252
306
  } = {},
253
307
  ): Promise<AuditFinding[]> {
254
308
  const provider = opts.checksProvider ?? defaultChecksProvider;
@@ -267,7 +321,7 @@ export async function auditFiles(
267
321
  const checks = (await provider(lexicon)).filter((c) => !c.auditOptIn || opts.enabledRules?.has(c.id));
268
322
  if (checks.length === 0) continue;
269
323
  const parseEntities = await entitiesProvider(lexicon);
270
- findings.push(...(await auditLexicon(lexicon, files, checks, parseEntities, opts.suppressionStats)));
324
+ findings.push(...(await auditLexicon(lexicon, files, checks, parseEntities, opts.suppressionStats, opts.skips, { ...(opts.root !== undefined ? { root: auditRootDir(opts.root) } : {}) })));
271
325
  }
272
326
 
273
327
  return findings;
@@ -298,9 +352,10 @@ function runChecks(
298
352
  checks: PostSynthCheck[],
299
353
  outputs: Map<string, string | SerializerResult>,
300
354
  entities: Map<string, Declarable> = new Map(),
355
+ audit?: { root?: string },
301
356
  ): CheckRunResult {
302
357
  const buildResult: PostSynthContext["buildResult"] = { outputs, entities, warnings: [], errors: [], sourceFileCount: outputs.size };
303
- const ctx: PostSynthContext = { outputs, entities: buildResult.entities, buildResult };
358
+ const ctx: PostSynthContext = { outputs, entities: buildResult.entities, buildResult, ...(audit ? { audit } : {}) };
304
359
  const diags: PostSynthDiagnostic[] = [];
305
360
  for (const check of checks) {
306
361
  try {
@@ -316,8 +371,8 @@ function runChecks(
316
371
  return applyInlineSuppressions(diags, entities);
317
372
  }
318
373
 
319
- function diagKey(d: { checkId: string; entity?: string; message: string }): string {
320
- return `${d.checkId}\u0000${d.entity ?? ""}\u0000${d.message}`;
374
+ function diagKey(d: { checkId: string; entity?: string; locator?: string; message: string }): string {
375
+ return `${d.checkId}\u0000${d.entity ?? ""}\u0000${d.locator ?? ""}\u0000${d.message}`;
321
376
  }
322
377
 
323
378
  /**
@@ -365,7 +420,10 @@ async function auditLexicon(
365
420
  checks: PostSynthCheck[],
366
421
  parseEntities?: EntitiesParser,
367
422
  suppressionStats?: SuppressionStats,
423
+ skips?: AuditSkip[],
424
+ audit?: { root?: string },
368
425
  ): Promise<AuditFinding[]> {
426
+ const unread = new Map<string, string[]>();
369
427
  const entitiesFor = async (file: AuditInput): Promise<Map<string, Declarable>> => {
370
428
  if (!parseEntities) return new Map();
371
429
  try {
@@ -374,13 +432,20 @@ async function auditLexicon(
374
432
  ...(file.dir !== undefined ? { dir: file.dir } : {}),
375
433
  ...(file.baseDir !== undefined ? { baseDir: file.baseDir } : {}),
376
434
  });
377
- } catch {
435
+ } catch (err) {
436
+ // A missing parser is not unparseable content: the files were never
437
+ // read, so say so instead of letting them read as clean (#5083).
438
+ const pkg = parserPackageOf(err);
439
+ if (pkg !== undefined) unread.set(pkg, [...(unread.get(pkg) ?? []), file.path]);
378
440
  // The audit contract is "runs against any repo" — unparseable content
379
441
  // contributes no entities, never a crash.
380
442
  return new Map();
381
443
  }
382
444
  };
383
445
  const perEntities = new Map(await Promise.all(files.map(async (f) => [f.path, await entitiesFor(f)] as const)));
446
+ for (const [pkg, paths] of unread) {
447
+ skips?.push({ lexicon, reason: "parser-not-installed", package: pkg, install: `npm install -D ${pkg}`, paths: paths.sort() });
448
+ }
384
449
 
385
450
  const perFindings: AuditFinding[] = [];
386
451
  const perKeys = new Set<string>();
@@ -390,25 +455,25 @@ async function auditLexicon(
390
455
  // directive again. Counted the same way, once, here too.
391
456
  const metaFindings: AuditFinding[] = [];
392
457
  for (const file of files) {
393
- const { diagnostics: diags, suppressed, meta } = runChecks(checks, new Map([[file.path, toOutput(file)]]), perEntities.get(file.path));
458
+ const { diagnostics: diags, suppressed, meta } = runChecks(checks, new Map([[file.path, toOutput(file)]]), perEntities.get(file.path), audit);
394
459
  if (suppressionStats) suppressionStats.count += suppressed.length;
395
460
  for (const m of meta) {
396
461
  metaFindings.push({ checkId: m.checkId, severity: m.severity, message: m.message, file: m.file, lexicon, line: m.line });
397
462
  }
398
463
  for (const d of diags) {
399
- perFindings.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: file.path, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing });
464
+ perFindings.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: file.path, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing, ...(d.locator !== undefined ? { locator: d.locator } : {}) });
400
465
  perKeys.add(diagKey(d));
401
466
  }
402
467
  }
403
468
 
404
469
  const allOutputs = new Map<string, string | SerializerResult>(files.map((f) => [f.path, toOutput(f)]));
405
- const { diagnostics: allDiags } = runChecks(checks, allOutputs, mergeEntities([...perEntities.values()]));
470
+ const { diagnostics: allDiags } = runChecks(checks, allOutputs, mergeEntities([...perEntities.values()]), audit);
406
471
  const allKeys = new Set(allDiags.map(diagKey));
407
472
 
408
473
  const out: AuditFinding[] = perFindings.filter((f) => allKeys.has(diagKey(f)));
409
474
  for (const d of allDiags) {
410
475
  if (!perKeys.has(diagKey(d))) {
411
- out.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: CROSS_FILE, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing });
476
+ out.push({ checkId: d.checkId, severity: d.severity, message: d.message, file: CROSS_FILE, lexicon: d.lexicon ?? lexicon, entity: d.entity, missing: d.missing, ...(d.locator !== undefined ? { locator: d.locator } : {}) });
412
477
  }
413
478
  }
414
479
  return [...out, ...metaFindings];
@@ -0,0 +1,31 @@
1
+ import { describe, test, expect } from "vitest";
2
+ import { findingIdentities } from "./identity";
3
+
4
+ const f = (over: Partial<Parameters<typeof findingIdentities>[0][number]> = {}) => ({ checkId: "R1", file: "a.yaml", ...over });
5
+
6
+ describe("findingIdentities (#5106)", () => {
7
+ test("is the same for the same inputs and differs per input", () => {
8
+ const base = findingIdentities([f({ entity: "x", locator: "Deployment/containers[0]" })])[0];
9
+ expect(findingIdentities([f({ entity: "x", locator: "Deployment/containers[0]" })])[0]).toBe(base);
10
+ for (const other of [f({ entity: "y", locator: "Deployment/containers[0]" }), f({ entity: "x", locator: "Deployment/containers[1]" }), f({ entity: "x" }), f({ checkId: "R2", entity: "x", locator: "Deployment/containers[0]" }), f({ file: "b.yaml", entity: "x", locator: "Deployment/containers[0]" })]) {
11
+ expect(findingIdentities([other])[0]).not.toBe(base);
12
+ }
13
+ });
14
+
15
+ test("findings that agree on every input are told apart by their order", () => {
16
+ const [a, b] = findingIdentities([f({ entity: "x" }), f({ entity: "x" })]);
17
+ expect(a).not.toBe(b);
18
+ expect(findingIdentities([f({ entity: "x" }), f({ entity: "x" })])).toEqual([a, b]);
19
+ });
20
+
21
+ test("a finding keeps its identity when findings of other keys come before it", () => {
22
+ const [alone] = findingIdentities([f({ entity: "x" })]);
23
+ const [, after] = findingIdentities([f({ entity: "other" }), f({ entity: "x" })]);
24
+ expect(after).toBe(alone);
25
+ });
26
+
27
+ test("a secret is told apart by its fingerprint, not by line", () => {
28
+ const [a, b] = findingIdentities([f({ fingerprint: "aaaa" }), f({ fingerprint: "bbbb" })]);
29
+ expect(a).not.toBe(b);
30
+ });
31
+ });
@@ -0,0 +1,43 @@
1
+ /**
2
+ * Finding identity (#5106). A report's `findings[].identity` and a SARIF
3
+ * result's `partialFingerprints` name a finding by what it is, so two audit
4
+ * runs over a base and a head can be compared without reading message text.
5
+ *
6
+ * The identity is a hash of the rule id, the file, the entity (the object's
7
+ * name or address), the diagnostic's `locator` (its place inside the object:
8
+ * kind, container index, path in the block), the fingerprint of a flagged
9
+ * secret, and the finding's order among findings that agree on all of those.
10
+ * `message` is not an input, so a name that only appears in the text of a
11
+ * message (a renamed container) does not change it. Renaming the object the
12
+ * entity names does change it.
13
+ *
14
+ * Not a cryptographic digest; it only has to tell findings apart.
15
+ */
16
+
17
+ import type { AuditFinding } from "./core";
18
+ import { fingerprintSecret } from "./secrets";
19
+
20
+ /** The SARIF `partialFingerprints` key the identity is published under. */
21
+ export const IDENTITY_FINGERPRINT_KEY = "chantFindingIdentity/v1";
22
+
23
+ type IdentityInput = Pick<AuditFinding, "checkId" | "file" | "entity" | "locator" | "fingerprint" | "missing">;
24
+
25
+ function baseKey(f: IdentityInput): string {
26
+ return [f.checkId, f.file, f.entity ?? "", f.missing ? `${f.missing.kind}@${f.missing.scope}` : "", f.locator ?? "", f.fingerprint ?? ""].join("\u0000");
27
+ }
28
+
29
+ /**
30
+ * One identity per finding, in the order given. Findings that agree on every
31
+ * input are told apart by their position among themselves, so the order the
32
+ * audit emitted them in must be the order passed here.
33
+ */
34
+ export function findingIdentities(findings: readonly IdentityInput[]): string[] {
35
+ const seen = new Map<string, number>();
36
+ return findings.map((f) => {
37
+ const key = baseKey(f);
38
+ const n = seen.get(key) ?? 0;
39
+ seen.set(key, n + 1);
40
+ // Two 64-bit halves over differently salted inputs: 32 hex characters.
41
+ return fingerprintSecret(`${key}\u0000${n}`) + fingerprintSecret(`${n}\u0000${key}`);
42
+ });
43
+ }
@@ -8,7 +8,7 @@
8
8
  * via `template`, plus theme knobs (title, logo, accent, footer).
9
9
  */
10
10
 
11
- import type { AuditFinding } from "./core";
11
+ import type { AuditFinding, AuditSkip } from "./core";
12
12
  import { ruleDocUrl, type RuleMeta, lineageLabel } from "./catalog";
13
13
  import { buildReportModel, buildReportJson, type AuditSnapshot, type BuildModelOptions, type EnrichedFinding, type GuidanceCluster, type QuickWinFile, type ReportCounts } from "./report-model";
14
14
 
@@ -33,6 +33,8 @@ export interface RenderHtmlOptions extends BuildModelOptions {
33
33
  notes?: string[];
34
34
  /** A truncated local walk (#2528), carried into the embedded JSON report. */
35
35
  truncated?: { limit: number; flag: string };
36
+ /** Lexicons skipped for want of a parser (#5083), carried into the embedded JSON report. */
37
+ skipped?: AuditSkip[];
36
38
  }
37
39
 
38
40
  const DEFAULT_ACCENT = "#7c3aed";
@@ -196,7 +198,7 @@ export function renderHtml(findings: AuditFinding[], opts: RenderHtmlOptions = {
196
198
 
197
199
  // Machine-readable data embedded so the HTML report is also parseable.
198
200
  // `<` escaped so the JSON can't break out of the <script> element.
199
- const dataJson = JSON.stringify(buildReportJson(findings, { snapshot: opts.snapshot, truncated: opts.truncated }), null, 0).replace(/</g, "\\u003c");
201
+ const dataJson = JSON.stringify(buildReportJson(findings, { snapshot: opts.snapshot, truncated: opts.truncated, skipped: opts.skipped }), null, 0).replace(/</g, "\\u003c");
200
202
  const dataScript = `<script type="application/json" id="chant-audit-report">${dataJson}</script>`;
201
203
 
202
204
  let body: string;
@@ -8,6 +8,8 @@
8
8
  import type { AuditFinding } from "./core";
9
9
  import type { UnclaimedFile } from "./discover";
10
10
  import { RULE_CATALOG, ruleDocUrl, type Authority, type Category, type FixKind, type Lineage, type RuleMeta, type Tier } from "./catalog";
11
+ import type { AuditSkip } from "./core";
12
+ import { findingIdentities } from "./identity";
11
13
  import { proveFix, unifiedDiff, type ProveOptions } from "./proof";
12
14
  import type { Severity } from "../lint/rule";
13
15
 
@@ -30,6 +32,8 @@ const SUPERSEDED_BY: Record<string, string[]> = {
30
32
 
31
33
  export interface EnrichedFinding extends AuditFinding {
32
34
  meta: RuleMeta;
35
+ /** Stable across runs while the defect is the same; see `identity.ts` (#5106). */
36
+ identity: string;
33
37
  }
34
38
 
35
39
  /** A per-file quick-win: a combined patch plus any findings still needing input. */
@@ -98,6 +102,12 @@ export interface SerializedFinding {
98
102
  line?: number;
99
103
  /** Redaction-safe fingerprint of a flagged value, when applicable (see `secrets.ts`). */
100
104
  fingerprint?: string;
105
+ /**
106
+ * Names the finding across runs (#5106): the same value while the rule, file,
107
+ * object and place in the object stay the same, whatever the message says
108
+ * and wherever the finding sits among others. See `identity.ts`.
109
+ */
110
+ identity: string;
101
111
  /** Set when the finding is an absence rather than a defect — see `PostSynthDiagnostic.missing` (chant #2113). */
102
112
  missing?: { kind: string; scope: string };
103
113
  lexicon: string;
@@ -135,6 +145,12 @@ export interface AuditReportJson {
135
145
  * scan and for a repository URL.
136
146
  */
137
147
  truncated?: { limit: number; flag: string };
148
+ /**
149
+ * Lexicons whose files were found but not read, because an optional parser
150
+ * is not installed (#5083). A lexicon listed here has no findings because it
151
+ * was skipped, not because it is clean. Absent when every lexicon was read.
152
+ */
153
+ skipped?: AuditSkip[];
138
154
  }
139
155
 
140
156
  export function metaFor(id: string, catalog: Record<string, RuleMeta> = RULE_CATALOG): RuleMeta {
@@ -252,7 +268,8 @@ export interface BuildModelOptions {
252
268
  /** Build the structured report model from raw findings. */
253
269
  export function buildReportModel(findings: AuditFinding[], opts: BuildModelOptions = {}): ReportModel {
254
270
  const catalog = opts.catalog ?? RULE_CATALOG;
255
- const enriched: EnrichedFinding[] = findings.map((f) => ({ ...f, meta: metaFor(f.checkId, catalog) }));
271
+ const identities = findingIdentities(findings);
272
+ const enriched: EnrichedFinding[] = findings.map((f, i) => ({ ...f, identity: identities[i], meta: metaFor(f.checkId, catalog) }));
256
273
  const contents = new Map((opts.files ?? []).map((f) => [f.path, f.content]));
257
274
 
258
275
  const mergeWorthy = enriched.filter((f) => f.meta.tier === "merge-worthy");
@@ -310,6 +327,7 @@ export function buildReportJson(
310
327
  catalog?: Record<string, RuleMeta>;
311
328
  unclaimed?: UnclaimedFile[];
312
329
  truncated?: { limit: number; flag: string };
330
+ skipped?: AuditSkip[];
313
331
  } = {},
314
332
  ): AuditReportJson {
315
333
  const model = buildReportModel(findings, { catalog: opts.catalog });
@@ -328,6 +346,7 @@ export function buildReportJson(
328
346
  entity: f.entity,
329
347
  line: f.line,
330
348
  fingerprint: f.fingerprint,
349
+ identity: f.identity,
331
350
  missing: f.missing,
332
351
  lexicon: f.lexicon,
333
352
  tier: f.meta.tier,
@@ -341,5 +360,6 @@ export function buildReportJson(
341
360
  })),
342
361
  unclaimed: opts.unclaimed && opts.unclaimed.length > 0 ? opts.unclaimed : undefined,
343
362
  truncated: opts.truncated,
363
+ skipped: opts.skipped && opts.skipped.length > 0 ? opts.skipped : undefined,
344
364
  };
345
365
  }
@@ -34,6 +34,7 @@ import {
34
34
  type AgentSettings,
35
35
  type LandInput,
36
36
  } from "./ci-agent";
37
+ import { TeamReadError } from "./ci-comment-allow";
37
38
  import { assertProductWords } from "./ci-product-words";
38
39
  import { PLYWOOD } from "./__fixtures__/product-words";
39
40
  import type { OpRunRecord, OpRunRecordInput } from "./op/runtime";
@@ -190,6 +191,37 @@ describe("agent prepare", () => {
190
191
  expect((await prepare({ body: "/plywood agent" })).decision.reason).toMatch(/needs an ask/);
191
192
  });
192
193
 
194
+ test("a list for the agent command (INTENTIUS/terragucci#1461) lets a listed login and a team member ask, and refuses another writer", async () => {
195
+ const asked = (settings: AgentSettings, user: string, teams?: { teamMember?: (t: string, l: string) => Promise<boolean> }) =>
196
+ prepareAgentRun({ settings, words, dir: dir(), env: {}, event: event("/plywood agent add a tag", user), forge: { pullRequestHead: async () => head(), userCanWrite: async () => true }, ...(teams ? { teams } : {}), readRuns: async () => [], git: fakeGit(), now: NOW });
197
+ const login = commentSettings({ commentAllow: { agent: ["ana"] } });
198
+ expect(await asked(login, "ana")).toMatchObject({ go: true });
199
+ const other = await asked(login, "ben");
200
+ expect(other).toMatchObject({ go: false, stop: "refused", pr: 7 });
201
+ expect(other.reason).toMatch(/ben may not run `agent` here: it is limited to `ana`/);
202
+ const team = commentSettings({ commentAllow: { default: ["team:acme/ai"] } });
203
+ expect(await asked(team, "ben", { teamMember: async (t, l) => t === "acme/ai" && l === "ben" })).toMatchObject({ go: true });
204
+ expect(await asked(team, "cy", { teamMember: async () => false })).toMatchObject({ go: false });
205
+ // A team no read can answer for, and one the token cannot read, run nothing.
206
+ expect((await asked(team, "ben")).reason).toMatch(/so nothing runs/);
207
+ const unreadable = await asked(team, "ben", { teamMember: async () => { throw new TeamReadError("GitHub team acme/ai answered 403"); } });
208
+ expect(unreadable).toMatchObject({ go: false, stop: "refused" });
209
+ expect(unreadable.reason).toMatch(/answered 403/);
210
+ // No list: write access alone, as before.
211
+ expect(await asked(commentSettings(), "ben")).toMatchObject({ go: true });
212
+ });
213
+
214
+ test("the list round-trips through the job's variables, and a broken one is refused", () => {
215
+ const s = commentSettings({ commentAllow: { agent: ["team:acme/ai", "ana"] }, commentAllowTokenEnv: "TG_TEAM_TOKEN" });
216
+ const env = agentSettingsEnv(s);
217
+ expect(JSON.parse(env.CHANT_COMMENT_ALLOW!)).toEqual({ agent: ["team:acme/ai", "ana"] });
218
+ expect(agentSettingsFromEnv(env, "plywood").commentAllow).toEqual({ agent: ["team:acme/ai", "ana"] });
219
+ expect(agentSettingsEnv(commentSettings())).not.toHaveProperty("CHANT_COMMENT_ALLOW");
220
+ expect(() => agentSettingsFromEnv({ ...env, CHANT_COMMENT_ALLOW: "{" }, "plywood")).toThrow(/CHANT_COMMENT_ALLOW is JSON/);
221
+ expect(() => resolveAgentSpec("x", { on: "comment", comment: "/plywood agent", commentAllow: { agent: [] } }, "plywood")).toThrow(/at least one entry/);
222
+ expect(() => resolveAgentSpec("x", { on: "comment", comment: "/plywood agent", commentAllowTokenEnv: "a b" }, "plywood")).toThrow(/commentAllowTokenEnv/);
223
+ });
224
+
193
225
  test("stops a run once the recorded costs reach the money limit, and refuses when the ledger cannot be read", async () => {
194
226
  const base = { words, env: {}, event: event("/plywood agent add a tag"), forge: { pullRequestHead: async () => head(), userCanWrite: async () => true }, git: fakeGit(), now: NOW };
195
227
  const settings = commentSettings({ maxRuns: undefined, maxCostUsd: 3 });
package/src/ci-agent.ts CHANGED
@@ -38,6 +38,7 @@ import { spawn } from "node:child_process";
38
38
  import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
39
39
  import { join } from "node:path";
40
40
  import { CHANT_EXIT } from "./exit-codes";
41
+ import { COMMENT_ALLOW_ENV, commentAllowFromEnv, commentAllowProblems, decideCommentAllow, type CommentAllow, type CommentAllowReads } from "./ci-comment-allow";
41
42
  import { parseProductComment, type CiProductWords } from "./ci-product-words";
42
43
  import { quoted } from "./op/activities/review-agent";
43
44
  import type { OpRunRecord, OpRunRecordInput } from "./op/runtime";
@@ -96,6 +97,16 @@ export interface OpAgentSpec {
96
97
  branch?: string;
97
98
  /** The ledger environment the runs are recorded under. Default `local`, the rule every Op follows (#4551 ruling A). */
98
99
  env?: string;
100
+ /**
101
+ * Who may ask, beyond write access, for `on: "comment"` (INTENTIUS/terragucci#1461,
102
+ * `./ci-comment-allow.ts`): the map's `agent` list, else its `default`. The
103
+ * generated job carries it as `CHANT_COMMENT_ALLOW`, so it is read from the
104
+ * workflow on the default branch. GitHub and Forgejo only; a team on
105
+ * another forge fails closed.
106
+ */
107
+ commentAllow?: CommentAllow;
108
+ /** The secret that holds the token team membership is read with, for `commentAllow`. Default: the job's token. */
109
+ commentAllowTokenEnv?: string;
99
110
  }
100
111
 
101
112
  /** An agent's settings, every default filled and checked. */
@@ -112,6 +123,10 @@ export interface AgentSettings {
112
123
  guarded: string[];
113
124
  branch?: string;
114
125
  env: string;
126
+ /** See {@link OpAgentSpec.commentAllow}. */
127
+ commentAllow?: CommentAllow;
128
+ /** See {@link OpAgentSpec.commentAllowTokenEnv}. */
129
+ commentAllowTokenEnv?: string;
115
130
  }
116
131
 
117
132
  /** The Claude Code release the default agent command runs (terragucci's pin, as the review agent's). */
@@ -239,6 +254,11 @@ export function resolveAgentSpec(name: string, spec: OpAgentSpec, product = "cha
239
254
  }
240
255
  const env = spec.env ?? "local";
241
256
  if (!NAME.test(env)) throw new AgentError(`${where}: env is a ledger environment name`);
257
+ if (spec.commentAllow !== undefined) {
258
+ const problems = commentAllowProblems(spec.commentAllow, `${where}: commentAllow`);
259
+ if (problems.length > 0) throw new AgentError(problems.join("; "));
260
+ }
261
+ if (spec.commentAllowTokenEnv !== undefined && !VAR.test(spec.commentAllowTokenEnv)) throw new AgentError(`${where}: commentAllowTokenEnv is a variable name`);
242
262
  return {
243
263
  name,
244
264
  on: spec.on,
@@ -252,6 +272,8 @@ export function resolveAgentSpec(name: string, spec: OpAgentSpec, product = "cha
252
272
  guarded: [...guarded],
253
273
  ...(branch !== undefined ? { branch } : {}),
254
274
  env,
275
+ ...(spec.commentAllow !== undefined ? { commentAllow: spec.commentAllow } : {}),
276
+ ...(spec.commentAllowTokenEnv !== undefined ? { commentAllowTokenEnv: spec.commentAllowTokenEnv } : {}),
255
277
  };
256
278
  }
257
279
 
@@ -270,6 +292,7 @@ export function agentSettingsEnv(s: AgentSettings): Record<string, string> {
270
292
  ...(s.guarded.length > 0 ? { [AGENT_ENV.guarded]: JSON.stringify(s.guarded) } : {}),
271
293
  ...(s.branch ? { [AGENT_ENV.branch]: s.branch } : {}),
272
294
  [AGENT_ENV.env]: s.env,
295
+ ...(s.commentAllow ? { [COMMENT_ALLOW_ENV]: JSON.stringify(s.commentAllow) } : {}),
273
296
  };
274
297
  }
275
298
 
@@ -313,6 +336,13 @@ export function agentSettingsFromEnv(env: Record<string, string | undefined>, pr
313
336
  ...(env[AGENT_ENV.branch] ? { branch: env[AGENT_ENV.branch] } : {}),
314
337
  ...(env[AGENT_ENV.env] ? { env: env[AGENT_ENV.env] } : {}),
315
338
  };
339
+ let commentAllow: CommentAllow | undefined;
340
+ try {
341
+ commentAllow = commentAllowFromEnv(env[COMMENT_ALLOW_ENV]);
342
+ } catch (e) {
343
+ throw new AgentError((e as Error).message);
344
+ }
345
+ if (commentAllow) spec.commentAllow = commentAllow;
316
346
  return resolveAgentSpec(name, spec, product);
317
347
  }
318
348
 
@@ -617,6 +647,8 @@ export interface PrepareInput {
617
647
  event?: unknown;
618
648
  /** A read client: who may write, and the pull request's head. */
619
649
  forge?: Pick<PrForge, "pullRequestHead" | "userCanWrite">;
650
+ /** With `settings.commentAllow` (INTENTIUS/terragucci#1461): the reads of a token that can read teams. Absent: a list that names a team fails closed. */
651
+ teams?: CommentAllowReads;
620
652
  /** The agent's earlier run records on the ledger. */
621
653
  readRuns: () => Promise<OpRunRecord[]>;
622
654
  git: AgentGit;
@@ -644,6 +676,16 @@ export async function prepareAgentRun(i: PrepareInput): Promise<AgentDecision> {
644
676
  ask = got;
645
677
  // GitHub's job condition already asks for a writer; Forgejo's runner has no author association, so the forge is asked.
646
678
  if (i.forge?.userCanWrite && !(await i.forge.userCanWrite(ask.user))) return no(`${ask.user} cannot write to the repository, so the agent does not run for them`, { pr: ask.pr });
679
+ // INTENTIUS/terragucci#1461: the pipeline's list, from the workflow on the default branch.
680
+ if (i.settings.commentAllow) {
681
+ let decision;
682
+ try {
683
+ decision = await decideCommentAllow(i.settings.commentAllow, "agent", ask.user, i.teams);
684
+ } catch (e) {
685
+ return no(`could not check who may ask the agent (${errText(e)}), so it does not run`, { pr: ask.pr });
686
+ }
687
+ if (!decision.ok) return no(decision.reason, { pr: ask.pr });
688
+ }
647
689
  }
648
690
 
649
691
  let records: OpRunRecord[] = [];