@cosmicdrift/kumiko-framework 0.401.0 → 0.403.0

package/dist/engine/boot-validator/boot-check.js

@@ -1,16 +1,28 @@
+import { BOOT_CHECK_RULES } from "./boot-check-rules.js";
+import { BootRuleFailures, BootRuleViolation, bootRuleError } from "./boot-rule.js";
 // r.bootCheck(fn) lets a feature declare its own mount-invariant instead of
 // relying on framework-internal knowledge (the gdpr-storage.ts guards are
 // the framework-owned version of this same idea). Each registered fn gets
 // the full mounted-feature set and throws to fail the boot; we wrap the
 // message with the owning feature's name so the error text points back at
 // the feature that declared the check.
+function prefixFailure(failure, prefix) {
+    const rule = failure instanceof BootRuleViolation ? failure.rule : BOOT_CHECK_RULES.failed;
+    return new BootRuleViolation(rule, prefix + failure.message);
+}
 export function runFeatureBootCheck(feature, check, features) {
     const ctx = { features };
+    const prefix = `[Feature ${feature.name}] r.bootCheck failed: `;
     try {
         check(ctx);
     }
     catch (err) {
+        if (err instanceof BootRuleViolation)
+            throw prefixFailure(err, prefix);
+        if (err instanceof BootRuleFailures) {
+            throw new BootRuleFailures(err.failures.map((failure) => prefixFailure(failure, prefix)));
+        }
         const message = err instanceof Error ? err.message : String(err);
-        throw new Error(`[Feature ${feature.name}] r.bootCheck failed: ${message}`);
+        throw bootRuleError(BOOT_CHECK_RULES.failed, { message: prefix + message });
     }
 }

package/dist/engine/boot-validator/boot-phases-app.js

@@ -5,6 +5,7 @@ import { validateProjectionAllowlist } from "../validate-projection-allowlist.js
 import { runFeatureBootCheck } from "./boot-check.js";
 import { validateCardMetaOverflow } from "./card-meta-overflow.js";
 import { validateConfigReads } from "./config-deps.js";
+import { validateDashboardStatNavigate } from "./dashboard-stat-navigate.js";
 import { validateExtensionPreSaveWiring } from "./entity-handler.js";
 import { validateEntityListScreens } from "./entity-list-screens.js";
 import { validateGdprStoragePersistence } from "./gdpr-storage.js";
@@ -45,6 +46,10 @@ const APP_CHECKS_AFTER_I18N = [
         check: "validateProjectionListScreens",
         run: (c) => validateProjectionListScreens(c.features),
     },
+    {
+        check: "validateDashboardStatNavigate",
+        run: (c) => validateDashboardStatNavigate(c.features),
+    },
     {
         check: "validateRelatedListSectionQueries",
         run: (c) => validateRelatedListSectionQueries(c.features),

package/dist/engine/boot-validator/boot-report.d.ts

@@ -4,3 +4,4 @@ export type BootReport = {
     finish(): void;
 };
 export declare function createBootReport(): BootReport;
+export declare function collectBootRuleViolations<T>(items: Iterable<T>, run: (item: T) => void): void;

package/dist/engine/boot-validator/boot-report.js

@@ -1,4 +1,4 @@
-import { BootValidationError } from "./boot-rule.js";
+import { BootRuleFailures, BootRuleViolation, BootValidationError, } from "./boot-rule.js";
 // A runtime crash is a bug in a validator (or in the input it assumed), not a
 // rule violation: it must surface as itself instead of masquerading as a finding.
 function isRuntimeCrash(thrown) {
@@ -10,6 +10,33 @@ function isRuntimeCrash(thrown) {
         thrown instanceof EvalError ||
         thrown instanceof URIError);
 }
+function violationsOf(failure, checkName, feature) {
+    if (failure instanceof BootRuleFailures) {
+        return failure.failures.flatMap((nested) => violationsOf(nested, checkName, feature));
+    }
+    if (failure instanceof BootValidationError)
+        return failure.violations;
+    const featurePart = feature === undefined ? {} : { feature };
+    if (failure instanceof BootRuleViolation) {
+        return [
+            {
+                ruleId: failure.rule.id,
+                check: checkName,
+                ...featurePart,
+                message: failure.message,
+                fix: failure.rule.fix,
+            },
+        ];
+    }
+    return [
+        {
+            ruleId: `unclassified/${checkName}`,
+            check: checkName,
+            ...featurePart,
+            message: failure.message,
+        },
+    ];
+}
 export function createBootReport() {
     const violations = [];
     let firstCrash;
@@ -31,12 +58,7 @@ export function createBootReport() {
                     firstCrash ??= { thrown };
                 }
                 else if (thrown instanceof Error) {
-                    violations.push({
-                        ruleId: `unclassified/${checkName}`,
-                        check: checkName,
-                        ...(feature === undefined ? {} : { feature }),
-                        message: thrown.message,
-                    });
+                    violations.push(...violationsOf(thrown, checkName, feature));
                 }
                 return false;
             }
@@ -45,3 +67,32 @@ export function createBootReport() {
         finish: endPhase,
     };
 }
+// Boundary per item: every item runs, so one boot reports all independent violations
+// instead of only the first. Crashes behave as in endPhase: dropped next to failures.
+export function collectBootRuleViolations(items, run) {
+    const failures = [];
+    let firstCrash;
+    for (const item of items) {
+        try {
+            run(item);
+        }
+        catch (thrown) {
+            if (isRuntimeCrash(thrown)) {
+                firstCrash ??= { thrown };
+            }
+            else if (thrown instanceof BootRuleFailures) {
+                failures.push(...thrown.failures);
+            }
+            else if (thrown instanceof Error) {
+                failures.push(thrown);
+            }
+        }
+    }
+    const [onlyFailure] = failures;
+    if (onlyFailure !== undefined && failures.length === 1)
+        throw onlyFailure;
+    if (failures.length > 1)
+        throw new BootRuleFailures(failures);
+    if (firstCrash !== undefined)
+        throw firstCrash.thrown;
+}

package/dist/engine/boot-validator/boot-rule.d.ts

@@ -5,6 +5,26 @@ export type BootViolation = {
     readonly message: string;
     readonly fix?: string;
 };
+export type BootRule = {
+    readonly id: string;
+    readonly summary: string;
+    readonly fix: string;
+};
+export type BootRuleTable = Readonly<Record<string, BootRule>>;
+export declare class BootRuleViolation extends Error {
+    readonly rule: BootRule;
+    readonly name = "BootRuleViolation";
+    constructor(rule: BootRule, message: string);
+}
+export declare function bootRuleError(rule: BootRule, details: {
+    readonly message: string;
+}): BootRuleViolation;
+export declare class BootRuleFailures extends Error {
+    readonly failures: readonly Error[];
+    readonly name = "BootRuleFailures";
+    constructor(failures: readonly Error[]);
+}
+export declare function bootRuleDocLink(ruleId: string): string | undefined;
 export declare class BootValidationError extends Error {
     readonly violations: readonly BootViolation[];
     readonly name = "BootValidationError";

package/dist/engine/boot-validator/boot-rule.js

@@ -1,6 +1,37 @@
+export class BootRuleViolation extends Error {
+    rule;
+    name = "BootRuleViolation";
+    constructor(rule, message) {
+        super(message);
+        this.rule = rule;
+    }
+}
+export function bootRuleError(rule, details) {
+    return new BootRuleViolation(rule, details.message);
+}
+export class BootRuleFailures extends Error {
+    failures;
+    name = "BootRuleFailures";
+    constructor(failures) {
+        super(failures.map((failure) => failure.message).join("\n"));
+        this.failures = failures;
+    }
+}
+const UNCLASSIFIED_RULE_PREFIX = "unclassified/";
+// Must match anchorOf in packages/guards/src/_lib/agent-docs-boot-rules.ts.
+export function bootRuleDocLink(ruleId) {
+    if (ruleId.startsWith(UNCLASSIFIED_RULE_PREFIX))
+        return undefined;
+    return `agents/boot-rules.md#${ruleId.replaceAll("/", "-")}`;
+}
 function describeViolation(violation) {
-    const line = `- [${violation.ruleId}] ${violation.message}`;
-    return violation.fix === undefined ? line : `${line}\n  Fix: ${violation.fix}`;
+    const lines = [`- [${violation.ruleId}] ${violation.message}`];
+    if (violation.fix !== undefined)
+        lines.push(`  Fix: ${violation.fix}`);
+    const docLink = bootRuleDocLink(violation.ruleId);
+    if (docLink !== undefined)
+        lines.push(`  Rule: ${docLink}`);
+    return lines.join("\n");
 }
 export class BootValidationError extends Error {
     violations;

package/dist/engine/boot-validator/boot-rules.d.ts

@@ -0,0 +1,246 @@
+import type { BootRule } from "./boot-rule.ts";
+export declare const FRAMEWORK_BOOT_RULE_TABLES: readonly [{
+    readonly multipleSubjectAnnotations: {
+        readonly id: "pii/multiple-subject-annotations";
+        readonly summary: "A field carries at most one subject-key annotation.";
+        readonly fix: "Keep a single personal annotation on the field.";
+    };
+    readonly textWithoutPersonalStance: {
+        readonly id: "pii/text-without-personal-stance";
+        readonly summary: "Every text and longText field declares whether it holds personal data.";
+        readonly fix: "Declare a personal stance, or personal: false with a reason stating why the value is not personal data.";
+    };
+    readonly plaintextUserReference: {
+        readonly id: "pii/plaintext-user-reference";
+        readonly summary: "A reference to the user entity is never plaintext.";
+        readonly fix: 'Use the default reference field or personal: "ref" instead of personal: false.';
+    };
+    readonly lookupableNonText: {
+        readonly id: "pii/lookupable-non-text";
+        readonly summary: "Blind-index lookups apply to text fields only.";
+        readonly fix: 'Use a text field or set find: "none".';
+    };
+    readonly lookupableWithoutSubject: {
+        readonly id: "pii/lookupable-without-subject";
+        readonly summary: "A blind-index lookup requires a subject annotation on the field.";
+        readonly fix: 'Add a personal annotation or set find: "none".';
+    };
+    readonly sensitiveWithoutCiphertext: {
+        readonly id: "pii/sensitive-without-ciphertext";
+        readonly summary: "A sensitive field is stored as ciphertext at rest.";
+        readonly fix: "Add a subject annotation or encrypted: true.";
+    };
+    readonly writeOnlyEmbeddedSubField: {
+        readonly id: "pii/write-only-embedded-sub-field";
+        readonly summary: "writeOnly is only supported on top-level text fields, not on embedded sub-fields.";
+        readonly fix: "Remove writeOnly from the sub-field or declare it on a top-level text field.";
+    };
+    readonly writeOnlyNonText: {
+        readonly id: "pii/write-only-non-text";
+        readonly summary: "writeOnly applies to text fields only.";
+        readonly fix: "Use a text field or remove writeOnly.";
+    };
+    readonly writeOnlyWithoutSensitive: {
+        readonly id: "pii/write-only-without-sensitive";
+        readonly summary: "A writeOnly field is also sensitive.";
+        readonly fix: 'Declare the field with find: "secret".';
+    };
+    readonly writeOnlyConflictingFlag: {
+        readonly id: "pii/write-only-conflicting-flag";
+        readonly summary: "A writeOnly field cannot be defaulted, searched, sorted, filtered or looked up.";
+        readonly fix: "Remove either writeOnly or the conflicting flag.";
+    };
+    readonly subjectKeySortable: {
+        readonly id: "pii/subject-key-sortable";
+        readonly summary: "A field with a subject-key annotation is not sortable, its column is ciphertext.";
+        readonly fix: 'Drop sortable, use find: "exact" for equality lookups, or keep the field plaintext.';
+    };
+    readonly sensitiveSearchable: {
+        readonly id: "pii/sensitive-searchable";
+        readonly summary: "A sensitive field is never searchable.";
+        readonly fix: "Drop searchable, or add writeOnly to never return the value.";
+    };
+    readonly personalJsonbFlag: {
+        readonly id: "pii/personal-jsonb-flag";
+        readonly summary: "A personal jsonb field cannot be sortable, filterable, searchable or lookupable, its value is a ciphertext string.";
+        readonly fix: "Remove the flag or the personal annotation.";
+    };
+    readonly personalJsonbIndex: {
+        readonly id: "pii/personal-jsonb-index";
+        readonly summary: "A personal jsonb field is not part of an entity index.";
+        readonly fix: "Drop the index or the personal annotation.";
+    };
+    readonly personalJsonbCustomFields: {
+        readonly id: "pii/personal-jsonb-custom-fields";
+        readonly summary: "The custom-fields jsonb column cannot carry a personal annotation.";
+        readonly fix: "Drop the personal annotation.";
+    };
+    readonly personalOfMissingOwnerName: {
+        readonly id: "pii/personal-of-missing-owner-name";
+        readonly summary: "personal: { of } names the owner field.";
+        readonly fix: 'Pass the name of the owner field: personal: { of: "<ownerField>" }.';
+    };
+    readonly personalOfUnknownOwner: {
+        readonly id: "pii/personal-of-unknown-owner";
+        readonly summary: "The owner field named by personal: { of } exists on the entity.";
+        readonly fix: "Point personal.of at an existing field of the entity.";
+    };
+    readonly personalOfOwnerType: {
+        readonly id: "pii/personal-of-owner-type";
+        readonly summary: "The owner field named by personal: { of } is a reference or text field.";
+        readonly fix: "Use a reference or text field as owner.";
+    };
+    readonly personalOfInvalidWhenAbsent: {
+        readonly id: "pii/personal-of-invalid-when-absent";
+        readonly summary: 'personal.whenAbsent is either "tenant" or "self".';
+        readonly fix: 'Remove whenAbsent or set it to "tenant" or "self".';
+    };
+    readonly personalOfOptionalOwner: {
+        readonly id: "pii/personal-of-optional-owner";
+        readonly summary: "An optional owner field of personal: { of } declares a whenAbsent fallback.";
+        readonly fix: 'Set whenAbsent to "tenant" or "self", or make the owner field required.';
+    };
+    readonly retentionUnknownReference: {
+        readonly id: "retention/unknown-reference";
+        readonly summary: "retention.reference names an existing field or a framework timestamp.";
+        readonly fix: "Point retention.reference at an existing field or a framework-managed timestamp.";
+    };
+}, {
+    readonly searchableFalse: {
+        readonly id: "entity-list/searchable-false";
+        readonly summary: "Operator lists are searchable unless they are on the searchable-false whitelist.";
+        readonly fix: "Set searchable: true or add the screen id to the whitelist.";
+    };
+    readonly defaultSortRequired: {
+        readonly id: "entity-list/default-sort-required";
+        readonly summary: "A list with active search or filterable fields declares a defaultSort.";
+        readonly fix: "Set defaultSort: { field, direction } on the screen.";
+    };
+    readonly defaultSortNotListed: {
+        readonly id: "entity-list/default-sort-not-listed";
+        readonly summary: "defaultSort.field is one of the listed columns.";
+        readonly fix: "Pick a field from columns or add it there.";
+    };
+    readonly defaultSortNotSortable: {
+        readonly id: "entity-list/default-sort-not-sortable";
+        readonly summary: "The defaultSort column is sortable.";
+        readonly fix: "Mark the field sortable or pick another defaultSort field.";
+    };
+    readonly detailWithoutNavigate: {
+        readonly id: "entity-list/detail-without-navigate";
+        readonly summary: "A list whose entity has a detail screen offers a navigate row action.";
+        readonly fix: 'Add a navigate rowAction with id "view" or "edit".';
+    };
+    readonly unknownNamedFilter: {
+        readonly id: "entity-list/unknown-named-filter";
+        readonly summary: "Every screen namedFilters id is declared in the entity's namedFilters.";
+        readonly fix: "Declare the rule in EntityDefinition.namedFilters or remove the id from the screen.";
+    };
+    readonly unknownColumn: {
+        readonly id: "entity-list/unknown-column";
+        readonly summary: "Every column without a label names an entity field, derived field or row-meta column.";
+        readonly fix: "Fix the column field name or give the column a label.";
+    };
+}, {
+    readonly projectionQueryAcceptsNamedFilter: {
+        readonly id: "named-filter/projection-query-accepts-named-filter";
+        readonly summary: "A projectionList with namedFilters binds a query whose schema has a namedFilter key.";
+        readonly fix: "Add namedFilter: z.string().optional() to the query schema, resolve it with resolveNamedListFilters and pass the conditions into executor.list filters, the only path that applies field-read and PII guards.";
+    };
+    readonly statNavigateTarget: {
+        readonly id: "named-filter/stat-navigate-target";
+        readonly summary: "A stat navigate.screen resolves to an entityList or projectionList screen.";
+        readonly fix: "Point navigate.screen at a registered list screen.";
+    };
+    readonly statNavigateFilterDeclared: {
+        readonly id: "named-filter/stat-navigate-filter-declared";
+        readonly summary: "A stat navigate.namedFilter is declared in the target screen's namedFilters.";
+        readonly fix: "Add { id, label } to namedFilters of the target screen.";
+    };
+    readonly statNavigateSameQuery: {
+        readonly id: "named-filter/stat-navigate-same-query";
+        readonly summary: "A stat with navigate counts with the target list's own query.";
+        readonly fix: "Set the stat query to the target list's query.";
+    };
+    readonly statNavigateSameNamedFilter: {
+        readonly id: "named-filter/stat-navigate-same-named-filter";
+        readonly summary: "A stat's params.namedFilter equals navigate.namedFilter.";
+        readonly fix: "Set params.namedFilter to the same id as navigate.namedFilter.";
+    };
+    readonly statNavigateStaticFilter: {
+        readonly id: "named-filter/stat-navigate-static-filter";
+        readonly summary: "A stat repeats the target screen's static filter in params.filter.";
+        readonly fix: "Set params.filter to the target screen's filter.";
+    };
+}, {
+    readonly missingFeatureKey: {
+        readonly id: "i18n/missing-feature-key";
+        readonly summary: "Every translation key a feature surface requires is defined.";
+        readonly fix: "Add the key via r.translations(...) in the feature.";
+    };
+    readonly missingSettingsHubKey: {
+        readonly id: "i18n/missing-settings-hub-key";
+        readonly summary: "Every translation key the generated settings hub requires is defined.";
+        readonly fix: "Add the key via r.translations(...) in the owning feature.";
+    };
+    readonly localeInconsistent: {
+        readonly id: "i18n/locale-inconsistent";
+        readonly summary: "Every locale a feature uses is maintained for every one of its translation keys.";
+        readonly fix: "Add the missing locale to the key, or move that locale into a locale package.";
+    };
+    readonly missingRequiredLocale: {
+        readonly id: "i18n/missing-required-locale";
+        readonly summary: "Every translation key exists in every locale the app requires.";
+        readonly fix: "Load the matching locale package or add the missing translations.";
+    };
+    readonly missingFieldValueTranslation: {
+        readonly id: "i18n/missing-field-value-translation";
+        readonly summary: "With requireFieldValueTranslations, select options and embedded cells are translated.";
+        readonly fix: "Add the keys via r.translations(...) in the owning feature.";
+    };
+}, {
+    readonly overflow: {
+        readonly id: "list/card-meta-overflow";
+        readonly summary: "A card list shows at most the maximum number of meta columns.";
+        readonly fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.";
+    };
+}, {
+    readonly actionIcon: {
+        readonly id: "screen/action-icon";
+        readonly summary: "Every screen action resolves to a registered icon.";
+        readonly fix: "Set icon to a registered NAV_ICONS key or use an action id that resolves one via the default icon map.";
+    };
+}, {
+    readonly unknownApi: {
+        readonly id: "api/unknown-api";
+        readonly summary: "Every r.usesApi name is exposed by some mounted feature.";
+        readonly fix: "Mount the feature that exposes the API or fix the API name.";
+    };
+    readonly providerNotRequired: {
+        readonly id: "api/provider-not-required";
+        readonly summary: "A feature using an API lists the exposing feature in requires or optionalRequires.";
+        readonly fix: "Add the exposing feature via r.requires({ features: [...] }).";
+    };
+    readonly providerNotMounted: {
+        readonly id: "api/provider-not-mounted";
+        readonly summary: "The feature exposing a used API is part of the app's feature list.";
+        readonly fix: "Register the provider feature in the app's feature list.";
+    };
+    readonly unknownExtension: {
+        readonly id: "extension/unknown-extension";
+        readonly summary: "Every extension a feature uses is defined by some mounted feature.";
+        readonly fix: "Register the feature that defines the extension or fix the extension name.";
+    };
+    readonly extensionProviderNotRequired: {
+        readonly id: "extension/provider-not-required";
+        readonly summary: "A feature using an extension lists the defining feature in requires or optionalRequires.";
+        readonly fix: "Add the defining feature via r.requires({ features: [...] }).";
+    };
+}, {
+    readonly failed: {
+        readonly id: "boot-check/failed";
+        readonly summary: "A feature's r.bootCheck invariant holds for the mounted feature set.";
+        readonly fix: "Satisfy the invariant named in the message or unmount the feature that declares it.";
+    };
+}];
+export declare const FRAMEWORK_BOOT_RULES: readonly BootRule[];

package/dist/engine/boot-validator/boot-rules.js

@@ -0,0 +1,19 @@
+import { API_EXT_RULES } from "./api-ext-rules.js";
+import { BOOT_CHECK_RULES } from "./boot-check-rules.js";
+import { CARD_META_OVERFLOW_RULES } from "./card-meta-overflow-rules.js";
+import { ENTITY_LIST_RULES } from "./entity-list-screens-rules.js";
+import { I18N_RULES } from "./i18n-keys-rules.js";
+import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
+import { PII_RULES } from "./pii-retention-rules.js";
+import { SCREEN_ACTION_RULES } from "./screens-actions-rules.js";
+export const FRAMEWORK_BOOT_RULE_TABLES = [
+    PII_RULES,
+    ENTITY_LIST_RULES,
+    NAMED_FILTER_RULES,
+    I18N_RULES,
+    CARD_META_OVERFLOW_RULES,
+    SCREEN_ACTION_RULES,
+    API_EXT_RULES,
+    BOOT_CHECK_RULES,
+];
+export const FRAMEWORK_BOOT_RULES = FRAMEWORK_BOOT_RULE_TABLES.flatMap((table) => Object.values(table));

package/dist/engine/boot-validator/card-meta-overflow-rules.d.ts

@@ -0,0 +1,7 @@
+export declare const CARD_META_OVERFLOW_RULES: {
+    readonly overflow: {
+        readonly id: "list/card-meta-overflow";
+        readonly summary: "A card list shows at most the maximum number of meta columns.";
+        readonly fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.";
+    };
+};

package/dist/engine/boot-validator/card-meta-overflow-rules.js

@@ -0,0 +1,7 @@
+export const CARD_META_OVERFLOW_RULES = {
+    overflow: {
+        id: "list/card-meta-overflow",
+        summary: "A card list shows at most the maximum number of meta columns.",
+        fix: "Reduce each list to the maximum number of meta columns or mark the others hideOnNarrow: true.",
+    },
+};

package/dist/engine/boot-validator/card-meta-overflow.js

@@ -2,6 +2,8 @@ import { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind, } from "../../ui-t
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { normalizeListColumn } from "../screen-helpers.js";
+import { bootRuleError } from "./boot-rule.js";
+import { CARD_META_OVERFLOW_RULES } from "./card-meta-overflow-rules.js";
 // Mirrors the type resolution of headless computeListViewModel; only the
 // "select" outcome matters for the card status role.
 function resolveColumnType(spec, storedType, entity) {
@@ -94,5 +96,7 @@ export function validateCardMetaOverflow(features) {
     if (overflows.length === 0)
         return;
     const lines = overflows.map((o) => `  - Feature "${o.feature}" screen "${o.screen}"${o.location !== undefined ? ` ${o.location}` : ""}: ${o.count} meta columns (${o.fields.join(", ")})`);
-    throw new Error(`List cards show at most ${CARD_META_MAX} meta columns (all columns except title, status select and hideOnNarrow ones); more would be cut off on narrow screens:\n${lines.join("\n")}\nReduce each to ${CARD_META_MAX} columns or mark the others hideOnNarrow: true.`);
+    throw bootRuleError(CARD_META_OVERFLOW_RULES.overflow, {
+        message: `List cards show at most ${CARD_META_MAX} meta columns (all columns except title, status select and hideOnNarrow ones); more would be cut off on narrow screens:\n${lines.join("\n")}\nReduce each to ${CARD_META_MAX} columns or mark the others hideOnNarrow: true.`,
+    });
 }

package/dist/engine/boot-validator/dashboard-stat-navigate.d.ts

@@ -0,0 +1,2 @@
+import type { FeatureDefinition } from "../types/index.ts";
+export declare function validateDashboardStatNavigate(features: readonly FeatureDefinition[]): void;

package/dist/engine/boot-validator/dashboard-stat-navigate.js

@@ -0,0 +1,77 @@
+import { isDeepStrictEqual } from "node:util";
+import { toKebab } from "../qualified-name.js";
+import { bootRuleError } from "./boot-rule.js";
+import { NAMED_FILTER_RULES } from "./named-filter-rules.js";
+import { resolveScreenTargetQn } from "./screens-actions.js";
+function entityListQueryName(feature, screen) {
+    return `${toKebab(feature.name)}:query:${toKebab(screen.entity)}:list`;
+}
+function listQueryOf(target) {
+    return target.screen.type === "entityList"
+        ? entityListQueryName(target.feature, target.screen)
+        : target.screen.query;
+}
+function declaredNamedFilterIds(target) {
+    return new Set((target.screen.namedFilters ?? []).map((ref) => ref.id));
+}
+function resolveListTarget(featureName, screenRef, featureMap) {
+    const qn = resolveScreenTargetQn(featureName, screenRef);
+    const [targetFeatureName = "", , targetShortId = ""] = qn.split(":");
+    const feature = featureMap.get(targetFeatureName);
+    const screen = feature?.screens[targetShortId];
+    if (feature === undefined || screen === undefined)
+        return { qn };
+    if (screen.type !== "entityList" && screen.type !== "projectionList")
+        return { qn };
+    return { feature, screen };
+}
+function validateStatNavigate(context, featureName, stat, featureMap) {
+    const navigate = stat.navigate;
+    // skip: stat has no navigate target to validate
+    if (navigate === undefined)
+        return;
+    const target = resolveListTarget(featureName, navigate.screen, featureMap);
+    if ("qn" in target) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateTarget, {
+            message: `${context} navigate.screen "${navigate.screen}" does not resolve to a registered entityList or projectionList screen (checked "${target.qn}").`,
+        });
+    }
+    if (navigate.namedFilter !== undefined &&
+        !declaredNamedFilterIds(target).has(navigate.namedFilter)) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateFilterDeclared, {
+            message: `${context} navigate.namedFilter "${navigate.namedFilter}" is not declared in namedFilters of screen "${target.screen.id}". Add { id, label } to that screen.`,
+        });
+    }
+    const listQuery = listQueryOf(target);
+    if (stat.query !== listQuery) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateSameQuery, {
+            message: `${context} navigate targets screen "${target.screen.id}" whose list query is "${listQuery}", but the stat counts with query "${stat.query}". Count with the list's own query so tile and list cannot drift.`,
+        });
+    }
+    if (stat.params?.["namedFilter"] !== navigate.namedFilter) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateSameNamedFilter, {
+            message: `${context} params.namedFilter (${JSON.stringify(stat.params?.["namedFilter"])}) must equal navigate.namedFilter (${JSON.stringify(navigate.namedFilter)}), otherwise the tile counts other rows than the list shows.`,
+        });
+    }
+    const staticFilter = target.screen.filter;
+    if (staticFilter !== undefined && !isDeepStrictEqual(stat.params?.["filter"], staticFilter)) {
+        throw bootRuleError(NAMED_FILTER_RULES.statNavigateStaticFilter, {
+            message: `${context} target screen "${target.screen.id}" has a static filter the tile does not apply. Set params.filter to the same filter on the stat.`,
+        });
+    }
+}
+export function validateDashboardStatNavigate(features) {
+    const featureMap = new Map(features.map((f) => [f.name, f]));
+    for (const feature of features) {
+        for (const screen of Object.values(feature.screens)) {
+            if (screen.type !== "dashboard")
+                continue;
+            for (const panel of screen.panels) {
+                const stats = panel.kind === "stat" ? [panel] : panel.kind === "stat-group" ? panel.stats : [];
+                for (const stat of stats) {
+                    validateStatNavigate(`[Feature ${feature.name}] Screen "${screen.id}" (dashboard) stat "${stat.id}"`, feature.name, stat, featureMap);
+                }
+            }
+        }
+    }
+}

package/dist/engine/boot-validator/entity-list-screens-rules.d.ts

@@ -0,0 +1,37 @@
+export declare const ENTITY_LIST_RULES: {
+    readonly searchableFalse: {
+        readonly id: "entity-list/searchable-false";
+        readonly summary: "Operator lists are searchable unless they are on the searchable-false whitelist.";
+        readonly fix: "Set searchable: true or add the screen id to the whitelist.";
+    };
+    readonly defaultSortRequired: {
+        readonly id: "entity-list/default-sort-required";
+        readonly summary: "A list with active search or filterable fields declares a defaultSort.";
+        readonly fix: "Set defaultSort: { field, direction } on the screen.";
+    };
+    readonly defaultSortNotListed: {
+        readonly id: "entity-list/default-sort-not-listed";
+        readonly summary: "defaultSort.field is one of the listed columns.";
+        readonly fix: "Pick a field from columns or add it there.";
+    };
+    readonly defaultSortNotSortable: {
+        readonly id: "entity-list/default-sort-not-sortable";
+        readonly summary: "The defaultSort column is sortable.";
+        readonly fix: "Mark the field sortable or pick another defaultSort field.";
+    };
+    readonly detailWithoutNavigate: {
+        readonly id: "entity-list/detail-without-navigate";
+        readonly summary: "A list whose entity has a detail screen offers a navigate row action.";
+        readonly fix: 'Add a navigate rowAction with id "view" or "edit".';
+    };
+    readonly unknownNamedFilter: {
+        readonly id: "entity-list/unknown-named-filter";
+        readonly summary: "Every screen namedFilters id is declared in the entity's namedFilters.";
+        readonly fix: "Declare the rule in EntityDefinition.namedFilters or remove the id from the screen.";
+    };
+    readonly unknownColumn: {
+        readonly id: "entity-list/unknown-column";
+        readonly summary: "Every column without a label names an entity field, derived field or row-meta column.";
+        readonly fix: "Fix the column field name or give the column a label.";
+    };
+};