@thethracian/oxlint-config 0.2.1 → 0.3.0

package/dist/rules/require-function-doc.js

@@ -1,78 +1,154 @@
-/**
- * Require-function-doc — ensures every exported declaration has a non-empty JSDoc comment.
- *
- * Checks:
- *   - `export function`, `export class`, `export const`, `export let`, `export var`
- *   - `export default function`, `export default class`
- *   - `export type`, `export interface`, `export enum`
- *   - `export abstract class`
- *
- * Skips:
- *   - `export { ... } from ...` (re-exports)
- *   - `export * from ...` (wildcard re-exports)
- *   - `export type { ... } from ...` (type re-exports)
- *   - `export default <expression>` (not a declaration)
- *   - Non-exported declarations
- */
-function isWhitespace(code) {
-    return code === 32 || code === 9 || code === 10 || code === 13;
-}
-function hasDescriptionContent(jsdocBody) {
+/* -------------------------------------------------------------------------- */
+/*  Exported-declaration documentation requirement helper for custom Oxlint   */
+/*                                   Rules.                                   */
+/* -------------------------------------------------------------------------- */
+import { isDocumentedLocalExportList } from './require-function-doc-local-exports.js';
+import { isInsideIgnoredText } from './require-function-doc-ignored-text.js';
+const CHAR_CODE_SPACE = 32;
+const CHAR_CODE_TAB = 9;
+const CHAR_CODE_NEWLINE = 10;
+const CHAR_CODE_CARRIAGE_RETURN = 13;
+const CHAR_CODE_ASTERISK = 42;
+const CHAR_CODE_SLASH = 47;
+const CHAR_CODE_HASH = 35;
+const CHAR_CODE_AT_SIGN = 64;
+const CHAR_CODE_OPEN_PAREN = 40;
+const CHAR_CODE_OPEN_BRACE = 123;
+const CHAR_CODE_SEMICOLON = 59;
+const CHAR_CODE_LESS_THAN = 60;
+const CHAR_CODE_LOWER_A = 97;
+const CHAR_CODE_LOWER_C = 99;
+const CHAR_CODE_LOWER_D = 100;
+const CHAR_CODE_LOWER_E = 101;
+const CHAR_CODE_LOWER_F = 102;
+const CHAR_CODE_LOWER_I = 105;
+const CHAR_CODE_LOWER_L = 108;
+const CHAR_CODE_LOWER_N = 110;
+const CHAR_CODE_LOWER_T = 116;
+const CHAR_CODE_LOWER_V = 118;
+const CHAR_CODE_UPPER_C = 67;
+const CHAR_CODE_UPPER_E = 69;
+const CHAR_CODE_UPPER_F = 70;
+const CHAR_CODE_UPPER_I = 73;
+const CHAR_CODE_UPPER_L = 76;
+const CHAR_CODE_UPPER_N = 78;
+const CHAR_CODE_UPPER_V = 86;
+const ASYNC_KEYWORD_LENGTH = 'async '.length;
+const TYPE_KEYWORD_LENGTH = 'type '.length;
+const EXPORT_KEYWORD_LENGTH = 'export '.length;
+const DEFAULT_KEYWORD_LENGTH = 'default '.length;
+const DECLARE_KEYWORD_LENGTH = 'declare '.length;
+const ABSTRACT_KEYWORD_LENGTH = 'abstract '.length;
+const isWhitespace = (code) => code === CHAR_CODE_SPACE ||
+    code === CHAR_CODE_TAB ||
+    code === CHAR_CODE_NEWLINE ||
+    code === CHAR_CODE_CARRIAGE_RETURN;
+const lineEndFor = (source, lineStart, len) => {
+    const newlineIndex = source.indexOf('\n', lineStart);
+    if (newlineIndex === -1) {
+        return len;
+    }
+    return newlineIndex;
+};
+const skipLinePrefix = (source, pos, lineEnd) => {
+    let cursor = pos;
+    while (cursor < lineEnd && isWhitespace(source.charCodeAt(cursor))) {
+        cursor++;
+    }
+    if (cursor < lineEnd && source.charCodeAt(cursor) === CHAR_CODE_ASTERISK) {
+        cursor++;
+    }
+    while (cursor < lineEnd && isWhitespace(source.charCodeAt(cursor))) {
+        cursor++;
+    }
+    return cursor;
+};
+const isJSDocTagLine = (source, pos, lineEnd) => pos < lineEnd && source.charCodeAt(pos) === CHAR_CODE_AT_SIGN;
+const lineHasDescriptionContent = (source, lineStart, lineEnd) => {
+    let pos = skipLinePrefix(source, lineStart, lineEnd);
+    if (isJSDocTagLine(source, pos, lineEnd)) {
+        return false;
+    }
+    while (pos < lineEnd) {
+        if (!isWhitespace(source.charCodeAt(pos))) {
+            return true;
+        }
+        pos++;
+    }
+    return false;
+};
+const nextDescriptionLineStart = (newlineIndex) => {
+    if (newlineIndex === -1) {
+        return undefined;
+    }
+    return newlineIndex + 1;
+};
+const hasDescriptionLine = (jsdocBody, lineStart, len) => {
+    const newlineIndex = jsdocBody.indexOf('\n', lineStart);
+    const lineEnd = lineEndFor(jsdocBody, lineStart, len);
+    if (lineHasDescriptionContent(jsdocBody, lineStart, lineEnd)) {
+        return { found: true };
+    }
+    return { found: false, nextLineStart: nextDescriptionLineStart(newlineIndex) };
+};
+const hasDescriptionContent = (jsdocBody) => {
     let lineStart = 0;
     const len = jsdocBody.length;
     while (lineStart <= len) {
-        const newlineIndex = jsdocBody.indexOf('\n', lineStart);
-        const lineEnd = newlineIndex === -1 ? len : newlineIndex;
-        let pos = lineStart;
-        while (pos < lineEnd && isWhitespace(jsdocBody.charCodeAt(pos))) {
-            pos++;
-        }
-        if (pos < lineEnd && jsdocBody.charCodeAt(pos) === 42) {
-            pos++;
-            while (pos < lineEnd && isWhitespace(jsdocBody.charCodeAt(pos))) {
-                pos++;
-            }
-        }
-        while (pos < lineEnd) {
-            if (!isWhitespace(jsdocBody.charCodeAt(pos))) {
-                return true;
-            }
-            pos++;
+        const result = hasDescriptionLine(jsdocBody, lineStart, len);
+        if (result.found) {
+            return true;
         }
-        if (newlineIndex === -1) {
+        if (result.nextLineStart === undefined) {
             return false;
         }
-        lineStart = newlineIndex + 1;
+        lineStart = result.nextLineStart;
     }
     return false;
-}
-function hasJSDocBefore(source, exportPos) {
-    let pos = exportPos;
-    while (pos > 0 && isWhitespace(source.charCodeAt(pos - 1))) {
-        pos--;
+};
+const skipWhitespaceBack = (source, pos) => {
+    let cursor = pos;
+    while (cursor > 0 && isWhitespace(source.charCodeAt(cursor - 1))) {
+        cursor--;
     }
-    if (pos < 2) {
-        return false;
-    }
-    if (source.charCodeAt(pos - 2) !== 42 || source.charCodeAt(pos - 1) !== 47) {
-        return false;
+    return cursor;
+};
+const hasBlockCommentCloseAt = (source, pos) => pos >= '*/'.length &&
+    source.charCodeAt(pos - '*/'.length) === CHAR_CODE_ASTERISK &&
+    source.charCodeAt(pos - 1) === CHAR_CODE_SLASH;
+const jsdocContentBeforeClose = (source, open, closeStar) => {
+    if (open + 1 < closeStar && source.charCodeAt(open + 1) === CHAR_CODE_ASTERISK) {
+        return source.slice(open + '/**'.length, closeStar).trim();
     }
-    const closeStar = pos - 2;
+    return undefined;
+};
+const previousJSDocContent = (source, closeStar) => {
     let open = closeStar - 1;
     while (open > 0) {
-        if (source.charCodeAt(open) === 42 && source.charCodeAt(open - 1) === 47) {
-            if (open + 1 < closeStar && source.charCodeAt(open + 1) === 42) {
-                const content = source.slice(open + 3, closeStar).trim();
-                return hasDescriptionContent(content);
+        if (source.charCodeAt(open) === CHAR_CODE_ASTERISK &&
+            source.charCodeAt(open - 1) === CHAR_CODE_SLASH) {
+            const content = jsdocContentBeforeClose(source, open, closeStar);
+            if (content !== undefined) {
+                return content;
             }
-            open -= 2;
-            continue;
+            open -= '/*'.length;
+        }
+        else {
+            open--;
         }
-        open--;
     }
-    return false;
-}
-function endsWithWord(source, pos, word) {
+    return undefined;
+};
+const hasJSDocBefore = (source, exportPOS) => {
+    const pos = skipWhitespaceBack(source, exportPOS);
+    if (!hasBlockCommentCloseAt(source, pos)) {
+        return false;
+    }
+    const closeStar = pos - '*/'.length;
+    const content = previousJSDocContent(source, closeStar);
+    return content !== undefined && hasDescriptionContent(content);
+};
+const endsWithWord = (source, pos, word) => {
     const end = pos + word.length;
     if (end > source.length) {
         return false;
@@ -84,196 +160,295 @@ function endsWithWord(source, pos, word) {
         return true;
     }
     const next = source.charCodeAt(end);
-    return isWhitespace(next) || next === 40 || next === 123 || next === 59 || next === 60;
-}
-function isDefaultDeclaration(source, pos, _len) {
+    return (isWhitespace(next) ||
+        next === CHAR_CODE_OPEN_PAREN ||
+        next === CHAR_CODE_OPEN_BRACE ||
+        next === CHAR_CODE_SEMICOLON ||
+        next === CHAR_CODE_LESS_THAN);
+};
+const isDefaultDeclaration = (source, pos, _len) => {
     const ch = source.charCodeAt(pos);
-    if (ch === 102) {
+    if (ch === CHAR_CODE_LOWER_F) {
         return endsWithWord(source, pos, 'function');
     }
-    if (ch === 99) {
+    if (ch === CHAR_CODE_LOWER_C) {
         return endsWithWord(source, pos, 'class');
     }
-    if (ch === 105) {
+    if (ch === CHAR_CODE_LOWER_I) {
         return endsWithWord(source, pos, 'interface');
     }
     return false;
-}
+};
 const AMBIENT_DECLARE_PREFIXES = ['declare module', 'declare namespace', 'declare global'];
-function isAmbientDeclarationFile(source) {
-    let idx = 0;
-    const len = source.length;
-    while (idx < len && source.charCodeAt(idx) === 35) {
-        idx = source.indexOf('\n', idx);
-        if (idx === -1) {
-            return false;
+const skipShebangComments = (source, idx) => {
+    let cursor = idx;
+    while (cursor < source.length && source.charCodeAt(cursor) === CHAR_CODE_HASH) {
+        cursor = source.indexOf('\n', cursor);
+        if (cursor === -1) {
+            return undefined;
         }
-        idx++;
+        cursor++;
+    }
+    return cursor;
+};
+const skipBlockComment = (source, idx) => {
+    const close = source.indexOf('*/', idx + '/*'.length);
+    if (close === -1) {
+        return undefined;
+    }
+    return close + '*/'.length;
+};
+const skipLineComment = (source, idx) => {
+    const nl = source.indexOf('\n', idx);
+    if (nl === -1) {
+        return undefined;
+    }
+    return nl + 1;
+};
+const skipTriviaToken = (source, idx) => {
+    const ch = source.charCodeAt(idx);
+    if (isWhitespace(ch)) {
+        return idx + 1;
+    }
+    if (ch === CHAR_CODE_SLASH &&
+        idx + 1 < source.length &&
+        source.charCodeAt(idx + 1) === CHAR_CODE_ASTERISK) {
+        return skipBlockComment(source, idx);
+    }
+    if (ch === CHAR_CODE_SLASH &&
+        idx + 1 < source.length &&
+        source.charCodeAt(idx + 1) === CHAR_CODE_SLASH) {
+        return skipLineComment(source, idx);
     }
-    while (idx < len) {
-        const ch = source.charCodeAt(idx);
-        if (isWhitespace(ch)) {
-            idx++;
-            continue;
+    return idx;
+};
+const skipLeadingTrivia = (source, idx) => {
+    let cursor = idx;
+    while (cursor < source.length) {
+        const next = skipTriviaToken(source, cursor);
+        if (next === undefined) {
+            return undefined;
         }
-        if (ch === 47 && idx + 1 < len && source.charCodeAt(idx + 1) === 42) {
-            const close = source.indexOf('*/', idx + 2);
-            if (close !== -1) {
-                idx = close + 2;
-                continue;
-            }
-            return false;
+        if (next === cursor) {
+            return cursor;
         }
-        if (ch === 47 && idx + 1 < len && source.charCodeAt(idx + 1) === 47) {
-            const nl = source.indexOf('\n', idx);
-            if (nl !== -1) {
-                idx = nl + 1;
-                continue;
-            }
-            return false;
+        cursor = next;
+    }
+    return cursor;
+};
+const hasAmbientPrefixAt = (source, idx) => AMBIENT_DECLARE_PREFIXES.some((prefix) => idx + prefix.length <= source.length && source.slice(idx, idx + prefix.length) === prefix);
+const isAmbientDeclarationFile = (source) => {
+    const shebangEnd = skipShebangComments(source, 0);
+    if (shebangEnd === undefined) {
+        return false;
+    }
+    const idx = skipLeadingTrivia(source, shebangEnd);
+    if (idx === undefined || idx >= source.length) {
+        return false;
+    }
+    return hasAmbientPrefixAt(source, idx);
+};
+const nextExportPosition = (source, start) => {
+    const exp = source.indexOf('export ', start);
+    if (exp === -1) {
+        return undefined;
+    }
+    return exp;
+};
+const isStandaloneExportKeyword = (source, exp) => {
+    if (exp === 0) {
+        return true;
+    }
+    return isWhitespace(source.charCodeAt(exp - 1));
+};
+const isDeclareExport = (source, exp) => exp >= DECLARE_KEYWORD_LENGTH && source.slice(exp - DECLARE_KEYWORD_LENGTH, exp) === 'declare ';
+const skipWhitespace = (source, pos) => {
+    let cursor = pos;
+    while (cursor < source.length && isWhitespace(source.charCodeAt(cursor))) {
+        cursor++;
+    }
+    return cursor;
+};
+const isReExportAt = (source, afterExport) => {
+    if (afterExport >= source.length) {
+        return false;
+    }
+    const c0 = source.charCodeAt(afterExport);
+    if (c0 === CHAR_CODE_OPEN_BRACE || c0 === CHAR_CODE_ASTERISK) {
+        return true;
+    }
+    if (c0 !== CHAR_CODE_LOWER_T ||
+        afterExport + TYPE_KEYWORD_LENGTH > source.length ||
+        source.slice(afterExport, afterExport + TYPE_KEYWORD_LENGTH) !== 'type ') {
+        return false;
+    }
+    const afterType = afterExport + TYPE_KEYWORD_LENGTH;
+    return afterType < source.length && source.charCodeAt(afterType) === CHAR_CODE_OPEN_BRACE;
+};
+const modifierSpecs = [
+    {
+        charCode: CHAR_CODE_LOWER_D,
+        isDefault: true,
+        length: DEFAULT_KEYWORD_LENGTH,
+        shouldStop: false,
+        text: 'default ',
+    },
+    {
+        charCode: CHAR_CODE_LOWER_A,
+        isDefault: false,
+        length: ASYNC_KEYWORD_LENGTH,
+        shouldStop: false,
+        text: 'async ',
+    },
+    {
+        charCode: CHAR_CODE_LOWER_A,
+        isDefault: false,
+        length: ABSTRACT_KEYWORD_LENGTH,
+        shouldStop: false,
+        text: 'abstract ',
+    },
+    {
+        charCode: CHAR_CODE_LOWER_T,
+        isDefault: false,
+        length: TYPE_KEYWORD_LENGTH,
+        shouldStop: false,
+        text: 'type ',
+    },
+    {
+        charCode: CHAR_CODE_LOWER_N,
+        isDefault: false,
+        length: 0,
+        shouldStop: true,
+        text: 'namespace ',
+    },
+];
+const modifierSpecMatches = (source, pos, spec) => source.charCodeAt(pos) === spec.charCode &&
+    pos + spec.text.length <= source.length &&
+    source.slice(pos, pos + spec.text.length) === spec.text;
+const modifierLengthAt = (source, pos) => {
+    for (const spec of modifierSpecs) {
+        if (modifierSpecMatches(source, pos, spec)) {
+            return spec;
         }
-        break;
     }
-    if (idx >= len) {
+    return undefined;
+};
+const scanExportModifiers = (source, start) => {
+    let pos = start;
+    let hasSawDefault = false;
+    let modifier = modifierLengthAt(source, pos);
+    while (modifier && !modifier.shouldStop) {
+        hasSawDefault ||= modifier.isDefault;
+        pos = skipWhitespace(source, pos + modifier.length);
+        modifier = modifierLengthAt(source, pos);
+    }
+    return { hasSawDefault, pos };
+};
+const declarationStartCodes = new Set([
+    CHAR_CODE_LOWER_F,
+    CHAR_CODE_UPPER_F,
+    CHAR_CODE_LOWER_C,
+    CHAR_CODE_UPPER_C,
+    CHAR_CODE_LOWER_I,
+    CHAR_CODE_UPPER_I,
+    CHAR_CODE_LOWER_E,
+    CHAR_CODE_UPPER_E,
+    CHAR_CODE_LOWER_L,
+    CHAR_CODE_UPPER_L,
+    CHAR_CODE_LOWER_V,
+    CHAR_CODE_UPPER_V,
+    CHAR_CODE_LOWER_N,
+    CHAR_CODE_UPPER_N,
+]);
+const isDeclarationStartCode = (code) => declarationStartCodes.has(code);
+const canSkipDocumentedExport = (source, modifiers) => {
+    if (modifiers.pos >= source.length) {
+        return true;
+    }
+    const next = source.charCodeAt(modifiers.pos);
+    if (!isDeclarationStartCode(next)) {
+        return true;
+    }
+    return modifiers.hasSawDefault && !isDefaultDeclaration(source, modifiers.pos, source.length);
+};
+const documentedLocalExportListResult = (source, after, exp) => isDocumentedLocalExportList(source, after, exp, hasJSDocBefore);
+const exhaustedExportDocResult = (source, after) => {
+    if (after >= source.length) {
+        return true;
+    }
+    return undefined;
+};
+const earlyExportDocResult = (source, after, exp) => {
+    const exhaustedExport = exhaustedExportDocResult(source, after);
+    if (exhaustedExport !== undefined) {
+        return exhaustedExport;
+    }
+    const localExportList = documentedLocalExportListResult(source, after, exp);
+    if (localExportList !== undefined) {
+        return localExportList;
+    }
+    if (isReExportAt(source, after)) {
+        return true;
+    }
+    return undefined;
+};
+const isDocumentedExportDeclaration = (source, exp) => {
+    const after = skipWhitespace(source, exp + EXPORT_KEYWORD_LENGTH);
+    const earlyResult = earlyExportDocResult(source, after, exp);
+    if (earlyResult !== undefined) {
+        return earlyResult;
+    }
+    const modifiers = scanExportModifiers(source, after);
+    if (canSkipDocumentedExport(source, modifiers)) {
+        return true;
+    }
+    return hasJSDocBefore(source, exp);
+};
+const isUndocumentedExportAt = (source, exp) => {
+    if (isInsideIgnoredText(source, exp) ||
+        !isStandaloneExportKeyword(source, exp) ||
+        isDeclareExport(source, exp)) {
         return false;
     }
-    for (const prefix of AMBIENT_DECLARE_PREFIXES) {
-        if (idx + prefix.length <= len && source.slice(idx, idx + prefix.length) === prefix) {
+    return isDocumentedExportDeclaration(source, exp) === false;
+};
+const nextExportSearchPosition = (source, pos) => {
+    const exp = nextExportPosition(source, pos);
+    if (exp === undefined) {
+        return undefined;
+    }
+    return {
+        nextPOS: exp + EXPORT_KEYWORD_LENGTH,
+        undocumented: isUndocumentedExportAt(source, exp),
+    };
+};
+const hasUndocumentedExport = (source) => {
+    let pos = 0;
+    while (pos < source.length) {
+        const exportSearch = nextExportSearchPosition(source, pos);
+        if (!exportSearch) {
+            return false;
+        }
+        if (exportSearch.undocumented) {
             return true;
         }
+        pos = exportSearch.nextPOS;
     }
     return false;
-}
+};
 /**
- * Returns true if all exported declarations have a non-empty JSDoc comment
- * preceding them. Returns false if any export is undocumented or has an
- * empty JSDoc.
+ * Checks whether exported declarations have meaningful JSDoc comments.
+ *
+ * @param source - TypeScript source text to inspect.
+ * @returns True when every public declaration is documented or no public declarations exist.
  */
 export default function hasRequiredFunctionDocs(source) {
-    const len = source.length;
     if (!source.includes('export ')) {
         return true;
     }
     if (isAmbientDeclarationFile(source)) {
         return true;
     }
-    let pos = 0;
-    while (pos < len) {
-        const exp = source.indexOf('export ', pos);
-        if (exp === -1) {
-            break;
-        }
-        if (exp > 0) {
-            const prev = source.charCodeAt(exp - 1);
-            if (prev !== 10 && prev !== 13 && prev !== 9 && prev !== 32) {
-                pos = exp + 1;
-                continue;
-            }
-            if (exp >= 8 && source.slice(exp - 8, exp) === 'declare ') {
-                pos = exp + 7;
-                continue;
-            }
-        }
-        let after = exp + 7;
-        while (after < len && isWhitespace(source.charCodeAt(after))) {
-            after++;
-        }
-        if (after >= len) {
-            break;
-        }
-        const c0 = source.charCodeAt(after);
-        // Re-export block: export { ... }
-        if (c0 === 123) {
-            pos = exp + 7;
-            continue;
-        }
-        // Wildcard re-export: export *
-        if (c0 === 42) {
-            pos = exp + 7;
-            continue;
-        }
-        // Type re-export: export type { ... }
-        if (c0 === 116 && after + 5 <= len && source.slice(after, after + 5) === 'type ') {
-            const afterType = after + 5;
-            if (afterType < len && source.charCodeAt(afterType) === 123) {
-                pos = afterType;
-                continue;
-            }
-        }
-        let afterMod = after;
-        let changed = true;
-        let sawDefault = false;
-        while (changed && afterMod < len) {
-            changed = false;
-            const ch = source.charCodeAt(afterMod);
-            if (ch === 100 &&
-                afterMod + 8 <= len &&
-                source.slice(afterMod, afterMod + 8) === 'default ') {
-                afterMod += 8;
-                changed = true;
-                sawDefault = true;
-            }
-            else if (ch === 97 &&
-                afterMod + 6 <= len &&
-                source.slice(afterMod, afterMod + 6) === 'async ') {
-                afterMod += 6;
-                changed = true;
-            }
-            else if (ch === 97 &&
-                afterMod + 9 <= len &&
-                source.slice(afterMod, afterMod + 9) === 'abstract ') {
-                afterMod += 9;
-                changed = true;
-            }
-            else if (ch === 116 &&
-                afterMod + 5 <= len &&
-                source.slice(afterMod, afterMod + 5) === 'type ') {
-                afterMod += 5;
-                changed = true;
-            }
-            else if (ch === 110 &&
-                afterMod + 10 <= len &&
-                source.slice(afterMod, afterMod + 10) === 'namespace ') {
-                break;
-            }
-            if (changed) {
-                while (afterMod < len && isWhitespace(source.charCodeAt(afterMod))) {
-                    afterMod++;
-                }
-            }
-        }
-        if (afterMod >= len) {
-            break;
-        }
-        const next = source.charCodeAt(afterMod);
-        // Declaration keyword check (case-insensitive first character):
-        // First chars: f/F=function, c/C=class|const, i/I=interface, e/E=enum, l/L=let, v/V=var, n/N=namespace
-        if (next === 102 ||
-            next === 70 ||
-            next === 99 ||
-            next === 67 ||
-            next === 105 ||
-            next === 73 ||
-            next === 101 ||
-            next === 69 ||
-            next === 108 ||
-            next === 76 ||
-            next === 118 ||
-            next === 86 ||
-            next === 110 ||
-            next === 78) {
-            if (sawDefault) {
-                if (!isDefaultDeclaration(source, afterMod, len)) {
-                    pos = exp + 7;
-                    continue;
-                }
-            }
-            if (!hasJSDocBefore(source, exp)) {
-                return false;
-            }
-        }
-        pos = exp + 7;
-    }
-    return true;
+    return !hasUndocumentedExport(source);
 }
 //# sourceMappingURL=require-function-doc.js.map