dry-lint 1.6.0__tar.gz

dry_lint-1.6.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.coverage
+.pytest_cache/
+.ruff_cache/
+
+# Documentation build
+.venv-docs/
+site/

dry_lint-1.6.0/.pre-commit-hooks.yaml

@@ -0,0 +1,32 @@
+# For the coding agent committing the change: it checks each finding itself, so the hook reports at the agent preset's
+# low threshold. `args: [--preset, auto]` puts a person's precision-first judging back.
+- id: dry-lint
+  name: dry-lint
+  description: Flag staged function duplication and model consolidation candidates. Use --no-models to opt out of models.
+  entry: dry-lint check --staged --preset agent --env-file .env
+  language: python
+  additional_dependencies: ["anthropic>=1.0", "python-dotenv>=1,<2"]  # the `hooks` extra: Claude judges, and .env
+  types_or: [python, javascript, jsx, ts, tsx]
+  stages: [pre-commit]
+  pass_filenames: false
+  require_serial: true
+# What the hook above saw fixed or dismissed before the commit, written into the commit's message as trailers so
+# the pull request's comment counts it. Install its stage once: `pre-commit install -t prepare-commit-msg`.
+- id: dry-lint-schema-policy
+  name: dry-lint schema ownership
+  description: Enforce explicitly configured Python structured-output schema boundaries.
+  entry: dry-lint schema-check --staged
+  language: python
+  additional_dependencies: ["anthropic>=1.0", "python-dotenv>=1,<2"]  # share the other hooks' environment
+  pass_filenames: false
+  always_run: true
+  stages: [pre-commit]
+
+- id: dry-lint-trailers
+  name: dry-lint trailers
+  description: Record in the commit message the duplicates dry-lint's hook kept out before the commit.
+  entry: dry-lint trailers
+  language: python
+  additional_dependencies: ["anthropic>=1.0", "python-dotenv>=1,<2"]  # the same environment as the hook above
+  stages: [prepare-commit-msg]
+  always_run: true

dry_lint-1.6.0/AGENTS.md

@@ -0,0 +1,26 @@
+# Working on dry-lint
+
+Follow [CONTRIBUTING.md](CONTRIBUTING.md) to set up, lint and test. Read [docs/design.md](docs/design.md) before
+changing the pipeline, a file format or the store, and [docs/plugins.md](docs/plugins.md) before adding a plugin.
+
+- **Adopters bring their own keys, always.** dry-lint is open source and never ships, holds, proxies or pays for an
+  API key, a model, or judge execution. Every judge runs on credentials the adopting repository passes in (action
+  inputs, its own environment), at its own cost; with none, dry-lint judges nothing and only lists look-alikes. No
+  input defaults to a credential other than the run's own `github.token`, and no code path calls a model on an
+  account or endpoint dry-lint operates. The only service dry-lint runs is the opt-out counter, which receives
+  anonymous counts, never credentials or code. No change that breaks this is accepted, whatever it would enable;
+  `tests/test_adopter_keys.py` guards it. See [docs/design.md](docs/design.md#adopters-bring-their-own-keys).
+- The pipeline, the file formats, the reuse rules and the reports are core; extractors, comparers, judges and store
+  backends are plugins. A new way to compare or judge is a plugin, not a branch in core.
+- Keep the detector stateless and model-free, and the judge separate. Anything slow belongs behind the verdict
+  store. Change a file format only with a `schema` bump.
+- A stored verdict may be reused only when the answer cannot have changed. Any rule that reuses more verdicts needs
+  an argument, and a test, that the answer still holds.
+- Decisions made by people go in code (`# dry-lint: distinct-from`) or in configuration (`patterns`), never in the
+  verdict store.
+- dry-lint should pass on its own code: run `uv run dry-lint check` before you push.
+
+## GitHub Actions versions
+
+- ALWAYS use published major-version tags for established GitHub Actions, for example `actions/checkout@v7` and `actions/upload-artifact@v7`, so compatible fixes arrive without per-commit maintenance. NEVER replace those tags with commit hashes unless the user explicitly requests that exact exception. If a publisher has no major-version tag, use its published release tag rather than inventing a ref or substituting a hash.
+- ALWAYS use the `v1` major-version tag for dry-lint: `gigaverse-app/dry-lint@v1` for Actions, `@v1` for CLI installs, and `rev: v1` for pre-commit hooks. Do not use commit SHAs or minor/patch release pins. Apply the same ref in workflow examples and adoption instructions.

dry_lint-1.6.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+Install Python 3.11+ and [uv](https://docs.astral.sh/uv/), then:
+
+```bash
+uv sync --locked
+uvx pre-commit install
+uv run ruff check .
+uv run ruff format .
+uv run pytest -q --cov
+uv build
+```
+
+When changing the action installer, also run `uv run python scripts/test_action_install.py` with Bash and uv
+on PATH. It performs real installs in temporary Python and Node repositories; CI runs it on Linux, macOS and
+Windows. The ordinary pytest suite stays offline.
+
+- **Tests use real objects.** A temporary git repository stands in for a pull request; judges run as real
+  subprocesses, or against `httpx.MockTransport`. New code needs full coverage, and a bug fix needs a test of the
+  invariant it broke.
+- **Thresholds and judge wording come from measurements.** If you change them, re-measure and update
+  [docs/benchmark.md](docs/benchmark.md). If you change the Jev questions, bump `PROMPT_VERSION`.
+- **Assets.** Regenerate them from `docs/assets/lint.png` with `uv run --with pillow python scripts/make_assets.py`, then
+  `uv run --with playwright==1.58.0 python scripts/render_png.py`.

dry_lint-1.6.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

dry_lint-1.6.0/PKG-INFO

@@ -0,0 +1,349 @@
+Metadata-Version: 2.5
+Name: dry-lint
+Version: 1.6.0
+Summary: Find code that re-implements what your codebase already does, judge it, and say so on the pull request
+Project-URL: Homepage, https://github.com/gigaverse-app/dry-lint
+Project-URL: Documentation, https://github.com/gigaverse-app/dry-lint/tree/main/docs
+Project-URL: Repository, https://github.com/gigaverse-app/dry-lint
+Project-URL: Issues, https://github.com/gigaverse-app/dry-lint/issues
+Author: Gigaverse
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: code-duplication,code-review,dry,duplication,github-actions,linter,llm,pre-commit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: tree-sitter-typescript<0.24,>=0.23
+Requires-Dist: tree-sitter<0.26,>=0.25
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=1.0; extra == 'anthropic'
+Provides-Extra: cpu-embedding
+Requires-Dist: numpy<3,>=2.2; extra == 'cpu-embedding'
+Requires-Dist: onnxruntime<1.32,>=1.31.1; extra == 'cpu-embedding'
+Requires-Dist: tokenizers<0.24,>=0.23.3; extra == 'cpu-embedding'
+Provides-Extra: hooks
+Requires-Dist: anthropic>=1.0; extra == 'hooks'
+Requires-Dist: python-dotenv<2,>=1; extra == 'hooks'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.35; extra == 's3'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/readme-hero-dark.svg">
+    <img alt="dry-lint: one concept, one implementation" src="docs/assets/readme-hero-light.svg" width="100%">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://github.com/gigaverse-app/dry-lint/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/gigaverse-app/dry-lint/ci.yml?branch=main&label=CI&logo=githubactions&logoColor=white&labelColor=24292F"></a>
+  <a href="#the-counter"><img alt="Duplicates kept out" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fdry-lint-counter.gigaverse-oss.workers.dev%2Fv1%2Fbadge%3Fmetric%3Dkept-out"></a>
+  <a href="pyproject.toml"><img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-7E4FC9?logo=python&logoColor=white&labelColor=24292F"></a>
+  <a href="docs/typescript.md"><img alt="TypeScript" src="https://img.shields.io/badge/typescript-supported-7E4FC9?logo=typescript&logoColor=white&labelColor=24292F"></a>
+  <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/license-Apache--2.0-7E4FC9?labelColor=24292F"></a>
+  <a href="https://dry-lint.readthedocs.io/en/latest/"><img alt="Documentation" src="https://readthedocs.org/projects/dry-lint/badge/?version=latest"></a>
+</p>
+
+<p align="center"><a href="https://dry-lint.readthedocs.io/en/latest/">Read the documentation</a> · <a href="https://dry-lint.readthedocs.io/en/latest/ecosystem/">Related tools</a></p>
+
+Coding agents rarely copy and paste. They write *new* code for a job the codebase already does: a second
+`truncate`, another pagination loop, a fresh Mongo query helper, each slightly different. Copy-paste detectors
+(pylint's `duplicate-code`, jscpd) look for repeated lines, so they miss this. Every rewrite is also a chance to
+drift: one version rounds, the other truncates, and callers get different answers to the same question.
+
+dry-lint finds functions in a pull request that look like they re-implement something that already exists. A
+judge decides whether each pair really is one concept, and the result goes back as PR annotations and one comment
+([see one](docs/comment-preview.md)):
+
+```text
+src/widgets/caption.py:1: preview_caption_text looks like src/text.py::shorten_text (drifted)
+    judge 0.91; the two already behave differently; call the existing function;
+    similarity 0.71; if they are different concepts, add
+    `# dry-lint: distinct-from src/text.py::shorten_text`
+```
+
+**You bring your own keys.** dry-lint never provides API keys, models or judge execution: judges run on the
+credentials your repository passes in, at your cost, and without any it only lists look-alikes
+([design](docs/design.md#adopters-bring-their-own-keys)).
+
+<a href="#the-counter">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://dry-lint-counter.gigaverse-oss.workers.dev/v1/sign.svg?theme=dark">
+    <img alt="Duplicate functions dry-lint has kept out of codebases" src="https://dry-lint-counter.gigaverse-oss.workers.dev/v1/sign.svg" width="100%">
+  </picture>
+</a>
+
+## Quick start
+
+Python, TypeScript and TSX work out of the box. TypeScript repositories need no Python project, `bun install`,
+Node or build step: dry-lint installs its own tools and parses source without executing your code
+([TypeScript and Bun](docs/typescript.md) covers monorepos).
+
+### Try it locally, without an API key
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/), open a terminal in your Git repository,
+and run:
+
+```bash
+uvx --no-config --python 3.13 --from git+https://github.com/gigaverse-app/dry-lint dry-lint scan --judge none --limit 30
+```
+
+uv downloads Python and runs dry-lint in its own environment, so nothing is added to your project. This lists
+look-alikes without calling a model or failing on findings. To inspect just your branch, replace
+`scan --judge none --limit 30` with `check --judge none --base origin/main` (use your default branch's name).
+
+For a permanent `dry-lint` command, then open a new terminal:
+
+```bash
+uv tool install --no-config --python 3.13 git+https://github.com/gigaverse-app/dry-lint
+uv tool update-shell
+```
+
+### Add it to GitHub Actions
+
+Save this as `.github/workflows/dry-lint.yml`. It works without a secret; add a `TYPESAFE_AI_API_KEY`
+repository secret when you want judged findings.
+
+```yaml
+name: dry-lint
+on: [pull_request]
+permissions:
+  contents: read
+  pull-requests: write
+concurrency:
+  group: dry-lint-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+jobs:
+  dry-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 1
+      - uses: gigaverse-app/dry-lint@v1
+        with:
+          typesafe-api-key: ${{ secrets.TYPESAFE_AI_API_KEY }}
+```
+
+The action installs its own Python and dependencies; your project's Python version, uv configuration and
+virtual environment do not change, and no `setup-python`, `pip install` or build step is needed. It annotates
+the changed functions, keeps one sticky PR comment up to date and caches verdicts between runs. The comment
+links both functions at the analyzed commit, shows the review workload, and folds evidence and pair-specific
+suppression instructions under each summary. A clean pull request gets a green sticky with what was checked
+(`comment-on-clean: "false"` to opt out), and every sticky keeps a running account of what each push cost and
+each duplicate kept out ([the ledger](docs/github-action.md#the-ledger)).
+
+A reported duplicate fails the check at the preset's threshold (98% of them are real duplicates with
+`jev+opus`); `fail-at` raises or lowers it, and the `dry-lint: override` label lets one through. That precision
+is for people. A coding agent can check findings itself, so for agents a cheap judge at a lower threshold catches
+more for less ([who reads the findings](docs/judges.md#who-reads-the-findings-people-or-coding-agents)). Pull
+requests from forks get no secrets, so the default `mode: auto` runs dry-lint as two jobs for them: `detect` on the pull
+request, and `judge` in [a `workflow_run` job](examples/dry-lint-judge.yml) that keeps the key away from pull
+request code ([design](docs/design.md#two-jobs-in-ci)). For default-branch runs and rechecks when override
+labels change, use the [extended workflow](examples/dry-lint.yml); the [action guide](docs/github-action.md)
+lists every option.
+
+### pre-commit
+
+```yaml
+default_install_hook_types: [pre-commit, prepare-commit-msg]
+repos:
+  - repo: https://github.com/gigaverse-app/dry-lint
+    rev: v1
+    hooks:
+      - id: dry-lint
+      - id: dry-lint-trailers  # optional: the pull request's comment counts what the hook kept out
+```
+
+The hook checks the staged Python, JavaScript and TypeScript for the coding agent making the commit. An agent checks
+each finding itself, then reuses the existing function or records why the two differ, so the hook judges for
+recall: preset `agent`, Jev on every pair, blocking from 0.6. That keeps 92% to 100% recall on four gold sets, with
+about one finding in two real, for about $0.0002 a commit. Set `TYPESAFE_AI_API_KEY` in the environment or in an
+untracked `.env`; nothing else is needed. `args: [--preset, agent+haiku]` adds Claude Haiku on Jev's uncertain
+scores, for higher precision and some lost recall on TypeScript; `args: [--preset, auto]` gives a person committing
+by hand the same precision-first judging as CI
+([who reads the findings](docs/judges.md#who-reads-the-findings-people-or-coding-agents)).
+
+A blocked commit names the pair. Fix it by reusing the existing function, or record an intentional difference with
+`# dry-lint: distinct-from path::name` or `dry-lint feedback dismiss PAIR --reason ...`. For wider exploration with a
+persistent campaign budget, see [`balanced`](docs/production-discovery.md).
+
+A duplicate the hook blocks and the agent fixes never reaches a push, so CI alone would never count it. The hook
+remembers what it blocked; `dry-lint-trailers` writes what was then fixed or dismissed into the commit message,
+`Dry-Lint-Kept-Out: ab7719f1ec3f9b70 repository_counter_name ≈ counter_key (3 lines)`, and the pull request's
+sticky, the repository's ledger and the [global counter](#the-counter) count it
+([the ledger](docs/github-action.md#the-ledger)). Run `pre-commit install` once more after adding it.
+
+## Commands
+
+| Command | Does |
+| --- | --- |
+| `check [--base REF \| --staged]` | detect, judge and report the functions a change touched (base: `origin/HEAD`) |
+| `scan [--limit N] [--refresh] [--repo OWNER/NAME=PATH ...]` | the repository's backlog, or cross-repository pairs from a combined workspace |
+| `sweep [--init \| --update]` | audit the configured repository; explicitly initialize or shrink its accepted backlog and README progress |
+| `config` | which judges, thresholds and budget would run, and what they cost |
+| `explain A B` | why a pair is, or is not, reported |
+| `detect --out candidates.json` | CI job 1: propose pairs; no judge, no secrets, no store |
+| `judge --candidates candidates.json` | CI job 2: judge them, store the verdicts, report |
+| `report --from report.json --format F` | render a report as `text`, `github`, `markdown`, `json`, `sarif` or `check-run` |
+| `bench --gold gold.jsonl [--comparer]` | measure the judge, or the comparer, on a gold set |
+| `bench --replay N [--preset P] [--fail-at X] [--label K]` | what `check` would have done on each of the last N commits of the default branch; with `--label`, what it would have caught, missed and blocked wrongly |
+
+`--report report.json` and `--output comment.md` write the report and the PR comment from any command that
+judges. Without a judge, dry-lint lists the candidate pairs and never fails. With `TYPESAFE_AI_API_KEY` set, Jev
+judges them; to use another judge, pass `--judge command --judge-command "your-llm-cli"`
+([judges](docs/judges.md)).
+
+| To | Read |
+| --- | --- |
+| Fully adopt hooks, PR/README stickies and a shrinking backlog | [Adoption playbook](docs/adoption-playbook.md) |
+| Set it up with an agent | [skills/dry-lint/SKILL.md](skills/dry-lint/SKILL.md) |
+| See the PR comment before installing | [Example report](docs/comment-preview.md) |
+| Put judged findings on pull requests | [GitHub Action setup](docs/github-action.md) |
+| Add structural matching | [The optional Dryer comparer](docs/detectors.md) ([compared on gigaverse-backend](docs/dryer-comparison.md)) |
+| Find copies across related repositories | [Workspace scans and shared ownership](docs/workspaces.md) |
+| Avoid cloning peer repositories in CI | [Versioned function indexes](docs/function-indexes.md) |
+| Audit existing duplication, shrink its baseline and show cleanup in your README | [Repository sweeps and ratchets](docs/sweeps.md) |
+
+## How it works
+
+dry-lint is a fixed core (the pipeline, the file formats, the verdict store's rules and the reports) with four
+plugin slots: how functions are found, how they are compared, how a pair is judged, and where verdicts are kept
+([design](docs/design.md), [plugins](docs/plugins.md)).
+
+1. **Detector** (local, no model, about 4.5 s on 10,000 functions). It finds the functions the diff touched. The
+   **comparer** proposes each one's nearest look-alikes in other files; the built-in one is a TF-IDF fingerprint
+   of what a function *does*: the names it calls, the attributes it touches, the words in its identifiers, its
+   loops, `try` blocks and `await`s. One shared policy consumes language-adapter facts: Python special methods, recognized forwarding wrappers,
+   a function that calls the other (resolved within the file), declared patterns and inline `distinct-from`.
+   Inheritance alone does not exclude repeated logic.
+2. **Judge** (separate and pluggable). [Jev](docs/judges.md) answers three typed questions per pair in about 0.3 s:
+   - Is it one concept?
+   - Do the two already behave differently?
+   - Which side should own the single implementation?
+
+   Any LLM CLI, or any program, can be the judge instead, and a second judge can take the scores the first is
+   least sure about.
+3. **Verdict store** (a cache, not a reviewed file). Each verdict is kept per pair with a *structure hash* of each
+   function, which comments and formatting do not change. Python also normalizes local renames; TypeScript
+   conservatively re-judges them to preserve binding semantics. Most cosmetic pushes cost zero judge calls.
+
+Research on profiles, judging budgets and discovery across repeated runs is in
+[Discovery over time](docs/coverage-exploration.md) and the [four-cent discovery trial](docs/four-cent-discovery.md).
+
+## When it is right not to merge them
+
+Some look-alikes are deliberate. Silence them where the decision belongs:
+
+- **Inline**: put `# dry-lint: distinct-from src/text.py::shorten_text` in the new function. The reason sits next
+  to the code it explains, and moves or disappears with it.
+- **A whole function**: put `# dry-lint: ignore` in it (generated code, a deliberate copy). It is left out of
+  every pair, on either side.
+- **Families**: declare a pattern of deliberate per-resource instances in `pyproject.toml`:
+
+```toml
+[tool.dry-lint]
+exclude = ["*/tests/*", "tests/*", "*/migrations/*"]
+
+[[tool.dry-lint.patterns]]
+members = "src/*/api/*_api.py::create_router"
+reason = "one router per resource"
+```
+
+Machine "not a duplicate" verdicts stay in the store and do not need to be checked in.
+
+## Measured
+
+On 600 gigaverse-ai pull requests, against a 250-pair gold set labelled blind by three vendors' models ([docs/benchmark.md](docs/benchmark.md)):
+
+| | |
+| --- | --- |
+| Changed functions per commit | median 1, p90 13 |
+| Judge calls per PR (uncached) | 2.5 |
+| Findings per PR at the default threshold | about 0.2 |
+| Jev `reuse-v2`: ranking quality | AUC 0.97 |
+| preset `jev+opus`, failing at 0.55, within $0.04 a pull request | 98% precision, 85% recall; about $0.005 per pull request on average |
+| preset `jev+sonnet`, failing at 0.7 | 97% precision, 84% recall; about $0.0035 per pull request |
+| preset `jev+codex` (ChatGPT subscription), failing at 0.7 | 96% precision, 85% recall; no per-call cost |
+| preset `jev`, failing at 0.8 | 94% precision, 73% recall; 15% of pull requests fail |
+| Known duplicates found and scored ≥ 0.8 | 11 of 13 |
+| Verdict store for the whole repository | about 1,900 pairs, 0.75 MB |
+
+## Settings
+
+All settings live under `[tool.dry-lint]` in `pyproject.toml` or in a `.dry-lint.toml` file. Judges and
+thresholds come from the preset ([docs/judges.md](docs/judges.md)); anything set here wins over it:
+
+| Setting | Default | |
+| --- | --- | --- |
+| `include` / `exclude` | everything / tests, migrations, scripts | fnmatch over tracked paths |
+| `neighbours` | 3 | candidates per changed function |
+| `preset` | `"auto"` | judges and their measured thresholds together: `jev+opus`, `jev+claude-code`, `jev+sonnet`, `jev+claude-code-sonnet`, `jev+codex`, `sonnet`, `claude-code`, `jev`, `none`; auto picks by the credentials present |
+| `drop_below` / `report_at` / `fail_at` | from the preset | separate below, reported at, failing at (`--fail-at` overrides it); `jev+opus` is 0.5 / 0.55 / 0.55, with Jev's answers that Opus did not see held to Jev's 0.8 |
+| `drift_at` | 0.8 | a duplicate whose `behaves_differently` reaches this is drifted |
+| `budget` | `{ usd = 0.04, subscription_calls = 20 }` | most judging spends on a pull request across all its pushes, at list price, subscriptions included (`--budget-usd`); and calls per run to subscription judges |
+| `prices` | built-in table | USD per million input and output tokens, by model |
+| `reopen_margin` | 0.05 | for a comparer that permits similarity reuse (no built-in one does), how much closer a "separate" pair must get before it is judged again |
+| `max_findings` | 10 | rows in the PR comment |
+| `extractors` | `["python", "typescript"]` | `.py`, `.ts`, `.tsx`, `.mts`, `.cts` |
+| `comparer` | `"tfidf"` | options `min_similarity` (0.5), `min_similarity_small` (0.3) under `small_function_lines` (6) |
+| `judge` / `escalate` | from the preset | name your own judge to run it alone, or `escalate = "none"` to turn the second judge off |
+| `store` | `"dir"` | `.git/dry-lint/verdicts/`, or `{ use = "s3", uri = "s3://bucket/prefix" }` |
+
+A plugin slot takes a name, or a table with `use` and the plugin's options:
+`comparer = { use = "tfidf", min_similarity = 0.45 }`.
+
+
+## The counter
+
+The sign at the top counts every duplicate dry-lint has kept out of a codebase: a duplicate a pull request
+introduced, dry-lint reported, and a later push removed before merging. A *rewrite* is one whose structure differs
+from the function it duplicates, so a copy-paste checker would not see it; a *drifted* copy already behaved
+differently; a *re-check skipped* is a verdict the store already held. Actions from November 2026 on measure these;
+until a pull request they measured has merged, the sign shows them as "–", never as zero.
+
+When a pull request merges, the action's run on the default branch sends its counts to a
+[Cloudflare Worker](counter): duplicates kept out (how many had drifted, how many were rewrites, and their lines),
+caught and dismissed, pushes, functions checked, look-alikes compared, verdicts reused, judgments, judging spend
+and the dry-lint version. No code, names, paths or people are sent. The repository is **pseudonymous**: it is sent
+as its counter key, the SHA-256 of its numeric GitHub id, which ties its pull requests together but which its name
+does not lead to; a private repository's id is visible only to people who can see the repository. Each pull
+request is counted once. Opt out with `share-totals: "false"`.
+
+A repository whose audit keeps a [README block](docs/sweeps.md#readme-sticky-and-shieldsio-badge) gets its sign
+there automatically, beside the old duplicates it has cleaned up and still has. To show it anywhere else, take its counter key from the
+log of a dry-lint run on your default branch
+(`dry-lint: this repository's counter key is ...`). `name` only labels the sign; the counter never looks a name up:
+
+```html
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://dry-lint-counter.gigaverse-oss.workers.dev/v1/sign.svg?theme=dark&key=KEY&name=OWNER/NAME">
+  <img alt="Duplicates dry-lint kept out of OWNER/NAME" src="https://dry-lint-counter.gigaverse-oss.workers.dev/v1/sign.svg?key=KEY&name=OWNER/NAME" width="100%">
+</picture>
+```
+
+or a badge, with `metric=kept-out`, `drifted`, `lines`, `pulls`, `functions` or `repositories`:
+
+```markdown
+![duplicates kept out](https://img.shields.io/endpoint?url=https%3A%2F%2Fdry-lint-counter.gigaverse-oss.workers.dev%2Fv1%2Fbadge%3Fkey%3DKEY%26metric%3Dkept-out)
+```
+
+## Lint
+
+<img src="docs/assets/avatar.png" alt="Lint, the dry-lint mascot: a purple ball of dryer lint holding a mint-green hair dryer" width="120" align="right">
+
+Lint is what is left behind when you dry things. It carries a hair dryer for blowing duplicated code away.
+`uv run --with pillow python scripts/make_assets.py` rebuilds the avatar, the mark, the banners and the README
+hero from [docs/assets/lint.png](docs/assets/lint.png).
+
+<br clear="right">
+
+## License
+
+Apache 2.0. See [CONTRIBUTING.md](CONTRIBUTING.md) to work on dry-lint itself.