JavaScript Parser

/**
 * Create a new parser instance of the specified type
 * @param type - Parser type (default: 'js')
 * @returns Parser instance
 */
function createParser(type?: string): Parser;

/**
 * Available parser types
 */
const PARSERS: {
  js: string;
};

class Parser {
  /**
   * Create a new Parser instance
   * @param builderInstance - AST builder (optional)
   * @param visitorInstance - AST visitor (optional) 
   * @param walkerInstance - AST walker (optional)
   */
  constructor(builderInstance?, visitorInstance?, walkerInstance?);

  /**
   * Parse source files and extract JSDoc comments
   * @param sourceFiles - Array of file paths or single file path
   * @param encoding - File encoding (default: 'utf8')
   * @returns Array of generated doclets
   */
  parse(sourceFiles: string | string[], encoding?: string): Doclet[];

  /**
   * Add a doclet to the results buffer
   * @param doclet - Doclet to add to results
   */
  addResult(doclet: Doclet): void;

  /**
   * Get current parsing results
   * @returns Array of doclets
   */
  results(): Doclet[];

  /**
   * Clear parser state and results
   */
  clear(): void;

  /**
   * Fire processing complete event
   * @param doclets - Final doclet array
   */
  fireProcessingComplete(doclets: Doclet[]): void;
}

/**
 * Add custom AST node visitor
 * @param visitor - Visitor function for AST nodes
 */
addAstNodeVisitor(visitor: Function): void;

/**
 * Get all registered AST node visitors
 * @returns Array of visitor functions
 */
getAstNodeVisitors(): Function[];

/**
 * Resolve what a node is a member of
 * @param node - AST node
 * @returns Object with memberof and basename information
 */
astnodeToMemberof(node: ASTNode): {
  memberof?: string;
  basename?: string;
};

/**
 * Resolve what "this" refers to for a given node
 * @param node - AST node containing "this" reference
 * @returns Longname of the enclosing context
 */
resolveThis(node: ASTNode): string;

/**
 * Resolve parent objects for a property node
 * @param node - Property AST node
 * @returns Array of parent doclets
 */
resolvePropertyParents(node: { parent: ASTNode }): Doclet[];

/**
 * Resolve variable scope for a node
 * @param node - AST node
 * @param basename - Variable basename
 * @returns Scope longname
 */
resolveVar(node: { enclosingScope?: ASTNode; type: string }, basename: string): string;

/**
 * Resolve enum properties
 * @param e - Event object with doclet and code information
 */
resolveEnum(e: { doclet: Doclet; code: { node: ASTNode } }): void;

/**
 * Add doclet reference for node lookup
 * @param e - Event object with doclet and code information
 */
addDocletRef(e: {
  doclet?: Doclet;
  code?: { node: ASTNode };
}): void;

// Event interfaces
interface ParseBeginEvent {
  sourcefiles: string[];
}

interface FileBeginEvent {
  filename: string;
}

interface JSDocCommentFoundEvent {
  comment: string;
  lineno: number;
  columnno: number;
  filename: string;
}

interface SymbolFoundEvent {
  // Symbol information
}

interface NewDocletEvent {
  doclet: Doclet;
}

interface FileCompleteEvent {
  filename: string;
  source?: string;
}

interface ParseCompleteEvent {
  sourcefiles: string[];
  doclets: Doclet[];
}

interface ProcessingCompleteEvent {
  doclets: Doclet[];
}

// Adding event handlers
parser.on('parseBegin', (e) => {
  console.log('Starting to parse:', e.sourcefiles);
});

parser.on('jsdocCommentFound', (e) => {
  console.log(`Found comment at ${e.filename}:${e.lineno}`);
});

parser.on('newDoclet', (e) => {
  console.log('Generated doclet:', e.doclet.longname);
});

interface Doclet {
  // Core properties
  kind: string;           // 'function', 'class', 'member', etc.
  name: string;           // Symbol name
  longname: string;       // Full qualified name
  description?: string;   // Description text
  
  // Hierarchy
  memberof?: string;      // Parent symbol longname
  scope?: string;         // 'static', 'instance', 'inner', 'global'
  
  // Metadata
  meta: {
    path: string;         // File path
    filename: string;     // File name
    lineno: number;       // Line number
    code: {
      name?: string;      // Code symbol name
      type: string;       // AST node type
      value?: any;        // Symbol value
      paramnames?: string[]; // Parameter names
    };
  };
  
  // Function-specific
  params?: Parameter[];   // Function parameters
  returns?: Return[];     // Return information
  
  // Class-specific
  classdesc?: string;     // Class description
  
  // Type information
  type?: {
    names: string[];      // Type names
  };
  
  // Documentation flags
  undocumented?: boolean; // No JSDoc comment
  ignore?: boolean;       // Should be ignored
  inherited?: boolean;    // Inherited member
  virtual?: boolean;      // Virtual/abstract member
}

interface Parameter {
  name: string;
  type?: { names: string[] };
  description?: string;
  optional?: boolean;
  defaultvalue?: any;
}

interface Return {
  type?: { names: string[] };
  description?: string;
}

const parser = require('jsdoc/src/parser');
const env = require('jsdoc/env');

// Set up environment
env.opts = { encoding: 'utf8' };
env.conf = {
  source: {
    includePattern: '\\.js$',
    excludePattern: 'node_modules/'
  }
};

// Create and use parser
const jsdocParser = parser.createParser();
const doclets = jsdocParser.parse(['src/myfile.js']);

console.log(`Generated ${doclets.length} doclets`);
doclets.forEach(doclet => {
  console.log(`${doclet.kind}: ${doclet.longname}`);
});

const parser = require('jsdoc/src/parser');
const env = require('jsdoc/env');

// Configure environment
env.conf = {
  source: { includePattern: '\\.js$' },
  plugins: ['plugins/markdown']
};

// Create parser with event handlers
const jsdocParser = parser.createParser();

jsdocParser.on('parseBegin', (e) => {
  console.log('Starting parse of:', e.sourcefiles);
});

jsdocParser.on('newDoclet', (e) => {
  if (!e.doclet.undocumented) {
    console.log(`Documented: ${e.doclet.longname}`);
  }
});

jsdocParser.on('parseComplete', (e) => {
  console.log(`Parse complete: ${e.doclets.length} doclets generated`);
});

// Parse files
const doclets = jsdocParser.parse(['src/**/*.js']);

const parser = require('jsdoc/src/parser');

// Create parser
const jsdocParser = parser.createParser();

// Add custom visitor for specific node types
jsdocParser.addAstNodeVisitor(function(node, e, parser, currentSourceName) {
  if (node.type === 'FunctionExpression' && node.id && node.id.name) {
    console.log(`Found function expression: ${node.id.name}`);
  }
});

// Parse with custom visitor
const doclets = jsdocParser.parse(['myfile.js']);

// Filter doclets by type
const functions = doclets.filter(d => d.kind === 'function');
const classes = doclets.filter(d => d.kind === 'class');

// Find specific doclet by longname
const mainClass = doclets.find(d => d.longname === 'MyClass');

// Get all members of a class
const members = doclets.filter(d => d.memberof === 'MyClass');

// Get undocumented symbols
const undocumented = doclets.filter(d => d.undocumented);

// Parser automatically loads plugins
env.conf.plugins = ['plugins/markdown', 'plugins/overloadHelper'];

const jsdocParser = parser.createParser();
// Plugins are now active during parsing

// Doclets are passed to template publish function
function publish(data, opts) {
  // data is a TaffyDB collection of doclets
  const allDoclets = data().get();
  
  allDoclets.forEach(doclet => {
    if (doclet.kind === 'function') {
      generateFunctionDoc(doclet);
    }
  });
}

try {
  const doclets = jsdocParser.parse(['problematic-file.js']);
} catch (error) {
  if (error.message.includes('Unexpected token')) {
    console.error('Syntax error in source file');
  } else {
    console.error('Parser error:', error.message);
  }
}

// Use pedantic mode to treat warnings as errors
env.opts.pedantic = true;