@api-extractor-tools/eslint-plugin 0.1.0-alpha.0 → 0.1.0-alpha.2

package/src/rules/valid-enum-type.ts

@@ -0,0 +1,252 @@
+/**
+ * ESLint rule for validating `@enumType` TSDoc tag usage.
+ *
+ * @remarks
+ * This rule validates that `@enumType` tags are:
+ * - Only used on enum declarations or string literal union type aliases
+ * - Have a valid value ('open' or 'closed')
+ * - Not duplicated on a single declaration
+ *
+ * @internal
+ */
+
+import { AST_NODE_TYPES, ESLintUtils, TSESTree } from '@typescript-eslint/utils'
+import { getLeadingTSDocComment, extractEnumType } from '../utils/tsdoc-parser'
+import type { ValidEnumTypeRuleOptions } from '../types'
+
+const createRule = ESLintUtils.RuleCreator(
+  (name) =>
+    `https://github.com/mike-north/api-extractor-tools/blob/main/tools/eslint-plugin/docs/rules/${name}.md`,
+)
+
+type MessageIds =
+  | 'missingValue'
+  | 'invalidValue'
+  | 'multipleEnumTypes'
+  | 'invalidConstruct'
+  | 'missingEnumType'
+
+export const validEnumType = createRule<[ValidEnumTypeRuleOptions], MessageIds>(
+  {
+    name: 'valid-enum-type',
+    meta: {
+      type: 'problem',
+      docs: {
+        description:
+          'Validate @enumType TSDoc tag usage on enums and string literal unions',
+      },
+      messages: {
+        missingValue: '@enumType tag requires a value of "open" or "closed"',
+        invalidValue:
+          '@enumType tag value "{{value}}" is invalid. Use "open" or "closed"',
+        multipleEnumTypes: 'Multiple @enumType tags found. Only one is allowed',
+        invalidConstruct:
+          '@enumType is only valid on enum declarations and string literal union type aliases',
+        missingEnumType:
+          'Exported {{kind}} "{{name}}" is missing @enumType tag. Add @enumType open or @enumType closed',
+      },
+      schema: [
+        {
+          type: 'object',
+          properties: {
+            requireOnExported: {
+              type: 'boolean',
+              description:
+                'Require @enumType on all exported enums and string literal unions',
+            },
+          },
+          additionalProperties: false,
+        },
+      ],
+    },
+    defaultOptions: [{}],
+    create(context) {
+      const options = context.options[0] ?? {}
+      const requireOnExported = options.requireOnExported ?? false
+
+      const sourceCode = context.sourceCode
+
+      /**
+       * Gets the TSDoc comment text for a node, checking both the node and its export parent.
+       */
+      function getTSDocComment(node: TSESTree.Node): string | undefined {
+        // First check the node itself
+        let commentText = getLeadingTSDocComment(sourceCode, node)
+        if (commentText) {
+          return commentText
+        }
+
+        // If node is inside an export, check the export statement
+        const parent = node.parent
+        if (
+          parent?.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+          parent?.type === AST_NODE_TYPES.ExportDefaultDeclaration
+        ) {
+          commentText = getLeadingTSDocComment(sourceCode, parent)
+          if (commentText) {
+            return commentText
+          }
+        }
+
+        return undefined
+      }
+
+      /**
+       * Checks if a node is exported.
+       */
+      function isExported(node: TSESTree.Node): boolean {
+        const parent = node.parent
+        if (parent?.type === AST_NODE_TYPES.ExportNamedDeclaration) {
+          return true
+        }
+        if (parent?.type === AST_NODE_TYPES.ExportDefaultDeclaration) {
+          return true
+        }
+        return false
+      }
+
+      /**
+       * Checks if a type alias is a string literal union.
+       * A string literal union is a union type where all members are string literal types.
+       */
+      function isStringLiteralUnion(
+        typeAnnotation: TSESTree.TypeNode,
+      ): boolean {
+        // Check if it's a union type
+        if (typeAnnotation.type !== AST_NODE_TYPES.TSUnionType) {
+          // Could be a single string literal - that's also valid
+          return (
+            typeAnnotation.type === AST_NODE_TYPES.TSLiteralType &&
+            typeAnnotation.literal.type === AST_NODE_TYPES.Literal &&
+            typeof typeAnnotation.literal.value === 'string'
+          )
+        }
+
+        // All union members must be string literals
+        return typeAnnotation.types.every((member) => {
+          if (member.type === AST_NODE_TYPES.TSLiteralType) {
+            return (
+              member.literal.type === AST_NODE_TYPES.Literal &&
+              typeof member.literal.value === 'string'
+            )
+          }
+          return false
+        })
+      }
+
+      /**
+       * Validates `@enumType` usage on a node that should have it (enum or string literal union).
+       */
+      function validateEnumTypeTag(
+        node: TSESTree.TSEnumDeclaration | TSESTree.TSTypeAliasDeclaration,
+        kind: 'enum' | 'type',
+      ): void {
+        const commentText = getTSDocComment(node)
+        const name = node.id.name
+
+        if (!commentText) {
+          // No TSDoc comment - check if we should require `@enumType`
+          if (requireOnExported && isExported(node)) {
+            context.report({
+              node,
+              messageId: 'missingEnumType',
+              data: { kind, name },
+            })
+          }
+          return
+        }
+
+        const extraction = extractEnumType(commentText)
+
+        if (!extraction.found) {
+          // No @enumType tag - check if we should require it
+          if (requireOnExported && isExported(node)) {
+            context.report({
+              node,
+              messageId: 'missingEnumType',
+              data: { kind, name },
+            })
+          }
+          return
+        }
+
+        // Multiple @enumType tags
+        if (extraction.count > 1) {
+          context.report({
+            node,
+            messageId: 'multipleEnumTypes',
+          })
+          return
+        }
+
+        // @enumType without value
+        if (!extraction.rawValue) {
+          context.report({
+            node,
+            messageId: 'missingValue',
+          })
+          return
+        }
+
+        // Invalid value
+        if (!extraction.isValid) {
+          context.report({
+            node,
+            messageId: 'invalidValue',
+            data: { value: extraction.rawValue },
+          })
+        }
+      }
+
+      /**
+       * Checks for `@enumType` on invalid constructs (non-enum, non-string-literal-union).
+       */
+      function checkInvalidEnumTypeUsage(node: TSESTree.Node): void {
+        const commentText = getTSDocComment(node)
+        if (!commentText) {
+          return
+        }
+
+        const extraction = extractEnumType(commentText)
+        if (extraction.found) {
+          context.report({
+            node,
+            messageId: 'invalidConstruct',
+          })
+        }
+      }
+
+      return {
+        // Check enum declarations - @enumType is valid here
+        TSEnumDeclaration(node): void {
+          validateEnumTypeTag(node, 'enum')
+        },
+
+        // Check type alias declarations
+        TSTypeAliasDeclaration(node): void {
+          if (isStringLiteralUnion(node.typeAnnotation)) {
+            // This is a string literal union - @enumType is valid
+            validateEnumTypeTag(node, 'type')
+          } else {
+            // Not a string literal union - @enumType is invalid
+            checkInvalidEnumTypeUsage(node)
+          }
+        },
+
+        // Check invalid constructs - @enumType should not be on these
+        FunctionDeclaration(node): void {
+          checkInvalidEnumTypeUsage(node)
+        },
+        ClassDeclaration(node): void {
+          checkInvalidEnumTypeUsage(node)
+        },
+        TSInterfaceDeclaration(node): void {
+          checkInvalidEnumTypeUsage(node)
+        },
+        VariableDeclaration(node): void {
+          checkInvalidEnumTypeUsage(node)
+        },
+      }
+    },
+  },
+)

package/src/types.ts

@@ -1,18 +1,21 @@
 /**
  * Types for the API Extractor ESLint plugin.
  *
+ * @remarks
+ * All types in this module are isomorphic - they work in both Node.js and browser environments.
+ *
  * @packageDocumentation
  */
 
 /**
  * Log levels supported by API Extractor message configuration.
- * @public
+ * @alpha
  */
 export type ApiExtractorLogLevel = 'error' | 'warning' | 'none'
 
 /**
  * Configuration for a single message type in API Extractor.
- * @public
+ * @alpha
  */
 export interface MessageConfig {
   logLevel: ApiExtractorLogLevel
@@ -21,7 +24,7 @@ export interface MessageConfig {
 
 /**
  * The messages configuration section from api-extractor.json.
- * @public
+ * @alpha
  */
 export interface ApiExtractorMessagesConfig {
   compilerMessageReporting?: {
@@ -34,6 +37,7 @@ export interface ApiExtractorMessagesConfig {
     'ae-forgotten-export'?: MessageConfig
     'ae-internal-missing-underscore'?: MessageConfig
     'ae-incompatible-release-tags'?: MessageConfig
+    'ae-extra-release-tag'?: MessageConfig
     [messageId: string]: MessageConfig | undefined
   }
   tsdocMessageReporting?: {
@@ -44,7 +48,7 @@ export interface ApiExtractorMessagesConfig {
 
 /**
  * Partial representation of api-extractor.json relevant for this plugin.
- * @public
+ * @alpha
  */
 export interface ApiExtractorConfig {
   extends?: string
@@ -54,13 +58,13 @@ export interface ApiExtractorConfig {
 
 /**
  * Release tags recognized by API Extractor.
- * @public
+ * @alpha
  */
 export type ReleaseTag = 'public' | 'beta' | 'alpha' | 'internal'
 
 /**
  * All valid release tags.
- * @public
+ * @alpha
  */
 export const RELEASE_TAGS: readonly ReleaseTag[] = [
   'public',
@@ -71,34 +75,73 @@ export const RELEASE_TAGS: readonly ReleaseTag[] = [
 
 /**
  * Options for the missing-release-tag rule.
- * @public
+ *
+ * @remarks
+ * All options are explicit - no automatic file discovery.
+ * Node.js users can use the `/node` entry point utilities to read config from disk.
+ *
+ * @alpha
  */
 export interface MissingReleaseTagRuleOptions {
-  configPath?: string
+  /**
+   * Severity level for missing release tags.
+   * - 'error': Report as error
+   * - 'warning': Report as warning (default)
+   * - 'none': Disable the check
+   *
+   * @defaultValue 'warning'
+   */
+  severity?: ApiExtractorLogLevel
 }
 
 /**
  * Options for the override-keyword rule.
- * @public
+ *
+ * @remarks
+ * This rule is purely syntactic and requires no configuration.
+ *
+ * @alpha
  */
-export interface OverrideKeywordRuleOptions {
-  configPath?: string
-}
+export type OverrideKeywordRuleOptions = Record<string, never>
 
 /**
  * Options for the package-documentation rule.
- * @public
+ *
+ * @remarks
+ * Automatically detects whether a file is a package entry point by examining
+ * the nearest package.json. Requires `@packageDocumentation` on barrel files
+ * and reports an error if the tag is found on non-barrel files.
+ *
+ * @alpha
  */
-export interface PackageDocumentationRuleOptions {
-  configPath?: string
-}
+export type PackageDocumentationRuleOptions = Record<string, never>
 
 /**
  * Resolved entry points from package.json.
- * @public
+ * @alpha
  */
 export interface ResolvedEntryPoints {
   main?: string
   types?: string
   exports: string[]
 }
+
+/**
+ * Options for the valid-enum-type rule.
+ *
+ * @remarks
+ * This rule validates `@enumType` TSDoc tag usage on enum declarations
+ * and string literal union type aliases.
+ *
+ * @alpha
+ */
+export interface ValidEnumTypeRuleOptions {
+  /**
+   * Whether to require `@enumType` on all exported enums and string literal unions.
+   * - When true, missing `@enumType` tags on exported enums/unions will be reported
+   * - When false (default), only invalid usage is reported
+   *
+   * @defaultValue false
+   */
+  requireOnExported?: boolean
+}

package/src/utils/config-loader.ts

@@ -192,3 +192,4 @@ export function logLevelToSeverity(logLevel: ApiExtractorLogLevel): 0 | 1 | 2 {
 export function clearConfigCache(): void {
   configCache.clear()
 }
+

package/src/utils/entry-point.ts

@@ -245,3 +245,4 @@ function getSourceEquivalents(filePath: string): string[] {
 export function clearPackageJsonCache(): void {
   packageJsonCache.clear()
 }
+

package/src/utils/tsdoc-parser.ts

@@ -37,6 +37,7 @@ function getParser(): TSDocParser {
  *
  * @param commentText - The full comment text including delimiters
  * @returns Parser context with the parsed doc comment
+ * @alpha
  */
 export function parseTSDocComment(commentText: string): ParserContext {
   const parser = getParser()
@@ -49,6 +50,7 @@ export function parseTSDocComment(commentText: string): ParserContext {
  *
  * @param docComment - The parsed doc comment
  * @returns The release tag if found, undefined otherwise
+ * @alpha
  */
 export function extractReleaseTag(
   docComment: DocComment,
@@ -74,6 +76,7 @@ export function extractReleaseTag(
  *
  * @param docComment - The parsed doc comment
  * @returns True if @override tag is present
+ * @alpha
  */
 export function hasOverrideTag(docComment: DocComment): boolean {
   return docComment.modifierTagSet.isOverride()
@@ -84,11 +87,73 @@ export function hasOverrideTag(docComment: DocComment): boolean {
  *
  * @param docComment - The parsed doc comment
  * @returns True if @packageDocumentation tag is present
+ * @alpha
  */
 export function hasPackageDocumentation(docComment: DocComment): boolean {
   return docComment.modifierTagSet.isPackageDocumentation()
 }
 
+/**
+ * Enum type values for `@enumType` tag.
+ * @alpha
+ */
+export type EnumTypeValue = 'open' | 'closed'
+
+/**
+ * Result of extracting `@enumType` tag from a TSDoc comment.
+ * @alpha
+ */
+export interface EnumTypeExtraction {
+  /** Whether any `@enumType` tags were found */
+  found: boolean
+  /** Number of `@enumType` tags found */
+  count: number
+  /** The extracted value (lowercase), or undefined if missing/invalid */
+  value?: string
+  /** Whether the value is valid ('open' or 'closed') */
+  isValid: boolean
+  /** The original raw value from the comment */
+  rawValue?: string
+}
+
+/**
+ * Extracts `@enumType` tag information from a TSDoc comment.
+ *
+ * @param commentText - The full comment text including delimiters
+ * @returns Extraction result with tag information
+ * @alpha
+ */
+export function extractEnumType(commentText: string): EnumTypeExtraction {
+  const result: EnumTypeExtraction = {
+    found: false,
+    count: 0,
+    isValid: false,
+  }
+
+  // Match @enumType followed by optional whitespace and a word (letters/numbers only)
+  // The value must be a word-like identifier, not * or other punctuation
+  // We use [ \t]+ instead of \s+ to avoid capturing across newlines
+  const enumTypeRegex = /@enumType(?:[ \t]+([a-zA-Z][a-zA-Z0-9]*))?/gi
+  let match: RegExpExecArray | null
+
+  while ((match = enumTypeRegex.exec(commentText)) !== null) {
+    result.count++
+    result.found = true
+
+    // Only capture the first occurrence's value
+    if (result.count === 1) {
+      result.rawValue = match[1]
+      if (match[1]) {
+        const lowerValue = match[1].toLowerCase()
+        result.value = lowerValue
+        result.isValid = lowerValue === 'open' || lowerValue === 'closed'
+      }
+    }
+  }
+
+  return result
+}
+
 /**
  * Checks if a comment is a block comment (TSDoc style).
  */
@@ -104,6 +169,7 @@ function isBlockComment(comment: TSESTree.Comment): boolean {
  * @param sourceCode - ESLint source code object
  * @param node - The AST node to check
  * @returns The comment text if a TSDoc comment exists, undefined otherwise
+ * @alpha
  */
 export function getLeadingTSDocComment(
   sourceCode: {
@@ -142,6 +208,7 @@ export function getLeadingTSDocComment(
  *
  * @param sourceCode - ESLint source code object
  * @returns Array of comment objects with their parsed content
+ * @alpha
  */
 export function findAllTSDocComments(sourceCode: {
   getAllComments: () => TSESTree.Comment[]