@larriereguichet/comment-dup-check 0.0.0-stage → 1.1.1

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 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,24 @@
1
- # Temporary Holding Version
1
+ # @larriereguichet/comment-dup-check
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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
+ npx comment-dup-check src --exit-code # 1 when it found something, for a lint step
14
+ ```
15
+
16
+ Without `--exit-code` it reports and leaves 0, which is what you want while reading the output.
17
+ A gate needs the opposite: a step that only prints can never fail, so the duplication it finds
18
+ depends on someone reading the log.
19
+
20
+ A backticked citation becomes a placeholder before matching:
21
+ two blocks naming one identifier are not the target, two blocks arguing one rule are.
22
+ Production against production is listed; what a test shares is counted, not listed.
23
+ Two shapes it flags are not defects, so read before cutting:
24
+ 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,31 @@
1
1
  {
2
2
  "name": "@larriereguichet/comment-dup-check",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.1.1",
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
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://gitlab.com/larriereguichet/practices.git",
9
+ "directory": "packages/comment-dup-check"
10
+ },
11
+ "author": "lutangar",
12
+ "keywords": [
13
+ "comments",
14
+ "duplication",
15
+ "lint",
16
+ "documentation"
17
+ ],
18
+ "type": "module",
19
+ "bin": {
20
+ "comment-dup-check": "comment-dup-check.mjs"
21
+ },
22
+ "files": [
23
+ "comment-dup-check.mjs"
24
+ ],
25
+ "engines": {
26
+ "node": ">=22.18"
27
+ },
28
+ "publishConfig": {
29
+ "access": "public"
30
+ }
31
+ }