@cosmicdrift/kumiko-guards 0.413.0 → 0.414.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 (52) hide show
  1. package/README.md +15 -9
  2. package/package.json +4 -4
  3. package/src/_lib/agent-docs-api-nodes.ts +9 -2
  4. package/src/_lib/agent-docs-api-render.ts +31 -10
  5. package/src/_lib/agent-docs-api.ts +13 -9
  6. package/src/_lib/agent-docs-feature-imports.ts +12 -1
  7. package/src/_lib/baseline-compare.ts +1 -2
  8. package/src/_lib/doc-status.ts +8 -4
  9. package/src/_lib/dockerfile.ts +28 -5
  10. package/src/_lib/escaped-literal.ts +26 -0
  11. package/src/_lib/npm-registry.ts +2 -2
  12. package/src/_lib/run-slots.ts +4 -6
  13. package/src/_lib/security-audit.ts +22 -6
  14. package/src/_lib/test-es-raw-writes.ts +5 -3
  15. package/src/changes.json +44 -0
  16. package/src/check-security.ts +4 -3
  17. package/src/guard-app-dockerfile.ts +29 -12
  18. package/src/guard-ignore-tag-reason.ts +18 -4
  19. package/src/guard-internal-subpath-imports.ts +35 -25
  20. package/src/guard-rls-session-settings.ts +48 -6
  21. package/src/guard-schema-cli-features.ts +22 -1
  22. package/src/guard-test-es-row-writes.ts +2 -1
  23. package/src/guard-unsafe-array-param.ts +4 -7
  24. package/src/pre-push.sh +46 -6
  25. package/src/run-guards.ts +0 -28
  26. package/src/run-repo-checks.ts +0 -6
  27. package/src/run-steps-parallel.ts +4 -4
  28. package/src/run-ui-guards.ts +1 -15
  29. package/src/_lib/german-test-title.ts +0 -94
  30. package/src/_lib/primitives-access.ts +0 -23
  31. package/src/check-predicates.ts +0 -244
  32. package/src/guard-admin-api.ts +0 -138
  33. package/src/guard-direct-fetch.ts +0 -161
  34. package/src/guard-error-reasons.ts +0 -210
  35. package/src/guard-event-store-writes.ts +0 -124
  36. package/src/guard-i18n-locale-terminology.ts +0 -134
  37. package/src/guard-no-custom-primitives.ts +0 -193
  38. package/src/guard-no-date-api.ts +0 -183
  39. package/src/guard-no-direct-fs.ts +0 -346
  40. package/src/guard-no-direct-process-env.ts +0 -127
  41. package/src/guard-no-inline-styles.ts +0 -64
  42. package/src/guard-no-raw-hooks.ts +0 -80
  43. package/src/guard-no-temporal-polyfill-import.ts +0 -131
  44. package/src/guard-primitives-discipline.ts +0 -357
  45. package/src/guard-raw-classname.ts +0 -117
  46. package/src/guard-raw-interactive-elements.ts +0 -164
  47. package/src/guard-restricted-symbols.ts +0 -155
  48. package/src/guard-silent-skip.ts +0 -186
  49. package/src/guard-test-es-fixtures.ts +0 -85
  50. package/src/guard-test-title.ts +0 -159
  51. package/src/guard-thin-wrappers.ts +0 -471
  52. package/src/guard-unsafe-json-parse.ts +0 -87
@@ -1,471 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Thin-Wrapper Guard (warning, never fails).
4
- *
5
- * Finds functions that only call another function (1 statement, direct
6
- * delegation) and are not marked as a deliberate wrapper.
7
- *
8
- * Such wrappers often appear as compatibility shims after refactorings —
9
- * this guard keeps the list visible so they can be deliberately removed.
10
- *
11
- * === Setting a marker ===
12
- *
13
- * When a wrapper is deliberate and permanent, right above the function:
14
- *
15
- * // @wrapper-known semantic-alias
16
- * export function signDeletionToken(dek: Buffer): string {
17
- * return signToken(dek);
18
- * }
19
- *
20
- * Known reasons:
21
- * semantic-alias — deliberate rename for domain clarity
22
- * error-helper — named error constructor (delegates to writeFailure or similar)
23
- * uuid-domain — domain-specific UUID generator
24
- * test-helper — test-utility alias
25
- * monitoring — monitoring/metrics alias
26
- * health-check — health-check wrapper
27
- * entry-point — entry-point-specific configuration
28
- */
29
-
30
- import * as path from "node:path";
31
- import {
32
- type ArrowFunction,
33
- type FunctionDeclaration,
34
- type FunctionExpression,
35
- type Node,
36
- Project,
37
- type SourceFile,
38
- SyntaxKind,
39
- } from "ts-morph";
40
- import { type RepoCheck, reportResults, runRepoChecks } from "./_lib/guard-kit";
41
- import { frameworkTsConfigPath } from "./_lib/roots";
42
- import { keepsRootKind, type ScanSpec, scanFiles } from "./_lib/scan-scope";
43
-
44
- const ROOT = process.cwd();
45
-
46
- const EXCLUDE =
47
- /(__tests__|\.test\.(ts|tsx)$|\.integration\.(ts|tsx)$|\.d\.(ts|tsx)$|\.spec\.(ts|tsx)$|node_modules)/;
48
-
49
- // ── Known reasons ─────────────────────────────────────────────────────────
50
-
51
- export const KNOWN_WRAPPER_REASONS = [
52
- "semantic-alias", // deliberate rename for domain clarity
53
- "error-helper", // named error constructor
54
- "uuid-domain", // domain-specific UUID generator
55
- "test-helper", // test-utility alias
56
- "monitoring", // monitoring/metrics alias
57
- "health-check", // health-check wrapper
58
- "entry-point", // entry-point-specific configuration
59
- ] as const;
60
-
61
- export type WrapperReason = (typeof KNOWN_WRAPPER_REASONS)[number];
62
-
63
- function isKnownReason(r: string): r is WrapperReason {
64
- return KNOWN_WRAPPER_REASONS.some((known) => known === r);
65
- }
66
-
67
- // ── Built-in filter ─────────────────────────────────────────────────────
68
-
69
- const BUILTIN_NAMES = new Set([
70
- "test",
71
- "exec",
72
- "push",
73
- "pop",
74
- "shift",
75
- "unshift",
76
- "map",
77
- "filter",
78
- "reduce",
79
- "reduceRight",
80
- "forEach",
81
- "find",
82
- "findIndex",
83
- "findLast",
84
- "findLastIndex",
85
- "some",
86
- "every",
87
- "includes",
88
- "indexOf",
89
- "lastIndexOf",
90
- "slice",
91
- "splice",
92
- "concat",
93
- "flat",
94
- "flatMap",
95
- "join",
96
- "sort",
97
- "reverse",
98
- "fill",
99
- "copyWithin",
100
- "at",
101
- "entries",
102
- "keys",
103
- "values",
104
- "from",
105
- "isArray",
106
- "of",
107
- "assign",
108
- "create",
109
- "fromEntries",
110
- "defineProperty",
111
- "getOwnPropertyNames",
112
- "getOwnPropertyDescriptor",
113
- "hasOwn",
114
- "freeze",
115
- "seal",
116
- "replace",
117
- "replaceAll",
118
- "split",
119
- "trim",
120
- "trimStart",
121
- "trimEnd",
122
- "trimLeft",
123
- "trimRight",
124
- "startsWith",
125
- "endsWith",
126
- "substring",
127
- "padStart",
128
- "padEnd",
129
- "repeat",
130
- "match",
131
- "matchAll",
132
- "search",
133
- "charAt",
134
- "charCodeAt",
135
- "toUpperCase",
136
- "toLowerCase",
137
- "normalize",
138
- "toString",
139
- "valueOf",
140
- "stringify",
141
- "parse",
142
- "log",
143
- "error",
144
- "warn",
145
- "info",
146
- "debug",
147
- "trace",
148
- "table",
149
- "group",
150
- "groupEnd",
151
- "time",
152
- "timeEnd",
153
- "min",
154
- "max",
155
- "floor",
156
- "ceil",
157
- "round",
158
- "abs",
159
- "sqrt",
160
- "pow",
161
- "random",
162
- "sign",
163
- "trunc",
164
- "then",
165
- "catch",
166
- "finally",
167
- "resolve",
168
- "reject",
169
- "all",
170
- "allSettled",
171
- "race",
172
- "any",
173
- "get",
174
- "set",
175
- "has",
176
- "delete",
177
- "clear",
178
- "call",
179
- "apply",
180
- "bind",
181
- "setTimeout",
182
- "clearTimeout",
183
- "setInterval",
184
- "clearInterval",
185
- "String",
186
- "Number",
187
- "Boolean",
188
- "Symbol",
189
- "BigInt",
190
- "Array",
191
- "Object",
192
- "Promise",
193
- "Map",
194
- "Set",
195
- "send",
196
- "emit",
197
- "on",
198
- "off",
199
- "once",
200
- "next",
201
- "done",
202
- "throw",
203
- "return",
204
- ]);
205
-
206
- // ── Types ─────────────────────────────────────────────────────────────────
207
-
208
- type FnNode = FunctionDeclaration | ArrowFunction | FunctionExpression;
209
-
210
- export interface Finding {
211
- file: string;
212
- line: number;
213
- fnName: string;
214
- callee: string;
215
- markerReason: string | null; // null = no marker, string = reason (unknown reasons included)
216
- }
217
-
218
- // ── AST helpers ───────────────────────────────────────────────────────────
219
-
220
- function getFnName(node: FnNode): string | undefined {
221
- if (node.isKind(SyntaxKind.FunctionDeclaration)) return node.getName() ?? undefined;
222
- const parent = node.getParent();
223
- if (parent?.isKind(SyntaxKind.VariableDeclaration)) {
224
- return parent.getName();
225
- }
226
- if (parent?.isKind(SyntaxKind.PropertyAssignment)) {
227
- return parent.getFirstChild()?.getText();
228
- }
229
- // ponytail: MethodDeclaration dropped — getFirstChild() returns the modifier keyword, not the name.
230
- return undefined;
231
- }
232
-
233
- function collectCalleeNames(node: FnNode): Set<string> {
234
- const callees = new Set<string>();
235
- node.forEachDescendant((n) => {
236
- if (n.isKind(SyntaxKind.CallExpression)) {
237
- const name = extractCalleeName(n);
238
- if (name) callees.add(name);
239
- }
240
- });
241
- return callees;
242
- }
243
-
244
- function wrapperCalleeName(callExpr: Node): string | null {
245
- const name = extractCalleeName(callExpr);
246
- if (!name) return null;
247
- if (BUILTIN_NAMES.has(name)) return null;
248
- return name;
249
- }
250
-
251
- // The single call expression a one-statement body consists of, if it has that shape.
252
- function singleStatementCall(single: Node): Node | null {
253
- if (single.isKind(SyntaxKind.ReturnStatement)) {
254
- const expr = single.getExpression();
255
- // `return () => ...` is a factory, not a delegation
256
- return expr?.isKind(SyntaxKind.CallExpression) ? expr : null;
257
- }
258
- if (single.isKind(SyntaxKind.ExpressionStatement)) {
259
- const expr = single.getExpression();
260
- return expr.isKind(SyntaxKind.CallExpression) ? expr : null;
261
- }
262
- return null;
263
- }
264
-
265
- function getSingleDirectCallee(node: FnNode): string | null {
266
- const rawBody =
267
- node.isKind(SyntaxKind.ArrowFunction) && !node.getBody().isKind(SyntaxKind.Block)
268
- ? null
269
- : node.getBody();
270
-
271
- // Concise arrow: `x => someCall(x)` — body IS the expression
272
- if (!rawBody?.isKind(SyntaxKind.Block)) {
273
- const body = node.getBody();
274
- if (!body?.isKind(SyntaxKind.CallExpression)) return null;
275
- // Method chains (A.from(x).toMethod(y)) have 2 call expressions — not a thin wrapper
276
- if (collectCalleeNames(node).size !== 1) return null;
277
- return wrapperCalleeName(body);
278
- }
279
-
280
- const stmts = rawBody.getStatements();
281
- if (stmts.length !== 1) return null;
282
-
283
- const callExpr = singleStatementCall(stmts.reduce((only) => only));
284
- if (!callExpr) return null;
285
-
286
- // Ensure the call isn't part of a larger nested-call tree: a direct call
287
- // has exactly 1 unique callee name across the whole body.
288
- if (collectCalleeNames(node).size !== 1) return null;
289
-
290
- return wrapperCalleeName(callExpr);
291
- }
292
-
293
- function extractCalleeName(callNode: ReturnType<FnNode["getBody"]> | undefined): string | null {
294
- if (!callNode) return null;
295
- const expr = callNode.isKind(SyntaxKind.CallExpression) ? callNode.getExpression() : null;
296
- if (!expr) return null;
297
- if (expr.isKind(SyntaxKind.Identifier)) return expr.getText();
298
- if (expr.isKind(SyntaxKind.PropertyAccessExpression)) {
299
- return expr.getName();
300
- }
301
- return null;
302
- }
303
-
304
- // ── Marker detection ──────────────────────────────────────────────────────
305
-
306
- const MARKER_RE = /\/[/*]\s*@wrapper-known(?:\s+([\w-]+))?/;
307
-
308
- function extractMarkerReason(node: FnNode): string | null {
309
- const fullText = node.getSourceFile().getFullText();
310
-
311
- // Anchor node for leading comments:
312
- // VariableStatement → const foo = () => ...
313
- // PropertyAssignment → { foo: () => ... } (marker above the property)
314
- // FunctionDeclaration → function foo() { ... }
315
- const parentNode = node.getParent();
316
- const anchor =
317
- node.getFirstAncestorByKind(SyntaxKind.VariableStatement) ??
318
- (parentNode?.isKind(SyntaxKind.PropertyAssignment) ? parentNode : null) ??
319
- (node.isKind(SyntaxKind.FunctionDeclaration) ? node : null);
320
-
321
- if (anchor) {
322
- for (const r of anchor.getLeadingCommentRanges()) {
323
- const m = MARKER_RE.exec(r.getText());
324
- if (m) return m[1] ?? "";
325
- }
326
- }
327
-
328
- // Trailing comment on the same line
329
- const end = node.getEnd();
330
- const eol = fullText.indexOf("\n", end);
331
- const trailing = fullText.slice(end, eol === -1 ? fullText.length : eol);
332
- const m = MARKER_RE.exec(trailing);
333
- if (m) return m[1] ?? "";
334
-
335
- return null;
336
- }
337
-
338
- // A typed lookup table (`const T: Record<K, Fn> = {…}` or `{…} satisfies …`) fixes one
339
- // signature per slot; a one-call entry adapts that signature, so inlining it would mean
340
- // dropping the table, not the wrapper.
341
- function isTypedTableLiteral(literal: Node): boolean {
342
- let parent = literal.getParent();
343
- while (parent?.isKind(SyntaxKind.AsExpression)) parent = parent.getParent();
344
- if (parent?.isKind(SyntaxKind.SatisfiesExpression)) return true;
345
- return parent?.isKind(SyntaxKind.VariableDeclaration) === true && !!parent.getTypeNode();
346
- }
347
-
348
- function collectTypedTableValueNames(sf: SourceFile): Set<string> {
349
- const names = new Set<string>();
350
- for (const literal of sf.getDescendantsOfKind(SyntaxKind.ObjectLiteralExpression)) {
351
- if (!isTypedTableLiteral(literal)) continue;
352
- for (const property of literal.getProperties()) {
353
- if (property.isKind(SyntaxKind.ShorthandPropertyAssignment)) names.add(property.getName());
354
- if (!property.isKind(SyntaxKind.PropertyAssignment)) continue;
355
- const value = property.getInitializer();
356
- if (value?.isKind(SyntaxKind.Identifier)) names.add(value.getText());
357
- }
358
- }
359
- return names;
360
- }
361
-
362
- function isInlineTypedTableValue(node: FnNode): boolean {
363
- const property = node.getParent();
364
- const literal = property?.isKind(SyntaxKind.PropertyAssignment)
365
- ? property.getParent()
366
- : undefined;
367
- return literal !== undefined && isTypedTableLiteral(literal);
368
- }
369
-
370
- // ── Scan ──────────────────────────────────────────────────────────────────
371
-
372
- export function collectFindings(sf: SourceFile): Finding[] {
373
- const file = path.relative(ROOT, sf.getFilePath());
374
- const findings: Finding[] = [];
375
- const typedTableValueNames = collectTypedTableValueNames(sf);
376
-
377
- const check = (node: FnNode) => {
378
- const fnName = getFnName(node);
379
- // skip: anonymous functions cannot be reported by name
380
- if (!fnName) return;
381
- // skip: a typed table slot, see isTypedTableLiteral
382
- if (typedTableValueNames.has(fnName) || isInlineTypedTableValue(node)) return;
383
-
384
- const callee = getSingleDirectCallee(node);
385
- // skip: not a single-callee wrapper
386
- if (!callee) return;
387
- // skip: self-recursion / same-name delegation is a false positive
388
- if (callee === fnName) return;
389
-
390
- const markerReason = extractMarkerReason(node);
391
- findings.push({
392
- file,
393
- line: node.getStartLineNumber(),
394
- fnName,
395
- callee,
396
- markerReason,
397
- });
398
- };
399
-
400
- sf.getFunctions().forEach(check);
401
- sf.getDescendantsOfKind(SyntaxKind.ArrowFunction).forEach(check);
402
- sf.getDescendantsOfKind(SyntaxKind.FunctionExpression).forEach(check);
403
-
404
- return findings;
405
- }
406
-
407
- // ── RepoCheck ─────────────────────────────────────────────────────────────
408
-
409
- const SCAN: ScanSpec = {
410
- scope: "source",
411
- extensions: ["ts"],
412
- frameworkWithin: ["packages/*/src/**"],
413
- };
414
-
415
- const WRAPPER_FIX =
416
- "call the delegate directly, or mark a deliberate wrapper with // @wrapper-known <reason>";
417
-
418
- export const check: RepoCheck = {
419
- name: "Thin-Wrappers Guard",
420
- run(roots) {
421
- // The kind filter (scan-scope.ts keepsRootKind) excludes "tooling" roots by
422
- // default — that's a deliberate scope choice, not a vacuous scan, so it must
423
- // report notApplicable instead of matchedFiles: 0.
424
- if (!roots.some((root) => keepsRootKind(SCAN, root))) {
425
- return { violations: [], matchedFiles: 0, notApplicable: true };
426
- }
427
-
428
- const project = new Project({
429
- tsConfigFilePath: frameworkTsConfigPath(),
430
- skipAddingFilesFromTsConfig: true,
431
- skipFileDependencyResolution: true,
432
- });
433
-
434
- const paths = scanFiles(SCAN, roots);
435
- for (const p of paths) project.addSourceFileAtPath(p);
436
-
437
- let scanned = 0;
438
- const warnings: { file: string; line: number; message: string }[] = [];
439
- for (const sf of project.getSourceFiles()) {
440
- if (EXCLUDE.test(sf.getFilePath())) continue;
441
- scanned++;
442
- for (const f of collectFindings(sf)) {
443
- if (f.markerReason === null) {
444
- warnings.push({
445
- file: f.file,
446
- line: f.line,
447
- message: `${f.fnName} → ${f.callee} (${WRAPPER_FIX})`,
448
- });
449
- } else if (!isKnownReason(f.markerReason)) {
450
- warnings.push({
451
- file: f.file,
452
- line: f.line,
453
- message: `${f.fnName} → ${f.callee} (reason="${f.markerReason}"; use a known reason from the list in this guard)`,
454
- });
455
- }
456
- }
457
- }
458
-
459
- return {
460
- violations: [],
461
- warnings: warnings.length > 0 ? warnings : undefined,
462
- matchedFiles: scanned,
463
- notApplicable: false,
464
- };
465
- },
466
- };
467
-
468
- if (import.meta.main) {
469
- const failed = reportResults(await runRepoChecks([check]));
470
- process.exit(failed > 0 ? 1 : 0);
471
- }
@@ -1,87 +0,0 @@
1
- #!/usr/bin/env bun
2
- /**
3
- * Guard: JSON.parse calls must be inside a try/catch OR routed through the
4
- * safe-json helpers (parseJsonSafe / parseJsonOrThrow). Bare JSON.parse on
5
- * data from external systems (Redis, DB, HTTP) crashes the pipeline silently
6
- * with a SyntaxError when input is corrupt.
7
- *
8
- * Usage:
9
- * bun guards/guard-unsafe-json-parse.ts
10
- */
11
-
12
- import * as path from "node:path";
13
- import { type Node, type SourceFile, SyntaxKind } from "ts-morph";
14
- import { ALL_REPO_KINDS, type AstGuard, runStandalone, type ScanSpec } from "./_lib/guard-kit";
15
-
16
- const ROOT = process.cwd();
17
-
18
- const SCAN: ScanSpec = {
19
- kinds: ALL_REPO_KINDS,
20
- scope: "source",
21
- extensions: ["ts"],
22
- frameworkWithin: ["packages/*/src/**"],
23
- };
24
-
25
- const EXCLUDE = /(__tests__|\.test\.ts$|\.integration\.ts$|\.d\.ts$|safe-json\.ts$)/;
26
-
27
- interface UnsafeSite {
28
- file: string;
29
- line: number;
30
- snippet: string;
31
- }
32
-
33
- function isInsideTry(node: Node): boolean {
34
- let cur: Node | undefined = node.getParent();
35
- while (cur) {
36
- if (cur.isKind(SyntaxKind.TryStatement)) {
37
- const tryBlock = cur.asKindOrThrow(SyntaxKind.TryStatement).getTryBlock();
38
- if (
39
- tryBlock &&
40
- node.getStart() >= tryBlock.getStart() &&
41
- node.getEnd() <= tryBlock.getEnd()
42
- ) {
43
- return true;
44
- }
45
- }
46
- cur = cur.getParent();
47
- }
48
- return false;
49
- }
50
-
51
- function scanFile(sf: SourceFile): UnsafeSite[] {
52
- const sites: UnsafeSite[] = [];
53
- const calls = sf.getDescendantsOfKind(SyntaxKind.CallExpression);
54
- for (const call of calls) {
55
- const expr = call.getExpression();
56
- if (expr.getText() !== "JSON.parse") continue;
57
- if (isInsideTry(call)) continue;
58
- sites.push({
59
- file: path.relative(ROOT, sf.getFilePath()),
60
- line: call.getStartLineNumber(),
61
- snippet: call.getText().slice(0, 80),
62
- });
63
- }
64
- return sites;
65
- }
66
-
67
- export const guard: AstGuard = {
68
- name: "Unsafe-JSON-Parse Guard",
69
- scan: SCAN,
70
- hint: "Use parseJsonSafe (cache semantics) or parseJsonOrThrow (boundary semantics) from utils/safe-json.",
71
- run(files) {
72
- const violations: Array<{ file: string; line: number; message: string }> = [];
73
- for (const sf of files) {
74
- if (EXCLUDE.test(sf.getFilePath())) continue;
75
- for (const site of scanFile(sf)) {
76
- violations.push({
77
- file: site.file,
78
- line: site.line,
79
- message: `unguarded JSON.parse — ${site.snippet}`,
80
- });
81
- }
82
- }
83
- return { violations };
84
- },
85
- };
86
-
87
- if (import.meta.main) runStandalone(guard);