titer 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. titer-0.1.0/.agents/skills/verify-titer/SKILL.md +58 -0
  2. titer-0.1.0/.agents/skills/verify-titer/features/README.md +5 -0
  3. titer-0.1.0/.agents/skills/verify-titer/features/check-report.md +25 -0
  4. titer-0.1.0/.agents/skills/verify-titer/features/check-summary.md +26 -0
  5. titer-0.1.0/.agents/skills/verify-titer/features/init.md +24 -0
  6. titer-0.1.0/.claude/skills/verify-titer/SKILL.md +58 -0
  7. titer-0.1.0/.claude/skills/verify-titer/features/README.md +5 -0
  8. titer-0.1.0/.claude/skills/verify-titer/features/check-report.md +25 -0
  9. titer-0.1.0/.claude/skills/verify-titer/features/check-summary.md +26 -0
  10. titer-0.1.0/.claude/skills/verify-titer/features/init.md +24 -0
  11. titer-0.1.0/.gitignore +2 -0
  12. titer-0.1.0/CODING-STANDARDS.md +22 -0
  13. titer-0.1.0/Cargo.lock +1207 -0
  14. titer-0.1.0/Cargo.toml +40 -0
  15. titer-0.1.0/LICENSE-APACHE +202 -0
  16. titer-0.1.0/LICENSE-MIT +21 -0
  17. titer-0.1.0/PKG-INFO +166 -0
  18. titer-0.1.0/README.md +148 -0
  19. titer-0.1.0/action.yml +214 -0
  20. titer-0.1.0/docs/UBIQUITOUS-LANGUAGE.md +27 -0
  21. titer-0.1.0/pyproject.toml +26 -0
  22. titer-0.1.0/schema/report.schema.json +554 -0
  23. titer-0.1.0/src/check.rs +282 -0
  24. titer-0.1.0/src/cli.rs +279 -0
  25. titer-0.1.0/src/config.rs +414 -0
  26. titer-0.1.0/src/crap.rs +369 -0
  27. titer-0.1.0/src/detect.rs +312 -0
  28. titer-0.1.0/src/diff.rs +361 -0
  29. titer-0.1.0/src/exit.rs +8 -0
  30. titer-0.1.0/src/gate.rs +265 -0
  31. titer-0.1.0/src/git.rs +228 -0
  32. titer-0.1.0/src/imports.rs +778 -0
  33. titer-0.1.0/src/init/SKILL.md +60 -0
  34. titer-0.1.0/src/init/mod.rs +508 -0
  35. titer-0.1.0/src/lang/mod.rs +158 -0
  36. titer-0.1.0/src/lang/python.rs +283 -0
  37. titer-0.1.0/src/lang/ts.rs +296 -0
  38. titer-0.1.0/src/lib.rs +25 -0
  39. titer-0.1.0/src/main.rs +5 -0
  40. titer-0.1.0/src/mutate/agent.rs +122 -0
  41. titer-0.1.0/src/mutate/mod.rs +890 -0
  42. titer-0.1.0/src/mutate/operators.rs +756 -0
  43. titer-0.1.0/src/process.rs +334 -0
  44. titer-0.1.0/src/prove.rs +415 -0
  45. titer-0.1.0/src/report.rs +307 -0
  46. titer-0.1.0/src/runner/mod.rs +309 -0
  47. titer-0.1.0/src/runner/pytest.rs +364 -0
  48. titer-0.1.0/src/runner/unittest.rs +520 -0
  49. titer-0.1.0/src/runner/vitest.rs +385 -0
  50. titer-0.1.0/src/scan.rs +626 -0
  51. titer-0.1.0/src/session.rs +46 -0
  52. titer-0.1.0/src/summary.rs +960 -0
  53. titer-0.1.0/src/tmp.rs +88 -0
  54. titer-0.1.0/src/worktree.rs +171 -0
  55. titer-0.1.0/src/xml.rs +184 -0
  56. titer-0.1.0/tests/check_cli.rs +93 -0
  57. titer-0.1.0/tests/common/mod.rs +204 -0
  58. titer-0.1.0/tests/crap.rs +134 -0
  59. titer-0.1.0/tests/detect.rs +149 -0
  60. titer-0.1.0/tests/gate.rs +159 -0
  61. titer-0.1.0/tests/init.rs +221 -0
  62. titer-0.1.0/tests/mutate.rs +386 -0
  63. titer-0.1.0/tests/prove.rs +236 -0
  64. titer-0.1.0/tests/runner_pytest.rs +266 -0
  65. titer-0.1.0/tests/runner_unittest.rs +265 -0
  66. titer-0.1.0/tests/runner_vitest.rs +298 -0
  67. titer-0.1.0/tests/scan.rs +122 -0
  68. titer-0.1.0/tests/snapshot.rs +224 -0
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: verify-titer
3
+ description: Use to prove a change to the titer CLI works by running `titer check` and `titer init` on fixture git repos, the way an agent or CI job calls them, and capturing the JSON report, Markdown summary, annotations, and exit code.
4
+ ---
5
+
6
+ # verify-titer
7
+
8
+ titer is a CLI. A user runs it inside a git repo that has `titer.toml`. Verify a change by building this checkout's binary, building a fixture repo, running the command the change affects, and keeping its output as evidence.
9
+
10
+ ## Launch
11
+
12
+ Build the binary and the fixture runners once per session:
13
+
14
+ ```sh
15
+ cargo build
16
+ scripts/setup-fixture-deps.sh
17
+ ```
18
+
19
+ Ready signal: `cargo build` prints `Finished`, and the setup script prints `fixture deps ready in .../.fixture-deps`. Each drive is a short-lived process, so there is no PID to record.
20
+
21
+ ## Doctor
22
+
23
+ ```sh
24
+ target/debug/titer --version
25
+ grep -m1 '^version' Cargo.toml
26
+ ```
27
+
28
+ The two versions match. `.fixture-deps/venv/bin/python -m pytest --version` prints `pytest 9.2.0`.
29
+
30
+ ## Drive
31
+
32
+ `scripts/check.sh MODE [titer check args...]` builds a fixture repo with `scripts/action-fixture.sh`, runs `titer check --json --markdown --annotations` in it, and writes the evidence. MODE is `proven` (a new test fails on base) or `unproven` (a new test never exercises the change). Extra arguments go to `titer check`.
33
+
34
+ ```sh
35
+ .agents/skills/verify-titer/scripts/check.sh proven
36
+ .agents/skills/verify-titer/scripts/check.sh unproven --only prove
37
+ ```
38
+
39
+ It prints the evidence directory. For a scenario the two modes do not cover, build a repo by hand the way `scripts/action-fixture.sh` does: `git init -b main`, write `titer.toml`, commit a base, change files on a branch, then run `target/debug/titer check --json --markdown FILE`.
40
+
41
+ A real repo also works, such as a clone of a project that already has `titer.toml`. Clone it outside this checkout and run `target/debug/titer check --base <base sha> --json --markdown FILE` from its root. titer never modifies the checkout it runs in.
42
+
43
+ ## Evidence
44
+
45
+ `check.sh` writes to `${XDG_CACHE_HOME:-$HOME/.cache}/titer-verify/<UTC timestamp>-<mode>/`:
46
+
47
+ - `report.json`: the JSON report from stdout.
48
+ - `summary.md`: the `--markdown` summary, the same text the Action posts as a PR comment.
49
+ - `annotations.txt`: the `--annotations` workflow commands, which the Action prints so GitHub shows them on the diff.
50
+ - `stderr.txt` and `exit-code.txt`.
51
+
52
+ ## Cleanup
53
+
54
+ `check.sh` removes its fixture repo on exit. titer removes its own worktrees under `$TITER_TMPDIR`, which `check.sh` sets to a directory it also removes. Keep the evidence directory.
55
+
56
+ ## Features
57
+
58
+ See [features/README.md](features/README.md).
@@ -0,0 +1,5 @@
1
+ # titer features
2
+
3
+ - [check-summary.md](check-summary.md): the Markdown summary and annotations of `titer check`.
4
+ - [check-report.md](check-report.md): the JSON report and the gate's exit code.
5
+ - [init.md](init.md): `titer init`, which opts a repo in.
@@ -0,0 +1,25 @@
1
+ # check report
2
+
3
+ ## Sub-features
4
+
5
+ - `gate`: status, exit code, and reasons.
6
+ - `tests`: one entry per changed test, with its verdict and base failure message.
7
+ - `mutants`: one entry per mutant, with its outcome and `unchanged_from_base`.
8
+ - `findings` and `crap`.
9
+
10
+ ## How to reach it
11
+
12
+ `titer check --json` prints the report on stdout and exits with the gate's code: 0 pass, 1 fail, 2 could not run.
13
+
14
+ ## Driving it
15
+
16
+ ```sh
17
+ .agents/skills/verify-titer/scripts/check.sh proven # exit 0
18
+ .agents/skills/verify-titer/scripts/check.sh unproven # exit 1
19
+ ```
20
+
21
+ Check `exit-code.txt` and `report.json`. The report must match `schema/report.schema.json`.
22
+
23
+ ## Gotchas
24
+
25
+ - `--only` limits the tiers, which changes the headline and the gate reasons.
@@ -0,0 +1,26 @@
1
+ # check summary
2
+
3
+ ## Sub-features
4
+
5
+ - Headline: the gate result (passed, failed, could not run) and the evidence it rests on.
6
+ - Survivors, with a note when the mutated code is unchanged from base.
7
+ - Changed tests table, with each test's failure on base.
8
+ - All mutants table, and GitHub annotations.
9
+
10
+ ## How to reach it
11
+
12
+ `titer check --markdown FILE` writes the summary, and `--annotations FILE` writes the annotations. The GitHub Action (`action.yml`) passes both, posts the summary as the job summary and, with `comment: true`, as a PR comment, and prints the annotations so GitHub shows them on the diff.
13
+
14
+ ## Driving it
15
+
16
+ ```sh
17
+ .agents/skills/verify-titer/scripts/check.sh proven
18
+ .agents/skills/verify-titer/scripts/check.sh unproven
19
+ ```
20
+
21
+ Read `summary.md` and `annotations.txt` in the printed evidence directory.
22
+
23
+ ## Gotchas
24
+
25
+ - Without `--markdown`, no summary is written.
26
+ - The `proven` fixture has one survivor (`>` to `>=`) because no test pins the boundary. Its code is new, so the survivor has no unchanged-from-base note. To see the note, make a change that only reformats a base line, as in `tests/mutate.rs`.
@@ -0,0 +1,24 @@
1
+ # init
2
+
3
+ ## Sub-features
4
+
5
+ - Writes `titer.toml`, the pinned dev dependency, and the repo skill in `.agents/skills/titer/` and `.claude/skills/titer/`.
6
+ - `--dry-run` prints the plan. `--update` rewrites the skill and the pin.
7
+
8
+ ## How to reach it
9
+
10
+ `titer init` in a git repo without `titer.toml`.
11
+
12
+ ## Driving it
13
+
14
+ ```sh
15
+ d=$(mktemp -d "${XDG_CACHE_HOME:-$HOME/.cache}/titer-init.XXXXXX")
16
+ git -C "$d" init -q -b main
17
+ printf '[project]\nname = "x"\nversion = "0"\n' > "$d/pyproject.toml"
18
+ (cd "$d" && "$OLDPWD/target/debug/titer" init --dry-run)
19
+ rm -rf "$d"
20
+ ```
21
+
22
+ ## Gotchas
23
+
24
+ - The skill text comes from `src/init/SKILL.md`, compiled into the binary. Rebuild after editing it.
@@ -0,0 +1,58 @@
1
+ ---
2
+ name: verify-titer
3
+ description: Use to prove a change to the titer CLI works by running `titer check` and `titer init` on fixture git repos, the way an agent or CI job calls them, and capturing the JSON report, Markdown summary, annotations, and exit code.
4
+ ---
5
+
6
+ # verify-titer
7
+
8
+ titer is a CLI. A user runs it inside a git repo that has `titer.toml`. Verify a change by building this checkout's binary, building a fixture repo, running the command the change affects, and keeping its output as evidence.
9
+
10
+ ## Launch
11
+
12
+ Build the binary and the fixture runners once per session:
13
+
14
+ ```sh
15
+ cargo build
16
+ scripts/setup-fixture-deps.sh
17
+ ```
18
+
19
+ Ready signal: `cargo build` prints `Finished`, and the setup script prints `fixture deps ready in .../.fixture-deps`. Each drive is a short-lived process, so there is no PID to record.
20
+
21
+ ## Doctor
22
+
23
+ ```sh
24
+ target/debug/titer --version
25
+ grep -m1 '^version' Cargo.toml
26
+ ```
27
+
28
+ The two versions match. `.fixture-deps/venv/bin/python -m pytest --version` prints `pytest 9.2.0`.
29
+
30
+ ## Drive
31
+
32
+ `scripts/check.sh MODE [titer check args...]` builds a fixture repo with `scripts/action-fixture.sh`, runs `titer check --json --markdown --annotations` in it, and writes the evidence. MODE is `proven` (a new test fails on base) or `unproven` (a new test never exercises the change). Extra arguments go to `titer check`.
33
+
34
+ ```sh
35
+ .agents/skills/verify-titer/scripts/check.sh proven
36
+ .agents/skills/verify-titer/scripts/check.sh unproven --only prove
37
+ ```
38
+
39
+ It prints the evidence directory. For a scenario the two modes do not cover, build a repo by hand the way `scripts/action-fixture.sh` does: `git init -b main`, write `titer.toml`, commit a base, change files on a branch, then run `target/debug/titer check --json --markdown FILE`.
40
+
41
+ A real repo also works, such as a clone of a project that already has `titer.toml`. Clone it outside this checkout and run `target/debug/titer check --base <base sha> --json --markdown FILE` from its root. titer never modifies the checkout it runs in.
42
+
43
+ ## Evidence
44
+
45
+ `check.sh` writes to `${XDG_CACHE_HOME:-$HOME/.cache}/titer-verify/<UTC timestamp>-<mode>/`:
46
+
47
+ - `report.json`: the JSON report from stdout.
48
+ - `summary.md`: the `--markdown` summary, the same text the Action posts as a PR comment.
49
+ - `annotations.txt`: the `--annotations` workflow commands, which the Action prints so GitHub shows them on the diff.
50
+ - `stderr.txt` and `exit-code.txt`.
51
+
52
+ ## Cleanup
53
+
54
+ `check.sh` removes its fixture repo on exit. titer removes its own worktrees under `$TITER_TMPDIR`, which `check.sh` sets to a directory it also removes. Keep the evidence directory.
55
+
56
+ ## Features
57
+
58
+ See [features/README.md](features/README.md).
@@ -0,0 +1,5 @@
1
+ # titer features
2
+
3
+ - [check-summary.md](check-summary.md): the Markdown summary and annotations of `titer check`.
4
+ - [check-report.md](check-report.md): the JSON report and the gate's exit code.
5
+ - [init.md](init.md): `titer init`, which opts a repo in.
@@ -0,0 +1,25 @@
1
+ # check report
2
+
3
+ ## Sub-features
4
+
5
+ - `gate`: status, exit code, and reasons.
6
+ - `tests`: one entry per changed test, with its verdict and base failure message.
7
+ - `mutants`: one entry per mutant, with its outcome and `unchanged_from_base`.
8
+ - `findings` and `crap`.
9
+
10
+ ## How to reach it
11
+
12
+ `titer check --json` prints the report on stdout and exits with the gate's code: 0 pass, 1 fail, 2 could not run.
13
+
14
+ ## Driving it
15
+
16
+ ```sh
17
+ .agents/skills/verify-titer/scripts/check.sh proven # exit 0
18
+ .agents/skills/verify-titer/scripts/check.sh unproven # exit 1
19
+ ```
20
+
21
+ Check `exit-code.txt` and `report.json`. The report must match `schema/report.schema.json`.
22
+
23
+ ## Gotchas
24
+
25
+ - `--only` limits the tiers, which changes the headline and the gate reasons.
@@ -0,0 +1,26 @@
1
+ # check summary
2
+
3
+ ## Sub-features
4
+
5
+ - Headline: the gate result (passed, failed, could not run) and the evidence it rests on.
6
+ - Survivors, with a note when the mutated code is unchanged from base.
7
+ - Changed tests table, with each test's failure on base.
8
+ - All mutants table, and GitHub annotations.
9
+
10
+ ## How to reach it
11
+
12
+ `titer check --markdown FILE` writes the summary, and `--annotations FILE` writes the annotations. The GitHub Action (`action.yml`) passes both, posts the summary as the job summary and, with `comment: true`, as a PR comment, and prints the annotations so GitHub shows them on the diff.
13
+
14
+ ## Driving it
15
+
16
+ ```sh
17
+ .agents/skills/verify-titer/scripts/check.sh proven
18
+ .agents/skills/verify-titer/scripts/check.sh unproven
19
+ ```
20
+
21
+ Read `summary.md` and `annotations.txt` in the printed evidence directory.
22
+
23
+ ## Gotchas
24
+
25
+ - Without `--markdown`, no summary is written.
26
+ - The `proven` fixture has one survivor (`>` to `>=`) because no test pins the boundary. Its code is new, so the survivor has no unchanged-from-base note. To see the note, make a change that only reformats a base line, as in `tests/mutate.rs`.
@@ -0,0 +1,24 @@
1
+ # init
2
+
3
+ ## Sub-features
4
+
5
+ - Writes `titer.toml`, the pinned dev dependency, and the repo skill in `.agents/skills/titer/` and `.claude/skills/titer/`.
6
+ - `--dry-run` prints the plan. `--update` rewrites the skill and the pin.
7
+
8
+ ## How to reach it
9
+
10
+ `titer init` in a git repo without `titer.toml`.
11
+
12
+ ## Driving it
13
+
14
+ ```sh
15
+ d=$(mktemp -d "${XDG_CACHE_HOME:-$HOME/.cache}/titer-init.XXXXXX")
16
+ git -C "$d" init -q -b main
17
+ printf '[project]\nname = "x"\nversion = "0"\n' > "$d/pyproject.toml"
18
+ (cd "$d" && "$OLDPWD/target/debug/titer" init --dry-run)
19
+ rm -rf "$d"
20
+ ```
21
+
22
+ ## Gotchas
23
+
24
+ - The skill text comes from `src/init/SKILL.md`, compiled into the binary. Rebuild after editing it.
titer-0.1.0/.gitignore ADDED
@@ -0,0 +1,2 @@
1
+ /target
2
+ /.fixture-deps
@@ -0,0 +1,22 @@
1
+ # Coding standards
2
+
3
+ These rules apply to every change in this repo, in addition to `docs/UBIQUITOUS-LANGUAGE.md`.
4
+
5
+ ## Safety
6
+
7
+ - Never modify the user's checkout. Do not write to its working tree, index, stash, refs, or worktree list. Read git state with plumbing commands, and build trees with a temporary `GIT_INDEX_FILE`.
8
+ - Start every test process in its own process group through `process::run`. Kill only process groups that titer started.
9
+ - Put temporary files in a `tmp::RunDir`, which is disk-backed and removed on exit and on SIGINT.
10
+
11
+ ## Results
12
+
13
+ - Never report a kill or a survivor for a run that executed zero tests or only skipped tests. Report no result.
14
+ - Run tests through the repo's own command and the runner's native selection flags. Never use a custom loader.
15
+ - Add a field to the report only with a schema update: regenerate `schema/report.schema.json` with `cargo run -- schema > schema/report.schema.json`.
16
+
17
+ ## Code
18
+
19
+ - Rust stable, edition 2024. `cargo fmt`, and `cargo clippy --all-targets -- -D warnings` must pass.
20
+ - Return `anyhow::Result` from command-level code and typed errors where a caller branches on the cause.
21
+ - Test behavior through fixture git repos built inside the tests (`tests/common`). Unit-test pure logic next to the code.
22
+ - Comments say why, not what. ASCII only.