@mui/internal-docs-infra
Version:
MUI Infra - internal documentation creation tools.
38 lines • 1.96 kB
text/typescript
import type { SourceComments } from "./types.mjs";
/**
* Merges two `SourceComments` maps by concatenating entries per line.
*
* Both maps are keyed by line number. The function does not interpret
* keys — it only matches them by value — so 0-indexed and 1-indexed
* conventions are both supported, but **both inputs must use the same
* convention**. The repository's `SourceTransformer` contract supplies
* 1-indexed line numbers; if you build `mine` by hand, match the
* upstream indexing of `input` or your markers will land on the wrong
* lines.
*
* In non-production builds a heuristic dev warning is emitted when the
* two inputs look like they disagree about indexing (one contains a
* `0` key and the other does not). The check has no runtime cost in
* production builds.
*
* For any line present in either map, the resulting entry is
* `[...input[line] ?? [], ...mine[line] ?? []]` — `input` markers come
* first, the transformer's own markers (`mine`) are appended.
*
* Returns `undefined` when the merge would produce no entries (both
* inputs absent, both empty, or every per-line array empty). Otherwise
* returns a fresh object whose per-line arrays are also fresh copies,
* so callers may safely mutate the result without affecting either
* input.
*
* Intended to be called by `SourceTransformer` implementations that
* receive an upstream `comments` map as their 3rd argument and want to
* preserve those entries alongside the markers they themselves emit.
*
* @param input - Comments map received by the transformer (may be
* `undefined` when no upstream comments exist).
* @param mine - Comments map the transformer wants to emit (may be
* `undefined` when the transformer has none of its own). Must use
* the same line-indexing convention as `input`.
*/
export declare function mergeComments(input: SourceComments | undefined, mine: SourceComments | undefined): SourceComments | undefined;