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

package/src/rules/incompatible-release-tags.ts

@@ -0,0 +1,331 @@
+/**
+ * ESLint rule for detecting incompatible release tags.
+ *
+ * @remarks
+ * This rule detects when an exported API with a specific release tag references
+ * another symbol with a less visible release tag. For example, a @public API
+ * should not reference an @internal type.
+ *
+ * @internal
+ */
+
+import { AST_NODE_TYPES, ESLintUtils, TSESTree } from '@typescript-eslint/utils'
+import {
+  getLeadingTSDocComment,
+  parseTSDocComment,
+  extractReleaseTag,
+} from '../utils/tsdoc-parser'
+import type { ApiExtractorLogLevel, ReleaseTag } 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 = 'incompatibleReleaseTags'
+
+/**
+ * Options for the incompatible-release-tags rule.
+ * @alpha
+ */
+export interface IncompatibleReleaseTagsRuleOptions {
+  /**
+   * Severity level for incompatible release tags.
+   * @defaultValue 'warning'
+   */
+  severity?: ApiExtractorLogLevel
+}
+
+// Release tag visibility levels (higher = more visible)
+const RELEASE_TAG_LEVELS: Record<ReleaseTag, number> = {
+  internal: 0,
+  alpha: 1,
+  beta: 2,
+  public: 3,
+}
+
+export const incompatibleReleaseTags = createRule<
+  [IncompatibleReleaseTagsRuleOptions],
+  MessageIds
+>({
+  name: 'incompatible-release-tags',
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require that exported APIs do not reference symbols with less visible release tags',
+    },
+    messages: {
+      incompatibleReleaseTags:
+        'The {{exportedTag}} API "{{exportedName}}" references the {{referencedTag}} symbol "{{referencedName}}". Referenced symbols must be at least as visible as the API that uses them.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          severity: {
+            type: 'string',
+            enum: ['error', 'warning', 'none'],
+            description: 'Severity level for incompatible release tags',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [{}],
+  create(context) {
+    const options = context.options[0] ?? {}
+    const severity = options.severity ?? 'warning'
+
+    // If severity is 'none', disable the rule
+    if (severity === 'none') {
+      return {}
+    }
+
+    const sourceCode = context.sourceCode
+    const symbolReleaseTags = new Map<string, ReleaseTag>()
+    const exportedSymbols = new Map<
+      string,
+      { tag: ReleaseTag; node: TSESTree.Node }
+    >()
+
+    /**
+     * Gets the release tag for a node.
+     */
+    function getReleaseTag(node: TSESTree.Node): ReleaseTag | undefined {
+      const commentText = getLeadingTSDocComment(sourceCode, node)
+      if (!commentText) {
+        return undefined
+      }
+
+      const parsed = parseTSDocComment(commentText)
+      if (parsed.docComment) {
+        return extractReleaseTag(parsed.docComment)
+      }
+
+      return undefined
+    }
+
+    /**
+     * 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
+    }
+
+    /**
+     * Checks if a release tag is compatible.
+     */
+    function isCompatible(
+      exportedTag: ReleaseTag,
+      referencedTag: ReleaseTag,
+    ): boolean {
+      return (
+        RELEASE_TAG_LEVELS[referencedTag] >= RELEASE_TAG_LEVELS[exportedTag]
+      )
+    }
+
+    /**
+     * Collects release tags for all declarations.
+     */
+    function collectSymbolReleaseTag(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ClassDeclaration
+        | TSESTree.TSInterfaceDeclaration
+        | TSESTree.TSTypeAliasDeclaration
+        | TSESTree.TSEnumDeclaration
+        | TSESTree.VariableDeclaration,
+    ): void {
+      const name = getDeclarationName(node)
+      if (!name) return
+
+      const tag = getReleaseTag(node)
+      if (tag) {
+        symbolReleaseTags.set(name, tag)
+      }
+    }
+
+    /**
+     * Checks if a node is exported.
+     */
+    function isExported(node: TSESTree.Node): boolean {
+      const parent = node.parent
+      return (
+        parent?.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+        parent?.type === AST_NODE_TYPES.ExportDefaultDeclaration
+      )
+    }
+
+    /**
+     * Checks type references for incompatible release tags.
+     */
+    function checkTypeReferences(
+      node: TSESTree.Node,
+      exportedName: string,
+      exportedTag: ReleaseTag,
+    ): void {
+      const visited = new WeakSet<object>()
+
+      // Helper to recursively find type references
+      function findTypeReferences(n: TSESTree.Node): void {
+        // Avoid infinite recursion
+        if (visited.has(n)) {
+          return
+        }
+        visited.add(n)
+
+        if (n.type === AST_NODE_TYPES.TSTypeReference) {
+          const typeName = n.typeName
+          if (typeName.type === AST_NODE_TYPES.Identifier) {
+            const referencedName = typeName.name
+            const referencedTag = symbolReleaseTags.get(referencedName)
+
+            if (referencedTag && !isCompatible(exportedTag, referencedTag)) {
+              context.report({
+                node: n,
+                messageId: 'incompatibleReleaseTags',
+                data: {
+                  exportedName,
+                  exportedTag: `@${exportedTag}`,
+                  referencedName,
+                  referencedTag: `@${referencedTag}`,
+                },
+              })
+            }
+          }
+        }
+
+        // Recursively check child nodes, but skip 'parent' property to avoid cycles
+        for (const key in n) {
+          if (key === 'parent') {
+            continue
+          }
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+          const child = (n as any)[key]
+          if (child && typeof child === 'object') {
+            if (Array.isArray(child)) {
+              for (const item of child) {
+                if (item && typeof item === 'object' && 'type' in item) {
+                  // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+                  findTypeReferences(item)
+                }
+              }
+            } else if ('type' in child) {
+              // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+              findTypeReferences(child)
+            }
+          }
+        }
+      }
+
+      findTypeReferences(node)
+    }
+
+    /**
+     * Checks a declaration for incompatible release tags.
+     */
+    function checkDeclaration(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ClassDeclaration
+        | TSESTree.TSInterfaceDeclaration
+        | TSESTree.TSTypeAliasDeclaration
+        | TSESTree.TSEnumDeclaration
+        | TSESTree.VariableDeclaration,
+    ): void {
+      if (!isExported(node)) {
+        return
+      }
+
+      const name = getDeclarationName(node)
+      if (!name) return
+
+      // Check both the export statement and the declaration for the comment
+      const exportNode = node.parent
+      const nodeToCheck = exportNode ?? node
+
+      const tag = getReleaseTag(nodeToCheck) ?? getReleaseTag(node)
+      if (tag) {
+        exportedSymbols.set(name, { tag, node })
+        checkTypeReferences(node, name, tag)
+      }
+    }
+
+    const declarationsToCheck: Array<{
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ClassDeclaration
+        | TSESTree.TSInterfaceDeclaration
+        | TSESTree.TSTypeAliasDeclaration
+        | TSESTree.TSEnumDeclaration
+        | TSESTree.VariableDeclaration
+    }> = []
+
+    return {
+      FunctionDeclaration(node): void {
+        collectSymbolReleaseTag(node)
+        if (isExported(node)) {
+          declarationsToCheck.push({ node })
+        }
+      },
+      ClassDeclaration(node): void {
+        collectSymbolReleaseTag(node)
+        if (isExported(node)) {
+          declarationsToCheck.push({ node })
+        }
+      },
+      TSInterfaceDeclaration(node): void {
+        collectSymbolReleaseTag(node)
+        if (isExported(node)) {
+          declarationsToCheck.push({ node })
+        }
+      },
+      TSTypeAliasDeclaration(node): void {
+        collectSymbolReleaseTag(node)
+        if (isExported(node)) {
+          declarationsToCheck.push({ node })
+        }
+      },
+      TSEnumDeclaration(node): void {
+        collectSymbolReleaseTag(node)
+        if (isExported(node)) {
+          declarationsToCheck.push({ node })
+        }
+      },
+      VariableDeclaration(node): void {
+        collectSymbolReleaseTag(node)
+        if (isExported(node)) {
+          declarationsToCheck.push({ node })
+        }
+      },
+      'Program:exit'(): void {
+        // Check all exported declarations after collecting all tags
+        for (const { node } of declarationsToCheck) {
+          checkDeclaration(node)
+        }
+      },
+    }
+  },
+})

package/src/rules/index.ts

@@ -6,13 +6,25 @@
 import { missingReleaseTag } from './missing-release-tag'
 import { overrideKeyword } from './override-keyword'
 import { packageDocumentation } from './package-documentation'
+import { forgottenExport } from './forgotten-export'
+import { incompatibleReleaseTags } from './incompatible-release-tags'
+import { extraReleaseTag } from './extra-release-tag'
+import { publicOnPrivateMember } from './public-on-private-member'
+import { publicOnNonExported } from './public-on-non-exported'
+import { validEnumType } from './valid-enum-type'
 
 /**
  * All available ESLint rules.
- * @public
+ * @alpha
  */
 export const rules = {
   'missing-release-tag': missingReleaseTag,
   'override-keyword': overrideKeyword,
   'package-documentation': packageDocumentation,
+  'forgotten-export': forgottenExport,
+  'incompatible-release-tags': incompatibleReleaseTags,
+  'extra-release-tag': extraReleaseTag,
+  'public-on-private-member': publicOnPrivateMember,
+  'public-on-non-exported': publicOnNonExported,
+  'valid-enum-type': validEnumType,
 } as const

package/src/rules/missing-release-tag.ts

@@ -1,16 +1,18 @@
 /**
  * ESLint rule for detecting missing release tags on exported symbols.
+ *
+ * @remarks
+ * Configuration is provided explicitly via rule options.
+ *
  * @internal
  */
 
 import { AST_NODE_TYPES, ESLintUtils, TSESTree } from '@typescript-eslint/utils'
 import {
-  resolveConfig,
-  getMessageLogLevel,
   getLeadingTSDocComment,
   parseTSDocComment,
   extractReleaseTag,
-} from '../utils'
+} from '../utils/tsdoc-parser'
 import type { MissingReleaseTagRuleOptions } from '../types'
 
 const createRule = ESLintUtils.RuleCreator(
@@ -39,9 +41,10 @@ export const missingReleaseTag = createRule<
       {
         type: 'object',
         properties: {
-          configPath: {
+          severity: {
             type: 'string',
-            description: 'Path to api-extractor.json configuration file',
+            enum: ['error', 'warning', 'none'],
+            description: 'Severity level for missing release tags',
           },
         },
         additionalProperties: false,
@@ -51,12 +54,10 @@ export const missingReleaseTag = createRule<
   defaultOptions: [{}],
   create(context) {
     const options = context.options[0] ?? {}
-    const filename = context.filename
-    const config = resolveConfig(filename, options.configPath)
-    const logLevel = getMessageLogLevel(config, 'ae-missing-release-tag')
+    const severity = options.severity ?? 'warning'
 
-    // If configured to 'none', disable the rule
-    if (logLevel === 'none') {
+    // If severity is 'none', disable the rule
+    if (severity === 'none') {
       return {}
     }
 
@@ -164,40 +165,24 @@ export const missingReleaseTag = createRule<
     }
 
     return {
-      // Check exported function declarations
       FunctionDeclaration(node): void {
         checkDeclaration(node)
       },
-
-      // Check exported class declarations
       ClassDeclaration(node): void {
         checkDeclaration(node)
       },
-
-      // Check exported interface declarations
       TSInterfaceDeclaration(node): void {
         checkDeclaration(node)
       },
-
-      // Check exported type alias declarations
       TSTypeAliasDeclaration(node): void {
         checkDeclaration(node)
       },
-
-      // Check exported enum declarations
       TSEnumDeclaration(node): void {
         checkDeclaration(node)
       },
-
-      // Check exported variable declarations
       VariableDeclaration(node): void {
         checkDeclaration(node)
       },
-
-      // Note: We intentionally don't handle ExportNamedDeclaration with specifiers
-      // (e.g., `export { foo }` or `export { foo } from './bar'`) because:
-      // - Re-exports should have release tags on the original declaration
-      // - Named exports reference declarations that are checked elsewhere
     }
   },
 })

package/src/rules/override-keyword.ts

@@ -1,5 +1,9 @@
 /**
  * ESLint rule requiring the TypeScript `override` keyword when `@override` TSDoc tag is used.
+ *
+ * @remarks
+ * It is purely syntactic and requires no configuration.
+ *
  * @internal
  */
 
@@ -8,7 +12,7 @@ import {
   getLeadingTSDocComment,
   parseTSDocComment,
   hasOverrideTag,
-} from '../utils'
+} from '../utils/tsdoc-parser'
 import type { OverrideKeywordRuleOptions } from '../types'
 
 const createRule = ESLintUtils.RuleCreator(
@@ -37,12 +41,7 @@ export const overrideKeyword = createRule<
     schema: [
       {
         type: 'object',
-        properties: {
-          configPath: {
-            type: 'string',
-            description: 'Path to api-extractor.json configuration file',
-          },
-        },
+        properties: {},
         additionalProperties: false,
       },
     ],
@@ -121,7 +120,6 @@ export const overrideKeyword = createRule<
         messageId: 'missingOverrideKeyword',
         data: { name },
         fix(fixer) {
-          // Insert override keyword at the start of the member declaration
           return fixer.insertTextBefore(node, 'override ')
         },
       })

package/src/rules/package-documentation.ts

@@ -1,15 +1,13 @@
 /**
- * ESLint rule requiring @packageDocumentation in package entry point files.
+ * ESLint rule requiring @packageDocumentation in files.
  * @internal
  */
 
 import { ESLintUtils } from '@typescript-eslint/utils'
 import {
-  findPackageJson,
-  isEntryPoint,
   findAllTSDocComments,
   hasPackageDocumentation,
-} from '../utils'
+} from '../utils/tsdoc-parser'
 import type { PackageDocumentationRuleOptions } from '../types'
 
 const createRule = ESLintUtils.RuleCreator(
@@ -27,58 +25,34 @@ export const packageDocumentation = createRule<
   meta: {
     type: 'suggestion',
     docs: {
-      description:
-        'Require @packageDocumentation tag in package entry point files',
+      description: 'Require @packageDocumentation tag in files',
     },
     messages: {
       missingPackageDocumentation:
-        'Entry point file is missing a @packageDocumentation comment. Add a TSDoc comment with @packageDocumentation at the top of the file.',
+        'File is missing a @packageDocumentation comment. Add a TSDoc comment with @packageDocumentation at the top of the file.',
     },
     schema: [
       {
         type: 'object',
-        properties: {
-          configPath: {
-            type: 'string',
-            description: 'Path to api-extractor.json configuration file',
-          },
-        },
+        properties: {},
         additionalProperties: false,
       },
     ],
   },
   defaultOptions: [{}],
   create(context) {
-    const filename = context.filename
     const sourceCode = context.sourceCode
 
-    // Find package.json
-    const pkgPath = findPackageJson(filename)
-    if (!pkgPath) {
-      // No package.json found, nothing to check
-      return {}
-    }
-
-    // Check if this file is an entry point
-    if (!isEntryPoint(filename, pkgPath)) {
-      // Not an entry point, skip
-      return {}
-    }
-
     return {
       Program(node): void {
-        // Look for @packageDocumentation in any TSDoc comment in the file
         const tsdocComments = findAllTSDocComments(sourceCode)
 
         for (const { parsed } of tsdocComments) {
           if (parsed.docComment && hasPackageDocumentation(parsed.docComment)) {
-            // Found @packageDocumentation, all good
             return
           }
         }
 
-        // No @packageDocumentation found
-        // Report at the first line of the file
         context.report({
           node,
           loc: { line: 1, column: 0 },