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

package/src/types.ts

@@ -0,0 +1,104 @@
+/**
+ * Types for the API Extractor ESLint plugin.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Log levels supported by API Extractor message configuration.
+ * @public
+ */
+export type ApiExtractorLogLevel = 'error' | 'warning' | 'none'
+
+/**
+ * Configuration for a single message type in API Extractor.
+ * @public
+ */
+export interface MessageConfig {
+  logLevel: ApiExtractorLogLevel
+  addToApiReportFile?: boolean
+}
+
+/**
+ * The messages configuration section from api-extractor.json.
+ * @public
+ */
+export interface ApiExtractorMessagesConfig {
+  compilerMessageReporting?: {
+    default?: MessageConfig
+    [messageId: string]: MessageConfig | undefined
+  }
+  extractorMessageReporting?: {
+    default?: MessageConfig
+    'ae-missing-release-tag'?: MessageConfig
+    'ae-forgotten-export'?: MessageConfig
+    'ae-internal-missing-underscore'?: MessageConfig
+    'ae-incompatible-release-tags'?: MessageConfig
+    [messageId: string]: MessageConfig | undefined
+  }
+  tsdocMessageReporting?: {
+    default?: MessageConfig
+    [messageId: string]: MessageConfig | undefined
+  }
+}
+
+/**
+ * Partial representation of api-extractor.json relevant for this plugin.
+ * @public
+ */
+export interface ApiExtractorConfig {
+  extends?: string
+  mainEntryPointFilePath?: string
+  messages?: ApiExtractorMessagesConfig
+}
+
+/**
+ * Release tags recognized by API Extractor.
+ * @public
+ */
+export type ReleaseTag = 'public' | 'beta' | 'alpha' | 'internal'
+
+/**
+ * All valid release tags.
+ * @public
+ */
+export const RELEASE_TAGS: readonly ReleaseTag[] = [
+  'public',
+  'beta',
+  'alpha',
+  'internal',
+] as const
+
+/**
+ * Options for the missing-release-tag rule.
+ * @public
+ */
+export interface MissingReleaseTagRuleOptions {
+  configPath?: string
+}
+
+/**
+ * Options for the override-keyword rule.
+ * @public
+ */
+export interface OverrideKeywordRuleOptions {
+  configPath?: string
+}
+
+/**
+ * Options for the package-documentation rule.
+ * @public
+ */
+export interface PackageDocumentationRuleOptions {
+  configPath?: string
+}
+
+/**
+ * Resolved entry points from package.json.
+ * @public
+ */
+export interface ResolvedEntryPoints {
+  main?: string
+  types?: string
+  exports: string[]
+}

package/src/utils/config-loader.ts

@@ -0,0 +1,194 @@
+/**
+ * Utilities for discovering and loading API Extractor configuration.
+ * @internal
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import type {
+  ApiExtractorConfig,
+  ApiExtractorLogLevel,
+  ApiExtractorMessagesConfig,
+} from '../types'
+
+/**
+ * Default message configuration when no api-extractor.json is found.
+ */
+const DEFAULT_MESSAGES_CONFIG: ApiExtractorMessagesConfig = {
+  extractorMessageReporting: {
+    default: { logLevel: 'warning' },
+    'ae-missing-release-tag': { logLevel: 'warning' },
+  },
+}
+
+/**
+ * Cache for loaded configurations to avoid repeated file reads.
+ */
+const configCache = new Map<string, ApiExtractorConfig | null>()
+
+/**
+ * Searches upward from the given directory to find api-extractor.json.
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Path to api-extractor.json if found, undefined otherwise
+ */
+export function findApiExtractorConfig(startDir: string): string | undefined {
+  let currentDir = path.resolve(startDir)
+  const root = path.parse(currentDir).root
+
+  while (currentDir !== root) {
+    const configPath = path.join(currentDir, 'api-extractor.json')
+    if (fs.existsSync(configPath)) {
+      return configPath
+    }
+    currentDir = path.dirname(currentDir)
+  }
+
+  return undefined
+}
+
+/**
+ * Loads and parses an api-extractor.json file.
+ *
+ * @param configPath - Path to the api-extractor.json file
+ * @returns Parsed configuration or null if file cannot be read
+ */
+export function loadApiExtractorConfig(
+  configPath: string,
+): ApiExtractorConfig | null {
+  // Check cache first
+  const cached = configCache.get(configPath)
+  if (cached !== undefined) {
+    return cached
+  }
+
+  try {
+    const content = fs.readFileSync(configPath, 'utf-8')
+    // Remove comments (api-extractor.json supports JSON with comments)
+    const jsonContent = content.replace(/\/\/.*$|\/\*[\s\S]*?\*\//gm, '')
+    const config = JSON.parse(jsonContent) as ApiExtractorConfig
+
+    // Handle extends
+    if (config.extends) {
+      const baseConfigPath = path.resolve(
+        path.dirname(configPath),
+        config.extends,
+      )
+      const baseConfig = loadApiExtractorConfig(baseConfigPath)
+      if (baseConfig) {
+        // Merge base config with current config
+        const merged = mergeConfigs(baseConfig, config)
+        configCache.set(configPath, merged)
+        return merged
+      }
+    }
+
+    configCache.set(configPath, config)
+    return config
+  } catch {
+    configCache.set(configPath, null)
+    return null
+  }
+}
+
+/**
+ * Merges two API Extractor configurations, with the override taking precedence.
+ */
+function mergeConfigs(
+  base: ApiExtractorConfig,
+  override: ApiExtractorConfig,
+): ApiExtractorConfig {
+  return {
+    ...base,
+    ...override,
+    messages: {
+      compilerMessageReporting: {
+        ...base.messages?.compilerMessageReporting,
+        ...override.messages?.compilerMessageReporting,
+      },
+      extractorMessageReporting: {
+        ...base.messages?.extractorMessageReporting,
+        ...override.messages?.extractorMessageReporting,
+      },
+      tsdocMessageReporting: {
+        ...base.messages?.tsdocMessageReporting,
+        ...override.messages?.tsdocMessageReporting,
+      },
+    },
+  }
+}
+
+/**
+ * Gets the log level for a specific message ID from the configuration.
+ *
+ * @param config - API Extractor configuration
+ * @param messageId - The message ID (e.g., 'ae-missing-release-tag')
+ * @returns The configured log level, or 'warning' as default
+ */
+export function getMessageLogLevel(
+  config: ApiExtractorConfig | null,
+  messageId: string,
+): ApiExtractorLogLevel {
+  if (!config?.messages?.extractorMessageReporting) {
+    return (
+      DEFAULT_MESSAGES_CONFIG.extractorMessageReporting?.default?.logLevel ??
+      'warning'
+    )
+  }
+
+  const reporting = config.messages.extractorMessageReporting
+  const messageConfig = reporting[messageId]
+
+  if (messageConfig?.logLevel) {
+    return messageConfig.logLevel
+  }
+
+  return reporting.default?.logLevel ?? 'warning'
+}
+
+/**
+ * Resolves configuration for a file, using auto-discovery or explicit path.
+ *
+ * @param filePath - Path to the file being linted
+ * @param explicitConfigPath - Optional explicit path to api-extractor.json
+ * @returns The resolved configuration or null
+ */
+export function resolveConfig(
+  filePath: string,
+  explicitConfigPath?: string,
+): ApiExtractorConfig | null {
+  if (explicitConfigPath) {
+    return loadApiExtractorConfig(explicitConfigPath)
+  }
+
+  const discovered = findApiExtractorConfig(path.dirname(filePath))
+  if (discovered) {
+    return loadApiExtractorConfig(discovered)
+  }
+
+  return null
+}
+
+/**
+ * Maps API Extractor log level to ESLint severity.
+ *
+ * @param logLevel - API Extractor log level
+ * @returns ESLint severity (0 = off, 1 = warn, 2 = error)
+ */
+export function logLevelToSeverity(logLevel: ApiExtractorLogLevel): 0 | 1 | 2 {
+  switch (logLevel) {
+    case 'error':
+      return 2
+    case 'warning':
+      return 1
+    case 'none':
+      return 0
+  }
+}
+
+/**
+ * Clears the configuration cache. Useful for testing.
+ */
+export function clearConfigCache(): void {
+  configCache.clear()
+}

package/src/utils/entry-point.ts

@@ -0,0 +1,247 @@
+/**
+ * Utilities for resolving package.json entry points.
+ * @internal
+ */
+
+import * as fs from 'fs'
+import * as path from 'path'
+import type { ResolvedEntryPoints } from '../types'
+
+/**
+ * Represents the relevant fields from package.json.
+ */
+interface PackageJson {
+  main?: string
+  types?: string
+  typings?: string
+  module?: string
+  exports?: PackageExports
+}
+
+/**
+ * Package.json exports field can be complex.
+ */
+type PackageExports =
+  | string
+  | { [key: string]: PackageExports | string | undefined }
+  | undefined
+
+/**
+ * Cache for package.json lookups.
+ */
+const packageJsonCache = new Map<string, PackageJson | null>()
+
+/**
+ * Finds the nearest package.json by searching upward from a directory.
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Path to package.json if found, undefined otherwise
+ */
+export function findPackageJson(startDir: string): string | undefined {
+  let currentDir = path.resolve(startDir)
+  const root = path.parse(currentDir).root
+
+  while (currentDir !== root) {
+    const pkgPath = path.join(currentDir, 'package.json')
+    if (fs.existsSync(pkgPath)) {
+      return pkgPath
+    }
+    currentDir = path.dirname(currentDir)
+  }
+
+  return undefined
+}
+
+/**
+ * Loads and parses a package.json file.
+ *
+ * @param pkgPath - Path to the package.json file
+ * @returns Parsed package.json or null if file cannot be read
+ */
+export function loadPackageJson(pkgPath: string): PackageJson | null {
+  const cached = packageJsonCache.get(pkgPath)
+  if (cached !== undefined) {
+    return cached
+  }
+
+  try {
+    const content = fs.readFileSync(pkgPath, 'utf-8')
+    const pkg = JSON.parse(content) as PackageJson
+    packageJsonCache.set(pkgPath, pkg)
+    return pkg
+  } catch {
+    packageJsonCache.set(pkgPath, null)
+    return null
+  }
+}
+
+/**
+ * Extracts all entry point paths from package.json exports field.
+ *
+ * @param exports - The exports field value
+ * @param results - Array to collect results
+ */
+function extractExportPaths(exports: PackageExports, results: string[]): void {
+  if (typeof exports === 'string') {
+    results.push(exports)
+    return
+  }
+
+  if (exports && typeof exports === 'object') {
+    for (const value of Object.values(exports)) {
+      if (value !== undefined) {
+        extractExportPaths(value, results)
+      }
+    }
+  }
+}
+
+/**
+ * Resolves all entry points from a package.json.
+ *
+ * @param pkgPath - Path to the package.json file
+ * @returns Resolved entry points with absolute paths
+ */
+export function resolveEntryPoints(pkgPath: string): ResolvedEntryPoints {
+  const pkg = loadPackageJson(pkgPath)
+  const pkgDir = path.dirname(pkgPath)
+  const result: ResolvedEntryPoints = { exports: [] }
+
+  if (!pkg) {
+    return result
+  }
+
+  // Resolve main entry point
+  if (pkg.main) {
+    result.main = path.resolve(pkgDir, pkg.main)
+  }
+
+  // Resolve types entry point
+  if (pkg.types) {
+    result.types = path.resolve(pkgDir, pkg.types)
+  } else if (pkg.typings) {
+    result.types = path.resolve(pkgDir, pkg.typings)
+  }
+
+  // Resolve exports
+  if (pkg.exports) {
+    const exportPaths: string[] = []
+    extractExportPaths(pkg.exports, exportPaths)
+    result.exports = exportPaths.map((p) => path.resolve(pkgDir, p))
+  }
+
+  return result
+}
+
+/**
+ * Checks if a file is a package entry point.
+ *
+ * @param filePath - Absolute path to the file being checked
+ * @param pkgPath - Path to the package.json
+ * @returns True if the file is an entry point
+ */
+export function isEntryPoint(filePath: string, pkgPath: string): boolean {
+  const entryPoints = resolveEntryPoints(pkgPath)
+  const absoluteFilePath = path.resolve(filePath)
+
+  // Check main
+  if (
+    entryPoints.main &&
+    normalizeForComparison(entryPoints.main) ===
+      normalizeForComparison(absoluteFilePath)
+  ) {
+    return true
+  }
+
+  // Check types
+  if (
+    entryPoints.types &&
+    normalizeForComparison(entryPoints.types) ===
+      normalizeForComparison(absoluteFilePath)
+  ) {
+    return true
+  }
+
+  // Check exports
+  for (const exportPath of entryPoints.exports) {
+    if (
+      normalizeForComparison(exportPath) ===
+      normalizeForComparison(absoluteFilePath)
+    ) {
+      return true
+    }
+  }
+
+  // Also check if the TypeScript source file corresponds to the entry point
+  // e.g., src/index.ts -> dist/index.js
+  const sourceEquivalents = getSourceEquivalents(absoluteFilePath)
+  for (const sourcePath of sourceEquivalents) {
+    if (
+      entryPoints.main &&
+      normalizeForComparison(entryPoints.main) ===
+        normalizeForComparison(sourcePath)
+    ) {
+      return true
+    }
+    if (
+      entryPoints.types &&
+      normalizeForComparison(entryPoints.types) ===
+        normalizeForComparison(sourcePath)
+    ) {
+      return true
+    }
+    for (const exportPath of entryPoints.exports) {
+      if (
+        normalizeForComparison(exportPath) ===
+        normalizeForComparison(sourcePath)
+      ) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Normalizes a path for comparison by removing extension variations.
+ */
+function normalizeForComparison(filePath: string): string {
+  // Remove common extensions and normalize
+  return filePath
+    .replace(/\.(js|ts|mjs|cjs|mts|cts|d\.ts|d\.mts|d\.cts)$/, '')
+    .replace(/\/index$/, '')
+}
+
+/**
+ * Gets potential source file equivalents for a dist file.
+ */
+function getSourceEquivalents(filePath: string): string[] {
+  const equivalents: string[] = []
+  const dir = path.dirname(filePath)
+  const base = path.basename(filePath).replace(/\.(ts|tsx|js|jsx|mjs|cjs)$/, '')
+
+  // Try common source directory patterns
+  const sourcePatterns = [
+    dir.replace('/dist/', '/src/').replace('\\dist\\', '\\src\\'),
+    dir.replace('/build/', '/src/').replace('\\build\\', '\\src\\'),
+    dir.replace('/lib/', '/src/').replace('\\lib\\', '\\src\\'),
+  ]
+
+  for (const sourceDir of sourcePatterns) {
+    if (sourceDir !== dir) {
+      equivalents.push(path.join(sourceDir, `${base}.ts`))
+      equivalents.push(path.join(sourceDir, `${base}.tsx`))
+      equivalents.push(path.join(sourceDir, `${base}.js`))
+    }
+  }
+
+  return equivalents
+}
+
+/**
+ * Clears the package.json cache. Useful for testing.
+ */
+export function clearPackageJsonCache(): void {
+  packageJsonCache.clear()
+}

package/src/utils/index.ts

@@ -0,0 +1,17 @@
+/**
+ * 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'