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

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

@@ -0,0 +1,409 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, afterAll } from 'vitest'
+import { validEnumType } from '../../src/rules/valid-enum-type'
+import parser from '@typescript-eslint/parser'
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser,
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
+
+describe('valid-enum-type', () => {
+  ruleTester.run('valid-enum-type', validEnumType, {
+    valid: [
+      // @enumType open on enum declaration
+      {
+        code: `
+/**
+ * Feature flags that may expand over time.
+ * @enumType open
+ * @public
+ */
+export enum FeatureFlag {
+  DarkMode = 'dark_mode',
+  BetaFeatures = 'beta_features',
+}
+`,
+      },
+      // @enumType closed on enum declaration
+      {
+        code: `
+/**
+ * Status values for an order.
+ * @enumType closed
+ * @public
+ */
+export enum OrderStatus {
+  Pending = 'pending',
+  Shipped = 'shipped',
+}
+`,
+      },
+      // @enumType open on string literal union type
+      {
+        code: `
+/**
+ * Payment method types - new methods may be added.
+ * @enumType open
+ * @public
+ */
+export type PaymentMethod = 'card' | 'bank_transfer' | 'crypto';
+`,
+      },
+      // @enumType closed on string literal union type
+      {
+        code: `
+/**
+ * Fixed set of log levels.
+ * @enumType closed
+ * @public
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+`,
+      },
+      // Case-insensitive: @enumType Open
+      {
+        code: `
+/**
+ * @enumType Open
+ * @public
+ */
+export enum Flags { A = 'a' }
+`,
+      },
+      // Case-insensitive: @enumType CLOSED
+      {
+        code: `
+/**
+ * @enumType CLOSED
+ * @public
+ */
+export type Status = 'ok' | 'error';
+`,
+      },
+      // Enum without @enumType (valid unless requireOnExported is true)
+      {
+        code: `
+/**
+ * @public
+ */
+export enum MyEnum { A, B }
+`,
+      },
+      // String literal union without @enumType
+      {
+        code: `
+/**
+ * @public
+ */
+export type MyType = 'a' | 'b';
+`,
+      },
+      // Non-exported enum without @enumType
+      {
+        code: `
+enum PrivateEnum { A, B }
+`,
+      },
+      // Interface without @enumType (no error - @enumType not applicable)
+      {
+        code: `
+/**
+ * @public
+ */
+export interface MyInterface {}
+`,
+      },
+      // Class without @enumType (no error - @enumType not applicable)
+      {
+        code: `
+/**
+ * @public
+ */
+export class MyClass {}
+`,
+      },
+      // Non-string-literal union type without @enumType (valid)
+      {
+        code: `
+/**
+ * @public
+ */
+export type MyType = string | number;
+`,
+      },
+      // const enum with @enumType
+      {
+        code: `
+/**
+ * @enumType closed
+ * @public
+ */
+export const enum Direction { Up, Down }
+`,
+      },
+      // Empty enum with @enumType
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export enum EmptyEnum {}
+`,
+      },
+      // Single-literal union with @enumType
+      {
+        code: `
+/**
+ * @enumType closed
+ * @public
+ */
+export type Single = 'only';
+`,
+      },
+    ],
+    invalid: [
+      // @enumType without value
+      {
+        code: `
+/**
+ * @enumType
+ * @public
+ */
+export enum MyEnum { A, B }
+`,
+        errors: [{ messageId: 'missingValue' }],
+      },
+      // @enumType with invalid value "foo"
+      {
+        code: `
+/**
+ * @enumType foo
+ * @public
+ */
+export enum MyEnum { A, B }
+`,
+        errors: [{ messageId: 'invalidValue', data: { value: 'foo' } }],
+      },
+      // @enumType with invalid value "opened"
+      {
+        code: `
+/**
+ * @enumType opened
+ * @public
+ */
+export type Status = 'a' | 'b';
+`,
+        errors: [{ messageId: 'invalidValue', data: { value: 'opened' } }],
+      },
+      // @enumType with invalid value "close"
+      {
+        code: `
+/**
+ * @enumType close
+ * @public
+ */
+export enum MyEnum { A }
+`,
+        errors: [{ messageId: 'invalidValue', data: { value: 'close' } }],
+      },
+      // @enumType with invalid value "true"
+      {
+        code: `
+/**
+ * @enumType true
+ * @public
+ */
+export type MyType = 'x' | 'y';
+`,
+        errors: [{ messageId: 'invalidValue', data: { value: 'true' } }],
+      },
+      // Multiple @enumType tags
+      {
+        code: `
+/**
+ * @enumType open
+ * @enumType closed
+ * @public
+ */
+export enum MyEnum { A, B }
+`,
+        errors: [{ messageId: 'multipleEnumTypes' }],
+      },
+      // @enumType on interface (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export interface MyInterface {}
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+      // @enumType on class (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export class MyClass {}
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+      // @enumType on function (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export function myFunction() {}
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+      // @enumType on variable (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export const MY_CONST = 42;
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+      // @enumType on numeric type (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export type MyType = number;
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+      // @enumType on numeric literal union (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export type Status = 0 | 1 | 2;
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+      // @enumType on mixed literal union (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export type Mixed = 'a' | 1;
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+      // @enumType on non-union, non-literal type alias (invalid construct)
+      {
+        code: `
+/**
+ * @enumType open
+ * @public
+ */
+export type MyType = string;
+`,
+        errors: [{ messageId: 'invalidConstruct' }],
+      },
+    ],
+  })
+
+  // Test with requireOnExported option
+  describe('with requireOnExported option', () => {
+    ruleTester.run('valid-enum-type with requireOnExported', validEnumType, {
+      valid: [
+        // Exported enum with @enumType (satisfies requirement)
+        {
+          code: `
+/**
+ * @enumType open
+ * @public
+ */
+export enum MyEnum { A }
+`,
+          options: [{ requireOnExported: true }],
+        },
+        // Exported string literal union with @enumType
+        {
+          code: `
+/**
+ * @enumType closed
+ * @public
+ */
+export type Status = 'ok' | 'error';
+`,
+          options: [{ requireOnExported: true }],
+        },
+        // Non-exported enum without @enumType (not required)
+        {
+          code: `
+enum PrivateEnum { A }
+`,
+          options: [{ requireOnExported: true }],
+        },
+        // Non-exported type alias without @enumType
+        {
+          code: `
+type PrivateType = 'a' | 'b';
+`,
+          options: [{ requireOnExported: true }],
+        },
+      ],
+      invalid: [
+        // Exported enum without @enumType
+        {
+          code: `
+/**
+ * @public
+ */
+export enum MyEnum { A }
+`,
+          options: [{ requireOnExported: true }],
+          errors: [{ messageId: 'missingEnumType' }],
+        },
+        // Exported string literal union without @enumType
+        {
+          code: `
+/**
+ * @public
+ */
+export type Status = 'ok' | 'error';
+`,
+          options: [{ requireOnExported: true }],
+          errors: [{ messageId: 'missingEnumType' }],
+        },
+        // Exported enum without any TSDoc comment
+        {
+          code: `
+export enum MyEnum { A }
+`,
+          options: [{ requireOnExported: true }],
+          errors: [{ messageId: 'missingEnumType' }],
+        },
+      ],
+    })
+  })
+})

package/test/types.test-d.ts

@@ -0,0 +1,20 @@
+import { expectType, expectAssignable } from 'tsd'
+import type {
+  ReleaseTag,
+  ApiExtractorConfig,
+  MissingReleaseTagRuleOptions,
+} from '../src/index'
+import { RELEASE_TAGS } from '../src/index'
+
+// Test type exports - ReleaseTag is a union type
+expectAssignable<ReleaseTag>('alpha')
+expectAssignable<ReleaseTag>('beta')
+expectAssignable<ReleaseTag>('public')
+expectAssignable<ReleaseTag>('internal')
+
+// Test option types
+expectAssignable<ApiExtractorConfig>({})
+expectAssignable<MissingReleaseTagRuleOptions>({})
+
+// Test constant exports
+expectType<typeof RELEASE_TAGS>(RELEASE_TAGS)

package/test/utils/config-loader.test.ts

@@ -197,3 +197,4 @@ describe('config-loader', () => {
     })
   })
 })
+

package/test/utils/tsdoc-parser.test.ts

@@ -4,6 +4,7 @@ import {
   extractReleaseTag,
   hasOverrideTag,
   hasPackageDocumentation,
+  extractEnumType,
 } from '../../src/utils/tsdoc-parser'
 
 describe('tsdoc-parser', () => {
@@ -33,7 +34,7 @@ describe('tsdoc-parser', () => {
  * @public
  */`
       const result = parseTSDocComment(comment)
-      const tag = extractReleaseTag(result.docComment!)
+      const tag = extractReleaseTag(result.docComment)
       expect(tag).toBe('public')
     })
 
@@ -42,7 +43,7 @@ describe('tsdoc-parser', () => {
  * @beta
  */`
       const result = parseTSDocComment(comment)
-      const tag = extractReleaseTag(result.docComment!)
+      const tag = extractReleaseTag(result.docComment)
       expect(tag).toBe('beta')
     })
 
@@ -51,7 +52,7 @@ describe('tsdoc-parser', () => {
  * @alpha
  */`
       const result = parseTSDocComment(comment)
-      const tag = extractReleaseTag(result.docComment!)
+      const tag = extractReleaseTag(result.docComment)
       expect(tag).toBe('alpha')
     })
 
@@ -60,7 +61,7 @@ describe('tsdoc-parser', () => {
  * @internal
  */`
       const result = parseTSDocComment(comment)
-      const tag = extractReleaseTag(result.docComment!)
+      const tag = extractReleaseTag(result.docComment)
       expect(tag).toBe('internal')
     })
 
@@ -69,7 +70,7 @@ describe('tsdoc-parser', () => {
  * Just a description.
  */`
       const result = parseTSDocComment(comment)
-      const tag = extractReleaseTag(result.docComment!)
+      const tag = extractReleaseTag(result.docComment)
       expect(tag).toBeUndefined()
     })
   })
@@ -80,7 +81,7 @@ describe('tsdoc-parser', () => {
  * @override
  */`
       const result = parseTSDocComment(comment)
-      expect(hasOverrideTag(result.docComment!)).toBe(true)
+      expect(hasOverrideTag(result.docComment)).toBe(true)
     })
 
     it('should return false when no @override tag', () => {
@@ -88,7 +89,7 @@ describe('tsdoc-parser', () => {
  * Just a comment.
  */`
       const result = parseTSDocComment(comment)
-      expect(hasOverrideTag(result.docComment!)).toBe(false)
+      expect(hasOverrideTag(result.docComment)).toBe(false)
     })
   })
 
@@ -99,7 +100,7 @@ describe('tsdoc-parser', () => {
  * @packageDocumentation
  */`
       const result = parseTSDocComment(comment)
-      expect(hasPackageDocumentation(result.docComment!)).toBe(true)
+      expect(hasPackageDocumentation(result.docComment)).toBe(true)
     })
 
     it('should return false when no @packageDocumentation tag', () => {
@@ -107,7 +108,114 @@ describe('tsdoc-parser', () => {
  * Just a comment.
  */`
       const result = parseTSDocComment(comment)
-      expect(hasPackageDocumentation(result.docComment!)).toBe(false)
+      expect(hasPackageDocumentation(result.docComment)).toBe(false)
+    })
+  })
+
+  describe('extractEnumType', () => {
+    it('should extract @enumType open', () => {
+      const comment = `/**
+ * @enumType open
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.count).toBe(1)
+      expect(result.value).toBe('open')
+      expect(result.isValid).toBe(true)
+      expect(result.rawValue).toBe('open')
+    })
+
+    it('should extract @enumType closed', () => {
+      const comment = `/**
+ * @enumType closed
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.count).toBe(1)
+      expect(result.value).toBe('closed')
+      expect(result.isValid).toBe(true)
+    })
+
+    it('should handle case-insensitive values (Open)', () => {
+      const comment = `/**
+ * @enumType Open
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.value).toBe('open')
+      expect(result.isValid).toBe(true)
+      expect(result.rawValue).toBe('Open')
+    })
+
+    it('should handle case-insensitive values (CLOSED)', () => {
+      const comment = `/**
+ * @enumType CLOSED
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.value).toBe('closed')
+      expect(result.isValid).toBe(true)
+      expect(result.rawValue).toBe('CLOSED')
+    })
+
+    it('should detect invalid value', () => {
+      const comment = `/**
+ * @enumType foo
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.count).toBe(1)
+      expect(result.value).toBe('foo')
+      expect(result.isValid).toBe(false)
+      expect(result.rawValue).toBe('foo')
+    })
+
+    it('should detect missing value', () => {
+      const comment = `/**
+ * @enumType
+ * @public
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.count).toBe(1)
+      expect(result.rawValue).toBeUndefined()
+      expect(result.isValid).toBe(false)
+    })
+
+    it('should detect multiple @enumType tags', () => {
+      const comment = `/**
+ * @enumType open
+ * @enumType closed
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.count).toBe(2)
+      // First value is captured
+      expect(result.value).toBe('open')
+    })
+
+    it('should return not found when no @enumType tag', () => {
+      const comment = `/**
+ * Just a comment.
+ * @public
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(false)
+      expect(result.count).toBe(0)
+      expect(result.value).toBeUndefined()
+      expect(result.isValid).toBe(false)
+    })
+
+    it('should handle @enumType with other tags', () => {
+      const comment = `/**
+ * Description of the enum.
+ * @enumType open
+ * @public
+ */`
+      const result = extractEnumType(comment)
+      expect(result.found).toBe(true)
+      expect(result.value).toBe('open')
+      expect(result.isValid).toBe(true)
     })
   })
 })

package/tsconfig.json

@@ -10,3 +10,4 @@
   },
   "include": ["src/**/*.ts"]
 }
+

package/vitest.config.mts

@@ -23,3 +23,4 @@ export default defineConfig({
     },
   },
 })
+

package/dist/utils/index.d.ts

@@ -1,8 +0,0 @@
-/**
- * Utility module exports.
- * @internal
- */
-export { resolveConfig, getMessageLogLevel } from './config-loader';
-export { parseTSDocComment, extractReleaseTag, hasOverrideTag, hasPackageDocumentation, getLeadingTSDocComment, findAllTSDocComments, } from './tsdoc-parser';
-export { findPackageJson, isEntryPoint } from './entry-point';
-//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEnE,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,GACrB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA"}

package/dist/utils/index.js

@@ -1,21 +0,0 @@
-"use strict";
-/**
- * Utility module exports.
- * @internal
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.isEntryPoint = exports.findPackageJson = exports.findAllTSDocComments = exports.getLeadingTSDocComment = exports.hasPackageDocumentation = exports.hasOverrideTag = exports.extractReleaseTag = exports.parseTSDocComment = exports.getMessageLogLevel = exports.resolveConfig = void 0;
-var config_loader_1 = require("./config-loader");
-Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_loader_1.resolveConfig; } });
-Object.defineProperty(exports, "getMessageLogLevel", { enumerable: true, get: function () { return config_loader_1.getMessageLogLevel; } });
-var tsdoc_parser_1 = require("./tsdoc-parser");
-Object.defineProperty(exports, "parseTSDocComment", { enumerable: true, get: function () { return tsdoc_parser_1.parseTSDocComment; } });
-Object.defineProperty(exports, "extractReleaseTag", { enumerable: true, get: function () { return tsdoc_parser_1.extractReleaseTag; } });
-Object.defineProperty(exports, "hasOverrideTag", { enumerable: true, get: function () { return tsdoc_parser_1.hasOverrideTag; } });
-Object.defineProperty(exports, "hasPackageDocumentation", { enumerable: true, get: function () { return tsdoc_parser_1.hasPackageDocumentation; } });
-Object.defineProperty(exports, "getLeadingTSDocComment", { enumerable: true, get: function () { return tsdoc_parser_1.getLeadingTSDocComment; } });
-Object.defineProperty(exports, "findAllTSDocComments", { enumerable: true, get: function () { return tsdoc_parser_1.findAllTSDocComments; } });
-var entry_point_1 = require("./entry-point");
-Object.defineProperty(exports, "findPackageJson", { enumerable: true, get: function () { return entry_point_1.findPackageJson; } });
-Object.defineProperty(exports, "isEntryPoint", { enumerable: true, get: function () { return entry_point_1.isEntryPoint; } });
-//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,iDAAmE;AAA1D,8GAAA,aAAa,OAAA;AAAE,mHAAA,kBAAkB,OAAA;AAE1C,+CAOuB;AANrB,iHAAA,iBAAiB,OAAA;AACjB,iHAAA,iBAAiB,OAAA;AACjB,8GAAA,cAAc,OAAA;AACd,uHAAA,uBAAuB,OAAA;AACvB,sHAAA,sBAAsB,OAAA;AACtB,oHAAA,oBAAoB,OAAA;AAGtB,6CAA6D;AAApD,8GAAA,eAAe,OAAA;AAAE,2GAAA,YAAY,OAAA"}

package/src/utils/index.ts

@@ -1,17 +0,0 @@
-/**
- * Utility module exports.
- * @internal
- */
-
-export { resolveConfig, getMessageLogLevel } from './config-loader'
-
-export {
-  parseTSDocComment,
-  extractReleaseTag,
-  hasOverrideTag,
-  hasPackageDocumentation,
-  getLeadingTSDocComment,
-  findAllTSDocComments,
-} from './tsdoc-parser'
-
-export { findPackageJson, isEntryPoint } from './entry-point'