Skip to content

Commit 3127546

Browse files
committed
📝 Enforce banned words in architecture and JSDoc prose
1 parent 2bc1f2e commit 3127546

11 files changed

Lines changed: 379 additions & 1 deletion

‎.oxlint-prose.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"ignorePatterns": [
3+
"**/node_modules/**",
4+
"site/_fresh/**",
5+
"site/vendor/**",
6+
"site/*.timestamp-*.mjs"
7+
],
8+
"categories": { "correctness": "off" },
9+
"jsPlugins": [{ "name": "local", "specifier": "./scripts/oxlint-plugin.js" }],
10+
"rules": { "local/no-banned-jsdoc-words": "error" }
11+
}

‎.oxlintrc.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414

1515
"rules": {
1616
"eslint/curly": "error",
17+
"local/no-banned-jsdoc-words": "error",
1718
"local/no-module-scoped-registry": "error",
1819
"local/no-section-divider-comments": "error",
1920
"local/no-sync-filesystem": "error",

‎AGENTS.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -503,6 +503,12 @@ the corpus or enabling in-shard concurrency is not an answer to a miss.
503503
alternatives, defensive qualifications, and exhaustive detail that does not
504504
help a reader understand or use the design.
505505

506+
### Banned words
507+
508+
Avoid words in the canonical [banned-words list](scripts/banned-words.js) when
509+
writing architecture prose or JSDoc. Choose wording for the specific meaning;
510+
keep literal code references intact. `deno task lint` enforces the list.
511+
506512
### Component descriptions
507513

508514
Write a component description for an author deciding what to type. Lead with an

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@
7575
"test:node": "tsx scripts/runtime-tests.ts node",
7676
"test:bun": "bun scripts/runtime-tests.ts bun",
7777
"test:deno": "deno task test",
78-
"lint": "oxlint -c .oxlintrc.json --ignore-pattern 'scripts/tests/fixtures/**' --ignore-pattern '**/npm/**' --ignore-pattern 'packages/workflow/vendor/cloudflare-computer-dofs/**' --ignore-pattern 'packages/acp/vendor/acpx/**' --ignore-pattern 'packages/cli/src/repl/vendor/freedom/**' packages scripts && oxfmt --check packages scripts && pnpm run lint:dead-code",
78+
"lint": "oxlint -c .oxlintrc.json --ignore-pattern 'scripts/tests/fixtures/**' --ignore-pattern '**/npm/**' --ignore-pattern 'packages/workflow/vendor/cloudflare-computer-dofs/**' --ignore-pattern 'packages/acp/vendor/acpx/**' --ignore-pattern 'packages/cli/src/repl/vendor/freedom/**' packages scripts && oxlint -c .oxlint-prose.json site smoke-test && node scripts/lint-architecture.js && oxfmt --check packages scripts && pnpm run lint:dead-code",
7979
"lint:dead-code": "knip --config knip.json --no-progress --no-config-hints --include files,exports,types",
8080
"fmt": "oxfmt --write packages scripts"
8181
},

‎scripts/banned-words.js‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
export const BANNED_WORDS = [
2+
"claim",
3+
"claims",
4+
"claimed",
5+
"claiming",
6+
"claimant",
7+
"claimants",
8+
"unclaimed",
9+
"reclaim",
10+
"reclaims",
11+
"reclaimed",
12+
"reclaiming",
13+
];

‎scripts/lib/banned-words.js‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
import { remark } from "remark";
2+
import { BANNED_WORDS } from "../banned-words.js";
3+
4+
export function bannedProseWords(source) {
5+
const forbidden = new Set(BANNED_WORDS.map((word) => word.toLowerCase()));
6+
const findings = [];
7+
8+
function visit(node) {
9+
if (node.type === "text") {
10+
const start = node.position.start.offset;
11+
const text = source.slice(start, node.position.end.offset);
12+
for (const match of text.matchAll(/[\p{L}\p{N}_$]+/gu)) {
13+
if (forbidden.has(match[0].toLowerCase())) {
14+
findings.push({ word: match[0], offset: start + match.index });
15+
}
16+
}
17+
}
18+
for (const child of node.children ?? []) {
19+
visit(child);
20+
}
21+
}
22+
23+
visit(remark().parse(source));
24+
return findings;
25+
}

‎scripts/lint-architecture.js‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
import { readTextFile } from "@effectionx/fs";
2+
import { exit, main } from "effection";
3+
import { bannedProseWords } from "./lib/banned-words.js";
4+
5+
main(function* () {
6+
const file = process.argv[2] ?? new URL("../architecture.md", import.meta.url);
7+
const source = yield* readTextFile(file);
8+
const findings = bannedProseWords(source);
9+
for (const { word, offset } of findings) {
10+
const before = source.slice(0, offset);
11+
const line = before.split("\n").length;
12+
const column = offset - before.lastIndexOf("\n");
13+
console.error(
14+
`${file}:${line}:${column}: forbidden prose word "${word}" (scripts/banned-words.js)`,
15+
);
16+
}
17+
if (findings.length > 0) {
18+
yield* exit(1);
19+
}
20+
});

‎scripts/oxlint-plugin.js‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import { requireScopeBoundEventRegistration } from "./oxlint-rules/require-scope
1010
export default {
1111
meta: { name: "executablemd" },
1212
rules: {
13+
"no-banned-jsdoc-words": noBannedJsdocWords,
1314
"no-module-scoped-registry": noModuleScopedRegistry,
1415
"no-section-divider-comments": noSectionDividerComments,
1516
"no-redundant-test-scope": noRedundantTestScope,
@@ -20,3 +21,4 @@ export default {
2021
"require-scope-bound-event-registration": requireScopeBoundEventRegistration,
2122
},
2223
};
24+
import { noBannedJsdocWords } from "./oxlint-rules/no-banned-jsdoc-words.js";
Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
import { bannedProseWords } from "../lib/banned-words.js";
2+
3+
function annotationEnd(text, start) {
4+
let cursor = start;
5+
while (/\s/.test(text[cursor] ?? "") && cursor < text.length) {
6+
cursor++;
7+
}
8+
if (text[cursor] !== "{") {
9+
return start;
10+
}
11+
let depth = 0;
12+
let quote;
13+
for (; cursor < text.length; cursor++) {
14+
const character = text[cursor];
15+
if (quote) {
16+
if (character === "\\") {
17+
cursor++;
18+
} else if (character === quote) {
19+
quote = undefined;
20+
}
21+
} else if (character === '"' || character === "'" || character === "`") {
22+
quote = character;
23+
} else if (character === "{") {
24+
depth++;
25+
} else if (character === "}") {
26+
if (--depth === 0) {
27+
return cursor + 1;
28+
}
29+
}
30+
}
31+
return start;
32+
}
33+
34+
function prose(comment) {
35+
const characters = [];
36+
const offsets = [];
37+
const body = comment.value.slice(1);
38+
let offset = comment.range[0] + 3;
39+
40+
for (const line of body.matchAll(/[^\n]*(?:\n|$)/g)) {
41+
const margin = /^\s*\* ?/.exec(line[0])?.[0].length ?? 0;
42+
for (let index = margin; index < line[0].length; index++) {
43+
characters.push(line[0][index]);
44+
offsets.push(offset + index);
45+
}
46+
offset += line[0].length;
47+
}
48+
49+
// Annotation syntax and link targets name code; their descriptions remain prose.
50+
let text = characters.join("");
51+
text = text.replace(/\{@(?:link|linkcode|linkplain)\s+[^\s|}]+/g, (value) =>
52+
" ".repeat(value.length),
53+
);
54+
text = text.replace(/^[ \t]*@example\b[^]*?(?=^[ \t]*@[\w-]+|$(?![^]))/gm, (value) =>
55+
value.replace(/[^\r\n]/g, " "),
56+
);
57+
const original = text;
58+
for (const tag of original.matchAll(/^[ \t]*@([\w-]+)/gm)) {
59+
let end = annotationEnd(original, tag.index + tag[0].length);
60+
if (
61+
/^(?:param|arg|argument|property|prop|typedef|callback|template|typeParam|extends|implements|see)$/.test(
62+
tag[1],
63+
)
64+
) {
65+
const name = /^[ \t]+(?:\[[^\]\n]*\]|[\w.$]+(?:[ \t]*,[ \t]*[\w.$]+)*)/.exec(
66+
original.slice(end),
67+
);
68+
end += name?.[0].length ?? 0;
69+
}
70+
text =
71+
text.slice(0, tag.index) +
72+
text.slice(tag.index, end).replace(/[^\r\n]/g, " ") +
73+
text.slice(end);
74+
}
75+
return { text, offsets };
76+
}
77+
78+
export const noBannedJsdocWords = {
79+
meta: {
80+
type: "suggestion",
81+
messages: {
82+
forbidden:
83+
'Avoid "{{word}}" in prose; choose wording for its meaning (scripts/banned-words.js).',
84+
},
85+
},
86+
create(context) {
87+
const source = context.sourceCode;
88+
return {
89+
Program() {
90+
for (const comment of source.getAllComments()) {
91+
if (comment.type !== "Block" || !source.text.startsWith("/**", comment.range[0])) {
92+
continue;
93+
}
94+
const { text, offsets } = prose(comment);
95+
for (const { word, offset } of bannedProseWords(text)) {
96+
const start = offsets[offset];
97+
context.report({
98+
loc: {
99+
start: source.getLocFromIndex(start),
100+
end: source.getLocFromIndex(start + word.length),
101+
},
102+
messageId: "forbidden",
103+
data: { word },
104+
});
105+
}
106+
}
107+
},
108+
};
109+
},
110+
};

0 commit comments

Comments
 (0)