#92 · stacks/bunpress

Observed problem

When a Markdown link names a document that does not exist, the build fails with the link target but not the file containing it, and the message arrives underneath roughly 1,700 lines of minified bundle source. On a docs set of any size the only way to act on it is to grep the repository for the string.

This is not an argument against rejecting the link. #86 set out to "reject unsupported cases explicitly instead of silently corrupting them", which is right. It is about the rejection being actionable.

Reproduction

Three files, @stacksjs/bunpress@0.2.28, Bun 1.4.3:

docs/index.md   # Home
                A link to [the guide](./guide.md) that exists.

docs/guide.md   # Guide
                A link to [a page that is not there](./missing-one.md).

docs/other.md   # Other
                Another link to [a second missing page](./missing-two.md).

bunpress build prints two very long minified chunk excerpts, then:

error: Markdown link has no documentation source: ./missing-one.md
      at resolveLink (.../@stacksjs/bunpress/dist/chunk-778jqyb6.js:1741:4665)
      at element (.../dist/chunk-778jqyb6.js:1741:5348)
      at P1 (.../dist/chunk-778jqyb6.js:1741:5416)
      at HQ (.../dist/chunk-0vf1e5mr.js:9655:197)
      at async x0 (.../dist/chunk-0vf1e5mr.js:9653:784)

Nothing in that output says docs/guide.md.

Source evidence

The throw site already has the file. In dist/chunk-778jqyb6.js, resolveLink(G, z) reads G.sourceFile on the line above the throw, to resolve the destination:

resolveLink(G, z) {
  ...
  let L = decodeURIComponent(I), H = E(i0(G.sourceFile), L), R = z0($, H);
  if (R === ".." || R.startsWith(`..${j0}`) || q0(R)) return z;
  let D = W.get(H);
  if (!D) throw Error(`Markdown link has no documentation source: ${I}`);

So G.sourceFile is in scope and carries exactly the missing context. The stack frames that are printed instead point into minified bundle internals, which tell a user of the package nothing.

What would help

Name the containing document, and a line or the surrounding link text if that is reachable: docs/guide.md: Markdown link has no documentation source: ./missing-one.md.
Fail without the minified source excerpt. A thrown Error gets Bun's default treatment; a diagnostic the CLI prints and exits on would read as a documentation problem rather than a crash in bunpress.

Reporting the rest of the dead links in the same run is a separate and larger ask, so it is filed separately.