Skip to content

Commit 27d71c9

Browse files
committed
fix(hooks): port doc-file-warning denylist policy to current hook runtime
Replace the broad allowlist approach with a targeted denylist that only warns on known ad-hoc filenames (NOTES, TODO, SCRATCH, TEMP, DRAFT, BRAINSTORM, SPIKE, DEBUG, WIP) outside structured directories. This eliminates false positives for legitimate markdown-heavy workflows while still catching impulse documentation files. Closes anomalyco#988 Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> Signed-off-by: Lidang-Jiang <[email protected]>
1 parent 6f16e75 commit 27d71c9

2 files changed

Lines changed: 127 additions & 39 deletions

File tree

‎scripts/hooks/doc-file-warning.js‎

Lines changed: 53 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
11
#!/usr/bin/env node
22
/**
33
* Doc file warning hook (PreToolUse - Write)
4-
* Warns about non-standard documentation files.
4+
*
5+
* Uses a denylist approach: only warn on known ad-hoc documentation
6+
* filenames (NOTES, TODO, SCRATCH, etc.) outside structured directories.
7+
* This avoids false positives for legitimate markdown-heavy workflows
8+
* (specs, ADRs, command definitions, skill files, etc.).
9+
*
10+
* Policy ported from the intent of PR #962 into the current hook architecture.
511
* Exit code 0 always (warns only, never blocks).
612
*/
713

@@ -12,31 +18,59 @@ const path = require('path');
1218
const MAX_STDIN = 1024 * 1024;
1319
let data = '';
1420

15-
function isAllowedDocPath(filePath) {
21+
// Known ad-hoc filenames that indicate impulse/scratch files (case-sensitive, uppercase only)
22+
const ADHOC_FILENAMES = /^(NOTES|TODO|SCRATCH|TEMP|DRAFT|BRAINSTORM|SPIKE|DEBUG|WIP)\.(md|txt)$/;
23+
24+
// Structured directories where even ad-hoc names are intentional
25+
const STRUCTURED_DIRS = /(^|\/)(docs|\.claude|\.github|commands|skills|benchmarks|templates|\.history|memory)\//;
26+
27+
function isSuspiciousDocPath(filePath) {
1628
const normalized = filePath.replace(/\\/g, '/');
17-
const basename = path.basename(filePath);
29+
const basename = path.basename(normalized);
1830

19-
if (!/\.(md|txt)$/i.test(filePath)) return true;
31+
// Only inspect .md and .txt files
32+
if (!/\.(md|txt)$/i.test(basename)) return false;
2033

21-
if (/^(README|CLAUDE|AGENTS|CONTRIBUTING|CHANGELOG|LICENSE|SKILL|MEMORY|WORKLOG)\.md$/i.test(basename)) {
22-
return true;
23-
}
34+
// Only flag known ad-hoc filenames
35+
if (!ADHOC_FILENAMES.test(basename)) return false;
2436

25-
if (/\.claude\/(commands|plans|projects)\//.test(normalized)) {
26-
return true;
27-
}
37+
// Allow ad-hoc names inside structured directories (intentional usage)
38+
if (STRUCTURED_DIRS.test(normalized)) return false;
2839

29-
if (/(^|\/)(docs|skills|\.history|memory)\//.test(normalized)) {
30-
return true;
40+
return true;
41+
}
42+
43+
/**
44+
* Exportable run() for in-process execution via run-with-flags.js.
45+
* Avoids the ~50-100ms spawnSync overhead when available.
46+
*/
47+
function run(inputOrRaw) {
48+
let input;
49+
try {
50+
input = typeof inputOrRaw === 'string'
51+
? (inputOrRaw.trim() ? JSON.parse(inputOrRaw) : {})
52+
: (inputOrRaw || {});
53+
} catch {
54+
return { exitCode: 0 };
3155
}
56+
const filePath = String(input?.tool_input?.file_path || '');
3257

33-
if (/\.plan\.md$/i.test(basename)) {
34-
return true;
58+
if (filePath && isSuspiciousDocPath(filePath)) {
59+
return {
60+
exitCode: 0,
61+
stderr:
62+
'[Hook] WARNING: Ad-hoc documentation filename detected\n' +
63+
`[Hook] File: ${filePath}\n` +
64+
'[Hook] Consider using structured paths: docs/, .claude/commands/, skills/',
65+
};
3566
}
3667

37-
return false;
68+
return { exitCode: 0 };
3869
}
3970

71+
module.exports = { run };
72+
73+
// Stdin fallback for spawnSync execution
4074
process.stdin.setEncoding('utf8');
4175
process.stdin.on('data', c => {
4276
if (data.length < MAX_STDIN) {
@@ -46,17 +80,10 @@ process.stdin.on('data', c => {
4680
});
4781

4882
process.stdin.on('end', () => {
49-
try {
50-
const input = JSON.parse(data);
51-
const filePath = String(input.tool_input?.file_path || '');
52-
53-
if (filePath && !isAllowedDocPath(filePath)) {
54-
console.error('[Hook] WARNING: Non-standard documentation file detected');
55-
console.error(`[Hook] File: ${filePath}`);
56-
console.error('[Hook] Consider consolidating into README.md or docs/ directory');
57-
}
58-
} catch {
59-
// ignore parse errors
83+
const result = run(data);
84+
85+
if (result.stderr) {
86+
process.stderr.write(result.stderr + '\n');
6087
}
6188

6289
process.stdout.write(data);

‎tests/hooks/doc-file-warning.test.js‎

Lines changed: 74 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -29,11 +29,11 @@ function runScript(input) {
2929
}
3030

3131
function runTests() {
32-
console.log('\n=== Testing doc-file-warning.js ===\n');
32+
console.log('\n=== Testing doc-file-warning.js (denylist policy) ===\n');
3333
let passed = 0;
3434
let failed = 0;
3535

36-
// 1. Allowed standard doc files - no warning in stderr
36+
// 1. Standard doc filenames - never on denylist, no warning
3737
const standardFiles = [
3838
'README.md',
3939
'CLAUDE.md',
@@ -53,20 +53,26 @@ function runTests() {
5353
}) ? passed++ : failed++);
5454
}
5555

56-
// 2. Allowed directory paths - no warning
57-
const allowedDirPaths = [
56+
// 2. Structured directory paths - no warning even for ad-hoc names
57+
const structuredDirPaths = [
5858
'docs/foo.md',
5959
'docs/guide/setup.md',
60+
'docs/TODO.md',
61+
'docs/specs/NOTES.md',
6062
'skills/bar.md',
6163
'skills/testing/tdd.md',
6264
'.history/session.md',
6365
'memory/patterns.md',
6466
'.claude/commands/deploy.md',
6567
'.claude/plans/roadmap.md',
6668
'.claude/projects/myproject.md',
69+
'.github/ISSUE_TEMPLATE/bug.md',
70+
'commands/triage.md',
71+
'benchmarks/test.md',
72+
'templates/DRAFT.md',
6773
];
68-
for (const file of allowedDirPaths) {
69-
(test(`allows directory path: ${file}`, () => {
74+
for (const file of structuredDirPaths) {
75+
(test(`allows structured directory path: ${file}`, () => {
7076
const { code, stderr } = runScript({ tool_input: { file_path: file } });
7177
assert.strictEqual(code, 0, `expected exit code 0, got ${code}`);
7278
assert.strictEqual(stderr, '', `expected no warning for ${file}, got: ${stderr}`);
@@ -96,18 +102,61 @@ function runTests() {
96102
}) ? passed++ : failed++);
97103
}
98104

99-
// 5. Non-standard doc files - warning in stderr
100-
const nonStandardFiles = ['random-notes.md', 'TODO.md', 'notes.txt', 'scratch.md', 'ideas.txt'];
101-
for (const file of nonStandardFiles) {
102-
(test(`warns on non-standard doc file: ${file}`, () => {
105+
// 5. Lowercase and partial-match filenames - NOT on denylist, no warning
106+
const allowedNonDenylist = [
107+
'random-notes.md',
108+
'notes.txt',
109+
'scratch.md',
110+
'ideas.txt',
111+
'todo-list.md',
112+
'my-draft.md',
113+
'meeting-notes.txt',
114+
];
115+
for (const file of allowedNonDenylist) {
116+
(test(`allows non-denylist doc file: ${file}`, () => {
117+
const { code, stderr } = runScript({ tool_input: { file_path: file } });
118+
assert.strictEqual(code, 0);
119+
assert.strictEqual(stderr, '', `expected no warning for ${file}, got: ${stderr}`);
120+
}) ? passed++ : failed++);
121+
}
122+
123+
// 6. Ad-hoc denylist filenames at root/non-structured paths - SHOULD warn
124+
const deniedFiles = [
125+
'NOTES.md',
126+
'TODO.md',
127+
'SCRATCH.md',
128+
'TEMP.md',
129+
'DRAFT.txt',
130+
'BRAINSTORM.md',
131+
'SPIKE.md',
132+
'DEBUG.md',
133+
'WIP.txt',
134+
'src/NOTES.md',
135+
'lib/TODO.txt',
136+
];
137+
for (const file of deniedFiles) {
138+
(test(`warns on ad-hoc denylist file: ${file}`, () => {
103139
const { code, stderr } = runScript({ tool_input: { file_path: file } });
104140
assert.strictEqual(code, 0, 'should still exit 0 (warn only)');
105141
assert.ok(stderr.includes('WARNING'), `expected warning in stderr for ${file}, got: ${stderr}`);
106142
assert.ok(stderr.includes(file), `expected file path in stderr for ${file}`);
107143
}) ? passed++ : failed++);
108144
}
109145

110-
// 6. Invalid/empty input - passes through without error
146+
// 7. Windows backslash paths - normalized correctly
147+
(test('allows ad-hoc name in structured dir with backslash path', () => {
148+
const { code, stderr } = runScript({ tool_input: { file_path: 'docs\\specs\\NOTES.md' } });
149+
assert.strictEqual(code, 0);
150+
assert.strictEqual(stderr, '', 'expected no warning for structured dir with backslash');
151+
}) ? passed++ : failed++);
152+
153+
(test('warns on ad-hoc name with backslash in non-structured dir', () => {
154+
const { code, stderr } = runScript({ tool_input: { file_path: 'src\\SCRATCH.md' } });
155+
assert.strictEqual(code, 0, 'should still exit 0');
156+
assert.ok(stderr.includes('WARNING'), 'expected warning for non-structured backslash path');
157+
}) ? passed++ : failed++);
158+
159+
// 8. Invalid/empty input - passes through without error
111160
(test('handles empty object input without error', () => {
112161
const { code, stderr } = runScript({});
113162
assert.strictEqual(code, 0);
@@ -126,15 +175,27 @@ function runTests() {
126175
assert.strictEqual(stderr, '', `expected no warning for empty file_path, got: ${stderr}`);
127176
}) ? passed++ : failed++);
128177

129-
// 7. Stdout always contains the original input (pass-through)
178+
// 9. Malformed input - passes through without error
179+
(test('handles non-JSON input without error', () => {
180+
const result = spawnSync('node', [script], {
181+
encoding: 'utf8',
182+
input: 'not-json',
183+
timeout: 10000,
184+
});
185+
assert.strictEqual(result.status || 0, 0);
186+
assert.strictEqual(result.stderr || '', '');
187+
assert.strictEqual(result.stdout, 'not-json');
188+
}) ? passed++ : failed++);
189+
190+
// 10. Stdout always contains the original input (pass-through)
130191
(test('passes through input to stdout for allowed file', () => {
131192
const input = { tool_input: { file_path: 'README.md' } };
132193
const { stdout } = runScript(input);
133194
assert.strictEqual(stdout, JSON.stringify(input));
134195
}) ? passed++ : failed++);
135196

136197
(test('passes through input to stdout for warned file', () => {
137-
const input = { tool_input: { file_path: 'random-notes.md' } };
198+
const input = { tool_input: { file_path: 'TODO.md' } };
138199
const { stdout } = runScript(input);
139200
assert.strictEqual(stdout, JSON.stringify(input));
140201
}) ? passed++ : failed++);

0 commit comments

Comments
 (0)