@dereekb/firebase 13.12.0 → 13.12.1

package/eslint/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@dereekb/firebase/eslint",
-  "version": "13.12.0",
+  "version": "13.12.1",
   "peerDependencies": {
-    "@marcbachmann/cel-js": "^7.6.1",
     "@typescript-eslint/utils": "8.59.3"
   },
   "devDependencies": {
-    "@dereekb/util": "13.12.0",
+    "@dereekb/util": "13.12.1",
     "@marcbachmann/cel-js": "^7.6.1",
     "@typescript-eslint/parser": "8.59.3",
     "eslint": "10.4.0"

package/eslint/src/lib/index.d.ts

@@ -4,7 +4,8 @@ export { FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_COMPANION_TAGS_RULE, type Fir
 export { FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_VALID_DISPATCHER_RULE, type FirebaseRequireDbxModelFirebaseIndexValidDispatcherRuleOptions, type FirebaseRequireDbxModelFirebaseIndexValidDispatcherRuleDefinition } from './require-dbx-model-firebase-index-valid-dispatcher.rule';
 export { FIREBASE_REQUIRE_FIRESTORE_CONSTRAINT_TYPE_PARAMETER_RULE, type FirebaseRequireFirestoreConstraintTypeParameterRuleOptions, type FirebaseRequireFirestoreConstraintTypeParameterRuleDefinition } from './require-firestore-constraint-type-parameter.rule';
 export { FIREBASE_REQUIRE_COMPLETE_CRUD_FUNCTION_CONFIG_MAP_RULE, DEFAULT_CRUD_VERB_NAMES, MODEL_FIREBASE_CRUD_FUNCTION_CONFIG_MAP_TYPE_NAME, type FirebaseRequireCompleteCrudFunctionConfigMapRuleOptions, type FirebaseRequireCompleteCrudFunctionConfigMapRuleDefinition } from './require-complete-crud-function-config-map.rule';
-export { FIREBASE_REQUIRE_API_DETAILS_FOR_CRUD_FUNCTION_RULE, DEFAULT_CRUD_FUNCTION_TYPE_VERBS, DEFAULT_API_DETAILS_FACTORY_NAME, type FirebaseRequireApiDetailsForCrudFunctionRuleOptions, type FirebaseRequireApiDetailsForCrudFunctionRuleDefinition } from './require-api-details-for-crud-function.rule';
+export { FIREBASE_REQUIRE_API_DETAILS_FOR_CRUD_FUNCTION_RULE, type FirebaseRequireApiDetailsForCrudFunctionRuleOptions, type FirebaseRequireApiDetailsForCrudFunctionRuleDefinition } from './require-api-details-for-crud-function.rule';
+export { FIREBASE_REQUIRE_INPUT_TYPE_FOR_API_DETAILS_RULE, type FirebaseRequireInputTypeForApiDetailsRuleOptions, type FirebaseRequireInputTypeForApiDetailsRuleDefinition } from './require-input-type-for-api-details.rule';
 export { FIREBASE_REQUIRE_STORAGEFILE_POLICY_MATCHES_RULES_RULE, DEFAULT_STORAGE_FILE_UPLOAD_POLICY_TYPE_NAME, DEFAULT_STORAGE_RULES_FILENAME, type FirebaseRequireStorageFilePolicyMatchesRulesRuleOptions, type FirebaseRequireStorageFilePolicyMatchesRulesRuleDefinition } from './require-storagefile-policy-matches-rules.rule';
 export { FIREBASE_REQUIRE_FIRESTORE_RULE_FOR_SERVICE_MODEL_RULE, DEFAULT_FIRESTORE_RULES_FILENAME, DEFAULT_REGISTRY_FACTORY_CALL_NAME, DEFAULT_IDENTITY_FACTORY_NAME, DEFAULT_MODEL_SEARCH_ROOTS, type FirebaseRequireFirestoreRuleForServiceModelRuleOptions, type FirebaseRequireFirestoreRuleForServiceModelRuleDefinition, type VirtualModelIdentity } from './require-firestore-rule-for-service-model.rule';
 export { FIREBASE_REQUIRE_DBX_MODEL_SERVICE_FACTORY_TAG_RULE, FIREBASE_MODEL_SERVICE_FACTORY_NAME, FIREBASE_MODEL_SERVICE_FACTORY_MODULE, DBX_MODEL_SERVICE_FACTORY_TAG, type FirebaseRequireDbxModelServiceFactoryTagRuleOptions, type FirebaseRequireDbxModelServiceFactoryTagRuleDefinition } from './require-dbx-model-service-factory-tag.rule';
@@ -13,4 +14,4 @@ export { FIREBASE_REQUIRE_DBX_MODEL_COMPANION_TAGS_RULE, type FirebaseRequireDbx
 export { parseStorageRules, MIRRORS_POLICY_KEY_MARKER_REGEX, type ParsedRuleBranch, type ParsedStorageRulesBlock } from './storage-rules-parser';
 export { parseFirestoreRules, type ParsedFirestoreMatchBlock } from './firestore-rules-parser';
 export { FIREBASE_ESLINT_PLUGIN, firebaseESLintPlugin, type FirebaseEslintPlugin } from './plugin';
-export { DBX_MODEL_FIREBASE_INDEX_MARKER, DEFAULT_CONSTRAINT_FACTORY_NAMES, DEFAULT_INDEX_AFFECTING_CONSTRAINT_NAMES, DEFAULT_PAGINATION_CONSTRAINT_NAMES, FIREBASE_MODULE, QUERY_SUFFIX } from './util';
+export { DBX_MODEL_FIREBASE_INDEX_MARKER, DEFAULT_CONSTRAINT_FACTORY_NAMES, DEFAULT_INDEX_AFFECTING_CONSTRAINT_NAMES, DEFAULT_PAGINATION_CONSTRAINT_NAMES, FIREBASE_MODULE, QUERY_SUFFIX, DEFAULT_CRUD_FUNCTION_TYPE_VERBS, DEFAULT_API_DETAILS_FACTORY_NAME, INPUT_TYPE_PROPERTY_NAME, API_DETAILS_IMPORT_MODULE } from './util';

package/eslint/src/lib/plugin.d.ts

@@ -5,6 +5,7 @@ import { FIREBASE_REQUIRE_DBX_MODEL_FIREBASE_INDEX_VALID_DISPATCHER_RULE } from
 import { FIREBASE_REQUIRE_FIRESTORE_CONSTRAINT_TYPE_PARAMETER_RULE } from './require-firestore-constraint-type-parameter.rule';
 import { FIREBASE_REQUIRE_COMPLETE_CRUD_FUNCTION_CONFIG_MAP_RULE } from './require-complete-crud-function-config-map.rule';
 import { FIREBASE_REQUIRE_API_DETAILS_FOR_CRUD_FUNCTION_RULE } from './require-api-details-for-crud-function.rule';
+import { FIREBASE_REQUIRE_INPUT_TYPE_FOR_API_DETAILS_RULE } from './require-input-type-for-api-details.rule';
 import { FIREBASE_REQUIRE_STORAGEFILE_POLICY_MATCHES_RULES_RULE } from './require-storagefile-policy-matches-rules.rule';
 import { FIREBASE_REQUIRE_FIRESTORE_RULE_FOR_SERVICE_MODEL_RULE } from './require-firestore-rule-for-service-model.rule';
 import { FIREBASE_REQUIRE_DBX_MODEL_SERVICE_FACTORY_TAG_RULE } from './require-dbx-model-service-factory-tag.rule';
@@ -22,6 +23,7 @@ export interface FirebaseEslintPlugin {
         readonly 'require-firestore-constraint-type-parameter': typeof FIREBASE_REQUIRE_FIRESTORE_CONSTRAINT_TYPE_PARAMETER_RULE;
         readonly 'require-complete-crud-function-config-map': typeof FIREBASE_REQUIRE_COMPLETE_CRUD_FUNCTION_CONFIG_MAP_RULE;
         readonly 'require-api-details-for-crud-function': typeof FIREBASE_REQUIRE_API_DETAILS_FOR_CRUD_FUNCTION_RULE;
+        readonly 'require-input-type-for-api-details': typeof FIREBASE_REQUIRE_INPUT_TYPE_FOR_API_DETAILS_RULE;
         readonly 'require-storagefile-policy-matches-rules': typeof FIREBASE_REQUIRE_STORAGEFILE_POLICY_MATCHES_RULES_RULE;
         readonly 'require-firestore-rule-for-service-model': typeof FIREBASE_REQUIRE_FIRESTORE_RULE_FOR_SERVICE_MODEL_RULE;
         readonly 'require-dbx-model-service-factory-tag': typeof FIREBASE_REQUIRE_DBX_MODEL_SERVICE_FACTORY_TAG_RULE;

package/eslint/src/lib/require-api-details-for-crud-function.rule.d.ts

@@ -1,19 +1,4 @@
 import { type AstNode } from './util';
-/**
- * Default CRUD verb names that combine with the `ModelFunction` suffix to form a type-name
- * pattern this rule treats as a CRUD function declaration (e.g. `OnCallCreateModelFunction`,
- * `DemoUpdateModelFunction`).
- *
- * Mirrors the verbs supported by `ModelFirebaseCrudFunctionConfigMap` — see
- * `packages/firebase/src/lib/client/function/model.function.factory.ts`.
- */
-export declare const DEFAULT_CRUD_FUNCTION_TYPE_VERBS: readonly string[];
-/**
- * Default factory function name that wraps CRUD function declarations and attaches the
- * `_apiDetails` metadata (`inputType`, `outputType`, `mcp.visibility`, `analytics`) consumed
- * by the MCP manifest builder. Defined in `packages/firebase-server/src/lib/nest/model/api.details.ts`.
- */
-export declare const DEFAULT_API_DETAILS_FACTORY_NAME: string;
 /**
  * Options for the require-api-details-for-crud-function rule.
  */
@@ -38,7 +23,7 @@ export interface FirebaseRequireApiDetailsForCrudFunctionRuleOptions {
 export interface FirebaseRequireApiDetailsForCrudFunctionRuleDefinition {
     readonly meta: {
         readonly type: 'problem';
-        readonly fixable: undefined;
+        readonly fixable: 'code';
         readonly docs: {
             readonly description: string;
             readonly recommended: boolean;
@@ -48,10 +33,12 @@ export interface FirebaseRequireApiDetailsForCrudFunctionRuleDefinition {
     };
     create(context: {
         options: FirebaseRequireApiDetailsForCrudFunctionRuleOptions[];
+        sourceCode: AstNode;
         report: (descriptor: {
             node: AstNode;
             messageId: string;
             data?: Record<string, string>;
+            fix?: (fixer: AstNode) => AstNode | AstNode[];
         }) => void;
     }): Record<string, (node: AstNode) => void>;
 }
@@ -69,6 +56,12 @@ export interface FirebaseRequireApiDetailsForCrudFunctionRuleDefinition {
  * initializer's `CallExpression` callee name. Type assertions (`as`, `<T>`) on the initializer
  * are unwrapped before the check.
  *
+ * Auto-fix: wraps the existing initializer as `withApiDetails({ fn: <initializer> })` (`inputType`
+ * is optional on the config, so the minimal wrap compiles) and — when the default factory is used
+ * and not already in scope — inserts `import { withApiDetails } from '@dereekb/firebase-server';`.
+ * The developer is still expected to add `inputType`; the companion `require-input-type-for-api-details`
+ * rule flags that follow-up where it matters.
+ *
  * @example
  * ```ts
  * // OK — wrapped, surfaces to MCP
@@ -76,7 +69,7 @@ export interface FirebaseRequireApiDetailsForCrudFunctionRuleDefinition {
  *   inputType, fn: async (req) => ({})
  * });
  *
- * // WARN — missingApiDetails, never reaches MCP
+ * // WARN — missingApiDetails, never reaches MCP (auto-fix wraps it)
  * export const fooDelete: FooDeleteModelFunction<X> = async (req) => {};
  * ```
  */

package/eslint/src/lib/require-input-type-for-api-details.rule.d.ts

@@ -0,0 +1,72 @@
+import { type AstNode } from './util';
+/**
+ * Options for the require-input-type-for-api-details rule.
+ */
+export interface FirebaseRequireInputTypeForApiDetailsRuleOptions {
+    /**
+     * Verb fragments that pair with the `ModelFunction` suffix to identify a CRUD function
+     * type annotation. Defaults to {@link DEFAULT_CRUD_FUNCTION_TYPE_VERBS}.
+     */
+    readonly typeVerbs?: readonly string[];
+    /**
+     * Factory function name whose config object must declare `inputType`. Defaults to {@link DEFAULT_API_DETAILS_FACTORY_NAME}.
+     */
+    readonly factoryName?: string;
+}
+/**
+ * ESLint rule definition for require-input-type-for-api-details.
+ */
+export interface FirebaseRequireInputTypeForApiDetailsRuleDefinition {
+    readonly meta: {
+        readonly type: 'problem';
+        readonly fixable: undefined;
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: Readonly<Record<string, string>>;
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        options: FirebaseRequireInputTypeForApiDetailsRuleOptions[];
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+        }) => void;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule that requires a CRUD function wrapped in `withApiDetails({ ... })` to declare an
+ * `inputType` on the config object. `inputType` drives the MCP tool input schema; without it the
+ * tool surfaces with no (or an auto-guessed) schema.
+ *
+ * The rule is purely syntactic and deliberately narrow to avoid false positives:
+ * - It only fires on declarators typed as a CRUD function (`On(?:Call)?<Verb>ModelFunction` or an
+ *   app-side `<Verb>ModelFunction` alias) whose initializer is already a `withApiDetails(...)` call.
+ *   The missing-wrapper case is owned by `require-api-details-for-crud-function`.
+ * - **Query** handlers are exempt — they consume standardized query/pagination params, not a
+ *   per-handler input type.
+ * - Handlers whose input generic is empty (`{}`) or absent are exempt — there is no meaningful input
+ *   schema to declare. (The input generic sits at index 1 for canonical `On...ModelFunction` names
+ *   and index 0 for app-side aliases — a syntactic heuristic keyed on the `On` prefix.)
+ * - Configs built with a spread (`{ ...base, fn }`) are skipped because the spread's contents cannot
+ *   be verified statically.
+ *
+ * There is no auto-fix (the rule cannot synthesize an `inputType` value). To intentionally omit
+ * `inputType`, use an inline `// eslint-disable-next-line` comment.
+ *
+ * @example
+ * ```ts
+ * // OK — declares inputType
+ * export const fooCreate: FooCreateModelFunction<CreateFooParams> = withApiDetails({
+ *   inputType: createFooParamsType, fn: async (req) => ({})
+ * });
+ *
+ * // WARN — missingInputType (non-empty input generic, not a Query)
+ * export const fooUpdate: FooUpdateModelFunction<UpdateFooParams> = withApiDetails({
+ *   fn: async (req) => {}
+ * });
+ * ```
+ */
+export declare const FIREBASE_REQUIRE_INPUT_TYPE_FOR_API_DETAILS_RULE: FirebaseRequireInputTypeForApiDetailsRuleDefinition;

package/eslint/src/lib/util.d.ts

@@ -105,3 +105,143 @@ export declare function getFunctionName(node: AstNode): Maybe<string>;
  * @returns The node to attach a `context.report` location to.
  */
 export declare function getFunctionNameNode(node: AstNode): AstNode;
+/**
+ * Default CRUD verb names that combine with the `ModelFunction` suffix to form a type-name
+ * pattern the api-details rules treat as a CRUD function declaration (e.g. `OnCallCreateModelFunction`,
+ * `DemoUpdateModelFunction`).
+ *
+ * Mirrors the verbs supported by `ModelFirebaseCrudFunctionConfigMap` — see
+ * `packages/firebase/src/lib/client/function/model.function.factory.ts`.
+ */
+export declare const DEFAULT_CRUD_FUNCTION_TYPE_VERBS: readonly string[];
+/**
+ * Default factory function name that wraps CRUD function declarations and attaches the
+ * `_apiDetails` metadata (`inputType`, `outputType`, `mcp.visibility`, `analytics`) consumed
+ * by the MCP manifest builder. Defined in `packages/firebase-server/src/lib/nest/model/api.details.ts`.
+ */
+export declare const DEFAULT_API_DETAILS_FACTORY_NAME: string;
+/**
+ * Property name on the `withApiDetails(...)` config object that declares the handler's input
+ * parameter type (consumed by the MCP manifest builder to generate the tool input schema).
+ */
+export declare const INPUT_TYPE_PROPERTY_NAME: string;
+/**
+ * Module the default api-details factory ({@link DEFAULT_API_DETAILS_FACTORY_NAME}) is exported
+ * from. Used by the require-api-details auto-fix to insert a missing import.
+ */
+export declare const API_DETAILS_IMPORT_MODULE: string;
+/**
+ * Unwraps `TSAsExpression` and `TSTypeAssertion` wrappers around an initializer so callers see the
+ * underlying expression (matches the helper in `require-complete-crud-function-config-map.rule.ts`).
+ *
+ * @param node - The AST node to unwrap.
+ * @returns The innermost wrapped expression, or `node` when no cast is present.
+ */
+export declare function unwrapTypeAssertion(node: AstNode): AstNode;
+/**
+ * Resolves the identifier name from a `TSTypeReference` annotation, when present.
+ *
+ * @param node - A `TSTypeReference` node (or anything else).
+ * @returns The identifier name when `node` is a TSTypeReference whose typeName is an Identifier; otherwise null.
+ */
+export declare function typeReferenceTypeName(node: AstNode): Maybe<string>;
+/**
+ * Resolves the type-argument nodes of a `TSTypeReference`, normalizing across `@typescript-eslint`
+ * versions (`typeArguments` in v6+, `typeParameters` in older releases).
+ *
+ * @param node - A `TSTypeReference` node (or anything else).
+ * @returns The generic argument nodes, or null when the reference has no type arguments.
+ */
+export declare function typeReferenceTypeArguments(node: AstNode): Maybe<AstNode[]>;
+/**
+ * Resolves the callee identifier name from a `CallExpression`, looking through both bare identifier
+ * callees (`withApiDetails(...)`) and member-expression callees (`api.withApiDetails(...)`).
+ *
+ * @param callee - The `CallExpression.callee` node.
+ * @returns The callee name when resolvable; otherwise null.
+ */
+export declare function callExpressionCalleeName(callee: AstNode): Maybe<string>;
+/**
+ * Determines whether the (already-unwrapped) initializer is a call to the configured api-details factory.
+ *
+ * @param initializer - The unwrapped initializer node.
+ * @param factoryName - The expected factory identifier name.
+ * @returns True when the initializer is a `CallExpression` whose callee resolves to `factoryName`.
+ */
+export declare function isApiDetailsCall(initializer: AstNode, factoryName: string): boolean;
+/**
+ * Returns the declarator's identifier name, when present.
+ *
+ * @param declaratorId - The `VariableDeclarator.id` node.
+ * @returns The identifier name, or null when the declarator binds a destructuring pattern.
+ */
+export declare function declaratorName(declaratorId: AstNode): Maybe<string>;
+/**
+ * Returns the CRUD verb fragment that `typeName` ends with — i.e. the `<Verb>` in a
+ * `<Verb>ModelFunction` suffix for one of the configured verbs (e.g. `OnCallCreateModelFunction` →
+ * `Create`, `DemoUpdateModelFunction` → `Update`).
+ *
+ * @param typeName - The type-reference identifier name.
+ * @param verbs - The allowed verb fragments.
+ * @returns The matched verb, or null when the suffix matches no recognized CRUD verb.
+ */
+export declare function matchedCrudFunctionVerb(typeName: string, verbs: Iterable<string>): Maybe<string>;
+/**
+ * Returns true when `typeName` ends with `<Verb>ModelFunction` for one of the configured verbs.
+ *
+ * @param typeName - The type-reference identifier name.
+ * @param verbs - The allowed verb fragments.
+ * @returns True when the suffix matches a recognized CRUD verb.
+ */
+export declare function isCrudFunctionTypeName(typeName: string, verbs: Iterable<string>): boolean;
+/**
+ * Resolves the input-parameter type-argument node from a CRUD function type reference.
+ *
+ * @param typeRef - The `TSTypeReference` annotation node.
+ * @param typeName - The resolved type-reference name (selects the generic position).
+ * @returns The input type-argument node, or null when absent.
+ */
+export declare function crudFunctionInputTypeArgNode(typeRef: AstNode, typeName: string): Maybe<AstNode>;
+/**
+ * Returns true when a CRUD function declares no meaningful input — either the input generic argument
+ * is absent or it is an empty object type literal (`{}`). Such handlers need no MCP input schema, so
+ * the require-input-type rule exempts them.
+ *
+ * @param typeRef - The `TSTypeReference` annotation node.
+ * @param typeName - The resolved type-reference name.
+ * @returns True when the input generic is empty or absent.
+ */
+export declare function isEmptyOrAbsentInputGeneric(typeRef: AstNode, typeName: string): boolean;
+/**
+ * Returns true when an `ObjectExpression` has an own (non-computed) property with the given name.
+ *
+ * @param objExpr - The `ObjectExpression` node.
+ * @param propName - The property name to look for.
+ * @returns True when a matching property is present.
+ */
+export declare function objectExpressionHasProperty(objExpr: AstNode, propName: string): boolean;
+/**
+ * Returns true when an `ObjectExpression` contains a spread element (`{ ...base }`), whose contents
+ * cannot be introspected statically.
+ *
+ * @param objExpr - The `ObjectExpression` node.
+ * @returns True when any property is a spread element.
+ */
+export declare function objectExpressionHasSpread(objExpr: AstNode): boolean;
+/**
+ * Returns the character offset at which an auto-fixer should insert a new import — the start of the
+ * first existing `ImportDeclaration`, or offset 0 when the file has no imports yet.
+ *
+ * @param program - The `Program` AST node.
+ * @returns The character offset for the import-insertion point.
+ */
+export declare function findImportInsertionOffset(program: AstNode): number;
+/**
+ * Returns true when the given identifier name is already in the module's top-level scope (imported
+ * or declared). Used by the require-api-details auto-fix to avoid inserting a duplicate import.
+ *
+ * @param program - The `Program` AST node.
+ * @param name - The identifier name to check.
+ * @returns True when an existing import or declaration brings `name` into scope.
+ */
+export declare function isFactoryNameInScope(program: AstNode, name: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/firebase",
-  "version": "13.12.0",
+  "version": "13.12.1",
   "sideEffects": false,
   "exports": {
     "./test": {
@@ -24,10 +24,10 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/util": "13.12.0",
-    "@dereekb/date": "13.12.0",
-    "@dereekb/model": "13.12.0",
-    "@dereekb/rxjs": "13.12.0",
+    "@dereekb/util": "13.12.1",
+    "@dereekb/date": "13.12.1",
+    "@dereekb/model": "13.12.1",
+    "@dereekb/rxjs": "13.12.1",
     "@firebase/rules-unit-testing": "5.0.0",
     "arktype": "^2.2.0",
     "date-fns": "^4.1.0",

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.12.0",
+  "version": "13.12.1",
   "peerDependencies": {
-    "@dereekb/date": "13.12.0",
-    "@dereekb/firebase": "13.12.0",
-    "@dereekb/model": "13.12.0",
-    "@dereekb/rxjs": "13.12.0",
-    "@dereekb/util": "13.12.0",
+    "@dereekb/date": "13.12.1",
+    "@dereekb/firebase": "13.12.1",
+    "@dereekb/model": "13.12.1",
+    "@dereekb/rxjs": "13.12.1",
+    "@dereekb/util": "13.12.1",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",