@jjanczur/tyran 0.1.52 → 0.1.53

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.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.52",
14
+ "version": "0.1.53",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.52",
3
+ "version": "0.1.53",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,101 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.53 — 2026-11-21
4
+
5
+ ### Path allowlists in a tracked gitleaks config apply, and a pathspec commit scans what it commits
6
+
7
+ Issue #105, points 1 and 3.
8
+
9
+ **Path allowlists.** The secrets gate piped every file into one
10
+ `gitleaks stdin` buffer, so every finding had an empty `File`. A `paths`
11
+ allowlist in a tracked `.gitleaks.toml` therefore never matched a real file,
12
+ and a fixture under `__tests__/` was refused whatever the config said. This is
13
+ the issue's AND case. Its OR case, a key under `src/` passing, did not
14
+ reproduce here with an allowlist regex that matches the empty string; that
15
+ case is now pinned as a guard. When a repository tracks a `.gitleaks.toml`,
16
+ the gate now writes the files it determined into a temporary tree and runs
17
+ `gitleaks dir` over it, so each file is scanned under its own path. Coverage
18
+ stays arithmetic. The scanner's trace must name every file written, as read or
19
+ as skipped by the allowlist and for no other reason, and the bytes it reports
20
+ must equal the sizes of the files it read. A scan that does not add up is
21
+ repeated over stdin, so a scanner change costs a false refusal, never a missed
22
+ key. A push range holding several versions of one path is split into rounds,
23
+ with one path per round under case and Unicode folding. Labels that are not
24
+ plain relative paths, and files gitleaks would read as its own configuration
25
+ (`.gitleaks*`), stay on stdin. A repository with no tracked config is scanned
26
+ exactly as before, because gitleaks' default config allowlists paths of its
27
+ own (lock files, images).
28
+
29
+ One consequence for a repository whose tracked config says
30
+ `[extend] useDefault = true`: gitleaks' default path allowlist now applies to
31
+ it too. Measured on 8.30.1, a key in `package-lock.json`, `yarn.lock`,
32
+ `go.sum`, a `.png` or a `.svg` is skipped by that allowlist. Over stdin it was
33
+ refused. A key under `vendor/` is still read. A file under `node_modules/` is
34
+ neither read nor reported by `gitleaks dir`. The accounting notices that and
35
+ scans it over stdin, where it is refused.
36
+
37
+ **Pathspec commits.** `git commit -m x -- b.txt` commits the working-tree
38
+ content of `b.txt` and nothing else that is staged. The gate scanned the whole
39
+ index instead. A key staged in another file refused the commit, and a key in
40
+ an unstaged edit of `b.txt` was published unscanned. `planCommand` now reads
41
+ the pathspec (`commitPathspec`), and the scan is the diff from `HEAD` to the
42
+ working tree for those paths. `--include` scans the index plus those paths.
43
+ The pathspec is narrowed on only under three conditions:
44
+
45
+ - it comes from the quote-aware reading with every quote closed;
46
+ - every word after the verb is understood;
47
+ - every path matches a tracked file (`git ls-files --error-unmatch`).
48
+
49
+ Each of these leaves the commit scanned whole:
50
+
51
+ - an unknown flag, a short cluster, `-a` or `--pathspec-from-file`;
52
+ - a glob, pathspec magic, a `#` comment or a word the shell would expand;
53
+ - a message read as paths: `-m "update b.txt"`, or unquoted words
54
+ (`git commit -m fix the bug`), which git refuses as pathspecs anyway.
55
+
56
+ With no `HEAD` yet, the index and the working tree are scanned. The diffs pass
57
+ `--no-relative`, so a `diff.relative` setting cannot move the paths they print.
58
+
59
+ **Found on the way: last-wins, again.** The commit side of `planCommand` had
60
+ the shape fixed for pushes in 0.1.52.
61
+
62
+ - **Two commits in one line.** The second commit's plan replaced the first's.
63
+ `git commit -am a && git commit -m b` lost the first commit's `-a`, so an
64
+ unstaged key it committed was not scanned. A second commit now only widens
65
+ the scan, and is never narrowed.
66
+ - **Two adds before a commit.** `git add a && git add b && git commit` kept
67
+ only `b`. Every add now folds in.
68
+ - **An add in a subdirectory.** `cd sub && git add new.pem && git commit` read
69
+ the added file at the repository root: `new.pem`, not `sub/new.pem`. It found
70
+ nothing there, and the commit published the file unscanned. Added paths are
71
+ now absolute, resolved where the `git add` ran, and an add folds into the
72
+ commit even when a `cd` lies between them.
73
+
74
+ 23 tests in `hook-secrets-gate-paths.test.mjs`; on 0.1.52, 15 are red. Five
75
+ of the 15 drive `scanTree` with a scripted scanner trace, and each of these is
76
+ not trusted:
77
+
78
+ - a file the trace does not name;
79
+ - a skip for another reason;
80
+ - a byte count that disagrees;
81
+ - a path the gate never wrote.
82
+
83
+ Eight more are guards that pass on both versions: a message that looks like a
84
+ pathspec, `--include`, no `HEAD`, a `node_modules/` file, and others. Five
85
+ mutants were run against the file, and each turns at least one test red:
86
+
87
+ - the per-file accounting;
88
+ - the byte check;
89
+ - the skip-reason check;
90
+ - the tracked-config switch;
91
+ - the add-folding.
92
+
93
+ Still open: #105 point 2. A file created in the same command that commits it
94
+ (`printf ... > f && git add f && git commit`) is read before it exists, and is
95
+ scanned as empty. The same goes for a new file under a directory named to
96
+ `git add` (`git add src/ && git commit`): the directory is not a file, and the
97
+ untracked files under it are not read.
98
+
3
99
  ## 0.1.52 — 2026-11-21
4
100
 
5
101
  ### Both gates judge every push on a command line, not only the last one
package/README.md CHANGED
@@ -329,7 +329,7 @@ enforces the cap (3947 of 5000 characters). What each one assumes, when it
329
329
  fires and who invokes it, is in
330
330
  [skills and agents](https://jjanczur.github.io/tyran/skills/); the prompts
331
331
  themselves are in [`skills/`](skills/) and [`agents/`](agents/). Behind all of
332
- it: 1794 unit tests, run with `node --test "tests/**/*.test.mjs"`.
332
+ it: 1817 unit tests, run with `node --test "tests/**/*.test.mjs"`.
333
333
 
334
334
  ## Documentation
335
335
 
@@ -63,9 +63,9 @@
63
63
  */
64
64
  import { spawn } from 'node:child_process';
65
65
  import { realpathSync, statSync } from 'node:fs';
66
- import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
66
+ import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
67
67
  import { homedir, tmpdir } from 'node:os';
68
- import { basename, dirname, join, resolve as resolvePath } from 'node:path';
68
+ import { basename, dirname, join, relative, resolve as resolvePath, sep } from 'node:path';
69
69
  import { fileURLToPath } from 'node:url';
70
70
 
71
71
  import { PASS, field, main, runGate } from './hook-io.mjs';
@@ -379,9 +379,10 @@ export function tokensOf(segment) {
379
379
  * `splitSegments` stays quote-blind (see SEPARATORS) still holds.
380
380
  *
381
381
  * Nothing is expanded: `$VAR`, globs and `~` stay literal and still fail
382
- * `isLiteralPath`. A quote still open at the end of the segment, which is what
383
- * a quote-blind split through a quoted value looks like, simply ends the last
384
- * word; `quotedSeparatorHidesVerb` is what reads that shape.
382
+ * `isLiteralPath`. `closed` is false when a quote is still open at the end of
383
+ * the segment, which is what a quote-blind split through a quoted value looks
384
+ * like; `quotedSeparatorHidesVerb` is what reads that shape, and a caller that
385
+ * narrows anything from these words must not do it from an open quote.
385
386
  */
386
387
  export function shellWords(segment) {
387
388
  const text = String(segment);
@@ -424,7 +425,7 @@ export function shellWords(segment) {
424
425
  }
425
426
  }
426
427
  if (inWord) words.push(word);
427
- return { words };
428
+ return { words, closed: quote === null };
428
429
  }
429
430
 
430
431
  /** `NAME=value` in the program slot: an assignment for the command after it. */
@@ -479,6 +480,79 @@ export function gitInvocation(words) {
479
480
  return { index, words: all, tokens: all.slice(index), env };
480
481
  }
481
482
 
483
+ /** `git commit` options that take no value and leave the pathspec readable. */
484
+ const COMMIT_BARE_FLAGS = new Set([
485
+ '-q', '--quiet', '-v', '--verbose', '-s', '--signoff', '--no-signoff', '-e', '--edit', '--no-edit',
486
+ '--amend', '--no-post-rewrite', '--allow-empty', '--allow-empty-message', '--dry-run', '--short',
487
+ '--branch', '--porcelain', '--long', '-z', '--null', '--reset-author', '--status', '--no-status',
488
+ '-S', '--gpg-sign', '--no-gpg-sign', '--verify', '-u', '--untracked-files',
489
+ ]);
490
+
491
+ /** `git commit` options whose value is the NEXT word unless it is attached. */
492
+ const COMMIT_VALUE_FLAGS = new Set([
493
+ '-m', '--message', '-F', '--file', '-C', '--reuse-message', '-c', '--reedit-message', '--author',
494
+ '--date', '--fixup', '--squash', '-t', '--template', '--cleanup', '--trailer',
495
+ ]);
496
+
497
+ /**
498
+ * The pathspec of a `git commit`, read from the words after the verb, or null
499
+ * when they cannot be read with certainty.
500
+ *
501
+ * A commit with a pathspec commits the WORKING-TREE content of the named
502
+ * paths and nothing else that is staged (`--only`, git's default), or the
503
+ * index plus those paths (`--include`). Scanning the whole index instead
504
+ * refused the commit for an unrelated staged key, and missed a key in an
505
+ * unstaged edit of a named path (issue #105, point 3).
506
+ *
507
+ * Narrowing a scan is the direction in which a misreading publishes a key, so
508
+ * this answers null for anything it does not positively understand: an
509
+ * unknown flag (it may take a value and shift every position after it), a
510
+ * short cluster, `-a` (git refuses it with paths), `--pathspec-from-file`, a
511
+ * path the shell would expand, a glob or pathspec magic (git's to expand, not
512
+ * this parser's). `{ paths: [] }` means "no pathspec": the commit is read as
513
+ * before.
514
+ */
515
+ export function commitPathspec(args) {
516
+ let only = false;
517
+ let include = false;
518
+ const paths = [];
519
+ for (let k = 0; k < args.length; k++) {
520
+ const t = args[k];
521
+ if (t === '--') {
522
+ paths.push(...args.slice(k + 1));
523
+ break;
524
+ }
525
+ if (!t.startsWith('-') || t === '-') {
526
+ paths.push(t);
527
+ continue;
528
+ }
529
+ if (COMMIT_VALUE_FLAGS.has(t)) {
530
+ if (k + 1 >= args.length) return null;
531
+ k++;
532
+ } else if (t.startsWith('--') && t.includes('=')) {
533
+ const name = t.slice(0, t.indexOf('='));
534
+ if (!COMMIT_VALUE_FLAGS.has(name) && name !== '--gpg-sign' && name !== '--untracked-files') return null;
535
+ } else if (/^-[mFCct]./.test(t) || /^-[Su]./.test(t)) {
536
+ // a short option with its value attached: `-mfix`, `-Skeyid`, `-uno`
537
+ } else if (t === '-o' || t === '--only') {
538
+ only = true;
539
+ } else if (t === '-i' || t === '--include') {
540
+ include = true;
541
+ } else if (!COMMIT_BARE_FLAGS.has(t)) {
542
+ return null;
543
+ }
544
+ }
545
+ if (paths.length === 0) return { paths: [], mode: null };
546
+ if (only && include) return null;
547
+ for (const p of paths) {
548
+ // `#` starts a comment: `git commit -m x # note` commits the whole index.
549
+ if (p === '' || p.startsWith(':') || p.startsWith('#') || [...EXPANSION_CHARS].some((c) => p.includes(c))) {
550
+ return null;
551
+ }
552
+ }
553
+ return { paths, mode: include ? 'include' : 'only' };
554
+ }
555
+
482
556
  /** The git verbs whose arguments decide what this gate scans. */
483
557
  const PUBLISHING_VERBS = Object.freeze(['commit', 'push', 'add']);
484
558
 
@@ -1059,23 +1133,61 @@ export function planCommand(command, startDir) {
1059
1133
  }
1060
1134
  // Naming files one by one is the commonest form an agent uses, and it
1061
1135
  // was the form round 2 left open: only `-A`/`.` folded anything in.
1062
- pendingAdd = { dir: addAt.dir, all: all || widen, paths: named };
1136
+ // Every `git add` in the line, not the last one: `git add a && git add b
1137
+ // && git commit` kept only `b`. The paths are absolute, resolved where
1138
+ // that add ran, so a later `cd` cannot change which file they name.
1139
+ pendingAdd = {
1140
+ all: (pendingAdd?.all ?? false) || all || widen,
1141
+ paths: [...new Set([...(pendingAdd?.paths ?? []), ...named.map((t) => resolvePath(addAt.dir, t))])],
1142
+ };
1063
1143
  }
1064
1144
 
1065
1145
  if (gitCommit) {
1066
1146
  const commitAll = commitAt.tokens.some((t) => t === '--all' || (isShortCluster(t) && t.includes('a')));
1067
- const sameRepo = pendingAdd !== null && pendingAdd.dir === commitAt.dir;
1147
+ // Any `git add` earlier in the line, not only one from the same
1148
+ // directory: `cd sub && git add x && cd .. && git commit` stages `x` in
1149
+ // the same repository from another directory, and the directories here
1150
+ // are as the shell sees them, not repositories. Folding in an add from
1151
+ // another repository scans more, never less.
1152
+ const sameRepo = pendingAdd !== null;
1153
+ // The pathspec is read only from the quote-aware reading, and only when
1154
+ // its quotes are closed: the whitespace reading turns `-m "add b.txt"`
1155
+ // into a pathspec `b.txt`, and narrowing on that would scan the wrong
1156
+ // file (see `commitPathspec`).
1157
+ const spec =
1158
+ quotedOp !== null && quotedOp.name === 'commit' && parsed.closed
1159
+ ? commitPathspec(quoted.tokens.slice(quotedOp.index + 1))
1160
+ : null;
1161
+ // One target per repository, and a line can commit twice. The second
1162
+ // commit's plan replaced the first's: its pathspec narrowed the first
1163
+ // commit's scan, and a missing `-a` dropped the first one's working
1164
+ // tree. Two commits are never narrowed, and every flag only widens.
1165
+ const prior = targets.get(commitAt.dir);
1166
+ const priorCommit = prior !== undefined && prior.scanCommit === true ? prior : null;
1167
+ const narrowed = spec !== null && spec.paths.length > 0 && priorCommit === null ? spec : null;
1068
1168
  note(commitAt.dir, {
1169
+ commitPaths: narrowed === null ? null : narrowed.paths,
1170
+ commitMode: narrowed === null ? null : narrowed.mode,
1171
+ // Where the pathspec is relative to: the directory the segment ran
1172
+ // in, not the repository root.
1173
+ commitFrom: commitAt.dir,
1069
1174
  scanCommit: true,
1070
1175
  // `git commit -a` stages tracked modifications as it runs, and
1071
1176
  // `git add X && git commit` stages them in an earlier segment of the
1072
1177
  // very same command line. In both cases the index at the moment this
1073
1178
  // gate runs is NOT what the commit will contain, so the working tree
1074
1179
  // is folded in. Round 1 declared this a limitation; closing it is
1075
- // cheaper than describing it.
1076
- includeWorktree: commitAll || sameRepo,
1077
- includeUntracked: sameRepo && pendingAdd.all,
1078
- includePaths: sameRepo ? pendingAdd.paths : [],
1180
+ // cheaper than describing it. A second commit in the line also folds
1181
+ // it in: the first one's pathspec, if it had one, committed from it.
1182
+ // So does a pathspec this commit carries but is not narrowed on.
1183
+ includeWorktree:
1184
+ commitAll ||
1185
+ sameRepo ||
1186
+ (spec !== null && spec.paths.length > 0 && narrowed === null) ||
1187
+ priorCommit?.includeWorktree === true ||
1188
+ (priorCommit?.commitPaths ?? null) !== null,
1189
+ includeUntracked: (sameRepo && pendingAdd.all) || priorCommit?.includeUntracked === true,
1190
+ includePaths: [...new Set([...(priorCommit?.includePaths ?? []), ...(sameRepo ? pendingAdd.paths : [])])],
1079
1191
  });
1080
1192
  triggers.push('a git commit (everything the commit would add is scanned)');
1081
1193
  }
@@ -1875,27 +1987,64 @@ export async function buildPayload(target, extraFiles, { runner, budget }) {
1875
1987
  };
1876
1988
 
1877
1989
  if (target !== null && target.scanCommit) {
1878
- const staged = parseRawDiff(
1879
- await git(['-C', target.dir, 'diff', '--cached', '--raw', '-z', '--no-renames', '--diff-filter=ACMR'], {
1880
- runner, timeoutMs: budget(GIT_BUDGET_MS), what: 'reading the staged index',
1881
- }),
1882
- );
1883
- assertComplete(0, staged.malformed, 'reading the staged index');
1884
- const wanted = [...staged.entries];
1885
- if (target.includeWorktree) {
1886
- const unstaged = parseRawDiff(
1887
- await git(['-C', target.dir, 'diff', '--raw', '-z', '--no-renames', '--diff-filter=ACMR'], {
1888
- runner, timeoutMs: budget(GIT_BUDGET_MS), what: 'reading unstaged modifications',
1889
- }),
1890
- );
1891
- assertComplete(0, unstaged.malformed, 'reading unstaged modifications');
1892
- wanted.push(...unstaged.entries);
1990
+ const rawDiff = async (args, what) => {
1991
+ const parsed = parseRawDiff(await git(args, { runner, timeoutMs: budget(GIT_BUDGET_MS), what }));
1992
+ assertComplete(0, parsed.malformed, what);
1993
+ return parsed.entries;
1994
+ };
1995
+ // `--no-relative`: with `diff.relative` set, a diff run from a
1996
+ // subdirectory prints paths relative to it, and every one would then be
1997
+ // read from the wrong place below.
1998
+ const DIFF = ['--raw', '-z', '--no-renames', '--no-relative', '--diff-filter=ACMR'];
1999
+ // A pathspec is relative to the directory the commit ran in, so these
2000
+ // diffs run THERE; their output paths are relative to the root either way.
2001
+ const from = target.commitFrom ?? target.dir;
2002
+ const paths = Array.isArray(target.commitPaths) && target.commitPaths.length > 0 ? target.commitPaths : null;
2003
+ // `--only` (git's default with a pathspec) commits the working-tree
2004
+ // content of the named paths over HEAD, and nothing else that is staged:
2005
+ // the diff from HEAD to the working tree, for those paths, is exactly
2006
+ // what it adds. With no HEAD yet there is nothing to diff from, and the
2007
+ // commit is scanned as a whole instead (see below).
2008
+ //
2009
+ // Narrowed only on PROOF that the pathspec names what git will commit:
2010
+ // every path must match a tracked file. Words that merely parse as paths
2011
+ // (`git commit -m fix the bug`) match nothing, git refuses that commit,
2012
+ // and the scan stays whole.
2013
+ const ok = (r) => r.spawned === true && r.timedOut !== true && r.code === 0;
2014
+ let hasHead = false;
2015
+ if (paths !== null && target.commitMode === 'only') {
2016
+ hasHead =
2017
+ ok(await runner('git', ['-C', target.dir, 'rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], {
2018
+ timeoutMs: budget(GIT_BUDGET_MS),
2019
+ })) &&
2020
+ ok(await runner('git', ['-C', from, 'ls-files', '--error-unmatch', '--', ...paths], {
2021
+ timeoutMs: budget(GIT_BUDGET_MS),
2022
+ }));
2023
+ }
2024
+ const wanted = [];
2025
+ if (hasHead) {
2026
+ wanted.push(...(await rawDiff(['-C', from, 'diff', 'HEAD', ...DIFF, '--', ...paths], 'reading the paths this commit names')));
2027
+ } else {
2028
+ wanted.push(...(await rawDiff(['-C', target.dir, 'diff', '--cached', ...DIFF], 'reading the staged index')));
2029
+ if (paths !== null && target.commitMode === 'include' && !target.includeWorktree) {
2030
+ // `--include`: the index, plus the named paths as they are on disk.
2031
+ wanted.push(...(await rawDiff(['-C', from, 'diff', ...DIFF, '--', ...paths], 'reading the paths this commit names')));
2032
+ } else if (target.includeWorktree || paths !== null) {
2033
+ // A pathspec this gate could not narrow on (no HEAD) still commits
2034
+ // the named paths' working-tree content, so the working tree is folded
2035
+ // in: wider than the commit, never narrower.
2036
+ wanted.push(...(await rawDiff(['-C', target.dir, 'diff', ...DIFF], 'reading unstaged modifications')));
2037
+ }
1893
2038
  }
1894
2039
  // Files named on a `git add <path>` earlier in the same command line. They
1895
2040
  // are not in the index yet and may not be modifications of a tracked file
1896
- // at all, so neither diff above can see them.
1897
- for (const rel of target.includePaths ?? []) {
1898
- add(rel, await readFileBounded(join(target.dir, rel)));
2041
+ // at all, so neither diff above can see them. They are read where that
2042
+ // `git add` ran: joining them to the repository ROOT read `sub/new.pem`
2043
+ // as `new.pem` when the add ran in `sub/`, found nothing there, and the
2044
+ // commit published it unscanned.
2045
+ for (const path of target.includePaths ?? []) {
2046
+ const abs = resolvePath(target.dir, path);
2047
+ add(repoLabel(target.dir, abs), await readFileBounded(abs));
1899
2048
  }
1900
2049
  if (target.includeUntracked) {
1901
2050
  const listed = await git(['-C', target.dir, 'ls-files', '-z', '--others', '--exclude-standard'], {
@@ -1946,6 +2095,22 @@ export async function buildPayload(target, extraFiles, { runner, budget }) {
1946
2095
  add(file.shown, await readFileBounded(file.path));
1947
2096
  }
1948
2097
 
2098
+ const { bytes, map } = assemble(chunks);
2099
+ if (bytes.length > MAX_PAYLOAD_BYTES) {
2100
+ throw new ScanFailure(
2101
+ `this would publish ${bytes.length} bytes, past the ${MAX_PAYLOAD_BYTES} this gate can scan inside its budget`,
2102
+ 'commit or push in smaller steps. The gate refuses rather than scanning a prefix: a partial ' +
2103
+ 'scan that reports nothing looks exactly like a clean one.',
2104
+ );
2105
+ }
2106
+ return { bytes, map, chunks, files: chunks.length };
2107
+ }
2108
+
2109
+ /**
2110
+ * Chunks as ONE byte stream for `gitleaks stdin`, with a line map back to
2111
+ * their labels.
2112
+ */
2113
+ export function assemble(chunks) {
1949
2114
  const parts = [];
1950
2115
  const map = [];
1951
2116
  let line = 1;
@@ -1961,15 +2126,211 @@ export async function buildPayload(target, extraFiles, { runner, budget }) {
1961
2126
  parts.push(chunk.body, Buffer.from('\n\n'));
1962
2127
  line += newlines + 2;
1963
2128
  }
1964
- const bytes = Buffer.concat(parts);
1965
- if (bytes.length > MAX_PAYLOAD_BYTES) {
2129
+ return { bytes: Buffer.concat(parts), map };
2130
+ }
2131
+
2132
+ /**
2133
+ * The repository-relative label of a file named on the command line, or the
2134
+ * path as given when it is not inside the repository. Both sides are
2135
+ * canonicalized, because the shell's spelling of a directory and git's
2136
+ * `--show-toplevel` disagree wherever a symlink sits on the way (`/var` and
2137
+ * `/private/var` on macOS).
2138
+ */
2139
+ function repoLabel(top, abs) {
2140
+ const canonical = (p) => {
2141
+ try {
2142
+ return realpathSync(p);
2143
+ } catch {
2144
+ return p;
2145
+ }
2146
+ };
2147
+ const rel = relative(canonical(top), join(canonical(dirname(abs)), basename(abs)));
2148
+ return rel.split(sep).join('/');
2149
+ }
2150
+
2151
+ // --------------------------------------------------------- scanning by path
2152
+
2153
+ /**
2154
+ * A chunk label as a path the gate may write into a scan tree, or null.
2155
+ *
2156
+ * Only a plain relative path qualifies: no `..`, no empty or `.` segment, no
2157
+ * absolute path, nothing under `.git/`, and no file whose name gitleaks reads
2158
+ * as its OWN configuration when it finds one in the tree it scans
2159
+ * (`.gitleaks.toml`, `.gitleaksignore`, measured: a `.gitleaksignore` at the
2160
+ * root of the tree suppressed a finding even with `--gitleaks-ignore-path`
2161
+ * pointing elsewhere). A label that does not qualify is scanned the old way.
2162
+ */
2163
+ function treePath(label) {
2164
+ if (typeof label !== 'string' || label === '' || label.length > 4096) return null;
2165
+ if (label.startsWith('/') || label.includes('\\') || label.includes('\u0000')) return null;
2166
+ const parts = label.split('/');
2167
+ if (parts.some((p) => p === '' || p === '.' || p === '..' || Buffer.byteLength(p, 'utf8') > 255)) return null;
2168
+ if (parts[0] === '.git' || basename(label).startsWith('.gitleaks')) return null;
2169
+ return label;
2170
+ }
2171
+
2172
+ /** How many trees one payload may be split into before the rest goes to stdin. */
2173
+ export const MAX_PATH_ROUNDS = 4;
2174
+
2175
+ /**
2176
+ * Split chunks into ROUNDS that can each be written as one tree, and the
2177
+ * REST, which cannot be written as a tree at all.
2178
+ *
2179
+ * A push range carries several versions of one path, and a disk may fold case
2180
+ * or Unicode normalization, so two labels can name one file; and a path can
2181
+ * be a file in one commit and a directory in another. Each round holds every
2182
+ * path at most once, under that folding, and never a file where another
2183
+ * path needs a directory. A chunk that fits no round within `maxRounds`, and
2184
+ * a chunk whose label is no plain relative path (`treePath`), goes to `rest`
2185
+ * and is scanned exactly as before this existed.
2186
+ */
2187
+ export function pathScanRounds(chunks, maxRounds = MAX_PATH_ROUNDS) {
2188
+ const rounds = [];
2189
+ const rest = [];
2190
+ for (const chunk of chunks) {
2191
+ const path = treePath(chunk.label);
2192
+ if (path === null) {
2193
+ rest.push(chunk);
2194
+ continue;
2195
+ }
2196
+ const key = path.normalize('NFC').toLowerCase();
2197
+ const segments = key.split('/');
2198
+ const parents = segments.slice(0, -1).map((_, i) => segments.slice(0, i + 1).join('/'));
2199
+ const round = rounds.find(
2200
+ (r) => !r.files.has(key) && !r.dirs.has(key) && !parents.some((d) => r.files.has(d)),
2201
+ );
2202
+ if (round !== undefined) {
2203
+ round.chunks.push(chunk);
2204
+ round.files.add(key);
2205
+ for (const d of parents) round.dirs.add(d);
2206
+ } else if (rounds.length < maxRounds) {
2207
+ rounds.push({ chunks: [chunk], files: new Set([key]), dirs: new Set(parents) });
2208
+ } else {
2209
+ rest.push(chunk);
2210
+ }
2211
+ }
2212
+ return { rounds: rounds.map((r) => r.chunks), rest };
2213
+ }
2214
+
2215
+ /** One trace line of `gitleaks dir`: a file it read, or one it skipped and why. */
2216
+ const TRACE_LINE = /\b(?:TRC|DBG) (scanning path|skipping file: ([^=]*?)) path=(.*)$/;
2217
+
2218
+ /** A `path=` value from that trace, unquoted the way gitleaks quotes one with a space. */
2219
+ function tracePath(value) {
2220
+ const v = value.trim();
2221
+ if (!v.startsWith('"')) return v.replace(/^\.\//, '');
2222
+ try {
2223
+ return JSON.parse(v).replace(/^\.\//, '');
2224
+ } catch {
2225
+ return null;
2226
+ }
2227
+ }
2228
+
2229
+ /**
2230
+ * Scan chunks as FILES, under their own paths, so a tracked `.gitleaks.toml`
2231
+ * can allowlist a path (issue #105, point 1). Returns the findings, or null
2232
+ * when the scan's coverage could not be accounted for, and the caller scans
2233
+ * the same chunks over stdin instead.
2234
+ *
2235
+ * `gitleaks stdin` sees one nameless buffer, so every finding had `File: ""`
2236
+ * and a `paths` allowlist could never match: a fixture under `__tests__/` was
2237
+ * refused whatever the config said. `gitleaks dir` reads real paths and
2238
+ * applies the config's allowlists, and it SKIPS a file a path allowlist
2239
+ * matches, reading none of its bytes, so the stdin coverage rule ("read
2240
+ * exactly the bytes sent") cannot hold. The rule that replaces it is the same
2241
+ * arithmetic, per file: the scanner's trace must name EVERY file written,
2242
+ * either as read or as skipped by the allowlist and for no other reason, and
2243
+ * the bytes it reports must equal the sizes of the files it says it read.
2244
+ * Anything else (a file the trace does not name, another skip reason, a path
2245
+ * that will not parse, a byte count that disagrees) is not trusted, and those
2246
+ * chunks are scanned the old way: failing to use a path costs a false
2247
+ * refusal, never a missed key.
2248
+ *
2249
+ * The tree is written by this gate into an empty directory, so no file the
2250
+ * command did not determine can be in it, and nothing the scanner reads as
2251
+ * configuration (`treePath`). The config itself is passed explicitly; the
2252
+ * ignore path is always explicit too, so the default (`.`, the tree) is never
2253
+ * consulted.
2254
+ */
2255
+ export async function scanTree(chunks, { runner, budget, workDir, suppressionArgs = [] }) {
2256
+ const timeoutMs = budget(CHILD_BUDGET_MS);
2257
+ if (timeoutMs <= 0) {
1966
2258
  throw new ScanFailure(
1967
- `this would publish ${bytes.length} bytes, past the ${MAX_PAYLOAD_BYTES} this gate can scan inside its budget`,
1968
- 'commit or push in smaller steps. The gate refuses rather than scanning a prefix: a partial ' +
1969
- 'scan that reports nothing looks exactly like a clean one.',
2259
+ 'the gate ran out of its own budget before it could start the scan',
2260
+ 'raise DEADLINE_MS together with the timeout in hooks.json',
2261
+ );
2262
+ }
2263
+ const tree = await mkdtemp(join(workDir, 'tree-'));
2264
+ const sizes = new Map();
2265
+ try {
2266
+ for (const chunk of chunks) {
2267
+ const abs = join(tree, ...chunk.label.split('/'));
2268
+ await mkdir(dirname(abs), { recursive: true });
2269
+ // `wx`: a path that already exists is a collision `pathScanRounds`
2270
+ // should have prevented, and it must fail rather than overwrite.
2271
+ await writeFile(abs, chunk.body, { flag: 'wx' });
2272
+ sizes.set(chunk.label, chunk.body.length);
2273
+ }
2274
+ } catch {
2275
+ // A name this disk will not hold (too long, a folding `pathScanRounds`
2276
+ // did not foresee): those files are scanned over stdin instead.
2277
+ return null;
2278
+ }
2279
+ const ignoreArgs = [];
2280
+ if (!suppressionArgs.includes('--gitleaks-ignore-path')) {
2281
+ const empty = join(workDir, 'no-ignore');
2282
+ await writeFile(empty, '');
2283
+ ignoreArgs.push('--gitleaks-ignore-path', empty);
2284
+ }
2285
+ const reportPath = join(workDir, `report-${Math.random().toString(36).slice(2)}.json`);
2286
+ const args = [
2287
+ 'dir', '.',
2288
+ '--report-format', 'json',
2289
+ '--report-path', reportPath,
2290
+ '--no-banner',
2291
+ '--no-color',
2292
+ '--redact',
2293
+ '--log-level', 'trace',
2294
+ ...ignoreArgs,
2295
+ ...suppressionArgs,
2296
+ ];
2297
+ const result = await runner(GITLEAKS_BIN(), args, { cwd: tree, timeoutMs, env: scannerEnv() });
2298
+ if (!result.spawned) {
2299
+ if (result.error?.code === 'ENOENT') {
2300
+ throw new ScanFailure('gitleaks is not installed (or not on PATH)', INSTALL_INSTRUCTIONS);
2301
+ }
2302
+ throw new ScanFailure(`gitleaks could not be started (${result.error?.code ?? 'unknown error'})`, INSTALL_INSTRUCTIONS);
2303
+ }
2304
+ if (result.timedOut) {
2305
+ throw new ScanFailure(
2306
+ `the scan did not finish within ${timeoutMs} ms and was killed`,
2307
+ 'commit or push in smaller steps, or run gitleaks by hand',
1970
2308
  );
1971
2309
  }
1972
- return { bytes, map, files: chunks.length };
2310
+ const read = new Set();
2311
+ const skipped = new Set();
2312
+ let unaccounted = false;
2313
+ for (const line of String(result.stderr).split('\n')) {
2314
+ const m = TRACE_LINE.exec(line);
2315
+ if (m === null) continue;
2316
+ const path = tracePath(m[3]);
2317
+ if (path === null || !sizes.has(path)) unaccounted = true;
2318
+ else if (m[1] === 'scanning path') read.add(path);
2319
+ else if (m[2].trim() === 'global allowlist') skipped.add(path);
2320
+ else unaccounted = true;
2321
+ }
2322
+ const readBytes = [...read].reduce((n, p) => n + sizes.get(p), 0);
2323
+ const covered =
2324
+ !unaccounted &&
2325
+ [...sizes.keys()].every((p) => read.has(p) !== skipped.has(p)) &&
2326
+ parseScannedBytes(result.stderr) === readBytes;
2327
+ if (!covered) return null;
2328
+ return (await readReport(reportPath, result)).map((raw) => ({
2329
+ ...safeFinding(raw),
2330
+ line: null,
2331
+ label: typeof raw?.File === 'string' ? raw.File.replace(/^\.\//, '') : null,
2332
+ fileLine: Number.isInteger(raw?.StartLine) ? raw.StartLine : null,
2333
+ }));
1973
2334
  }
1974
2335
 
1975
2336
  // ------------------------------------------------------------------ scanner
@@ -2248,7 +2609,7 @@ export function locate(map, line) {
2248
2609
 
2249
2610
  export function renderFindings(findings, map) {
2250
2611
  const shown = findings.slice(0, MAX_FINDINGS_SHOWN).map((f) => {
2251
- const at = locate(map, f.line);
2612
+ const at = f.label !== undefined ? { label: f.label, line: f.fileLine } : locate(map, f.line);
2252
2613
  const where = at.label === null ? 'somewhere in the scanned payload' : JSON.stringify(shortPath(at.label));
2253
2614
  const line = at.line === null ? '' : `:${at.line}`;
2254
2615
  return ` - ${where}${line} — rule \`${safeRuleName(f.rule)}\``;
@@ -2384,23 +2745,43 @@ export async function decide({ input, cwd, runner = runChild, startedAt = Date.n
2384
2745
  suppressed.push(...supp.found);
2385
2746
  const payload = await buildPayload(resolved, index === 0 ? plan.extraFiles : [], { runner, budget });
2386
2747
  totalBytes += payload.bytes.length;
2387
- if (payload.bytes.length > 0) {
2748
+ // With a TRACKED config, every chunk that can be a file in a tree is
2749
+ // scanned under its own path, so the config's path allowlists apply
2750
+ // (`scanTree`). Without one nothing changes: gitleaks' default config
2751
+ // allowlists paths too (lock files, `vendor/`...), and applying that
2752
+ // here would pass what this gate refused before.
2753
+ const byPath = supp.found.some((f) => f.kind === 'config');
2754
+ const { rounds, rest } = byPath ? pathScanRounds(payload.chunks) : { rounds: [], rest: payload.chunks };
2755
+ const viaStdin = [...rest];
2756
+ let viaTree = 0;
2757
+ for (const round of rounds) {
2758
+ const found = await scanTree(round, { runner, budget, workDir, suppressionArgs: supp.args });
2759
+ if (found === null) {
2760
+ viaStdin.push(...round);
2761
+ } else {
2762
+ findings.push(...found);
2763
+ viaTree += round.length;
2764
+ }
2765
+ }
2766
+ const stream = assemble(viaStdin);
2767
+ if (stream.bytes.length > 0) {
2388
2768
  // The map and the FINDINGS have to move by the SAME amount, and by the
2389
2769
  // offset as it stood BEFORE this payload was added. Capturing it after
2390
2770
  // the increment shifted every finding by a whole payload and produced
2391
2771
  // "somewhere in the scanned payload" — a refusal that names nothing.
2392
2772
  const base = lineOffset;
2393
- for (const entry of payload.map) {
2773
+ for (const entry of stream.map) {
2394
2774
  map.push({ ...entry, from: entry.from + base, to: entry.to + base });
2395
2775
  }
2396
- const found = await scanBytes(payload.bytes, { runner, budget, workDir, suppressionArgs: supp.args });
2776
+ const found = await scanBytes(stream.bytes, { runner, budget, workDir, suppressionArgs: supp.args });
2397
2777
  findings.push(...found.map((f) => ({ ...f, line: f.line === null ? null : f.line + base })));
2398
- lineOffset += newlineCount(payload.bytes) + 2;
2778
+ lineOffset += newlineCount(stream.bytes) + 2;
2399
2779
  }
2400
2780
  scanned.push(
2401
2781
  resolved === null
2402
2782
  ? `${payload.files} uploaded file(s)`
2403
- : `${payload.files} object(s), ${payload.bytes.length} bytes, from ${shortPath(resolved.dir)}`,
2783
+ : `${payload.files} object(s), ${payload.bytes.length} bytes, from ${shortPath(resolved.dir)}` +
2784
+ (viaTree > 0 ? ` (${viaTree} of them by path, under the tracked ${SUPPRESSION_FILES.config})` : ''),
2404
2785
  );
2405
2786
  }
2406
2787
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.52",
3
+ "version": "0.1.53",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {