ESLint Plugin TSDoc

const plugin = require("eslint-plugin-tsdoc");

const plugin = require("eslint-plugin-tsdoc");
// plugin.rules contains the ESLint rule definitions

npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

npm install --save-dev eslint-plugin-tsdoc

// .eslintrc.js
module.exports = {
  plugins: [
    "@typescript-eslint/eslint-plugin",
    "eslint-plugin-tsdoc"
  ],
  extends: [
    'plugin:@typescript-eslint/recommended'
  ],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: "./tsconfig.json",
    tsconfigRootDir: __dirname,
    ecmaVersion: 2018,
    sourceType: "module"
  },
  rules: {
    "tsdoc/syntax": "warn"  // or "error"
  }
};

npx eslint "src/**/*.{ts,tsx}"

// Main Plugin Interface (exported via export = plugin)
interface IPlugin {
  rules: { [ruleName: string]: eslint.Rule.RuleModule };
}

// The actual exported plugin object
const plugin: IPlugin = {
  rules: {
    syntax: RuleModule
  }
};

// ESLint Rule Module Structure
interface RuleModule {
  meta: {
    messages: { [messageId: string]: string };
    type: 'problem';
    docs: {
      description: string;
      category: string;
      recommended: boolean;
      url: string;
    };
  };
  create: (context: eslint.Rule.RuleContext) => RuleListener;
}

// Rule Listener (ESLint visitor pattern)
interface RuleListener {
  Program?: (node: ESTreeNode) => void;
  [nodeType: string]: ((node: ESTreeNode) => void) | undefined;
}

// Rule Context (from ESLint)
interface RuleContext {
  filename: string;
  parserOptions: {
    tsconfigRootDir?: string;
    [key: string]: any;
  };
  getSourceCode(): SourceCode;
  report(descriptor: ReportDescriptor): void;
}

// ESLint SourceCode interface
interface SourceCode {
  text: string;
  getAllComments(): Comment[];
  getLocFromIndex(index: number): { line: number; column: number };
}

// ESLint Comment interface
interface Comment {
  type: 'Block' | 'Line';
  value: string;
  range?: [number, number];
}

// ESTree Node interface
interface ESTreeNode {
  type: string;
  [key: string]: any;
}

// Report Descriptor for TSDoc violations
interface ReportDescriptor {
  loc: {
    start: { line: number; column: number };
    end: { line: number; column: number };
  } | { line: number; column: number };
  messageId: string;
  data?: { [key: string]: string };
}

/**
 * A great function that does something useful.
 * @param name - The name parameter  
 * @returns The processed result
 */
function processData(name: string): string {
  return `Processed: ${name}`;
}

/**
 * A well-documented class.
 * @public
 */
class DataProcessor {
  /**
   * Process the input data.
   * @param input - Data to process
   * @param options - Processing options
   */
  process(input: string[], options?: { verbose: boolean }): void {
    // implementation
  }
}

/**
 * This `is wrong - missing closing backtick
 */
function badExample() {}

/**
 * @badtag This uses an undefined tag
 */
function anotherBadExample() {}

/**
 * @param missingDescription
 */
function paramWithoutDescription(param: string) {}

// Configuration and Application Errors
type ConfigErrorMessages = {
  'error-loading-config-file': 'Error loading TSDoc config file:\n{{details}}';
  'error-applying-config': 'Error applying TSDoc configuration: {{details}}';
};

// TSDoc Syntax Error Messages (dynamically loaded from @microsoft/tsdoc)
// Common examples include:
type TSDocErrorMessages = {
  'tsdoc-code-span-missing-delimiter': 'tsdoc-code-span-missing-delimiter: {{unformattedText}}';
  'tsdoc-undefined-tag': 'tsdoc-undefined-tag: {{unformattedText}}';
  'tsdoc-malformed-inline-tag': 'tsdoc-malformed-inline-tag: {{unformattedText}}';
  'tsdoc-missing-reference-target': 'tsdoc-missing-reference-target: {{unformattedText}}';
  // ... other TSDoc message IDs from the TSDoc parser
};

// tsdoc.json
{
  "extends": ["@microsoft/api-extractor-config"],
  "tagDefinitions": [
    {
      "tagName": "@customTag",
      "syntaxKind": "block",
      "allowMultiple": false
    }
  ]
}

// Main plugin interface (export = pattern)
interface IPlugin {
  rules: { [ruleName: string]: eslint.Rule.RuleModule };
}

// TSDoc Configuration File (from @microsoft/tsdoc-config)
interface TSDocConfigFile {
  fileNotFound: boolean;
  hasErrors: boolean;
  getErrorSummary(): string;
  configureParser(configuration: TSDocConfiguration): void;
  checkForModifiedFiles(): boolean;
}

// TSDoc Parser Context (from @microsoft/tsdoc)
interface ParserContext {
  log: {
    messages: Array<{
      messageId: string;
      textRange: TextRange;
      unformattedText: string;
    }>;
  };
}

// ESLint Source Code interface
interface SourceCode {
  text: string;
  getAllComments(): Comment[];
  getLocFromIndex(index: number): { line: number; column: number };
}

// ESLint Comment interface  
interface Comment {
  type: 'Block' | 'Line';
  value: string;
  range?: [number, number];
}

class Debug {
  /**
   * Log a debug message (no-op in production builds)
   * @param message - Debug message to log
   */
  static log(message: string): void;
}

class ConfigCache {
  /**
   * Get TSDoc configuration for a specific source file
   * @param sourceFilePath - Path to the source file being linted
   * @param tsConfigRootDir - Optional TypeScript config root directory
   * @returns TSDoc configuration file object
   */
  static getForSourceFile(
    sourceFilePath: string,
    tsConfigRootDir?: string
  ): TSDocConfigFile;
}

// Cache configuration interface
interface ICachedConfig {
  loadTimeMs: number;
  lastCheckTimeMs: number;
  configFile: TSDocConfigFile;
}