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

package/docs/rules/valid-enum-type.md

@@ -0,0 +1,153 @@
+# valid-enum-type
+
+Validates the usage of the `@enumType` TSDoc tag on enum declarations and string literal union type aliases.
+
+## Rule Details
+
+The `@enumType` tag is used to specify whether an enum or string literal union is "open" (new members may be added) or "closed" (the set of members is fixed). This information is used by the change detector to properly classify API changes.
+
+This rule ensures that:
+
+- `@enumType` tags have a valid value (`open` or `closed`)
+- `@enumType` tags are not duplicated
+- `@enumType` tags are only used on valid constructs (enums and string literal unions)
+- Optionally, exported enums and string literal unions have an `@enumType` tag
+
+## Options
+
+```json
+{
+  "@api-extractor-tools/valid-enum-type": [
+    "warn",
+    {
+      "requireOnExported": false
+    }
+  ]
+}
+```
+
+### `requireOnExported`
+
+Type: `boolean`
+Default: `false`
+
+When `true`, requires all exported enums and string literal union type aliases to have an `@enumType` tag.
+
+## Examples
+
+### ❌ Incorrect
+
+```ts
+// Missing value
+/**
+ * @enumType
+ */
+export enum Status {
+  Active,
+  Inactive,
+}
+
+// Invalid value
+/**
+ * @enumType invalid
+ */
+export enum Status {
+  Active,
+  Inactive,
+}
+
+// Multiple @enumType tags
+/**
+ * @enumType open
+ * @enumType closed
+ */
+export enum Status {
+  Active,
+  Inactive,
+}
+
+// @enumType on invalid construct
+/**
+ * @enumType open
+ */
+export function myFunction(): void {}
+
+// @enumType on non-string-literal union
+/**
+ * @enumType open
+ */
+export type NumberUnion = 1 | 2 | 3
+
+// With requireOnExported: true - missing @enumType
+export enum Status {
+  Active,
+  Inactive,
+}
+```
+
+### ✅ Correct
+
+```ts
+// Open enum - new members may be added in future versions
+/**
+ * Status values for a resource.
+ * @enumType open
+ * @public
+ */
+export enum Status {
+  Active = 'active',
+  Inactive = 'inactive',
+}
+
+// Closed enum - the set of members is fixed
+/**
+ * Boolean-like values.
+ * @enumType closed
+ * @public
+ */
+export enum YesNo {
+  Yes = 'yes',
+  No = 'no',
+}
+
+// String literal union with @enumType
+/**
+ * Supported color values.
+ * @enumType open
+ * @public
+ */
+export type Color = 'red' | 'green' | 'blue'
+
+// Single string literal (also valid)
+/**
+ * The only supported format.
+ * @enumType closed
+ * @public
+ */
+export type Format = 'json'
+
+// Without requireOnExported, missing @enumType is allowed
+export enum InternalStatus {
+  Pending,
+  Complete,
+}
+```
+
+## When to Use
+
+Use this rule when:
+
+- You use the `@enumType` tag to document enum semantics
+- You want to ensure consistent and valid `@enumType` usage
+- You want to require `@enumType` on all exported enums (with `requireOnExported: true`)
+
+## When Not to Use
+
+You might want to disable this rule if:
+
+- You don't use the `@enumType` tag in your codebase
+- You're not using the change detector that processes this tag
+
+## Related
+
+- [Open/Closed Enum Semantics](https://github.com/mike-north/api-extractor-tools/issues/127) - Epic describing the enum type feature

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "@api-extractor-tools/eslint-plugin",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.2",
   "description": "ESLint plugin providing authoring-time feedback for API Extractor",
   "main": "dist/index.js",
   "types": "dist/eslint-plugin-public.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/eslint-plugin-public.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    }
+  },
   "keywords": [
     "eslint",
     "eslint-plugin",
@@ -18,26 +28,30 @@
     "typescript": ">=5.5.0"
   },
   "dependencies": {
-    "@microsoft/tsdoc": "^0.15.1",
-    "@typescript-eslint/utils": "^8.48.1"
+    "@microsoft/tsdoc": "^0.15.1"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.55.1",
     "@types/node": "^22.10.2",
     "@typescript-eslint/parser": "^8.48.1",
     "@typescript-eslint/rule-tester": "^8.48.1",
+    "@typescript-eslint/utils": "^8.48.1",
+    "@vitest/coverage-v8": "^4.0.15",
     "eslint": "^9.39.1",
+    "tsd": "^0.33.0",
     "typescript": "5.8.3",
-    "@vitest/coverage-v8": "^4.0.15",
-    "vitest": "^4.0.15"
+    "vitest": "^4.0.15",
+    "@api-extractor-tools/declaration-file-normalizer": "0.1.0-alpha.6"
   },
   "scripts": {
-    "build": "tsc",
+    "clean": "rm -rf dist",
+    "build": "tsc && node ../declaration-file-normalizer/dist/cli.js dist/index.d.ts",
     "generate:api-report": "api-extractor run --local --verbose",
-    "test": "vitest run",
+    "test": "vitest run && pnpm test:types",
+    "test:types": "tsd --files 'test/**/*.test-d.ts' --typings src/index.ts",
     "test:coverage": "vitest run --coverage",
     "check": "pnpm check:eslint && pnpm check:typecheck-tests && pnpm check:api-report",
-    "check:eslint": "eslint src",
+    "check:eslint": "eslint src test",
     "check:typecheck-tests": "tsc -p test/tsconfig.json",
     "check:api-report": "api-extractor run"
   }

package/src/configs/recommended.ts

@@ -13,12 +13,18 @@ import type { TSESLint } from '@typescript-eslint/utils'
 /**
  * Recommended rule configuration.
  * These are the rules enabled by default with appropriate severity.
- * @public
+ * @alpha
  */
 export const recommendedRules: TSESLint.Linter.RulesRecord = {
   '@api-extractor-tools/missing-release-tag': 'warn',
   '@api-extractor-tools/override-keyword': 'error',
   '@api-extractor-tools/package-documentation': 'warn',
+  '@api-extractor-tools/forgotten-export': 'warn',
+  '@api-extractor-tools/incompatible-release-tags': 'warn',
+  '@api-extractor-tools/extra-release-tag': 'error',
+  '@api-extractor-tools/public-on-private-member': 'error',
+  '@api-extractor-tools/public-on-non-exported': 'error',
+  '@api-extractor-tools/valid-enum-type': 'warn',
 }
 
 /**

package/src/index.ts

@@ -1,10 +1,6 @@
 /**
  * ESLint plugin providing authoring-time feedback for API Extractor.
  *
- * @remarks
- * This plugin provides ESLint rules that mirror API Extractor's validations,
- * enabling developers to catch issues during development rather than at build time.
- *
  * @example
  * Using with flat config (eslint.config.js):
  * ```js
@@ -12,15 +8,6 @@
  *
  * export default [
  *   apiExtractorPlugin.configs.recommended,
- *   // Or configure rules individually:
- *   {
- *     plugins: {
- *       '@api-extractor-tools': apiExtractorPlugin,
- *     },
- *     rules: {
- *       '@api-extractor-tools/missing-release-tag': 'error',
- *     },
- *   },
  * ];
  * ```
  *
@@ -51,10 +38,29 @@ export type {
   OverrideKeywordRuleOptions,
   PackageDocumentationRuleOptions,
   ResolvedEntryPoints,
+  ValidEnumTypeRuleOptions,
 } from './types'
+export type { ForgottenExportRuleOptions } from './rules/forgotten-export'
+export type { IncompatibleReleaseTagsRuleOptions } from './rules/incompatible-release-tags'
+export type { ExtraReleaseTagRuleOptions } from './rules/extra-release-tag'
+export type { PublicOnPrivateMemberRuleOptions } from './rules/public-on-private-member'
+export type { PublicOnNonExportedRuleOptions } from './rules/public-on-non-exported'
 
 export { RELEASE_TAGS } from './types'
 
+// Re-export TSDoc utilities (browser-safe)
+export {
+  parseTSDocComment,
+  extractReleaseTag,
+  hasOverrideTag,
+  hasPackageDocumentation,
+  getLeadingTSDocComment,
+  findAllTSDocComments,
+  extractEnumType,
+  type EnumTypeValue,
+  type EnumTypeExtraction,
+} from './utils/tsdoc-parser'
+
 /**
  * Plugin configuration type.
  * @internal
@@ -69,7 +75,7 @@ interface PluginConfigs {
 
 /**
  * The ESLint plugin type.
- * @public
+ * @alpha
  */
 export interface ApiExtractorEslintPlugin {
   meta: {
@@ -82,7 +88,7 @@ export interface ApiExtractorEslintPlugin {
 
 /**
  * The ESLint plugin object.
- * @public
+ * @alpha
  */
 const plugin: ApiExtractorEslintPlugin = {
   meta: {

package/src/node.ts

@@ -0,0 +1,50 @@
+/**
+ * Node.js-specific utilities for the ESLint plugin.
+ *
+ * @remarks
+ * These utilities require Node.js file system access. Use them to:
+ * - Load api-extractor.json configuration
+ * - Discover configuration file locations
+ * - Determine package entry points
+ *
+ * @example
+ * ```ts
+ * import {
+ *   findApiExtractorConfig,
+ *   loadApiExtractorConfig,
+ *   getMessageLogLevel,
+ * } from '@api-extractor-tools/eslint-plugin/node';
+ *
+ * const configPath = findApiExtractorConfig(__dirname);
+ * const config = configPath ? loadApiExtractorConfig(configPath) : null;
+ * const severity = getMessageLogLevel(config, 'ae-missing-release-tag');
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export {
+  findApiExtractorConfig,
+  loadApiExtractorConfig,
+  resolveConfig,
+  getMessageLogLevel,
+  logLevelToSeverity,
+  clearConfigCache,
+} from './utils/config-loader'
+
+export {
+  findPackageJson,
+  loadPackageJson,
+  resolveEntryPoints,
+  isEntryPoint,
+  clearPackageJsonCache,
+} from './utils/entry-point'
+
+// Re-export types that are useful for Node.js consumers
+export type {
+  ApiExtractorConfig,
+  ApiExtractorLogLevel,
+  ApiExtractorMessagesConfig,
+  MessageConfig,
+  ResolvedEntryPoints,
+} from './types'

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

@@ -0,0 +1,201 @@
+/**
+ * ESLint rule for detecting multiple release tags on a single symbol.
+ *
+ * @remarks
+ * This rule detects when a symbol has more than one release tag
+ * (e.g., both `@public` and `@beta`). Each symbol should have exactly one release tag.
+ *
+ * @internal
+ */
+
+import { AST_NODE_TYPES, ESLintUtils, TSESTree } from '@typescript-eslint/utils'
+import {
+  getLeadingTSDocComment,
+  parseTSDocComment,
+} 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 = 'extraReleaseTag'
+
+/**
+ * Options for the extra-release-tag rule.
+ * @alpha
+ */
+export interface ExtraReleaseTagRuleOptions {
+  /**
+   * Severity level for extra release tags.
+   * @defaultValue 'error'
+   */
+  severity?: ApiExtractorLogLevel
+}
+
+export const extraReleaseTag = createRule<
+  [ExtraReleaseTagRuleOptions],
+  MessageIds
+>({
+  name: 'extra-release-tag',
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require that symbols have at most one release tag (@public, @beta, @alpha, or @internal)',
+    },
+    messages: {
+      extraReleaseTag:
+        'Symbol "{{name}}" has multiple release tags: {{tags}}. Each symbol should have exactly one release tag.',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          severity: {
+            type: 'string',
+            enum: ['error', 'warning', 'none'],
+            description: 'Severity level for extra release tags',
+          },
+        },
+        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
+
+    /**
+     * Counts release tags in a TSDoc comment.
+     */
+    function countReleaseTags(node: TSESTree.Node): {
+      count: number
+      tags: string[]
+    } {
+      const commentText = getLeadingTSDocComment(sourceCode, node)
+      if (!commentText) {
+        return { count: 0, tags: [] }
+      }
+
+      const parsed = parseTSDocComment(commentText)
+      if (!parsed.docComment) {
+        return { count: 0, tags: [] }
+      }
+
+      const modifierTagSet = parsed.docComment.modifierTagSet
+      const tags: string[] = []
+
+      if (modifierTagSet.isPublic()) {
+        tags.push('@public')
+      }
+      if (modifierTagSet.isBeta()) {
+        tags.push('@beta')
+      }
+      if (modifierTagSet.isAlpha()) {
+        tags.push('@alpha')
+      }
+      if (modifierTagSet.isInternal()) {
+        tags.push('@internal')
+      }
+
+      return { count: tags.length, tags }
+    }
+
+    /**
+     * Gets the name of a declaration.
+     */
+    function getDeclarationName(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ClassDeclaration
+        | TSESTree.TSInterfaceDeclaration
+        | TSESTree.TSTypeAliasDeclaration
+        | TSESTree.TSEnumDeclaration
+        | TSESTree.VariableDeclaration,
+    ): string {
+      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 '<unknown>'
+      }
+
+      if ('id' in node && node.id) {
+        return node.id.name
+      }
+
+      return '<anonymous>'
+    }
+
+    /**
+     * Checks a declaration for multiple release tags.
+     */
+    function checkDeclaration(
+      node:
+        | TSESTree.FunctionDeclaration
+        | TSESTree.ClassDeclaration
+        | TSESTree.TSInterfaceDeclaration
+        | TSESTree.TSTypeAliasDeclaration
+        | TSESTree.TSEnumDeclaration
+        | TSESTree.VariableDeclaration,
+    ): void {
+      // Check both the export statement and the declaration for the comment
+      const exportNode = node.parent
+      let releaseTagInfo = countReleaseTags(node)
+
+      // If no tags on the declaration, check the export statement
+      if (
+        releaseTagInfo.count === 0 &&
+        exportNode &&
+        (exportNode.type === AST_NODE_TYPES.ExportNamedDeclaration ||
+          exportNode.type === AST_NODE_TYPES.ExportDefaultDeclaration)
+      ) {
+        releaseTagInfo = countReleaseTags(exportNode)
+      }
+
+      if (releaseTagInfo.count > 1) {
+        const name = getDeclarationName(node)
+        context.report({
+          node,
+          messageId: 'extraReleaseTag',
+          data: {
+            name,
+            tags: releaseTagInfo.tags.join(', '),
+          },
+        })
+      }
+    }
+
+    return {
+      FunctionDeclaration(node): void {
+        checkDeclaration(node)
+      },
+      ClassDeclaration(node): void {
+        checkDeclaration(node)
+      },
+      TSInterfaceDeclaration(node): void {
+        checkDeclaration(node)
+      },
+      TSTypeAliasDeclaration(node): void {
+        checkDeclaration(node)
+      },
+      TSEnumDeclaration(node): void {
+        checkDeclaration(node)
+      },
+      VariableDeclaration(node): void {
+        checkDeclaration(node)
+      },
+    }
+  },
+})