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

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

@@ -0,0 +1,340 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, afterAll } from 'vitest'
+import * as tseslintParser from '@typescript-eslint/parser'
+import { incompatibleReleaseTags } from '../../src/rules/incompatible-release-tags'
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: tseslintParser,
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
+
+describe('incompatible-release-tags', () => {
+  ruleTester.run('incompatible-release-tags', incompatibleReleaseTags, {
+    valid: [
+      // Public API using public type
+      {
+        code: `
+/**
+ * A public interface.
+ * @public
+ */
+export interface MyInterface {
+  name: string;
+}
+
+/**
+ * A public function.
+ * @public
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+      },
+      // Public API using beta type (beta is less visible, but this is OK since beta >= beta in some interpretations)
+      // Actually, let's make this more strict - public should only use public
+      {
+        code: `
+/**
+ * A beta interface.
+ * @beta
+ */
+export interface MyInterface {
+  name: string;
+}
+
+/**
+ * A beta function.
+ * @beta
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+      },
+      // Alpha API using alpha type
+      {
+        code: `
+/**
+ * An alpha interface.
+ * @alpha
+ */
+export interface MyInterface {
+  name: string;
+}
+
+/**
+ * An alpha function.
+ * @alpha
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+      },
+      // Internal API using internal type
+      {
+        code: `
+/**
+ * An internal interface.
+ * @internal
+ */
+export interface MyInterface {
+  name: string;
+}
+
+/**
+ * An internal function.
+ * @internal
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+      },
+      // Beta API using public type (more visible)
+      {
+        code: `
+/**
+ * A public interface.
+ * @public
+ */
+export interface MyInterface {
+  name: string;
+}
+
+/**
+ * A beta function.
+ * @beta
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+      },
+      // Alpha API using public type (more visible)
+      {
+        code: `
+/**
+ * A public interface.
+ * @public
+ */
+export interface MyInterface {
+  name: string;
+}
+
+/**
+ * An alpha function.
+ * @alpha
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+      },
+    ],
+    invalid: [
+      // Public API using internal type
+      {
+        code: `
+/**
+ * An internal interface.
+ * @internal
+ */
+interface MyInterface {
+  name: string;
+}
+
+/**
+ * A public function.
+ * @public
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+        errors: [
+          {
+            messageId: 'incompatibleReleaseTags',
+            data: {
+              exportedName: 'myFunction',
+              exportedTag: '@public',
+              referencedName: 'MyInterface',
+              referencedTag: '@internal',
+            },
+          },
+        ],
+      },
+      // Public API using alpha type
+      {
+        code: `
+/**
+ * An alpha interface.
+ * @alpha
+ */
+interface MyInterface {
+  name: string;
+}
+
+/**
+ * A public function.
+ * @public
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+        errors: [
+          {
+            messageId: 'incompatibleReleaseTags',
+            data: {
+              exportedName: 'myFunction',
+              exportedTag: '@public',
+              referencedName: 'MyInterface',
+              referencedTag: '@alpha',
+            },
+          },
+        ],
+      },
+      // Beta API using internal type
+      {
+        code: `
+/**
+ * An internal interface.
+ * @internal
+ */
+interface MyInterface {
+  name: string;
+}
+
+/**
+ * A beta function.
+ * @beta
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+        errors: [
+          {
+            messageId: 'incompatibleReleaseTags',
+            data: {
+              exportedName: 'myFunction',
+              exportedTag: '@beta',
+              referencedName: 'MyInterface',
+              referencedTag: '@internal',
+            },
+          },
+        ],
+      },
+      // Beta API using alpha type
+      {
+        code: `
+/**
+ * An alpha interface.
+ * @alpha
+ */
+interface MyInterface {
+  name: string;
+}
+
+/**
+ * A beta function.
+ * @beta
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+        errors: [
+          {
+            messageId: 'incompatibleReleaseTags',
+            data: {
+              exportedName: 'myFunction',
+              exportedTag: '@beta',
+              referencedName: 'MyInterface',
+              referencedTag: '@alpha',
+            },
+          },
+        ],
+      },
+      // Alpha API using internal type
+      {
+        code: `
+/**
+ * An internal interface.
+ * @internal
+ */
+interface MyInterface {
+  name: string;
+}
+
+/**
+ * An alpha function.
+ * @alpha
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+        errors: [
+          {
+            messageId: 'incompatibleReleaseTags',
+            data: {
+              exportedName: 'myFunction',
+              exportedTag: '@alpha',
+              referencedName: 'MyInterface',
+              referencedTag: '@internal',
+            },
+          },
+        ],
+      },
+      // Public interface with internal type property
+      {
+        code: `
+/**
+ * An internal type.
+ * @internal
+ */
+type InternalType = string;
+
+/**
+ * A public interface.
+ * @public
+ */
+export interface MyInterface {
+  value: InternalType;
+}
+`,
+        errors: [
+          {
+            messageId: 'incompatibleReleaseTags',
+            data: {
+              exportedName: 'MyInterface',
+              exportedTag: '@public',
+              referencedName: 'InternalType',
+              referencedTag: '@internal',
+            },
+          },
+        ],
+      },
+    ],
+  })
+
+  // Test with severity option
+  ruleTester.run(
+    'incompatible-release-tags with severity=none',
+    incompatibleReleaseTags,
+    {
+      valid: [
+        // Should not report when severity is 'none'
+        {
+          code: `
+/**
+ * An internal interface.
+ * @internal
+ */
+interface MyInterface {
+  name: string;
+}
+
+/**
+ * A public function.
+ * @public
+ */
+export function myFunction(param: MyInterface): void {}
+`,
+          options: [{ severity: 'none' }],
+        },
+      ],
+      invalid: [],
+    },
+  )
+})

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

@@ -1,5 +1,6 @@
 import { RuleTester } from '@typescript-eslint/rule-tester'
 import { describe, it, afterAll } from 'vitest'
+import * as tseslintParser from '@typescript-eslint/parser'
 import { missingReleaseTag } from '../../src/rules/missing-release-tag'
 
 RuleTester.afterAll = afterAll
@@ -8,7 +9,7 @@ RuleTester.it = it
 
 const ruleTester = new RuleTester({
   languageOptions: {
-    parser: require('@typescript-eslint/parser'),
+    parser: tseslintParser,
     parserOptions: {
       ecmaVersion: 2022,
       sourceType: 'module',

package/test/rules/override-keyword.test.ts

@@ -1,5 +1,6 @@
 import { RuleTester } from '@typescript-eslint/rule-tester'
 import { describe, it, afterAll } from 'vitest'
+import * as tseslintParser from '@typescript-eslint/parser'
 import { overrideKeyword } from '../../src/rules/override-keyword'
 
 RuleTester.afterAll = afterAll
@@ -8,7 +9,7 @@ RuleTester.it = it
 
 const ruleTester = new RuleTester({
   languageOptions: {
-    parser: require('@typescript-eslint/parser'),
+    parser: tseslintParser,
     parserOptions: {
       ecmaVersion: 2022,
       sourceType: 'module',

package/test/rules/package-documentation.test.ts

@@ -1,18 +1,63 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, expect, afterAll, afterEach, beforeEach } from 'vitest'
+import * as tseslintParser from '@typescript-eslint/parser'
 import * as path from 'path'
 import * as fs from 'fs'
 import * as os from 'os'
-import { clearPackageJsonCache } from '../../src/utils/entry-point.js'
+import { packageDocumentation } from '../../src/rules/package-documentation.js'
 import {
   findPackageJson,
   isEntryPoint,
+  clearPackageJsonCache,
+} from '../../src/utils/entry-point.js'
+import {
   hasPackageDocumentation,
   parseTSDocComment,
-} from '../../src/utils'
+} from '../../src/utils/tsdoc-parser.js'
+
+// Wire up vitest for RuleTester
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+// Create a temp directory for RuleTester tests (must exist at module eval time)
+const ruleTestDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eslint-pd-rule-'))
+const ruleTestSrcDir = path.join(ruleTestDir, 'src')
+fs.mkdirSync(ruleTestSrcDir, { recursive: true })
+fs.mkdirSync(path.join(ruleTestSrcDir, 'utils'), { recursive: true })
+
+fs.writeFileSync(
+  path.join(ruleTestDir, 'package.json'),
+  JSON.stringify({ name: 'test-package', main: './src/index.ts' }, null, 2),
+)
+
+// Create placeholder files so paths resolve correctly
+fs.writeFileSync(path.join(ruleTestSrcDir, 'index.ts'), '')
+fs.writeFileSync(path.join(ruleTestSrcDir, 'helper.ts'), '')
+fs.writeFileSync(path.join(ruleTestSrcDir, 'utils', 'deep.ts'), '')
+
+const entryFile = path.join(ruleTestSrcDir, 'index.ts')
+const helperFile = path.join(ruleTestSrcDir, 'helper.ts')
+const deepFile = path.join(ruleTestSrcDir, 'utils', 'deep.ts')
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: tseslintParser,
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
 
 describe('package-documentation', () => {
   let tempDir: string
 
+  afterAll(() => {
+    fs.rmSync(ruleTestDir, { recursive: true, force: true })
+    clearPackageJsonCache()
+  })
+
   beforeEach(() => {
     tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eslint-plugin-test-'))
     clearPackageJsonCache()
@@ -72,7 +117,7 @@ describe('package-documentation', () => {
  */`
       const parsed = parseTSDocComment(comment)
       expect(parsed.docComment).toBeDefined()
-      expect(hasPackageDocumentation(parsed.docComment!)).toBe(true)
+      expect(hasPackageDocumentation(parsed.docComment)).toBe(true)
     })
 
     it('should return false when @packageDocumentation is missing', () => {
@@ -81,72 +126,76 @@ describe('package-documentation', () => {
  */`
       const parsed = parseTSDocComment(comment)
       expect(parsed.docComment).toBeDefined()
-      expect(hasPackageDocumentation(parsed.docComment!)).toBe(false)
+      expect(hasPackageDocumentation(parsed.docComment)).toBe(false)
     })
   })
 
-  describe('rule logic simulation', () => {
-    it('should pass when entry point has @packageDocumentation', () => {
-      createPackageJson('./src/index.ts')
-      const srcDir = createSourceDir()
-      const indexPath = path.join(srcDir, 'index.ts')
-
-      const code = `/**
- * This is the main entry point.
+  ruleTester.run('package-documentation', packageDocumentation, {
+    valid: [
+      // Entry point with @packageDocumentation — should pass
+      {
+        code: `/**
+ * Package entry point.
  * @packageDocumentation
  */
-
-export function foo() {}`
-
-      fs.writeFileSync(indexPath, code)
-
-      const pkgPath = findPackageJson(srcDir)
-      expect(isEntryPoint(indexPath, pkgPath!)).toBe(true)
-
-      // Simulate checking for @packageDocumentation
-      const parsed = parseTSDocComment(`/**
- * This is the main entry point.
+export function foo() {}`,
+        filename: entryFile,
+      },
+      // Non-entry-point without @packageDocumentation — should pass
+      {
+        code: `/**
+ * A helper function.
+ */
+export function helper() {}`,
+        filename: helperFile,
+      },
+      // Non-entry-point with no comments at all — should pass
+      {
+        code: `export function helper() {}`,
+        filename: helperFile,
+      },
+      // Deep non-entry-point without @packageDocumentation — should pass
+      {
+        code: `export const x = 1`,
+        filename: deepFile,
+      },
+    ],
+    invalid: [
+      // Entry point without @packageDocumentation — should fail
+      {
+        code: `/**
+ * Missing package documentation.
+ */
+export function foo() {}`,
+        filename: entryFile,
+        errors: [{ messageId: 'missingPackageDocumentation' as const }],
+      },
+      // Entry point with no comments at all — should fail
+      {
+        code: `export function foo() {}`,
+        filename: entryFile,
+        errors: [{ messageId: 'missingPackageDocumentation' as const }],
+      },
+      // Non-entry-point with @packageDocumentation — should fail
+      {
+        code: `/**
+ * This shouldn't be here.
  * @packageDocumentation
- */`)
-      expect(hasPackageDocumentation(parsed.docComment!)).toBe(true)
-    })
-
-    it('should fail when entry point lacks @packageDocumentation', () => {
-      createPackageJson('./src/index.ts')
-      const srcDir = createSourceDir()
-      const indexPath = path.join(srcDir, 'index.ts')
-
-      const code = `/**
- * This is the main entry point.
  */
-
-export function foo() {}`
-
-      fs.writeFileSync(indexPath, code)
-
-      const pkgPath = findPackageJson(srcDir)
-      expect(isEntryPoint(indexPath, pkgPath!)).toBe(true)
-
-      // Simulate checking for @packageDocumentation
-      const parsed = parseTSDocComment(`/**
- * This is the main entry point.
- */`)
-      expect(hasPackageDocumentation(parsed.docComment!)).toBe(false)
-    })
-
-    it('should not require @packageDocumentation for non-entry points', () => {
-      createPackageJson('./src/index.ts')
-      const srcDir = createSourceDir()
-
-      const indexPath = path.join(srcDir, 'index.ts')
-      fs.writeFileSync(indexPath, '/** @packageDocumentation */ export {}')
-
-      const helperPath = path.join(srcDir, 'helper.ts')
-      fs.writeFileSync(helperPath, '// No package documentation needed')
-
-      const pkgPath = findPackageJson(srcDir)
-      // Helper is not an entry point, so no check needed
-      expect(isEntryPoint(helperPath, pkgPath!)).toBe(false)
-    })
+export function helper() {}`,
+        filename: helperFile,
+        errors: [{ messageId: 'unexpectedPackageDocumentation' as const }],
+      },
+      // Deep non-entry-point with @packageDocumentation — should fail
+      {
+        code: `/**
+ * Wrong place for package docs.
+ * @packageDocumentation
+ */
+export const x = 1`,
+        filename: deepFile,
+        errors: [{ messageId: 'unexpectedPackageDocumentation' as const }],
+      },
+    ],
   })
 })