tripwire-git 0.2.1__tar.gz → 0.3.0__tar.gz

{tripwire_git-0.2.1/src/tripwire_git.egg-info → tripwire_git-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tripwire-git
-Version: 0.2.1
+Version: 0.3.0
 Summary: Protect blocks of code in Git: changes need approval from an owner, an approver or a leader.
 License: MIT
 Keywords: git,code-owners,approval,pre-receive,ci
@@ -71,6 +71,41 @@ required check on GitHub, GitLab and Gitea / Forgejo.
   Unclosed blocks extend to end of file. A marker whose id is missing from the
   rules is leaders-only.
 
+## Rules file reference
+
+```json
+{
+  "whitespace": "ignore",
+  "groups": {"finance": ["bob", "carol"], "all": ["@finance", "dave"]},
+  "leaders": ["alice", "@org/platform"],
+  "locks": [
+    {"id": "billing", "owners": ["@finance"], "approvers": ["@all"]},
+    {"id": "py-core", "owners": ["bob"], "paths": ["src/core/"], "whitespace": "indent"}
+  ]
+}
+```
+
+- `groups`: reusable lists, referenced as `@name` (groups may contain groups).
+- `@org/team`: a platform team. The GitHub adapter resolves it through the API
+  (the token needs `read:org`); other adapters leave it unresolved, so it never
+  matches anybody. `tripwire validate` warns about this.
+- `whitespace`: `ignore` (default) treats re-indenting as no change; `indent`
+  keeps leading whitespace significant, for Python and similar. Set it globally
+  or per lock. Trailing whitespace and blank lines never count.
+- `paths`: `dir/` prefix or a glob (`*` also matches `/`).
+
+Helpers:
+
+```bash
+tripwire validate                                     # lint the rules against the repository
+tripwire import-codeowners --leader alice --write     # start from an existing CODEOWNERS
+```
+
+`import-codeowners` turns every CODEOWNERS pattern into a path lock. CODEOWNERS
+applies "last match wins"; tripwire locks are additive, so it is stricter only
+where a later pattern deliberately narrows an earlier one. Sections and email
+owners are skipped with a warning. Set `leaders` before relying on the result.
+
 ## Commands
 
 ```bash
@@ -149,7 +184,8 @@ path lock for the CI configuration, otherwise a PR can delete the check.
 
 **GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
 the PR's current head commit, so a new push voids it. Reviewer logins are
-matched to names in `locks.json` case-insensitively; teams are not supported.
+matched to names in `locks.json` case-insensitively; `@org/team` entries are
+resolved through the API.
 
 **GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
 approvals endpoint is not bound to a commit, so enable "Remove all approvals
@@ -176,8 +212,11 @@ reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
 - On every platform, people who can edit branch protection or CI settings are
   trusted; tripwire cannot stop an admin from switching the rule off.
 - Pushes with several authors are checked as one cumulative diff by the pusher.
-- Whitespace-insensitive comparison also ignores indentation changes.
-- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
+- By default re-indenting is not a change; set `"whitespace": "indent"` for
+  languages where indentation matters.
+- Platform teams (`@org/team`) are resolved on GitHub only (simulated API tests;
+  not run against a real organization).
+- Not yet: GitLab groups and Gitea teams, Bitbucket, Azure DevOps, Gerrit.
 
 ## Development
 

tripwire_git-0.2.1/PKG-INFO → tripwire_git-0.3.0/README.md

@@ -1,191 +1,211 @@
-Metadata-Version: 2.4
-Name: tripwire-git
-Version: 0.2.1
-Summary: Protect blocks of code in Git: changes need approval from an owner, an approver or a leader.
-License: MIT
-Keywords: git,code-owners,approval,pre-receive,ci
-Classifier: Development Status :: 3 - Alpha
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Topic :: Software Development :: Version Control :: Git
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Dynamic: license-file
-
-# tripwire
-
-Protect blocks of code in Git. A protected block can only be changed by its
-owner or a leader, or by someone whose change an authorized person approved.
-Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
-required check on GitHub, GitLab and Gitea / Forgejo.
-
-## Quick start
-
-1. Mark a block in any language, inside a comment:
-
-   ```python
-   # @lock-begin billing
-   RATE = 5
-   # @lock-end billing
-   ```
-
-2. Create `.tripwire/locks.json` (see `locks.example.json`):
-
-   ```json
-   {
-     "leaders": ["alice"],
-     "locks": [
-       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
-       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
-     ]
-   }
-   ```
-
-3. Check a change:
-
-   ```bash
-   pip install tripwire-git
-   tripwire preflight --actor dave        # uncommitted changes vs HEAD
-   ```
-
-   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
-   alice, bob, carol`, exit code 1.
-
-## Concepts
-
-- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
-  folders are locked with path patterns (`dir/` prefix or glob).
-- Owners and leaders may edit freely. Anyone else needs an approval from an
-  owner, an approver or a leader. You cannot approve your own change.
-- Approvals are bound to the exact before/after content of the protected
-  block (a SHA-256 digest). Edit the code again and the approval is void.
-- Rules are always read from the **base** revision (the target branch), so a
-  change cannot rewrite the rules that judge it. Changing the rules file is
-  leaders-only and cannot be approved.
-- Whitespace-only edits are ignored. Deleting markers counts as a change.
-  Unclosed blocks extend to end of file. A marker whose id is missing from the
-  rules is leaders-only.
-
-## Commands
-
-```bash
-tripwire preflight --actor alice                              # uncommitted changes vs HEAD
-tripwire check --base origin/main --head HEAD --actor alice   # a commit range
-tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
-tripwire preflight --staged                                   # staged changes only
-tripwire install-hook                                         # local pre-commit hook
-tripwire pre-receive                                          # server hook, reads stdin
-tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
-```
-
-Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
-
-## Local early warning
-
-`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
-and refuses the commit when a protected block is touched without permission
-(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
-identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
-`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
-server-side or CI check below remains the real gate. Nothing can stop someone
-from editing files in their own clone; tripwire stops unapproved changes from
-landing on protected branches.
-
-## AI coding agents (Claude Code)
-
-Stop an AI agent from changing protected code *before* it touches the disk:
-
-```bash
-tripwire install-claude-hook      # adds a PreToolUse hook to .claude/settings.json
-```
-
-The agent acts as its own identity (`TRIPWIRE_AI_ACTOR`, default `ai-agent`),
-which is not an owner unless you list it. When it tries to `Edit`, `MultiEdit`
-or `Write` a protected block, the call is refused with a message naming who may
-approve it, and the request is recorded. A human then approves that exact
-change **from an interactive terminal**; `grant` shows the request and makes
-the person type the approver's name to confirm (a pseudo-terminal alone is not
-trusted):
-
-```bash
-tripwire pending                                  # what was blocked
-tripwire grant <id> --approver anna               # the agent can now retry the same edit
-```
-
-The approval is bound to the exact before/after content, so a different edit
-is blocked again. To let the agent edit a block freely, list its identity as an
-owner of that lock. Rules are read from the committed version (`HEAD`), and the
-agent cannot edit the rules or approvals files, run `tripwire grant`, or touch
-those files through `Bash`.
-
-Limits: shell commands that rewrite files (`sed -i`, redirects, scripts) are not
-inspected, so keep the pre-commit hook and the server / CI check as backstops.
-`grant` trusts whoever runs it in a terminal; a person with shell access can
-also edit `.tripwire/approvals.json` by hand. Verified with simulated hook
-payloads and end to end with a live Claude Code 2.1 session: the edit was
-refused with the message shown to the agent, a human `grant` let the identical
-retry through, and the agent's own attempt to run `tripwire grant` did not
-approve anything.
-
-## Platforms
-
-| Platform | Enforce with | Approvals from | Verified |
-|---|---|---|---|
-| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
-| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
-| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
-| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
-
-On hosted services, also forbid direct pushes to the protected branch and add a
-path lock for the CI configuration, otherwise a PR can delete the check.
-
-**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
-`TRIPWIRE_ACTOR` from your server's authenticated user.
-
-**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
-the PR's current head commit, so a new push voids it. Reviewer logins are
-matched to names in `locks.json` case-insensitively; teams are not supported.
-
-**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
-approvals endpoint is not bound to a commit, so enable "Remove all approvals
-when commits are added to the source branch"; tripwire cannot verify it.
-
-**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
-reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
-`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
-
-## Architecture
-
-- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
-- `review.py`: shared pull / merge request check used by the platform adapters
-- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
-- `approvals.py`: local approvals file
-- `gitio.py`, `cli.py`: Git access and command line
-
-## Limits
-
-- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
-  trustworthy as whatever sets it. On hosted platforms it is the PR author.
-- The local approvals file is trust-based: anyone able to commit could write an
-  entry naming an approver. Use platform approvals for real deployments.
-- On every platform, people who can edit branch protection or CI settings are
-  trusted; tripwire cannot stop an admin from switching the rule off.
-- Pushes with several authors are checked as one cumulative diff by the pusher.
-- Whitespace-insensitive comparison also ignores indentation changes.
-- Not yet: platform teams, Bitbucket, Azure DevOps, Gerrit, CODEOWNERS import.
-
-## Development
-
-```bash
-pip install -e .[dev]
-pytest
-```
-
-## License
-
-MIT
+# tripwire
+
+Protect blocks of code in Git. A protected block can only be changed by its
+owner or a leader, or by someone whose change an authorized person approved.
+Works from a local pre-commit check, a self-hosted `pre-receive` hook, or as a
+required check on GitHub, GitLab and Gitea / Forgejo.
+
+## Quick start
+
+1. Mark a block in any language, inside a comment:
+
+   ```python
+   # @lock-begin billing
+   RATE = 5
+   # @lock-end billing
+   ```
+
+2. Create `.tripwire/locks.json` (see `locks.example.json`):
+
+   ```json
+   {
+     "leaders": ["alice"],
+     "locks": [
+       {"id": "billing", "owners": ["bob"], "approvers": ["carol"]},
+       {"id": "prod-config", "owners": ["bob"], "paths": ["config/prod/", "*.pem"]}
+     ]
+   }
+   ```
+
+3. Check a change:
+
+   ```bash
+   pip install tripwire-git
+   tripwire preflight --actor dave        # uncommitted changes vs HEAD
+   ```
+
+   Output: `tripwire: BLOCKED` with `block 'billing' in app.py is locked; ask:
+   alice, bob, carol`, exit code 1.
+
+## Concepts
+
+- Blocks are marked with `@lock-begin <id>` / `@lock-end <id>`; files and
+  folders are locked with path patterns (`dir/` prefix or glob).
+- Owners and leaders may edit freely. Anyone else needs an approval from an
+  owner, an approver or a leader. You cannot approve your own change.
+- Approvals are bound to the exact before/after content of the protected
+  block (a SHA-256 digest). Edit the code again and the approval is void.
+- Rules are always read from the **base** revision (the target branch), so a
+  change cannot rewrite the rules that judge it. Changing the rules file is
+  leaders-only and cannot be approved.
+- Whitespace-only edits are ignored. Deleting markers counts as a change.
+  Unclosed blocks extend to end of file. A marker whose id is missing from the
+  rules is leaders-only.
+
+## Rules file reference
+
+```json
+{
+  "whitespace": "ignore",
+  "groups": {"finance": ["bob", "carol"], "all": ["@finance", "dave"]},
+  "leaders": ["alice", "@org/platform"],
+  "locks": [
+    {"id": "billing", "owners": ["@finance"], "approvers": ["@all"]},
+    {"id": "py-core", "owners": ["bob"], "paths": ["src/core/"], "whitespace": "indent"}
+  ]
+}
+```
+
+- `groups`: reusable lists, referenced as `@name` (groups may contain groups).
+- `@org/team`: a platform team. The GitHub adapter resolves it through the API
+  (the token needs `read:org`); other adapters leave it unresolved, so it never
+  matches anybody. `tripwire validate` warns about this.
+- `whitespace`: `ignore` (default) treats re-indenting as no change; `indent`
+  keeps leading whitespace significant, for Python and similar. Set it globally
+  or per lock. Trailing whitespace and blank lines never count.
+- `paths`: `dir/` prefix or a glob (`*` also matches `/`).
+
+Helpers:
+
+```bash
+tripwire validate                                     # lint the rules against the repository
+tripwire import-codeowners --leader alice --write     # start from an existing CODEOWNERS
+```
+
+`import-codeowners` turns every CODEOWNERS pattern into a path lock. CODEOWNERS
+applies "last match wins"; tripwire locks are additive, so it is stricter only
+where a later pattern deliberately narrows an earlier one. Sections and email
+owners are skipped with a warning. Set `leaders` before relying on the result.
+
+## Commands
+
+```bash
+tripwire preflight --actor alice                              # uncommitted changes vs HEAD
+tripwire check --base origin/main --head HEAD --actor alice   # a commit range
+tripwire approve --base origin/main --head HEAD --approver carol  # local approvals file
+tripwire preflight --staged                                   # staged changes only
+tripwire install-hook                                         # local pre-commit hook
+tripwire pre-receive                                          # server hook, reads stdin
+tripwire github-check | gitlab-check | gitea-check            # pull / merge requests
+```
+
+Exit codes: 0 allowed, 1 blocked, 2 error (fails closed).
+
+## Local early warning
+
+`tripwire install-hook` installs a `pre-commit` hook that checks staged changes
+and refuses the commit when a protected block is touched without permission
+(or use `.pre-commit-hooks.yaml` with the pre-commit framework). Your Git
+identity (`git config user.email`, or `TRIPWIRE_ACTOR`) must match a name in
+`locks.json`. This is a convenience: `git commit --no-verify` skips it, so the
+server-side or CI check below remains the real gate. Nothing can stop someone
+from editing files in their own clone; tripwire stops unapproved changes from
+landing on protected branches.
+
+## AI coding agents (Claude Code)
+
+Stop an AI agent from changing protected code *before* it touches the disk:
+
+```bash
+tripwire install-claude-hook      # adds a PreToolUse hook to .claude/settings.json
+```
+
+The agent acts as its own identity (`TRIPWIRE_AI_ACTOR`, default `ai-agent`),
+which is not an owner unless you list it. When it tries to `Edit`, `MultiEdit`
+or `Write` a protected block, the call is refused with a message naming who may
+approve it, and the request is recorded. A human then approves that exact
+change **from an interactive terminal**; `grant` shows the request and makes
+the person type the approver's name to confirm (a pseudo-terminal alone is not
+trusted):
+
+```bash
+tripwire pending                                  # what was blocked
+tripwire grant <id> --approver anna               # the agent can now retry the same edit
+```
+
+The approval is bound to the exact before/after content, so a different edit
+is blocked again. To let the agent edit a block freely, list its identity as an
+owner of that lock. Rules are read from the committed version (`HEAD`), and the
+agent cannot edit the rules or approvals files, run `tripwire grant`, or touch
+those files through `Bash`.
+
+Limits: shell commands that rewrite files (`sed -i`, redirects, scripts) are not
+inspected, so keep the pre-commit hook and the server / CI check as backstops.
+`grant` trusts whoever runs it in a terminal; a person with shell access can
+also edit `.tripwire/approvals.json` by hand. Verified with simulated hook
+payloads and end to end with a live Claude Code 2.1 session: the edit was
+refused with the message shown to the agent, a human `grant` let the identical
+retry through, and the agent's own attempt to run `tripwire grant` did not
+approve anything.
+
+## Platforms
+
+| Platform | Enforce with | Approvals from | Verified |
+|---|---|---|---|
+| Self-hosted Git | `hooks/pre-receive` | `.tripwire/approvals.json` | real git repos |
+| GitHub | required check, `templates/github-actions.yml` | PR reviews | real GitHub |
+| GitLab | required pipeline, `templates/gitlab-ci.yml` | MR approvals | simulated API only |
+| Gitea / Forgejo | required check, `templates/gitea-actions.yml` | PR reviews | simulated API only |
+
+On hosted services, also forbid direct pushes to the protected branch and add a
+path lock for the CI configuration, otherwise a PR can delete the check.
+
+**Self-hosted Git.** Copy `hooks/pre-receive` into the bare repo and set
+`TRIPWIRE_ACTOR` from your server's authenticated user.
+
+**GitHub.** Only a reviewer's latest review counts; it must be `APPROVED` on
+the PR's current head commit, so a new push voids it. Reviewer logins are
+matched to names in `locks.json` case-insensitively; `@org/team` entries are
+resolved through the API.
+
+**GitLab.** Store a `read_api` project access token as `GITLAB_TOKEN`. GitLab's
+approvals endpoint is not bound to a commit, so enable "Remove all approvals
+when commits are added to the source branch"; tripwire cannot verify it.
+
+**Gitea / Forgejo.** Enable "Dismiss stale approvals". Stale and dismissed
+reviews are ignored. The API base comes from `--gitea-url`, `GITEA_API_URL`,
+`GITHUB_API_URL` or `GITHUB_SERVER_URL`.
+
+## Architecture
+
+- `engine.py`: platform-neutral core (diff + actor + rules + approvals -> decision)
+- `review.py`: shared pull / merge request check used by the platform adapters
+- `github.py`, `gitlab.py`, `gitea.py`: API clients and approval mapping
+- `approvals.py`: local approvals file
+- `gitio.py`, `cli.py`: Git access and command line
+
+## Limits
+
+- Identity comes from `--actor` / `TRIPWIRE_ACTOR` locally; it is only as
+  trustworthy as whatever sets it. On hosted platforms it is the PR author.
+- The local approvals file is trust-based: anyone able to commit could write an
+  entry naming an approver. Use platform approvals for real deployments.
+- On every platform, people who can edit branch protection or CI settings are
+  trusted; tripwire cannot stop an admin from switching the rule off.
+- Pushes with several authors are checked as one cumulative diff by the pusher.
+- By default re-indenting is not a change; set `"whitespace": "indent"` for
+  languages where indentation matters.
+- Platform teams (`@org/team`) are resolved on GitHub only (simulated API tests;
+  not run against a real organization).
+- Not yet: GitLab groups and Gitea teams, Bitbucket, Azure DevOps, Gerrit.
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT

{tripwire_git-0.2.1 → tripwire_git-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tripwire-git"
-version = "0.2.1"
+version = "0.3.0"
 description = "Protect blocks of code in Git: changes need approval from an owner, an approver or a leader."
 readme = "README.md"
 requires-python = ">=3.9"

{tripwire_git-0.2.1 → tripwire_git-0.3.0}/src/tripwire/__init__.py

@@ -1,3 +1,3 @@
 """tripwire: approval-gated protection for blocks of code in Git."""
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"

{tripwire_git-0.2.1 → tripwire_git-0.3.0}/src/tripwire/blocks.py

@@ -9,12 +9,20 @@ END = re.compile(r"@lock-end\s+([A-Za-z0-9_.\-]+)")
 Norm = Tuple[str, ...]
 
 
-def normalize(text: str) -> Norm:
-    """Strip each line and drop blank lines, so whitespace-only edits don't count."""
-    return tuple(line.strip() for line in text.splitlines() if line.strip())
+def _clean(line: str, mode: str) -> str:
+    return line.rstrip() if mode == "indent" else line.strip()
 
 
-def extract_blocks(text: str) -> Dict[str, Norm]:
+def normalize(text: str, mode: str = "ignore") -> Norm:
+    """Drop blank lines and trailing whitespace.
+
+    mode "ignore" also strips leading whitespace, so re-indenting is not a change;
+    mode "indent" keeps it (for languages where indentation carries meaning).
+    """
+    return tuple(c for c in (_clean(line, mode) for line in text.splitlines()) if c.strip())
+
+
+def extract_blocks(text: str, mode: str = "ignore") -> Dict[str, Norm]:
     """Map block id -> normalized content between its markers.
 
     An unclosed block extends to the end of the file (fail closed).
@@ -34,8 +42,8 @@ def extract_blocks(text: str) -> Dict[str, Norm]:
                 open_ids.remove(end.group(1))
                 open_ids.reverse()
             continue
-        stripped = line.strip()
-        if stripped:
+        cleaned = _clean(line, mode)
+        if cleaned.strip():
             for block_id in open_ids:
-                content[block_id].append(stripped)
+                content[block_id].append(cleaned)
     return {k: tuple(v) for k, v in content.items()}

{tripwire_git-0.2.1 → tripwire_git-0.3.0}/src/tripwire/cli.py

@@ -243,6 +243,55 @@ def cmd_install_claude_hook(args, root: str) -> int:
     return 0
 
 
+def cmd_validate(args, root: str) -> int:
+    from .validate import validate
+
+    path = args.file or os.path.join(root, RULES_PATH)
+    if not os.path.isfile(path):
+        print("tripwire: %s not found" % path, file=sys.stderr)
+        return 2
+    with open(path, encoding="utf-8") as fh:
+        errors, warnings = validate(root, fh.read())
+    for e in errors:
+        print("error:   " + e, file=sys.stderr)
+    for w in warnings:
+        print("warning: " + w)
+    print("tripwire: %d error(s), %d warning(s)" % (len(errors), len(warnings)))
+    return 1 if errors else 0
+
+
+def cmd_import_codeowners(args, root: str) -> int:
+    from . import codeowners
+
+    source = args.file
+    if source is None:
+        for cand in codeowners.CANDIDATES:
+            if os.path.isfile(os.path.join(root, cand)):
+                source = os.path.join(root, cand)
+                break
+    if source is None or not os.path.isfile(source):
+        print("tripwire: no CODEOWNERS file found; pass --file", file=sys.stderr)
+        return 2
+    with open(source, encoding="utf-8") as fh:
+        entries, warnings = codeowners.parse(fh.read())
+    config = codeowners.to_config(entries, args.leader or [])
+    for w in warnings:
+        print("warning: " + w, file=sys.stderr)
+    text = json.dumps(config, indent=2) + "\n"
+    if not args.write:
+        sys.stdout.write(text)
+        return 0
+    target = os.path.join(root, RULES_PATH)
+    if os.path.exists(target) and not args.force:
+        print("tripwire: %s already exists; use --force to replace it" % RULES_PATH, file=sys.stderr)
+        return 1
+    os.makedirs(os.path.dirname(target), exist_ok=True)
+    with open(target, "w", encoding="utf-8") as fh:
+        fh.write(text)
+    print("tripwire: wrote %d lock(s) to %s; set leaders before relying on it" % (len(config["locks"]), RULES_PATH))
+    return 0
+
+
 def cmd_approve(args, root: str) -> int:
     config, decision = run_check(root, args.base, args.head, actor="")
     if config is None:
@@ -322,6 +371,17 @@ def build_parser() -> argparse.ArgumentParser:
     gr.add_argument("--approver", required=True)
     gr.set_defaults(func=cmd_grant)
 
+    v = sub.add_parser("validate", help="check the rules file against the repository")
+    v.add_argument("--file", help="rules file (default: .tripwire/locks.json)")
+    v.set_defaults(func=cmd_validate)
+
+    ic = sub.add_parser("import-codeowners", help="turn a CODEOWNERS file into path locks")
+    ic.add_argument("--file", help="CODEOWNERS path (default: search the usual places)")
+    ic.add_argument("--leader", action="append", help="leader name (repeatable)")
+    ic.add_argument("--write", action="store_true", help="write .tripwire/locks.json instead of printing")
+    ic.add_argument("--force", action="store_true", help="overwrite an existing rules file")
+    ic.set_defaults(func=cmd_import_codeowners)
+
     a = sub.add_parser("approve", help="record an approval for the pending change")
     a.add_argument("--base", required=True)
     a.add_argument("--head")