@cosmicdrift/kumiko-framework 0.319.0 → 0.321.0

package/src/engine/__tests__/toolbar-navigate-tab.test.ts

@@ -0,0 +1,233 @@
+import { describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
+describe("validateBoot — ToolbarAction.tab", () => {
+  test("entityList toolbar navigate + unknown tab throws with the action id", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("vehicle:detail", z.object({}), async () => ({ name: "x" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "vehicle-detail",
+        type: "projectionDetail",
+        query: "app:query:vehicle:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", fields: ["name"] },
+            { id: "channels", title: "Channels", fields: ["name"] },
+          ],
+        },
+      });
+      r.entity(
+        "car",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.screen({
+        id: "car-list",
+        type: "entityList",
+        entity: "car",
+        columns: ["name"],
+        toolbarActions: [
+          {
+            kind: "navigate",
+            id: "view-channels",
+            label: "app.actions.viewChannels",
+            screen: "vehicle-detail",
+            tab: "unknown",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /toolbarAction "view-channels".*navigates to tab "unknown", which is not a section id on target screen/,
+    );
+  });
+
+  test("entityList toolbar navigate + known tab boots cleanly", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("vehicle:detail", z.object({}), async () => ({ name: "x" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "vehicle-detail",
+        type: "projectionDetail",
+        query: "app:query:vehicle:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", fields: ["name"] },
+            { id: "channels", title: "Channels", fields: ["name"] },
+          ],
+        },
+      });
+      r.entity(
+        "car",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.screen({
+        id: "car-list",
+        type: "entityList",
+        entity: "car",
+        columns: ["name"],
+        toolbarActions: [
+          {
+            kind: "navigate",
+            id: "view-channels",
+            label: "app.actions.viewChannels",
+            screen: "vehicle-detail",
+            tab: "channels",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("entityList toolbar navigate targeting a non-tabs projectionDetail throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("vehicle:detail", z.object({}), async () => ({ name: "x" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "vehicle-detail",
+        type: "projectionDetail",
+        query: "app:query:vehicle:detail",
+        layout: { sections: [{ title: "Overview", fields: ["name"] }] },
+      });
+      r.entity(
+        "car",
+        createEntity({
+          fields: { name: createTextField({ personal: false, reason: "test_fixture" }) },
+        }),
+      );
+      r.screen({
+        id: "car-list",
+        type: "entityList",
+        entity: "car",
+        columns: ["name"],
+        toolbarActions: [
+          {
+            kind: "navigate",
+            id: "view-channels",
+            label: "app.actions.viewChannels",
+            screen: "vehicle-detail",
+            tab: "overview",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /is not a projectionDetail with layout.mode "tabs"/,
+    );
+  });
+
+  test("projectionList toolbar navigate + unknown tab throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("vehicle:detail", z.object({}), async () => ({ name: "x" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "vehicle-detail",
+        type: "projectionDetail",
+        query: "app:query:vehicle:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", fields: ["name"] },
+            { id: "channels", title: "Channels", fields: ["name"] },
+          ],
+        },
+      });
+      r.queryHandler("car:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "car-projection-list",
+        type: "projectionList",
+        query: "app:query:car:list",
+        columns: ["name"],
+        toolbarActions: [
+          {
+            kind: "navigate",
+            id: "view-channels",
+            label: "app.actions.viewChannels",
+            screen: "vehicle-detail",
+            tab: "unknown",
+          },
+        ],
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /toolbarAction "view-channels".*navigates to tab "unknown", which is not a section id on target screen/,
+    );
+  });
+
+  test("relatedList section toolbar navigate + unknown tab throws", () => {
+    const feature = defineFeature("app", (r) => {
+      r.queryHandler("vehicle:detail", z.object({}), async () => ({ name: "x" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.screen({
+        id: "vehicle-detail",
+        type: "projectionDetail",
+        query: "app:query:vehicle:detail",
+        layout: {
+          mode: "tabs",
+          sections: [
+            { id: "overview", title: "Overview", fields: ["name"] },
+            { id: "channels", title: "Channels", fields: ["name"] },
+          ],
+        },
+      });
+      r.queryHandler("lease:detail", z.object({}), async () => ({ id: "1" }), {
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      });
+      r.queryHandler(
+        "lease:positions",
+        z.object({}),
+        async () => ({ rows: [], nextCursor: null }),
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
+      );
+      r.screen({
+        id: "lease-detail",
+        type: "projectionDetail",
+        query: "app:query:lease:detail",
+        layout: {
+          sections: [
+            {
+              kind: "relatedList",
+              title: "Positions",
+              query: "app:query:lease:positions",
+              columns: ["id"],
+              toolbarActions: [
+                {
+                  kind: "navigate",
+                  id: "view-channels",
+                  label: "app.actions.viewChannels",
+                  screen: "vehicle-detail",
+                  tab: "unknown",
+                },
+              ],
+            },
+          ],
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(
+      /toolbarAction "view-channels".*navigates to tab "unknown", which is not a section id on target screen/,
+    );
+  });
+});

package/src/engine/boot-validator/pii-retention.ts

@@ -1,5 +1,5 @@
 import type { FeatureDefinition } from "../types";
-import type { ResolvedPiiFlags } from "../types/fields";
+import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
 import {
   PII_DIRECT_NAME_HINTS,
   PII_USER_OWNED_NAME_HINTS,
@@ -27,6 +27,17 @@ function hasAnonymizableSubjectField(annot: ResolvedPiiFlags): boolean {
   return Boolean(annot.pii || annot.userOwned || annot.tenantOwned || annot.recordOwned);
 }
 
+function ownerFieldNamesReferencedByPersonalOf(
+  fieldsByName: EntityDefinition["fields"],
+): ReadonlySet<string> {
+  const ownerFieldNames = new Set<string>();
+  for (const field of Object.values(fieldsByName)) {
+    const ownerFieldName = (field as ResolvedPiiFlags).userOwned?.ownerField; // @cast-boundary schema-walk
+    if (typeof ownerFieldName === "string") ownerFieldNames.add(ownerFieldName);
+  }
+  return ownerFieldNames;
+}
+
 // --- PII / Subject-Key Annotations + Retention validation ---
 //
 // Drei Klassen von Checks:
@@ -54,6 +65,7 @@ function hasAnonymizableSubjectField(annot: ResolvedPiiFlags): boolean {
 export function validatePiiAndRetention(feature: FeatureDefinition): void {
   for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
     const fieldsByName = entity.fields;
+    const personalOfOwnerFieldNames = ownerFieldNamesReferencedByPersonalOf(fieldsByName);
 
     for (const [fieldName, field] of Object.entries(fieldsByName)) {
       // ResolvedPiiFlags properties are type-level optional. On field defs
@@ -192,7 +204,11 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-content-typical name but no personal annotation. If this contains user-generated content, mark it { personal: { of: "<authorIdField>" }, find: ... }. If business data, set { personal: false, reason: "..." } to silence.`,
           );
-        } else if (PII_USER_REFERENCE_NAME_HINTS.has(lower) && !annot.subjectRef) {
+        } else if (
+          PII_USER_REFERENCE_NAME_HINTS.has(lower) &&
+          !annot.subjectRef &&
+          !personalOfOwnerFieldNames.has(fieldName)
+        ) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Field "${fieldName}" on entity "${entityName}" has a user-reference-typical name but no personal annotation — a foreign key into \`user\` carries Art.17 obligations even with no annotated content on the entity. Mark it { personal: "ref" } AND register r.useExtension(EXT_USER_DATA, "${entityName}", …) for Art.17 coverage — this warning is the only boot-time check for that, registering the hook is not enforced. Or { personal: { of: "${fieldName}" } } on the field it owns. If business data, set { personal: false, reason: "..." } to silence.`,

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

@@ -450,7 +450,7 @@ export function validateScreenShortIdCollisions(
 // cross-feature screen QN (`<feature>:screen:<id>`) given verbatim — a
 // short id can never itself be a valid QN (QN_SEGMENT forbids colons), so
 // the two forms don't collide.
-function resolveScreenTargetQn(featureName: string, target: string): string {
+export function resolveScreenTargetQn(featureName: string, target: string): string {
   return isValidQn(target) ? target : qualifyEntityName(featureName, "screen", target);
 }
 
@@ -1158,9 +1158,9 @@ export function validateScreens(
         }
         validateAtMostOneRowClick(feature.name, screenId, "projectionList", screen.rowActions);
       }
-      // Only drawer-kind is validated here — navigate/writeHandler toolbarActions
-      // on projectionList have no boot check yet (pre-existing gap, out of
-      // scope for fw#2225).
+      // Only drawer-kind and navigate actions that set tab are validated
+      // here — plain navigate (no tab) and writeHandler toolbarActions on
+      // projectionList have no boot check yet (pre-existing gap).
       if (screen.toolbarActions !== undefined) {
         for (const action of screen.toolbarActions) {
           if (action.kind === "drawer") {
@@ -1173,6 +1173,19 @@ export function validateScreens(
               feature.screens,
             );
           }
+          if (action.kind === "navigate" && action.tab !== undefined) {
+            resolveRowActionNavigateTarget(
+              feature.name,
+              screenId,
+              "projectionList",
+              "toolbarAction",
+              action,
+              allScreenQns,
+              navTargetShortIds,
+              screensByShortId,
+              detailForScreens,
+            );
+          }
         }
       }
       continue;
@@ -1239,18 +1252,35 @@ export function validateScreens(
             );
           }
           const navigate = typeof metric === "string" ? undefined : metric.navigate;
-          // Cross-screen navigate+tab isn't checked here — the target screen
-          // validates its own section ids when the loop reaches it.
-          if (
-            navigate?.tab !== undefined &&
-            navigate.screen === undefined &&
-            navigate.entity === undefined &&
-            !screen.layout.sections.some((section) => section.id === navigate.tab)
-          ) {
-            throw new Error(
-              `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${field}" ` +
-                `navigates to tab "${navigate.tab}", which is not a section id on this screen.`,
-            );
+          if (navigate?.tab !== undefined) {
+            if (navigate.screen === undefined && navigate.entity === undefined) {
+              if (!screen.layout.sections.some((section) => section.id === navigate.tab)) {
+                throw new Error(
+                  `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) metric "${field}" ` +
+                    `navigates to tab "${navigate.tab}", which is not a section id on this screen.`,
+                );
+              }
+            } else {
+              resolveRowActionNavigateTarget(
+                feature.name,
+                screenId,
+                "projectionDetail",
+                "metric",
+                {
+                  kind: "navigate",
+                  id: field,
+                  label: field,
+                  ...(navigate.screen !== undefined ? { screen: navigate.screen } : {}),
+                  ...(navigate.entity !== undefined ? { entity: navigate.entity } : {}),
+                  ...(navigate.entityId !== undefined ? { entityId: navigate.entityId } : {}),
+                  tab: navigate.tab,
+                },
+                allScreenQns,
+                navTargetShortIds,
+                screensByShortId,
+                detailForScreens,
+              );
+            }
           }
         }
       }
@@ -1459,8 +1489,9 @@ export function validateScreens(
               featureMap,
             );
           }
-          // Only drawer-kind is validated here — navigate/writeHandler
-          // toolbarActions have no boot check yet, same gap as above.
+          // Only drawer-kind and navigate actions that set tab are validated
+          // here — plain navigate (no tab) and writeHandler toolbarActions
+          // have no boot check yet, same gap as above.
           if (section.toolbarActions !== undefined) {
             for (const action of section.toolbarActions) {
               if (action.kind === "drawer") {
@@ -1473,6 +1504,19 @@ export function validateScreens(
                   feature.screens,
                 );
               }
+              if (action.kind === "navigate" && action.tab !== undefined) {
+                resolveRowActionNavigateTarget(
+                  feature.name,
+                  screenId,
+                  "projectionDetail",
+                  "toolbarAction",
+                  action,
+                  allScreenQns,
+                  navTargetShortIds,
+                  screensByShortId,
+                  detailForScreens,
+                );
+              }
             }
           }
           continue;
@@ -2002,6 +2046,19 @@ export function validateScreens(
                   `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
               );
             }
+            if (action.tab !== undefined) {
+              resolveRowActionNavigateTarget(
+                feature.name,
+                screenId,
+                "entityList",
+                "toolbarAction",
+                action,
+                allScreenQns,
+                navTargetShortIds,
+                screensByShortId,
+                detailForScreens,
+              );
+            }
           } else if (action.kind === "drawer") {
             validateDrawerTargetAction(
               feature.name,

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/alias-reexport.ts

@@ -0,0 +1 @@
+export { ORIGIN_VALUE as ALIASED } from "./origin";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/cycle-a.ts

@@ -0,0 +1 @@
+export * from "./cycle-b";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/cycle-b.ts

@@ -0,0 +1 @@
+export * from "./cycle-a";

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/entry.ts

@@ -0,0 +1,3 @@
+import { ALIASED as RENAMED } from "./star-barrel";
+
+export const marker: string = RENAMED;

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/local-rebind.ts

@@ -0,0 +1,3 @@
+import { ORIGIN_VALUE } from "./origin";
+
+export { ORIGIN_VALUE as LOCAL_EXPORT };

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/origin.ts

@@ -0,0 +1 @@
+export const ORIGIN_VALUE = "origin-value" as const;

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/star-barrel.ts

@@ -0,0 +1 @@
+export * from "./alias-reexport";

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -2799,10 +2799,10 @@ defineFeature("showpony", (r) => {
 
   test("an imported registrar-wrapper stays invisible when its file can't be resolved (in-memory project, #1008)", () => {
     // parseInline uses an in-memory ts-morph Project — "./register/screens"
-    // isn't a real file, so getModuleSpecifierSourceFile() returns
-    // undefined and the wrapper is skipped like any other unresolvable
-    // call. Real cross-file resolution against on-disk files is covered by
-    // the parseFeatureFile fixture tests below.
+    // isn't a real file, so resolveModuleFile() returns undefined and the
+    // wrapper is skipped like any other unresolvable call. Real cross-file
+    // resolution against on-disk files is covered by the parseFeatureFile
+    // fixture tests below.
     expect(result.patterns.some((p) => p.kind === "screen" || p.kind === "nav")).toBe(false);
   });
 });

package/src/engine/feature-ast/__tests__/resolve-import.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { Project, type SourceFile } from "ts-morph";
+import {
+  findImportBindingForLocalName,
+  resolveExportedVariable,
+  resolveModuleFile,
+} from "../extractors/resolve-import";
+import { parseFeatureFile, parseSourceFile } from "../parse";
+
+function loadFixture(relPath: string): SourceFile {
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  return project.addSourceFileAtPath(resolve(__dirname, relPath));
+}
+
+describe("resolveModuleFile", () => {
+  test("resolves a relative specifier to the real source file", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const resolved = resolveModuleFile(entry, "./star-barrel");
+    expect(String(resolved?.getFilePath())).toBe(
+      resolve(__dirname, "fixtures/resolve-import/star-barrel.ts"),
+    );
+  });
+
+  test("returns undefined for an unresolvable package", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const resolved = resolveModuleFile(entry, "@totally-unresolvable/not-a-real-package");
+    expect(resolved).toBeUndefined();
+  });
+});
+
+describe("findImportBindingForLocalName", () => {
+  test("follows an aliased named import to the module's original export name", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const binding = findImportBindingForLocalName(entry, "RENAMED");
+    expect(binding).toEqual({ moduleSpecifier: "./star-barrel", importedName: "ALIASED" });
+  });
+
+  test("returns undefined for a name with no import declaration", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    expect(findImportBindingForLocalName(entry, "NOT_IMPORTED")).toBeUndefined();
+  });
+});
+
+describe("resolveExportedVariable", () => {
+  test("follows a cross-file aliased re-export (export { X as Y } from ...)", () => {
+    const aliasFile = loadFixture("fixtures/resolve-import/alias-reexport.ts");
+    const decl = resolveExportedVariable(aliasFile, "ALIASED");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+    expect(decl?.getInitializer()?.getText()).toContain("origin-value");
+  });
+
+  test("follows an export * barrel to a nested aliased re-export", () => {
+    const barrelFile = loadFixture("fixtures/resolve-import/star-barrel.ts");
+    const decl = resolveExportedVariable(barrelFile, "ALIASED");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+  });
+
+  test("follows a local re-export of an imported binding (import + export {} with no from)", () => {
+    const localRebindFile = loadFixture("fixtures/resolve-import/local-rebind.ts");
+    const decl = resolveExportedVariable(localRebindFile, "LOCAL_EXPORT");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+    expect(String(decl?.getSourceFile().getFilePath())).toBe(
+      resolve(__dirname, "fixtures/resolve-import/origin.ts"),
+    );
+  });
+
+  test("terminates instead of looping forever on a mutual export * cycle", () => {
+    const cycleFile = loadFixture("fixtures/resolve-import/cycle-a.ts");
+    const decl = resolveExportedVariable(cycleFile, "NOTHING_EXPORTED_HERE");
+    expect(decl).toBeUndefined();
+  });
+
+  test("returns undefined for a name that is never exported anywhere in the chain", () => {
+    const barrelFile = loadFixture("fixtures/resolve-import/star-barrel.ts");
+    expect(resolveExportedVariable(barrelFile, "DOES_NOT_EXIST")).toBeUndefined();
+  });
+});
+
+describe("same-file shadowing (regression for the getSymbol()/getDefinitionNodes() removal)", () => {
+  function makeSourceFile(content: string): SourceFile {
+    const project = new Project({
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+      useInMemoryFileSystem: true,
+    });
+    return project.createSourceFile("shadow.ts", content);
+  }
+
+  test("an inner const declared inside setup() shadows a same-named outer const", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const NAME = "outer";
+
+defineFeature("f", (r) => {
+  const NAME = "inner";
+  r.extendsRegistrar(NAME, {});
+});
+`);
+    const result = parseSourceFile(sf);
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "extendsRegistrar", extensionName: "inner" }]);
+  });
+
+  test("a function parameter shadowing an outer const yields an unresolvable reference, not the outer value", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const NAME = "outer";
+
+defineFeature("f", (r) => {
+  function wrap(NAME) {
+    r.extendsRegistrar(NAME, {});
+  }
+  wrap("shadowed-by-param");
+});
+`);
+    const result = parseSourceFile(sf);
+    expect(result.patterns).toEqual([]);
+    expect(result.errors).toEqual([expect.objectContaining({ methodName: "extendsRegistrar" })]);
+  });
+});
+
+describe("parseFeatureFile resolves cross-file constants without a Program", () => {
+  test("sessions' imported event-name constant resolves to its real value", () => {
+    const result = parseFeatureFile(
+      resolve(__dirname, "../../../../../bundled-features/src/sessions/feature.ts"),
+    );
+    const defineEvent = result.patterns.find((p) => p.kind === "defineEvent");
+    // SESSION_REVOKED_EVENT_SHORT is imported from ./session-revoked-event —
+    // only resolves through the cross-file resolver this change replaces.
+    expect(defineEvent).toMatchObject({ eventName: "session-revoked" });
+  });
+});

package/src/engine/feature-ast/extractors/index.ts

@@ -35,6 +35,10 @@ export {
   readApplyBodies,
   readScreenStatic,
 } from "./projections-screens";
+export {
+  findImportBindingForLocalName,
+  resolveModuleFile,
+} from "./resolve-import";
 export {
   extractDescribe,
   extractOptionalRequires,