can't use any other pipeline proposal syntax than "minimal"

[nnmrts]

• What version of documentation.js are you using?: 13.0.1
• How are you running documentation.js (on the CLI, Node.js API, Grunt, other?): CLI

When I use syntax that requires the "fsharp" or "smart" pipeline proposal, documentation throws with a babel parser error

Primary Topic Reference found but pipelineOperator
not passed 'smart' for 'proposal' option.

even though I did exactly that. The issue is that src/parsers/parse_to_ast.js overwrites my babel config with ['pipelineOperator', { proposal: 'minimal' }].

---

command:

documentation build src -f html -o docs --babel=babel.config.json

babel config:

{
	"presets": [
		[
			"@babel/preset-env",
			{
				"targets": {
					"node": "14"
				}
			}
		]
	],
	"plugins": [
		[
			"@babel/plugin-proposal-pipeline-operator",
			{
				"proposal": "smart"
			}
		]
	],
}

[tmcw]

This is a pretty tough area for documentation.js: pipelines don't especially affect the AST in a way that would break its inference, but other parser options would, hence the fixed maximal set of parser options. Maybe it should pass through just this option? I'm not sure - if you have a preferred plan of attack, I'd be happy to hear it.

[nnmrts]

Well, my personal plan of attack was to just switch to "minimal" because it's not that big of a difference.

But, yeah, I discovered that src/parsers/parse_to_ast.js file by accident, because I originally thought my local babel config is somehow not found or something. I thought it's just using the STANDARD_BABEL_CONFIG of src/input/dependency.js, but no. For some parts it's using my babel config, but later it breaks because it uses the babel config from src/parsers/parse_to_ast.js.

So I would just make the whole "standardBabelParserPlugins" dynamic, to make the whole thing future-proof. What if for example @babel/plugin-proposal-optional-chaining suddenly allows a new flavour option?

So in my opinion, this https://github.com/documentationjs/documentation/blob/78c6a5a72882e3ad7766a72a78a113d5a2980d4a/src/parsers/parse_to_ast.js#L37-L47

should look like this

function getParserOpts(file) {
  return {
    allowImportExportEverywhere: true,
    sourceType: 'module',
    plugins: [
      ...standardBabelParserPlugins,
      ...MYBABELCONFIG.plugins,
      ['decorators', { decoratorsBeforeExport: false }],
      TYPESCRIPT_EXTS[path.extname(file || '')] ? 'typescript' : 'flow'
    ]
  };
}

[tmcw]

So I would just make the whole "standardBabelParserPlugins" dynamic, to make the whole thing future-proof. What if for example @babel/plugin-proposal-optional-chaining suddenly allows a new flavour option?

Yeah, the issue is here - documentation.js processes a particular syntax tree to extract meaning from it. Parser plugins output different kinds of syntax trees. If one is implemented that adds a new node type or new import/export structure or something else, then the new parser will just break documentation.js because it can't be written in a way that supports every possible AST. I guess we could be liberal and allow custom parsers and just tolerate breakage, but it would be trading a clearly-defined scope for a pretty vague one.

[nnmrts]

I see. While I personally think that a user is responsible for managing their plugins and working out if they are supported by documentation.js, just like in this case I'm responsible for using the "right" pipeline syntax, because it breaks when I use other syntaxes, I also understand your perspective on this.

So, the fast, "now"-solution would be indeed to pass through just this option, I guess. I'd still suggest looking into a more generic solution in the future, or, at least some sort of documentation about the specific default babel configs documentation.js, and where and when it uses them.

Getting this error when running documentation.js

Primary Topic Reference found but pipelineOperator not passed 'smart' for 'proposal' option.

with a trace just to the @babel/parser package, and even though I passed "smart" for the "proposal" option, is weird and confusing.

[nnmrts]

Closing this because I don't think it's really relevant anymore and because I was obviously the only person with this problem back then and today.