Add plugin tree type parameter

[wooorm]

Initial checklist

• [x] I read the support docs
• [x] I read the contributing guide
• [x] I agree to follow the code of conduct
• [x] I searched issues and couldn’t find anything (or linked relevant results below)
• [x] If applicable, I’ve added docs and tests

Description of changes

This allows plugins to define what type of tree they receive and yield in their transformer. It does not prevent misuse of those plugins (such as a rehype plugin and then a remark plugin). Nor does it handle parser or compiler plugins.

[wooorm]

/cc @remcohaszing

[wooorm]

It allows Plugins to set a generic for their input and output, but this doesn't appear to be checked by unified to ensure the unified.use chain is valid?

Correct.

Is this intended? (from your description it appear so?) If so, could you expand a bit on the value of adding the generics if they are not checked by unified.use?

So that plugins can start defining what input/output they receive/yield. unified otherwise gives/accepts Node, which due to:

• index signature removal
• improved mdast/hast (with their registries)
• hast / mdast utilities now accepting hast / mdast nodes rather than Node
• unist-util-visit-* now searching the tree for nodes rather than assuming that they contain a <Heading> …Node becomes annoying and too abstract.

---

A future idea I have:

• A ParserPlugin<OutputTree> / CompilerPlugin<InputTree>:
• Which could perhaps be inferred from Plugin<[], void, OutputTree> or Plugin<[], InputTree, void> respectively
• or even Plugin<[], string|Buffer, OutputTree> or Plugin<[], InputTree, string|Buffer|unknown> …which when .used stores those values on the Processor<Input, ParseTree, StringifyTree, Output>, and affects the input/output of .parse, .run, .stringify, and .process?

Perhaps this could be includes in this PR.

---

The last step is checking whether the .use chains are correct. But because processors are mutable, that’s quite hard:

const processor = unified()
processor.use(compilerPlugin)
processor.use(parserPlugin)
processor.use(transformPlugin)

Though, most people will probably chain?

[ChristianMurphy]

unist-util-visit-* now searching the tree for nodes rather than assuming that they contain a <Heading>

Follow up question on this added at https://github.com/syntax-tree/unist-util-visit-parents/pull/10#issuecomment-888310388

hast / mdast utilities now accepting hast / mdast nodes rather than Node

A fair point. I agree this is a challenge, the alternative, adding is or assert type assertions to every plugin doesn't seem performant or useful. There is a notable difference between utils and plugins though. utils are generally directly passed a tree, TypeScript can directly check the types match. plugins are generally called though unified, the tree being indirectly passed, without adding something to unified to try to match up the chained inputs and outputs, we would miss otherwise detectable errors.

which when .used stores those values on the Processor<Input, ParseTree, StringifyTree, Output>, and affects the input/output of .parse, .run, .stringify, and .process?

That's what I was thinking as well

const processor = unified()
processor.use(compilerPlugin)
processor.use(parserPlugin)
processor.use(transformPlugin)

Each of these .use() mutate the processor? (I didn't know that was supported) I'd be fine not supporting changing between node types when using this particular syntax. I do think it would still be possible to support a single tree/node type with it.

[wooorm]

Working on it!

[codecov-commenter]

Codecov Report

Merging #156 (e333401) into main (cf8653b) will not change coverage. The diff coverage is n/a.

@@            Coverage Diff            @@
##              main      #156   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            2         2           
  Lines          600       600           
=========================================
  Hits           600       600           

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update cf8653b...e333401. Read the comment docs.

[wooorm]

I’ve implemented parsers, compilers, etc for plugins. Now they:

• define the result of .parse, .stringify, .process, .run
• define the input of .run
• their output defines the input of the next plugin

I have not implemented errors of some sort when misconfiguring plugins. Given that:

• It is fine to only define transform plugins on a processor because .run is used and not .parse/.stringify
• several parser plugins / several compiler plugins could be used, overwriting what came before
• code is already used a lot in the wild
• the complexity of it all

I’m quite okay with not throwing on .use(rehypeWhatever).use(remarkWhatever)

[wooorm]

We can assert that it should match the Input of the next Plugin?

We could, but existing plugins can be untyped, not typed with input/output, or implicit. I think it’ll cause way to many errors. I’ll check again but what I tried yesterday resulted in 100s of errors in this code base

It is, but these errors would be things which never worked

Wrong code never worked (rehype plugin before remark plugin without rehype-remark), but I’m not worried about that. I’m worried about this breaking all the existing plugins.

[wooorm]

Made the types smarter. I don’t see how to allow untyped/implicit plugins while also emitting errors when they are chained incorrectly. I’m not sure how to infer these things from Pluggable / PluggableList / Preset though

[github-actions[bot]]

Hi! This was closed. Team: If this was merged, please describe when this is likely to be released. Otherwise, please add one of the no/* labels.