Lints import maps: HTML-spec-accurate resolution, unresolvable specifiers, unversioned or unaudited third-party CDN entries, missing integrity metadata, dead entries, and the structural errors the spec defines.

[error] duplicate-key: Duplicate key "moment" at imports.moment (occurs 2 times: 4:5, 5:5). JSON.parse keeps only the last one silently. (imports.moment)
[error] empty-specifier-key: Specifier key at imports is the empty string; the HTML spec requires it to be dropped. (imports)
[error] trailing-slash-mismatch: Specifier key "utils/" ends with "/", so its address must too; got "https://importmap-lint.invalid/no-trailing-slash". (imports.utils/)
[warn]  unversioned-remote-specifier: "moment" points at an unversioned remote URL (https://cdn.example.com/moment/moment.js) — no version segment, "@version", or "?v=" query found. This is the import-map equivalent of a floating tag: the code it loads can change without this file changing. (imports.moment)
[warn]  missing-integrity: "moment" (https://cdn.example.com/moment/moment.js) has no matching entry in the import map's "integrity" object, so a tampered or replaced response at that URL would load without complaint. (imports.moment)
[warn]  missing-integrity: "lodash" (https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/lodash.js) has no matching entry in the import map's "integrity" object, so a tampered or replaced response at that URL would load without complaint. (imports.lodash)
[warn]  unversioned-remote-specifier: "left-pad" points at an unversioned remote URL (https://cdn.example.com/left-pad/index.js) — no version segment, "@version", or "?v=" query found. This is the import-map equivalent of a floating tag: the code it loads can change without this file changing. (imports.left-pad)
[warn]  missing-integrity: "left-pad" (https://cdn.example.com/left-pad/index.js) has no matching entry in the import map's "integrity" object, so a tampered or replaced response at that URL would load without complaint. (imports.left-pad)
[warn]  unparseable-import: Dynamic import() at /tmp/demo/main.ts:4:29 does not have a plain string literal argument; it can't be checked statically.
[warn]  dead-entry: "utils/" in imports is not imported anywhere in the scanned source. (imports.utils/)
[warn]  dead-entry: "unused-vendor-thing" in imports is not imported anywhere in the scanned source. (imports.unused-vendor-thing)
[info]  remote-specifier: "moment" resolves to a third-party URL: https://cdn.example.com/moment/moment.js (imports.moment)
[info]  remote-specifier: "lodash" resolves to a third-party URL: https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/lodash.js (imports.lodash)
[info]  remote-specifier: "left-pad" resolves to a third-party URL: https://cdn.example.com/left-pad/index.js (imports.left-pad)

Scanned 1 source file(s). 3 error(s), 8 warning(s), 3 info finding(s).

That's the real, unedited output of node examples/demo.ts (the one file path is a Node temp directory, shortened here to /tmp/demo/main.ts for readability — the counts, rules, and messages are exactly what it printed) against a small import map seeded with one instance of every issue this tool looks for, plus one source file that imports from it.

Import maps are now a standard browser feature, and the mechanism Deno, buildless setups, and micro-frontend "scope"-based module federation use to pin what a bare specifier like "lodash" actually resolves to. That JSON is also an unguarded supply-chain surface with no equivalent of npm audit, npm ls, or a lockfile:

• An entry can point at any URL, including an unversioned third-party CDN URL — "lodash": "https://cdn.example.com/lodash/lodash.js" will load whatever that server serves at request time, forever. It is the import-map equivalent of FROM node:latest or an unpinned :latest tag.
• A typo'd or removed specifier in the codebase that isn't in the map fails only when a browser actually executes that code path — tsc, ESLint, and your bundler (if you have one) don't see it, because none of them resolve through the import map.
• Scopes have precedence rules people get wrong: the most-specific matching scope wins, but only if it actually defines the specifier — otherwise resolution falls through to a less-specific scope, and finally to the top-level imports. It is easy to add a scope override, watch it appear to do nothing, and not know why.
• The JSON has structural rules of its own — an empty-string key, a trailing-slash mismatch, a duplicate key — that a browser's JSON.parse will not warn you about; a duplicate key is silently resolved to "last one wins" with zero indication a duplicate ever existed.

Import maps are small enough that reading one over feels sufficient, and that is exactly the failure mode: scope precedence is not textual (you cannot tell which scope wins by reading top to bottom — it depends on the importing module's URL, which isn't in the file at all), and "is this specifier used anywhere" is a codebase-wide question, not a file-local one. Both require actually running the resolution algorithm and cross-referencing source, which is what this tool does instead of eyeballing it.

This is a small space, and worth being straightforward about what's already in it — checked on npm before writing this:

• importmap-check — a real, maintained package, but a different tool for a different job: it checks whether the packages named in an import map have newer versions available (an npm outdated for import maps), assuming the map is otherwise fine. It doesn't validate structure, flag unversioned/unaudited entries, or check integrity. Its name was already taken on npm, which is why this package is published as importmap-lint instead.
• @import-maps/resolve (open-wc/modern-web) — a real implementation of the resolution algorithm, used at runtime/dev-server time to actually resolve specifiers. It has no opinion on supply chain, dead entries, or CI; it's a resolver, not a linter.
• Nothing found combines spec-accurate structural validation, supply-chain signal detection, and cross-referencing against real source into one zero-dependency CLI with CI exit codes. That's the gap this fills.

npm install --save-dev importmap-lint

Node >= 20.6. No runtime dependencies.

npx importmap-lint import-map.json
npx importmap-lint index.html --src src/         # extract from <script type="importmap">,
                                                   # and cross-check against real imports
npx importmap-lint import-map.json --json         # machine-readable output
npx importmap-lint import-map.json --fail-on-warn # CI: fail the build on warnings too

Programmatically:

import { lintImportMap } from 'importmap-lint';

const report = lintImportMap({
  input: { text: await fs.readFile('import-map.json', 'utf8') },
  sourceDir: 'src', // optional: enables unresolvable-specifier / dead-entry checks
  baseURL: 'https://app.example/',
});

for (const finding of report.findings) console.log(finding.severity, finding.rule, finding.message);

Exit codes: 0 clean, 1 findings at/above the failure threshold, 2 usage error (bad arguments, missing file, --src matching zero source files).

Structural checks follow the HTML Standard's import map processing model — "parse an import map string", "sort and normalize a module specifier map", "sort and normalize scopes" — and resolution follows "resolve a module specifier" and "resolve an imports match" exactly, including the most-specific-scope-first precedence and the backtracking guard that stops a prefix mapping ("pkg/": "/vendor/pkg/") from being escaped with ../. src/resolve.ts and src/parse-import-map.ts cite the specific spec step for every check.

Tests are TypeScript run directly by Node's test runner — no build, no install:

node --test "test/*.test.ts"    # full suite, needs node 24+ for type stripping
node examples/demo.ts

npm run build && npm run test:dist   # what CI runs against node 20 and 22

test/fixtures/ includes two real import maps, fetched rather than invented: Deno's own import_map.json (~470 flat entries, no scopes or remote URLs — confirms large real-world flat maps parse cleanly) and a benchmark page from es-module-shims (a genuine <script type="importmap"> with a prefix mapping, extracted from real HTML, whose inline module also exercises the "dynamic import with a non-literal specifier" case for real).

• Doesn't implement the multi-import-map merge algorithm. A document can legally carry more than one <script type="importmap">, merged by rules this tool doesn't reproduce; given more than one, it refuses and asks for --script-index rather than silently picking (or merging) wrong.
• The source scanner is heuristic, not a parser. It tracks strings, comments, regex-literal-vs-division, and template-literal nesting well enough to find import/export ... from/import() reliably in ordinary code, but it can be fooled — e.g. a variable literally named from immediately assigned a string (const from = "x") can be misread as an import specifier if nothing between them resets the heuristic. require() is intentionally ignored (import maps don't apply to CommonJS). .d.ts files are skipped.
• --src cross-checks don't know each file's real browser URL. Which scopes entry applies to a given module depends on where a browser would load it from, which a static source tree doesn't encode. The unresolvable-specifier and dead-entry checks look at the union of top-level imports and every scope, not which scope would actually apply to a specific importing file.
• The version heuristic is pattern-based, not a semver parser: it recognizes @1.2.3, a bare 1.2.3/v18 path segment, and a ?v=/?version= query. An unconventional versioning scheme can produce a false "unversioned" flag; conversely, a path segment that merely looks like a version isn't proof the URL is actually pinned to immutable content.
• No network access. Nothing is fetched to confirm a CDN URL is reachable, that its integrity hash matches the live bytes, or that a "versioned" URL hasn't been republished in place. Zero dependencies means offline by construction, not just by default.
• Doesn't check whether an address a browser would actually load exists (404s, wrong MIME type) — this is a static analysis of the map and the source, not an integration test.

MIT