diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ceb668c..007835a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -4,12 +4,12 @@ "name": "NovusEdge", "url": "https://github.com/NovusEdge" }, - "description": "Blocks agent turns that add duplicated code.", + "description": "Warns when agent turns add duplicated code.", "plugins": [ { "name": "drygate", "source": "./", - "description": "Blocks the end of a turn that added duplicated code, using jscpd, and gives the agent jscpd's MCP tools to check for existing code first.", + "description": "Warns at the end of a turn that added duplicated code, using jscpd, and gives the agent jscpd's MCP tools to check for existing code first.", "keywords": [ "dry", "duplication", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index ff538cc..add9e29 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "drygate", "displayName": "drygate", - "version": "0.1.0", - "description": "Blocks the end of a turn that added duplicated code, using jscpd, and gives the agent jscpd's MCP tools to check for existing code first.", + "version": "0.2.0", + "description": "Warns at the end of a turn that added duplicated code, using jscpd, and gives the agent jscpd's MCP tools to check for existing code first.", "author": { "name": "NovusEdge" }, diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 84af68a..4b8ee19 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "drygate", - "version": "0.1.0", - "description": "Blocks the end of a turn that added duplicated code, using jscpd.", + "version": "0.2.0", + "description": "Warns at the end of a turn that added duplicated code, using jscpd.", "author": { "name": "NovusEdge", "url": "https://github.com/NovusEdge" @@ -21,7 +21,7 @@ "hooks": "./hooks/hooks.json", "interface": { "displayName": "drygate", - "shortDescription": "Blocks agent turns that add duplicated code.", + "shortDescription": "Warns when agent turns add duplicated code.", "developerName": "NovusEdge", "category": "Coding", "websiteURL": "https://github.com/NovusEdge/drygate" diff --git a/AGENTS.md b/AGENTS.md index 7aeba9e..4309708 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,15 @@ # drygate - `hooks/drygate.js` is the one hook for Claude Code and Codex. Both send the same Stop and - SessionStart JSON and read `{"decision":"block"}` from stdout. Codex has no + SessionStart JSON and read `systemMessage` from stdout. Codex has no `CLAUDE_PROJECT_DIR`, so the hook falls back to the stdin `cwd`. -- The hook must exit 0 on every path and report failures as `systemMessage`. Exit 2 from a +- The Stop hook warns and never returns `{"decision":"block"}`. All Stop hooks share one + `stop_hook_active` flag, so a drygate block let flocc's Stop hook end a turn its agent + had not finished. +- The hook must exit 0 on every path and report everything as `systemMessage`. Exit 2 from a Stop hook blocks the turn, and a crash shows a hook error on every turn in every repo that enables the plugin. -- `VERSION` in `hooks/jscpd.js` pins the jscpd that drygate installs. The blocking rule reads +- `VERSION` in `hooks/jscpd.js` pins the jscpd that drygate installs. The warning rule reads jscpd's JSON report (`fragment`, file names), so bump it only with the tests passing against the new version. - Options reach jscpd through a temp config file from `config()`, never `--ignore`: jscpd diff --git a/README.md b/README.md index df239d4..d2a7a2b 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,11 @@ drygate keeps coding agents from adding duplicated code. It has three parts: -- **A stop gate.** When the agent finishes a turn, drygate runs [jscpd](https://github.com/kucherenko/jscpd) - over the repository. If the session added a block that repeats code elsewhere, the turn - does not end: the agent gets the list of copies and has to remove them first. +- **A stop check.** When the agent finishes a turn, drygate runs [jscpd](https://github.com/kucherenko/jscpd) + over the repository. If the session added a block that repeats code elsewhere, drygate + shows the user the list of copies. It warns and never blocks the turn: Claude Code shares + one `stop_hook_active` flag between all Stop hooks, so a block from drygate would use up + the one refusal another Stop hook relies on. - **A sweep**, `/drygate:sweep`, for code jscpd cannot see: functions that reimplement the standard library or an installed dependency, and wrappers that add nothing. Haiku scouts read the code in parallel batches and Sonnet verifies every candidate before it is @@ -12,7 +14,7 @@ drygate keeps coding agents from adding duplicated code. It has three parts: - **jscpd's MCP server**, so the agent can check a draft against the codebase before it writes it (Claude Code only). -It works in Claude Code and Codex. It needs Node 20 or later and git. The gate does nothing +It works in Claude Code and Codex. It needs Node 20 or later and git. The check does nothing outside a git repository. ## Install @@ -49,22 +51,21 @@ once per machine, in the background; until that finishes, stops are not checked A failed install, for example offline or behind a proxy npm cannot reach, is retried after 10 minutes. To use a specific binary, set `DRYGATE_JSCPD` to its path. -## How the gate decides +## How the check decides At session start, drygate scans the working tree in a background process and counts the clones by the pair of files they join and by the code they repeat. At each stop it scans -again and blocks on a clone when both its file pair and its code are more common than in -the snapshot. After a stop that passes, the snapshot moves forward to the current tree. - -- Duplication that was already there, committed or not, never blocks. Editing an old clone, - renaming its file or moving it does not block either. -- A third copy of code that was already duplicated blocks. -- A copy the agent commits before it stops still blocks. drygate compares against the +again and warns on a clone when both its file pair and its code are more common than in +the snapshot. After every checked stop, the snapshot moves forward to the current tree, so +each copy is reported once. + +- Duplication that was already there, committed or not, is never reported. Editing an old + clone, renaming its file or moving it is not reported either. +- A third copy of code that was already duplicated is reported. +- A copy the agent commits before it stops is still reported. drygate compares against the snapshot, not against `HEAD`. - A copy with its local names changed still counts (renamed-identifier matching). -- After one block, the next stop is let through, the user sees what is left, and those - copies are accepted from then on. -- On resume, drygate takes a new snapshot, so commits pulled in between do not block. +- On resume, drygate takes a new snapshot, so commits pulled in between are not reported. Uncommitted changes since the last check stay out of it: a turn the user interrupted had no stop, so they are still checked. - A stop with no file changed since the last check skips the scan. @@ -85,7 +86,7 @@ renamed-copy detection and any other jscpd option. drygate still adds worktrees, submodules and nested clones to its `ignore` list. See jscpd's [options](https://github.com/kucherenko/jscpd#options). -To keep a deliberate duplicate, wrap it in comments the gate skips: +To keep a deliberate duplicate out of the report, wrap it in comments the check skips: ```js // jscpd:ignore-start @@ -93,17 +94,20 @@ To keep a deliberate duplicate, wrap it in comments the gate skips: // jscpd:ignore-end ``` -`DRYGATE_DISABLE=1` in the environment turns the gate off. +`DRYGATE_DISABLE=1` in the environment turns the check off. ## Limits -- The gate finds copies of text: exact copies, renamed copies and near-copies. It does not +- The warning goes to the user, not to the agent: a Stop hook cannot add to the model's + context without blocking. In an unattended session nobody sees it; run + `/drygate:sweep` or review the diff instead. +- The check finds copies of text: exact copies, renamed copies and near-copies. It does not find two functions that do the same thing written differently. The sweep covers part of that: code the standard library or a dependency already provides. - Removing one clone and adding a different one between the same two files, in the same turn, is not caught: the counts do not change. - A clone that existed before the session, in a file the agent edits before the start - snapshot finishes, counts as new and blocks once. The snapshot takes a few seconds at most, + snapshot finishes, counts as new and is reported once. The snapshot takes a few seconds at most, and in an interactive session the first edit comes after the user's first prompt. - The sweep reads every file in scope with a model. It reports the batch and line counts first and asks before sweeping more than 300,000 lines. diff --git a/hooks/drygate.js b/hooks/drygate.js index f498314..3ccd2e9 100644 --- a/hooks/drygate.js +++ b/hooks/drygate.js @@ -1,16 +1,21 @@ #!/usr/bin/env node -// Blocks the end of a turn that added duplicated code. Claude Code and Codex +// Warns at the end of a turn that added duplicated code. Claude Code and Codex // both run it with the event JSON on stdin and read a decision from stdout. // +// It warns instead of blocking because every Stop hook shares one +// stop_hook_active flag: a block from drygate used up the one refusal another +// plugin's Stop hook relies on, such as a harness that refuses to end a turn +// before its agent has reported. +// // SessionStart snapshots the clones in the working tree. Stop scans again and -// blocks on clones the session added, then moves the snapshot forward. The +// warns on clones the session added, then moves the snapshot forward. The // snapshot is of the working tree, not of a git ref: jscpd --changed rebuilds // its baseline when HEAD moves, so a copy the agent committed before stopping // went unreported. // -// Always exits 0 and reports failures as systemMessage. Exit 2 from a Stop -// hook blocks the turn, and a crash shows an error on every turn in every repo -// that enables the plugin. +// Always exits 0 and reports through systemMessage. Exit 2 from a Stop hook +// blocks the turn, and a crash shows an error on every turn in every repo that +// enables the plugin. const crypto = require('crypto'); const fs = require('fs'); @@ -26,11 +31,6 @@ const PENDING_TTL = 10 * 60 * 1000; const PENDING_WAIT = 60 * 1000; const STOP_SCAN_TIMEOUT = 50 * 1000; -const MESSAGE = - 'Remove each duplicate before you finish: call or import the existing code, or move the ' + - 'shared part into one function that both places use. If the user wants a duplicate kept, ' + - 'wrap it in jscpd:ignore-start and jscpd:ignore-end comments and say so in your reply.'; - function scan(root, { allowInstall, timeout, ignore = [] }) { const cmd = jscpd.command({ allowInstall }); if (!cmd) return null; @@ -223,19 +223,12 @@ function stop(input, root, state) { } const before = JSON.parse(fs.readFileSync(state.snapshot, 'utf8')); const found = added(before, clones); - // The snapshot moves forward after a pass, and after a second stop lets - // remaining duplicates through: those were reported once, and blocking on - // them again every turn would make the user turn the gate off. - if (!found.length || input.stop_hook_active) { - save(state.snapshot, tally(clones)); - fs.writeFileSync(state.passed, fp); - } + // The snapshot always moves forward, so each duplicate is reported once. + save(state.snapshot, tally(clones)); + fs.writeFileSync(state.passed, fp); if (!found.length) return null; const list = found.map((c) => describe(root, c)).join('\n'); - if (input.stop_hook_active) { - return { systemMessage: `drygate: duplicated code kept this turn:\n${list}` }; - } - return { decision: 'block', reason: `drygate: this session added duplicated code.\n${list}\n\n${MESSAGE}` }; + return { systemMessage: `drygate: this session added duplicated code:\n${list}` }; } function stateFor(input, root) { diff --git a/tests/drygate.test.js b/tests/drygate.test.js index 9764fec..94f2436 100644 --- a/tests/drygate.test.js +++ b/tests/drygate.test.js @@ -110,6 +110,7 @@ function session(dir, opts = {}) { } const BROKEN = { DRYGATE_JSCPD: path.join(os.tmpdir(), 'no-such-jscpd') }; +const WARN = /drygate: this session added duplicated code/; test('a turn that adds no duplication stops normally', () => { const { dir } = repo({ 'src/a.js': PARSER }); @@ -119,14 +120,15 @@ test('a turn that adds no duplication stops normally', () => { assert.equal(s.stop(), null); }); -test('a new copy of existing code blocks the stop and names both files', () => { +test('a new copy of existing code warns without blocking and names both files', () => { const { dir } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start(); write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); const out = s.stop(); - assert.equal(out.decision, 'block'); - assert.match(out.reason, /src\/b\.js:1-13 repeats src\/a\.js:1-13/); + assert.equal(out.decision, undefined); + assert.match(out.systemMessage, WARN); + assert.match(out.systemMessage, /src\/b\.js:1-13 repeats src\/a\.js:1-13/); }); test('the file written later is named as the copy, whichever side jscpd lists first', () => { @@ -134,39 +136,39 @@ test('the file written later is named as the copy, whichever side jscpd lists fi const s = session(dir); s.start(); write(dir, { 'src/a.js': PARSER.replace('parseUser', 'parseAdmin') }); - assert.match(s.stop().reason, /src\/a\.js:1-13 repeats src\/z\.js:1-13/); + assert.match(s.stop().systemMessage, /src\/a\.js:1-13 repeats src\/z\.js:1-13/); }); -test('a copy with renamed locals still blocks', () => { +test('a copy with renamed locals still warns', () => { const { dir } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start(); const renamed = PARSER.replace(/parts/g, 'fields').replace(/email/g, 'mail').replace('parseUser', 'parseGuest'); write(dir, { 'src/c.js': renamed }); - assert.equal(s.stop()?.decision, 'block'); + assert.match(s.stop()?.systemMessage ?? '', WARN); }); -test('a copy committed before the stop still blocks', () => { +test('a copy committed before the stop still warns', () => { const { dir, git } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start(); write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); git('add', '-A'); git('commit', '-qm', 'copy'); - assert.equal(s.stop()?.decision, 'block'); + assert.match(s.stop()?.systemMessage ?? '', WARN); }); -test('a copy committed while the background snapshot runs still blocks', () => { +test('a copy committed while the background snapshot runs still warns', () => { const { dir, git } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start('startup', { wait: false }); write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); git('add', '-A'); git('commit', '-qm', 'copy'); - assert.equal(s.stop()?.decision, 'block'); + assert.match(s.stop()?.systemMessage ?? '', WARN); }); -test('editing a clone that existed at session start does not block', () => { +test('editing a clone that existed at session start does not warn', () => { const { dir } = repo({ 'src/a.js': PARSER, 'src/legacy.js': PARSER.replace('parseUser', 'parseLegacy') }); const s = session(dir); s.start(); @@ -175,7 +177,7 @@ test('editing a clone that existed at session start does not block', () => { assert.equal(s.stop(), null); }); -test('a second copy between files that already shared one blocks', () => { +test('a second copy between files that already shared one warns', () => { const { dir } = repo({ 'src/a.js': PARSER + '\n' + OTHER, 'src/legacy.js': PARSER.replace('parseUser', 'parseLegacy') }); const s = session(dir); s.start(); @@ -183,10 +185,10 @@ test('a second copy between files that already shared one blocks', () => { write(dir, { 'src/a.js': PARSER + '\n' + big }); const legacy = fs.readFileSync(path.join(dir, 'src/legacy.js'), 'utf8'); write(dir, { 'src/legacy.js': legacy + '\n' + big.replace('sum', 'total') }); - assert.equal(s.stop()?.decision, 'block'); + assert.match(s.stop()?.systemMessage ?? '', WARN); }); -test('renaming a file that held old duplication does not block', () => { +test('renaming a file that held old duplication does not warn', () => { const { dir, git } = repo({ 'src/a.js': PARSER, 'src/legacy.js': PARSER.replace('parseUser', 'parseLegacy') }); const s = session(dir); s.start(); @@ -194,28 +196,28 @@ test('renaming a file that held old duplication does not block', () => { assert.equal(s.stop(), null); }); -test('a third copy of code that was already duplicated blocks', () => { +test('a third copy of code that was already duplicated warns', () => { const { dir } = repo({ 'src/a.js': PARSER, 'src/legacy.js': PARSER.replace('parseUser', 'parseLegacy') }); const s = session(dir); s.start(); write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); const out = s.stop(); - assert.equal(out?.decision, 'block'); - assert.match(out.reason, /src\/b\.js/); + assert.match(out?.systemMessage ?? '', WARN); + assert.match(out.systemMessage, /src\/b\.js/); }); -test('a duplicate let through after a block does not block later turns', () => { +test('a duplicate is reported once, not on later turns', () => { const { dir } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start(); write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); - assert.equal(s.stop().decision, 'block'); - assert.ok(s.stop(true).systemMessage); + assert.match(s.stop().systemMessage, WARN); + assert.equal(s.stop(), null); write(dir, { 'src/sum.js': OTHER }); assert.equal(s.stop(), null); }); -test('resume takes a new snapshot, so code pulled in between does not block', () => { +test('resume takes a new snapshot, so code pulled in between does not warn', () => { const { dir, git } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start(); @@ -252,7 +254,7 @@ test('input that is not JSON makes the hook do nothing, with exit 0', () => { assert.equal(r.stdout, ''); }); -test("the user's uncommitted duplication from before the session does not block", () => { +test("the user's uncommitted duplication from before the session does not warn", () => { const { dir } = repo({ 'src/a.js': PARSER }); write(dir, { 'src/wip.js': PARSER.replace('parseUser', 'parseWip') }); const s = session(dir); @@ -260,7 +262,7 @@ test("the user's uncommitted duplication from before the session does not block" assert.equal(s.stop(), null); }); -test('after one block, a second stop is allowed with a message to the user', () => { +test('a stop continued by another Stop hook still warns and never blocks', () => { const { dir } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start(); @@ -270,13 +272,13 @@ test('after one block, a second stop is allowed with a message to the user', () assert.match(out.systemMessage, /src\/b\.js/); }); -test('a copy from an interrupted turn, which had no stop, still blocks after resume', () => { +test('a copy from an interrupted turn, which had no stop, still warns after resume', () => { const { dir } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start('startup'); write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); s.start('resume'); - assert.equal(s.stop()?.decision, 'block'); + assert.match(s.stop()?.systemMessage ?? '', WARN); }); test('a stop with no baseline takes one and lets the turn end', () => { @@ -285,7 +287,7 @@ test('a stop with no baseline takes one and lets the turn end', () => { const s = session(dir); assert.equal(s.stop(), null); write(dir, { 'src/c.js': PARSER.replace('parseUser', 'parseGuest') }); - assert.equal(s.stop()?.decision, 'block'); + assert.match(s.stop()?.systemMessage ?? '', WARN); }); test("the repo's own .jscpd.json replaces drygate's defaults", () => { @@ -296,7 +298,7 @@ test("the repo's own .jscpd.json replaces drygate's defaults", () => { assert.equal(s.stop(), null); }); -test('a git worktree created inside the repo during the session does not block', () => { +test('a git worktree created inside the repo during the session does not warn', () => { const { dir, git } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start(); @@ -351,21 +353,12 @@ test('a stop with no file changed since the last clean check does not scan', () assert.match(s.stop(false, BROKEN).systemMessage, /drygate/); }); -test('a stop right after a block scans again even with no change', () => { - const { dir } = repo({ 'src/a.js': PARSER }); - const s = session(dir); - s.start(); - write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); - assert.equal(s.stop().decision, 'block'); - assert.match(s.stop(true).systemMessage, /src\/b\.js/); -}); - test('a file written while the background snapshot runs still counts as new', () => { const { dir } = repo({ 'src/a.js': PARSER }); const s = session(dir); s.start('startup', { wait: false }); write(dir, { 'src/b.js': PARSER.replace('parseUser', 'parseAdmin') }); - assert.equal(s.stop()?.decision, 'block'); + assert.match(s.stop()?.systemMessage ?? '', WARN); }); test('DRYGATE_DISABLE=1 turns the hook off', () => {