@supercat1337/coverage-to-markdown 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -66,17 +66,21 @@ the same path.
66
66
 
67
67
  ### Options
68
68
 
69
- | Flag | Short | Required | Description | Default |
70
- | ------------------- | ----- | -------- | -------------------------------------------- | ----------------------- |
71
- | `--ranges <ranges>` | `-r` | yes | Comma-separated line ranges | |
72
- | `--input <path>` | `-i` | yes | Source file to extract lines from | |
73
- | `--output <path>` | `-o` | yes | Markdown file to write | |
74
- | `--context <n>` | `-c` | | Lines of context before and after each range | `2` |
75
- | `--title <s>` | `-t` | | Top-level heading text | `Coverage: <basename>` |
76
- | `--fence <lang>` | | | Override fence language | Detected from extension |
77
- | `--force` | `-f` | | Overwrite the output file if it exists | off |
78
- | `--help` | `-h` | | Show usage and exit | |
79
- | `--version` | `-v` | | Print the version and exit | |
69
+ | Flag | Short | Required | Description | Default |
70
+ | --- | --- | --- | --- | --- |
71
+ | `--ranges <ranges>` | `-r` | yes | Comma-separated line ranges | |
72
+ | `--input <path>` | `-i` | yes | Source file to extract lines from | |
73
+ | `--output <path>` | `-o` | yes | Markdown file to write | |
74
+ | `--context <n>` | `-c` | | Lines of context before and after each range | `2` |
75
+ | `--title <s>` | `-t` | | Top-level heading text | `Coverage: <basename>` |
76
+ | `--fence <lang>` | | | Override fence language | Detected from extension |
77
+ | `--highlight <mode>` | | | Uncovered marker: `none`, `comment`, `gutter` | `comment` |
78
+ | `--command <cmd>` | | | Add a `Reproduce:` line to the header | |
79
+ | `--absolute-path` | | | Print the source path as absolute | off (relative) |
80
+ | `--force` | `-f` | | Overwrite the output file if it exists | off |
81
+ | `--quiet` | `-q` | | Suppress the success summary | off |
82
+ | `--help` | `-h` | | Show usage and exit | |
83
+ | `--version` | `-v` | | Print the version and exit | |
80
84
 
81
85
  ### Examples
82
86
 
@@ -91,6 +95,11 @@ cov2md \
91
95
  cov2md -c 10 -t "Uncovered @ abc123" \
92
96
  -r "176-181" -i ./src/index.js -o ./cov.md
93
97
 
98
+ # Diff-style gutter, with a reproduce hint
99
+ cov2md -r "10-20" -i ./src/client.js -o ./cov.md \
100
+ --highlight gutter \
101
+ --command "npm test && npx c8 report --reporter=text"
102
+
94
103
  # Force Python highlighting for a file with an unknown extension
95
104
  cov2md --fence python -r "10-20" -i ./script -o ./cov.md
96
105
 
@@ -98,6 +107,76 @@ cov2md --fence python -r "10-20" -i ./script -o ./cov.md
98
107
  cov2md -r "1-5" -i ./src/index.js -o ./existing.md --force
99
108
  ```
100
109
 
110
+ ### Output format
111
+
112
+ The document has one top-level heading (customisable via `--title`),
113
+ a short metadata block, then one `## R1 · line 56` or
114
+ `## R1 · lines 111–112` section per normalised range. Each section
115
+ contains a fenced code block with the language inferred from the file
116
+ extension, lines from `start - contextLines` through
117
+ `end + contextLines` (clamped to the file bounds), and markers on
118
+ uncovered lines (controlled by `--highlight`).
119
+
120
+ The metadata block looks like this:
121
+
122
+ ```text
123
+ Source: `src/client.js`
124
+ Reproduce: `npm test && npx c8 report`
125
+
126
+ 3 ranges · one contiguous uncovered block each · sorted by line
127
+ Labels R1..RN are assigned per run and may change when lines shift.
128
+ ```
129
+
130
+ - **`Source:`** is the input path. By default it is printed **relative to
131
+ the current working directory** with forward slashes, so it is portable
132
+ across machines and does not leak local file-system structure. Use
133
+ `--absolute-path` to print the absolute path instead.
134
+ - **`Reproduce:`** appears only when `--command` is given. Backticks and
135
+ newlines inside the command are replaced with single quotes and spaces
136
+ respectively to keep the Markdown valid.
137
+ - **`N range(s) · …`** states the count and the range convention.
138
+ - **`Labels R1..RN …`** warns that section labels are per-run and should
139
+ not be treated as stable references across regenerations.
140
+
141
+ ### Highlight modes
142
+
143
+ `--highlight` controls how uncovered lines are marked inside each
144
+ snippet.
145
+
146
+ `comment` (default) keeps every line copy-pasteable and appends a marker
147
+ to the trailing line-number comment on uncovered lines:
148
+
149
+ ```js
150
+ const pattern = ... // 174
151
+ const entries = ... // 175
152
+ for (const item of entries) { // 176 ← UNCOVERED
153
+ if (!item) continue; // 177 ← UNCOVERED
154
+ total += item.weight; // 178 ← UNCOVERED
155
+ } // 179 ← UNCOVERED
156
+ return total; // 180 ← UNCOVERED
157
+ } // 181 ← UNCOVERED
158
+ ```
159
+
160
+ `gutter` moves the line number to the left, right-aligns it, and uses
161
+ `>` for uncovered lines. Reads like a diff, but the snippet is no longer
162
+ directly pasteable into an editor:
163
+
164
+ ```js
165
+ 174 │ const pattern = ...
166
+ 175 │ const entries = ...
167
+ > 176 │ for (const item of entries) {
168
+ > 177 │ if (!item) continue;
169
+ > 178 │ total += item.weight;
170
+ > 179 │ }
171
+ > 180 │ return total;
172
+ > 181 │ }
173
+ 182 │ // (context after)
174
+ ```
175
+
176
+ `none` produces the pre-2.1 snippet format: `// <n>` comments on every
177
+ line, no uncovered marker. Useful when downstream tooling parses the
178
+ snippet and does not expect a marker.
179
+
101
180
  ### Ranges format
102
181
 
103
182
  Comma-separated segments; each segment is either `x-y` (inclusive) or a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@supercat1337/coverage-to-markdown",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Convert coverage ranges into markdown snippets with line numbers, surrounding context lines, and automatic fence language detection.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,31 +1,26 @@
1
1
  #!/usr/bin/env node
2
-
3
- // @ts-check
4
-
5
2
  /**
6
3
  * Coverage-to-markdown utility.
7
4
  *
8
5
  * Reads a source file and a coverage range string like
9
6
  * "176-181,258-270,305" and writes a markdown document where each range
10
7
  * is rendered as a fenced code block with configurable context lines
11
- * around it, and each line gets an inline "// <lineNumber>" comment.
12
- *
13
- * All CLI arguments are named flags. There is no positional form on
14
- * purpose: a missing or misplaced positional argument could otherwise
15
- * silently point the output at the input file and overwrite it.
8
+ * around it, an R-label, and uncovered lines marked according to the
9
+ * `highlight` option.
16
10
  *
17
11
  * The fence language is inferred from the source file extension, and the
18
12
  * fence length grows automatically when the snippet contains backtick
19
13
  * runs so that markdown fences never break.
20
14
  */
21
15
  import { existsSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';
22
- import { dirname, extname, resolve } from 'node:path';
16
+ import { dirname, extname, isAbsolute, relative, resolve } from 'node:path';
23
17
  import { fileURLToPath } from 'node:url';
24
18
  import { parseArgs } from 'node:util';
25
19
 
26
20
  /**
27
21
  * @typedef {import('./types.js').Range} Range
28
22
  * @typedef {import('./types.js').BuildOptions} BuildOptions
23
+ * @typedef {import('./types.js').HighlightMode} HighlightMode
29
24
  */
30
25
 
31
26
  /** @type {number} */
@@ -34,6 +29,9 @@ const DEFAULT_CONTEXT_LINES = 2;
34
29
  /** @type {number} */
35
30
  const MIN_FENCE_LENGTH = 3;
36
31
 
32
+ /** @type {HighlightMode[]} */
33
+ const VALID_HIGHLIGHTS = ['none', 'comment', 'gutter'];
34
+
37
35
  /**
38
36
  * File extension to markdown fence language identifier.
39
37
  * @type {Record<string, string>}
@@ -103,6 +101,9 @@ Options:
103
101
  -c, --context <n> Lines of context before and after each range (default: 2)
104
102
  -t, --title <s> Top-level heading text (default: "Coverage: <basename>")
105
103
  --fence <lang> Override fence language (default: from file extension)
104
+ --highlight <mode> Marker for uncovered lines: none | comment | gutter (default: comment)
105
+ --command <cmd> Add a "Reproduce:" line with the given command
106
+ --absolute-path Print the source path as absolute (default: relative to cwd)
106
107
  -f, --force Overwrite the output file if it already exists
107
108
  -q, --quiet Suppress the success summary on stdout
108
109
  -h, --help Show this help and exit
@@ -118,13 +119,12 @@ Examples:
118
119
  coverage-to-markdown --ranges "176-181,258-270" --input ./src/index.js --output ./coverage.md
119
120
  coverage-to-markdown -r "10-20" -i ./src/util.ts -o ./ctx.md -c 5
120
121
  coverage-to-markdown -r "1-5" -i ./src/index.js -o ./existing.md --force
122
+ coverage-to-markdown -r "10-20" -i ./src/client.js -o ./cov.md \\
123
+ --highlight gutter --command "npm test && npx c8 report"
121
124
  `;
122
125
 
123
126
  /**
124
127
  * Parse a coverage range string into an array of ranges.
125
- * Accepts comma-separated segments in the form "x-y" or "x".
126
- * Does not merge overlapping or adjacent ranges — use {@link normalizeRanges}
127
- * for that.
128
128
  * @param {string} input
129
129
  * @returns {Range[]}
130
130
  */
@@ -137,7 +137,6 @@ function parseRanges(input) {
137
137
  }
138
138
 
139
139
  /**
140
- * Parse a single segment of form "x-y" or "x" into a Range.
141
140
  * @param {string} segment
142
141
  * @returns {Range}
143
142
  */
@@ -156,7 +155,6 @@ function parseRangeSegment(segment) {
156
155
  }
157
156
 
158
157
  /**
159
- * Parse a positive integer line number.
160
158
  * @param {string} raw
161
159
  * @returns {number}
162
160
  */
@@ -170,7 +168,6 @@ function parseLineNumber(raw) {
170
168
 
171
169
  /**
172
170
  * Sort ranges and merge overlapping or directly adjacent ones.
173
- * For example, `[5-7, 8-10, 12-14]` becomes `[5-10, 12-14]`.
174
171
  * @param {Range[]} ranges
175
172
  * @returns {Range[]}
176
173
  */
@@ -195,8 +192,6 @@ function normalizeRanges(ranges) {
195
192
  }
196
193
 
197
194
  /**
198
- * Detect the markdown fence language from a file path extension.
199
- * Returns an empty string for unknown extensions or dotfiles.
200
195
  * @param {string} filePath
201
196
  * @returns {string}
202
197
  */
@@ -207,9 +202,6 @@ function detectFenceLanguage(filePath) {
207
202
  }
208
203
 
209
204
  /**
210
- * Compute the fence length needed so the snippet never breaks the fence.
211
- * Scans the snippet lines for backtick runs and returns `maxRun + 1`,
212
- * clamped to a minimum of three backticks.
213
205
  * @param {string[]} lines
214
206
  * @param {number} start
215
207
  * @param {number} end
@@ -234,7 +226,6 @@ function pickFenceLength(lines, start, end) {
234
226
  }
235
227
 
236
228
  /**
237
- * Split file content into lines, stripping trailing CR characters.
238
229
  * @param {string} content
239
230
  * @returns {string[]}
240
231
  */
@@ -243,39 +234,108 @@ function splitLines(content) {
243
234
  }
244
235
 
245
236
  /**
246
- * Compute the 1-based snippet boundaries for a range, clamped to file size.
247
237
  * @param {string[]} lines
248
238
  * @param {Range} range
249
239
  * @param {number} contextLines
250
240
  * @returns {{ start: number, end: number }}
251
241
  */
252
242
  function snippetBounds(lines, range, contextLines) {
253
- const total = lines.length;
254
243
  return {
255
244
  start: Math.max(1, range.start - contextLines),
256
- end: Math.min(total, range.end + contextLines),
245
+ end: Math.min(lines.length, range.end + contextLines),
257
246
  };
258
247
  }
259
248
 
260
249
  /**
261
- * Render snippet lines with `// <lineNumber>` suffixes.
250
+ * Format a range as a heading label: "line 56" or "lines 111–112".
251
+ * Uses an en-dash between range endpoints.
252
+ * @param {Range} range
253
+ * @returns {string}
254
+ */
255
+ function formatRangeLabel(range) {
256
+ if (range.start === range.end) {
257
+ return `line ${range.start}`;
258
+ }
259
+ return `lines ${range.start}–${range.end}`;
260
+ }
261
+
262
+ /**
263
+ * Render snippet in `none` mode: every line gets `// <n>`, no marker.
262
264
  * @param {string[]} lines
263
- * @param {number} start
264
- * @param {number} end
265
+ * @param {number} snippetStart
266
+ * @param {number} snippetEnd
265
267
  * @returns {string}
266
268
  */
267
- function renderSnippet(lines, start, end) {
269
+ function renderSnippetNone(lines, snippetStart, snippetEnd) {
268
270
  const parts = [];
269
- for (let n = start; n <= end; n += 1) {
271
+ for (let n = snippetStart; n <= snippetEnd; n += 1) {
270
272
  parts.push(`${lines[n - 1] ?? ''} // ${n}`);
271
273
  }
272
274
  return parts.join('\n');
273
275
  }
274
276
 
277
+ /**
278
+ * Render snippet in `comment` mode: context lines get `// <n>`,
279
+ * uncovered lines get `// <n> ← UNCOVERED`.
280
+ * @param {string[]} lines
281
+ * @param {Range} range
282
+ * @param {number} snippetStart
283
+ * @param {number} snippetEnd
284
+ * @returns {string}
285
+ */
286
+ function renderSnippetComment(lines, range, snippetStart, snippetEnd) {
287
+ const parts = [];
288
+ for (let n = snippetStart; n <= snippetEnd; n += 1) {
289
+ const isUncovered = n >= range.start && n <= range.end;
290
+ const marker = isUncovered ? ' ← UNCOVERED' : '';
291
+ parts.push(`${lines[n - 1] ?? ''} // ${n}${marker}`);
292
+ }
293
+ return parts.join('\n');
294
+ }
295
+
296
+ /**
297
+ * Render snippet in `gutter` mode: line number on the left with `│`
298
+ * separator, `>` for uncovered lines. Line numbers are right-aligned
299
+ * to the width of the largest number in the snippet.
300
+ * @param {string[]} lines
301
+ * @param {Range} range
302
+ * @param {number} snippetStart
303
+ * @param {number} snippetEnd
304
+ * @returns {string}
305
+ */
306
+ function renderSnippetGutter(lines, range, snippetStart, snippetEnd) {
307
+ const width = String(snippetEnd).length;
308
+ const parts = [];
309
+ for (let n = snippetStart; n <= snippetEnd; n += 1) {
310
+ const isUncovered = n >= range.start && n <= range.end;
311
+ const prefix = isUncovered ? '> ' : ' ';
312
+ const padded = String(n).padStart(width, ' ');
313
+ parts.push(`${prefix}${padded} │ ${lines[n - 1] ?? ''}`);
314
+ }
315
+ return parts.join('\n');
316
+ }
317
+
318
+ /**
319
+ * Dispatch to the correct snippet renderer.
320
+ * @param {string[]} lines
321
+ * @param {Range} range
322
+ * @param {number} snippetStart
323
+ * @param {number} snippetEnd
324
+ * @param {HighlightMode} highlight
325
+ * @returns {string}
326
+ */
327
+ function renderSnippet(lines, range, snippetStart, snippetEnd, highlight) {
328
+ if (highlight === 'gutter') {
329
+ return renderSnippetGutter(lines, range, snippetStart, snippetEnd);
330
+ }
331
+ if (highlight === 'none') {
332
+ return renderSnippetNone(lines, snippetStart, snippetEnd);
333
+ }
334
+ return renderSnippetComment(lines, range, snippetStart, snippetEnd);
335
+ }
336
+
275
337
  /**
276
338
  * Build the markdown document body for all ranges.
277
- * Input ranges are normalized (overlapping and adjacent ranges merged)
278
- * before rendering.
279
339
  * @param {string} sourcePath
280
340
  * @param {string[]} lines
281
341
  * @param {Range[]} ranges
@@ -288,23 +348,39 @@ function buildMarkdown(sourcePath, lines, ranges, options = {}) {
288
348
  throw new Error(`Invalid contextLines: ${contextLines}`);
289
349
  }
290
350
 
351
+ const highlight = options.highlight ?? 'comment';
352
+ if (!VALID_HIGHLIGHTS.includes(highlight)) {
353
+ throw new Error(
354
+ `Invalid highlight mode: "${highlight}". ` +
355
+ `Expected one of: ${VALID_HIGHLIGHTS.join(', ')}.`
356
+ );
357
+ }
358
+
291
359
  const normalized = normalizeRanges(ranges);
292
360
  const title = options.title ?? `Coverage: ${basenameOf(sourcePath)}`;
293
361
  const fenceLang = options.fence !== undefined ? options.fence : detectFenceLanguage(sourcePath);
294
362
 
295
- const header = [
296
- `# ${title}`,
297
- '',
298
- `Source: \`${sourcePath}\``,
299
- '',
300
- `Ranges: ${normalized.length}`,
301
- ].join('\n');
363
+ const headerLines = [`# ${title}`, '', `Source: \`${sourcePath}\``];
364
+
365
+ if (typeof options.command === 'string' && options.command.length > 0) {
366
+ const safeCommand = options.command.replace(/`/g, "'").replace(/\r?\n/g, ' ');
367
+ headerLines.push(`Reproduce: \`${safeCommand}\``);
368
+ }
369
+
370
+ headerLines.push('');
371
+
372
+ const count = normalized.length;
373
+ const noun = count === 1 ? 'range' : 'ranges';
374
+ headerLines.push(`${count} ${noun} · one contiguous uncovered block each · sorted by line`);
375
+ headerLines.push('Labels R1..RN are assigned per run and may change when lines shift.');
302
376
 
303
- const sections = normalized.map(range => {
377
+ const header = headerLines.join('\n');
378
+
379
+ const sections = normalized.map((range, index) => {
304
380
  const bounds = snippetBounds(lines, range, contextLines);
305
381
  const fenceLength = pickFenceLength(lines, bounds.start, bounds.end);
306
382
  const fence = '`'.repeat(fenceLength);
307
- const snippet = renderSnippet(lines, bounds.start, bounds.end);
383
+ const snippet = renderSnippet(lines, range, bounds.start, bounds.end, highlight);
308
384
 
309
385
  const block = [`${fence}${fenceLang}`];
310
386
  if (snippet.length > 0) {
@@ -312,7 +388,7 @@ function buildMarkdown(sourcePath, lines, ranges, options = {}) {
312
388
  }
313
389
  block.push(fence);
314
390
 
315
- return [`## Range (${range.start}, ${range.end})`, '', ...block].join('\n');
391
+ return [`## R${index + 1} · ${formatRangeLabel(range)}`, '', ...block].join('\n');
316
392
  });
317
393
 
318
394
  return [header, ...sections].join('\n\n') + '\n';
@@ -329,6 +405,20 @@ function basenameOf(filePath) {
329
405
  return lastSlash >= 0 ? normalized.slice(lastSlash + 1) : normalized;
330
406
  }
331
407
 
408
+ /**
409
+ * Return a display form of `absPath`: relative to cwd with forward
410
+ * slashes when possible, otherwise the original absolute path.
411
+ * @param {string} absPath
412
+ * @returns {string}
413
+ */
414
+ function toRelativeDisplay(absPath) {
415
+ const rel = relative(process.cwd(), absPath);
416
+ if (rel === '' || isAbsolute(rel)) {
417
+ return absPath;
418
+ }
419
+ return rel.replace(/\\/g, '/');
420
+ }
421
+
332
422
  /**
333
423
  * Read the package version from package.json.
334
424
  * @returns {string}
@@ -340,7 +430,6 @@ function readVersion() {
340
430
  }
341
431
 
342
432
  /**
343
- * Parse and validate the `--context` option value.
344
433
  * @param {string} raw
345
434
  * @returns {number}
346
435
  */
@@ -353,9 +442,20 @@ function parseContextOption(raw) {
353
442
  }
354
443
 
355
444
  /**
356
- * Reject positional arguments passed to the CLI.
357
- * Named arguments are mandatory so that a forgotten flag cannot shift
358
- * paths around and overwrite the input file with output.
445
+ * @param {string} raw
446
+ * @returns {HighlightMode}
447
+ */
448
+ function parseHighlightOption(raw) {
449
+ if (!VALID_HIGHLIGHTS.includes(raw)) {
450
+ throw new Error(
451
+ `Invalid --highlight value: "${raw}". ` +
452
+ `Expected one of: ${VALID_HIGHLIGHTS.join(', ')}.`
453
+ );
454
+ }
455
+ return /** @type {HighlightMode} */ (raw);
456
+ }
457
+
458
+ /**
359
459
  * @param {string[]} positionals
360
460
  * @returns {void}
361
461
  */
@@ -370,21 +470,14 @@ function rejectPositionals(positionals) {
370
470
  }
371
471
 
372
472
  /**
373
- * Ensure every required flag is present.
374
473
  * @param {Record<string, unknown>} values
375
474
  * @returns {{ ranges: string, input: string, output: string }}
376
475
  */
377
476
  function readRequiredFlags(values) {
378
477
  const missing = [];
379
- if (values.ranges === undefined) {
380
- missing.push('--ranges');
381
- }
382
- if (values.input === undefined) {
383
- missing.push('--input');
384
- }
385
- if (values.output === undefined) {
386
- missing.push('--output');
387
- }
478
+ if (values.ranges === undefined) {missing.push('--ranges');}
479
+ if (values.input === undefined) {missing.push('--input');}
480
+ if (values.output === undefined) {missing.push('--output');}
388
481
  if (missing.length > 0) {
389
482
  throw new Error(
390
483
  `Missing required argument(s): ${missing.join(', ')}. ` + 'Run with --help for usage.'
@@ -399,9 +492,9 @@ function readRequiredFlags(values) {
399
492
 
400
493
  /**
401
494
  * Validate input and output paths before any file is written.
402
- * @param {string} sourcePath absolute path to the source file
403
- * @param {string} outputPath absolute path to the output file
404
- * @param {boolean} force whether --force was passed
495
+ * @param {string} sourcePath
496
+ * @param {string} outputPath
497
+ * @param {boolean} force
405
498
  * @returns {void}
406
499
  */
407
500
  function guardFilePaths(sourcePath, outputPath, force) {
@@ -426,12 +519,10 @@ function guardFilePaths(sourcePath, outputPath, force) {
426
519
 
427
520
  /**
428
521
  * Check whether the current module was started as the main script.
429
- *
430
522
  * Compares real (symlink-resolved) paths instead of file URLs, because
431
523
  * on Windows process.argv[1] and import.meta.url can disagree on drive
432
- * letter case, on short (8.3) names, and on whether junctions are
433
- * resolved when the script is launched through an npm bin shim — the
434
- * exact setup that `npm link` produces.
524
+ * letter case, on short (8.3) names, and on junction resolution when
525
+ * launched through an npm bin shim (`npm link`).
435
526
  * @returns {boolean}
436
527
  */
437
528
  function isMainModule() {
@@ -468,8 +559,11 @@ function main(argv) {
468
559
  context: { type: 'string', short: 'c' },
469
560
  title: { type: 'string', short: 't' },
470
561
  fence: { type: 'string' },
562
+ highlight: { type: 'string' },
563
+ command: { type: 'string' },
471
564
  force: { type: 'boolean', short: 'f' },
472
565
  quiet: { type: 'boolean', short: 'q' },
566
+ 'absolute-path': { type: 'boolean' },
473
567
  help: { type: 'boolean', short: 'h' },
474
568
  version: { type: 'boolean', short: 'v' },
475
569
  },
@@ -492,6 +586,8 @@ function main(argv) {
492
586
  values.context !== undefined
493
587
  ? parseContextOption(values.context)
494
588
  : DEFAULT_CONTEXT_LINES;
589
+ const highlight =
590
+ values.highlight !== undefined ? parseHighlightOption(values.highlight) : 'comment';
495
591
 
496
592
  const sourcePath = resolve(flags.input);
497
593
  const outputPath = resolve(flags.output);
@@ -513,16 +609,18 @@ function main(argv) {
513
609
  const content = readFileSync(sourcePath, 'utf8');
514
610
  const lines = splitLines(content);
515
611
 
516
- const markdown = buildMarkdown(sourcePath, lines, rawRanges, {
612
+ const displayPath =
613
+ values['absolute-path'] === true ? sourcePath : toRelativeDisplay(sourcePath);
614
+
615
+ const markdown = buildMarkdown(displayPath, lines, rawRanges, {
517
616
  contextLines,
617
+ highlight,
518
618
  title: values.title,
519
619
  fence: values.fence,
620
+ command: values.command,
520
621
  });
521
622
 
522
623
  writeFileSync(outputPath, markdown, 'utf8');
523
-
524
- // Verify the file actually landed on disk; if it didn't, fail loudly
525
- // rather than silently reporting success.
526
624
  const written = statSync(outputPath);
527
625
 
528
626
  if (!values.quiet) {
package/src/types.d.ts CHANGED
@@ -8,6 +8,17 @@ export interface Range {
8
8
  end: number;
9
9
  }
10
10
 
11
+ /**
12
+ * How uncovered lines are marked inside rendered snippets.
13
+ *
14
+ * - `none` — no marker, just line-number comments (pre-2.1 snippet format).
15
+ * - `comment` — append `← UNCOVERED` to the line-number comment on
16
+ * uncovered lines; keeps lines copy-pasteable.
17
+ * - `gutter` — put the line number on the left with a `│` separator and
18
+ * use `>` for uncovered lines; reads like a diff.
19
+ */
20
+ export type HighlightMode = 'none' | 'comment' | 'gutter';
21
+
11
22
  /**
12
23
  * Options for `buildMarkdown`.
13
24
  */
@@ -18,4 +29,12 @@ export interface BuildOptions {
18
29
  title?: string;
19
30
  /** Fence language override. Default: detected from the file extension. */
20
31
  fence?: string;
32
+ /** How uncovered lines are marked. Default: `comment`. */
33
+ highlight?: HighlightMode;
34
+ /**
35
+ * Command that reproduces the coverage report. When set, a
36
+ * `Reproduce:` line is added to the header. Backticks and newlines
37
+ * are sanitised to keep the Markdown valid.
38
+ */
39
+ command?: string;
21
40
  }