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

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

@@ -0,0 +1,152 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as path from 'path'
+import * as fs from 'fs'
+import * as os from 'os'
+import { clearPackageJsonCache } from '../../src/utils/entry-point.js'
+import {
+  findPackageJson,
+  isEntryPoint,
+  hasPackageDocumentation,
+  parseTSDocComment,
+} from '../../src/utils'
+
+describe('package-documentation', () => {
+  let tempDir: string
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eslint-plugin-test-'))
+    clearPackageJsonCache()
+  })
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+    clearPackageJsonCache()
+  })
+
+  function createPackageJson(main: string): void {
+    const pkgPath = path.join(tempDir, 'package.json')
+    fs.writeFileSync(
+      pkgPath,
+      JSON.stringify({ name: 'test-package', main }, null, 2),
+    )
+  }
+
+  function createSourceDir(): string {
+    const srcDir = path.join(tempDir, 'src')
+    fs.mkdirSync(srcDir, { recursive: true })
+    return srcDir
+  }
+
+  describe('entry point detection', () => {
+    it('should correctly identify entry points from package.json', () => {
+      createPackageJson('./src/index.ts')
+      const srcDir = createSourceDir()
+      const indexPath = path.join(srcDir, 'index.ts')
+      fs.writeFileSync(indexPath, 'export {}')
+
+      const pkgPath = findPackageJson(srcDir)
+      expect(pkgPath).toBeDefined()
+      expect(isEntryPoint(indexPath, pkgPath!)).toBe(true)
+    })
+
+    it('should not identify non-entry points', () => {
+      createPackageJson('./src/index.ts')
+      const srcDir = createSourceDir()
+
+      const indexPath = path.join(srcDir, 'index.ts')
+      fs.writeFileSync(indexPath, 'export {}')
+
+      const helperPath = path.join(srcDir, 'helper.ts')
+      fs.writeFileSync(helperPath, 'export {}')
+
+      const pkgPath = findPackageJson(srcDir)
+      expect(isEntryPoint(helperPath, pkgPath!)).toBe(false)
+    })
+  })
+
+  describe('@packageDocumentation detection', () => {
+    it('should detect @packageDocumentation in a comment', () => {
+      const comment = `/**
+ * This is the main entry point.
+ * @packageDocumentation
+ */`
+      const parsed = parseTSDocComment(comment)
+      expect(parsed.docComment).toBeDefined()
+      expect(hasPackageDocumentation(parsed.docComment!)).toBe(true)
+    })
+
+    it('should return false when @packageDocumentation is missing', () => {
+      const comment = `/**
+ * This is just a comment.
+ */`
+      const parsed = parseTSDocComment(comment)
+      expect(parsed.docComment).toBeDefined()
+      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.
+ * @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.
+ * @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)
+    })
+  })
+})

package/test/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rootDir": "..",
+    "baseUrl": "..",
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": ["./**/*.ts", "../src/**/*.ts"]
+}

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

@@ -0,0 +1,199 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as path from 'path'
+import * as fs from 'fs'
+import * as os from 'os'
+import {
+  findApiExtractorConfig,
+  loadApiExtractorConfig,
+  getMessageLogLevel,
+  resolveConfig,
+  logLevelToSeverity,
+  clearConfigCache,
+} from '../../src/utils/config-loader'
+
+describe('config-loader', () => {
+  let tempDir: string
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'config-loader-test-'))
+    clearConfigCache()
+  })
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+    clearConfigCache()
+  })
+
+  describe('findApiExtractorConfig', () => {
+    it('should find api-extractor.json in the same directory', () => {
+      const configPath = path.join(tempDir, 'api-extractor.json')
+      fs.writeFileSync(configPath, '{}')
+
+      const found = findApiExtractorConfig(tempDir)
+      expect(found).toBe(configPath)
+    })
+
+    it('should find api-extractor.json in parent directory', () => {
+      const subDir = path.join(tempDir, 'src')
+      fs.mkdirSync(subDir)
+      const configPath = path.join(tempDir, 'api-extractor.json')
+      fs.writeFileSync(configPath, '{}')
+
+      const found = findApiExtractorConfig(subDir)
+      expect(found).toBe(configPath)
+    })
+
+    it('should return undefined when no config found', () => {
+      const found = findApiExtractorConfig(tempDir)
+      expect(found).toBeUndefined()
+    })
+  })
+
+  describe('loadApiExtractorConfig', () => {
+    it('should load and parse api-extractor.json', () => {
+      const configPath = path.join(tempDir, 'api-extractor.json')
+      const config = {
+        mainEntryPointFilePath: './dist/index.d.ts',
+        messages: {
+          extractorMessageReporting: {
+            'ae-missing-release-tag': { logLevel: 'error' },
+          },
+        },
+      }
+      fs.writeFileSync(configPath, JSON.stringify(config))
+
+      const loaded = loadApiExtractorConfig(configPath)
+      expect(loaded).toEqual(config)
+    })
+
+    it('should handle JSON with comments', () => {
+      const configPath = path.join(tempDir, 'api-extractor.json')
+      const content = `{
+        // This is a comment
+        "mainEntryPointFilePath": "./dist/index.d.ts"
+        /* Block comment */
+      }`
+      fs.writeFileSync(configPath, content)
+
+      const loaded = loadApiExtractorConfig(configPath)
+      expect(loaded?.mainEntryPointFilePath).toBe('./dist/index.d.ts')
+    })
+
+    it('should handle extends', () => {
+      const baseConfigPath = path.join(tempDir, 'base.json')
+      const baseConfig = {
+        messages: {
+          extractorMessageReporting: {
+            default: { logLevel: 'warning' },
+          },
+        },
+      }
+      fs.writeFileSync(baseConfigPath, JSON.stringify(baseConfig))
+
+      const configPath = path.join(tempDir, 'api-extractor.json')
+      const config = {
+        extends: './base.json',
+        mainEntryPointFilePath: './dist/index.d.ts',
+      }
+      fs.writeFileSync(configPath, JSON.stringify(config))
+
+      const loaded = loadApiExtractorConfig(configPath)
+      expect(loaded?.mainEntryPointFilePath).toBe('./dist/index.d.ts')
+      expect(
+        loaded?.messages?.extractorMessageReporting?.default?.logLevel,
+      ).toBe('warning')
+    })
+
+    it('should return null for invalid JSON', () => {
+      const configPath = path.join(tempDir, 'api-extractor.json')
+      fs.writeFileSync(configPath, 'invalid json')
+
+      const loaded = loadApiExtractorConfig(configPath)
+      expect(loaded).toBeNull()
+    })
+
+    it('should return null for non-existent file', () => {
+      const configPath = path.join(tempDir, 'non-existent.json')
+      const loaded = loadApiExtractorConfig(configPath)
+      expect(loaded).toBeNull()
+    })
+  })
+
+  describe('getMessageLogLevel', () => {
+    it('should return specific message log level', () => {
+      const config = {
+        messages: {
+          extractorMessageReporting: {
+            'ae-missing-release-tag': { logLevel: 'error' as const },
+          },
+        },
+      }
+
+      const level = getMessageLogLevel(config, 'ae-missing-release-tag')
+      expect(level).toBe('error')
+    })
+
+    it('should return default log level when message not configured', () => {
+      const config = {
+        messages: {
+          extractorMessageReporting: {
+            default: { logLevel: 'warning' as const },
+          },
+        },
+      }
+
+      const level = getMessageLogLevel(config, 'ae-missing-release-tag')
+      expect(level).toBe('warning')
+    })
+
+    it('should return warning for null config', () => {
+      const level = getMessageLogLevel(null, 'ae-missing-release-tag')
+      expect(level).toBe('warning')
+    })
+  })
+
+  describe('logLevelToSeverity', () => {
+    it('should map error to 2', () => {
+      expect(logLevelToSeverity('error')).toBe(2)
+    })
+
+    it('should map warning to 1', () => {
+      expect(logLevelToSeverity('warning')).toBe(1)
+    })
+
+    it('should map none to 0', () => {
+      expect(logLevelToSeverity('none')).toBe(0)
+    })
+  })
+
+  describe('resolveConfig', () => {
+    it('should use explicit config path when provided', () => {
+      const configPath = path.join(tempDir, 'custom-config.json')
+      const config = { mainEntryPointFilePath: './custom.d.ts' }
+      fs.writeFileSync(configPath, JSON.stringify(config))
+
+      const filePath = path.join(tempDir, 'src', 'index.ts')
+      const resolved = resolveConfig(filePath, configPath)
+      expect(resolved?.mainEntryPointFilePath).toBe('./custom.d.ts')
+    })
+
+    it('should auto-discover config when no explicit path', () => {
+      const configPath = path.join(tempDir, 'api-extractor.json')
+      const config = { mainEntryPointFilePath: './dist/index.d.ts' }
+      fs.writeFileSync(configPath, JSON.stringify(config))
+
+      const srcDir = path.join(tempDir, 'src')
+      fs.mkdirSync(srcDir)
+      const filePath = path.join(srcDir, 'index.ts')
+
+      const resolved = resolveConfig(filePath)
+      expect(resolved?.mainEntryPointFilePath).toBe('./dist/index.d.ts')
+    })
+
+    it('should return null when no config found', () => {
+      const filePath = path.join(tempDir, 'index.ts')
+      const resolved = resolveConfig(filePath)
+      expect(resolved).toBeNull()
+    })
+  })
+})

package/test/utils/entry-point.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import * as path from 'path'
+import * as fs from 'fs'
+import * as os from 'os'
+import {
+  findPackageJson,
+  loadPackageJson,
+  resolveEntryPoints,
+  isEntryPoint,
+  clearPackageJsonCache,
+} from '../../src/utils/entry-point'
+
+describe('entry-point', () => {
+  let tempDir: string
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'entry-point-test-'))
+    clearPackageJsonCache()
+  })
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true })
+    clearPackageJsonCache()
+  })
+
+  describe('findPackageJson', () => {
+    it('should find package.json in the same directory', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, '{}')
+
+      const found = findPackageJson(tempDir)
+      expect(found).toBe(pkgPath)
+    })
+
+    it('should find package.json in parent directory', () => {
+      const subDir = path.join(tempDir, 'src')
+      fs.mkdirSync(subDir)
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, '{}')
+
+      const found = findPackageJson(subDir)
+      expect(found).toBe(pkgPath)
+    })
+
+    it('should return undefined when no package.json found', () => {
+      const found = findPackageJson(tempDir)
+      expect(found).toBeUndefined()
+    })
+  })
+
+  describe('loadPackageJson', () => {
+    it('should load and parse package.json', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      const pkg = { name: 'test-package', main: './dist/index.js' }
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg))
+
+      const loaded = loadPackageJson(pkgPath)
+      expect(loaded).toEqual(pkg)
+    })
+
+    it('should return null for invalid JSON', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, 'invalid json')
+
+      const loaded = loadPackageJson(pkgPath)
+      expect(loaded).toBeNull()
+    })
+  })
+
+  describe('resolveEntryPoints', () => {
+    it('should resolve main entry point', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, JSON.stringify({ main: './dist/index.js' }))
+
+      const entryPoints = resolveEntryPoints(pkgPath)
+      expect(entryPoints.main).toBe(path.join(tempDir, 'dist/index.js'))
+    })
+
+    it('should resolve types entry point', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, JSON.stringify({ types: './dist/index.d.ts' }))
+
+      const entryPoints = resolveEntryPoints(pkgPath)
+      expect(entryPoints.types).toBe(path.join(tempDir, 'dist/index.d.ts'))
+    })
+
+    it('should resolve typings entry point', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(
+        pkgPath,
+        JSON.stringify({ typings: './dist/index.d.ts' }),
+      )
+
+      const entryPoints = resolveEntryPoints(pkgPath)
+      expect(entryPoints.types).toBe(path.join(tempDir, 'dist/index.d.ts'))
+    })
+
+    it('should resolve simple exports', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(
+        pkgPath,
+        JSON.stringify({
+          exports: {
+            '.': './dist/index.js',
+            './utils': './dist/utils.js',
+          },
+        }),
+      )
+
+      const entryPoints = resolveEntryPoints(pkgPath)
+      expect(entryPoints.exports).toContain(path.join(tempDir, 'dist/index.js'))
+      expect(entryPoints.exports).toContain(path.join(tempDir, 'dist/utils.js'))
+    })
+
+    it('should resolve nested exports', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(
+        pkgPath,
+        JSON.stringify({
+          exports: {
+            '.': {
+              import: './dist/index.mjs',
+              require: './dist/index.cjs',
+            },
+          },
+        }),
+      )
+
+      const entryPoints = resolveEntryPoints(pkgPath)
+      expect(entryPoints.exports).toContain(
+        path.join(tempDir, 'dist/index.mjs'),
+      )
+      expect(entryPoints.exports).toContain(
+        path.join(tempDir, 'dist/index.cjs'),
+      )
+    })
+  })
+
+  describe('isEntryPoint', () => {
+    it('should identify main entry point', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, JSON.stringify({ main: './dist/index.js' }))
+
+      const filePath = path.join(tempDir, 'dist/index.js')
+      expect(isEntryPoint(filePath, pkgPath)).toBe(true)
+    })
+
+    it('should identify source file when main points to source', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, JSON.stringify({ main: './src/index.ts' }))
+
+      const filePath = path.join(tempDir, 'src/index.ts')
+      expect(isEntryPoint(filePath, pkgPath)).toBe(true)
+    })
+
+    it('should not identify non-entry point files', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, JSON.stringify({ main: './dist/index.js' }))
+
+      const filePath = path.join(tempDir, 'src/utils.ts')
+      expect(isEntryPoint(filePath, pkgPath)).toBe(false)
+    })
+
+    it('should handle relative paths in package.json', () => {
+      const pkgPath = path.join(tempDir, 'package.json')
+      fs.writeFileSync(pkgPath, JSON.stringify({ main: 'dist/index.js' }))
+
+      const filePath = path.join(tempDir, 'dist/index.js')
+      expect(isEntryPoint(filePath, pkgPath)).toBe(true)
+    })
+  })
+})

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

@@ -0,0 +1,113 @@
+import { describe, it, expect } from 'vitest'
+import {
+  parseTSDocComment,
+  extractReleaseTag,
+  hasOverrideTag,
+  hasPackageDocumentation,
+} from '../../src/utils/tsdoc-parser'
+
+describe('tsdoc-parser', () => {
+  describe('parseTSDocComment', () => {
+    it('should parse a simple TSDoc comment', () => {
+      const comment = `/**
+ * A simple comment.
+ */`
+      const result = parseTSDocComment(comment)
+      expect(result.docComment).toBeDefined()
+    })
+
+    it('should handle comments with modifier tags', () => {
+      const comment = `/**
+ * A public API.
+ * @public
+ */`
+      const result = parseTSDocComment(comment)
+      expect(result.docComment).toBeDefined()
+      expect(result.docComment?.modifierTagSet.isPublic()).toBe(true)
+    })
+  })
+
+  describe('extractReleaseTag', () => {
+    it('should extract @public tag', () => {
+      const comment = `/**
+ * @public
+ */`
+      const result = parseTSDocComment(comment)
+      const tag = extractReleaseTag(result.docComment!)
+      expect(tag).toBe('public')
+    })
+
+    it('should extract @beta tag', () => {
+      const comment = `/**
+ * @beta
+ */`
+      const result = parseTSDocComment(comment)
+      const tag = extractReleaseTag(result.docComment!)
+      expect(tag).toBe('beta')
+    })
+
+    it('should extract @alpha tag', () => {
+      const comment = `/**
+ * @alpha
+ */`
+      const result = parseTSDocComment(comment)
+      const tag = extractReleaseTag(result.docComment!)
+      expect(tag).toBe('alpha')
+    })
+
+    it('should extract @internal tag', () => {
+      const comment = `/**
+ * @internal
+ */`
+      const result = parseTSDocComment(comment)
+      const tag = extractReleaseTag(result.docComment!)
+      expect(tag).toBe('internal')
+    })
+
+    it('should return undefined when no release tag', () => {
+      const comment = `/**
+ * Just a description.
+ */`
+      const result = parseTSDocComment(comment)
+      const tag = extractReleaseTag(result.docComment!)
+      expect(tag).toBeUndefined()
+    })
+  })
+
+  describe('hasOverrideTag', () => {
+    it('should detect @override tag', () => {
+      const comment = `/**
+ * @override
+ */`
+      const result = parseTSDocComment(comment)
+      expect(hasOverrideTag(result.docComment!)).toBe(true)
+    })
+
+    it('should return false when no @override tag', () => {
+      const comment = `/**
+ * Just a comment.
+ */`
+      const result = parseTSDocComment(comment)
+      expect(hasOverrideTag(result.docComment!)).toBe(false)
+    })
+  })
+
+  describe('hasPackageDocumentation', () => {
+    it('should detect @packageDocumentation tag', () => {
+      const comment = `/**
+ * Package description.
+ * @packageDocumentation
+ */`
+      const result = parseTSDocComment(comment)
+      expect(hasPackageDocumentation(result.docComment!)).toBe(true)
+    })
+
+    it('should return false when no @packageDocumentation tag', () => {
+      const comment = `/**
+ * Just a comment.
+ */`
+      const result = parseTSDocComment(comment)
+      expect(hasPackageDocumentation(result.docComment!)).toBe(false)
+    })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "outDir": "dist",
+    "rootDir": "src",
+    "baseUrl": "src",
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*.ts"]
+}

package/vitest.config.mts

@@ -0,0 +1,25 @@
+import { defineConfig } from 'vitest/config'
+import * as path from 'path'
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, 'src/index.ts'),
+    },
+  },
+  test: {
+    testTimeout: 30000,
+    server: {
+      deps: {
+        inline: ['fast-glob'],
+      },
+    },
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      reportsDirectory: './coverage',
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/*.d.ts', 'src/**/index.ts'],
+    },
+  },
+})