Media battery rules
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
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.
// 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.
// 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.
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.
// 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.