@open-tomato/gates 0.0.0-stage → 0.1.1

package/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.

package/NOTICE

@@ -0,0 +1,10 @@
+@open-tomato/packages
+Copyright 2026 Marcos Tomatti and the open-tomato contributors
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+The configs, rules and gates in this repository began in other
+open-tomato repositories and are developed here since: the ESLint and
+TypeScript configs and the two ESLint rules in rafa, the control-byte
+gate in rafa, the privacy gate in components, and the pack and publish
+scripts in service.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @open-tomato/gates
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Repository gates for the open-tomato projects. Each gate reads what git
+tracks, reports by file and line, and exits with one of three codes:
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | clean |
+| `1` | findings |
+| `2` | the gate could not run |
+
+A gate that cannot run never reports a pass. Both gates are TypeScript run
+by bun, so they need bun 1.3 or newer.
+
+```bash
+bun add -d @open-tomato/gates
+```
+
+## `ot-control-byte-gate`
+
+Refuses raw control bytes and invisible characters in tracked text files.
+A raw NUL makes git treat a file as binary, so its diffs stop rendering, and
+makes grep miss text that is there. The gate also refuses the Trojan Source
+BiDi overrides and the zero-width characters, the same set as
+`@open-tomato/no-unsafe-unicode` in
+[`@open-tomato/eslint-plugin`](../eslint-plugin/README.md). The gate covers
+files ESLint never reads, such as YAML, shell scripts and lock files.
+
+```bash
+bunx ot-control-byte-gate                      # every tracked file
+bunx ot-control-byte-gate --staged             # the index, for a pre-commit hook
+bunx ot-control-byte-gate --include-untracked  # also files not yet added
+```
+
+## `ot-privacy-gate`
+
+Refuses personal and private data in what a public repository tracks:
+
+- **Banned terms** from the project's own list, stored as sha256 hashes so
+  no file spells them: machine names, private domains, private
+  repositories, home paths.
+- **Shapes** that need no list: a home directory with its account name, a
+  private or public IPv4 address, a LAN host name, a credential prefix, an
+  email outside the reserved example domains.
+- **Sample data** in stories, fixtures, mocks and tests: a URL, a phone
+  number or a profile link must use a reserved example host or the
+  fictional 555-01xx range.
+
+```bash
+bunx ot-privacy-gate              # tracked files and untracked ones git would track
+bunx ot-privacy-gate --staged     # the index, for a pre-commit hook
+bunx ot-privacy-gate --history    # every blob and commit identity, before a first push
+bunx ot-privacy-gate --root ../other-repo  # a repository other than the current one
+```
+
+Each mode reads what it judges from where a reviewer would see it:
+
+- `--staged` reads the files and `.privacy-gate.json` from the index, so
+  an allowance edited locally but never staged cannot pass a commit.
+- `--history` judges a blob under every path it was committed at,
+  because the sample rules and the allow list both depend on the path.
+- An unknown flag, `--root` with no folder, or two modes at once stop the
+  gate with exit 2, so a typo never runs a different scan.
+
+### The project's list
+
+The package ships no banned terms. Each project keeps its own in
+`.privacy-gate.json` at the repository root:
+
+```json
+{
+  "banned": [
+    { "sha256": "<sha256 of the lowercase term>", "label": "a private machine name" }
+  ],
+  "allow": [
+    { "path": "package.json", "rule": "email", "sha256": "<sha256 of the evidence>", "why": "The author field." }
+  ]
+}
+```
+
+A label names the term without spelling it. Print a term's hash with:
+
+```bash
+bun -e 'console.log(new Bun.CryptoHasher("sha256").update(process.argv[1].toLowerCase()).digest("hex"))' '<term>'
+```
+
+An `allow` entry is a reviewed exception: the path glob, the rule, the
+sha256 of the exact text the gate reported, and why it is meant. Without a
+config file, the gate runs the shape rules alone and says so in its report.
+A malformed config stops the gate with exit 2, and so does a key other than
+`banned`, `allow` and `$comment`, or an `allow` rule the gate does not have:
+a typo there would otherwise empty a list without a word.
+
+## A pre-commit hook
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+bunx ot-control-byte-gate --staged
+bunx ot-privacy-gate --staged
+```
+
+Save it as `.githooks/pre-commit`, make it executable, and turn it on once
+per clone with `git config core.hooksPath .githooks`.
+
+## Exports
+
+The gates are importable too, for a project that wraps them:
+
+| Path | What it holds |
+| --- | --- |
+| `./control-bytes` | `scanText`, `scanBuffer`, `scanFiles`, `listFiles` |
+| `./privacy` | `judge`, `readSources`, `readConfig`, `parseArgs`, `run` |
+| `./privacy/rules` | `scan`, `bannedIn`, `isSamplePath`, `sha256`, `RULE_NAMES` |
+| `./privacy/config` | `readPrivacyConfig`, `parsePrivacyConfig`, `CONFIG_FILE`, `NO_CONFIG` |

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@open-tomato/gates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Repository gates of the open-tomato projects: a control-byte gate and a privacy gate, run in CI and as pre-commit hooks.",
+  "license": "Apache-2.0",
+  "author": "Marcos Tomatti",
+  "openTomato": {
+    "team": "@open-tomato/maintainers"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/open-tomato/packages.git",
+    "directory": "packages/gates"
+  },
+  "homepage": "https://github.com/open-tomato/packages/tree/main/packages/gates#readme",
+  "bugs": {
+    "url": "https://github.com/open-tomato/packages/issues"
+  },
+  "keywords": [
+    "gate",
+    "privacy",
+    "pre-commit",
+    "trojan-source",
+    "control-characters"
+  ],
+  "type": "module",
+  "bin": {
+    "ot-control-byte-gate": "./src/control-byte-gate.ts",
+    "ot-privacy-gate": "./src/privacy-gate.ts"
+  },
+  "exports": {
+    "./control-bytes": "./src/control-byte-gate.ts",
+    "./privacy": "./src/privacy-gate.ts",
+    "./privacy/rules": "./src/privacy-rules.ts",
+    "./privacy/config": "./src/privacy-config.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "check-types": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@open-tomato/eslint-config": "^0.1.1",
+    "@open-tomato/eslint-plugin": "^0.1.1",
+    "@open-tomato/typescript-config": "^0.1.1",
+    "@types/bun": "^1.3.0",
+    "eslint": "^9.39.5",
+    "typescript": "^5.9.3"
+  }
+}

package/src/control-byte-gate.ts

@@ -0,0 +1,411 @@
+#!/usr/bin/env bun
+/**
+ * Control-byte gate:
+ * A raw C0 control byte in a tracked text file breaks two tools at once,
+ * and both failures are silent false negatives:
+ *
+ *   - git classifies the blob as binary, so every diff renders as
+ *     `Bin N -> M bytes` and the file can never be reviewed again.
+ *   - POSIX grep reports NO MATCH for strings that are present in the
+ *     file, so any absence check built on grep passes vacuously.
+ *
+ * Source must spell control characters as language escapes (the
+ * six-character backslash-u form), never as the literal byte. Runtime
+ * behaviour is identical; tool visibility is not.
+ *
+ * Usage:
+ *   ot-control-byte-gate                      # all tracked files
+ *   ot-control-byte-gate --staged             # staged files only
+ *   ot-control-byte-gate --include-untracked  # + files not yet git-added
+ *   ot-control-byte-gate --root <repo-root>
+ *
+ * Exit codes: 0 clean, 1 findings, 2 the gate could not run.
+ * 2 is distinct from 0 on purpose — a gate that cannot run must never be
+ * mistaken for a gate that passed.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The NUL character and the escape spelling this gate recommends, built
+ * from code points rather than written as escapes. A backslash-u escape
+ * with four hex digits is valid JSON, so content carrying one through a
+ * JSON-decoding write path (an agent tool call) arrives with the escape
+ * already collapsed to the real byte — the exact accident this gate
+ * exists to catch. Built this way, this file can never seed it.
+ */
+const NUL = String.fromCharCode(0);
+const BACKSLASH_U = String.fromCharCode(92) + 'u';
+
+/**
+ * Bytes that must never appear raw in a tracked text file: every C0
+ * control character except TAB/LF/CR, plus DEL. NUL (0x00) is the one
+ * git and grep key their binary classification on; ESC (0x1b) does not
+ * trip the classifier but makes a file unreadable and unmatchable by
+ * edit tools.
+ */
+export const FORBIDDEN_BYTES: ReadonlySet<number> = new Set([
+  ...Array.from({ length: 0x20 }, (_, b) => b).filter(
+    (b) => b !== 0x09 && b !== 0x0a && b !== 0x0d,
+  ),
+  0x7f,
+]);
+
+/**
+ * Codepoints that are invisible or misleading rather than merely control
+ * bytes. These encode as bytes >= 0x80, so the byte scan above cannot
+ * see them — a Trojan Source payload (CVE-2021-42574) is entirely in
+ * this set.
+ *
+ * Kept deliberately in sync with `@open-tomato/no-unsafe-unicode` in
+ * `@open-tomato/eslint-plugin`; the gate's test suite asserts the two
+ * agree. The duplication is on
+ * purpose: this gate imports nothing, so it runs on a bare checkout with
+ * no install.
+ */
+export const FORBIDDEN_CODEPOINTS: ReadonlySet<number> = new Set([
+  // Bidirectional overrides and isolates — Trojan Source.
+  0x202a, 0x202b, 0x202c, 0x202d, 0x202e,
+  0x2066, 0x2067, 0x2068, 0x2069,
+  // Invisible / default-ignorable.
+  0x00ad, 0x200b, 0x200e, 0x200f, 0x2060, 0xfeff,
+  // Parser-splitting separators.
+  0x2028, 0x2029,
+]);
+
+/** Legitimate between two emoji, suspicious anywhere else. */
+export const EMOJI_JOINERS: ReadonlySet<number> = new Set([0x200c, 0x200d]);
+
+const EMOJI_ADJACENT =
+  /[\p{Extended_Pictographic}\p{Emoji_Modifier}\u{FE0F}]/u;
+
+/**
+ * Extensions whose files are legitimately binary. This is an ALLOWLIST,
+ * and it is the gate's only escape hatch: anything not listed here is
+ * scanned. The inverse design — skipping unknown extensions — is what
+ * lets a control byte slip through unnoticed, so do not invert it.
+ */
+export const BINARY_EXTENSIONS: ReadonlySet<string> = new Set([
+  'png', 'jpg', 'jpeg', 'gif', 'webp', 'avif', 'ico', 'icns', 'bmp', 'tiff',
+  'woff', 'woff2', 'ttf', 'otf', 'eot',
+  'pdf', 'zip', 'gz', 'tgz', 'br', 'xz', '7z',
+  'mp3', 'mp4', 'webm', 'wav', 'mov', 'ogg',
+  'wasm', 'bin', 'lockb', 'node', 'dylib', 'so', 'class', 'jar',
+  'p12', 'der', 'keystore', 'jks',
+]);
+
+/** Explicit per-path exemptions. Keep empty unless a file truly cannot comply. */
+export const ALLOWLISTED_PATHS: ReadonlySet<string> = new Set<string>([]);
+
+/** Per-file reporting cap: a truly binary file would otherwise flood the log. */
+export const MAX_REPORTED_PER_FILE = 10;
+
+export interface Finding {
+  file: string;
+  line: number;
+  column: number;
+  byte: number;
+  snippet: string;
+}
+
+export function isScannable(relPath: string): boolean {
+  if (ALLOWLISTED_PATHS.has(relPath)) return false;
+  const base = relPath.slice(relPath.lastIndexOf('/') + 1);
+  const dot = base.lastIndexOf('.');
+  if (dot <= 0) return true; // extensionless and dotfiles are scanned
+  return !BINARY_EXTENSIONS.has(base.slice(dot + 1).toLowerCase());
+}
+
+/**
+ * Render a line for display with every forbidden byte replaced by
+ * `<0xNN>`, so the gate's own output can never carry the byte into a
+ * terminal or CI log. Segments between control bytes are decoded as
+ * UTF-8 so multi-byte characters survive intact.
+ */
+export function renderSafe(buf: Buffer): string {
+  const parts: string[] = [];
+  let start = 0;
+  for (let i = 0; i < buf.length; i++) {
+    if (!FORBIDDEN_BYTES.has(buf[i]!)) continue;
+    parts.push(buf.subarray(start, i).toString('utf8'));
+    parts.push(`<0x${buf[i]!.toString(16).padStart(2, '0')}>`);
+    start = i + 1;
+  }
+  parts.push(buf.subarray(start).toString('utf8'));
+  return parts.join('').trim()
+    .slice(0, 160);
+}
+
+/**
+ * Every forbidden CODEPOINT in the decoded text, with 1-based
+ * line/column. Runs alongside the byte scan: bytes catch NUL/ESC,
+ * codepoints catch BiDi and the invisible set.
+ */
+export function scanText(file: string, text: string): Finding[] {
+  const findings: Finding[] = [];
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i]!;
+    if (ch === '\n') {
+      line += 1;
+      lineStart = i + 1;
+      continue;
+    }
+    const code = text.codePointAt(i)!;
+    if (code === 0xfeff && i === 0) continue; // leading BOM is an encoding artifact
+
+    if (EMOJI_JOINERS.has(code)) {
+      const prev = codePointBefore(text, i);
+      const next = i + 1 < text.length
+        ? text.codePointAt(i + 1)!
+        : -1;
+      const ok =
+        prev >= 0 && next >= 0 &&
+        EMOJI_ADJACENT.test(String.fromCodePoint(prev)) &&
+        EMOJI_ADJACENT.test(String.fromCodePoint(next));
+      if (ok) continue;
+    } else if (!FORBIDDEN_CODEPOINTS.has(code)) {
+      continue;
+    }
+
+    let lineEnd = text.indexOf('\n', i);
+    if (lineEnd === -1) lineEnd = text.length;
+    findings.push({
+      file,
+      line,
+      column: i - lineStart + 1,
+      byte: code,
+      snippet: renderSafeText(text.slice(lineStart, lineEnd)),
+    });
+  }
+  return findings;
+}
+
+/**
+ * Code point ending at `i`, walking back over a surrogate pair. Reading
+ * `text[i - 1]` yields a lone low surrogate for any astral emoji, which
+ * never matches a Unicode property escape — that reads every real emoji
+ * ZWJ sequence as a violation.
+ */
+function codePointBefore(text: string, i: number): number {
+  if (i <= 0) return -1;
+  const lo = text.charCodeAt(i - 1);
+  if (lo >= 0xdc00 && lo <= 0xdfff && i >= 2) {
+    const hi = text.charCodeAt(i - 2);
+    if (hi >= 0xd800 && hi <= 0xdbff) {
+      return (hi - 0xd800) * 0x400 + (lo - 0xdc00) + 0x10000;
+    }
+  }
+  return lo;
+}
+
+/** Like `renderSafe`, for text: replaces flagged codepoints with `<U+XXXX>`. */
+export function renderSafeText(text: string): string {
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const code = text.codePointAt(i)!;
+    const flagged =
+      FORBIDDEN_CODEPOINTS.has(code) ||
+      EMOJI_JOINERS.has(code) ||
+      FORBIDDEN_BYTES.has(code);
+    out += flagged
+      ? `<U+${code.toString(16).toUpperCase()
+        .padStart(4, '0')}>`
+      : text[i];
+  }
+  return out.trim().slice(0, 160);
+}
+
+/** Every forbidden byte in `buf`, with 1-based line/column. */
+export function scanBuffer(file: string, buf: Buffer): Finding[] {
+  const findings: Finding[] = [];
+  let line = 1;
+  let lineStart = 0;
+  for (let i = 0; i < buf.length; i++) {
+    const byte = buf[i]!;
+    if (byte === 0x0a) {
+      line += 1;
+      lineStart = i + 1;
+      continue;
+    }
+    if (!FORBIDDEN_BYTES.has(byte)) continue;
+    let lineEnd = buf.indexOf(0x0a, i);
+    if (lineEnd === -1) lineEnd = buf.length;
+    findings.push({
+      file,
+      line,
+      column: i - lineStart + 1,
+      byte,
+      snippet: renderSafe(buf.subarray(lineStart, lineEnd)),
+    });
+  }
+  return findings;
+}
+
+/**
+ * Paths git knows about, NUL-delimited so filenames with newlines cannot
+ * split a record. Throws when git cannot answer — callers must exit 2,
+ * not 0.
+ */
+export function listFiles(
+  root: string,
+  staged: boolean,
+  includeUntracked = false,
+): string[] {
+  const run = (args: string[]): string[] => execFileSync('git', args, { cwd: root, maxBuffer: 64 * 1024 * 1024 })
+    .toString('utf8')
+    .split(NUL)
+    .filter(Boolean);
+
+  if (staged) {
+    return run(['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMR']);
+  }
+
+  const tracked = run(['ls-files', '-z']);
+  if (!includeUntracked) return tracked;
+
+  // New skill/agent/context files are usually written before they are
+  // added. `--exclude-standard` keeps .gitignore honoured, so
+  // node_modules and build output stay out.
+  const untracked = run(['ls-files', '--others', '--exclude-standard', '-z']);
+  return [...new Set([...tracked, ...untracked])];
+}
+
+/** Worktree content, or null when the path is not a readable regular file. */
+export function readWorktree(root: string, rel: string): Buffer | null {
+  const full = join(root, rel);
+  try {
+    if (!statSync(full).isFile()) return null; // submodule / gone
+  } catch {
+    return null; // staged deletion, or a path removed from the worktree
+  }
+  return readFileSync(full);
+}
+
+/**
+ * Content of the STAGED (index) version. The pre-commit hook must judge
+ * what the commit will actually contain: a byte staged and then cleaned
+ * up in the worktree would otherwise sail through.
+ */
+export function readStaged(root: string, rel: string): Buffer | null {
+  try {
+    return execFileSync('git', ['cat-file', 'blob', `:${rel}`], {
+      cwd: root,
+      maxBuffer: 64 * 1024 * 1024,
+    });
+  } catch {
+    return null;
+  }
+}
+
+export function scanFiles(
+  root: string,
+  relPaths: string[],
+  read: (rel: string) => Buffer | null = (rel) => readWorktree(root, rel),
+): Finding[] {
+  const findings: Finding[] = [];
+  for (const rel of relPaths) {
+    if (!isScannable(rel)) continue;
+    const content = read(rel);
+    if (content === null) continue;
+    findings.push(...scanBuffer(rel, content));
+    // Byte scan first (NUL/ESC), then the decoded scan (BiDi/invisible).
+    // A file that is not valid UTF-8 still gets the byte scan, which is
+    // the one that matters for git's binary classification.
+    findings.push(...scanText(rel, content.toString('utf8')));
+  }
+  return findings;
+}
+
+if (import.meta.main) {
+  const argv = process.argv.slice(2);
+  const staged = argv.includes('--staged');
+  const includeUntracked = argv.includes('--include-untracked');
+  const rootFlag = argv.indexOf('--root');
+  const root = rootFlag > -1
+    ? argv[rootFlag + 1]!
+    : process.cwd();
+
+  let files: string[] = [];
+  try {
+    files = listFiles(root, staged, includeUntracked);
+  } catch (err) {
+    const message = err instanceof Error
+      ? err.message
+      : String(err);
+    console.error(`[control-byte-gate] FAIL — git could not list files: ${message}`);
+    process.exit(2);
+  }
+
+  const scannable = files.filter(isScannable);
+
+  // Vacuity guard: in full-repo mode an empty file list means the gate
+  // was pointed somewhere wrong, not that the repo is clean. Reporting
+  // OK here would be exactly the false all-clear this gate exists to
+  // prevent.
+  if (!staged && scannable.length === 0) {
+    console.error(
+      '[control-byte-gate] FAIL — 0 scannable files found. Refusing to report' +
+        ' a pass; check --root points at the repository.',
+    );
+    process.exit(2);
+  }
+
+  // Say plainly when there was nothing to look at. "OK - 0 files
+  // scanned" reads like a verification that happened; it is the absence
+  // of one.
+  if (staged && scannable.length === 0) {
+    console.log('[control-byte-gate] nothing staged to scan.');
+    process.exit(0);
+  }
+
+  const findings = scanFiles(
+    root,
+    scannable,
+    staged
+      ? (rel) => readStaged(root, rel)
+      : undefined,
+  );
+
+  if (findings.length === 0) {
+    console.log(
+      `[control-byte-gate] OK — ${scannable.length} file(s) scanned, no unsafe characters.`,
+    );
+    process.exit(0);
+  }
+
+  console.error(
+    `[control-byte-gate] FAIL — ${findings.length} unsafe character(s) in ` +
+      `${new Set(findings.map((f) => f.file)).size} file(s):`,
+  );
+  const byFile = new Map<string, Finding[]>();
+  for (const f of findings) {
+    const list = byFile.get(f.file) ?? [];
+    list.push(f);
+    byFile.set(f.file, list);
+  }
+  for (const [file, list] of byFile) {
+    for (const f of list.slice(0, MAX_REPORTED_PER_FILE)) {
+      const hexByte = `0x${f.byte.toString(16).padStart(2, '0')}`;
+      console.error(`  ${file}:${f.line}:${f.column}  ${hexByte}`);
+      console.error(`    ${f.snippet}`);
+    }
+    if (list.length > MAX_REPORTED_PER_FILE) {
+      console.error(
+        `  ${file}: ... and ${list.length - MAX_REPORTED_PER_FILE} more in this file`,
+      );
+    }
+  }
+  console.error(
+    `\n  Write the character as a language escape instead (e.g. ${BACKSLASH_U}0000).`,
+  );
+  console.error(
+    '  Runtime behaviour is unchanged; a literal byte makes git render the',
+  );
+  console.error(
+    '  file as `Bin` and makes grep report no match for text that is present.',
+  );
+  process.exit(1);
+}

package/src/privacy-config.ts

@@ -0,0 +1,106 @@
+/**
+ * The project's privacy-gate config: `.privacy-gate.json` at the
+ * repository root. It holds what only the project knows:
+ *
+ *   {
+ *     "banned": [{ "sha256": "<hash of the lowercase term>", "label": "a private machine name" }],
+ *     "allow":  [{ "path": "package.json", "rule": "email", "sha256": "<hash of the evidence>", "why": "..." }]
+ *   }
+ *
+ * Both lists store hashes, never values, so the config can sit in a
+ * public repository. A project with no file gets the shape rules alone,
+ * and the gate says so in its report.
+ *
+ * A malformed file throws: a gate that silently dropped a broken list
+ * would pass the very terms the list exists to stop.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { type BannedTerms, RULE_NAMES, type RuleName } from './privacy-rules';
+
+/** The config file name, at the repository root. */
+export const CONFIG_FILE = '.privacy-gate.json';
+
+/** The top-level keys a config may hold; any other is a typo that would empty a list. */
+const KNOWN_KEYS: ReadonlySet<string> = new Set(['$comment', 'banned', 'allow']);
+
+/** A sha256 in lowercase hex. */
+const SHA256 = /^[0-9a-f]{64}$/;
+
+/** One reviewed exception: a path glob, a rule, and the sha256 of the exact evidence. */
+export interface Allowance {
+  readonly path: string;
+  readonly rule: RuleName;
+  readonly sha256: string;
+  readonly why: string;
+}
+
+/** The parsed config. */
+export interface PrivacyConfig {
+  /** Whether the project has a config file at all. */
+  readonly found: boolean;
+  readonly banned: BannedTerms;
+  readonly allow: readonly Allowance[];
+}
+
+/** Whether `value` is a non-empty string. */
+function isText(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+/** Whether `value` names one of the gate's rules. */
+function isRuleName(value: unknown): value is RuleName {
+  return (RULE_NAMES as readonly unknown[]).includes(value);
+}
+
+/** One banned entry, checked, as a map pair. */
+function parseBanned(entry: unknown, index: number): [string, string] {
+  const { sha256, label } = (entry ?? {}) as Record<string, unknown>;
+  if (!isText(sha256) || !SHA256.test(sha256)) throw new Error(`${CONFIG_FILE}: banned[${index}].sha256 must be a lowercase sha256`);
+  if (!isText(label)) throw new Error(`${CONFIG_FILE}: banned[${index}].label must name the term without spelling it`);
+  return [sha256, label];
+}
+
+/** One allow entry, checked. */
+function parseAllowance(entry: unknown, index: number): Allowance {
+  const { path, rule, sha256, why } = (entry ?? {}) as Record<string, unknown>;
+  if (!isText(path)) throw new Error(`${CONFIG_FILE}: allow[${index}].path must be a glob`);
+  if (!isRuleName(rule)) throw new Error(`${CONFIG_FILE}: allow[${index}].rule must be one of ${RULE_NAMES.join(', ')}`);
+  if (!isText(sha256) || !SHA256.test(sha256)) throw new Error(`${CONFIG_FILE}: allow[${index}].sha256 must be a lowercase sha256`);
+  if (!isText(why)) throw new Error(`${CONFIG_FILE}: allow[${index}].why must say why the value is meant`);
+  return { path, rule, sha256, why };
+}
+
+/** A list field of the config, or an empty list when it is absent. */
+function listField(config: Record<string, unknown>, field: string): unknown[] {
+  const value = config[field];
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${CONFIG_FILE}: ${field} must be a list`);
+  return value;
+}
+
+/** Parses the text of a config file. */
+export function parsePrivacyConfig(text: string): PrivacyConfig {
+  const parsed = JSON.parse(text) as unknown;
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error(`${CONFIG_FILE}: must hold a JSON object`);
+  const config = parsed as Record<string, unknown>;
+  const unknown = Object.keys(config).filter((key) => !KNOWN_KEYS.has(key));
+  if (unknown.length > 0) throw new Error(`${CONFIG_FILE}: unknown key ${unknown.join(', ')}; it holds only banned, allow and $comment`);
+  return {
+    found: true,
+    banned: new Map(listField(config, 'banned').map(parseBanned)),
+    allow: listField(config, 'allow').map(parseAllowance),
+  };
+}
+
+/** The config of a project with no config file. */
+export const NO_CONFIG: PrivacyConfig = { found: false, banned: new Map(), allow: [] };
+
+/** Reads `.privacy-gate.json` from `root`, or an empty config when there is none. */
+export function readPrivacyConfig(root: string): PrivacyConfig {
+  const path = join(root, CONFIG_FILE);
+  if (!existsSync(path)) return NO_CONFIG;
+  return parsePrivacyConfig(readFileSync(path, 'utf8'));
+}

package/src/privacy-gate.ts

@@ -0,0 +1,234 @@
+#!/usr/bin/env bun
+/**
+ * The privacy gate: refuses personal and private data in what a public
+ * repository tracks. The rules live in `./privacy-rules.ts`, the
+ * project's banned terms and reviewed exceptions in its
+ * `.privacy-gate.json` (`./privacy-config.ts`); this file picks what to
+ * read and reports.
+ *
+ *   ot-privacy-gate              tracked and untracked-not-ignored files
+ *   ot-privacy-gate --staged     the index blobs (the pre-commit hook)
+ *   ot-privacy-gate --history    every blob and commit identity in every ref
+ *   ot-privacy-gate --root <dir> a repository other than the current one
+ *
+ * `--staged` judges the index, not the worktree, so a value staged and
+ * then cleaned up locally still blocks; it reads the config from the
+ * index too, so an unstaged allowance cannot pass a commit. `--history`
+ * is the check before a first push: a value removed by a later commit is
+ * still published by the earlier one, and a blob is judged under every
+ * path it was committed at.
+ *
+ * A finding that is meant (the author's address in `package.json`, say)
+ * goes in the config's `allow` list with its path glob, rule and the
+ * sha256 of its evidence, so every exception is written down and reviewed
+ * in a diff without the config spelling the value.
+ *
+ * Exit codes: 0 clean, 1 findings, 2 the gate could not run. A gate that
+ * cannot run must never read as a gate that passed.
+ */
+import { join } from 'node:path';
+
+import { type Allowance, CONFIG_FILE, NO_CONFIG, parsePrivacyConfig, type PrivacyConfig, readPrivacyConfig } from './privacy-config';
+import { type Finding, scan, sha256 } from './privacy-rules';
+
+/** A file to judge: where it is named from, and its text. */
+export interface Source {
+  readonly name: string;
+  readonly path: string;
+  readonly text: string;
+}
+
+/** The modes the gate reads sources in. */
+export type Mode = 'tree' | 'staged' | 'history';
+
+/** What the command line asks for. */
+export interface GateArgs {
+  readonly mode: Mode;
+  /** The folder to start from; the current one when absent. */
+  readonly root: string | undefined;
+}
+
+/** A NUL in the first bytes marks a binary file, which is skipped. */
+const BINARY_PROBE = 8000;
+
+/** The flags that pick a mode other than the tree. */
+const MODE_FLAGS: Readonly<Record<string, Mode>> = { '--staged': 'staged', '--history': 'history' };
+
+/** Run git and answer its stdout, failing loudly on a nonzero exit. */
+function git(args: string[], cwd: string): Buffer {
+  const result = Bun.spawnSync(['git', ...args], { cwd, maxBuffer: 512 * 1024 * 1024 });
+  if (result.exitCode !== 0) throw new Error(`git ${args.join(' ')} failed: ${result.stderr.toString()}`);
+  return result.stdout;
+}
+
+/** The whole text of a blob, or null for a binary one. */
+function textOf(bytes: Uint8Array): string | null {
+  if (bytes.subarray(0, BINARY_PROBE).includes(0)) return null;
+  return new TextDecoder().decode(bytes);
+}
+
+/** Split NUL-separated git output into its entries. */
+function entries(output: Buffer): string[] {
+  return output.toString().split('\0')
+    .filter((entry) => entry !== '');
+}
+
+/** The tracked files and the untracked ones git would track. */
+async function treeSources(root: string): Promise<Source[]> {
+  const sources: Source[] = [];
+  for (const path of entries(git(['ls-files', '-z', '--cached', '--others', '--exclude-standard'], root))) {
+    const file = Bun.file(join(root, path));
+    if (!(await file.exists())) continue;
+    const text = textOf(await file.bytes());
+    if (text !== null) sources.push({ name: path, path, text });
+  }
+  return sources;
+}
+
+/** The index blobs of the files a commit would add or change. */
+function stagedSources(root: string): Source[] {
+  const sources: Source[] = [];
+  for (const path of entries(git(['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMR'], root))) {
+    const text = textOf(git(['show', `:${path}`], root));
+    if (text !== null) sources.push({ name: `${path} (staged)`, path, text });
+  }
+  return sources;
+}
+
+/** The text of the blob `sha`, read once and kept in `cache`. */
+function blobText(sha: string, root: string, cache: Map<string, string | null>): string | null {
+  const known = cache.get(sha);
+  if (known !== undefined) return known;
+  const text = textOf(git(['cat-file', 'blob', sha], root));
+  cache.set(sha, text);
+  return text;
+}
+
+/**
+ * Every blob in the tree of every commit reachable from any ref, once per
+ * path it was committed at, plus commit identities and messages. The
+ * rules and the allow list both depend on the path, so a blob copied to a
+ * second path is judged again there.
+ */
+function historySources(root: string): Source[] {
+  const sources: Source[] = [];
+  const seen = new Set<string>();
+  const cache = new Map<string, string | null>();
+  for (const commit of git(['rev-list', '--all'], root).toString()
+    .split('\n')
+    .filter((line) => line !== '')) {
+    for (const entry of entries(git(['ls-tree', '-r', '-z', commit], root))) {
+      const [meta = '', path = ''] = entry.split('\t');
+      const [, type, sha] = meta.split(' ');
+      if (type !== 'blob' || sha === undefined || path === '' || seen.has(`${sha} ${path}`)) continue;
+      seen.add(`${sha} ${path}`);
+      const text = blobText(sha, root, cache);
+      if (text !== null) sources.push({ name: `${path} @ ${sha.slice(0, 8)}`, path, text });
+    }
+  }
+  const log = git(['log', '--all', '--format=%h%x00%an <%ae>%x00%cn <%ce>%x00%B%x00%x01'], root).toString();
+  for (const record of log.split('\x01')) {
+    const [hash, author, committer, body] = record.replace(/^\n/, '').split('\0');
+    if (hash === undefined || hash === '') continue;
+    sources.push({ name: `commit ${hash}`, path: '.git/COMMIT', text: [author, committer, body].join('\n') });
+  }
+  return sources;
+}
+
+/** Whether a finding in `path` is one of the reviewed exceptions. */
+function isAllowed(path: string, finding: Finding, allowed: readonly Allowance[]): boolean {
+  return allowed.some((allowance) => allowance.rule === finding.rule
+    && allowance.sha256 === sha256(finding.evidence)
+    && new Bun.Glob(allowance.path).match(path));
+}
+
+/** Judges the sources under `config` and answers the report lines. */
+export function judge(sources: readonly Source[], config: PrivacyConfig): string[] {
+  const report: string[] = [];
+  for (const source of sources) {
+    for (const finding of scan(source.path, source.text, config.banned)) {
+      if (isAllowed(source.path, finding, config.allow)) continue;
+      report.push(`${source.name}:${finding.line}  ${finding.rule}  ${finding.evidence}`);
+    }
+  }
+  return report;
+}
+
+/** The sources one mode reads from the repository at `root`. */
+export async function readSources(root: string, mode: Mode): Promise<Source[]> {
+  if (mode === 'staged') return stagedSources(root);
+  if (mode === 'history') return historySources(root);
+  return treeSources(root);
+}
+
+/** The config a mode judges by: the index copy for `--staged`, the worktree copy otherwise. */
+export function readConfig(root: string, mode: Mode): PrivacyConfig {
+  if (mode !== 'staged') return readPrivacyConfig(root);
+  if (entries(git(['ls-files', '-z', '--cached', '--', CONFIG_FILE], root)).length === 0) return NO_CONFIG;
+  return parsePrivacyConfig(git(['show', `:${CONFIG_FILE}`], root).toString());
+}
+
+/**
+ * Parses the command line strictly: an unknown argument, `--root` with
+ * no folder, or two mode flags throw, so a typo never runs a different
+ * scan than the one asked for.
+ */
+export function parseArgs(argv: readonly string[]): GateArgs {
+  let mode: Mode | undefined;
+  let root: string | undefined;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? '';
+    if (arg === '--root') {
+      const value = argv[index + 1];
+      if (value === undefined || value.startsWith('--')) throw new Error('--root needs a folder after it');
+      if (root !== undefined) throw new Error('--root is given twice');
+      root = value;
+      index += 1;
+      continue;
+    }
+    const flagMode = MODE_FLAGS[arg];
+    if (flagMode === undefined) throw new Error(`unknown argument ${arg}; the gate takes --staged, --history and --root <dir>`);
+    if (mode !== undefined) throw new Error(`--${mode} and ${arg} cannot run together`);
+    mode = flagMode;
+  }
+  return { mode: mode ?? 'tree', root };
+}
+
+/** The exit code for "the gate could not run". */
+const EXIT_FAILED = 2;
+
+/** Runs the gate over the repository the arguments name and answers its exit code. */
+export async function run(argv: readonly string[]): Promise<number> {
+  const { mode, root: start = process.cwd() } = parseArgs(argv);
+  const root = git(['rev-parse', '--show-toplevel'], start).toString()
+    .trim();
+  const config = readConfig(root, mode);
+  const sources = await readSources(root, mode);
+  if (mode !== 'staged' && sources.length === 0) {
+    console.error(`privacy-gate: FAIL, 0 ${mode} sources under ${root}. Refusing to report a pass.`);
+    return EXIT_FAILED;
+  }
+  const listNote = config.found
+    ? `${config.banned.size} banned terms`
+    : `no ${CONFIG_FILE}, so no banned terms`;
+  const report = judge(sources, config);
+  if (report.length === 0) {
+    console.log(`privacy-gate: ${sources.length} ${mode} sources, ${listNote}, no findings`);
+    return 0;
+  }
+  console.error(`privacy-gate: ${report.length} findings in ${mode} sources (${listNote})\n${report.join('\n')}`);
+  console.error(`\nRemove each value, replace it with a reserved example, or add a reviewed entry to the allow list of ${CONFIG_FILE}\n(its evidence as sha256: bun -e 'console.log(new Bun.CryptoHasher("sha256").update(process.argv[1]).digest("hex"))' '<evidence>').`);
+  return 1;
+}
+
+if (import.meta.main) {
+  try {
+    process.exit(await run(process.argv.slice(2)));
+  } catch (error) {
+    const message = error instanceof Error
+      ? error.message
+      : String(error);
+    console.error(`privacy-gate: FAIL, the gate could not run: ${message}`);
+    process.exit(EXIT_FAILED);
+  }
+}

package/src/privacy-rules.ts

@@ -0,0 +1,209 @@
+/**
+ * The privacy rules: what a tracked file may not carry in a public
+ * repository. Each rule reads one string and answers findings with a
+ * line number, so the same rules judge a staged blob, a tracked file and
+ * every blob in the history.
+ *
+ * Three families:
+ *
+ * - **Banned terms**, stored as sha256 hashes of their lowercase form so
+ *   no file spells them: machine names, private domains, private
+ *   repositories, home paths and mail handles. This package ships no
+ *   list; each project keeps its own in `.privacy-gate.json`
+ *   (`./privacy-config.ts`).
+ * - **Shapes**, which need no list: a home directory path, a private or
+ *   public IPv4 address, a LAN host name, a credential prefix.
+ * - **Sample data**, the gap other projects found: mock people in
+ *   stories, fixtures and tests. There an email, a URL, a phone number
+ *   or a profile link must use a reserved example domain or number, so a
+ *   real person's address can never pass as a sample.
+ *
+ * To ban a term, print its hash and add an entry to the project's
+ * `.privacy-gate.json` with a label that does not spell it:
+ *
+ *   bun -e 'console.log(new Bun.CryptoHasher("sha256").update(process.argv[1].toLowerCase()).digest("hex"))' '<term>'
+ */
+
+/** A rule's answer: the line it fired on and what it found. */
+export interface Finding {
+  readonly line: number;
+  readonly rule: RuleName;
+  /** What matched. A banned term is shown by its label only. */
+  readonly evidence: string;
+}
+
+/** The rule names, as the report and the allowlist spell them. */
+export const RULE_NAMES = [
+  'banned-term',
+  'home-path',
+  'ip-address',
+  'lan-host',
+  'credential',
+  'email',
+  'sample-url',
+  'sample-phone',
+  'profile-link',
+] as const;
+
+/** One rule name. */
+export type RuleName = typeof RULE_NAMES[number];
+
+/** sha256 of a banned lowercase term, mapped to a label that does not spell it. */
+export type BannedTerms = ReadonlyMap<string, string>;
+
+/** No banned terms: the default when a project lists none. */
+export const NO_BANNED_TERMS: BannedTerms = new Map();
+
+/** Characters a token is made of, for the banned-term rule. */
+const TOKEN = /[a-z0-9._/~@-]+/g;
+
+/** The separators that split a token into words. */
+const SEPARATOR = /[._/~@-]/;
+
+/** Tokens longer than this are cut into words from their first part only. */
+const MAX_WORDS = 24;
+
+/** Mail and web domains reserved for examples (RFC 2606, RFC 6761). */
+const RESERVED_DOMAIN = /(^|\.)(example\.(com|net|org)|example|test|invalid|localhost)$/;
+
+/** IPv4 addresses kept for documentation, loopback and wildcards. */
+const ALLOWED_IP = /^(127\.0\.0\.1|0\.0\.0\.0|255\.255\.255\.255|192\.0\.2\.\d+|198\.51\.100\.\d+|203\.0\.113\.\d+)$/;
+
+/** Hosts a sample may link to without naming anyone. */
+const ALLOWED_SAMPLE_HOST = /(^|\.)(example\.(com|net|org)|example|test|invalid|localhost|www\.w3\.org|w3\.org)$/;
+
+/** Credential prefixes a vendor issues keys under, followed by a key-like body. */
+const CREDENTIAL = /\b(gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|(AKIA|ASIA)[A-Z0-9]{16}|sk-(ant-)?[A-Za-z0-9_-]{20,}|xox[abprs]-[A-Za-z0-9-]{10,}|AIza[A-Za-z0-9_-]{30,}|-----BEGIN [A-Z ]*PRIVATE KEY-----)/;
+
+/** A home directory with its account segment, on macOS, Linux or Windows. */
+const HOME_PATH = /(^|[^\w.-])(\/Users\/[A-Za-z0-9._-]+|\/home\/[A-Za-z0-9._-]+|[A-Za-z]:\\Users\\[A-Za-z0-9._-]+)/;
+
+/** A dotted quad, checked for range after the match. */
+const IPV4 = /(?<![\w.])(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})(?![\w.]*\d)/g;
+
+/** An SVG path or points attribute, whose numbers read like dotted quads. */
+const SVG_PATH = /(^|\s)(d|points)=["{]/;
+
+/** A host name on a LAN-only suffix, not a property chain like `node.local.name`. */
+const LAN_HOST = /\b[a-z0-9-]+\.(local|lan|internal|home\.arpa|localdomain)\b(?![.(\w])/i;
+
+/** An email address; the domain is checked after the match. */
+const EMAIL = /(?<![\w/@.-])[A-Za-z0-9._%+-]+@((?:[A-Za-z0-9-]+\.)+[A-Za-z]{2,})(?![\w-])/g;
+
+/** An http(s) URL's host. */
+const URL_HOST = /https?:\/\/([A-Za-z0-9.-]+)/g;
+
+/** A phone number shape: optional country code, then 9 to 13 digits in groups. */
+const PHONE = /(?<![\w.])\+?\d{1,3}?[ (.-]*\d{2,4}[ ).-]+\d{3,4}[ .-]+\d{3,4}(?![\w.])/g;
+
+/** The fictional range: 555-0100 to 555-0199. */
+const FICTIONAL_PHONE = /555[ .-]?01\d\d/;
+
+/** A link to a person's profile on a public network. */
+const PROFILE = /\b(github\.com|gitlab\.com|twitter\.com|x\.com|linkedin\.com\/in|instagram\.com|facebook\.com)\/([A-Za-z0-9_.-]+)/gi;
+
+/** Paths that hold sample data: stories, fixtures, mocks, tests. */
+const SAMPLE_PATH = /(\.stories\.[jt]sx?$|\.test\.[jt]sx?$|\.spec\.[jt]sx?$|(^|\/)(stories|fixtures?|mocks?|__mocks__|testdata|samples?)\/|fixtures?\.[jt]sx?$|mocks?\.[jt]sx?$)/;
+
+/** Whether `path` holds sample data. */
+export function isSamplePath(path: string): boolean {
+  return SAMPLE_PATH.test(path);
+}
+
+/** The sha256 of `text`, as hex. */
+export function sha256(text: string): string {
+  return new Bun.CryptoHasher('sha256').update(text)
+    .digest('hex');
+}
+
+/** Every run of whole words in `token`, each with and without the separator before it. */
+function candidates(token: string): string[] {
+  const words: { start: number; end: number }[] = [];
+  let start = -1;
+  for (let index = 0; index <= token.length; index += 1) {
+    const isWord = index < token.length && !SEPARATOR.test(token.charAt(index));
+    if (isWord && start === -1) start = index;
+    if (!isWord && start !== -1) {
+      words.push({ start, end: index });
+      start = -1;
+    }
+  }
+  const runs: string[] = [];
+  const kept = words.slice(0, MAX_WORDS);
+  for (let first = 0; first < kept.length; first += 1) {
+    const from = kept[first]?.start ?? 0;
+    for (let last = first; last < kept.length; last += 1) {
+      const to = kept[last]?.end ?? 0;
+      runs.push(token.slice(from, to));
+      if (from > 0) runs.push(token.slice(from - 1, to));
+    }
+  }
+  return runs;
+}
+
+/** The labels of the banned terms one line holds. */
+export function bannedIn(text: string, banned: BannedTerms = NO_BANNED_TERMS): string[] {
+  const found = new Set<string>();
+  for (const token of text.toLowerCase().match(TOKEN) ?? []) {
+    for (const candidate of candidates(token)) {
+      const label = banned.get(sha256(candidate));
+      if (label !== undefined) found.add(label);
+    }
+  }
+  return [...found];
+}
+
+/** Whether an IPv4 match is a real address outside the allowed set. */
+function isReportableIp(parts: string[], text: string): boolean {
+  if (parts.some((part) => Number(part) > 255)) return false;
+  return !ALLOWED_IP.test(text);
+}
+
+/** The findings of the rules that apply to every file, for one line. */
+function lineFindings(text: string, line: number, banned: BannedTerms): Finding[] {
+  const findings: Finding[] = [];
+  for (const label of bannedIn(text, banned)) findings.push({ line, rule: 'banned-term', evidence: label });
+  const home = HOME_PATH.exec(text);
+  if (home?.[2] !== undefined) findings.push({ line, rule: 'home-path', evidence: home[2] });
+  const svgPath = SVG_PATH.test(text);
+  for (const match of svgPath
+    ? []
+    : text.matchAll(IPV4)) {
+    if (isReportableIp(match.slice(1, 5), match[0])) findings.push({ line, rule: 'ip-address', evidence: match[0] });
+  }
+  const lan = LAN_HOST.exec(text);
+  if (lan !== null) findings.push({ line, rule: 'lan-host', evidence: lan[0] });
+  const credential = CREDENTIAL.exec(text);
+  if (credential?.[1] !== undefined) findings.push({ line, rule: 'credential', evidence: `${credential[1].slice(0, 6)}…` });
+  for (const match of text.matchAll(EMAIL)) {
+    const domain = (match[1] ?? '').toLowerCase();
+    if (!RESERVED_DOMAIN.test(domain)) findings.push({ line, rule: 'email', evidence: match[0] });
+  }
+  return findings;
+}
+
+/** The findings of the sample-data rules, for one line of a sample file. */
+function sampleFindings(text: string, line: number): Finding[] {
+  const findings: Finding[] = [];
+  for (const match of text.matchAll(URL_HOST)) {
+    const host = (match[1] ?? '').toLowerCase();
+    if (!ALLOWED_SAMPLE_HOST.test(host)) findings.push({ line, rule: 'sample-url', evidence: match[0] });
+  }
+  for (const match of text.matchAll(PHONE)) {
+    const digits = match[0].replace(/\D/g, '');
+    if (digits.length >= 9 && !FICTIONAL_PHONE.test(match[0])) findings.push({ line, rule: 'sample-phone', evidence: match[0].trim() });
+  }
+  for (const match of text.matchAll(PROFILE)) findings.push({ line, rule: 'profile-link', evidence: match[0] });
+  return findings;
+}
+
+/** Every finding in one file's text. Line numbers count from one. */
+export function scan(path: string, text: string, banned: BannedTerms = NO_BANNED_TERMS): Finding[] {
+  const sample = isSamplePath(path);
+  const findings: Finding[] = [];
+  text.split('\n').forEach((content, index) => {
+    findings.push(...lineFindings(content, index + 1, banned));
+    if (sample) findings.push(...sampleFindings(content, index + 1));
+  });
+  return findings;
+}