---
url: 'https://adk.nht.io/developer-tools/eslint-rules/media.md'
description: >-
  The adk-media plugin at @nhtio/adk/batteries/media/lint — four rules that
  guard engine composition: supply form, dispatch order, declaration-merging
  target, and optional peers.
---

# Media battery rules

## LLM summary — Media battery rules

* `import adkMedia from '@nhtio/adk/batteries/media/lint'`, namespace `adk-media`, four rules, `configs.recommended` enables them.
* `adk-media/prefer-engine-resolver` — a static value import of a bundled engine subpath; supply engines as dynamic-import resolvers instead. Type-only imports pass.
* `adk-media/no-shadowed-engine` — an engine whose statically-known capabilities are entirely covered by an EARLIER engine in the same `engines` array; dispatch is first-capable-wins, so it is dead code.
* `adk-media/augment-contracts-module` — a `ConvertOptions` declaration-merging block targeting any module other than `@nhtio/adk/batteries/media/contracts`; the merge silently never happens.
* `adk-media/require-engine-peers` — a reference to a bundled engine subpath whose optional peer dependency (`xlsx`, `jimp`, `exceljs`, `tesseract.js`, …) cannot be resolved from the linting file; the pipeline throws `E_INVALID_MEDIA_PIPELINE_CONFIG` at first use. `ignore` option per peer; soffice and fs\_workspace have no external peer.
* `no-shadowed-engine` reasons from a hand-maintained summary table, pinned to the live factories by `lint_drift.node.spec.ts`. Any rule that mirrors runtime facts by hand needs that pin.

The media pipeline is composed, not configured: you hand it an ordered array of
engines, and the order decides which engine wins every dispatch. That makes four
mistakes easy to make and invisible to the type system — the wrong supply form
(paying a bundle cost for an engine that never runs), an engine shadowed by an
earlier one (dead code that looks like a safety net), a type augmentation that
targets the wrong module (compiles, merges nothing), and a missing optional peer
(constructs cleanly, throws mid-turn in production).

## Install and register

```ts
import adkMedia from "@nhtio/adk/batteries/media/lint";

export default [
  {
    plugins: { "adk-media": adkMedia.plugin },
    rules: adkMedia.configs.recommended.rules,
  },
];
```

`eslint` and `@typescript-eslint/utils` are optional peer dependencies of
`@nhtio/adk`; the media battery never imports this module at runtime. Every rule
is report-only.

## `adk-media/prefer-engine-resolver`

A static value import of a bundled engine subpath (`import { sharpEngine } from
'@nhtio/adk/batteries/media/engines/sharp'`) puts that engine's wrapper module
into every bundle that mentions the pipeline — including the deployments that
never enable it. The canonical supply form is the dynamic-import resolver, which
is only ever reached when that engine actually dispatches.

```ts
// flagged
import { sharpEngine } from "@nhtio/adk/batteries/media/engines/sharp";

// correct
const pipeline = createMediaPipeline({
  engines: [
    () =>
      import("@nhtio/adk/batteries/media/engines/sharp").then((m) =>
        m.sharpEngine(),
      ),
  ],
});
```

Type-only imports pass — they are erased before anything is bundled.

## `adk-media/no-shadowed-engine`

Dispatch is **first-capable-wins**. An engine listed after another engine that
already covers everything it declares can never be selected, no matter what the
caller asks for: it is dead code occupying a slot in the array, and it reads like
a fallback that is not one.

```ts
// flagged — sharp's image/* mutate already covers this narrow webp-only resizer
const pipeline = createMediaPipeline({
  engines: [
    sharpEngine(),
    {
      id: "tiny",
      mutates: [
        { over: ["image/webp"], ops: ["resize"], encodes: ["webp"], mutate },
      ],
    },
  ],
});
```

The rule understands the bundled factories and literal inline declarations, and
it resolves the call through the file's import bindings: an aliased
`createMediaPipeline as mkPipeline` and a namespace
`media.createMediaPipeline` are the same battery export and are checked, while a
same-named factory imported from another module is not. Anything else it cannot
analyze statically — an identifier in the `engines` array, a spread, a computed
array, a config held in a variable — it leaves alone rather than guess.

::: info Field note: the shadow rule was wrong on day one
An ESLint rule cannot execute the factories it lints, so `no-shadowed-engine`
reasons about the bundled engines from a hand-copied summary table. Within an
hour of writing it, a drift test was added pinning that table to the live factory
declarations — and it failed immediately: the hand-written sharp summary claimed
a `bmp` encode the factory does not declare. Which meant the rule's own flagship
example was backwards. We had confidently written "`[sharp, jimp]` means jimp
never runs" in this very document, and it is false — jimp uniquely encodes bmp, so
it stays reachable behind sharp. The summary, the rule's tests, and this page were
all corrected the same hour.

The lesson is not subtle: any lint rule that mirrors runtime facts by hand WILL
drift, the drift will be invisible precisely because lint rules have no runtime,
and the only honest fix is a test that compares the mirror to the real thing
(`lint_drift.node.spec.ts`, plus a canary that fails when a new factory is
summarized without a matching assertion). If you write a rule like this, write
the pin first.
:::

## `adk-media/augment-contracts-module`

Extending `ConvertOptions` is TypeScript declaration merging, and it only merges
when the augmented module resolves to the same file the pipeline compiles
against. Target the barrel and the block compiles, looks right, and silently
never merges — your keys just do not exist, and nothing anywhere tells you why.
This is the nastiest failure mode here precisely because it produces no error.

```ts
// flagged — merges nothing
declare module "@nhtio/adk/batteries/media" {
  interface ConvertOptions {
    myOption?: boolean;
  }
}

// correct
declare module "@nhtio/adk/batteries/media/contracts" {
  interface ConvertOptions {
    myOption?: boolean;
  }
}
```

## `adk-media/require-engine-peers`

Every bundled engine lazily imports its optional peer: `sheetjsEngine` needs
`xlsx`, `jimpEngine` needs `jimp`, `exceljsEngine` needs `exceljs`, and so on.
Compose one without the peer installed and the pipeline constructs cleanly, then
throws `E_INVALID_MEDIA_PIPELINE_CONFIG` the **first time that engine runs** —
which, for an agent-driven pipeline, is in production, mid-turn, hours after the
code shipped.

The rule resolves each engine's peer from the linting file's own location, so it
honours your real `node_modules` layout, and reports the missing one at lint time
with the exact install command (SheetJS gets its CDN-tarball command, since
`npm i xlsx` installs a stale, CVE'd 0.18.5). Engines with no external peer —
soffice, fs\_workspace — have nothing to check. Use the `ignore` option when you
resolve a peer through a loader the linter cannot see.
