@dereekb/util 13.11.14 → 13.11.15

package/eslint/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dereekb/util/eslint",
-  "version": "13.11.14",
+  "version": "13.11.15",
   "peerDependencies": {
-    "@typescript-eslint/utils": "8.59.0"
+    "@typescript-eslint/utils": "8.59.3"
   },
   "devDependencies": {
-    "@typescript-eslint/parser": "8.59.0",
-    "eslint": "9.39.4"
+    "@typescript-eslint/parser": "8.59.3",
+    "eslint": "10.4.0"
   },
   "exports": {
     "./package.json": "./package.json",

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

@@ -1,3 +1,4 @@
+import type { Maybe } from '@dereekb/util';
 /**
  * The bundler hint string that marks a function call as side-effect-free.
  */
@@ -9,7 +10,7 @@ export interface JsdocCommentInfo {
     readonly hasNoSideEffects: boolean;
 }
 export interface FunctionLeadingContext {
-    readonly jsdoc: JsdocCommentInfo | null;
+    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
@@ -30,7 +31,7 @@ export interface FunctionLeadingContext {
      * `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;
+    readonly implLineComment: Maybe<AstNode>;
     /**
      * True when the implementation will carry the `@__NO_SIDE_EFFECTS__` annotation in the emitted
      * JavaScript:
@@ -74,9 +75,19 @@ export declare function getLineIndent(sourceText: string, offset: number): strin
  * @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:
+ * 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).

package/eslint/src/lib/dbx-tag-families.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Shared helpers for the `@dbx<Family>` companion-tag ESLint rules. Mirrors the
+ * scanner schemas in `packages/dbx-components-mcp/src/scan/*-extract.ts` so
+ * violations surface at lint time instead of at manifest-regeneration time.
+ *
+ * Each per-family rule supplies a {@link DbxTagFamilySpec} describing which
+ * companions are required/optional, what value format each accepts, and which
+ * messageId to emit when a check fails. The rule body itself only wires the
+ * visitors and message map; all value-format validation lives here.
+ */
+import type { Maybe } from '@dereekb/util';
+import { type ParsedJsdoc, type ParsedJsdocTag } from './jsdoc-parser';
+interface AstNode {
+    readonly type: string;
+    [key: string]: any;
+}
+/**
+ * Kebab-case slug pattern: lowercase letters/digits, words separated by single hyphens,
+ * starts with a letter. Used to validate slug/related/skill-ref values.
+ */
+export declare const KEBAB_SLUG_PATTERN: RegExp;
+/**
+ * Pascal-case TypeScript identifier pattern (starts uppercase). Used for model
+ * identifiers and other `<ModelName>` style tag values.
+ */
+export declare const PASCAL_IDENTIFIER_PATTERN: RegExp;
+/**
+ * Discriminated description of how a companion tag's value should be parsed
+ * and validated. The shared checker dispatches on `kind`.
+ */
+export type DbxTagFormat = {
+    readonly kind: 'marker';
+} | {
+    readonly kind: 'kebab-slug';
+} | {
+    readonly kind: 'enum';
+    readonly values: readonly string[];
+} | {
+    readonly kind: 'pascal-identifier';
+} | {
+    readonly kind: 'comma-list-kebab-slug';
+} | {
+    readonly kind: 'comma-list-lowercase';
+} | {
+    readonly kind: 'comma-list-free-text';
+} | {
+    readonly kind: 'free-text';
+} | {
+    readonly kind: 'boolean';
+};
+/**
+ * One companion-tag spec entry. `suffix` is appended to the family marker name
+ * to form the full tag (e.g. `dbxPipe` + `Slug` → `@dbxPipeSlug`).
+ */
+export interface DbxCompanionTagSpec {
+    readonly suffix: string;
+    readonly required?: boolean;
+    readonly multiple?: boolean;
+    readonly format: DbxTagFormat;
+}
+/**
+ * The full set of companions plus the marker that triggers a family rule.
+ */
+export interface DbxTagFamilySpec {
+    readonly marker: string;
+    readonly companions: readonly DbxCompanionTagSpec[];
+}
+/**
+ * One violation emitted by {@link checkDbxTagFamily}. Each rule's `meta.messages`
+ * map provides the message text for each `kind`.
+ */
+export type DbxTagViolation = {
+    readonly kind: 'missing';
+    readonly suffix: string;
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'empty';
+    readonly suffix: string;
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'invalid-kebab';
+    readonly suffix: string;
+    readonly value: string;
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'invalid-enum';
+    readonly suffix: string;
+    readonly value: string;
+    readonly allowed: readonly string[];
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'invalid-pascal';
+    readonly suffix: string;
+    readonly value: string;
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'invalid-boolean';
+    readonly suffix: string;
+    readonly value: string;
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'comma-item-not-kebab';
+    readonly suffix: string;
+    readonly value: string;
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'tags-not-lowercase';
+    readonly suffix: string;
+    readonly value: string;
+    readonly lineIndex: number;
+    readonly raw: ParsedJsdocTag;
+} | {
+    readonly kind: 'unknown';
+    readonly suffix: string;
+    readonly lineIndex: number;
+} | {
+    readonly kind: 'duplicate';
+    readonly suffix: string;
+    readonly lineIndex: number;
+};
+/**
+ * Splits a comma-separated tag-value string into trimmed items, preserving order.
+ *
+ * @param value - Raw text following the tag name on a single line.
+ * @returns Non-empty trimmed segments in declaration order.
+ */
+export declare function splitCommaSeparated(value: string): string[];
+/**
+ * Parses a boolean tag value using the workspace vocabulary
+ * (`''`/`true`/`yes` → true; `false`/`no` → false). Other inputs return `undefined`.
+ *
+ * @param text - The trimmed tag value text.
+ * @returns The parsed boolean, or `undefined` when the text is not in the vocabulary.
+ */
+export declare function parseBooleanTagValue(text: string): Maybe<boolean>;
+/**
+ * Returns the source-text offset of an offset-within-comment-value, given a Block comment node.
+ *
+ * @param commentNode - The ESLint Block comment AST node.
+ * @param valueOffset - The character offset within `comment.value`.
+ * @returns The character offset in the source file.
+ */
+export declare function commentValueToSourceOffset(commentNode: AstNode, valueOffset: number): number;
+/**
+ * Returns the family marker + companion tag list for the given parsed JSDoc.
+ * Family membership is determined by tag-name prefix.
+ *
+ * @param parsed - The parsed JSDoc.
+ * @param marker - The bare family marker (e.g. `'dbxPipe'`).
+ * @returns The marker tag (if present), and all companion tags in source order.
+ */
+export declare function findFamilyTags(parsed: ParsedJsdoc, marker: string): {
+    readonly markerTag: Maybe<ParsedJsdocTag>;
+    readonly familyTags: readonly ParsedJsdocTag[];
+};
+/**
+ * Groups companion tags (those after the marker) by suffix. Marker entries are excluded.
+ *
+ * @param familyTags - The family tag list from {@link findFamilyTags}.
+ * @param marker - The bare family marker.
+ * @returns Lookup keyed by companion-suffix listing matching tags in declaration order.
+ */
+export declare function groupCompanionsBySuffix(familyTags: readonly ParsedJsdocTag[], marker: string): Map<string, ParsedJsdocTag[]>;
+/**
+ * Runs the canonical companion-tag validation pass for a `@dbx<Family>`-tagged
+ * JSDoc against the supplied {@link DbxTagFamilySpec}. Emits one
+ * {@link DbxTagViolation} per finding via `emit`; the calling rule maps each
+ * violation to its own messageId.
+ *
+ * Validation pass order:
+ *
+ *   1. Unknown companions (typo detection — companions not in the spec).
+ *   2. Required companions present (one violation per missing required tag).
+ *   3. Duplicates (companion appears more than once, when `multiple` is not set).
+ *   4. Per-companion value-format validation.
+ *
+ * Marker presence is the caller's responsibility — pass `markerPresent=true`
+ * (i.e. `requireBareMarker` already satisfied) before invoking this.
+ */
+export interface CheckDbxTagFamilyInput {
+    readonly parsed: ParsedJsdoc;
+    readonly spec: DbxTagFamilySpec;
+    readonly markerTag: ParsedJsdocTag;
+    readonly familyTags: readonly ParsedJsdocTag[];
+    readonly emit: (violation: DbxTagViolation) => void;
+}
+/**
+ * Validates a `@dbx<Family>` marker plus its companion tags against the supplied spec.
+ * Reports unknown companions, missing required companions, duplicates, and per-companion
+ * value violations through `input.emit`.
+ *
+ * @param input - Parsed JSDoc, family spec, resolved marker/companion tags, and emit sink.
+ *
+ * @example
+ * ```ts
+ * checkDbxTagFamily({ parsed, spec, markerTag, familyTags, emit });
+ * ```
+ */
+export declare function checkDbxTagFamily(input: CheckDbxTagFamilyInput): void;
+/**
+ * Wraps `context.report` with the family rule's common "report on a tag line"
+ * helper. The shared rule body uses this to translate {@link DbxTagViolation}
+ * locations into ESLint source ranges.
+ */
+export interface ReportOnLineInput {
+    readonly commentNode: AstNode;
+    readonly parsed: ParsedJsdoc;
+    readonly sourceCode: AstNode;
+    readonly lineIndex: number;
+    readonly messageId: string;
+    readonly data?: Record<string, string>;
+    readonly report: (descriptor: {
+        loc: AstNode;
+        messageId: string;
+        data?: Record<string, string>;
+        fix?: (fixer: AstNode) => Maybe<AstNode | AstNode[]>;
+    }) => void;
+    readonly fix?: (fixer: AstNode) => Maybe<AstNode | AstNode[]>;
+}
+/**
+ * Translates a JSDoc-line violation into an ESLint `context.report()` call by computing the
+ * source range of the offending line and attaching the supplied message + optional fixer.
+ *
+ * @param input - Reporting context (comment node, parsed JSDoc, source code, line index, message id, optional data + fixer, report sink).
+ *
+ * @example
+ * ```ts
+ * reportOnJsdocLine({ commentNode, parsed, sourceCode, lineIndex: tag.startLineIndex, messageId: 'unknown', report: context.report });
+ * ```
+ */
+export declare function reportOnJsdocLine(input: ReportOnLineInput): void;
+/**
+ * The visitor scopes used by `@dbx<Family>` companion-tag rules. Each rule
+ * supplies a subset and the shared visitor wires them with the canonical
+ * `getStatementAnchor` / `leadingJsdocFor` logic.
+ */
+export type DbxFamilyVisitorKind = 'FunctionDeclaration' | 'VariableDeclaration' | 'ClassDeclaration' | 'TSInterfaceDeclaration' | 'TSTypeAliasDeclaration' | 'TSEnumDeclaration' | 'TSPropertySignature' | 'PropertyDefinition' | 'TSEnumMember';
+/**
+ * Callback that maps a {@link DbxTagViolation} to its rule-specific
+ * messageId + data, or `null` when the violation should be silently dropped
+ * (e.g. when the rule does not require the missing companion).
+ */
+export type DbxFamilyViolationMapper = (violation: DbxTagViolation) => Maybe<{
+    readonly messageId: string;
+    readonly data?: Record<string, string>;
+    readonly fixable?: boolean;
+}>;
+/**
+ * Produces an auto-fix for a `@dbx<Family>Tags ...` line that lowercases every
+ * token after the tag name. Returns the replacement source range + text, or
+ * `undefined` when the line is already canonical.
+ *
+ * @param input - The fix context (comment node, parsed JSDoc, source code, tag).
+ * @returns The replacement range/text, or `undefined` when no fix is needed.
+ */
+export interface BuildLowercaseTagsFixInput {
+    readonly commentNode: AstNode;
+    readonly parsed: ParsedJsdoc;
+    readonly sourceCode: AstNode;
+    readonly tag: ParsedJsdocTag;
+}
+export interface LowercaseTagsFixResult {
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly replacement: string;
+}
+/**
+ * Computes an auto-fix descriptor that lowercases every token after a `@dbx<Family>Tags` tag
+ * name. Returns `undefined` when the line is already canonical so the caller can short-circuit.
+ *
+ * @param input - Fix context (comment node, parsed JSDoc, source code, target tag).
+ * @returns Replacement range + text when a rewrite is needed; otherwise `undefined`.
+ *
+ * @example
+ * ```ts
+ * const fix = buildLowercaseTagsFix({ commentNode, parsed, sourceCode, tag });
+ * ```
+ */
+export declare function buildLowercaseTagsFix(input: BuildLowercaseTagsFixInput): Maybe<LowercaseTagsFixResult>;
+export {};

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

@@ -1,3 +1,26 @@
-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';
+export { UTIL_REQUIRE_NO_SIDE_EFFECTS_RULE, type UtilRequireNoSideEffectsRuleOptions, type UtilRequireNoSideEffectsRuleDefinition } from './require-no-side-effects.rule';
+export { UTIL_PREFER_NO_SIDE_EFFECTS_IN_JSDOC_RULE, type UtilPreferNoSideEffectsInJsdocRuleDefinition } from './prefer-no-side-effects-in-jsdoc.rule';
+export { UTIL_NO_SISTER_RE_EXPORT_RULE, type UtilNoSisterReExportRuleOptions, type UtilNoSisterReExportRuleDefinition } from './no-sister-re-export.rule';
+export { UTIL_REQUIRE_SINGLE_RETURN_RULE, type UtilRequireSingleReturnRuleDefinition } from './require-single-return.rule';
+export { UTIL_REQUIRE_READONLY_CONFIG_PARAMS_RULE, type UtilRequireReadonlyConfigParamsRuleOptions, type UtilRequireReadonlyConfigParamsRuleDefinition } from './require-readonly-config-params.rule';
+export { UTIL_PREFER_CONFIG_OBJECT_RULE, UTIL_PREFER_CONFIG_OBJECT_HARD_RULE, type UtilPreferConfigObjectRuleOptions, type UtilPreferConfigObjectRuleDefinition } from './prefer-config-object.rule';
+export { UTIL_PREFER_MAYBE_TYPE_RULE, type UtilPreferMaybeTypeRuleOptions, type UtilPreferMaybeTypeRuleDefinition } from './prefer-maybe-type.rule';
+export { UTIL_NO_INLINE_TYPE_IMPORT_RULE, type UtilNoInlineTypeImportRuleDefinition } from './no-inline-type-import.rule';
+export { UTIL_REQUIRE_DEPRECATED_ALIAS_PLACEMENT_RULE, type UtilRequireDeprecatedAliasPlacementRuleDefinition } from './require-deprecated-alias-placement.rule';
+export { UTIL_PREFER_CANONICAL_JSDOC_RULE, type UtilPreferCanonicalJsdocRuleOptions, type UtilPreferCanonicalJsdocRuleDefinition } from './prefer-canonical-jsdoc.rule';
+export { UTIL_REQUIRE_DBX_UTIL_COMPANION_TAGS_RULE, type UtilRequireDbxUtilCompanionTagsRuleOptions, type UtilRequireDbxUtilCompanionTagsRuleDefinition } from './require-dbx-util-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_PIPE_COMPANION_TAGS_RULE, type UtilRequireDbxPipeCompanionTagsRuleOptions, type UtilRequireDbxPipeCompanionTagsRuleDefinition } from './require-dbx-pipe-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_FILTER_COMPANION_TAGS_RULE, type UtilRequireDbxFilterCompanionTagsRuleOptions, type UtilRequireDbxFilterCompanionTagsRuleDefinition } from './require-dbx-filter-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_WEB_COMPANION_TAGS_RULE, type UtilRequireDbxWebCompanionTagsRuleOptions, type UtilRequireDbxWebCompanionTagsRuleDefinition } from './require-dbx-web-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_DOCS_UI_EXAMPLE_COMPANION_TAGS_RULE, type UtilRequireDbxDocsUiExampleCompanionTagsRuleOptions, type UtilRequireDbxDocsUiExampleCompanionTagsRuleDefinition } from './require-dbx-docs-ui-example-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_MODEL_SNAPSHOT_FIELD_COMPANION_TAGS_RULE, type UtilRequireDbxModelSnapshotFieldCompanionTagsRuleOptions, type UtilRequireDbxModelSnapshotFieldCompanionTagsRuleDefinition } from './require-dbx-model-snapshot-field-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_MODEL_FIREBASE_INDEX_COMPANION_TAGS_RULE, type UtilRequireDbxModelFirebaseIndexCompanionTagsRuleOptions, type UtilRequireDbxModelFirebaseIndexCompanionTagsRuleDefinition } from './require-dbx-model-firebase-index-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_ACTION_COMPANION_TAGS_RULE, type UtilRequireDbxActionCompanionTagsRuleOptions, type UtilRequireDbxActionCompanionTagsRuleDefinition } from './require-dbx-action-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_FORM_FIELD_COMPANION_TAGS_RULE, type UtilRequireDbxFormFieldCompanionTagsRuleOptions, type UtilRequireDbxFormFieldCompanionTagsRuleDefinition } from './require-dbx-form-field-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_MODEL_COMPANION_TAGS_RULE, type UtilRequireDbxModelCompanionTagsRuleOptions, type UtilRequireDbxModelCompanionTagsRuleDefinition } from './require-dbx-model-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_AUTH_COMPANION_TAGS_RULE, type UtilRequireDbxAuthCompanionTagsRuleOptions, type UtilRequireDbxAuthCompanionTagsRuleDefinition } from './require-dbx-auth-companion-tags.rule';
+export { UTIL_REQUIRE_DBX_RULE_COMPANION_TAGS_RULE, type UtilRequireDbxRuleCompanionTagsRuleOptions, type UtilRequireDbxRuleCompanionTagsRuleDefinition } from './require-dbx-rule-companion-tags.rule';
+export { UTIL_REQUIRE_CONSTANT_NAMING_RULE, type UtilRequireConstantNamingRuleOptions, type UtilRequireConstantNamingRuleDefinition } from './require-constant-naming.rule';
+export { UTIL_REQUIRE_DEFAULT_PREFIX_NAMING_RULE, type UtilRequireDefaultPrefixNamingRuleOptions, type UtilRequireDefaultPrefixNamingRuleDefinition } from './require-default-prefix-naming.rule';
+export { UTIL_REQUIRE_EXPORTED_JSDOC_EXAMPLE_RULE, type UtilRequireExportedJsdocExampleRuleOptions, type UtilRequireExportedJsdocExampleRuleDefinition } from './require-exported-jsdoc-example.rule';
+export { UTIL_ESLINT_PLUGIN, type UtilEslintPlugin } from './plugin';

package/eslint/src/lib/jsdoc-parser.d.ts

@@ -0,0 +1,116 @@
+import type { Maybe } from '@dereekb/util';
+/**
+ * Minimal JSDoc parser used by the workspace's custom ESLint rules.
+ *
+ * Operates on the raw `value` of an ESLint Block comment (the text between `/*` and `*\/`,
+ * which includes the leading `*` of a JSDoc opener). Returns a structured view of the comment:
+ * description, paragraphs, tags (with their continuation lines), and per-line metadata.
+ */
+/**
+ * Per-line view of a comment body.
+ */
+export interface ParsedJsdocLine {
+    /**
+     * Raw line content with leading whitespace + `*` prefix preserved.
+     */
+    readonly raw: string;
+    /**
+     * Text content after the leading whitespace + `*` + optional space prefix has been stripped.
+     */
+    readonly text: string;
+    /**
+     * True when the line is blank after stripping (only `* ` with nothing else).
+     */
+    readonly blank: boolean;
+    /**
+     * Index in the original `splitLines` array.
+     */
+    readonly index: number;
+    /**
+     * Character offset of `raw[0]` relative to the start of `commentValue` (not the source file).
+     */
+    readonly valueOffsetStart: number;
+    /**
+     * Character offset of `text[0]` relative to the start of `commentValue`. Equals `valueOffsetStart` plus the length of the stripped prefix.
+     */
+    readonly textOffsetStart: number;
+}
+/**
+ * Parsed view of a single `@tag` block, including any continuation lines that follow it
+ * up to the next tag (or end of comment).
+ */
+export interface ParsedJsdocTag {
+    /**
+     * Tag name without the leading `@`, e.g. `param`, `returns`, `throws`, `dbxUtil`, `__NO_SIDE_EFFECTS__`.
+     */
+    readonly tag: string;
+    /**
+     * For `@param`: the parameter name. For other tags: `undefined`.
+     */
+    readonly name: Maybe<string>;
+    /**
+     * For `@throws` / `@param` style: the `{Type}` annotation if present.
+     */
+    readonly type: Maybe<string>;
+    /**
+     * Remaining text on the tag line + continuation lines, joined with `\n`. Trimmed of trailing whitespace.
+     */
+    readonly description: string;
+    /**
+     * All lines belonging to this tag (the tag line itself and any continuation lines).
+     */
+    readonly lines: readonly ParsedJsdocLine[];
+    /**
+     * Index in the comment-lines array where the tag starts.
+     */
+    readonly startLineIndex: number;
+    /**
+     * Index (inclusive) where the tag ends.
+     */
+    readonly endLineIndex: number;
+}
+/**
+ * Parsed view of a whole JSDoc comment.
+ */
+export interface ParsedJsdoc {
+    /**
+     * All lines in the comment body.
+     */
+    readonly lines: readonly ParsedJsdocLine[];
+    /**
+     * Lines belonging to the description (before any tag).
+     */
+    readonly descriptionLines: readonly ParsedJsdocLine[];
+    /**
+     * Description text joined with `\n`, with leading and trailing blank lines stripped.
+     */
+    readonly description: string;
+    /**
+     * Description split into paragraphs by blank lines, with each paragraph joined by `\n`.
+     */
+    readonly descriptionParagraphs: readonly string[];
+    /**
+     * All tags in source order.
+     */
+    readonly tags: readonly ParsedJsdocTag[];
+    /**
+     * True when the original comment is a single-line `/** ... *\/` block (no newlines).
+     */
+    readonly singleLine: boolean;
+}
+/**
+ * Parses the value of an ESLint Block comment that represents a JSDoc into a structured form.
+ *
+ * @param commentValue - The `value` of an ESLint Block comment (text between `/*` and `*\/`, including the leading `*`).
+ * @returns A structured view of the JSDoc with description, paragraphs, and tags.
+ *
+ * @example
+ * ```ts
+ * const parsed = parseJsdocComment('*\n * Hello.\n *\n * @param x - The value.\n ');
+ * // parsed.description === 'Hello.'
+ * // parsed.tags[0].tag === 'param'
+ * // parsed.tags[0].name === 'x'
+ * // parsed.tags[0].description === 'The value.'
+ * ```
+ */
+export declare function parseJsdocComment(commentValue: string): ParsedJsdoc;

package/eslint/src/lib/no-inline-string-empty-object-intersection.rule.d.ts

@@ -0,0 +1,44 @@
+interface AstNode {
+    readonly type: string;
+    [key: string]: any;
+}
+/**
+ * ESLint rule definition for no-inline-string-empty-object-intersection.
+ */
+export interface UtilNoInlineStringEmptyObjectIntersectionRuleDefinition {
+    readonly meta: {
+        readonly type: 'problem';
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: {
+            readonly inlineIntersectionForbidden: string;
+        };
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+        }) => void;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule that errors on any inline `string & {}` intersection — either standalone or as a
+ * member of a union (the `T | (string & {})` autocomplete-preserving idiom). The intersection is
+ * opaque at the call site and reads like a typo; the workspace's `SuggestedString<T>` alias from
+ * `@dereekb/util` is the only sanctioned way to express the same shape.
+ *
+ * The rule is intentionally non-fixable: switching to `SuggestedString<T>` also requires adding
+ * an `import { type SuggestedString } from '@dereekb/util'` (or a relative path inside
+ * `@dereekb/util` itself), and the right insertion point depends on existing import structure.
+ * The error message names the type so the developer can make the change deliberately.
+ *
+ * The rule visits `TSIntersectionType` directly, so it fires regardless of whether the
+ * intersection appears inside a union, a parenthesized type, a type alias body, a function
+ * signature, or anywhere else.
+ */
+export declare const UTIL_NO_INLINE_STRING_EMPTY_OBJECT_INTERSECTION_RULE: UtilNoInlineStringEmptyObjectIntersectionRuleDefinition;
+export {};

package/eslint/src/lib/no-inline-type-import.rule.d.ts

@@ -0,0 +1,38 @@
+interface AstNode {
+    readonly type: string;
+    [key: string]: any;
+}
+/**
+ * ESLint rule definition for no-inline-type-import.
+ */
+export interface UtilNoInlineTypeImportRuleDefinition {
+    readonly meta: {
+        readonly type: 'suggestion';
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: {
+            readonly inlineImportTypeForbidden: string;
+        };
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+        }) => void;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule prohibiting inline `import('path').Type` usage in type positions. Inline imports are
+ * a TypeScript shortcut that bypasses the workspace convention of declaring all imports at the top
+ * of the file via `import type`. The rule reports each occurrence; rewriting the source is left to
+ * the developer because resolving the right top-of-file import (or merging with an existing one)
+ * is too source-shape-dependent to mechanize safely.
+ *
+ * @see `dbx__note__typescript-programming` → No Inline Type Imports
+ */
+export declare const UTIL_NO_INLINE_TYPE_IMPORT_RULE: UtilNoInlineTypeImportRuleDefinition;
+export {};

package/eslint/src/lib/no-sister-re-export.rule.d.ts

@@ -0,0 +1,69 @@
+interface AstNode {
+    readonly type: string;
+    [key: string]: any;
+}
+/**
+ * Options for the no-sister-re-export rule.
+ */
+export interface UtilNoSisterReExportRuleOptions {
+    /**
+     * Glob-style specifier patterns that identify "sister" packages. A specifier matching
+     * any pattern is reported. `*` matches any run of characters; other regex metacharacters
+     * are escaped. Anchored start-to-end.
+     *
+     * @example ['@dereekb/*', 'joinfoodflip-*']
+     */
+    readonly patterns?: readonly string[];
+    /**
+     * Exact specifier exemptions. A re-export whose source string exactly matches an entry
+     * is always allowed, even if it matches one of `patterns`.
+     */
+    readonly allow?: readonly string[];
+    /**
+     * When true, type-only re-exports (`export type { ... } from 'pkg'` and `export type * from 'pkg'`)
+     * are allowed regardless of `patterns`. Defaults to false.
+     */
+    readonly allowTypeOnly?: boolean;
+}
+/**
+ * ESLint rule definition for no-sister-re-export.
+ */
+export interface UtilNoSisterReExportRuleDefinition {
+    readonly meta: {
+        readonly type: 'problem';
+        readonly docs: {
+            readonly description: string;
+            readonly recommended: boolean;
+        };
+        readonly messages: {
+            readonly noSisterReExport: string;
+            readonly noSisterReExportAll: string;
+        };
+        readonly schema: readonly object[];
+    };
+    create(context: {
+        options: UtilNoSisterReExportRuleOptions[];
+        report: (descriptor: {
+            node: AstNode;
+            messageId: string;
+            data?: Record<string, string>;
+        }) => void;
+    }): Record<string, (node: AstNode) => void>;
+}
+/**
+ * ESLint rule that disallows re-exporting from "sister" packages — workspace packages other than
+ * the one the file lives in. Catches the common shortcut of
+ *
+ * ```ts
+ * export { somethingFromOtherPackage } from 'some-other-package';
+ * ```
+ *
+ * inside package A when `some-other-package` is package B in the same workspace. The fix is to
+ * either import directly from the source package at the call site, or to expose the symbol from
+ * that package's own public surface so callers don't traverse an unrelated package's barrel.
+ *
+ * Sister packages are identified by `options.patterns` (glob-style; `*` matches any run of characters).
+ * Relative re-exports (`./local`, `../sibling`) are always allowed.
+ */
+export declare const UTIL_NO_SISTER_RE_EXPORT_RULE: UtilNoSisterReExportRuleDefinition;
+export {};