@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/src/engine/boot-validator/__tests__/i18n-keys.test.ts

@@ -1,340 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import * as z from "zod";
-import { SETTINGS_HUB_I18N } from "../../../i18n/settings-hub-keys";
-import { buildConfigFeatureSchema } from "../../build-config-feature-schema";
-import { access, createTenantConfig } from "../../config-helpers";
-import { defineFeature } from "../../define-feature";
-import { i18nKey } from "../../i18n-key";
-import { createRegistry } from "../../registry";
-import { isFieldsEditSection } from "../../screen-helpers";
-import type { ConfigEditScreenDefinition } from "../../types";
-import { validateBoot } from "../index";
-
-// Mirrors packages/bundled-features/src/config/i18n.ts — the audience-parent
-// labels every masked config key's generated hub requires regardless of
-// which feature owns the key or which scope its keys are visible at
-// (requiredKeysFromGeneratedConfigHub adds all four unconditionally once
-// any masked key exists, see i18n-keys.ts:35-38).
-const configHub = defineFeature("config", (r) => {
-  r.translations({
-    keys: {
-      "config.settings.title": { en: "Settings" },
-      "config.settings.system": { en: "Platform" },
-      "config.settings.tenant": { en: "Tenant" },
-      "config.settings.user": { en: "Personal" },
-    },
-  });
-});
-
-// fw#2260: the Settings-Hub generator (buildConfigFeatureSchema) labels a
-// masked config key's generated nav entry / configEdit section with the
-// dot-form key `${feature}.settings` — never colon-form. isI18nKey's
-// colon-only check dropped that label from the required-keys set, so a
-// feature could ship a generated Settings screen whose label was never
-// translated and boot validation stayed silent.
-describe("validateI18nSurfaceKeys — Settings-Hub generated dot-form label (fw#2260)", () => {
-  function billingFeature(translationKeys: Record<string, { readonly en: string }>) {
-    return defineFeature("billing", (r) => {
-      r.config({
-        keys: {
-          // write restricted to a non-elevated role (see ELEVATED_ROLES in
-          // build-config-feature-schema.ts) so this stays a single
-          // tenant-scope screen — no SystemAdmin cascade to a second one.
-          apiKey: createTenantConfig("text", {
-            write: access.roles("TenantAdmin"),
-            mask: { title: "billing.api-key" },
-          }),
-        },
-      });
-      if (Object.keys(translationKeys).length > 0) {
-        r.translations({ keys: translationKeys });
-      }
-    });
-  }
-
-  test("generated nav label 'billing.settings' left untranslated fails boot", () => {
-    const billing = billingFeature({
-      "billing.api-key": { en: "API Key" },
-      "screen:billing-tenant.title": { en: "Billing Settings" },
-    });
-    expect(() => validateBoot([configHub, billing])).toThrow(
-      /Settings-Hub: required translation key missing: "billing\.settings"/,
-    );
-  });
-
-  test("translating the generated dot-form label lets boot pass", () => {
-    const billing = billingFeature({
-      "billing.api-key": { en: "API Key" },
-      "screen:billing-tenant.title": { en: "Billing Settings" },
-      "billing.settings": { en: "Billing Settings" },
-    });
-    expect(() => validateBoot([configHub, billing])).not.toThrow();
-  });
-
-  test("group namespace ≠ feature name: blank translation key satisfies hub label", () => {
-    const billing = defineFeature("billing", (r) => {
-      r.config({
-        keys: {
-          apiKey: createTenantConfig("text", {
-            write: access.roles("TenantAdmin"),
-            group: "tenant-settings",
-            mask: { title: "billing.api-key" },
-          }),
-        },
-      });
-      r.translations({
-        keys: {
-          "billing.api-key": { en: "API Key" },
-          "screen:tenant-settings-tenant.title": { en: "Tenant Settings" },
-          "tenant-settings.settings": { en: "Tenant Settings" },
-        },
-      });
-    });
-    expect(() => validateBoot([configHub, billing])).not.toThrow();
-  });
-});
-
-// PR #2314 idx2: buildConfigFeatureSchema varies the generated dot-form label
-// along two more paths that fw#2260's tests above never exercise — a tenant
-// key with an elevated (SystemAdmin) write role surfaces the same feature
-// under a second, broader scope (build-config-feature-schema.ts:142-158), and
-// a feature can opt into a configEdit section description
-// (build-config-feature-schema.ts:246-249). The `group`-namespace path is
-// deliberately left untested here — fw#2314 idx1 tracks it as broken
-// (treatDotFormAsKey requires an unsatisfiable `${group}.settings` key for a
-// namespace that has no matching feature), and a test would either fail on
-// the open bug or paper over it; it belongs with the idx1 fix, not this batch.
-describe("validateI18nSurfaceKeys — scoped label fallback for elevated write roles (PR #2314 idx2)", () => {
-  function opsFeature(translationKeys: Record<string, { readonly en: string }>) {
-    return defineFeature("ops", (r) => {
-      r.config({
-        keys: {
-          // Home scope tenant + an elevated SystemAdmin write role surfaces
-          // "ops" under BOTH the tenant audience (home, full write set) and
-          // the system audience (cascade, write set ∩ ELEVATED_ROLES.system)
-          // — two navs/screens for one feature.
-          maintenanceMode: createTenantConfig("boolean", {
-            write: access.roles("TenantAdmin", "SystemAdmin"),
-            mask: { title: "ops.maintenance-mode" },
-          }),
-        },
-      });
-      if (Object.keys(translationKeys).length > 0) {
-        r.translations({ keys: translationKeys });
-      }
-    });
-  }
-
-  test("elevated write role surfaces the feature at two scopes; the scoped override labels the system nav while the tenant nav falls back to the plain key", () => {
-    const translations = {
-      "ops.maintenance-mode": { en: "Maintenance Mode" },
-      "screen:ops-tenant.title": { en: "Ops Settings" },
-      "screen:ops-system.title": { en: "Ops Settings (Platform)" },
-      // Required unconditionally: both screens' section title is always
-      // `${feature}.settings` (build-config-feature-schema.ts:248).
-      "ops.settings": { en: "Ops" },
-      // Opt-in scoped override — only the system (cascade) nav uses it.
-      "ops.settings.system": { en: "Ops (Platform Cascade)" },
-    };
-    const ops = opsFeature(translations);
-
-    const schema = buildConfigFeatureSchema(createRegistry([configHub, ops]));
-    expect(schema.navs.find((n) => n.id === "ops-system")?.label).toBe("ops.settings.system");
-    expect(schema.navs.find((n) => n.id === "ops-tenant")?.label).toBe("ops.settings");
-
-    expect(() => validateBoot([configHub, ops])).not.toThrow();
-  });
-});
-
-// isI18nKeys.ts's requiredKeysFromScreen never reads EditFieldsSection.description
-// (only title + field labels, see required-surface-keys.ts:210-224), so this
-// gate is invisible to validateBoot either way — a validateBoot(...).not.toThrow()
-// assertion alone would pass identically with build-config-feature-schema.ts:249
-// deleted outright. Assert on the generated schema itself instead, the only
-// artifact the gate actually changes.
-describe("validateI18nSurfaceKeys — gated configEdit section description (PR #2314 idx2)", () => {
-  function reportingFeature(translationKeys: Record<string, { readonly en: string }>) {
-    return defineFeature("reporting", (r) => {
-      r.config({
-        keys: {
-          retentionDays: createTenantConfig("number", {
-            write: access.roles("TenantAdmin"),
-            mask: { title: "reporting.retention-days" },
-          }),
-        },
-      });
-      r.translations({ keys: translationKeys });
-    });
-  }
-
-  function reportingSection(translationKeys: Record<string, { readonly en: string }>) {
-    const reporting = reportingFeature(translationKeys);
-    const schema = buildConfigFeatureSchema(createRegistry([configHub, reporting]));
-    const screen = schema.screens.find(
-      (s): s is ConfigEditScreenDefinition => s.type === "configEdit",
-    );
-    if (screen === undefined) throw new Error("expected a generated configEdit screen");
-    const section = screen.layout.sections[0];
-    if (section === undefined || !isFieldsEditSection(section)) {
-      throw new Error("expected a fields section");
-    }
-    return section;
-  }
-
-  test("declaring 'reporting.settings.description' adds it to the generated section; omitting it leaves the section without one", () => {
-    const withDescription = reportingSection({
-      "reporting.retention-days": { en: "Retention (days)" },
-      "screen:reporting-tenant.title": { en: "Reporting Settings" },
-      "reporting.settings": { en: "Reporting" },
-      "reporting.settings.description": { en: "Configure how long reports are kept." },
-    });
-    expect(withDescription.description).toBe("reporting.settings.description");
-
-    const withoutDescription = reportingSection({
-      "reporting.retention-days": { en: "Retention (days)" },
-      "screen:reporting-tenant.title": { en: "Reporting Settings" },
-      "reporting.settings": { en: "Reporting" },
-    });
-    expect(withoutDescription.description).toBeUndefined();
-  });
-});
-
-// fw#2313: a hand-written dot-form label is indistinguishable from literal
-// display text, so isI18nKey only requires a translation for one explicitly
-// marked via i18nKey() — unmarked dot-form labels must keep failing silently
-// (that's the existing, intentional behavior for literal text like
-// "actions.open"), never crashing boot on their own.
-describe("validateI18nSurfaceKeys — explicit i18nKey() dot-form opt-in (fw#2313)", () => {
-  test("i18nKey()-marked dot-form label without a translation fails boot naming the key", () => {
-    const feature = defineFeature("fw2313boot", (r) => {
-      r.nav({ id: "home", label: i18nKey("fw2313.boot.optin.nav") });
-    });
-    expect(() => validateBoot([feature])).toThrow(
-      /required translation key missing: "fw2313\.boot\.optin\.nav"/,
-    );
-  });
-
-  test("i18nKey()-marked dot-form label with a translation passes boot", () => {
-    const feature = defineFeature("fw2313boot", (r) => {
-      r.nav({ id: "home", label: i18nKey("fw2313.boot.optin.nav.translated") });
-      r.translations({ keys: { "fw2313.boot.optin.nav.translated": { en: "Home" } } });
-    });
-    expect(() => validateBoot([feature])).not.toThrow();
-  });
-
-  test("unmarked literal dot-form label never fails boot", () => {
-    const feature = defineFeature("fw2313boot", (r) => {
-      r.nav({ id: "home", label: "fw2313.boot.never-marked.literal" });
-    });
-    expect(() => validateBoot([feature])).not.toThrow();
-  });
-});
-
-// The mask.title bypass is unconditional (required-surface-keys.ts,
-// requiredKeysFromFeature) — mask.title is always an i18n key by
-// ConfigKeyDefinition contract, never literal display text, so it needs no
-// i18nKey() marker.
-describe("validateI18nSurfaceKeys — mask.title is unconditionally required (fw#2313)", () => {
-  function maskedFeature(translationKeys: Record<string, { readonly en: string }>) {
-    return defineFeature("fw2313mask", (r) => {
-      r.config({
-        keys: {
-          apiKey: createTenantConfig("text", {
-            write: access.roles("TenantAdmin"),
-            mask: { title: "fw2313.boot.mask.title" },
-          }),
-        },
-      });
-      if (Object.keys(translationKeys).length > 0) {
-        r.translations({ keys: translationKeys });
-      }
-    });
-  }
-
-  test("masked config key without a mask.title translation fails boot", () => {
-    const feature = maskedFeature({});
-    expect(() => validateBoot([configHub, feature])).toThrow(
-      /required translation key missing: "fw2313\.boot\.mask\.title"/,
-    );
-  });
-
-  test("masked config key with a mask.title translation passes boot", () => {
-    const feature = maskedFeature({
-      "fw2313.boot.mask.title": { en: "API Key" },
-      "screen:fw2313mask-tenant.title": { en: "Settings" },
-      "fw2313mask.settings": { en: "Settings" },
-    });
-    expect(() => validateBoot([configHub, feature])).not.toThrow();
-  });
-});
-
-describe("validateI18nSurfaceKeys — extension-selector settings dashboard", () => {
-  const secretsMount = defineFeature("secrets", (r) => {
-    r.writeHandler(
-      "set",
-      z.object({ key: z.string(), value: z.string() }),
-      async () => ({ isSuccess: true, data: null }),
-      { access: { roles: ["TenantAdmin"] } },
-    );
-  });
-  const hubWithHint = defineFeature("config", (r) => {
-    r.translations({ keys: SETTINGS_HUB_I18N });
-  });
-  const hubWithoutHint = defineFeature("config", (r) => {
-    const { "config.settings.extensionSelectorHint": _hint, ...withoutHint } = SETTINGS_HUB_I18N;
-    r.translations({ keys: withoutHint });
-  });
-
-  // Consumer-shaped: only the keys an app declared before the selector screen existed.
-  const owner = defineFeature("mail-foundation", (r) => {
-    r.translations({
-      keys: {
-        "mail-foundation.settings": { en: "Mail" },
-        "screen:mail-foundation-tenant.title": { en: "Mail" },
-        "mail.provider": { en: "Provider" },
-      },
-    });
-    r.extendsRegistrar("mailTransport", { onRegister: () => undefined });
-    const keys = r.config({
-      keys: {
-        provider: createTenantConfig("text", {
-          default: "",
-          write: access.roles("TenantAdmin"),
-          mask: { title: "mail.provider" },
-        }),
-      },
-    });
-    r.extensionSelector("mailTransport", keys.provider);
-  });
-  const smtp = defineFeature("mail-smtp", (r) => {
-    r.requires("mail-foundation");
-    r.translations({
-      keys: {
-        "mail-smtp.settings": { en: "SMTP" },
-        "screen:mail-smtp-tenant.title": { en: "SMTP" },
-        "smtp.host": { en: "Host" },
-      },
-    });
-    r.useExtension("mailTransport", "smtp");
-    r.config({
-      keys: {
-        host: createTenantConfig("text", {
-          default: "",
-          write: access.roles("TenantAdmin"),
-          mask: { title: "smtp.host" },
-        }),
-      },
-    });
-    r.secret("password", { label: { en: "SMTP password" }, scope: "tenant" });
-  });
-
-  test("an app declaring only today's keys boots with the selector dashboard", () => {
-    expect(() => validateBoot([hubWithHint, secretsMount, owner, smtp])).not.toThrow();
-  });
-
-  test("the dashboard hint key is required once a selector dashboard exists", () => {
-    expect(() => validateBoot([hubWithoutHint, secretsMount, owner, smtp])).toThrow(
-      /Settings-Hub: required translation key missing: "config\.settings\.extensionSelectorHint"/,
-    );
-  });
-});

package/src/engine/boot-validator/__tests__/nav.test.ts

@@ -1,290 +0,0 @@
-import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
-import type { NavDefinition, WorkspaceDefinition } from "../../types";
-import { warnOnUnreachableNavScreens } from "../nav";
-import { deriveNavAllowlistFromWorkspaces, resolveNavAllowlist } from "../workspaces";
-
-function navMap(
-  entries: ReadonlyArray<[string, NavDefinition & { readonly featureName: string }]>,
-): Map<string, NavDefinition & { readonly featureName: string }> {
-  return new Map(entries);
-}
-
-function workspaceMap(
-  entries: ReadonlyArray<[string, WorkspaceDefinition & { readonly featureName: string }]>,
-): Map<string, WorkspaceDefinition & { readonly featureName: string }> {
-  return new Map(entries);
-}
-
-describe("warnOnUnreachableNavScreens", () => {
-  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
-
-  beforeEach(() => {
-    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    warnSpy.mockRestore();
-  });
-
-  test("does not warn for an unallowlisted nav whose screen is reached by an allowlisted nav", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        {
-          id: "a",
-          label: "A",
-          screen: "vehicles:screen:vin",
-          featureName: "vehicles",
-        },
-      ],
-      [
-        "vehicles:nav:b",
-        {
-          id: "b",
-          label: "B",
-          screen: "vehicles:screen:vin",
-          featureName: "vehicles",
-        },
-      ],
-    ]);
-
-    warnOnUnreachableNavScreens(allNavQns, new Set(["vehicles:nav:a"]));
-
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-
-  test("warns only for the unallowlisted nav whose screen nobody else reaches", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        {
-          id: "a",
-          label: "A",
-          screen: "vehicles:screen:vin",
-          featureName: "vehicles",
-        },
-      ],
-      [
-        "vehicles:nav:b",
-        {
-          id: "b",
-          label: "B",
-          screen: "vehicles:screen:vin",
-          featureName: "vehicles",
-        },
-      ],
-      [
-        "vehicles:nav:c",
-        {
-          id: "c",
-          label: "C",
-          screen: "vehicles:screen:title",
-          featureName: "vehicles",
-        },
-      ],
-    ]);
-
-    warnOnUnreachableNavScreens(allNavQns, new Set(["vehicles:nav:a"]));
-
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    const msg = warnSpy.mock.calls[0]![0] as string;
-    expect(msg).toContain("vehicles:nav:c");
-    expect(msg).toContain("vehicles");
-    expect(msg).toContain("vehicles:screen:title");
-  });
-
-  test("navAllowlistExempt suppresses the warning for an exempted nav", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        {
-          id: "a",
-          label: "A",
-          screen: "vehicles:screen:vin",
-          featureName: "vehicles",
-        },
-      ],
-      [
-        "vehicles:nav:c",
-        {
-          id: "c",
-          label: "C",
-          screen: "vehicles:screen:title",
-          featureName: "vehicles",
-        },
-      ],
-    ]);
-
-    warnOnUnreachableNavScreens(
-      allNavQns,
-      new Set(["vehicles:nav:a"]),
-      new Set(["vehicles:nav:c"]),
-    );
-
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-
-  test("never warns for a nav without a screen (pure grouping entry)", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:group",
-        {
-          id: "group",
-          label: "Group",
-          featureName: "vehicles",
-        },
-      ],
-    ]);
-
-    warnOnUnreachableNavScreens(allNavQns, new Set());
-
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-});
-
-describe("resolveNavAllowlist (fw#3019 solon#113: workspace-derived allowlist)", () => {
-  let warnSpy: ReturnType<typeof spyOn<Console, "warn">>;
-
-  beforeEach(() => {
-    warnSpy = spyOn(console, "warn").mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    warnSpy.mockRestore();
-  });
-
-  test("does not warn for a nav listed in a workspace's nav array", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
-      ],
-    ]);
-    const allWorkspaceQns = workspaceMap([
-      [
-        "vehicles:workspace:main",
-        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
-      ],
-    ]);
-
-    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
-    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
-
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-
-  test("does not warn for a nav that self-assigns via workspaces", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        {
-          id: "a",
-          label: "A",
-          screen: "vehicles:screen:vin",
-          workspaces: ["vehicles:workspace:main"],
-          featureName: "vehicles",
-        },
-      ],
-    ]);
-    const allWorkspaceQns = workspaceMap([
-      ["vehicles:workspace:main", { id: "main", label: "Main", featureName: "vehicles" }],
-    ]);
-
-    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
-    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
-
-    expect(warnSpy).not.toHaveBeenCalled();
-  });
-
-  test("warns for a nav in no workspace whose screen nobody else reaches (solon#113)", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
-      ],
-      [
-        "vehicles:nav:orphan",
-        { id: "orphan", label: "Orphan", screen: "vehicles:screen:title", featureName: "vehicles" },
-      ],
-    ]);
-    const allWorkspaceQns = workspaceMap([
-      [
-        "vehicles:workspace:main",
-        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
-      ],
-    ]);
-
-    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
-    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
-
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(warnSpy.mock.calls[0]![0] as string).toContain("vehicles:nav:orphan");
-  });
-
-  test("does not warn when the app has no workspaces at all", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
-      ],
-    ]);
-    const allWorkspaceQns = workspaceMap([]);
-
-    const allowlist = resolveNavAllowlist(undefined, allNavQns, allWorkspaceQns);
-
-    expect(allowlist).toBeUndefined();
-  });
-
-  test("an explicit navAllowlist wins over the workspace-derived one", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
-      ],
-    ]);
-    const allWorkspaceQns = workspaceMap([
-      [
-        "vehicles:workspace:main",
-        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
-      ],
-    ]);
-
-    const allowlist = resolveNavAllowlist(new Set(), allNavQns, allWorkspaceQns);
-    warnOnUnreachableNavScreens(allNavQns, allowlist ?? new Set());
-
-    expect(allowlist).toEqual(new Set());
-    expect(warnSpy).toHaveBeenCalledTimes(1);
-    expect(warnSpy.mock.calls[0]![0] as string).toContain("vehicles:nav:a");
-  });
-});
-
-describe("deriveNavAllowlistFromWorkspaces", () => {
-  test("unions workspace.nav entries and self-assigning nav.workspaces entries", () => {
-    const allNavQns = navMap([
-      [
-        "vehicles:nav:a",
-        { id: "a", label: "A", screen: "vehicles:screen:vin", featureName: "vehicles" },
-      ],
-      [
-        "vehicles:nav:b",
-        {
-          id: "b",
-          label: "B",
-          screen: "vehicles:screen:title",
-          workspaces: ["vehicles:workspace:main"],
-          featureName: "vehicles",
-        },
-      ],
-    ]);
-    const allWorkspaceQns = workspaceMap([
-      [
-        "vehicles:workspace:main",
-        { id: "main", label: "Main", nav: ["vehicles:nav:a"], featureName: "vehicles" },
-      ],
-    ]);
-
-    const allowlist = deriveNavAllowlistFromWorkspaces(allNavQns, allWorkspaceQns);
-
-    expect(allowlist).toEqual(new Set(["vehicles:nav:a", "vehicles:nav:b"]));
-  });
-});