@cosmicdrift/kumiko-guards 0.322.0 → 0.323.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-guards",
-  "version": "0.322.0",
+  "version": "0.323.0",
   "description": "AST-based security guards for Kumiko repos: direct-fs/fetch, tenant escalation, admin-API, escape hatches and related checks, run over a shared ts-morph project.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -28,7 +28,7 @@
     "kumiko-pre-push": "./src/pre-push.sh"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-repo-manifest": "0.322.0",
+    "@cosmicdrift/kumiko-repo-manifest": "0.323.0",
     "ts-morph": "^28.0.0"
   },
   "publishConfig": {

package/src/_lib/guard-kit.ts

@@ -255,6 +255,10 @@ export type RunResult = {
   readonly message?: string;
   /** No root resolved at all: the target repos are not in this checkout. */
   readonly notApplicable?: boolean;
+  /** Why `notApplicable` is set — `runGuards` only; `runRepoChecks` leaves this undefined. */
+  readonly skipReason?: "repos-missing" | "outside-kinds";
+  /** The guard's `scan.kinds`, for the "outside-kinds" skip message. */
+  readonly scanKinds?: readonly string[];
   /** Files the scan matched — the runner's own count, basis of the floor. */
   readonly matchedFiles?: number;
   /** Roots whose declared sourceRoots hold no .ts/.tsx at all (D4, infra#427). */
@@ -333,13 +337,20 @@ export function runGuards(
         ? { violations: securityResult.blocking }
         : outcome;
       const { violatingRoots } = checkRootFloor(guard, scans);
+      const notApplicable = scans.length === 0;
       results.push({
         name: guard.name,
         ok: effectiveOutcome.violations.length === 0 && violatingRoots.length === 0,
         ms: Math.round(performance.now() - start),
         outcome: effectiveOutcome,
         hint: guard.hint,
-        notApplicable: scans.length === 0,
+        notApplicable,
+        skipReason: notApplicable
+          ? roots.length === 0
+            ? "repos-missing"
+            : "outside-kinds"
+          : undefined,
+        scanKinds: notApplicable ? guard.scan.kinds : undefined,
         matchedFiles: files.length,
         violatingRoots: violatingRoots.length > 0 ? violatingRoots : undefined,
         frozenFindings: securityResult?.frozen,
@@ -600,7 +611,9 @@ export function reportResults(results: readonly RunResult[]): number {
       // Not applicable does not mean checked — that must stay visible,
       // otherwise a standalone run reads like a complete one.
       const scope = r.notApplicable
-        ? " — skipped, target repos not in checkout"
+        ? r.skipReason === "outside-kinds"
+          ? ` — skipped, repo kind outside guard kinds (${(r.scanKinds ?? []).join(", ")})`
+          : " — skipped, target repos not in checkout"
         : ` (${r.matchedFiles ?? 0} files)`;
       const frozen =
         r.frozenFindings && r.frozenFindings > 0

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "guard-fake-tests now also runs in app repos, counts same-file assertion helpers and the writeOk/writeErr/queryOk/queryErr test APIs as assertions; skip output distinguishes \"outside guard kinds\" from \"target repos missing\"",
+    "migration": "A same-file helper function (or arrow/function-expression variable) whose\nbody calls `expect(...)` — directly or through up to two more levels of\nsame-file helpers — now counts as an assertion, same as calling `expect`\nin the test body itself. `stack.http.writeOk/writeErr` and\n`tenant.api.queryOk/queryErr` (matched on the last property name of the\ncallee) count as assertions too, since they throw on the wrong outcome.\nA bare Testing Library `waitFor(() => screen.getByTestId(...))` (or any\nother `getBy*`/`getAllBy*` query call) does NOT count as an assertion —\nit still needs its own `expect(...)` to prove the wait actually found\nsomething. The guard now also scans `kind: \"app\"` repos and `.tsx` test files,\nnot just framework/library `.ts`. `reportResults` now prints \"skipped,\nrepo kind outside guard kinds (<kinds>)\" instead of \"target repos not in\ncheckout\" when the checkout has repo roots but none match the guard's\n`kinds` — the missing-checkout case keeps its original message."
+  },
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "Text-Field Personal-Stance Guard exempts the two framework tests that assert the throw",
+    "detail": "`guard-text-field-stance.ts` now skips an explicit, exact\nrepo-relative-path allowlist\n(`packages/framework/src/engine/__tests__/factories-long-text.test.ts`,\n`packages/framework/src/engine/__tests__/factories-personal.test.ts`) —\nthese two deliberately call `createTextField`/`createLongTextField`\nwithout a stance to prove the fail-closed throw. A different file\nsharing one of those basenames is not exempt; the match is on the exact\nrepo-relative path. The guard also scans `samples/**` and `demo/**`\nnow, not only `packages/*/src/**`. The baseline\n(`.kumiko-text-field-stance-baseline.json`) drops to 0."
+  },
   {
     "version": "0.321.0",
     "type": "improvement",

package/src/guard-fake-tests.ts

@@ -20,8 +20,8 @@ const ROOT = process.cwd();
 
 const SCAN: ScanSpec = {
   scope: "tests",
-  extensions: ["ts"],
-  kinds: ["framework", "library"],
+  extensions: ["ts", "tsx"],
+  kinds: ["framework", "library", "app"],
 };
 
 interface Violation {
@@ -59,19 +59,60 @@ const ASSERTION_HELPER_NAMES = new Set([
   "expectTypeOf",
 ]);
 
-function countExpects(node: Node): number {
-  let n = 0;
-  node.forEachDescendant((d) => {
-    if (d.isKind(SyntaxKind.CallExpression)) {
-      const name = d.getExpression().getText();
-      if (name === "expect" || name.startsWith("expect.")) {
-        n++;
-      } else if (ASSERTION_HELPER_NAMES.has(name)) {
-        n++;
-      }
-    }
-  });
-  return n;
+// Matched on the LAST property name of a property-access callee
+// (`stack.http.writeOk(...)`, `tenant.api.queryErr(...)`) — these throw on
+// the wrong outcome, same as expect(), so a call to one counts as an
+// assertion (framework request-helper.ts, testing auth-kit.ts successData).
+const ASSERTION_API_METHODS = new Set(["writeOk", "writeErr", "queryOk", "queryErr"]);
+
+const MAX_HELPER_DEPTH = 3;
+
+function isDirectAssertionCall(call: CallExpression): boolean {
+  const expr = call.getExpression();
+  const text = expr.getText();
+  if (text === "expect" || text.startsWith("expect.")) return true;
+  if (ASSERTION_HELPER_NAMES.has(text)) return true;
+  if (!expr.isKind(SyntaxKind.PropertyAccessExpression)) return false;
+  const name = expr.getName();
+  return ASSERTION_API_METHODS.has(name);
+}
+
+// A bare identifier `foo(...)` counts as an assertion when `foo` is declared
+// in the SAME file (function declaration, or a variable initialized with an
+// arrow/function expression, at any nesting level) and its own body asserts —
+// recursively, so a chain of thin wrappers around expect() still counts.
+function resolveSameFileHelper(sf: SourceFile, name: string): Node | undefined {
+  const fn = sf
+    .getDescendantsOfKind(SyntaxKind.FunctionDeclaration)
+    .find((f) => f.getName() === name);
+  if (fn) return fn;
+  const varDecl = sf
+    .getDescendantsOfKind(SyntaxKind.VariableDeclaration)
+    .find((v) => v.getName() === name);
+  const init = varDecl?.getInitializer();
+  if (
+    init &&
+    (init.isKind(SyntaxKind.ArrowFunction) || init.isKind(SyntaxKind.FunctionExpression))
+  ) {
+    return init;
+  }
+  return undefined;
+}
+
+// depth limit + visited set: a helper chain deeper than the limit is treated
+// as unproven (violation), and a recursive helper never infinite-loops.
+function bodyHasAssertion(node: Node, sf: SourceFile, depth: number, visited: Set<Node>): boolean {
+  if (visited.has(node)) return false;
+  visited.add(node);
+  for (const call of node.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+    if (isDirectAssertionCall(call)) return true;
+    if (depth >= MAX_HELPER_DEPTH) continue;
+    const expr = call.getExpression();
+    if (!expr.isKind(SyntaxKind.Identifier)) continue;
+    const helper = resolveSameFileHelper(sf, expr.getText());
+    if (helper && bodyHasAssertion(helper, sf, depth + 1, visited)) return true;
+  }
+  return false;
 }
 
 function scanFile(sf: SourceFile): Violation[] {
@@ -100,8 +141,8 @@ function scanFile(sf: SourceFile): Violation[] {
     const isArrowOrFn =
       body.isKind(SyntaxKind.ArrowFunction) || body.isKind(SyntaxKind.FunctionExpression);
     if (!isArrowOrFn) continue;
-    const nExpect = countExpects(body);
-    if (nExpect === 0) {
+    const hasAssertion = bodyHasAssertion(body, sf, 0, new Set());
+    if (!hasAssertion) {
       const nameArg = args[0]?.getText().slice(0, 50) ?? "<anonymous>";
       violations.push({
         file: path.relative(ROOT, sf.getFilePath()),

package/src/guard-text-field-stance.ts

@@ -50,7 +50,11 @@ const ROOT = process.cwd();
 const SCAN: ScanSpec = {
   scope: "source",
   extensions: ["ts"],
-  frameworkWithin: ["packages/*/src/**"],
+  frameworkWithin: ["packages/*/src/**", "samples/**", "demo/**"],
+  // `demo/` isn't a declared sourceRoot (kumiko.json) — extraGlobs pulls its
+  // files in on top of the scope's own hits; frameworkWithin above still
+  // gates them the same as every other hit.
+  extraGlobs: ["demo/**/*.ts"],
 };
 // Unlike guard-pii-annotations.ts, tests are IN scope: kumiko-framework#2810's
 // fail-closed throw fires at call time regardless of test vs. production code —
@@ -60,6 +64,14 @@ const EXCLUDE = /\.d\.ts$/;
 
 const FIELD_FACTORY_CALLEES = new Set(["createTextField", "createLongTextField"]);
 
+// These two files deliberately call the factories without a stance to prove
+// the fail-closed throw (kumiko-framework#2921) — exact repo-relative match,
+// not basename, so a consumer file sharing a name stays flagged.
+const STANCE_THROW_TEST_ALLOWLIST = new Set<string>([
+  "packages/framework/src/engine/__tests__/factories-long-text.test.ts",
+  "packages/framework/src/engine/__tests__/factories-personal.test.ts",
+]);
+
 const VALID_PERSONAL_HINT =
   '{ personal: "self" | "tenant" | "ref" | { of: "<ownerField>" } | false } ("false" additionally needs { reason: "..." })';
 
@@ -114,6 +126,9 @@ export interface Finding {
 
 function scanFieldFactories(sf: SourceFile, roots: readonly RepoRoot[]): Finding[] {
   const findings: Finding[] = [];
+  const file = relFile(sf, roots);
+  if (STANCE_THROW_TEST_ALLOWLIST.has(file)) return findings;
+
   for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
     const callee = call.getExpression().getText();
     if (!FIELD_FACTORY_CALLEES.has(callee)) continue;
@@ -128,7 +143,6 @@ function scanFieldFactories(sf: SourceFile, roots: readonly RepoRoot[]): Finding
 
     const place = enclosingFieldName(call) ?? `${callee}(...)`;
     const line = call.getStartLineNumber();
-    const file = relFile(sf, roots);
     findings.push({ file, line, place, callee });
     console.warn(
       `  [text-field-stance WARN] ${file}:${line}  ${callee}(...) at "${place}" has no personal stance — mark ${VALID_PERSONAL_HINT}`,
@@ -137,7 +151,7 @@ function scanFieldFactories(sf: SourceFile, roots: readonly RepoRoot[]): Finding
   return findings;
 }
 
-function scan(
+export function scan(
   files: readonly SourceFile[],
   roots: readonly RepoRoot[] = resolveRepoRoots(),
 ): {

package/src/runtime-isolation-classify.ts

@@ -85,15 +85,16 @@ export function classifyByPath(repoRelativePath: string): Runtime | null {
 }
 
 /**
- * App-repo browser bundle entry, mirroring kumiko-build's own discovery
- * (`discoverClientEntries` in kumiko-framework's
+ * App-repo browser bundle entry, mirroring the naming convention apps use
+ * for `kumiko-build` entries (`resolveClientEntries` in kumiko-framework's
  * `packages/server-runtime/src/build-prod-bundle.ts`): `src/client.tsx`/
- * `src/client.ts` (single-entry) or `src/client-<suffix>.tsx?` (multi-entry).
- * Framework/enterprise packages never match — their sources live under
- * `packages/*\/src/`, not a repo-root `src/`. Kept independent of the
- * framework's own regex (cross-package import would be a build-vs-lint
- * layering violation) — if kumiko-build's discovery pattern changes, this
- * drifts and needs a matching update.
+ * `src/client.ts` (single-entry) or `src/client-<suffix>.tsx?` (declared via
+ * package.json `kumiko.clientEntries`, fw#2320 — no longer auto-discovered
+ * by this filename alone). Framework/enterprise packages never match —
+ * their sources live under `packages/*\/src/`, not a repo-root `src/`. Kept
+ * independent of the framework's own regex (cross-package import would be a
+ * build-vs-lint layering violation) — if apps stop following this naming
+ * convention, this drifts and needs a matching update.
  */
 export function isClientEntryPath(repoRelativePath: string): boolean {
   const rel = repoRelativePath.replace(/\\/g, "/");