feat: pipelining and builders

[yankeeinlondon]

First of all let me start by appologizing for how large this PR is. Secondly, let me say that this PR intends to change absolutely nothing about the default functionality. The main goal was to find a clear means to tap into event hooks throughout the build pipeline. At a high level this can be viewed from the following change areas:

1. Explicit Pipeline
   As I was looking through the code and determining the various steps in the transformation pipeline I started adding more types and comments to those types. It was helpful for me to write it down and my hope is that it would be helpful to others too. Finally, as this is really a pipeline process I brought in a functional style to the newly minted composeSfcBlocks.ts
   file which serves as an overview of the whole process.

    // run the pipeline
    const result = pipe(
      payload,
   
      transformsBefore,
      callEventHooks(PipelineStage.initialize),
   
      extractFrontmatter,
      frontmatterPreprocess,
      callEventHooks(PipelineStage.metaExtracted),
   
      createParser,
      loadMarkdownItPlugins,
      applyMarkdownItOptions,
      callEventHooks(PipelineStage.parser),
   
      parseHtml,
      wrapHtml,
      escapeCodeTagInterpolation,
      callEventHooks(PipelineStage.parsed),
   
      extractBlocks,
      callEventHooks(PipelineStage.sfcBlocksExtracted),
   
      finalize,
      transformsAfter,
      callEventHooks(PipelineStage.closeout),
    )

   Note: the pipeline is strongly typed, only allowing the proscribed evolution of the pipeline's "payload" to move from caller to receiver

2. Builders
   I then wanted to create a way for people to add hooks into the various stages of the lifecycle through a controlled manner and came up with the "builders" name. Originally I had intended all of them to strictly follow the traditional builder interface pattern but decided that was too much type burden to place on others so am using a similar options hash for configuration of these builders.

   Both to illustrate the power of builders and to give some "out of the box" punch to them I have included two builders as part of this PR:

   • link() - see the docs at ./docs/LinkBuilder.md ... short version ... adds contextual classes to links and switches to vue-router for internal links
   • meta() - provides a set of rules to map HEAD, META, and ROUTER metadata that goes further than the default implementation

3. Tests

   • I have greatly expanded the number of tests (both traditional units and some more snapshots)

   • I did want to do some Component Tests but I was having trouble getting started ...

     

   • I will come back to this after I'm back from vacation and fill in any other tests you feel aren't covered in great enough detail

I had intended to add one or two more builders but realized this PR was getting too large and I'm flying out to Idaho for some skiing on Tuesday so I'll be MIA for a week but I can respond to anything before that or on my return.

The nice thing about the pipeline/builders pairing is that I think it makes the pipeline very explicit in a helpful way, provides more opportunities to hook into whatever stage you want, and there is zero code cost to a builder you don't use as they're 99% a build concern but also that any client will easily shake away any residual JS (not sure there's any atm) due to them being isolated static deps.

[yankeeinlondon]

• this is what is failing in the 14.x builds ... it's a language feature that should not effect 14.x clients of the library because they will be using the transpiled version of this library which will have removed .replaceAll() but because the tests test on the TS directly, it would appear that the TS's target of es2017 is not being respected.
• I could re-implement this without the use of this function but it does make things nice and compact for reading and future use and only effects tests like this :(

[yankeeinlondon]

ok kept the new 14.x solution compact:

for (const [before, after] of replacements)
  updated = updated.replace(new RegExp(before, 'g'), after)

[antfu]

Thanks for the effort and from a rough look it LGTM! If you are sure it won't break the existing usage I'd say let's go for it.

If you'd like, after this PR has been merged I am happy to invite you as a maintainer of this project! Again, thanks a lot for the hard work!

[yankeeinlondon]

One thing I think I've seen in some of your repos -- not sure though -- is the use of changesets which helps in creating a changelog. Would you be ok if I added that?

think it's quite popular in the pnpm crowd

[yankeeinlondon]

WRT to being a maintainer ... I'd be honored. Hope that that means that I can share the responsibility for this rather than fully own it as I tend to be pretty scattered all over the place and am a classic ADHD sufferer but I would like to help out if I can and I guess at this point I do know the code very well :)

[antfu]

I have never used changesets but https://github.com/antfu/bumpp and https://www.npmjs.com/package/conventional-changelog-cli. Which is already configured for this repo

vite-plugin-md/.github/workflows/release.yml

Lines 25 to 27 in 7e760a8

	- run: npx conventional-github-releaser -p angular
	env:
	CONVENTIONAL_GITHUB_RELEASER_TOKEN: ${{secrets.GITHUB_TOKEN}}

Maintainer

No worries, I will still be here. Basically it's just that you will have permission to push and release, but not necessarily have to do anything.