@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 +90 -11
- package/package.json +1 -1
- package/src/coverage-to-markdown.js +164 -66
- package/src/types.d.ts +19 -0
package/README.md
CHANGED
|
@@ -66,17 +66,21 @@ the same path.
|
|
|
66
66
|
|
|
67
67
|
### Options
|
|
68
68
|
|
|
69
|
-
| Flag
|
|
70
|
-
|
|
|
71
|
-
| `--ranges <ranges>` | `-r`
|
|
72
|
-
| `--input <path>`
|
|
73
|
-
| `--output <path>`
|
|
74
|
-
| `--context <n>`
|
|
75
|
-
| `--title <s>`
|
|
76
|
-
| `--fence <lang>`
|
|
77
|
-
| `--
|
|
78
|
-
| `--
|
|
79
|
-
| `--
|
|
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.
|
|
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,
|
|
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(
|
|
245
|
+
end: Math.min(lines.length, range.end + contextLines),
|
|
257
246
|
};
|
|
258
247
|
}
|
|
259
248
|
|
|
260
249
|
/**
|
|
261
|
-
*
|
|
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}
|
|
264
|
-
* @param {number}
|
|
265
|
+
* @param {number} snippetStart
|
|
266
|
+
* @param {number} snippetEnd
|
|
265
267
|
* @returns {string}
|
|
266
268
|
*/
|
|
267
|
-
function
|
|
269
|
+
function renderSnippetNone(lines, snippetStart, snippetEnd) {
|
|
268
270
|
const parts = [];
|
|
269
|
-
for (let n =
|
|
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
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
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
|
|
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 [`##
|
|
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
|
-
*
|
|
357
|
-
*
|
|
358
|
-
|
|
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
|
-
|
|
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
|
|
403
|
-
* @param {string} outputPath
|
|
404
|
-
* @param {boolean} force
|
|
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
|
|
433
|
-
*
|
|
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
|
|
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
|
}
|