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

package/temp/eslint-plugin.api.md

@@ -4,11 +4,14 @@
 
 ```ts
 
+import { DocComment } from '@microsoft/tsdoc';
+import { ParserContext } from '@microsoft/tsdoc';
 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';
+import type { TSESTree } from '@typescript-eslint/utils';
 
-// @public
+// @alpha
 export interface ApiExtractorConfig {
     // (undocumented)
     extends?: string;
@@ -18,7 +21,7 @@ export interface ApiExtractorConfig {
     messages?: ApiExtractorMessagesConfig;
 }
 
-// @public
+// @alpha
 export interface ApiExtractorEslintPlugin {
     // Warning: (ae-forgotten-export) The symbol "PluginConfigs" needs to be exported by the entry point index.d.ts
     //
@@ -33,33 +36,82 @@ export interface ApiExtractorEslintPlugin {
     rules: typeof rules;
 }
 
-// @public
-export type ApiExtractorLogLevel = 'error' | 'warning' | 'none';
+// @alpha
+export type ApiExtractorLogLevel = 'error' | 'none' | 'warning';
 
-// @public
+// @alpha
 export interface ApiExtractorMessagesConfig {
     // (undocumented)
     compilerMessageReporting?: {
-        default?: MessageConfig;
         [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
     };
     // (undocumented)
     extractorMessageReporting?: {
-        default?: MessageConfig;
-        'ae-missing-release-tag'?: MessageConfig;
+        'ae-extra-release-tag'?: MessageConfig;
         'ae-forgotten-export'?: MessageConfig;
-        'ae-internal-missing-underscore'?: MessageConfig;
         'ae-incompatible-release-tags'?: MessageConfig;
+        'ae-internal-missing-underscore'?: MessageConfig;
+        'ae-missing-release-tag'?: MessageConfig;
         [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
     };
     // (undocumented)
     tsdocMessageReporting?: {
-        default?: MessageConfig;
         [messageId: string]: MessageConfig | undefined;
+        default?: MessageConfig;
     };
 }
 
-// @public
+// @alpha
+export interface EnumTypeExtraction {
+    count: number;
+    found: boolean;
+    isValid: boolean;
+    rawValue?: string;
+    value?: string;
+}
+
+// @alpha
+export type EnumTypeValue = 'closed' | 'open';
+
+// @alpha
+export function extractEnumType(commentText: string): EnumTypeExtraction;
+
+// @alpha
+export function extractReleaseTag(docComment: DocComment): ReleaseTag | undefined;
+
+// @alpha
+export interface ExtraReleaseTagRuleOptions {
+    severity?: ApiExtractorLogLevel;
+}
+
+// @alpha
+export function findAllTSDocComments(sourceCode: { getAllComments: () => TSESTree.Comment[] }): Array<{
+    comment: TSESTree.Comment;
+    parsed: ParserContext;
+}>;
+
+// @alpha
+export interface ForgottenExportRuleOptions {
+    severity?: ApiExtractorLogLevel;
+}
+
+// @alpha
+export function getLeadingTSDocComment(sourceCode: { getCommentsBefore: (node: TSESTree.Node) => TSESTree.Comment[] }, node: TSESTree.Node): string | undefined;
+
+// @alpha @override
+export function hasOverrideTag(docComment: DocComment): boolean;
+
+// @alpha
+export function hasPackageDocumentation(docComment: DocComment): boolean;
+
+// @alpha
+export interface IncompatibleReleaseTagsRuleOptions {
+    severity?: ApiExtractorLogLevel;
+}
+
+// @alpha
 export interface MessageConfig {
     // (undocumented)
     addToApiReportFile?: boolean;
@@ -67,38 +119,44 @@ export interface MessageConfig {
     logLevel: ApiExtractorLogLevel;
 }
 
-// @public
+// @alpha
 export interface MissingReleaseTagRuleOptions {
-    // (undocumented)
-    configPath?: string;
+    severity?: ApiExtractorLogLevel;
 }
 
-// @public
-export interface OverrideKeywordRuleOptions {
-    // (undocumented)
-    configPath?: string;
-}
+// @alpha
+export type OverrideKeywordRuleOptions = Record<string, never>;
 
-// @public
-export interface PackageDocumentationRuleOptions {
-    // (undocumented)
-    configPath?: string;
-}
+// @alpha
+export type PackageDocumentationRuleOptions = Record<string, never>;
+
+// @alpha
+export function parseTSDocComment(commentText: string): ParserContext;
 
-// @public
+// @alpha
 const plugin: ApiExtractorEslintPlugin;
 export default plugin;
 
-// @public
+// @alpha
+export interface PublicOnNonExportedRuleOptions {
+    severity?: ApiExtractorLogLevel;
+}
+
+// @alpha
+export interface PublicOnPrivateMemberRuleOptions {
+    severity?: ApiExtractorLogLevel;
+}
+
+// @alpha
 export const recommendedRules: TSESLint.Linter.RulesRecord;
 
-// @public
+// @alpha
 export const RELEASE_TAGS: readonly ReleaseTag[];
 
-// @public
-export type ReleaseTag = 'public' | 'beta' | 'alpha' | 'internal';
+// @alpha
+export type ReleaseTag = 'alpha' | 'beta' | 'internal' | 'public';
 
-// @public
+// @alpha
 export interface ResolvedEntryPoints {
     // (undocumented)
     exports: string[];
@@ -108,11 +166,22 @@ export interface ResolvedEntryPoints {
     types?: string;
 }
 
-// @public
+// @alpha
 export const rules: {
+    readonly 'extra-release-tag': RuleModule<"extraReleaseTag", [ExtraReleaseTagRuleOptions], unknown, RuleListener>;
+    readonly 'forgotten-export': RuleModule<"forgottenExport", [ForgottenExportRuleOptions], unknown, RuleListener>;
+    readonly 'incompatible-release-tags': RuleModule<"incompatibleReleaseTags", [IncompatibleReleaseTagsRuleOptions], unknown, RuleListener>;
     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>;
+    readonly 'package-documentation': RuleModule<"missingPackageDocumentation" | "unexpectedPackageDocumentation", [PackageDocumentationRuleOptions], unknown, RuleListener>;
+    readonly 'public-on-non-exported': RuleModule<"publicOnNonExported", [PublicOnNonExportedRuleOptions], unknown, RuleListener>;
+    readonly 'public-on-private-member': RuleModule<"publicOnPrivateMember", [PublicOnPrivateMemberRuleOptions], unknown, RuleListener>;
+    readonly 'valid-enum-type': RuleModule<"missingValue" | "invalidValue" | "multipleEnumTypes" | "invalidConstruct" | "missingEnumType", [ValidEnumTypeRuleOptions], unknown, RuleListener>;
 };
 
+// @alpha
+export interface ValidEnumTypeRuleOptions {
+    requireOnExported?: boolean;
+}
+
 ```

package/test/index.test.ts

@@ -64,3 +64,4 @@ describe('eslint-plugin', () => {
     })
   })
 })
+

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

@@ -0,0 +1,276 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, afterAll } from 'vitest'
+import * as tseslintParser from '@typescript-eslint/parser'
+import { extraReleaseTag } from '../../src/rules/extra-release-tag'
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: tseslintParser,
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
+
+describe('extra-release-tag', () => {
+  ruleTester.run('extra-release-tag', extraReleaseTag, {
+    valid: [
+      // Single @public tag
+      {
+        code: `
+/**
+ * A public function.
+ * @public
+ */
+export function myFunction(): void {}
+`,
+      },
+      // Single @beta tag
+      {
+        code: `
+/**
+ * A beta function.
+ * @beta
+ */
+export function myBetaFunction(): void {}
+`,
+      },
+      // Single @alpha tag
+      {
+        code: `
+/**
+ * An alpha function.
+ * @alpha
+ */
+export function myAlphaFunction(): void {}
+`,
+      },
+      // Single @internal tag
+      {
+        code: `
+/**
+ * An internal function.
+ * @internal
+ */
+export function myInternalFunction(): void {}
+`,
+      },
+      // No release tag
+      {
+        code: `
+/**
+ * A function without release tag.
+ */
+export function myFunction(): void {}
+`,
+      },
+      // Single tag on class
+      {
+        code: `
+/**
+ * A public class.
+ * @public
+ */
+export class MyClass {}
+`,
+      },
+      // Single tag on interface
+      {
+        code: `
+/**
+ * A public interface.
+ * @public
+ */
+export interface MyInterface {}
+`,
+      },
+      // Single tag on type alias
+      {
+        code: `
+/**
+ * A public type.
+ * @public
+ */
+export type MyType = string;
+`,
+      },
+      // Single tag on enum
+      {
+        code: `
+/**
+ * A public enum.
+ * @public
+ */
+export enum MyEnum { A, B }
+`,
+      },
+    ],
+    invalid: [
+      // Both @public and @beta
+      {
+        code: `
+/**
+ * A function with multiple tags.
+ * @public
+ * @beta
+ */
+export function myFunction(): void {}
+`,
+        errors: [
+          {
+            messageId: 'extraReleaseTag',
+            data: {
+              name: 'myFunction',
+              tags: '@public, @beta',
+            },
+          },
+        ],
+      },
+      // Both @public and @alpha
+      {
+        code: `
+/**
+ * A function with multiple tags.
+ * @public
+ * @alpha
+ */
+export function myFunction(): void {}
+`,
+        errors: [
+          {
+            messageId: 'extraReleaseTag',
+            data: {
+              name: 'myFunction',
+              tags: '@public, @alpha',
+            },
+          },
+        ],
+      },
+      // Both @beta and @internal
+      {
+        code: `
+/**
+ * A function with multiple tags.
+ * @beta
+ * @internal
+ */
+export function myFunction(): void {}
+`,
+        errors: [
+          {
+            messageId: 'extraReleaseTag',
+            data: {
+              name: 'myFunction',
+              tags: '@beta, @internal',
+            },
+          },
+        ],
+      },
+      // Three tags
+      {
+        code: `
+/**
+ * A function with three tags.
+ * @public
+ * @beta
+ * @alpha
+ */
+export function myFunction(): void {}
+`,
+        errors: [
+          {
+            messageId: 'extraReleaseTag',
+            data: {
+              name: 'myFunction',
+              tags: '@public, @beta, @alpha',
+            },
+          },
+        ],
+      },
+      // Multiple tags on class
+      {
+        code: `
+/**
+ * A class with multiple tags.
+ * @public
+ * @internal
+ */
+export class MyClass {}
+`,
+        errors: [
+          {
+            messageId: 'extraReleaseTag',
+            data: {
+              name: 'MyClass',
+              tags: '@public, @internal',
+            },
+          },
+        ],
+      },
+      // Multiple tags on interface
+      {
+        code: `
+/**
+ * An interface with multiple tags.
+ * @beta
+ * @alpha
+ */
+export interface MyInterface {}
+`,
+        errors: [
+          {
+            messageId: 'extraReleaseTag',
+            data: {
+              name: 'MyInterface',
+              tags: '@beta, @alpha',
+            },
+          },
+        ],
+      },
+      // Multiple tags on type alias
+      {
+        code: `
+/**
+ * A type with multiple tags.
+ * @public
+ * @beta
+ */
+export type MyType = string;
+`,
+        errors: [
+          {
+            messageId: 'extraReleaseTag',
+            data: {
+              name: 'MyType',
+              tags: '@public, @beta',
+            },
+          },
+        ],
+      },
+    ],
+  })
+
+  // Test with severity option
+  ruleTester.run('extra-release-tag with severity=none', extraReleaseTag, {
+    valid: [
+      // Should not report when severity is 'none'
+      {
+        code: `
+/**
+ * A function with multiple tags.
+ * @public
+ * @beta
+ */
+export function myFunction(): void {}
+`,
+        options: [{ severity: 'none' }],
+      },
+    ],
+    invalid: [],
+  })
+})

package/test/rules/forgotten-export.test.ts

@@ -0,0 +1,190 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { describe, it, afterAll } from 'vitest'
+import * as tseslintParser from '@typescript-eslint/parser'
+import { forgottenExport } from '../../src/rules/forgotten-export'
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    parser: tseslintParser,
+    parserOptions: {
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+  },
+})
+
+describe('forgotten-export', () => {
+  ruleTester.run('forgotten-export', forgottenExport, {
+    valid: [
+      // Both the interface and function are exported
+      {
+        code: `
+export interface MyInterface {
+  name: string;
+}
+
+export function myFunction(param: MyInterface): void {}
+`,
+      },
+      // Using only built-in types
+      {
+        code: `
+export function myFunction(param: string): number {
+  return 0;
+}
+`,
+      },
+      // Type is not defined in the file (imported or built-in)
+      {
+        code: `
+export function myFunction(param: Date): void {}
+`,
+      },
+      // Exported type alias
+      {
+        code: `
+export type MyType = string;
+
+export function myFunction(param: MyType): void {}
+`,
+      },
+      // Exported class
+      {
+        code: `
+export class MyClass {
+  value: string = '';
+}
+
+export function useClass(c: MyClass): void {}
+`,
+      },
+      // Using generic built-in types
+      {
+        code: `
+export function myFunction(): Promise<void> {
+  return Promise.resolve();
+}
+`,
+      },
+    ],
+    invalid: [
+      // Interface used but not exported
+      {
+        code: `
+interface MyInterface {
+  name: string;
+}
+
+export function myFunction(param: MyInterface): void {}
+`,
+        errors: [
+          {
+            messageId: 'forgottenExport',
+            data: {
+              name: 'MyInterface',
+              exportedName: 'myFunction',
+            },
+          },
+        ],
+      },
+      // Type alias used but not exported
+      {
+        code: `
+type MyType = string;
+
+export function myFunction(param: MyType): void {}
+`,
+        errors: [
+          {
+            messageId: 'forgottenExport',
+            data: {
+              name: 'MyType',
+              exportedName: 'myFunction',
+            },
+          },
+        ],
+      },
+      // Class used but not exported
+      {
+        code: `
+class MyClass {
+  value: string = '';
+}
+
+export function useClass(c: MyClass): void {}
+`,
+        errors: [
+          {
+            messageId: 'forgottenExport',
+            data: {
+              name: 'MyClass',
+              exportedName: 'useClass',
+            },
+          },
+        ],
+      },
+      // Return type not exported
+      {
+        code: `
+interface Result {
+  success: boolean;
+}
+
+export function getResult(): Result {
+  return { success: true };
+}
+`,
+        errors: [
+          {
+            messageId: 'forgottenExport',
+            data: {
+              name: 'Result',
+              exportedName: 'getResult',
+            },
+          },
+        ],
+      },
+      // Type used in exported interface
+      {
+        code: `
+type InternalType = string;
+
+export interface MyInterface {
+  value: InternalType;
+}
+`,
+        errors: [
+          {
+            messageId: 'forgottenExport',
+            data: {
+              name: 'InternalType',
+              exportedName: 'MyInterface',
+            },
+          },
+        ],
+      },
+    ],
+  })
+
+  // Test with severity option
+  ruleTester.run('forgotten-export with severity=none', forgottenExport, {
+    valid: [
+      // Should not report when severity is 'none'
+      {
+        code: `
+interface MyInterface {
+  name: string;
+}
+
+export function myFunction(param: MyInterface): void {}
+`,
+        options: [{ severity: 'none' }],
+      },
+    ],
+    invalid: [],
+  })
+})