mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-06-30 19:00:57 +08:00
88f6894267
* fix(hooks): guard doc-file-warning stdin listeners behind require.main doc-file-warning.js registered process.stdin data/end listeners at module scope while also exporting run(). run-with-flags.js require()s any hook that exports run() for its in-process fast path, so importing this hook attached stray stdin listeners to the dispatcher process, corrupting the PreToolUse stdout JSON contract. This is the exact failure run-with-flags' own SAFETY comment warns about, and 24 sibling hooks already guard against it. - Move the stdin entrypoint into main() and gate it behind require.main === module - pre-write-doc-warn.js now calls main() explicitly instead of relying on the import side effect - Add regression tests: require() attaches no stdin listeners, run()/main() stay exported, and the pre-write-doc-warn shim still warns * docs(hooks): add JSDoc for doc-file-warning main() entrypoint Satisfies the docstring-coverage pre-merge check; documents the stdin entrypoint and why it must not run on require().
109 lines
3.4 KiB
JavaScript
109 lines
3.4 KiB
JavaScript
#!/usr/bin/env node
|
|
/**
|
|
* Doc file warning hook (PreToolUse - Write)
|
|
*
|
|
* Uses a denylist approach: only warn on known ad-hoc documentation
|
|
* filenames (NOTES, TODO, SCRATCH, etc.) outside structured directories.
|
|
* This avoids false positives for legitimate markdown-heavy workflows
|
|
* (specs, ADRs, command definitions, skill files, etc.).
|
|
*
|
|
* Policy ported from the intent of PR #962 into the current hook architecture.
|
|
* Exit code 0 always (warns only, never blocks).
|
|
*/
|
|
|
|
'use strict';
|
|
|
|
const path = require('path');
|
|
const { buildPreToolUseAdditionalContext } = require('./pretooluse-visible-output');
|
|
|
|
const MAX_STDIN = 1024 * 1024;
|
|
|
|
// Known ad-hoc filenames that indicate impulse/scratch files (case-sensitive, uppercase only)
|
|
const ADHOC_FILENAMES = /^(NOTES|TODO|SCRATCH|TEMP|DRAFT|BRAINSTORM|SPIKE|DEBUG|WIP)\.(md|txt)$/;
|
|
|
|
// Structured directories where even ad-hoc names are intentional
|
|
const STRUCTURED_DIRS = /(^|\/)(docs|\.claude|\.github|commands|skills|benchmarks|templates|\.history|memory)\//;
|
|
|
|
function isSuspiciousDocPath(filePath) {
|
|
const normalized = filePath.replace(/\\/g, '/');
|
|
const basename = path.basename(normalized);
|
|
|
|
// Only inspect .md and .txt files (case-sensitive, consistent with ADHOC_FILENAMES)
|
|
if (!/\.(md|txt)$/.test(basename)) return false;
|
|
|
|
// Only flag known ad-hoc filenames
|
|
if (!ADHOC_FILENAMES.test(basename)) return false;
|
|
|
|
// Allow ad-hoc names inside structured directories (intentional usage)
|
|
if (STRUCTURED_DIRS.test(normalized)) return false;
|
|
|
|
return true;
|
|
}
|
|
|
|
/**
|
|
* Exportable run() for in-process execution via run-with-flags.js.
|
|
* Avoids the ~50-100ms spawnSync overhead when available.
|
|
*/
|
|
function run(inputOrRaw, _options = {}) {
|
|
let input;
|
|
try {
|
|
input = typeof inputOrRaw === 'string'
|
|
? (inputOrRaw.trim() ? JSON.parse(inputOrRaw) : {})
|
|
: (inputOrRaw || {});
|
|
} catch {
|
|
return { exitCode: 0 };
|
|
}
|
|
const filePath = String(input?.tool_input?.file_path || '');
|
|
|
|
if (filePath && isSuspiciousDocPath(filePath)) {
|
|
return {
|
|
exitCode: 0,
|
|
additionalContext: [
|
|
'[Hook] WARNING: Ad-hoc documentation filename detected',
|
|
`[Hook] File: ${filePath}`,
|
|
'[Hook] Consider using a structured path (e.g. docs/, .claude/, skills/, .github/, benchmarks/, templates/)',
|
|
],
|
|
};
|
|
}
|
|
|
|
return { exitCode: 0 };
|
|
}
|
|
|
|
/**
|
|
* Stdin entrypoint for direct/spawnSync execution: reads the hook payload from
|
|
* stdin (capped at MAX_STDIN), runs the policy, and writes the PreToolUse result
|
|
* to stdout. Must only run when invoked directly, never on require(), so the
|
|
* stdin listeners are not leaked into a parent that loads this hook in-process.
|
|
*/
|
|
function main() {
|
|
let data = '';
|
|
process.stdin.setEncoding('utf8');
|
|
process.stdin.on('data', c => {
|
|
if (data.length < MAX_STDIN) {
|
|
const remaining = MAX_STDIN - data.length;
|
|
data += c.substring(0, remaining);
|
|
}
|
|
});
|
|
|
|
process.stdin.on('end', () => {
|
|
const result = run(data);
|
|
|
|
if (result.stderr) {
|
|
process.stderr.write(result.stderr + '\n');
|
|
}
|
|
|
|
if (Object.prototype.hasOwnProperty.call(result, 'additionalContext')) {
|
|
process.stdout.write(buildPreToolUseAdditionalContext(result.additionalContext));
|
|
} else {
|
|
process.stdout.write(data);
|
|
}
|
|
});
|
|
}
|
|
|
|
module.exports = { run, main };
|
|
|
|
// Stdin fallback for spawnSync execution — only when invoked directly, not via require()
|
|
if (require.main === module) {
|
|
main();
|
|
}
|