@dereekb/firebase 13.11.18 → 13.12.0

package/src/lib/common/auth/oidc/oidc.d.ts

@@ -12,24 +12,26 @@ export declare const READ_MODEL_OIDC_SCOPE: "model.read";
 export declare const UPDATE_MODEL_OIDC_SCOPE: "model.update";
 export declare const DELETE_MODEL_OIDC_SCOPE: "model.delete";
 export declare const QUERY_MODEL_OIDC_SCOPE: "model.query";
+export declare const INVOKE_MODEL_OIDC_SCOPE: "model.invoke";
 export type CreateModelOidcScope = typeof CREATE_MODEL_OIDC_SCOPE;
 export type ReadModelOidcScope = typeof READ_MODEL_OIDC_SCOPE;
 export type UpdateModelOidcScope = typeof UPDATE_MODEL_OIDC_SCOPE;
 export type DeleteModelOidcScope = typeof DELETE_MODEL_OIDC_SCOPE;
 export type QueryModelOidcScope = typeof QUERY_MODEL_OIDC_SCOPE;
+export type InvokeModelOidcScope = typeof INVOKE_MODEL_OIDC_SCOPE;
 /**
- * Canonical CRUD scopes enforced on the `callModel` API.
+ * Canonical CRUD + invoke scopes enforced on the `callModel` API.
  *
  * Each scope corresponds 1:1 to a {@link KnownOnCallFunctionType}; see
  * {@link CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE}.
  */
-export declare const CALL_MODEL_OIDC_SCOPES: readonly ["model.create", "model.read", "model.update", "model.delete", "model.query"];
+export declare const CALL_MODEL_OIDC_SCOPES: readonly ["model.create", "model.read", "model.update", "model.delete", "model.query", "model.invoke"];
 /**
- * Union of the five canonical callModel CRUD scope strings.
+ * Union of the six canonical callModel scope strings (CRUDQ + invoke).
  */
-export type CallModelOidcScope = CreateModelOidcScope | ReadModelOidcScope | UpdateModelOidcScope | DeleteModelOidcScope | QueryModelOidcScope;
+export type CallModelOidcScope = CreateModelOidcScope | ReadModelOidcScope | UpdateModelOidcScope | DeleteModelOidcScope | QueryModelOidcScope | InvokeModelOidcScope;
 /**
- * Maps each known CRUD call type to the scope an OIDC token must carry to invoke it.
+ * Maps each known call type to the scope an OIDC token must carry to invoke it.
  */
 export declare const CALL_MODEL_OIDC_SCOPE_FOR_CALL_TYPE: Readonly<Record<KnownOnCallFunctionType, CallModelOidcScope>>;
 /**

package/src/lib/common/model/function.d.ts

@@ -3,8 +3,11 @@ import { type DocumentReferenceRef } from '../firestore/reference';
 import { type FirestoreModelKey, type FirestoreModelType, type FirestoreModelTypeRef } from '../firestore/collection/collection';
 /**
  * Standard CRUD call types used by the `callModel` Firebase function pattern.
+ *
+ * CRUDQ + I: 'invoke' covers side-effecting RPC-style operations that don't fit any CRUD verb
+ * (e.g. regenerate-thumbnails, resync-with-external, recompute-index).
  */
-export type KnownOnCallFunctionType = 'create' | 'read' | 'update' | 'delete' | 'query';
+export type KnownOnCallFunctionType = 'create' | 'read' | 'update' | 'delete' | 'query' | 'invoke';
 /**
  * Call type identifier — one of the standard CRUD types or a custom string.
  */
@@ -74,6 +77,10 @@ export declare const onCallDeleteModelParams: OnCallTypeModelParamsFunction;
  * Pre-configured OnCallTypedModelParamsFunctions for 'query'
  */
 export declare const onCallQueryModelParams: OnCallTypeModelParamsFunction;
+/**
+ * Pre-configured OnCallTypedModelParamsFunctions for 'invoke'
+ */
+export declare const onCallInvokeModelParams: OnCallTypeModelParamsFunction;
 /**
  * Key used on the front-end and backend that refers to the call function.
  */
@@ -98,6 +105,10 @@ export type OnCallDeleteModelParams<T = unknown> = OnCallTypedModelParams<T>;
  * OnCallTypedModelParams for Query calls.
  */
 export type OnCallQueryModelParams<T extends OnCallQueryModelRequestParams = OnCallQueryModelRequestParams> = OnCallTypedModelParams<T>;
+/**
+ * OnCallTypedModelParams for Invoke calls.
+ */
+export type OnCallInvokeModelParams<T = unknown> = OnCallTypedModelParams<T>;
 /**
  * Default maximum items per page for query operations.
  */

package/src/lib/model/notification/notification.d.ts

@@ -91,6 +91,7 @@ export declare const notificationUserIdentity: import("../..").RootFirestoreMode
  * @see `NotificationServerActions.updateNotificationUser` in `@dereekb/firebase-server/model` for server-side sync logic
  *
  * @dbxModel
+ * @dbxModelRead system
  */
 export interface NotificationUser extends UserRelated, UserRelatedById {
     /**
@@ -194,6 +195,7 @@ export declare const NOTIFICATION_SUMMARY_EMBEDDED_NOTIFICATION_ITEM_MESSAGE_MAX
  * Implements {@link InitializedNotificationModel} — requires server-side initialization to populate the owner (`o`) field.
  *
  * @dbxModel
+ * @dbxModelRead system
  * @dbxModelArchetype root-singleton-aggregate
  * @dbxModelArchetype composite-key-root
  * @dbxModelCompositeKey from=* encoding=two-way
@@ -291,6 +293,7 @@ export declare const notificationBoxIdentity: import("../..").RootFirestoreModel
  * @see `NotificationServerActions.createNotificationBox` in `@dereekb/firebase-server/model` for creation logic
  *
  * @dbxModel
+ * @dbxModelRead system
  * @dbxModelArchetype composite-key-root
  * @dbxModelCompositeKey from=* encoding=two-way
  */
@@ -578,6 +581,7 @@ export interface NotificationSendCheckpoints {
  * @see `NotificationServerActions.sendQueuedNotifications` in `@dereekb/firebase-server/model` for the send pipeline
  *
  * @dbxModel
+ * @dbxModelRead system
  */
 export interface Notification extends NotificationSendFlags, NotificationSendCheckpoints {
     /**
@@ -737,6 +741,7 @@ export declare const NOTIFICATION_WEEK_NOTIFICATION_ITEM_LIMIT = 5000;
  * Used for historical browsing of past notifications per box.
  *
  * @dbxModel
+ * @dbxModelRead system
  */
 export interface NotificationWeek {
     /**
@@ -837,6 +842,7 @@ export declare const NOTIFICATION_LOGGED_EVENT_DAY_ITEM_CONVERTER: PagedItemConv
  * items are distributed across pages by {@link makePagedItemFirestoreCollection}.
  *
  * @dbxModel
+ * @dbxModelRead system
  */
 export interface NotificationLoggedEventDay {
     /**

package/src/lib/model/oidcmodel/oidcmodel.d.ts

@@ -46,6 +46,7 @@ export declare const OIDC_ENTRY_CLIENT_TYPE: OidcEntryType;
  * (used primarily for Client entries so users can query their own registered OAuth clients).
  *
  * @dbxModel
+ * @dbxModelRead permissions
  * @dbxModelArchetype reference-registry hasChildren=false,hasInheritance=false
  */
 export interface OidcEntry {

package/src/lib/model/storagefile/storagefile.api.d.ts

@@ -2,9 +2,9 @@ import { type Type } from 'arktype';
 import { type TargetModelParams, type OnCallCreateModelResult, type FirestoreModelKey } from '../../common';
 import { type ModelFirebaseCrudFunction, type FirebaseFunctionTypeConfigMap, type ModelFirebaseCrudFunctionConfigMap, type ModelFirebaseFunctionMap, type ModelFirebaseCreateFunction } from '../../client';
 import { type StorageFileSignedDownloadUrl, type StorageFileTypes } from './storagefile';
-import { type StorageFileKey, type StorageFileId } from './storagefile.id';
+import { type StorageFileKey, type StorageFileId, type StorageFilePurpose } from './storagefile.id';
 import { type StorageBucketId, type StoragePath, type StorageSlashPath } from '../../common/storage';
-import { type ContentDispositionString, type ContentTypeMimeType, type Maybe, type Milliseconds, type UnixDateTimeSecondsNumber } from '@dereekb/util';
+import { type ContentDispositionString, type ContentTypeMimeType, type Maybe, type Milliseconds, type SlashPath, type SlashPathFile, type UnixDateTimeMillisecondsNumber, type UnixDateTimeSecondsNumber } from '@dereekb/util';
 import { type SendNotificationResult } from '../notification/notification.api';
 export declare const DOWNLOAD_MULTIPLE_STORAGE_FILES_MIN_FILES = 1;
 export declare const DOWNLOAD_MULTIPLE_STORAGE_FILES_MAX_FILES = 50;
@@ -187,6 +187,115 @@ export interface DownloadMultipleStorageFilesResult {
     readonly success: DownloadMultipleStorageFileSuccessItem[];
     readonly errors: DownloadMultipleStorageFileErrorItem[];
 }
+/**
+ * Lower bound for caller-supplied `expiresInMs` on signed-upload-url generation.
+ *
+ * Anything shorter than 30 seconds is unrealistic for a caller to pick up a
+ * URL, perform the PUT, and acknowledge before the URL expires.
+ */
+export declare const CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_MIN_EXPIRES_IN_MS: Milliseconds;
+/**
+ * Upper bound for caller-supplied `expiresInMs` on signed-upload-url generation.
+ *
+ * 10 minutes is the longest acceptable window for a one-shot upload URL. Any
+ * legitimate caller should be uploading within this window; longer windows
+ * increase the blast radius if the URL leaks.
+ */
+export declare const CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_MAX_EXPIRES_IN_MS: Milliseconds;
+/**
+ * Default `expiresInMs` applied when the caller does not supply one.
+ */
+export declare const DEFAULT_CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_EXPIRES_IN_MS: Milliseconds;
+/**
+ * Maximum length of a caller-supplied filename. Enforced both at the ArkType
+ * layer and again by the handler's sanitizer.
+ */
+export declare const CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_MAX_FILENAME_LENGTH = 200;
+/**
+ * Parameters for creating a short-lived signed PUT URL for a StorageFile upload.
+ *
+ * The resulting URL is restricted to a specific {@link StorageFilePurpose}, MIME
+ * type, and file size and lands the bytes inside the authenticated caller's
+ * `/uploads/u/{uid}/...` namespace. Once uploaded, the existing
+ * `StorageFileInitializeFromUploadService` flow picks the file up and creates
+ * the matching `StorageFile` document.
+ */
+export interface CreateStorageFileSignedUploadUrlParams {
+    /**
+     * The {@link StorageFilePurpose} to upload as. Must be supported by the
+     * app's signed-upload-url policy registry. The chosen policy decides where
+     * the file lands and which content-types/sizes are allowed.
+     */
+    readonly purpose: StorageFilePurpose;
+    /**
+     * The MIME type the client intends to PUT. Validated against the policy's
+     * `allowedMimeTypes` and signed into the URL so GCS rejects any PUT with a
+     * different `Content-Type`.
+     */
+    readonly contentType: ContentTypeMimeType;
+    /**
+     * Filename to place inside the policy's upload folder. Required when the
+     * policy has `requiresFilenameInput: true`. Sanitized server-side — must not
+     * contain `/`, `..`, or NUL bytes; capped at
+     * {@link CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_MAX_FILENAME_LENGTH} chars.
+     */
+    readonly filename?: Maybe<SlashPathFile>;
+    /**
+     * Client-declared size in bytes for the upload. Validated against the
+     * policy's `maxFileSizeBytes` cap. The storage rules independently enforce
+     * the same cap via `request.resource.size`.
+     */
+    readonly fileSizeBytes: number;
+    /**
+     * Lifetime of the signed URL in milliseconds. Clamped to
+     * [{@link CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_MIN_EXPIRES_IN_MS},
+     * {@link CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_MAX_EXPIRES_IN_MS}].
+     * Defaults to {@link DEFAULT_CREATE_STORAGE_FILE_SIGNED_UPLOAD_URL_EXPIRES_IN_MS}
+     * when omitted.
+     */
+    readonly expiresInMs?: Maybe<Milliseconds>;
+}
+export declare const createStorageFileSignedUploadUrlParamsType: Type<CreateStorageFileSignedUploadUrlParams>;
+/**
+ * Result of creating a signed upload URL.
+ *
+ * The caller PUTs the file bytes to {@link uploadUrl} with the headers in
+ * {@link requiredHeaders}. The existing initializer flow then picks the file
+ * up from {@link uploadPath} and creates the StorageFile document.
+ *
+ * `modelKeys` is intentionally empty — minting the URL does not create a
+ * StorageFile document; the document is created later by the upload-complete
+ * pipeline.
+ */
+export interface CreateStorageFileSignedUploadUrlResult extends OnCallCreateModelResult {
+    readonly modelKeys: [];
+    /**
+     * Short-lived, content-type-pinned PUT URL.
+     */
+    readonly uploadUrl: string;
+    /**
+     * The full storage path the URL writes to (inside `/uploads/u/{uid}/...`).
+     * Returned so the caller can confirm where the file landed.
+     */
+    readonly uploadPath: SlashPath;
+    /**
+     * Unix millisecond timestamp at which the URL expires.
+     */
+    readonly expiresAt: UnixDateTimeMillisecondsNumber;
+    /**
+     * Headers the caller MUST send on the PUT for the signature to validate.
+     * At minimum, the `content-type` matches the signed value.
+     */
+    readonly requiredHeaders: Readonly<Record<string, string>>;
+    /**
+     * Echo of the policy's `maxFileSizeBytes` cap, for caller-side validation.
+     */
+    readonly maxFileSizeBytes: number;
+    /**
+     * The resolved {@link StorageFilePurpose}.
+     */
+    readonly purpose: StorageFilePurpose;
+}
 /**
  * Used for creating or initializing a new StorageFileGroup for a StorageFile.
  *
@@ -274,6 +383,7 @@ export type StorageFileModelCrudFunctionsConfig = {
             _: CreateStorageFileParams;
             fromUpload: InitializeStorageFileFromUploadParams;
             allFromUpload: [InitializeAllStorageFilesFromUploadsParams, InitializeAllStorageFilesFromUploadsResult];
+            signedUploadUrl: [CreateStorageFileSignedUploadUrlParams, CreateStorageFileSignedUploadUrlResult];
         };
         update: {
             _: UpdateStorageFileParams;
@@ -308,6 +418,7 @@ export declare abstract class StorageFileFunctions implements ModelFirebaseFunct
             create: ModelFirebaseCreateFunction<CreateStorageFileParams, OnCallCreateModelResult>;
             fromUpload: ModelFirebaseCreateFunction<InitializeStorageFileFromUploadParams, OnCallCreateModelResult>;
             allFromUpload: ModelFirebaseCrudFunction<InitializeAllStorageFilesFromUploadsParams, InitializeAllStorageFilesFromUploadsResult>;
+            signedUploadUrl: ModelFirebaseCreateFunction<CreateStorageFileSignedUploadUrlParams, CreateStorageFileSignedUploadUrlResult>;
         };
         updateStorageFile: {
             update: ModelFirebaseCrudFunction<UpdateStorageFileParams>;

package/src/lib/model/storagefile/storagefile.d.ts

@@ -263,6 +263,7 @@ export type StorageFileDownloadUrl = StorageFilePublicDownloadUrl | StorageFileS
  *
  * @template M - type of the arbitrary metadata stored in the `d` field
  * @dbxModel
+ * @dbxModelRead permissions
  * @dbxModelArchetype root-entity
  * @dbxModelArchetype state-machine-item
  */
@@ -502,6 +503,7 @@ export declare const storageFileGroupEmbeddedFile: import("../..").FirestoreSubO
  * the `s` (needs sync) flag is set on creation and cleared once initialized.
  *
  * @dbxModel
+ * @dbxModelRead admin-only
  */
 export interface StorageFileGroup extends InitializedStorageFileModel {
     /**

package/src/lib/model/storagefile/storagefile.upload.d.ts

@@ -1,6 +1,7 @@
-import { type FactoryWithRequiredInput, type Maybe, type SlashPath } from '@dereekb/util';
+import { type ContentTypeMimeType, type FactoryWithRequiredInput, type Maybe, type SlashPath, type SlashPathFile } from '@dereekb/util';
 import { type StoragePath } from '../../common/storage/storage';
 import { type FirebaseAuthUserId } from '../../common';
+import { type StorageFilePurpose } from './storagefile.id';
 /**
  * Root path for all uploaded files in Firebase Storage.
  *
@@ -97,3 +98,34 @@ export type UploadedFileTypeIdentifier = string;
  * - `permanent_initializer_failure` — the initializer failed permanently; the file should be deleted
  */
 export type StorageFileInitializeFromUploadResultType = 'success' | 'no_determiner_match' | 'no_initializer_configured' | 'initializer_error' | 'permanent_initializer_failure';
+/**
+ * Input passed to {@link StorageFilePurposeUploadPolicy.buildUploadPath} when
+ * computing the upload destination for a signed-upload-url.
+ */
+export interface StorageFilePurposeUploadPolicyBuildPathInput {
+    readonly uid: FirebaseAuthUserId;
+    readonly filename?: Maybe<SlashPathFile>;
+}
+/**
+ * Per-purpose constraints for generating short-lived signed upload URLs.
+ *
+ * Implementations are kept in app-level registries (e.g.
+ * `STORAGE_FILE_PURPOSE_UPLOAD_POLICIES` in demo-firebase) and wired into the
+ * server-action context so the `createStorageFileSignedUploadUrl` action can
+ * resolve the policy by purpose at request time.
+ *
+ * The policy ensures the URL it signs targets a path and content-type that
+ * both `storage.rules` and the matching `StorageFileInitializeFromUploadService`
+ * initializer accept.
+ */
+export interface StorageFilePurposeUploadPolicy {
+    readonly purpose: StorageFilePurpose;
+    readonly allowedMimeTypes: readonly ContentTypeMimeType[];
+    readonly maxFileSizeBytes: number;
+    readonly buildUploadPath: (input: StorageFilePurposeUploadPolicyBuildPathInput) => SlashPath;
+    /**
+     * When true, the caller MUST provide a filename for `buildUploadPath`.
+     * When false (e.g. avatar), the path is derived solely from the uid.
+     */
+    readonly requiresFilenameInput: boolean;
+}

package/src/lib/model/system/system.d.ts

@@ -60,6 +60,7 @@ export type SystemStateStoredData = Record<string, any>;
  *
  * @template T - shape of the stored data record
  * @dbxModel
+ * @dbxModelRead system
  * @dbxModelArchetype system-state-singleton
  */
 export interface SystemState<T extends SystemStateStoredData = SystemStateStoredData> {

package/test/index.cjs.js

@@ -1471,12 +1471,10 @@ function _is_native_reflect_construct$4() {
 }(firebase.AbstractFirestoreDocument);
 /**
  * Firestore collection path name.
- */ // eslint-disable-next-line @typescript-eslint/naming-convention -- camelCase chosen to match neighboring mock exports in this test fixture
-var MOCK_ITEM_USER_COLLECTION_NAME = 'mockItemUser';
+ */ var MOCK_ITEM_USER_COLLECTION_NAME = 'mockItemUser';
 /**
  * Default document identifier used for MockItemUser in tests.
- */ // eslint-disable-next-line @typescript-eslint/naming-convention -- camelCase chosen to match neighboring mock exports in this test fixture
-var MOCK_ITEM_USER_IDENTIFIER = '0';
+ */ var MOCK_ITEM_USER_IDENTIFIER = '0';
 /**
  * Used to build a FirestoreDataConverter. Fields are configured via configuration. See the SnapshotConverterFunctions for more info.
  */ var mockItemUserConverter = firebase.snapshotConverterFunctions({

package/test/index.esm.js

@@ -1469,12 +1469,10 @@ function _is_native_reflect_construct$4() {
 }(AbstractFirestoreDocument);
 /**
  * Firestore collection path name.
- */ // eslint-disable-next-line @typescript-eslint/naming-convention -- camelCase chosen to match neighboring mock exports in this test fixture
-var MOCK_ITEM_USER_COLLECTION_NAME = 'mockItemUser';
+ */ var MOCK_ITEM_USER_COLLECTION_NAME = 'mockItemUser';
 /**
  * Default document identifier used for MockItemUser in tests.
- */ // eslint-disable-next-line @typescript-eslint/naming-convention -- camelCase chosen to match neighboring mock exports in this test fixture
-var MOCK_ITEM_USER_IDENTIFIER = '0';
+ */ var MOCK_ITEM_USER_IDENTIFIER = '0';
 /**
  * Used to build a FirestoreDataConverter. Fields are configured via configuration. See the SnapshotConverterFunctions for more info.
  */ var mockItemUserConverter = snapshotConverterFunctions({

package/test/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/firebase/test",
-  "version": "13.11.18",
+  "version": "13.12.0",
   "peerDependencies": {
-    "@dereekb/date": "13.11.18",
-    "@dereekb/firebase": "13.11.18",
-    "@dereekb/model": "13.11.18",
-    "@dereekb/rxjs": "13.11.18",
-    "@dereekb/util": "13.11.18",
+    "@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",
     "@firebase/rules-unit-testing": "5.0.0",
     "date-fns": "^4.1.0",
     "firebase": "^12.12.1",

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

@@ -1,112 +0,0 @@
-import type { Maybe } from '@dereekb/util';
-/**
- * The bundler hint string that marks a function call as side-effect-free.
- */
-export declare const NO_SIDE_EFFECTS_TAG = "@__NO_SIDE_EFFECTS__";
-type AstNode = any;
-export interface JsdocCommentInfo {
-    readonly node: AstNode;
-    readonly text: string;
-    readonly hasNoSideEffects: boolean;
-}
-export interface FunctionLeadingContext {
-    readonly jsdoc: Maybe<JsdocCommentInfo>;
-    /**
-     * Adjacent `@__NO_SIDE_EFFECTS__` line/block comments that should be migrated into the JSDoc
-     * and removed. Excludes the implementation-leading annotation on overloaded functions, which
-     * is tracked separately by {@link implLineComment} because it must be preserved.
-     */
-    readonly orphanLineComments: readonly AstNode[];
-    /**
-     * True when this implementation is preceded by sibling overload signatures (`TSDeclareFunction`
-     * statements with the same name).
-     */
-    readonly hasOverloads: boolean;
-    /**
-     * The `@__NO_SIDE_EFFECTS__` line/block comment immediately above the implementation
-     * declaration when the function has overloads. TypeScript erases overload signatures during
-     * emit, so JSDoc placed only on the first overload is dropped from the bundled JS — the
-     * line comment directly above the implementation is what survives and reaches the bundler.
-     *
-     * `null` when the function is single-signature (the line comment is then a removable orphan)
-     * or when no such comment is present.
-     */
-    readonly implLineComment: Maybe<AstNode>;
-    /**
-     * True when the implementation will carry the `@__NO_SIDE_EFFECTS__` annotation in the emitted
-     * JavaScript:
-     *
-     * - Single-signature: true when the (only) JSDoc carries the tag.
-     * - Overloaded: true when a line/block comment with the tag sits immediately above the
-     *   implementation, OR the implementation has its own JSDoc carrying the tag.
-     *
-     * This is the signal upstream packages need so esbuild/rollup can tree-shake unused calls.
-     */
-    readonly implHasSurvivingAnnotation: boolean;
-    /**
-     * The first statement in the overload chain (i.e. the first overload's export wrapper, or the
-     * implementation itself when there are no overloads). Use this as the insertion anchor when
-     * creating a brand-new JSDoc for the function, since docs conventionally live on the first
-     * overload rather than the implementation.
-     */
-    readonly chainStartStatement: AstNode;
-}
-/**
- * Returns true if the given comment text contains the @__NO_SIDE_EFFECTS__ marker.
- *
- * @param text - The comment body text (without the `/*` and `*\/` delimiters).
- * @returns True when the marker substring is present.
- */
-export declare function commentContainsNoSideEffects(text: string): boolean;
-/**
- * Returns the leading whitespace (column indent) of the line containing the given offset.
- *
- * @param sourceText - The full source text being inspected.
- * @param offset - A character offset into `sourceText` indicating the line of interest.
- * @returns The whitespace prefix (spaces/tabs) of that line.
- */
-export declare function getLineIndent(sourceText: string, offset: number): string;
-/**
- * Returns the outermost statement node for a FunctionDeclaration — its `ExportNamedDeclaration`
- * or `ExportDefaultDeclaration` parent if exported, otherwise the declaration itself. This is the
- * node ESLint attaches leading comments to.
- *
- * @param node - The FunctionDeclaration AST node.
- * @returns The statement node ESLint attaches leading comments to.
- */
-export declare function getStatementAnchor(node: AstNode): AstNode;
-/**
- * Returns the JSDoc Block comment immediately preceding `anchor`, or `null` when
- * the anchor has no JSDoc leader. Used by the `@dbx<Family>` companion-tag rules
- * to locate the tagged declaration's documentation.
- *
- * @param sourceCode - The ESLint `SourceCode` object.
- * @param anchor - The statement-level node ESLint attaches leading comments to.
- * @returns The JSDoc block comment, or null when none is present.
- */
-export declare function leadingJsdocFor(sourceCode: AstNode, anchor: AstNode): Maybe<AstNode>;
-/**
- * Walks backward from the implementation FunctionDeclaration through any overload signatures
- * with the same name, collecting:.
- *
- * - The leading JSDoc block (preferring the one attached to the **first** overload, since that's
- *   where the function's documentation conventionally lives).
- * - All orphan `@__NO_SIDE_EFFECTS__` line/block comments encountered between overloads or
- *   between the last overload and the implementation.
- *
- * This handles the common pattern:
- *
- * ```ts
- * \/\*\* doc \*\/
- * export function foo(a: number): number;
- * export function foo(a: string): string;
- * \/\/ \@__NO_SIDE_EFFECTS__
- * export function foo(a: any) { ... }
- * ```
- *
- * @param sourceCode - The ESLint `SourceCode` object used to read leading comments.
- * @param implNode - The implementation FunctionDeclaration node.
- * @returns The leading JSDoc (if any) and any orphan side-effect annotation comments.
- */
-export declare function findFunctionLeadingContext(sourceCode: AstNode, implNode: AstNode): FunctionLeadingContext;
-export {};