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

package/src/utils/tsdoc-parser.ts

@@ -0,0 +1,163 @@
+/**
+ * Utilities for parsing TSDoc comments.
+ * @internal
+ */
+
+import {
+  TSDocParser,
+  TSDocConfiguration,
+  TextRange,
+  ParserContext,
+  DocComment,
+} from '@microsoft/tsdoc'
+import type { TSESTree } from '@typescript-eslint/utils'
+import type { ReleaseTag } from '../types'
+
+/**
+ * TSDoc parser instance configured for API Extractor compatibility.
+ */
+let parserInstance: TSDocParser | undefined
+
+/**
+ * Gets or creates a TSDoc parser instance.
+ */
+function getParser(): TSDocParser {
+  if (!parserInstance) {
+    const config = new TSDocConfiguration()
+    // API Extractor's custom tags are defined via tsdoc.json extends
+    // For our purposes, the default configuration suffices as we're
+    // checking for standard modifier tags
+    parserInstance = new TSDocParser(config)
+  }
+  return parserInstance
+}
+
+/**
+ * Parses a TSDoc comment string.
+ *
+ * @param commentText - The full comment text including delimiters
+ * @returns Parser context with the parsed doc comment
+ */
+export function parseTSDocComment(commentText: string): ParserContext {
+  const parser = getParser()
+  const textRange = TextRange.fromString(commentText)
+  return parser.parseRange(textRange)
+}
+
+/**
+ * Extracts a release tag from a parsed TSDoc comment.
+ *
+ * @param docComment - The parsed doc comment
+ * @returns The release tag if found, undefined otherwise
+ */
+export function extractReleaseTag(
+  docComment: DocComment,
+): ReleaseTag | undefined {
+  // Check for modifier tags
+  if (docComment.modifierTagSet.isPublic()) {
+    return 'public'
+  }
+  if (docComment.modifierTagSet.isBeta()) {
+    return 'beta'
+  }
+  if (docComment.modifierTagSet.isAlpha()) {
+    return 'alpha'
+  }
+  if (docComment.modifierTagSet.isInternal()) {
+    return 'internal'
+  }
+  return undefined
+}
+
+/**
+ * Checks if a TSDoc comment has the @override tag.
+ *
+ * @param docComment - The parsed doc comment
+ * @returns True if @override tag is present
+ */
+export function hasOverrideTag(docComment: DocComment): boolean {
+  return docComment.modifierTagSet.isOverride()
+}
+
+/**
+ * Checks if a TSDoc comment has the @packageDocumentation tag.
+ *
+ * @param docComment - The parsed doc comment
+ * @returns True if @packageDocumentation tag is present
+ */
+export function hasPackageDocumentation(docComment: DocComment): boolean {
+  return docComment.modifierTagSet.isPackageDocumentation()
+}
+
+/**
+ * Checks if a comment is a block comment (TSDoc style).
+ */
+function isBlockComment(comment: TSESTree.Comment): boolean {
+  // TSESTree.Comment.type is 'Line' | 'Block' - comparing to string literal
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-enum-comparison
+  return comment.type === 'Block'
+}
+
+/**
+ * Gets the leading comment for a node, if it's a TSDoc comment.
+ *
+ * @param sourceCode - ESLint source code object
+ * @param node - The AST node to check
+ * @returns The comment text if a TSDoc comment exists, undefined otherwise
+ */
+export function getLeadingTSDocComment(
+  sourceCode: {
+    getCommentsBefore: (node: TSESTree.Node) => TSESTree.Comment[]
+  },
+  node: TSESTree.Node,
+): string | undefined {
+  const comments = sourceCode.getCommentsBefore(node)
+  if (comments.length === 0) {
+    return undefined
+  }
+
+  // Get the last comment before the node (closest to it)
+  const lastComment = comments[comments.length - 1]
+  if (!lastComment) {
+    return undefined
+  }
+
+  // TSDoc comments must be block comments starting with /**
+  if (!isBlockComment(lastComment)) {
+    return undefined
+  }
+
+  // Check if it's a TSDoc comment (starts with *)
+  const value = lastComment.value
+  if (!value.startsWith('*')) {
+    return undefined
+  }
+
+  // Reconstruct the full comment
+  return `/*${value}*/`
+}
+
+/**
+ * Finds all TSDoc comments in a source file.
+ *
+ * @param sourceCode - ESLint source code object
+ * @returns Array of comment objects with their parsed content
+ */
+export function findAllTSDocComments(sourceCode: {
+  getAllComments: () => TSESTree.Comment[]
+}): Array<{ comment: TSESTree.Comment; parsed: ParserContext }> {
+  const results: Array<{ comment: TSESTree.Comment; parsed: ParserContext }> =
+    []
+
+  for (const comment of sourceCode.getAllComments()) {
+    if (!isBlockComment(comment) || !comment.value.startsWith('*')) {
+      continue
+    }
+
+    const commentText = `/*${comment.value}*/`
+    const parsed = parseTSDocComment(commentText)
+    results.push({ comment, parsed })
+  }
+
+  return results
+}

package/temp/eslint-plugin.api.md

@@ -0,0 +1,118 @@
+## API Report File for "@api-extractor-tools/eslint-plugin"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { RuleListener } from '@typescript-eslint/utils/dist/ts-eslint';
+import { RuleModule } from '@typescript-eslint/utils/dist/ts-eslint';
+import type { TSESLint } from '@typescript-eslint/utils';
+
+// @public
+export interface ApiExtractorConfig {
+    // (undocumented)
+    extends?: string;
+    // (undocumented)
+    mainEntryPointFilePath?: string;
+    // (undocumented)
+    messages?: ApiExtractorMessagesConfig;
+}
+
+// @public
+export interface ApiExtractorEslintPlugin {
+    // Warning: (ae-forgotten-export) The symbol "PluginConfigs" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    configs: PluginConfigs;
+    // (undocumented)
+    meta: {
+        name: string;
+        version: string;
+    };
+    // (undocumented)
+    rules: typeof rules;
+}
+
+// @public
+export type ApiExtractorLogLevel = 'error' | 'warning' | 'none';
+
+// @public
+export interface ApiExtractorMessagesConfig {
+    // (undocumented)
+    compilerMessageReporting?: {
+        default?: MessageConfig;
+        [messageId: string]: MessageConfig | undefined;
+    };
+    // (undocumented)
+    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;
+    };
+    // (undocumented)
+    tsdocMessageReporting?: {
+        default?: MessageConfig;
+        [messageId: string]: MessageConfig | undefined;
+    };
+}
+
+// @public
+export interface MessageConfig {
+    // (undocumented)
+    addToApiReportFile?: boolean;
+    // (undocumented)
+    logLevel: ApiExtractorLogLevel;
+}
+
+// @public
+export interface MissingReleaseTagRuleOptions {
+    // (undocumented)
+    configPath?: string;
+}
+
+// @public
+export interface OverrideKeywordRuleOptions {
+    // (undocumented)
+    configPath?: string;
+}
+
+// @public
+export interface PackageDocumentationRuleOptions {
+    // (undocumented)
+    configPath?: string;
+}
+
+// @public
+const plugin: ApiExtractorEslintPlugin;
+export default plugin;
+
+// @public
+export const recommendedRules: TSESLint.Linter.RulesRecord;
+
+// @public
+export const RELEASE_TAGS: readonly ReleaseTag[];
+
+// @public
+export type ReleaseTag = 'public' | 'beta' | 'alpha' | 'internal';
+
+// @public
+export interface ResolvedEntryPoints {
+    // (undocumented)
+    exports: string[];
+    // (undocumented)
+    main?: string;
+    // (undocumented)
+    types?: string;
+}
+
+// @public
+export const rules: {
+    readonly 'missing-release-tag': RuleModule<"missingReleaseTag", [MissingReleaseTagRuleOptions], unknown, RuleListener>;
+    readonly 'override-keyword': RuleModule<"missingOverrideKeyword", [OverrideKeywordRuleOptions], unknown, RuleListener>;
+    readonly 'package-documentation': RuleModule<"missingPackageDocumentation", [PackageDocumentationRuleOptions], unknown, RuleListener>;
+};
+
+```

package/test/index.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from 'vitest'
+import plugin, { rules, recommendedRules, RELEASE_TAGS } from '../src/index'
+
+describe('eslint-plugin', () => {
+  describe('plugin exports', () => {
+    it('should export plugin meta', () => {
+      expect(plugin.meta).toBeDefined()
+      expect(plugin.meta.name).toBe('@api-extractor-tools/eslint-plugin')
+      expect(plugin.meta.version).toBeDefined()
+    })
+
+    it('should export all rules', () => {
+      expect(plugin.rules).toBeDefined()
+      expect(plugin.rules['missing-release-tag']).toBeDefined()
+      expect(plugin.rules['override-keyword']).toBeDefined()
+      expect(plugin.rules['package-documentation']).toBeDefined()
+    })
+
+    it('should export configs', () => {
+      expect(plugin.configs).toBeDefined()
+      expect(plugin.configs.recommended).toBeDefined()
+      expect(plugin.configs['recommended-legacy']).toBeDefined()
+    })
+  })
+
+  describe('named exports', () => {
+    it('should export rules object', () => {
+      expect(rules).toBeDefined()
+      expect(rules['missing-release-tag']).toBeDefined()
+      expect(rules['override-keyword']).toBeDefined()
+      expect(rules['package-documentation']).toBeDefined()
+    })
+
+    it('should export recommendedRules', () => {
+      expect(recommendedRules).toBeDefined()
+      expect(recommendedRules['@api-extractor-tools/missing-release-tag']).toBe(
+        'warn',
+      )
+      expect(recommendedRules['@api-extractor-tools/override-keyword']).toBe(
+        'error',
+      )
+      expect(
+        recommendedRules['@api-extractor-tools/package-documentation'],
+      ).toBe('warn')
+    })
+
+    it('should export RELEASE_TAGS', () => {
+      expect(RELEASE_TAGS).toEqual(['public', 'beta', 'alpha', 'internal'])
+    })
+  })
+
+  describe('recommended config', () => {
+    it('should have correct structure for flat config', () => {
+      const config = plugin.configs.recommended
+      expect(config.plugins).toBeDefined()
+      expect(config.plugins?.['@api-extractor-tools']).toBe(plugin)
+      expect(config.rules).toEqual(recommendedRules)
+    })
+
+    it('should have correct structure for legacy config', () => {
+      const config = plugin.configs['recommended-legacy']
+      expect(config.plugins).toEqual(['@api-extractor-tools'])
+      expect(config.rules).toEqual(recommendedRules)
+    })
+  })
+})

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

@@ -0,0 +1,184 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, afterAll } from 'vitest'
+import { missingReleaseTag } from '../../src/rules/missing-release-tag'
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: require('@typescript-eslint/parser'),
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
+
+describe('missing-release-tag', () => {
+  ruleTester.run('missing-release-tag', missingReleaseTag, {
+    valid: [
+      // Exported function with @public tag
+      {
+        code: `
+/**
+ * A public function.
+ * @public
+ */
+export function myFunction() {}
+`,
+      },
+      // Exported function with @beta tag
+      {
+        code: `
+/**
+ * A beta function.
+ * @beta
+ */
+export function myBetaFunction() {}
+`,
+      },
+      // Exported function with @alpha tag
+      {
+        code: `
+/**
+ * An alpha function.
+ * @alpha
+ */
+export function myAlphaFunction() {}
+`,
+      },
+      // Exported function with @internal tag
+      {
+        code: `
+/**
+ * An internal function.
+ * @internal
+ */
+export function myInternalFunction() {}
+`,
+      },
+      // Exported class with release tag
+      {
+        code: `
+/**
+ * A public class.
+ * @public
+ */
+export class MyClass {}
+`,
+      },
+      // Exported interface with release tag
+      {
+        code: `
+/**
+ * A public interface.
+ * @public
+ */
+export interface MyInterface {}
+`,
+      },
+      // Exported type with release tag
+      {
+        code: `
+/**
+ * A public type.
+ * @public
+ */
+export type MyType = string;
+`,
+      },
+      // Exported enum with release tag
+      {
+        code: `
+/**
+ * A public enum.
+ * @public
+ */
+export enum MyEnum { A, B }
+`,
+      },
+      // Exported const with release tag
+      {
+        code: `
+/**
+ * A public constant.
+ * @public
+ */
+export const MY_CONST = 42;
+`,
+      },
+      // Non-exported function (no release tag needed)
+      {
+        code: `
+function privateFunction() {}
+`,
+      },
+      // Non-exported class
+      {
+        code: `
+class PrivateClass {}
+`,
+      },
+    ],
+    invalid: [
+      // Exported function without release tag
+      {
+        code: `
+/**
+ * A function without release tag.
+ */
+export function myFunction() {}
+`,
+        errors: [{ messageId: 'missingReleaseTag' }],
+      },
+      // Exported class without release tag
+      {
+        code: `
+/**
+ * A class without release tag.
+ */
+export class MyClass {}
+`,
+        errors: [{ messageId: 'missingReleaseTag' }],
+      },
+      // Exported function without any comment
+      {
+        code: `export function myFunction() {}`,
+        errors: [{ messageId: 'missingReleaseTag' }],
+      },
+      // Exported interface without release tag
+      {
+        code: `
+/**
+ * An interface without release tag.
+ */
+export interface MyInterface {}
+`,
+        errors: [{ messageId: 'missingReleaseTag' }],
+      },
+      // Exported type without release tag
+      {
+        code: `
+export type MyType = string;
+`,
+        errors: [{ messageId: 'missingReleaseTag' }],
+      },
+      // Exported enum without release tag
+      {
+        code: `
+export enum MyEnum { A, B }
+`,
+        errors: [{ messageId: 'missingReleaseTag' }],
+      },
+      // Exported const without release tag
+      {
+        code: `
+export const MY_CONST = 42;
+`,
+        errors: [{ messageId: 'missingReleaseTag' }],
+      },
+    ],
+  })
+})

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

@@ -0,0 +1,171 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, afterAll } from 'vitest'
+import { overrideKeyword } from '../../src/rules/override-keyword'
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: require('@typescript-eslint/parser'),
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
+
+describe('override-keyword', () => {
+  ruleTester.run('override-keyword', overrideKeyword, {
+    valid: [
+      // Method with @override and override keyword
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  override doSomething() {}
+}
+`,
+      },
+      // Property with @override and override keyword
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  override myProperty = 42;
+}
+`,
+      },
+      // Method without @override tag (no override keyword needed)
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * A method without override tag.
+   */
+  doSomething() {}
+}
+`,
+      },
+      // Method with override keyword but no @override tag (allowed)
+      {
+        code: `
+class Child extends Parent {
+  override doSomething() {}
+}
+`,
+      },
+      // Static method with @override and override keyword
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  static override staticMethod() {}
+}
+`,
+      },
+      // Constructor (should be skipped)
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * Constructor.
+   */
+  constructor() {
+    super();
+  }
+}
+`,
+      },
+    ],
+    invalid: [
+      // Method with @override but missing override keyword
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  doSomething() {}
+}
+`,
+        output: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  override doSomething() {}
+}
+`,
+        errors: [{ messageId: 'missingOverrideKeyword' }],
+      },
+      // Property with @override but missing override keyword
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  myProperty = 42;
+}
+`,
+        output: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  override myProperty = 42;
+}
+`,
+        errors: [{ messageId: 'missingOverrideKeyword' }],
+      },
+      // Getter with @override but missing override keyword
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  get myGetter() { return 42; }
+}
+`,
+        output: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  override get myGetter() { return 42; }
+}
+`,
+        errors: [{ messageId: 'missingOverrideKeyword' }],
+      },
+      // Setter with @override but missing override keyword
+      {
+        code: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  set mySetter(value: number) {}
+}
+`,
+        output: `
+class Child extends Parent {
+  /**
+   * @override
+   */
+  override set mySetter(value: number) {}
+}
+`,
+        errors: [{ messageId: 'missingOverrideKeyword' }],
+      },
+    ],
+  })
+})