chore(docs): keep internal references out of docs and commit messages (LAB-8003)

.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+# Pre-commit hooks. Install once per clone: prek install (Python pre-commit works too).
+default_install_hook_types: [pre-commit, commit-msg]
+
+repos:
+  # Keeps internal references (ticket ids, secret-store paths, internal hosts and process
+  # names) out of user-facing docs and commit messages. The patterns are generic on purpose:
+  # a list of specific internal names would itself disclose them.
+  # Scope rule: https://docs.cachekit.io/contributing/#what-belongs-in-these-docs
+  - repo: local
+    hooks:
+      - id: no-internal-references
+        name: No internal references in docs
+        language: pygrep
+        entry: '\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s_-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])'
+        files: ^((packages|crates)/[^/]+/)?README[^/]*$|^docs/
+        types: [text]
+        stages: [pre-commit]
+      - id: no-internal-references-commit-msg
+        name: No internal references in commit message
+        # Same patterns. git hands this hook the raw message file: "# " comment lines, the diff
+        # below the `git commit -v` scissors line, and its own merge and revert subjects, which
+        # quote branch names and earlier subjects. Only the text the author wrote is checked.
+        language: python
+        entry: python -c
+        args:
+          - |
+            import re, sys
+            P = re.compile(r"\b(?i:LAB)-[0-9]+|op://|\.ts\.net|(?i:\bk3s[\s_-]+(?:cluster|node|host)s?\b)|dev\.cachekit\.io|\bStage [0-9]|\bAC-[0-9]|github\.com/cachekit(?![\w-])")
+            KIND = r"(?:branch|branches|remote-tracking branch|remote-tracking branches|tag|tags|commit|commits)"
+            GIT_SUBJECT = re.compile(rf"Merge {KIND} '[^']*'(?:(?:, |; | and ){KIND}? ?'[^']*')*(?: of \S+)?(?: into \S+)?|(?:Revert|Reapply) \".*\"")
+            try:
+                with open(sys.argv[1], encoding="utf-8", errors="replace") as f:
+                    text = f.read()
+            except OSError as e:
+                sys.exit(f"{sys.argv[1]}: cannot read the commit message: {e}")
+            text = text.split("# ------------------------ >8 ------------------------")[0]
+            lines = [line for line in text.splitlines() if line.strip() and not re.match(r"#(?:[ \t]|$)", line)]
+            if lines and GIT_SUBJECT.fullmatch(lines[0]):
+                lines = lines[1:]
+            bad = [line for line in lines if P.search(line)]
+            for line in bad:
+                print(f"{sys.argv[1]}: {line}")
+            sys.exit(1 if bad else 0)
+        stages: [commit-msg]

README.md

@@ -49,7 +49,7 @@ is not repeated. A typical use is a secret read in a shell startup file, where
 every new shell would otherwise call the secret manager again:
 
 ```sh
-API_TOKEN="$(ck run --ttl 12h --stale 7d -- op read op://Private/api/token)"
+API_TOKEN="$(ck run --ttl 12h --stale 7d -- op item get api --fields token --reveal)"
 export API_TOKEN
 ```
 
@@ -278,6 +278,13 @@ Linux and macOS. The cache directory must be on a local filesystem: on NFS or
 SMB, concurrent first calls may each run the command, though entries are never
 torn.
 
+## Contributing
+
+User-facing docs in this repository follow CacheKit's shared rule on what belongs in them:
+[What belongs in these docs](https://docs.cachekit.io/contributing/#what-belongs-in-these-docs).
+`prek install` (or `pre-commit install`) sets up hooks that reject internal references in README
+files, `docs/` and commit messages.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).