fix(codemod): keep a file's leading comment block above rewritten imports

[axits-lab]

Fixes#2575

Root cause

v1-to-v2 positions a re-emitted import against the full start of the declaration it replaces, which is ahead of that declaration's leading trivia. Both shapes in the issue follow from that one fact:

Shape A — header hoisted over, blank line consumed

// Copyright (c) 2026 Example Corp.// SPDX-License-Identifier: Apache-2.0importtype{CallToolResult}from'@modelcontextprotocol/sdk/types.js';exportconstok=(): CallToolResult=>({content: []});

became

importtype{CallToolResult}from"@modelcontextprotocol/server";// Copyright (c) 2026 Example Corp.// SPDX-License-Identifier: Apache-2.0exportconstok=(): CallToolResult=>({content: []});

The header stops being the first thing in the file, so eslint-plugin-header / eslint-plugin-notice / SPDX scanners start failing on a file that previously passed. The blank line goes with it, so the header now reads as a doc comment on export const ok.

Shape B — import inserted inside the header run

When the header is a multi-line // run and the SDK import is not the first import, line 1 is stranded above an unrelated import:

// page_to_markdown tool: fetches a URL and returns clean Markdown.importtype{CallToolResult}from"@modelcontextprotocol/server";// Uses @page2ai/core under the hood - inherits SSRF protection and a 10MB cap.// Static tab discovery emits per-tab sections for docs sites.import{fetchAndConvert}from'@page2ai/core';

As the reporter notes, Prettier does not move the import back, so the guide's "run your formatter" step does not cover either shape.

Fix

Detach the comment block anchored at byte 0 for the duration of the rewrite and restore the exact bytes afterwards — the trivia those insertion positions are derived from no longer exists while imports are emitted.

Scope is deliberately narrow: only a block starting at byte 0 is treated as a file header. A comment above a mid-file import documents that import and must travel with it, which the existing leading-comment capture still handles (covered by a third test).

The detached slice includes the whitespace following the block, so the blank line separating header from code survives the round trip.

On the existing tests

There were already three leading-header tests. All three assert only that the header's content survives (toContain) — none assert its position, which is why both shapes passed them. The new tests assert position and the surviving blank line. Verified they fail on main without the src change:

× keeps a license header above the rewritten import, with its blank line intact
× does not split a multi-line header run when the SDK import is not the first import

Verification

• 632/632 codemod tests pass (629 existing + 3 new)
• pnpm lint and pnpm typecheck clean
• Built the CLI and ran it against the reporter's exact repro — output now matches their "Expected" block byte-for-byte:

// Copyright (c) 2026 Example Corp.// SPDX-License-Identifier: Apache-2.0importtype{CallToolResult}from"@modelcontextprotocol/server";exportconstok=(): CallToolResult=>({content: []});

Changeset included.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4afd7e4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@modelcontextprotocol/codemod	Patch
@modelcontextprotocol/core	Patch
@modelcontextprotocol/client	Patch
@modelcontextprotocol/server	Patch
@modelcontextprotocol/server-legacy	Patch
@modelcontextprotocol/core-internal	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@2582

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@2582

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@2582

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@2582

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@2582

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@2582

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@2582

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@2582

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@2582

commit: 4afd7e4