{"id":13397,"library":"jsdoc3-parser","title":"JSDoc3 AST Parser Wrapper","description":"jsdoc3-parser is a utility designed to extract the Abstract Syntax Tree (AST) from JavaScript files by leveraging JSDoc's internal parser. It operates by invoking the JSDoc CLI with the `-X` option, which outputs the parsed documentation as JSON, and then processes this output. As of its last major release, version 3.0.0, published approximately three years ago, this package offered a workaround for the absence of a direct programmatic API for JSDoc's parser. However, the official JSDoc project now provides `@jsdoc/parse` which offers a direct, programmatic approach. Consequently, `jsdoc3-parser` has seen no recent updates and its core method of operation is now largely superseded, making its release cadence effectively ceased. Its key differentiator was its ability to provide JSDoc's parsed output programmatically at a time when no official library existed for this purpose.","status":"abandoned","version":"3.0.0","language":"javascript","source_language":"en","source_url":"git://github.com/mrjoelkemp/jsdoc3-parser","tags":["javascript","jsdoc","parser","ast"],"install":[{"cmd":"npm install jsdoc3-parser","lang":"bash","label":"npm"},{"cmd":"yarn add jsdoc3-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add jsdoc3-parser","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"This package is a wrapper around the JSDoc command-line interface, specifically using its `-X` option to get AST output. JSDoc must be installed and accessible in the system's PATH, though it is not a direct npm dependency of `jsdoc3-parser`.","package":"jsdoc","optional":false}],"imports":[{"note":"The package was last updated in 2023 and primarily supports CommonJS `require()` syntax. There is no indication of official ESM support.","wrong":"import parser from 'jsdoc3-parser';","symbol":"parser","correct":"const parser = require('jsdoc3-parser');"}],"quickstart":{"code":"const parser = require('jsdoc3-parser');\nconst path = require('path');\nconst fs = require('fs');\n\nconst tempJsFile = path.join(__dirname, 'tempFileForParsing.js');\nconst jsContent = `\n/**\n * Represents a point in 2D space.\n * @class\n * @param {number} x - The x-coordinate.\n * @param {number} y - The y-coordinate.\n */\nfunction Point(x, y) {\n  /**\n   * The x-coordinate.\n   * @type {number}\n   */\n  this.x = x;\n  /**\n   * The y-coordinate.\n   * @type {number}\n   */\n  this.y = y;\n}\n\n/**\n * Calculates the distance from this point to another point.\n * @param {Point} otherPoint - The other point.\n * @returns {number} The distance between the two points.\n */\nPoint.prototype.distance = function(otherPoint) {\n  const dx = this.x - otherPoint.x;\n  const dy = this.y - otherPoint.y;\n  return Math.sqrt(dx * dx + dy * dy);\n};\n`;\n\nfs.writeFileSync(tempJsFile, jsContent);\n\nparser(tempJsFile, function(error, ast) {\n  if (error) {\n    console.error('Error parsing file:', error);\n    return;\n  }\n  console.log('Successfully parsed JSDoc AST for:', tempJsFile);\n  // The AST is an array of JSDoc doclets\n  console.log(JSON.stringify(ast[0], null, 2));\n  console.log(JSON.stringify(ast[1], null, 2));\n  console.log(JSON.stringify(ast[2], null, 2));\n  fs.unlinkSync(tempJsFile); // Clean up temp file\n});","lang":"javascript","description":"This example demonstrates how to parse a JavaScript file containing JSDoc comments to retrieve its AST (doclets) using `jsdoc3-parser`. It writes a temporary file, parses it, and then logs parts of the resulting JSDoc AST."},"warnings":[{"fix":"Migrate to `@jsdoc/parse` for official and stable programmatic JSDoc parsing, or carefully pin JSDoc CLI version.","message":"This package relies on the internal `-X` option of the JSDoc CLI. Future versions of JSDoc may change the format of this output or remove the option entirely, which would break `jsdoc3-parser` functionality without a corresponding update.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure JSDoc is installed and globally accessible (e.g., `npm install -g jsdoc`) or configured in your environment's PATH.","message":"The package requires the JSDoc CLI tool to be installed globally or available in the system's PATH. It does not manage the JSDoc dependency itself, leading to potential 'command not found' errors if JSDoc is not set up correctly.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Transition to using `@jsdoc/parse` for modern, stable, and direct programmatic JSDoc parsing. Consider alternatives like `jsdoc-parse` or `jsdoctypeparser` for specific AST needs.","message":"The fundamental premise of this package—providing programmatic access to JSDoc's parser via CLI scraping—is now deprecated. The official JSDoc project offers `@jsdoc/parse` as a direct, npm-installable library for parsing JSDoc comments programmatically.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"For projects using modern JavaScript, consider `@jsdoc/parse` or other actively maintained AST parsers that are kept up-to-date with ECMAScript specifications.","message":"This package, last updated three years ago, is unlikely to fully support modern JavaScript syntax (ESM, newer language features) in its parsing capabilities without updates to the underlying JSDoc CLI version it was designed to interact with.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Install JSDoc globally: `npm install -g jsdoc`, or ensure its executable path is correctly configured in your environment.","cause":"The JSDoc command-line tool is not found in the system's PATH or is not installed.","error":"Error: Command failed: jsdoc -X"},{"fix":"Ensure you are using CommonJS `const parser = require('jsdoc3-parser');` and calling `parser(filePath, callback)` as shown in the quickstart.","cause":"Attempting to use `jsdoc3-parser` with ESM `import` syntax or incorrect CommonJS usage, when the package is designed for CommonJS `require()` and exports a function directly.","error":"TypeError: parser is not a function"},{"fix":"Pin your JSDoc CLI version to the one compatible with `jsdoc3-parser` (likely an older JSDoc 3.x version from ~2023), or migrate to `@jsdoc/parse` for more robust parsing.","cause":"An updated version of the JSDoc CLI has altered the structure of its `-X` command's JSON output, which `jsdoc3-parser` expects in a specific format.","error":"JSDoc -X output format changed, cannot parse"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}