fix: make gitlabPlugin conform to Docusaurus PluginModule

[ebuildy]

Problem

The default export is not assignable to Docusaurus's PluginModule, and its return value is not a valid Plugin. As a result the registration form documented in README.md and used by examples/gitlab — the function form, which is what Docusaurus actually type-checks against PluginConfig — fails to compile in any TypeScript Docusaurus site:

error TS2322: Type '[(context: unknown, options: PluginOptions) => Promise<{...}>, {...}]'
  is not assignable to type 'PluginConfig'.

Two causes

1. mergeStrategy widened to string. mergeStrategy: { "module.rules": "append" } inferred the literal as string, which is not a webpack-merge CustomizeRuleString, so the configureWebpack result violated ConfigureWebpackResult. The runtime value was always correct — only the type was wrong. It went unnoticed because the factory has no return-type annotation, so its shape was inferred and never compared against Plugin. Docusaurus's own plugins annotate Promise<Plugin<Content>> explicitly and would have caught this.

2. options: PluginOptions fails contravariantly against PluginModule's options: unknown. Worth noting this one is not specific to this package — I checked @docusaurus/plugin-sitemap, declared (context: LoadContext, options: PluginOptions), and it fails identically. Widening both parameters holds a stricter line than first-party so the documented form type-checks.

context: unknown was already fine — unknown is a supertype of LoadContext, so it passes contravariantly. The hand-rolled CliLike shim is also structurally compatible with Commander's CommanderStatic.

Why nothing caught it

@docusaurus/types was not a dependency at any level — not dep, devDep, or peer — and it is not even resolvable from examples/gitlab under pnpm. Neither example site had a tsconfig.json, so the const config: Config annotation in docusaurus.config.ts was never checked. pnpm run typecheck structurally could not see the plugin contract.

The fix

Two lines in src/plugin/index.ts, each commented as load-bearing, plus two guards:

• src/plugin/types.test.ts — asserts assignability to PluginModule, Plugin, and PluginConfig. tsconfig.build.json excludes *.test.ts, so the @docusaurus/types import never reaches dist/. This matters: a .d.ts importing it would fail to resolve for pnpm consumers, who do not get the package hoisted — examples/gitlab has to declare it explicitly, which is the proof.
• examples/gitlab/tsconfig.json + a typecheck script — the consumer-side guard, checking the real registration against the real Config type. Scoped to docusaurus.config.ts and sidebars.ts: src/theme/* swizzles import @theme-original/*, a webpack alias that only resolves against a generated .docusaurus/ dir, so including it would demand a full site build just to type-check.

Verification

Both guards were written first and confirmed failing, then passing. I also verified they actually bite rather than passing vacuously — reverting only the as const and rebuilding fails both, the example one pointing straight at the documented line:

docusaurus.config.ts(35,14): error TS2322: Type '(context: unknown, rawOptions: unknown) => ...'
  is not assignable to type 'PluginModule<unknown> | DeepPartial<PluginOptions>'.

With the fix in place:

• typecheck clean (root and examples/gitlab)
• 678 tests across 59 files pass, including the e2e Docusaurus build in both v3 and future.v4 variants
• lint 0 errors, markdownlint 0 issues
• grep -rn "@docusaurus/types" dist/ returns nothing — no devDependency leak into the published package

Note for reviewers

This changes the exported signature to (context: unknown, options: unknown). It is source-compatible for every documented usage — the string form, the function form, and direct calls are all unaffected (widening a parameter is assignment-safe), and the narrowing back to PluginOptions happens on the first line where resolveOptions validates with Joi regardless.

An earlier version of this note claimed callers lose option checking on the second argument. That was wrong — they never had it. Docusaurus's tuple slot is its own PluginOptions = {id?: string} & {[key: string]: unknown}, an index signature that accepts anything, so [[gitlabPlugin, { strcit: true }]] compiled clean before this PR too. An overload preserving the narrow signature was tested and rejected: a typo'd literal silently falls through to the wide overload. What does give consumers real checking is satisfies PluginOptions on the options object in the README snippet and examples/gitlab — worth a follow-up.

Review round

Reviewed from three angles (impact, security, code style). Fixes applied in 3664021:

• The runtime it() could not catch its own bug. Types are erased, so removing as const left it passing, and it duplicated index.test.ts:69. Replaced the whole file with two satisfies lines — the idiom this repo already uses 8× in gitlab/fetchers.ts. Verified both regressions are still caught independently.
• The test polluted the repo working tree, creating static/gitlab-assets/ in the root on every pnpm test (no assetDir, so the eager assets.sync() used the relative default). Confirmed by bisection. Dropping the runtime half removed the cause rather than patching it.
• The consumer-side guard ran nowhere — ci.yml only ran the root typecheck, whose tsconfig covers just src and test, and mise.toml had no task. Now wired into both; the CI step sits in the test job, which already builds dist/.
• rawOptions renamed back to options; the parameter name is public API surface visible in dist/plugin/index.d.ts.
• Documented that ?? {} is load-bearing (it converts a raw TypeError on opts.host into the branded validation error).

Out of scope, raised separately: the security review surfaced a pre-existing HIGH finding unrelated to this PR — plugin options are serialized verbatim into the client bundle via Docusaurus's siteConfig, so a configured token ships to the browser. Independently reproduced. Not addressed here.