@cosmicdrift/kumiko-framework 0.250.0 → 0.251.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.250.0",
+  "version": "0.251.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.250.0",
+    "@cosmicdrift/kumiko-types": "0.251.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.250.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.251.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/engine/__tests__/screen.test.ts

@@ -362,6 +362,190 @@ describe("r.screen() — registration", () => {
     expect(() => validateBoot(features)).not.toThrow();
   });
 
+  describe("relatedList search + facets (fw#2740)", () => {
+    test("rejects searchable: true when the bound query's schema has no search parameter", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+            access: { openToAll: true },
+          });
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  searchable: true,
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/searchable: true.*"search"/);
+    });
+
+    test("accepts searchable: true when the bound query's schema accepts search", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ search: z.string().optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            { access: { openToAll: true } },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  searchable: true,
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+
+    test("rejects facets when the bound query's schema has no filters parameter", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+            access: { openToAll: true },
+          });
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name", "status"],
+                  facets: [
+                    {
+                      field: "status",
+                      type: "select",
+                      label: "Status",
+                      options: [{ value: "active", label: "Active" }],
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(/declares facets but query.*"filters"/);
+    });
+
+    test("rejects a facet whose field is not a declared column", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ filters: z.array(z.object({})).optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            { access: { openToAll: true } },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name"],
+                  facets: [
+                    {
+                      field: "status",
+                      type: "select",
+                      label: "Status",
+                      options: [{ value: "active", label: "Active" }],
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).toThrow(
+        /relatedList section "s".*facet references field "status" which is not a declared column/,
+      );
+    });
+
+    test("accepts valid facets when the bound query's schema accepts filters", () => {
+      const features = [
+        defineFeature("app", (r) => {
+          r.queryHandler("foo:detail", z.object({}), async () => ({}), {
+            access: { openToAll: true },
+          });
+          r.queryHandler(
+            "foo:list",
+            z.object({ filters: z.array(z.object({})).optional() }),
+            async () => ({ rows: [], nextCursor: null }),
+            { access: { openToAll: true } },
+          );
+          r.screen({
+            id: "x",
+            type: "projectionDetail",
+            query: "app:query:foo:detail",
+            layout: {
+              sections: [
+                {
+                  kind: "relatedList",
+                  title: "s",
+                  query: "app:query:foo:list",
+                  columns: ["name", "status"],
+                  facets: [
+                    {
+                      field: "status",
+                      type: "select",
+                      label: "Status",
+                      options: [{ value: "active", label: "Active" }],
+                    },
+                  ],
+                },
+              ],
+            },
+          });
+        }),
+      ];
+      expect(() => validateBoot(features)).not.toThrow();
+    });
+  });
+
   test("validateBoot rejects a relatedList section on entityEdit (fw#2166)", () => {
     const features = [
       defineFeature("shop", (r) => {

package/src/engine/boot-validator/index.ts

@@ -46,7 +46,10 @@ import {
 } from "./nav";
 import { collectClaimKeys, validateOwnershipRules } from "./ownership";
 import { validatePiiAndRetention } from "./pii-retention";
-import { validateProjectionListScreens } from "./projection-list-screens";
+import {
+  validateProjectionListScreens,
+  validateRelatedListSectionQueries,
+} from "./projection-list-screens";
 import { validateQueryOutputColumns } from "./query-output-columns";
 import { validateQueryRefs } from "./query-refs";
 import {
@@ -224,6 +227,7 @@ export function validateBoot(
   // assume every `query` string already resolves to a registered handler.
   validateQueryOutputColumns(features);
   validateProjectionListScreens(features);
+  validateRelatedListSectionQueries(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateFeatureBootChecks(features);

package/src/engine/boot-validator/projection-list-screens.ts

@@ -121,3 +121,45 @@ export function validateProjectionListScreens(features: readonly FeatureDefiniti
     }
   }
 }
+
+// relatedList sections declare search/facets the same way a projectionList
+// screen does, and hit the same 422 footgun: definePagedQueryHandler doesn't
+// auto-merge params into the handler's own Zod schema (fw#2165/#2224), so an
+// undeclared param would fail every query instead of failing at boot.
+// Reachable on projectionDetail only (screens.ts rejects relatedList
+// elsewhere), but the layout walk stays uniform so lifting that restriction
+// doesn't quietly skip these checks.
+export function validateRelatedListSectionQueries(features: readonly FeatureDefinition[]): void {
+  const queryHandlers = buildQueryHandlerMap(features);
+  for (const feature of features) {
+    for (const screen of Object.values(feature.screens)) {
+      if (
+        screen.type !== "projectionDetail" &&
+        screen.type !== "entityEdit" &&
+        screen.type !== "actionForm" &&
+        screen.type !== "configEdit"
+      ) {
+        continue;
+      }
+      for (const section of screen.layout.sections) {
+        if (section.kind !== "relatedList") continue;
+        const prefix = `[Feature ${feature.name}] Screen "${screen.id}" (${screen.type}) relatedList section "${section.title}"`;
+        const schema = queryHandlers.get(section.query)?.schema;
+        if (section.searchable === true && !schemaAccepts(schema, "search")) {
+          throw new Error(
+            `${prefix}: searchable: true but query "${section.query}" has no "search" parameter in its Zod schema`,
+          );
+        }
+        if (
+          section.facets !== undefined &&
+          section.facets.length > 0 &&
+          !schemaAccepts(schema, "filters")
+        ) {
+          throw new Error(
+            `${prefix}: declares facets but query "${section.query}" has no "filters" parameter in its Zod schema — add filters: z.array(z.object({ field: z.string(), op: z.literal("in"), value: z.unknown() })).optional() (or reuse entityListSchema's shape) to the handler's schema.`,
+          );
+        }
+      }
+    }
+  }
+}

package/src/engine/boot-validator/screens.ts

@@ -25,6 +25,8 @@ import type {
   EditFieldSpec,
   EditLayout,
   FieldCondition,
+  ListColumnSpec,
+  ListFacetSpec,
   RowAction,
   RowActionNavigateBase,
   RowFieldExtractor,
@@ -559,37 +561,12 @@ export function validateScreens(
             `filter.value to be a readonly array.`,
         );
       }
-      // Facets (fw#2224) — unlike filter, a field inventory IS available
-      // here: the declared columns. A facet on a field with no column is
-      // almost always a typo (the user never sees the field anywhere), so
-      // this is hard-checked rather than just documented.
       if (screen.facets !== undefined) {
-        const columnFieldNames = new Set(
-          screen.columns.map((col) => normalizeListColumn(col).field),
+        validateListFacets(
+          `[Feature ${feature.name}] Screen "${screenId}" (projectionList)`,
+          screen.facets,
+          screen.columns,
         );
-        const seenFacetFields = new Set<string>();
-        for (const facet of screen.facets) {
-          if (seenFacetFields.has(facet.field)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) declares facet ` +
-                `"${facet.field}" more than once.`,
-            );
-          }
-          seenFacetFields.add(facet.field);
-          if (!columnFieldNames.has(facet.field)) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet references field ` +
-                `"${facet.field}" which is not a declared column. Known columns: ` +
-                `${[...columnFieldNames].sort().join(", ")}`,
-            );
-          }
-          if (facet.type === "select" && facet.options.length === 0) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionList) facet "${facet.field}" ` +
-                `(type "select") has an empty options list — declare at least one option.`,
-            );
-          }
-        }
       }
       if (screen.rowActions !== undefined) {
         for (const action of screen.rowActions) {
@@ -863,6 +840,13 @@ export function validateScreens(
               );
             }
           }
+          if (section.facets !== undefined) {
+            validateListFacets(
+              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) relatedList section "${section.title}"`,
+              section.facets,
+              section.columns,
+            );
+          }
           continue;
         }
         if (isWriteFormEditSection(section)) {
@@ -1805,6 +1789,38 @@ export function validateColumnRendererForm(
   }
 }
 
+// Facets (fw#2224) — unlike filter, a field inventory IS available here: the
+// declared columns. A facet on a field with no column is almost always a
+// typo (the user never sees the field anywhere), so this is hard-checked
+// rather than just documented. Shared by projectionList and relatedList
+// (fw#2740) — `prefix` carries the caller's own screen/section message lead-in.
+function validateListFacets(
+  prefix: string,
+  facets: readonly ListFacetSpec[],
+  columns: readonly ListColumnSpec[],
+): void {
+  const columnFieldNames = new Set(columns.map((col) => normalizeListColumn(col).field));
+  const seenFacetFields = new Set<string>();
+  for (const facet of facets) {
+    if (seenFacetFields.has(facet.field)) {
+      throw new Error(`${prefix} declares facet "${facet.field}" more than once.`);
+    }
+    seenFacetFields.add(facet.field);
+    if (!columnFieldNames.has(facet.field)) {
+      throw new Error(
+        `${prefix} facet references field "${facet.field}" which is not a declared column. ` +
+          `Known columns: ${[...columnFieldNames].sort().join(", ")}`,
+      );
+    }
+    if (facet.type === "select" && facet.options.length === 0) {
+      throw new Error(
+        `${prefix} facet "${facet.field}" (type "select") has an empty options list — ` +
+          `declare at least one option.`,
+      );
+    }
+  }
+}
+
 export function findEntityFeature(
   entityName: string,
   featureMap: ReadonlyMap<string, FeatureDefinition>,