vouchington-tooling 0.57.0 → 0.59.0
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.
- package/README.md +26 -0
- package/dist/agent-issue-labels/ensure-labels.d.mts +17 -0
- package/dist/agent-issue-labels/ensure-labels.mjs +55 -0
- package/dist/agent-issue-labels/index.d.mts +5 -0
- package/dist/agent-issue-labels/index.mjs +3 -0
- package/dist/agent-issue-labels/label-policy.d.mts +21 -0
- package/dist/agent-issue-labels/label-policy.mjs +67 -0
- package/dist/agent-issue-labels/labels-from-paths.d.mts +9 -0
- package/dist/agent-issue-labels/labels-from-paths.mjs +54 -0
- package/dist/browser-session-runner/tail-queue.d.mts +1 -1
- package/dist/browser-session-runner/tail-queue.mjs +1 -1
- package/dist/cli/commands/agent-issue-labels.d.mts +2 -0
- package/dist/cli/commands/agent-issue-labels.mjs +17 -0
- package/dist/cli/commands/gitleaks-directory-scan.d.mts +4 -0
- package/dist/cli/commands/gitleaks-directory-scan.mjs +9 -0
- package/dist/cli/commands/transient-retry.d.mts +13 -0
- package/dist/cli/commands/transient-retry.mjs +68 -0
- package/dist/cli/index.mjs +14 -53
- package/dist/cli/parse-agent-issue-labels.d.mts +19 -0
- package/dist/cli/parse-agent-issue-labels.mjs +70 -0
- package/dist/cli/parse-forwarded-commands.d.mts +9 -0
- package/dist/cli/parse-forwarded-commands.mjs +6 -0
- package/dist/cli/parse.d.mts +11 -1
- package/dist/cli/parse.mjs +3 -0
- package/dist/cli/script-paths.d.mts +5 -0
- package/dist/cli/script-paths.mjs +48 -0
- package/dist/cli/usage.d.mts +1 -1
- package/dist/cli/usage.mjs +12 -0
- package/dist/dead-code/baseline.d.mts +19 -0
- package/dist/dead-code/baseline.mjs +124 -0
- package/dist/dead-code/child-command.d.mts +6 -0
- package/dist/dead-code/child-command.mjs +107 -0
- package/dist/dead-code/cli.d.mts +5 -0
- package/dist/dead-code/cli.mjs +71 -0
- package/dist/dead-code/entry-roots.d.mts +7 -0
- package/dist/dead-code/entry-roots.mjs +43 -0
- package/dist/dead-code/fixture-deadline.test-helpers.d.mts +1 -0
- package/dist/dead-code/fixture-deadline.test-helpers.mjs +9 -0
- package/dist/dead-code/gate.d.mts +29 -0
- package/dist/dead-code/gate.mjs +33 -0
- package/dist/dead-code/gate.test-helpers.d.mts +14 -0
- package/dist/dead-code/gate.test-helpers.mjs +35 -0
- package/dist/dead-code/index.d.mts +9 -0
- package/dist/dead-code/index.mjs +7 -0
- package/dist/dead-code/scan.d.mts +11 -0
- package/dist/dead-code/scan.mjs +37 -0
- package/dist/dead-code/tracked-snapshot.d.mts +2 -0
- package/dist/dead-code/tracked-snapshot.mjs +72 -0
- package/dist/index.d.mts +2 -0
- package/dist/index.mjs +1 -0
- package/dist/markdown/details-scope.d.mts +1 -1
- package/dist/markdown/details-scope.mjs +1 -1
- package/dist/transient-retry/attempts.d.mts +1 -1
- package/dist/transient-retry/attempts.mjs +1 -1
- package/dist/transient-retry/decision-evaluator.d.mts +3 -3
- package/dist/transient-retry/gh-api.d.mts +30 -0
- package/dist/transient-retry/gh-api.mjs +68 -0
- package/dist/transient-retry/github-actions-log.d.mts +7 -0
- package/dist/transient-retry/github-actions-log.mjs +33 -0
- package/dist/transient-retry/index.d.mts +15 -0
- package/dist/transient-retry/index.mjs +8 -0
- package/dist/transient-retry/log-stream.d.mts +12 -0
- package/dist/transient-retry/log-stream.mjs +39 -0
- package/dist/transient-retry/log-window.d.mts +18 -0
- package/dist/transient-retry/log-window.mjs +94 -0
- package/dist/transient-retry/rerun.d.mts +23 -0
- package/dist/transient-retry/rerun.mjs +68 -0
- package/dist/transient-retry/run-context-annotations.d.mts +7 -0
- package/dist/transient-retry/run-context-annotations.mjs +44 -0
- package/dist/transient-retry/run-context-jobs.d.mts +20 -0
- package/dist/transient-retry/run-context-jobs.mjs +54 -0
- package/dist/transient-retry/run-context-logs.d.mts +12 -0
- package/dist/transient-retry/run-context-logs.mjs +86 -0
- package/dist/transient-retry/run-context-rule-attempts.d.mts +14 -0
- package/dist/transient-retry/run-context-rule-attempts.mjs +65 -0
- package/dist/transient-retry/run-context-types.d.mts +49 -0
- package/dist/transient-retry/run-context-types.mjs +3 -0
- package/dist/transient-retry/run-context.d.mts +9 -0
- package/dist/transient-retry/run-context.mjs +25 -0
- package/dist/transient-retry/run-context.test-helpers.d.mts +16 -0
- package/dist/transient-retry/run-context.test-helpers.mjs +56 -0
- package/dist/transient-retry/types.d.mts +8 -7
- package/dist/vitest-diagnostics/vitest-worker-exit-diagnostics-reporter.mjs +1 -1
- package/dist/workflow-secrets-drift/cli.d.mts +10 -0
- package/dist/workflow-secrets-drift/cli.mjs +73 -0
- package/dist/workflow-secrets-drift/collect.d.mts +10 -0
- package/dist/workflow-secrets-drift/collect.mjs +70 -0
- package/dist/workflow-secrets-drift/drift.d.mts +22 -0
- package/dist/workflow-secrets-drift/drift.mjs +49 -0
- package/dist/workflow-secrets-drift/gh-parse.d.mts +5 -0
- package/dist/workflow-secrets-drift/gh-parse.mjs +41 -0
- package/dist/workflow-secrets-drift/gh.d.mts +4 -0
- package/dist/workflow-secrets-drift/gh.mjs +51 -0
- package/dist/workflow-secrets-drift/index.d.mts +11 -0
- package/dist/workflow-secrets-drift/index.mjs +6 -0
- package/dist/workflow-secrets-drift/inventory.d.mts +10 -0
- package/dist/workflow-secrets-drift/inventory.mjs +78 -0
- package/dist/workflow-secrets-drift/scopes.d.mts +12 -0
- package/dist/workflow-secrets-drift/scopes.mjs +56 -0
- package/dist/workflow-secrets-drift/settle.d.mts +3 -0
- package/dist/workflow-secrets-drift/settle.mjs +19 -0
- package/dist/workflow-secrets-drift/types.d.mts +33 -0
- package/dist/workflow-secrets-drift/types.mjs +1 -0
- package/package.json +16 -1
- package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
|
@@ -19,6 +19,12 @@ type ForwardedCommand = {
|
|
|
19
19
|
} | {
|
|
20
20
|
kind: 'nuget-central-version';
|
|
21
21
|
args: string[];
|
|
22
|
+
} | {
|
|
23
|
+
kind: 'verify-workflow-secrets';
|
|
24
|
+
args: string[];
|
|
25
|
+
} | {
|
|
26
|
+
kind: 'dead-code';
|
|
27
|
+
args: string[];
|
|
22
28
|
} | {
|
|
23
29
|
kind: 'swift-semantic-equal';
|
|
24
30
|
args: string[];
|
|
@@ -43,6 +49,9 @@ type ForwardedCommand = {
|
|
|
43
49
|
} | {
|
|
44
50
|
kind: 'worktree';
|
|
45
51
|
args: string[];
|
|
52
|
+
} | {
|
|
53
|
+
kind: 'transient-retry';
|
|
54
|
+
args: string[];
|
|
46
55
|
};
|
|
47
56
|
export declare function parseForwardedCommand(command: string | undefined, args: string[]): ForwardedCommand | undefined;
|
|
48
57
|
export {};
|
|
@@ -13,6 +13,10 @@ export function parseForwardedCommand(command, args) {
|
|
|
13
13
|
return { kind: 'prepare-vitest-reports', args };
|
|
14
14
|
if (command === 'nuget-central-version')
|
|
15
15
|
return { kind: 'nuget-central-version', args };
|
|
16
|
+
if (command === 'verify-workflow-secrets')
|
|
17
|
+
return { kind: 'verify-workflow-secrets', args };
|
|
18
|
+
if (command === 'dead-code')
|
|
19
|
+
return { kind: 'dead-code', args };
|
|
16
20
|
if (command === 'swift-semantic-equal')
|
|
17
21
|
return { kind: 'swift-semantic-equal', args };
|
|
18
22
|
if (command === 'post-review')
|
|
@@ -29,5 +33,7 @@ export function parseForwardedCommand(command, args) {
|
|
|
29
33
|
return { kind: 'mcp', args };
|
|
30
34
|
if (command === 'worktree')
|
|
31
35
|
return { kind: 'worktree', args };
|
|
36
|
+
if (command === 'transient-retry')
|
|
37
|
+
return { kind: 'transient-retry', args };
|
|
32
38
|
return undefined;
|
|
33
39
|
}
|
package/dist/cli/parse.d.mts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { type ParsedGhaArtifactsCleanup } from './parse-gha-artifacts-cleanup.mts';
|
|
2
|
+
import { type ParsedAgentIssueLabels } from './parse-agent-issue-labels.mts';
|
|
2
3
|
import { type ParsedStoryCoverage } from './parse-story-coverage.mts';
|
|
3
4
|
import { type ParsedGhaRuntimeAudit } from './parse-gha-runtime-audit.mts';
|
|
4
5
|
export type ParsedCli = {
|
|
@@ -40,6 +41,12 @@ export type ParsedCli = {
|
|
|
40
41
|
} | {
|
|
41
42
|
kind: 'nuget-central-version';
|
|
42
43
|
args: string[];
|
|
44
|
+
} | {
|
|
45
|
+
kind: 'verify-workflow-secrets';
|
|
46
|
+
args: string[];
|
|
47
|
+
} | {
|
|
48
|
+
kind: 'dead-code';
|
|
49
|
+
args: string[];
|
|
43
50
|
} | {
|
|
44
51
|
kind: 'swift-semantic-equal';
|
|
45
52
|
args: string[];
|
|
@@ -73,6 +80,9 @@ export type ParsedCli = {
|
|
|
73
80
|
} | {
|
|
74
81
|
kind: 'worktree';
|
|
75
82
|
args: string[];
|
|
83
|
+
} | {
|
|
84
|
+
kind: 'transient-retry';
|
|
85
|
+
args: string[];
|
|
76
86
|
} | {
|
|
77
87
|
kind: 'require-up-to-date';
|
|
78
88
|
remote: string;
|
|
@@ -97,7 +107,7 @@ export type ParsedCli = {
|
|
|
97
107
|
root?: string;
|
|
98
108
|
workflowDirectories?: string[];
|
|
99
109
|
actionDirectories?: string[];
|
|
100
|
-
} | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup | ParsedStoryCoverage;
|
|
110
|
+
} | ParsedGhaRuntimeAudit | ParsedGhaArtifactsCleanup | ParsedAgentIssueLabels | ParsedStoryCoverage;
|
|
101
111
|
export type ScriptCommand = 'gha-output' | 'gha-needs-results' | 'download-with-diagnostics' | 'download-optional-run-artifacts' | 'host-pressure-diagnostics' | 'allocate-browser-safe-ports' | 'diagnose-port-collision' | 'prepare-trivy-db' | 'check-cache-size' | 'make-shard-matrix' | 'load-runner-env' | 'clean-workspace' | 'install-github-release' | 'run-with-timeout' | 'lint-links' | 'materialize-pr-context' | 'wait-for-apt-locks' | 'install-playwright-chromium-arm64' | 'ghcr-package-retention' | 'harness-admission-lane' | 'harness-assert-gates' | 'gha-collaborator-trust';
|
|
102
112
|
export declare function parseCli(argv: readonly string[]): ParsedCli;
|
|
103
113
|
export declare function parseCommandHelp(command: string | undefined, rest: readonly string[]): {
|
package/dist/cli/parse.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { parseGhaArtifactsCleanup, } from "./parse-gha-artifacts-cleanup.mjs";
|
|
2
|
+
import { parseAgentIssueLabels } from "./parse-agent-issue-labels.mjs";
|
|
2
3
|
import { parseStoryCoverage } from "./parse-story-coverage.mjs";
|
|
3
4
|
import { parseGhaRuntimeAudit } from "./parse-gha-runtime-audit.mjs";
|
|
4
5
|
import { parseForwardedCommand } from "./parse-forwarded-commands.mjs";
|
|
@@ -64,6 +65,8 @@ export function parseCli(argv) {
|
|
|
64
65
|
return parseGhaWorkspacePolicy(rest);
|
|
65
66
|
if (command === 'gha-artifacts-cleanup')
|
|
66
67
|
return parseGhaArtifactsCleanup(rest);
|
|
68
|
+
if (command === 'agent-issue-labels')
|
|
69
|
+
return parseAgentIssueLabels(rest);
|
|
67
70
|
if (command === 'story-coverage')
|
|
68
71
|
return parseStoryCoverage(rest);
|
|
69
72
|
if (command !== undefined && SCRIPT_COMMANDS.has(command)) {
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
export const SCRIPT_PATHS = {
|
|
2
|
+
'gha-output': { command: 'bash', path: 'scripts/gha/write-github-multiline-output.sh' },
|
|
3
|
+
'gha-needs-results': { command: 'bash', path: 'scripts/gha/check-needs-results.sh' },
|
|
4
|
+
'download-with-diagnostics': {
|
|
5
|
+
command: 'bash',
|
|
6
|
+
path: 'scripts/gha/download-with-diagnostics.sh',
|
|
7
|
+
},
|
|
8
|
+
'download-optional-run-artifacts': {
|
|
9
|
+
command: 'bash',
|
|
10
|
+
path: 'scripts/gha/download-optional-run-artifacts.sh',
|
|
11
|
+
},
|
|
12
|
+
'host-pressure-diagnostics': {
|
|
13
|
+
command: 'bash',
|
|
14
|
+
path: 'scripts/gha/host-pressure-diagnostics.sh',
|
|
15
|
+
},
|
|
16
|
+
'allocate-browser-safe-ports': {
|
|
17
|
+
command: 'python3',
|
|
18
|
+
path: 'scripts/allocate-browser-safe-ports.py',
|
|
19
|
+
},
|
|
20
|
+
'diagnose-port-collision': {
|
|
21
|
+
command: 'bash',
|
|
22
|
+
path: 'scripts/gha/diagnose-port-collision.sh',
|
|
23
|
+
},
|
|
24
|
+
'prepare-trivy-db': { command: 'bash', path: 'scripts/gha/prepare-trivy-db.sh' },
|
|
25
|
+
'check-cache-size': { command: 'bash', path: 'scripts/gha/check-cache-size.sh' },
|
|
26
|
+
'make-shard-matrix': { command: 'bash', path: 'scripts/gha/make-shard-matrix.sh' },
|
|
27
|
+
'load-runner-env': { command: 'bash', path: 'scripts/gha/load-runner-env.sh' },
|
|
28
|
+
'clean-workspace': { command: 'bash', path: 'scripts/gha/clean-workspace.sh' },
|
|
29
|
+
'install-github-release': { command: 'bash', path: 'scripts/gha/install-github-release.sh' },
|
|
30
|
+
'run-with-timeout': { command: 'bash', path: 'scripts/gha/run-with-timeout.sh' },
|
|
31
|
+
'lint-links': { command: 'bash', path: 'scripts/gha/lint-links.sh' },
|
|
32
|
+
'materialize-pr-context': { command: 'bash', path: 'scripts/gha/materialize-pr-context.sh' },
|
|
33
|
+
'wait-for-apt-locks': { command: 'bash', path: 'scripts/gha/wait-for-apt-locks.sh' },
|
|
34
|
+
'install-playwright-chromium-arm64': {
|
|
35
|
+
command: 'bash',
|
|
36
|
+
path: 'scripts/gha/install-playwright-chromium-arm64.sh',
|
|
37
|
+
},
|
|
38
|
+
'ghcr-package-retention': { command: 'bash', path: 'scripts/gha/ghcr-package-retention.sh' },
|
|
39
|
+
'harness-admission-lane': {
|
|
40
|
+
command: 'bash',
|
|
41
|
+
path: 'scripts/gha/harness-admission-lane.sh',
|
|
42
|
+
},
|
|
43
|
+
'harness-assert-gates': { command: 'bash', path: 'scripts/gha/harness-assert-gates.sh' },
|
|
44
|
+
'gha-collaborator-trust': {
|
|
45
|
+
command: 'bash',
|
|
46
|
+
path: 'scripts/gha/gha-collaborator-trust.sh',
|
|
47
|
+
},
|
|
48
|
+
};
|
package/dist/cli/usage.d.mts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n runner-port-policy Print or validate a runner port policy\n with-host-lock Run a command under a host-wide lock\n host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\n gha-output Write a collision-safe multiline GITHUB_OUTPUT record\n gha-needs-results Fail if required GitHub Actions job results failed\n download-with-diagnostics Download a URL and report HTTP status on failure\n download-optional-run-artifacts Download optional artifacts from the current run\n host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot\n allocate-browser-safe-ports Allocate Fetch-safe localhost ports\n diagnose-port-collision Capture bounded localhost port diagnostics\n prepare-trivy-db Download the Trivy vulnerability database\n gha-artifacts-cleanup Delete classified GitHub Actions artifacts\n http-origin Validate an optional HTTP(S) origin\n vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file\n vitest-report-attempt Write or read a Vitest report-attempt marker\n prepare-vitest-reports Validate and select Vitest report JSON files\n pnpm-install Install a pnpm workspace with retry and release-age fail-fast\n check-cache-size Measure a path and decide whether to save a GHA cache\n make-shard-matrix Emit a [1..N] GitHub Actions shard matrix\n load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards\n clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate\n install-github-release Download a checksum-verified GitHub Release binary\n run-with-timeout Run a command with GNU timeout or a Perl fallback\n lint-links Two-pass lychee: internal links fail, external warn\n materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl\n wait-for-apt-locks Wait until apt/dpkg lock files are free\n install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json\n ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\n post-review Post one COMMENT review from a staged payload file\n stage-review-payload Validate a review payload file into a staging directory\n retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts\n link-skill Link one packaged skill into an explicit consumer directory\n retrospective-facts Gather immutable facts for a retrospective\n agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n worktree Reclaim finished git worktrees (dry run unless --yes)\n story-coverage Check component exports are imported by stories\n\nOptions:\n -h, --help Show this help\n -v, --version Print the package version\n\nrunner-port-policy\n (no args) Print the shipped policy as JSON\n --file <path> Validate and print a policy file\n --reserved <port> Print true if the port is reserved\n\nwith-host-lock\n --name <family>\n [--slots <n>]\n --timeout-seconds <n>\n [--command-timeout-seconds <n>]\n [--failure-diagnostics <absolute-script>]\n [--on-acquire-timeout fail|run-unlocked]\n -- <command> [args...]\n\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nworktree reclaim [--yes] [--json]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
|
1
|
+
export declare const USAGE = "Usage: vouchington <command> [options]\n\nCommands:\n runner-port-policy Print or validate a runner port policy\n with-host-lock Run a command under a host-wide lock\n host-storage Check free space on caller-supplied paths\n gha-runtime-audit Audit successful GitHub Actions job runtimes\n require-up-to-date Require HEAD to include a fetched remote branch\n fresh-base Classify the worktree against a remote base branch\n gitleaks-directory-scan Scan a directory with Gitleaks\n ast-grep-examples Run AST-grep rule examples\n ast-grep-pack Print shipped unconditional AST-grep pack paths as JSON\n gha-workspace-policy Check GitHub Actions workspace safety policy\n gha-output Write a collision-safe multiline GITHUB_OUTPUT record\n gha-needs-results Fail if required GitHub Actions job results failed\n download-with-diagnostics Download a URL and report HTTP status on failure\n download-optional-run-artifacts Download optional artifacts from the current run\n host-pressure-diagnostics Print a bounded host memory/OOM/PSI snapshot\n allocate-browser-safe-ports Allocate Fetch-safe localhost ports\n diagnose-port-collision Capture bounded localhost port diagnostics\n prepare-trivy-db Download the Trivy vulnerability database\n gha-artifacts-cleanup Delete classified GitHub Actions artifacts\n agent-issue-labels Map changed paths to labels; create missing repository labels\n http-origin Validate an optional HTTP(S) origin\n vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file\n vitest-report-attempt Write or read a Vitest report-attempt marker\n prepare-vitest-reports Validate and select Vitest report JSON files\n pnpm-install Install a pnpm workspace with retry and release-age fail-fast\n check-cache-size Measure a path and decide whether to save a GHA cache\n make-shard-matrix Emit a [1..N] GitHub Actions shard matrix\n load-runner-env Overlay a runner env file onto GITHUB_ENV with injection guards\n clean-workspace Reset a persistent-runner workspace with a fork-PR trust gate\n install-github-release Download a checksum-verified GitHub Release binary\n run-with-timeout Run a command with GNU timeout or a Perl fallback\n lint-links Two-pass lychee: internal links fail, external warn\n materialize-pr-context Dump PR title/body/files/diff/comments and #N crawl\n wait-for-apt-locks Wait until apt/dpkg lock files are free\n install-playwright-chromium-arm64 Install Playwright Chromium from browsers.json\n ghcr-package-retention Delete old GHCR package versions (KEEP_MIN or --main-history)\n harness-admission-lane Compute a GITHUB_RUN_ID admission lane for fleet fan-out\n harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled\n gha-collaborator-trust Classify authors as write-access collaborators or not\n nuget-central-version Validate a Directory.Packages.props PackageVersion delta\n verify-workflow-secrets Check a secret inventory against live repository and environment secrets\n dead-code Gate unused code against a committed jscpd baseline\n swift-semantic-equal Compare Swift sources ignoring comments and whitespace\n post-review Post one COMMENT review from a staged payload file\n stage-review-payload Validate a review payload file into a staging directory\n retrospective-transcript Format facts from Claude-compatible, Codex, or Grok transcripts\n link-skill Link one packaged skill into an explicit consumer directory\n retrospective-facts Gather immutable facts for a retrospective\n agent-blackboard Probe an Agent Blackboard deployment, classify distill sessions, manage snapshots\n mcp Serve the agent-blackboard journal tools over stdio (MCP)\n worktree Reclaim finished git worktrees (dry run unless --yes)\n story-coverage Check component exports are imported by stories\n transient-retry Rerun a failed GitHub Actions run when an injected rule matches\n\nOptions:\n -h, --help Show this help\n -v, --version Print the package version\n\nrunner-port-policy\n (no args) Print the shipped policy as JSON\n --file <path> Validate and print a policy file\n --reserved <port> Print true if the port is reserved\n\nwith-host-lock\n --name <family>\n [--slots <n>]\n --timeout-seconds <n>\n [--command-timeout-seconds <n>]\n [--failure-diagnostics <absolute-script>]\n [--on-acquire-timeout fail|run-unlocked]\n -- <command> [args...]\n\nhost-storage --path <path> [--path <path>...] [--minimum-free-bytes <bytes>] [--pnpm-store] [--docker-root] [--docker-desktop-path <path>] [--discovery-timeout-ms <ms>]\n\ngha-runtime-audit\n [--repository owner/name] Default GITHUB_REPOSITORY\n [--branch main]\n [--median-threshold-floor <seconds>] Off unless set. Must be below the ceiling\n [--median-threshold-ceiling <seconds>] Default 360. Flags a five-sample median above this\n --pr-workflow <name|/regex/> Repeatable\n --push-workflow <name|/regex/> Repeatable\n\nrequire-up-to-date --remote <name> --branch <name>\nfresh-base [--remote <name>] [--branch <name>] [--skip-fetch]\ngitleaks-directory-scan --config <path> [--directory <path>]\nast-grep-examples --rules <directory> --config <path>\nast-grep-pack\ngha-workspace-policy [--root <directory>] [--workflow-directory <directory>] [--action-directory <directory>]\n\ngha-output <name>\ngha-needs-results [label]\ndownload-with-diagnostics <url> <destination> [-- curl-args...]\ndownload-optional-run-artifacts (--name <name>... | --pattern <pattern>) --dir <directory>\nhost-pressure-diagnostics\nallocate-browser-safe-ports <count> [--policy path] [--forbidden-ports path]\ndiagnose-port-collision [--ports \"2200 2216\"] [--output-dir PATH]\nprepare-trivy-db\ngha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\ngha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]\nagent-issue-labels labels-from-paths [--labeler <path>] <path>...\nagent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...\nhttp-origin [--field NAME] [value]\nvitest-blob-manifest <suite> [reports-directory]\nvitest-report-attempt <write DIRECTORY SUITE|read ROOT>\nprepare-vitest-reports [primary-directory] [fallback-directory] [output-directory]\npnpm-install --runner-lifecycle persistent|ephemeral|ephemeral-full --install-scripts true|false\ncheck-cache-size <path> <max-bytes> <label>\nmake-shard-matrix <total>\nload-runner-env\nclean-workspace\ninstall-github-release --repo owner/name --version X --asset 'name-{platform}.tar.gz' --bin name [--tag-prefix PREFIX] [--expected-sha256 SHA256] [--no-checksum] [--checksums-asset NAME] [--version-flag FLAG] [--bin-dir DIR]\nrun-with-timeout <timeout-seconds> <kill-after-seconds> <command...>\nlint-links [--offline] [--config PATH] [--glob PATTERN] [files...]\nmaterialize-pr-context\nwait-for-apt-locks\ninstall-playwright-chromium-arm64 [name:archive...]\nghcr-package-retention [--main-history] [--apply|--dry-run] [<url-encoded-package>...]\nharness-admission-lane <lanes>\nharness-assert-gates <gate>...\ngha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json\nnuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>\nverify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]\ndead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...\nswift-semantic-equal <base> <head> <file.swift>\npost-review\nstage-review-payload optional|required <source> <destination>\nretrospective-transcript [--session-id ID] [--jsonl PATH] [--projects-dir PATH] [--codex-sessions-dir PATH] [--grok-sessions-dir PATH]\nlink-skill <name> --source-root <skills-dir> --target-root <consumer-skills-dir> Link a packaged or repository-local skill\nretrospective-facts (--pr NUMBER | --branch NAME | --no-pr) [--repo OWNER/NAME] [--raw]\nagent-blackboard probe\nagent-blackboard session-start [--skip-env NAME] [--setup-hint TEXT] [--docs-path PATH] [--restore-hint TEXT] [--timeout-ms N] (SessionStart hook; payload on stdin)\nagent-blackboard distill classify <partition.jsonl> --retro-cutoff ISO8601 --session-cutoff ISO8601\nagent-blackboard snapshot partition --snapshot PATH --checksum SHA256 --counts '{\"sessions\":N,\"entries\":N,\"records\":N,\"bytes\":N}'\nagent-blackboard snapshot cleanup [--snapshot PATH] [--partition-directory PATH --receipt JSON]\nmcp\n (no args) Serve journal_append, journal_entries, outbox_status, outbox_flush,\n session_ensure, retrospective_check, retrospective_save,\n pr_validate, pr_create, pr_update,\n snapshot_export, snapshot_cleanup, and session_archive over stdio.\n Needs the optional @modelcontextprotocol/sdk peer (and zod).\n Launch it from inside the repository's git worktree.\n\nworktree reclaim [--yes] [--json]\n Dry run by default. Removes clean, fully pushed worktrees whose same-repository PR for the\n branch is merged or closed at exactly HEAD, using git worktree remove (never forced).\n Skips the main checkout, the current worktree, and locked, bare or detached worktrees.\n\ntransient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>\n Loads a module exporting \"rules\" (and optionally \"limits\"), evaluates them against the failed run,\n and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.\n\nstory-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]\n";
|
|
2
2
|
export declare function printUsage(stream?: NodeJS.WritableStream): void;
|
|
3
3
|
export declare function commandNames(usage?: string): string[];
|
|
4
4
|
export declare function commandUsage(command: string, usage?: string): string;
|
package/dist/cli/usage.mjs
CHANGED
|
@@ -20,6 +20,7 @@ Commands:
|
|
|
20
20
|
diagnose-port-collision Capture bounded localhost port diagnostics
|
|
21
21
|
prepare-trivy-db Download the Trivy vulnerability database
|
|
22
22
|
gha-artifacts-cleanup Delete classified GitHub Actions artifacts
|
|
23
|
+
agent-issue-labels Map changed paths to labels; create missing repository labels
|
|
23
24
|
http-origin Validate an optional HTTP(S) origin
|
|
24
25
|
vitest-blob-manifest Stamp a vitest-blob-manifest:v1 identity file
|
|
25
26
|
vitest-report-attempt Write or read a Vitest report-attempt marker
|
|
@@ -40,6 +41,8 @@ Commands:
|
|
|
40
41
|
harness-assert-gates Fail if any named HARNESS_*_ENABLED gate is enabled
|
|
41
42
|
gha-collaborator-trust Classify authors as write-access collaborators or not
|
|
42
43
|
nuget-central-version Validate a Directory.Packages.props PackageVersion delta
|
|
44
|
+
verify-workflow-secrets Check a secret inventory against live repository and environment secrets
|
|
45
|
+
dead-code Gate unused code against a committed jscpd baseline
|
|
43
46
|
swift-semantic-equal Compare Swift sources ignoring comments and whitespace
|
|
44
47
|
post-review Post one COMMENT review from a staged payload file
|
|
45
48
|
stage-review-payload Validate a review payload file into a staging directory
|
|
@@ -50,6 +53,7 @@ Commands:
|
|
|
50
53
|
mcp Serve the agent-blackboard journal tools over stdio (MCP)
|
|
51
54
|
worktree Reclaim finished git worktrees (dry run unless --yes)
|
|
52
55
|
story-coverage Check component exports are imported by stories
|
|
56
|
+
transient-retry Rerun a failed GitHub Actions run when an injected rule matches
|
|
53
57
|
|
|
54
58
|
Options:
|
|
55
59
|
-h, --help Show this help
|
|
@@ -96,6 +100,8 @@ diagnose-port-collision [--ports "2200 2216"] [--output-dir PATH]
|
|
|
96
100
|
prepare-trivy-db
|
|
97
101
|
gha-artifacts-cleanup run --run-id <id> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]
|
|
98
102
|
gha-artifacts-cleanup sweep --older-than-hours <n> [--keep-pattern glob] [--delete-pattern glob] [--patterns-file json]
|
|
103
|
+
agent-issue-labels labels-from-paths [--labeler <path>] <path>...
|
|
104
|
+
agent-issue-labels ensure-labels [--repo owner/name] [--policy-file json] [--update] <label>...
|
|
99
105
|
http-origin [--field NAME] [value]
|
|
100
106
|
vitest-blob-manifest <suite> [reports-directory]
|
|
101
107
|
vitest-report-attempt <write DIRECTORY SUITE|read ROOT>
|
|
@@ -116,6 +122,8 @@ harness-admission-lane <lanes>
|
|
|
116
122
|
harness-assert-gates <gate>...
|
|
117
123
|
gha-collaborator-trust <owner/repo> [--allow-bot <login>]... < authors.json
|
|
118
124
|
nuget-central-version <trusted-props> <candidate-props> <metadata-json> <output-props>
|
|
125
|
+
verify-workflow-secrets [--repo OWNER/NAME] [--confirm NAME,...] [--inventory MODULE] [--export NAME] [--branch NAME]
|
|
126
|
+
dead-code --baseline PATH [--seed|--update] [--config PATH] [--binary PATH] [--repo-root PATH] [--entry GLOB]... [--snapshot-ignore GLOB]... [--exclude GLOB]...
|
|
119
127
|
swift-semantic-equal <base> <head> <file.swift>
|
|
120
128
|
post-review
|
|
121
129
|
stage-review-payload optional|required <source> <destination>
|
|
@@ -140,6 +148,10 @@ worktree reclaim [--yes] [--json]
|
|
|
140
148
|
branch is merged or closed at exactly HEAD, using git worktree remove (never forced).
|
|
141
149
|
Skips the main checkout, the current worktree, and locked, bare or detached worktrees.
|
|
142
150
|
|
|
151
|
+
transient-retry --rules <module> [--repo owner/name] [--token-env NAME] [--dry-run] <run-id>
|
|
152
|
+
Loads a module exporting "rules" (and optionally "limits"), evaluates them against the failed run,
|
|
153
|
+
and reruns only on a match. Exits 0 on rerun, 2 when none is warranted, 1 on error.
|
|
154
|
+
|
|
143
155
|
story-coverage --root <dir> --component-root <rel> --story-root <rel> --source-extension <ext> --component-extension <ext> --marker <regex> --story-pattern <regex> [--alias <prefix>=<path>] [--exclusions <json>] [--exclusions-label <text>]
|
|
144
156
|
`;
|
|
145
157
|
export function printUsage(stream = process.stdout) {
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
export type FindingIdentity = {
|
|
2
|
+
category: string;
|
|
3
|
+
path: string;
|
|
4
|
+
parent: string;
|
|
5
|
+
name: string;
|
|
6
|
+
symbolKind: string;
|
|
7
|
+
};
|
|
8
|
+
export type BaselineRow = FindingIdentity & {
|
|
9
|
+
count: number;
|
|
10
|
+
};
|
|
11
|
+
export declare function rowsFromReport(value: unknown, include?: (finding: FindingIdentity, raw: Record<string, unknown>) => boolean): BaselineRow[];
|
|
12
|
+
export declare function parseBaseline(value: unknown): BaselineRow[];
|
|
13
|
+
export declare function compareRows(current: readonly BaselineRow[], baseline: readonly BaselineRow[]): {
|
|
14
|
+
added: BaselineRow[];
|
|
15
|
+
stale: BaselineRow[];
|
|
16
|
+
};
|
|
17
|
+
export declare function readBaseline(path: string): Promise<BaselineRow[]>;
|
|
18
|
+
export declare function writeBaseline(path: string, rows: readonly BaselineRow[]): Promise<void>;
|
|
19
|
+
export declare function reconcileBaseline(path: string, current: readonly BaselineRow[], operation: 'check' | 'seed' | 'update'): Promise<number>;
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { existsSync } from 'node:fs';
|
|
2
|
+
import { readFile, writeFile } from 'node:fs/promises';
|
|
3
|
+
const categories = new Set([
|
|
4
|
+
'unused-file',
|
|
5
|
+
'unused-export',
|
|
6
|
+
'unused-symbol',
|
|
7
|
+
'unused-import',
|
|
8
|
+
'unused-member',
|
|
9
|
+
]);
|
|
10
|
+
function record(value) {
|
|
11
|
+
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
|
|
12
|
+
throw new Error('Expected a JSON object');
|
|
13
|
+
}
|
|
14
|
+
return value;
|
|
15
|
+
}
|
|
16
|
+
function requiredString(value, field) {
|
|
17
|
+
if (typeof value !== 'string')
|
|
18
|
+
throw new Error(`Expected ${field} to be a string`);
|
|
19
|
+
return value;
|
|
20
|
+
}
|
|
21
|
+
function identity(value) {
|
|
22
|
+
const row = record(value);
|
|
23
|
+
const category = requiredString(row['category'], 'category');
|
|
24
|
+
const path = requiredString(row['path'], 'path');
|
|
25
|
+
const parent = requiredString(row['parent'] ?? '', 'parent');
|
|
26
|
+
const name = requiredString(row['name'], 'name');
|
|
27
|
+
const symbolKind = requiredString(row['symbolKind'] ?? '', 'symbolKind');
|
|
28
|
+
if (!categories.has(category))
|
|
29
|
+
throw new Error(`Unknown dead-code category: ${category}`);
|
|
30
|
+
if (!path || path.startsWith('/') || path.includes('\\') || path.split('/').includes('..')) {
|
|
31
|
+
throw new Error(`Invalid report path: ${path}`);
|
|
32
|
+
}
|
|
33
|
+
return { category, path, parent, name, symbolKind };
|
|
34
|
+
}
|
|
35
|
+
function key(row) {
|
|
36
|
+
return JSON.stringify([row.category, row.path, row.parent, row.name, row.symbolKind]);
|
|
37
|
+
}
|
|
38
|
+
function sortedRows(rows) {
|
|
39
|
+
return rows.toSorted((a, b) => key(a).localeCompare(key(b), 'en'));
|
|
40
|
+
}
|
|
41
|
+
export function rowsFromReport(value, include = () => true) {
|
|
42
|
+
const report = record(value);
|
|
43
|
+
const statistics = record(report['statistics']);
|
|
44
|
+
if (!Number.isInteger(statistics['files']) || statistics['files'] <= 0) {
|
|
45
|
+
throw new Error('Dead-code scan analyzed no files');
|
|
46
|
+
}
|
|
47
|
+
if (statistics['unparsed'] !== 0) {
|
|
48
|
+
throw new Error(`Dead-code scan has unparsed files: ${String(statistics['unparsed'])}`);
|
|
49
|
+
}
|
|
50
|
+
if (!Array.isArray(report['findings']))
|
|
51
|
+
throw new Error('Dead-code report has no findings array');
|
|
52
|
+
const counts = new Map();
|
|
53
|
+
for (const value of report['findings']) {
|
|
54
|
+
const found = identity(value);
|
|
55
|
+
if (!include(found, record(value)))
|
|
56
|
+
continue;
|
|
57
|
+
const id = key(found);
|
|
58
|
+
const existing = counts.get(id);
|
|
59
|
+
counts.set(id, { ...found, count: (existing?.count ?? 0) + 1 });
|
|
60
|
+
}
|
|
61
|
+
return sortedRows([...counts.values()]);
|
|
62
|
+
}
|
|
63
|
+
export function parseBaseline(value) {
|
|
64
|
+
const baseline = record(value);
|
|
65
|
+
if (baseline['version'] !== 1 || !Array.isArray(baseline['findings'])) {
|
|
66
|
+
throw new Error('Invalid dead-code baseline version or findings array');
|
|
67
|
+
}
|
|
68
|
+
const rows = baseline['findings'].map((value) => {
|
|
69
|
+
const item = record(value);
|
|
70
|
+
const found = identity(item);
|
|
71
|
+
if (!Number.isInteger(item['count']) || item['count'] < 1) {
|
|
72
|
+
throw new Error(`Invalid dead-code baseline count for ${key(found)}`);
|
|
73
|
+
}
|
|
74
|
+
return { ...found, count: item['count'] };
|
|
75
|
+
});
|
|
76
|
+
const sorted = sortedRows(rows);
|
|
77
|
+
if (rows.some((row, index) => key(row) !== key(sorted[index]))) {
|
|
78
|
+
throw new Error('Dead-code baseline is not sorted');
|
|
79
|
+
}
|
|
80
|
+
if (new Set(rows.map(key)).size !== rows.length) {
|
|
81
|
+
throw new Error('Dead-code baseline has duplicate identities');
|
|
82
|
+
}
|
|
83
|
+
return rows;
|
|
84
|
+
}
|
|
85
|
+
export function compareRows(current, baseline) {
|
|
86
|
+
const oldCounts = new Map(baseline.map((row) => [key(row), row.count]));
|
|
87
|
+
const newCounts = new Map(current.map((row) => [key(row), row.count]));
|
|
88
|
+
const added = current.filter((row) => row.count > (oldCounts.get(key(row)) ?? 0));
|
|
89
|
+
const stale = baseline.filter((row) => row.count > (newCounts.get(key(row)) ?? 0));
|
|
90
|
+
return { added, stale };
|
|
91
|
+
}
|
|
92
|
+
export async function readBaseline(path) {
|
|
93
|
+
return parseBaseline(JSON.parse(await readFile(path, 'utf8')));
|
|
94
|
+
}
|
|
95
|
+
export async function writeBaseline(path, rows) {
|
|
96
|
+
await writeFile(path, `${JSON.stringify({ version: 1, findings: sortedRows(rows) }, null, 2)}\n`);
|
|
97
|
+
}
|
|
98
|
+
function describe(rows) {
|
|
99
|
+
const shown = rows.slice(0, 12).map((row) => {
|
|
100
|
+
const symbol = row.name ? ` ${row.parent ? `${row.parent}.` : ''}${row.name}` : '';
|
|
101
|
+
return ` ${row.category} ${row.path}${symbol} (${row.count})`;
|
|
102
|
+
});
|
|
103
|
+
if (rows.length > shown.length)
|
|
104
|
+
shown.push(` …and ${rows.length - shown.length} more identities`);
|
|
105
|
+
return shown.join('\n');
|
|
106
|
+
}
|
|
107
|
+
export async function reconcileBaseline(path, current, operation) {
|
|
108
|
+
if (operation === 'seed') {
|
|
109
|
+
if (existsSync(path))
|
|
110
|
+
throw new Error('Initial baseline already exists');
|
|
111
|
+
await writeBaseline(path, current);
|
|
112
|
+
return 0;
|
|
113
|
+
}
|
|
114
|
+
const previous = await readBaseline(path);
|
|
115
|
+
const { added, stale } = compareRows(current, previous);
|
|
116
|
+
if (added.length > 0)
|
|
117
|
+
throw new Error(`New dead-code findings:\n${describe(added)}`);
|
|
118
|
+
if (operation === 'check' && stale.length > 0) {
|
|
119
|
+
throw new Error(`Stale dead-code baseline findings:\n${describe(stale)}`);
|
|
120
|
+
}
|
|
121
|
+
if (operation === 'update' && stale.length > 0)
|
|
122
|
+
await writeBaseline(path, current);
|
|
123
|
+
return stale.length;
|
|
124
|
+
}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
export declare class ChildCommandCleanupError extends AggregateError {
|
|
2
|
+
readonly processGroupId: number;
|
|
3
|
+
readonly completion: Promise<Error | null>;
|
|
4
|
+
constructor(processGroupId: number, completion: Promise<Error | null>, errors: unknown[]);
|
|
5
|
+
}
|
|
6
|
+
export declare function runChildCommand(file: string, args: string[], cwd: string, remaining?: () => number): Promise<void>;
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
import { spawn } from 'node:child_process';
|
|
2
|
+
export class ChildCommandCleanupError extends AggregateError {
|
|
3
|
+
processGroupId;
|
|
4
|
+
completion;
|
|
5
|
+
constructor(processGroupId, completion, errors) {
|
|
6
|
+
super(errors, 'Child command cleanup failed; owned process group may still be live', {
|
|
7
|
+
cause: errors[0],
|
|
8
|
+
});
|
|
9
|
+
this.processGroupId = processGroupId;
|
|
10
|
+
this.completion = completion;
|
|
11
|
+
}
|
|
12
|
+
}
|
|
13
|
+
class ChildCommandFailure extends Error {
|
|
14
|
+
code;
|
|
15
|
+
constructor(file, code, signal, stderr) {
|
|
16
|
+
super(`Command failed: ${file} (${signal ?? code}): ${stderr}`);
|
|
17
|
+
this.code = code;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
// Finite fixtures opt into a deadline; repository scans retain no local cap.
|
|
21
|
+
export async function runChildCommand(file, args, cwd, remaining) {
|
|
22
|
+
const timeout = remaining?.();
|
|
23
|
+
await new Promise((resolve, reject) => {
|
|
24
|
+
let settleCapture = () => undefined;
|
|
25
|
+
const capture = new Promise((done) => {
|
|
26
|
+
settleCapture = done;
|
|
27
|
+
});
|
|
28
|
+
let expired = false;
|
|
29
|
+
let settled = false;
|
|
30
|
+
let failure = null;
|
|
31
|
+
let exit;
|
|
32
|
+
let timer;
|
|
33
|
+
let bytes = 0;
|
|
34
|
+
let stderr = '';
|
|
35
|
+
const child = spawn(file, args, { cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
|
|
36
|
+
function stopGroup() {
|
|
37
|
+
if (settled || child.pid === undefined)
|
|
38
|
+
return;
|
|
39
|
+
try {
|
|
40
|
+
// eslint-disable-next-line no-restricted-properties -- terminate only this command's detached group, never the application process
|
|
41
|
+
process.kill(-child.pid, 'SIGKILL');
|
|
42
|
+
}
|
|
43
|
+
catch (err) {
|
|
44
|
+
if (err instanceof Error && 'code' in err && err.code === 'ESRCH')
|
|
45
|
+
return;
|
|
46
|
+
settled = true;
|
|
47
|
+
clearTimeout(timer);
|
|
48
|
+
const errors = failure ? [failure, err] : [err];
|
|
49
|
+
child.stdout.destroy();
|
|
50
|
+
child.stderr.destroy();
|
|
51
|
+
reject(new ChildCommandCleanupError(child.pid, capture, errors));
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
function output(chunk, isError) {
|
|
55
|
+
bytes += chunk.length;
|
|
56
|
+
if (bytes > 8 * 1024 * 1024) {
|
|
57
|
+
// Signal once: a later signal can hit the already-exited group leader and fail with EPERM.
|
|
58
|
+
if (failure !== null)
|
|
59
|
+
return;
|
|
60
|
+
failure = new Error('Child command output exceeded maxBuffer');
|
|
61
|
+
stopGroup();
|
|
62
|
+
}
|
|
63
|
+
else if (isError)
|
|
64
|
+
stderr += chunk.toString('utf8');
|
|
65
|
+
}
|
|
66
|
+
child.stdout.on('data', (chunk) => output(chunk, false));
|
|
67
|
+
child.stderr.on('data', (chunk) => output(chunk, true));
|
|
68
|
+
child.once('error', (err) => {
|
|
69
|
+
failure ??= err;
|
|
70
|
+
});
|
|
71
|
+
child.once('spawn', () => {
|
|
72
|
+
if (expired)
|
|
73
|
+
stopGroup();
|
|
74
|
+
});
|
|
75
|
+
child.once('exit', (code, signal) => {
|
|
76
|
+
exit = { code, signal };
|
|
77
|
+
stopGroup();
|
|
78
|
+
});
|
|
79
|
+
child.once('close', (code, signal) => {
|
|
80
|
+
const outcome = exit ?? { code, signal };
|
|
81
|
+
const commandFailure = outcome.code === 0
|
|
82
|
+
? null
|
|
83
|
+
: new ChildCommandFailure(file, outcome.code, outcome.signal, stderr);
|
|
84
|
+
if (commandFailure && failure && commandFailure !== failure) {
|
|
85
|
+
failure = new AggregateError([failure, commandFailure], failure.message, { cause: failure });
|
|
86
|
+
}
|
|
87
|
+
else
|
|
88
|
+
failure ??= commandFailure;
|
|
89
|
+
settleCapture(failure);
|
|
90
|
+
clearTimeout(timer);
|
|
91
|
+
if (settled)
|
|
92
|
+
return;
|
|
93
|
+
settled = true;
|
|
94
|
+
if (failure)
|
|
95
|
+
reject(failure);
|
|
96
|
+
else
|
|
97
|
+
resolve();
|
|
98
|
+
});
|
|
99
|
+
if (timeout !== undefined) {
|
|
100
|
+
timer = setTimeout(() => {
|
|
101
|
+
expired = true;
|
|
102
|
+
failure ??= new Error('Child command exceeded the fixture deadline');
|
|
103
|
+
stopGroup();
|
|
104
|
+
}, timeout);
|
|
105
|
+
}
|
|
106
|
+
});
|
|
107
|
+
}
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export declare const USAGE: string;
|
|
2
|
+
type Output = Pick<Console, 'error' | 'log'>;
|
|
3
|
+
/** Runs `vouchington dead-code`. Returns 2 for usage errors and 1 for gate failures. */
|
|
4
|
+
export declare function runDeadCodeCli(argv: readonly string[], output?: Output): Promise<number>;
|
|
5
|
+
export {};
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import { parseArgs } from 'node:util';
|
|
2
|
+
import { runDeadCodeGate } from "./gate.mjs";
|
|
3
|
+
export const USAGE = 'Usage: vouchington dead-code --baseline <path> [--seed|--update] [--config <path>] ' +
|
|
4
|
+
'[--binary <path>] [--repo-root <path>] [--entry <glob>]... [--snapshot-ignore <glob>]... ' +
|
|
5
|
+
'[--exclude <glob>]...';
|
|
6
|
+
function message(err) {
|
|
7
|
+
return err instanceof Error ? err.message : String(err);
|
|
8
|
+
}
|
|
9
|
+
function summary(result) {
|
|
10
|
+
const { identities, trackedFiles, removed } = result;
|
|
11
|
+
if (result.operation === 'seed') {
|
|
12
|
+
return `Seeded dead-code baseline with ${identities} identities from ${trackedFiles} tracked files`;
|
|
13
|
+
}
|
|
14
|
+
if (result.operation === 'update') {
|
|
15
|
+
return `Dead-code baseline removed ${removed} stale identities; ${identities} remain`;
|
|
16
|
+
}
|
|
17
|
+
return `Dead-code baseline matches ${identities} identities across ${trackedFiles} tracked files`;
|
|
18
|
+
}
|
|
19
|
+
/** Runs `vouchington dead-code`. Returns 2 for usage errors and 1 for gate failures. */
|
|
20
|
+
export async function runDeadCodeCli(argv, output = console) {
|
|
21
|
+
let values;
|
|
22
|
+
try {
|
|
23
|
+
;
|
|
24
|
+
({ values } = parseArgs({
|
|
25
|
+
args: [...argv],
|
|
26
|
+
options: {
|
|
27
|
+
baseline: { type: 'string' },
|
|
28
|
+
seed: { type: 'boolean' },
|
|
29
|
+
update: { type: 'boolean' },
|
|
30
|
+
config: { type: 'string' },
|
|
31
|
+
binary: { type: 'string' },
|
|
32
|
+
'repo-root': { type: 'string' },
|
|
33
|
+
entry: { type: 'string', multiple: true },
|
|
34
|
+
'snapshot-ignore': { type: 'string', multiple: true },
|
|
35
|
+
exclude: { type: 'string', multiple: true },
|
|
36
|
+
},
|
|
37
|
+
strict: true,
|
|
38
|
+
}));
|
|
39
|
+
}
|
|
40
|
+
catch (err) {
|
|
41
|
+
output.error(`${USAGE}\n${message(err)}`);
|
|
42
|
+
return 2;
|
|
43
|
+
}
|
|
44
|
+
if (!values.baseline) {
|
|
45
|
+
output.error(`${USAGE}\n--baseline is required`);
|
|
46
|
+
return 2;
|
|
47
|
+
}
|
|
48
|
+
if (values.seed && values.update) {
|
|
49
|
+
output.error(`${USAGE}\n--seed and --update are mutually exclusive`);
|
|
50
|
+
return 2;
|
|
51
|
+
}
|
|
52
|
+
const operation = values.seed ? 'seed' : values.update ? 'update' : 'check';
|
|
53
|
+
try {
|
|
54
|
+
const result = await runDeadCodeGate({
|
|
55
|
+
repoRoot: values['repo-root'] ?? process.cwd(),
|
|
56
|
+
baselinePath: values.baseline,
|
|
57
|
+
operation,
|
|
58
|
+
configPath: values.config,
|
|
59
|
+
binary: values.binary,
|
|
60
|
+
entryRoots: values.entry,
|
|
61
|
+
snapshotIgnore: values['snapshot-ignore'],
|
|
62
|
+
excludeFindings: values.exclude,
|
|
63
|
+
});
|
|
64
|
+
output.log(summary(result));
|
|
65
|
+
return 0;
|
|
66
|
+
}
|
|
67
|
+
catch (err) {
|
|
68
|
+
output.error(message(err));
|
|
69
|
+
return 1;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Resolves the live entry roots for a snapshot. Roots come from `override` when given,
|
|
3
|
+
* otherwise from the snapshot config's `deadCode.entry`. Every root must be a relative
|
|
4
|
+
* snapshot-internal glob that matches at least one file. An override is written into the
|
|
5
|
+
* snapshot's copy of the config (never the working tree).
|
|
6
|
+
*/
|
|
7
|
+
export declare function resolveEntryRoots(snapshotRoot: string, configPath: string, override?: readonly string[]): Promise<string[]>;
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { glob, readFile, writeFile } from 'node:fs/promises';
|
|
2
|
+
import { join } from 'node:path';
|
|
3
|
+
function invalid(entry) {
|
|
4
|
+
return (typeof entry !== 'string' ||
|
|
5
|
+
entry.length === 0 ||
|
|
6
|
+
entry.startsWith('/') ||
|
|
7
|
+
entry.includes('\\') ||
|
|
8
|
+
entry.split('/').includes('..'));
|
|
9
|
+
}
|
|
10
|
+
async function assertLive(snapshotRoot, entries) {
|
|
11
|
+
if (entries.length === 0)
|
|
12
|
+
throw new Error('jscpd deadCode.entry must contain at least one root');
|
|
13
|
+
for (const entry of entries) {
|
|
14
|
+
if (invalid(entry))
|
|
15
|
+
throw new Error(`Invalid dead-code entry root: ${String(entry)}`);
|
|
16
|
+
let matches = 0;
|
|
17
|
+
for await (const _ of glob(entry, { cwd: snapshotRoot }))
|
|
18
|
+
matches += 1;
|
|
19
|
+
if (matches === 0)
|
|
20
|
+
throw new Error(`Stale dead-code entry root: ${String(entry)}`);
|
|
21
|
+
}
|
|
22
|
+
return [...entries];
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Resolves the live entry roots for a snapshot. Roots come from `override` when given,
|
|
26
|
+
* otherwise from the snapshot config's `deadCode.entry`. Every root must be a relative
|
|
27
|
+
* snapshot-internal glob that matches at least one file. An override is written into the
|
|
28
|
+
* snapshot's copy of the config (never the working tree).
|
|
29
|
+
*/
|
|
30
|
+
export async function resolveEntryRoots(snapshotRoot, configPath, override) {
|
|
31
|
+
const file = join(snapshotRoot, configPath);
|
|
32
|
+
const config = JSON.parse(await readFile(file, 'utf8'));
|
|
33
|
+
const configured = config?.deadCode?.entry;
|
|
34
|
+
if (override === undefined && !Array.isArray(configured)) {
|
|
35
|
+
throw new Error('jscpd deadCode.entry must contain at least one root');
|
|
36
|
+
}
|
|
37
|
+
const entries = await assertLive(snapshotRoot, override ?? configured);
|
|
38
|
+
if (override !== undefined) {
|
|
39
|
+
config.deadCode = { ...config.deadCode, entry: entries };
|
|
40
|
+
await writeFile(file, `${JSON.stringify(config, null, 2)}\n`);
|
|
41
|
+
}
|
|
42
|
+
return entries;
|
|
43
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare function createFixtureDeadline(): () => number;
|