How to depend on external package without error from its links

[cefn]

A module we are publishing in our enterprise has a dependency on the package https://watchable.dev/api/modules/_watchable_store.html

We export types from the upstream package, since they are used in return types of our functions.

export type { Immutable, RootState, Selector, Store } from "@watchable/store";

Attempting to create documentation for our module we get errors like this coming from markdown defined outside our project...

[warning] Failed to resolve link to "createStore" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "@watchable/store!Store.write" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "Watcher | Watchers" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "@watchable/store!Watchable.watch" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "@watchable/store!Store#write" in comment for @my-scope/microfrontend-store-registry.Immutable
[warning] Failed to resolve link to "@watchable/store!Store#read" in comment for @my-scope/microfrontend-store-registry.Immutable

All these errors seem to come from the tsdoc markdown resolved from inside the upstream package. For example the first error seems to match to https://github.com/cefn/watchable/blob/bb7131e23af46b1ab712ace723937d42d6fafec1/packages/store/src/types/store.ts#L6

Our module looks after calling createStore on behalf of users so deliberately doesn't re-export that function. We tried providing a definition in the typedoc.mjs like this, doesn't suppress the error either...

/** @type {Partial<import("typedoc").TypeDocOptions>} */
const config = {
  excludeReferences: true,
  externalSymbolLinkMappings: {
    "@watchable/store": {
      createStore:
        "https://watchable.dev/api/functions/_watchable_store.createStore.html",
    },
  },
};

export default config;

The other links we could also try to resolve to upstream documentation at watchable.dev if we knew a way to match the failed symbols linked.

However the more immediate issue is that documentation warnings are deliberately configured to block the pipeline, to force 100% documentation coverage so this means we can't get pipelines to pass at all currently, and we can't establish how to selectively 'allowlist' these failures.

Questions

Initially what configuration can we use to selectively allowlist only these link failures?
As a followup is there a way to make these links correctly point to upstream documentation?

[Gerrit0]

Dealing with links is unfortunately probably the worst part about typedoc... though it's probably a problem for any tool which can process somewhat arbitrary links that might not make any sense...

The createStore and Watcher links are unfortunately defined by @watchable/store in such a way that they are local links, but without any variables in scope which TypeScript can use to decide what symbol they refer to, so all TypeDoc has to go on is the link text. When generating docs for @watcher/store, this will end up happening to work due to how TypeDoc attempts to resolve links, but wont for your case since you don't export createStore from the same package.

Broken local links can't be specified by the externalSymbolLinkMappings option (perhaps this is something that should change... it'd probably have to be another special key like global is today)

The resolution you want for these links can be specified with a custom plugin, with the following config and the export you provided I get no warnings:

// @ts-check
/** @import * as td from "typedoc"; */

/** @type {Record<string, string | undefined>} */
const brokenLocalLinkResolutions = {
    createStore: "#",
    Watcher: "#"
};

/** @param {td.Application} app */
function resolveLinksPlugin(app) {
    app.converter.addUnknownSymbolResolver((ref, refl, part, symbol) => {
        // If TS resolved this link, don't touch it here, let typedoc still report warnings
        if (symbol) return undefined;

        if (!ref.moduleSource && ref.symbolReference?.path?.length === 1) {
            return brokenLocalLinkResolutions[ref.symbolReference.path[0].path];
        }

        return undefined;
    })
}

/** @type {td.TypeDocOptions} */
const config = {
    plugin: [resolveLinksPlugin],
    externalSymbolLinkMappings: {
        "@watchable/store": {
            "Store.write": "#",
            "Store.read": "#",
            "Watchable.watch": "#",
        }
    },
};

export default config;

[cefn]

That is so cool! I had confidence reaching out to the Typedoc community having seen your incredibly helpful and practical responses in the past. The solution of writing a custom plugin is powerful and solved many of the problem links.

However, a couple of puzzles remain. Without your intervention our list of link failures looked like this...

[warning] Failed to resolve link to "createStore" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "@watchable/store!Store.write" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "Watcher | Watchers" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "@watchable/store!Watchable.watch" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "@watchable/store!Store#write" in comment for @my-scope/microfrontend-store-registry.Immutable
[warning] Failed to resolve link to "@watchable/store!Store#read" in comment for @my-scope/microfrontend-store-registry.Immutable

...and after the intervention of the custom plugin we have these remaining failures, which are the ones without a @watchable/store! prefix ...

[warning] Failed to resolve link to "createStore" in comment for @my-scope/microfrontend-store-registry.Store
[warning] Failed to resolve link to "Watcher | Watchers" in comment for @my-scope/microfrontend-store-registry.Store

This happens in the context of 'Merging converted projects' and even with --logLevel Verbose the error doesn't indicate what resolution path the failing link is coming through. Maybe therefore the matching scopes that you've helpfully resolved to '#' haven't matched those particular cases, or maybe there's no matching mechanism that can catch them at all?

These failures are hard to trace as I'm unsure what the 'namespaces' and strings/ids are that this layer is processing, or indeed where the (local/remote) source files are that are bringing these into scope.

One of them is distinctive (the disjunction syntax) and could therefore come via some import path from one of these remote locations ...

• https://github.com/cefn/watchable/blob/bb7131e23af46b1ab712ace723937d42d6fafec1/packages/store/src/lib/store.ts#L34
• https://github.com/cefn/watchable/blob/bb7131e23af46b1ab712ace723937d42d6fafec1/packages/store/src/types/store.ts#L15
• https://github.com/cefn/watchable/blob/bb7131e23af46b1ab712ace723937d42d6fafec1/packages/store/src/lib/partition.ts#L54

If tracking the resolution path down to actually fix these is hard, is there any way to ask typedoc not to attempt it at all? E.g. can we terminate the process at root by saying e.g. Store should just take you to an external link, and not bother to drill down and process the remote module's markdown and links at all?

Based on your comment I found a workaround for passing the build, though. If we DO export both createStore and Watcher then the typedoc build completes without validation errors. Exporting Watcher is probably a good idea and not a compatibility issue.

However, exporting createStore would ideally not happen, since that's what this module is looking after (committing to a particular centrally-managed store lifecycle, and not inviting people to create their own). It also ends up being the only 'runtime' export (all other exports are just types which is preferred to isolate from the remote package)

Requesting upstream fix

To fix this upstream in watchable, should each link destination like Watcher actually be @watchable/store!Watcher ?

Looking at https://watchable.dev/api/interfaces/_watchable_store.Store.html though, the cases with the ! prefix makes documentation text quite unreadable.

Unrelated config typing issue

Unrelated to the failure, and not preventing the workaround from being effective, I have the below type error against the custom plugin signature.

The type td.TypeDocOptions['plugin'] is only allowed to be a string according to the types I am resolving locally, which seem to be coming via definitions at node_modules/.pnpm/typedoc@0.28.16_typescript@5.9.3 which looks to be latest. Do these config types need updating?

Type '(app: Application) => void' is not assignable to type 'string'.

[Gerrit0]

after the intervention of the custom plugin we have these remaining failures

I cannot reproduce this, the custom plugin should resolve those, and does in the test project I made which references the same classes.

These failures are hard to trace as I'm unsure what the 'namespaces' and strings/ids are that this layer is processing, or indeed where the (local/remote) source files are that are bringing these into scope.

The second part of the warning tells you this: "in comment for @my-scope/microfrontend-store-registry.Store"

That indicates the warning is coming from the Store class within your @my-scope/microfrontend-store-registry module, which you've indicated comes from https://github.com/cefn/watchable/blob/bb7131e23af46b1ab712ace723937d42d6fafec1/packages/store/src/types/store.ts#L3, so that's the comment in question here.

I realized today that the declaration references page didn't really describe how TypeDoc resolved links, so have attempted to resolve that with a resolution strategy section, that will hopefully clarify things.

To fix this upstream in watchable, should each link destination like Watcher actually be @watchable/store!Watcher?

That would work. If the declaration file imported Watcher, then {@link Watcher} would have a symbol reference and TypeScript would resolve it so externalSymbolLinkMappings would work as expected, but as it doesn't TypeDoc is unfortunately stuck with just the text.

Looking at https://watchable.dev/api/interfaces/_watchable_store.Store.html though, the cases with the ! prefix makes documentation text quite unreadable.

I agree, the preserveLinkText option is on by default, but unfortunately gets rather noisy with full links like this. I'm somewhat regretting defaulting it to on...

Thankfully, the @link tag supports specifying text for a link after a bar, so @watchable/store!Watcher | Watcher would also work to just display the class name.

Unrelated to the failure, and not preventing the workaround from being effective, I have the below type error against the custom plugin signature.

I noticed this was wrong when setting up the example as well, have fixed in 0736af4, which isn't released yet