@larriereguichet/comment-dup-check 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +18 -2
- package/comment-dup-check.mjs +202 -0
- package/package.json +24 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 L'Arrière-Guichet
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,19 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @larriereguichet/comment-dup-check
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Where the same rule is written twice.
|
|
4
|
+
In a domain the comment is the specification, so two copies are two specifications,
|
|
5
|
+
free to diverge with nothing to catch them.
|
|
6
|
+
This reports the phrases of ten words or more that two or more comment blocks share,
|
|
7
|
+
longest first.
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install --save-dev --save-exact @larriereguichet/comment-dup-check
|
|
11
|
+
npx comment-dup-check src # the pathspecs git ls-files gets (default: src)
|
|
12
|
+
npx comment-dup-check src --words 8 --top 20
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
A backticked citation becomes a placeholder before matching:
|
|
16
|
+
two blocks naming one identifier are not the target, two blocks arguing one rule are.
|
|
17
|
+
Production against production is listed; what a test shares is counted, not listed.
|
|
18
|
+
Two shapes it flags are not defects, so read before cutting:
|
|
19
|
+
an upstream fact, which cannot diverge between copies, and sibling field docblocks.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* Where the same rule is written twice: the phrases of `--words` or more (default 10; below
|
|
4
|
+
* that the report fills with idiom and boilerplate) that two or more comment blocks share,
|
|
5
|
+
* longest first.
|
|
6
|
+
*
|
|
7
|
+
* In a domain the comment is the specification, so two copies are two specifications, free to
|
|
8
|
+
* diverge with nothing to catch them. A backticked citation becomes `cited` before matching:
|
|
9
|
+
* two blocks naming one identifier are not the target, two blocks arguing one rule are.
|
|
10
|
+
* Directives (`@perms:`, `biome-ignore`, `eslint-disable`…) are not prose and end a block.
|
|
11
|
+
*
|
|
12
|
+
* The report is production against production. A source and its own test sharing a sentence
|
|
13
|
+
* is a different question (the test names the rule it pins, the one restatement to keep), so
|
|
14
|
+
* those are counted, not listed. Two shapes it flags are not defects, so read before cutting:
|
|
15
|
+
* an upstream fact, which cannot diverge between copies, and sibling field docblocks in
|
|
16
|
+
* parallel.
|
|
17
|
+
*
|
|
18
|
+
* Run from the project root, no dependency (package @larriereguichet/comment-dup-check):
|
|
19
|
+
*
|
|
20
|
+
* npx comment-dup-check [pathspec…] [--words N] [--top N]
|
|
21
|
+
*
|
|
22
|
+
* The pathspecs go to `git ls-files` (default `src`); the `.ts`, `.tsx`, `.js` and `.mjs`
|
|
23
|
+
* files under them are read.
|
|
24
|
+
*/
|
|
25
|
+
import { execFileSync } from 'node:child_process';
|
|
26
|
+
import { existsSync, readFileSync } from 'node:fs';
|
|
27
|
+
|
|
28
|
+
// tools' directives, not prose (a `@todo:` or `@note:` line is prose and stays)
|
|
29
|
+
const DIRECTIVE =
|
|
30
|
+
/^\s*(?:@perms:|@env-file:|biome-ignore|eslint-(?:disable|enable)|prettier-ignore|@ts-(?:ignore|expect-error|nocheck|check)\b|(?:c8|istanbul) ignore)/;
|
|
31
|
+
const isCode = (f) => /\.(?:tsx?|m?js)$/.test(f);
|
|
32
|
+
const isTest = (where) => /\.(?:test|spec)\./.test(where);
|
|
33
|
+
|
|
34
|
+
/** One block per run of full-line comments, its words lowercased, a backticked span or a URL
|
|
35
|
+
* replaced by `cited` (the words around it stay aligned).
|
|
36
|
+
* A `*` line is prose only inside a `/* … *\/`: an expression's `* factor` is not. Pure. */
|
|
37
|
+
export function commentBlocks(path, text, minWords = 10) {
|
|
38
|
+
const out = [];
|
|
39
|
+
/** @type {{ line: number, parts: string[] } | null} */
|
|
40
|
+
let cur = null;
|
|
41
|
+
const flush = () => {
|
|
42
|
+
if (!cur) return;
|
|
43
|
+
const words = cur.parts
|
|
44
|
+
.join(' ')
|
|
45
|
+
.replaceAll(/`[^`]*`/g, ' cited ')
|
|
46
|
+
.replaceAll(/\bhttps?:\/\/\S+/g, ' cited ')
|
|
47
|
+
.toLowerCase()
|
|
48
|
+
.match(/[\p{L}\p{N}]+(?:['’-][\p{L}\p{N}]+)*/gu);
|
|
49
|
+
if (words && words.length >= minWords) out.push({ where: `${path}:${cur.line}`, words });
|
|
50
|
+
cur = null;
|
|
51
|
+
};
|
|
52
|
+
let inBlock = false;
|
|
53
|
+
for (const [i, raw] of text.split('\n').entries()) {
|
|
54
|
+
const line = raw.trim();
|
|
55
|
+
let prose = null;
|
|
56
|
+
if (inBlock) {
|
|
57
|
+
prose = line.replace(/^\*(?!\/)/, '');
|
|
58
|
+
if (line.includes('*/')) inBlock = false;
|
|
59
|
+
} else if (line.startsWith('//')) prose = line.replace(/^\/+/, '');
|
|
60
|
+
else if (line.startsWith('/*')) {
|
|
61
|
+
prose = line.replace(/^\/\*+/, '');
|
|
62
|
+
inBlock = !line.includes('*/');
|
|
63
|
+
}
|
|
64
|
+
if (prose === null || DIRECTIVE.test(prose)) {
|
|
65
|
+
flush();
|
|
66
|
+
continue;
|
|
67
|
+
}
|
|
68
|
+
cur ??= { line: i + 1, parts: [] };
|
|
69
|
+
cur.parts.push(prose.replace(/\*\/.*$/, ''));
|
|
70
|
+
}
|
|
71
|
+
flush();
|
|
72
|
+
return out;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** The maximal phrases of `minWords`+ words found in two or more blocks, longest first, none
|
|
76
|
+
* contained in a longer one found in the same places: each shared run of `minWords` grows
|
|
77
|
+
* word by word, its places splitting where their next words part. Pure. */
|
|
78
|
+
export function sharedPhrases(blocks, minWords = 10) {
|
|
79
|
+
const index = new Map();
|
|
80
|
+
for (const [b, { words }] of blocks.entries()) {
|
|
81
|
+
for (let p = 0; p + minWords <= words.length; p++) {
|
|
82
|
+
const key = words.slice(p, p + minWords).join(' ');
|
|
83
|
+
const hits = index.get(key);
|
|
84
|
+
if (hits) hits.push([b, p]);
|
|
85
|
+
else index.set(key, [[b, p]]);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
const found = new Map();
|
|
89
|
+
const distinct = (hits) => new Set(hits.map(([b]) => b)).size;
|
|
90
|
+
// grow a phrase while its places go on with the same word; where they part, report it and
|
|
91
|
+
// let each subgroup of two or more blocks grow on its own (a longer phrase fewer places share)
|
|
92
|
+
const grow = (hits, from) => {
|
|
93
|
+
let length = from; // grows while every place goes on with the same word
|
|
94
|
+
for (;;) {
|
|
95
|
+
const byNext = new Map();
|
|
96
|
+
for (const h of hits) {
|
|
97
|
+
const next = blocks[h[0]].words[h[1] + length];
|
|
98
|
+
if (next === undefined) continue;
|
|
99
|
+
byNext.set(next, [...(byNext.get(next) ?? []), h]);
|
|
100
|
+
}
|
|
101
|
+
const [only] = byNext.values();
|
|
102
|
+
if (byNext.size === 1 && only.length === hits.length) {
|
|
103
|
+
length++;
|
|
104
|
+
continue;
|
|
105
|
+
}
|
|
106
|
+
const [b0, p0] = hits[0];
|
|
107
|
+
const phrase = blocks[b0].words.slice(p0, p0 + length).join(' ');
|
|
108
|
+
const where = [...new Set(hits.map(([b]) => blocks[b].where))].sort();
|
|
109
|
+
if (where.length >= 2 && !found.has(phrase)) found.set(phrase, where);
|
|
110
|
+
for (const sub of byNext.values()) if (distinct(sub) >= 2) grow(sub, length + 1);
|
|
111
|
+
return;
|
|
112
|
+
}
|
|
113
|
+
};
|
|
114
|
+
for (const hits of index.values()) {
|
|
115
|
+
if (distinct(hits) < 2) continue;
|
|
116
|
+
// a run whose places all share the word before it is part of a longer run, grown from there
|
|
117
|
+
const before = new Set(hits.map(([b, p]) => (p > 0 ? blocks[b].words[p - 1] : undefined)));
|
|
118
|
+
if (before.size === 1 && !before.has(undefined)) continue;
|
|
119
|
+
grow(hits, minWords);
|
|
120
|
+
}
|
|
121
|
+
const ranked = [...found]
|
|
122
|
+
.map(([phrase, where]) => ({ phrase, words: phrase.split(' ').length, where }))
|
|
123
|
+
.sort((x, y) => y.words - x.words || (x.phrase < y.phrase ? -1 : 1));
|
|
124
|
+
// a shorter phrase inside a longer one says nothing new, unless it is found in more places
|
|
125
|
+
const kept = [];
|
|
126
|
+
for (const d of ranked) {
|
|
127
|
+
const covered = kept.some(
|
|
128
|
+
(k) => ` ${k.phrase} `.includes(` ${d.phrase} `) && d.where.every((w) => k.where.includes(w)),
|
|
129
|
+
);
|
|
130
|
+
if (!covered) kept.push(d);
|
|
131
|
+
}
|
|
132
|
+
return kept;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const USAGE = 'usage: comment-dup-check [pathspec…] [--words N] [--top N] [--exit-code]';
|
|
136
|
+
|
|
137
|
+
/** `--words N` / `--words=N` and `--top`, each a whole number ≥ 1, `--exit-code`, and the
|
|
138
|
+
* pathspecs; anything else exits 2: a NaN would report a clean bill over nothing. */
|
|
139
|
+
function parse(args) {
|
|
140
|
+
const opts = { words: 10, top: Number.POSITIVE_INFINITY, exitCode: false };
|
|
141
|
+
const specs = [];
|
|
142
|
+
// biome-ignore lint/style/useForOf: an option's value is the next argument (++i)
|
|
143
|
+
for (let i = 0; i < args.length; i++) {
|
|
144
|
+
if (args[i] === '--exit-code') {
|
|
145
|
+
opts.exitCode = true; // for a gate: reporting alone always passes
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
148
|
+
const m = /^--(words|top)(?:=(.*))?$/.exec(args[i]);
|
|
149
|
+
if (!m) {
|
|
150
|
+
if (args[i].startsWith('--')) fail(`unknown option: ${args[i]}`);
|
|
151
|
+
specs.push(args[i]);
|
|
152
|
+
continue;
|
|
153
|
+
}
|
|
154
|
+
const raw = m[2] ?? args[++i];
|
|
155
|
+
const n = Number(raw);
|
|
156
|
+
if (!Number.isInteger(n) || n < 1) fail(`--${m[1]} wants a whole number ≥ 1, got "${raw}"`);
|
|
157
|
+
opts[m[1]] = n;
|
|
158
|
+
}
|
|
159
|
+
return { ...opts, specs };
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function fail(msg) {
|
|
163
|
+
console.error(`${msg}\n${USAGE}`);
|
|
164
|
+
process.exit(2);
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
function main(args) {
|
|
168
|
+
const { words: minWords, top, specs, exitCode } = parse(args);
|
|
169
|
+
const files = execFileSync('git', ['ls-files', '--', ...(specs.length ? specs : ['src'])], {
|
|
170
|
+
encoding: 'utf8',
|
|
171
|
+
})
|
|
172
|
+
.split('\n')
|
|
173
|
+
.filter((f) => isCode(f) && existsSync(f)); // tracked but deleted, not yet staged: gone
|
|
174
|
+
// a clean bill of health over nothing is worse than none
|
|
175
|
+
if (files.length === 0) {
|
|
176
|
+
console.error(`no tracked code file under ${specs.join(' ') || 'src'}: pass the pathspecs`);
|
|
177
|
+
process.exit(1);
|
|
178
|
+
}
|
|
179
|
+
const blocks = files.flatMap((f) => commentBlocks(f, readFileSync(f, 'utf8'), minWords));
|
|
180
|
+
const prod = sharedPhrases(
|
|
181
|
+
blocks.filter((b) => !isTest(b.where)),
|
|
182
|
+
minWords,
|
|
183
|
+
);
|
|
184
|
+
// what a test shares and production alone does not repeat: counted, not listed
|
|
185
|
+
const withTests = sharedPhrases(blocks, minWords).filter(
|
|
186
|
+
(d) => d.where.some(isTest) && d.where.filter((w) => !isTest(w)).length < 2,
|
|
187
|
+
).length;
|
|
188
|
+
for (const d of prod.slice(0, top)) {
|
|
189
|
+
console.log(`${d.words} words × ${d.where.length}: ${d.phrase}\n ${d.where.join('\n ')}`);
|
|
190
|
+
}
|
|
191
|
+
console.log(
|
|
192
|
+
`${prod.length} phrase(s) in two or more production comments (${blocks.length} blocks, ` +
|
|
193
|
+
`${files.length} files); ${withTests} more shared with a test`,
|
|
194
|
+
);
|
|
195
|
+
if (exitCode && prod.length) process.exitCode = 1;
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
if (import.meta.main === undefined)
|
|
199
|
+
throw new Error(
|
|
200
|
+
`Node 22.18 or later, not ${process.version}: left undefined, import.meta.main would make this a silent no-op`,
|
|
201
|
+
);
|
|
202
|
+
if (import.meta.main) main(process.argv.slice(2));
|
package/package.json
CHANGED
|
@@ -1,6 +1,26 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@larriereguichet/comment-dup-check",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"description": "Where the same rule is written twice: the phrases of ten words or more that two comment blocks share.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"author": "lutangar",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"comments",
|
|
9
|
+
"duplication",
|
|
10
|
+
"lint",
|
|
11
|
+
"documentation"
|
|
12
|
+
],
|
|
13
|
+
"type": "module",
|
|
14
|
+
"bin": {
|
|
15
|
+
"comment-dup-check": "comment-dup-check.mjs"
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"comment-dup-check.mjs"
|
|
19
|
+
],
|
|
20
|
+
"engines": {
|
|
21
|
+
"node": ">=22.18"
|
|
22
|
+
},
|
|
23
|
+
"publishConfig": {
|
|
24
|
+
"access": "public"
|
|
25
|
+
}
|
|
26
|
+
}
|