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

package/src/rules/public-on-non-exported.ts

@@ -0,0 +1,265 @@
+/**
+ * ESLint rule preventing the use of @public tag on non-exported symbols.
+ *
+ * @remarks
+ * The @public tag indicates that a symbol is part of the public API, but non-exported
+ * symbols cannot be accessed by consumers and should not be marked as public.
+ *
+ * @internal
+ */
+
+import { AST_NODE_TYPES, ESLintUtils, TSESTree } from '@typescript-eslint/utils'
+import {
+  getLeadingTSDocComment,
+  parseTSDocComment,
+  extractReleaseTag,
+} from '../utils/tsdoc-parser'
+import type { ApiExtractorLogLevel } 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 = 'publicOnNonExported'
+
+/**
+ * Options for the public-on-non-exported rule.
+ * @alpha
+ */
+export interface PublicOnNonExportedRuleOptions {
+  /**
+   * Severity level for public tags on non-exported symbols.
+   * @defaultValue 'error'
+   */
+  severity?: ApiExtractorLogLevel
+}
+
+export const publicOnNonExported = createRule<
+  [PublicOnNonExportedRuleOptions],
+  MessageIds
+>({
+  name: 'public-on-non-exported',
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Prevent the use of @public tag on symbols that are not exported',
+    },
+    messages: {
+      publicOnNonExported:
+        'Symbol "{{name}}" has the @public tag but is not exported. Only exported symbols can be marked as @public.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          severity: {
+            type: 'string',
+            enum: ['error', 'warning', 'none'],
+            description:
+              'Severity level for public tags on non-exported symbols',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [{}],
+  create(context) {
+    const options = context.options[0] ?? {}
+    const severity = options.severity ?? 'error'
+
+    // If severity is 'none', disable the rule
+    if (severity === 'none') {
+      return {}
+    }
+
+    const sourceCode = context.sourceCode
+    const exportedSymbols = new Set<string>()
+    const symbolsWithPublicTag = new Map<
+      string,
+      { node: TSESTree.Node; name: string }
+    >()
+
+    /**
+     * Checks if a node has the @public release tag.
+     */
+    function hasPublicTag(node: TSESTree.Node): boolean {
+      const commentText = getLeadingTSDocComment(sourceCode, node)
+      if (!commentText) {
+        return false
+      }
+
+      const parsed = parseTSDocComment(commentText)
+      if (parsed.docComment) {
+        const tag = extractReleaseTag(parsed.docComment)
+        return tag === 'public'
+      }
+
+      return false
+    }
+
+    /**
+     * Gets the name of a declaration.
+     */
+    function getDeclarationName(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ClassDeclaration
+        | TSESTree.TSInterfaceDeclaration
+        | TSESTree.TSTypeAliasDeclaration
+        | TSESTree.TSEnumDeclaration
+        | TSESTree.VariableDeclaration,
+    ): string | undefined {
+      if (node.type === AST_NODE_TYPES.VariableDeclaration) {
+        const firstDeclarator = node.declarations[0]
+        if (firstDeclarator?.id.type === AST_NODE_TYPES.Identifier) {
+          return firstDeclarator.id.name
+        }
+        return undefined
+      }
+
+      if ('id' in node && node.id) {
+        return node.id.name
+      }
+
+      return undefined
+    }
+
+    /**
+     * Collects all exported symbol names.
+     */
+    function collectExportedSymbols(
+      node: TSESTree.ExportNamedDeclaration | TSESTree.ExportDefaultDeclaration,
+    ): void {
+      if (node.type === AST_NODE_TYPES.ExportNamedDeclaration) {
+        // export { foo, bar }
+        if (node.specifiers) {
+          for (const specifier of node.specifiers) {
+            if (specifier.type === AST_NODE_TYPES.ExportSpecifier) {
+              if (specifier.exported.type === AST_NODE_TYPES.Identifier) {
+                exportedSymbols.add(specifier.exported.name)
+              }
+              // Also add the local name in case it's different
+              if (specifier.local.type === AST_NODE_TYPES.Identifier) {
+                exportedSymbols.add(specifier.local.name)
+              }
+            }
+          }
+        }
+
+        // export function foo() {} or export class Bar {}
+        if (node.declaration) {
+          const decl = node.declaration
+          if (
+            'id' in decl &&
+            decl.id &&
+            decl.id.type === AST_NODE_TYPES.Identifier
+          ) {
+            exportedSymbols.add(decl.id.name)
+          } else if (decl.type === AST_NODE_TYPES.VariableDeclaration) {
+            for (const declarator of decl.declarations) {
+              if (declarator.id.type === AST_NODE_TYPES.Identifier) {
+                exportedSymbols.add(declarator.id.name)
+              }
+            }
+          }
+        }
+      }
+    }
+
+    /**
+     * Checks if a node is directly exported.
+     */
+    function isDirectlyExported(node: TSESTree.Node): boolean {
+      const parent = node.parent
+      return (
+        parent?.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+        parent?.type === AST_NODE_TYPES.ExportDefaultDeclaration
+      )
+    }
+
+    /**
+     * Collects symbols with @public tag.
+     */
+    function collectSymbolWithPublicTag(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ClassDeclaration
+        | TSESTree.TSInterfaceDeclaration
+        | TSESTree.TSTypeAliasDeclaration
+        | TSESTree.TSEnumDeclaration
+        | TSESTree.VariableDeclaration,
+    ): void {
+      // Check if the node has @public tag
+      if (!hasPublicTag(node) && !isDirectlyExported(node)) {
+        // Check if the export has the tag
+        const parent = node.parent
+        if (
+          parent &&
+          (parent.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+            parent.type === AST_NODE_TYPES.ExportDefaultDeclaration)
+        ) {
+          if (!hasPublicTag(parent)) {
+            return
+          }
+        } else {
+          return
+        }
+      }
+
+      const name = getDeclarationName(node)
+      if (name && hasPublicTag(node)) {
+        symbolsWithPublicTag.set(name, { node, name })
+      }
+    }
+
+    return {
+      ExportNamedDeclaration(node): void {
+        collectExportedSymbols(node)
+      },
+
+      ExportDefaultDeclaration(node): void {
+        collectExportedSymbols(node)
+      },
+
+      FunctionDeclaration(node): void {
+        collectSymbolWithPublicTag(node)
+      },
+
+      ClassDeclaration(node): void {
+        collectSymbolWithPublicTag(node)
+      },
+
+      TSInterfaceDeclaration(node): void {
+        collectSymbolWithPublicTag(node)
+      },
+
+      TSTypeAliasDeclaration(node): void {
+        collectSymbolWithPublicTag(node)
+      },
+
+      TSEnumDeclaration(node): void {
+        collectSymbolWithPublicTag(node)
+      },
+
+      VariableDeclaration(node): void {
+        collectSymbolWithPublicTag(node)
+      },
+
+      'Program:exit'(): void {
+        // Check for @public on non-exported symbols
+        for (const [name, { node }] of symbolsWithPublicTag) {
+          if (!exportedSymbols.has(name)) {
+            context.report({
+              node,
+              messageId: 'publicOnNonExported',
+              data: { name },
+            })
+          }
+        }
+      },
+    }
+  },
+})

package/src/rules/public-on-private-member.ts

@@ -0,0 +1,157 @@
+/**
+ * ESLint rule preventing the use of @public tag on private or protected class members.
+ *
+ * @remarks
+ * Private and protected members cannot be public API since they are not accessible
+ * outside the class or to external consumers.
+ *
+ * @internal
+ */
+
+import { AST_NODE_TYPES, ESLintUtils, TSESTree } from '@typescript-eslint/utils'
+import {
+  getLeadingTSDocComment,
+  parseTSDocComment,
+  extractReleaseTag,
+} from '../utils/tsdoc-parser'
+import type { ApiExtractorLogLevel } 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 = 'publicOnPrivateMember'
+
+/**
+ * Options for the public-on-private-member rule.
+ * @alpha
+ */
+export interface PublicOnPrivateMemberRuleOptions {
+  /**
+   * Severity level for public tags on private/protected members.
+   * @defaultValue 'error'
+   */
+  severity?: ApiExtractorLogLevel
+}
+
+export const publicOnPrivateMember = createRule<
+  [PublicOnPrivateMemberRuleOptions],
+  MessageIds
+>({
+  name: 'public-on-private-member',
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Prevent the use of @public tag on private or protected class members',
+    },
+    messages: {
+      publicOnPrivateMember:
+        '{{accessibility}} member "{{name}}" cannot have the @public tag. Only public members can be marked as @public.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          severity: {
+            type: 'string',
+            enum: ['error', 'warning', 'none'],
+            description:
+              'Severity level for public tags on private/protected members',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [{}],
+  create(context) {
+    const options = context.options[0] ?? {}
+    const severity = options.severity ?? 'error'
+
+    // If severity is 'none', disable the rule
+    if (severity === 'none') {
+      return {}
+    }
+
+    const sourceCode = context.sourceCode
+
+    /**
+     * Checks if a node has the @public release tag.
+     */
+    function hasPublicTag(node: TSESTree.Node): boolean {
+      const commentText = getLeadingTSDocComment(sourceCode, node)
+      if (!commentText) {
+        return false
+      }
+
+      const parsed = parseTSDocComment(commentText)
+      if (parsed.docComment) {
+        const tag = extractReleaseTag(parsed.docComment)
+        return tag === 'public'
+      }
+
+      return false
+    }
+
+    /**
+     * Gets the name of a member.
+     */
+    function getMemberName(
+      node: TSESTree.PropertyDefinition | TSESTree.MethodDefinition,
+    ): string {
+      if (node.key.type === AST_NODE_TYPES.Identifier) {
+        return node.key.name
+      }
+      if (
+        node.key.type === AST_NODE_TYPES.Literal &&
+        typeof node.key.value === 'string'
+      ) {
+        return node.key.value
+      }
+      return '<computed>'
+    }
+
+    /**
+     * Checks a class member for @public tag on private/protected members.
+     */
+    function checkClassMember(
+      node: TSESTree.PropertyDefinition | TSESTree.MethodDefinition,
+    ): void {
+      // Skip if not private or protected
+      if (
+        node.accessibility !== 'private' &&
+        node.accessibility !== 'protected'
+      ) {
+        return
+      }
+
+      // Check if it has @public tag
+      if (hasPublicTag(node)) {
+        const name = getMemberName(node)
+        const accessibility =
+          node.accessibility.charAt(0).toUpperCase() +
+          node.accessibility.slice(1)
+
+        context.report({
+          node,
+          messageId: 'publicOnPrivateMember',
+          data: {
+            name,
+            accessibility,
+          },
+        })
+      }
+    }
+
+    return {
+      PropertyDefinition(node): void {
+        checkClassMember(node)
+      },
+      MethodDefinition(node): void {
+        checkClassMember(node)
+      },
+    }
+  },
+})

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)
+        },
+      }
+    },
+  },
+)