@dereekb/util 13.11.2 → 13.11.4

package/eslint/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@dereekb/util/eslint",
+  "version": "13.11.4",
+  "peerDependencies": {
+    "@typescript-eslint/utils": "8.59.0"
+  },
+  "devDependencies": {
+    "@typescript-eslint/parser": "8.59.0",
+    "eslint": "9.39.4"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "module": "./index.esm.js",
+      "types": "./index.d.ts",
+      "import": "./index.cjs.mjs",
+      "default": "./index.cjs.js"
+    }
+  },
+  "module": "./index.esm.js",
+  "main": "./index.cjs.js",
+  "types": "./index.d.ts"
+}

package/eslint/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib';

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

@@ -0,0 +1,101 @@
+/**
+ * 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: JsdocCommentInfo | null;
+    /**
+     * 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: AstNode | null;
+    /**
+     * 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;
+/**
+ * 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 {};

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

@@ -0,0 +1,3 @@
+export { utilRequireNoSideEffectsRule, type UtilRequireNoSideEffectsRuleOptions, type UtilRequireNoSideEffectsRuleDefinition } from './require-no-side-effects.rule';
+export { utilPreferNoSideEffectsInJsdocRule, type UtilPreferNoSideEffectsInJsdocRuleDefinition } from './prefer-no-side-effects-in-jsdoc.rule';
+export { utilEslintPlugin, type UtilEslintPlugin } from './plugin';

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

@@ -0,0 +1,18 @@
+import { type UtilRequireNoSideEffectsRuleDefinition } from './require-no-side-effects.rule';
+import { type UtilPreferNoSideEffectsInJsdocRuleDefinition } from './prefer-no-side-effects-in-jsdoc.rule';
+/**
+ * ESLint plugin interface for @dereekb/util rules.
+ */
+export interface UtilEslintPlugin {
+    readonly rules: {
+        readonly 'require-no-side-effects': UtilRequireNoSideEffectsRuleDefinition;
+        readonly 'prefer-no-side-effects-in-jsdoc': UtilPreferNoSideEffectsInJsdocRuleDefinition;
+    };
+}
+/**
+ * ESLint plugin for @dereekb/util rules.
+ *
+ * Register as a plugin in your flat ESLint config, then enable individual rules
+ * under the chosen plugin prefix (e.g. 'dereekb-util/require-no-side-effects').
+ */
+export declare const utilEslintPlugin: UtilEslintPlugin;

package/eslint/src/lib/prefer-no-side-effects-in-jsdoc.rule.d.ts

@@ -0,0 +1,50 @@
+type AstNode = any;
+/**
+ * ESLint rule definition for prefer-no-side-effects-in-jsdoc.
+ */
+export interface UtilPreferNoSideEffectsInJsdocRuleDefinition {
+    readonly meta: {
+        readonly type: 'suggestion';
+        readonly fixable: 'code';
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: {
+            readonly preferJsdocPlacement: string;
+            readonly missingImplAnnotationOverloaded: string;
+        };
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        options: unknown[];
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+            fix?: (fixer: AstNode) => AstNode | AstNode[];
+        }) => void;
+        sourceCode: AstNode;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule that flags functions with both a JSDoc block and a separate
+ * `// @__NO_SIDE_EFFECTS__` (or block-comment equivalent) line comment between
+ * the JSDoc and the declaration. Auto-fix migrates the annotation into the JSDoc
+ * (last tag before the closing) and removes the standalone comment, since the
+ * JSDoc form is the workspace's preferred placement.
+ *
+ * Unlike `require-no-side-effects`, this rule does not require the function to
+ * be tagged as a factory — it triggers purely on the presence of an existing
+ * line-comment annotation alongside a JSDoc, so it can sweep all 688 historical
+ * annotations through `eslint --fix`.
+ *
+ * Overloaded functions are a special case: TypeScript erases overload signatures
+ * during emit, so a JSDoc tag on the first overload doesn't reach the bundled JS.
+ * The `// @__NO_SIDE_EFFECTS__` line comment immediately above the implementation
+ * is the only annotation that survives compilation, so this rule preserves it
+ * (and treats line comments between overloads — but not directly above the impl —
+ * as ordinary orphans to migrate).
+ */
+export declare const utilPreferNoSideEffectsInJsdocRule: UtilPreferNoSideEffectsInJsdocRuleDefinition;
+export {};

package/eslint/src/lib/require-no-side-effects.rule.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Options for the require-no-side-effects rule.
+ */
+export interface UtilRequireNoSideEffectsRuleOptions {
+    /**
+     * When true, also flag functions whose names match the factory naming patterns
+     * in addition to JSDoc-tag detection.
+     */
+    readonly checkNamePatterns?: boolean;
+    /**
+     * Additional name pattern source strings (compiled to RegExp) when `checkNamePatterns` is true.
+     */
+    readonly additionalNamePatterns?: readonly string[];
+}
+type AstNode = any;
+/**
+ * ESLint rule definition for require-no-side-effects.
+ */
+export interface UtilRequireNoSideEffectsRuleDefinition {
+    readonly meta: {
+        readonly type: 'suggestion';
+        readonly fixable: 'code';
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: {
+            readonly missingNoSideEffectsJsdoc: string;
+            readonly missingJsdocForFactory: string;
+            readonly missingImplAnnotationOverloaded: string;
+        };
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        options: UtilRequireNoSideEffectsRuleOptions[];
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+            fix?: (fixer: AstNode) => AstNode | AstNode[];
+        }) => void;
+        sourceCode: AstNode;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule requiring the side-effect-free annotation on every factory function — that is,
+ * declarations carrying the `@dbxUtilKind factory` JSDoc tag (and optionally functions matching
+ * factory name patterns). The rule guarantees the marker reaches the bundled JavaScript so
+ * esbuild/rollup can drop unused calls during tree-shaking.
+ *
+ * Behavior:
+ *
+ * - **Single-signature functions:** the JSDoc above the declaration is preserved during emit, so
+ *   the rule simply requires `@__NO_SIDE_EFFECTS__` inside that JSDoc.
+ *
+ * - **Overloaded functions:** TypeScript erases overload signatures during emit, so a JSDoc tag
+ *   placed only on the first overload is dropped from the bundled JS. The rule additionally requires
+ *   either (a) a `// @__NO_SIDE_EFFECTS__` line comment immediately above the implementation, or
+ *   (b) a JSDoc with the tag attached directly to the implementation. Auto-fix inserts the line
+ *   comment alongside the JSDoc tag so consumer-facing docs and the bundler annotation stay in sync.
+ *
+ * Auto-fix also removes any redundant standalone-comment annotations between the JSDoc and the
+ * declaration (other than the required impl-leading line comment on overloaded functions), and
+ * when no JSDoc is present, creates a minimal one carrying both tags.
+ */
+export declare const utilRequireNoSideEffectsRule: UtilRequireNoSideEffectsRuleDefinition;
+export {};

package/fetch/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@dereekb/util/fetch",
-  "version": "13.11.2",
+  "version": "13.11.4",
   "peerDependencies": {
-    "@dereekb/util": "13.11.2",
+    "@dereekb/util": "13.11.4",
     "make-error": "^1.3.6",
     "fast-content-type-parse": "^3.0.0"
   },