vouchington-tooling 0.13.2 → 0.13.4

package/README.md

@@ -93,6 +93,11 @@ ancestor of `HEAD`. `gitleaks-directory-scan` builds and scans isolated staged-i
 nonignored-working-tree mirrors with an explicit config; `--directory` selects the repository root.
 `ast-grep-examples` runs native `ast-grep test`, then validates each scoped rule's `files:` and
 `ignores:` examples with project `languageGlobs` replay from its root `--config`.
+`compareAstGrepCompanions` compares recursive `<name>.yml`/`.yaml` and `<name>-tsx` companion
+rules across every YAML field, returns stable JSON-pointer differences, and rejects unsafe or
+ambiguous rule paths. The supplied rule path and every ancestor must be physical directories; YAML
+aliases and non-JSON tagged values are rejected before comparison. Callers own any explicit
+normalization for language-specific differences.
 `ast-grep-pack` prints JSON `{ rules, config }` for the shipped unconditional rule pack. Point a
 consumer `sgconfig.yml` `ruleDirs` at `rules` and keep product-specific YAML locally.
 `gha-workspace-policy` checks tracked workflow and composite-action files in the current repository;

package/ast-grep/rules/no-three-sequential-awaits-tsx.yml

@@ -12,6 +12,10 @@ ignores:
   - 'web/test-helpers/**'
 rule:
   all:
+    - not:
+        any:
+          - matches: async-disposable-acquisition
+          - matches: async-disposable-commit
     - not:
         follows:
           stopBy: neighbor
@@ -72,6 +76,10 @@ rule:
                     pattern: $W = await Promise.all($$$)
                 - not:
                     pattern: $W = await Promise.allSettled($$$)
+          not:
+            any:
+              - matches: async-disposable-acquisition
+              - matches: async-disposable-commit
     - any:
         - all:
             - pattern:
@@ -189,8 +197,16 @@ rule:
                       pattern: $Y = await Promise.all($$$)
                   - not:
                       pattern: $Y = await Promise.allSettled($$$)
+          - not:
+              any:
+                - matches: async-disposable-acquisition
+                - matches: async-disposable-commit
           - precedes:
               stopBy: neighbor
+              not:
+                any:
+                  - matches: async-disposable-acquisition
+                  - matches: async-disposable-commit
               any:
                 - all:
                     - pattern:
@@ -261,6 +277,69 @@ constraints:
   P:
     not:
       regex: '^Promise\.all(Settled)?\b'
+utils:
+  async-disposable-acquisition:
+    all:
+      - pattern:
+          context: |
+            async function run() {
+              await using $RESOURCE = await $ACQUIRE
+            }
+          selector: expression_statement
+      - precedes:
+          # Pair only with the nearest lifecycle endpoint to the right.
+          # Overlapping-resource policy belongs to a separate lifecycle rule.
+          stopBy:
+            any:
+              - pattern:
+                  context: |
+                    async function run() {
+                      await using $_ = await $_
+                    }
+                  selector: expression_statement
+              - pattern:
+                  context: |
+                    async function run() {
+                      await $_.commit($$$)
+                    }
+                  selector: expression_statement
+          pattern:
+            context: |
+              async function run() {
+                await $RESOURCE.commit($$$)
+              }
+            selector: expression_statement
+  async-disposable-commit:
+    all:
+      - pattern:
+          context: |
+            async function run() {
+              await $RESOURCE.commit($$$)
+            }
+          selector: expression_statement
+      - follows:
+          # Pair only with the nearest lifecycle endpoint to the left.
+          # Overlapping-resource policy belongs to a separate lifecycle rule.
+          stopBy:
+            any:
+              - pattern:
+                  context: |
+                    async function run() {
+                      await using $_ = await $_
+                    }
+                  selector: expression_statement
+              - pattern:
+                  context: |
+                    async function run() {
+                      await $_.commit($$$)
+                    }
+                  selector: expression_statement
+          pattern:
+            context: |
+              async function run() {
+                await using $RESOURCE = await $ACQUIRE
+              }
+            selector: expression_statement
 examples:
   - code: |
       async function run() {
@@ -286,3 +365,102 @@ examples:
       }
     isValid: true
     file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyChange(transaction)
+        await transaction.commit()
+        return <div />
+      }
+    isValid: true
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using transaction = await beginBoundedTransaction({ timeoutMs: 1000 })
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await transaction.commit()
+        return <div />
+      }
+    isValid: true
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await applyThirdChange(transaction)
+        await transaction.commit()
+        return <div />
+      }
+    isValid: false
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await unrelatedFirst()
+        await unrelatedSecond()
+        await unrelatedThird()
+        await using transaction = await beginTransaction()
+        await applyChange(transaction)
+        await transaction.commit()
+        return <div />
+      }
+    isValid: false
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await other.commit()
+        return <div />
+      }
+    isValid: false
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyChange(transaction)
+        await transaction.commit()
+        await afterFirst()
+        await afterSecond()
+        await afterThird()
+        return <div />
+      }
+    isValid: false
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using outer = await acquire()
+        {
+          await using inner = await acquire()
+          await innerFirst(inner)
+          await innerSecond(inner)
+          await innerThird(inner)
+          await inner.commit()
+        }
+        await outer.commit()
+        return <div />
+      }
+    isValid: false
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await transaction.rollback()
+        return <div />
+      }
+    isValid: false
+    file: 'web/app/example.tsx'
+  - code: |
+      async function run() {
+        await using resource = await acquire()
+        await useFirst(resource)
+        await useSecond(resource)
+        await resource.dispose()
+        return <div />
+      }
+    isValid: false
+    file: 'web/app/example.tsx'

package/ast-grep/rules/no-three-sequential-awaits.yml

@@ -33,6 +33,10 @@ ignores:
   - 'backend/scripts/explain-analyze/**'
 rule:
   all:
+    - not:
+        any:
+          - matches: async-disposable-acquisition
+          - matches: async-disposable-commit
     - not:
         follows:
           stopBy: neighbor
@@ -73,6 +77,10 @@ rule:
                     pattern: $W = await Promise.all($$$)
                 - not:
                     pattern: $W = await Promise.allSettled($$$)
+          not:
+            any:
+              - matches: async-disposable-acquisition
+              - matches: async-disposable-commit
     - any:
         - all:
             - pattern:
@@ -150,8 +158,16 @@ rule:
                       pattern: $Y = await Promise.all($$$)
                   - not:
                       pattern: $Y = await Promise.allSettled($$$)
+          - not:
+              any:
+                - matches: async-disposable-acquisition
+                - matches: async-disposable-commit
           - precedes:
               stopBy: neighbor
+              not:
+                any:
+                  - matches: async-disposable-acquisition
+                  - matches: async-disposable-commit
               any:
                 - all:
                     - pattern:
@@ -202,6 +218,69 @@ constraints:
   P:
     not:
       regex: '^Promise\.all(Settled)?\b'
+utils:
+  async-disposable-acquisition:
+    all:
+      - pattern:
+          context: |
+            async function run() {
+              await using $RESOURCE = await $ACQUIRE
+            }
+          selector: expression_statement
+      - precedes:
+          # Pair only with the nearest lifecycle endpoint to the right.
+          # Overlapping-resource policy belongs to a separate lifecycle rule.
+          stopBy:
+            any:
+              - pattern:
+                  context: |
+                    async function run() {
+                      await using $_ = await $_
+                    }
+                  selector: expression_statement
+              - pattern:
+                  context: |
+                    async function run() {
+                      await $_.commit($$$)
+                    }
+                  selector: expression_statement
+          pattern:
+            context: |
+              async function run() {
+                await $RESOURCE.commit($$$)
+              }
+            selector: expression_statement
+  async-disposable-commit:
+    all:
+      - pattern:
+          context: |
+            async function run() {
+              await $RESOURCE.commit($$$)
+            }
+          selector: expression_statement
+      - follows:
+          # Pair only with the nearest lifecycle endpoint to the left.
+          # Overlapping-resource policy belongs to a separate lifecycle rule.
+          stopBy:
+            any:
+              - pattern:
+                  context: |
+                    async function run() {
+                      await using $_ = await $_
+                    }
+                  selector: expression_statement
+              - pattern:
+                  context: |
+                    async function run() {
+                      await $_.commit($$$)
+                    }
+                  selector: expression_statement
+          pattern:
+            context: |
+              async function run() {
+                await using $RESOURCE = await $ACQUIRE
+              }
+            selector: expression_statement
 examples:
   - code: |
       async function run() {
@@ -240,3 +319,93 @@ examples:
       }
     isValid: true
     file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyChange(transaction)
+        await transaction.commit()
+      }
+    isValid: true
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using transaction = await beginBoundedTransaction({ timeoutMs: 1000 })
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await transaction.commit()
+      }
+    isValid: true
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await applyThirdChange(transaction)
+        await transaction.commit()
+      }
+    isValid: false
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await unrelatedFirst()
+        await unrelatedSecond()
+        await unrelatedThird()
+        await using transaction = await beginTransaction()
+        await applyChange(transaction)
+        await transaction.commit()
+      }
+    isValid: false
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await other.commit()
+      }
+    isValid: false
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyChange(transaction)
+        await transaction.commit()
+        await afterFirst()
+        await afterSecond()
+        await afterThird()
+      }
+    isValid: false
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using outer = await acquire()
+        {
+          await using inner = await acquire()
+          await innerFirst(inner)
+          await innerSecond(inner)
+          await innerThird(inner)
+          await inner.commit()
+        }
+        await outer.commit()
+      }
+    isValid: false
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using transaction = await beginTransaction()
+        await applyFirstChange(transaction)
+        await applySecondChange(transaction)
+        await transaction.rollback()
+      }
+    isValid: false
+    file: 'backend/services/example.mts'
+  - code: |
+      async function run() {
+        await using resource = await acquire()
+        await useFirst(resource)
+        await useSecond(resource)
+        await resource.dispose()
+      }
+    isValid: false
+    file: 'backend/services/example.mts'

package/dist/ast-grep-examples/companion-parity.d.mts

@@ -0,0 +1,19 @@
+export interface AstGrepCompanionDifference {
+    readonly baseFile: string;
+    readonly companionFile: string;
+    readonly path: string;
+    readonly base: unknown;
+    readonly companion: unknown;
+}
+export interface AstGrepCompanionParityOptions {
+    readonly rules: string;
+    readonly companionSuffix?: string;
+    readonly normalize?: (document: unknown, context: AstGrepCompanionContext) => unknown;
+}
+export interface AstGrepCompanionContext {
+    readonly file: string;
+    readonly role: 'base' | 'companion';
+}
+export declare function compareCodeUnits(left: string, right: string): number;
+/** Compares recursive `<name>.yml`/`.yaml` rules with `<name>-tsx` companions. */
+export declare function compareAstGrepCompanions(options: AstGrepCompanionParityOptions): AstGrepCompanionDifference[];

package/dist/ast-grep-examples/companion-parity.mjs

@@ -0,0 +1,156 @@
+import * as fs from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { parse as yamlLoad } from 'yaml';
+const YAML_EXTENSION = /\.ya?ml$/u;
+export function compareCodeUnits(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+function assertPhysicalPath(path) {
+    let ancestor = path;
+    while (true) {
+        if (fs.lstatSync(ancestor).isSymbolicLink())
+            throw new Error('rules: symbolic links are not allowed');
+        const parent = dirname(ancestor);
+        if (parent === ancestor)
+            return;
+        ancestor = parent;
+    }
+}
+function yamlFiles(directory, relative = '') {
+    const entries = fs
+        .readdirSync(directory, { withFileTypes: true })
+        .toSorted((a, b) => compareCodeUnits(a.name, b.name));
+    const files = [];
+    for (const entry of entries) {
+        const file = relative ? `${relative}/${entry.name}` : entry.name;
+        if (entry.isSymbolicLink())
+            throw new Error(`${file}: symbolic links are not allowed`);
+        if (entry.isDirectory())
+            files.push(...yamlFiles(join(directory, entry.name), file));
+        else if (entry.isFile() && YAML_EXTENSION.test(entry.name))
+            files.push(file);
+    }
+    return files;
+}
+function loadDocument(rules, file) {
+    try {
+        const document = yamlLoad(fs.readFileSync(join(rules, file), 'utf8'), { maxAliasCount: 0 });
+        assertJsonValue(document);
+        return document;
+    }
+    catch (error) {
+        throw new Error(`${file}: invalid YAML: ${String(error)}`);
+    }
+}
+function stem(file) {
+    return file.replace(YAML_EXTENSION, '');
+}
+function pointer(path, key) {
+    const segment = String(key).replaceAll('~', '~0').replaceAll('/', '~1');
+    return `${path}/${segment}`;
+}
+function isRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || prototype === Object.prototype;
+}
+function assertJsonValue(value, ancestors = new WeakSet()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return;
+    if (Array.isArray(value)) {
+        if (ancestors.has(value))
+            throw new Error('unsupported cyclic YAML value');
+        ancestors.add(value);
+        for (const item of value)
+            assertJsonValue(item, ancestors);
+        ancestors.delete(value);
+        return;
+    }
+    if (isRecord(value)) {
+        if (ancestors.has(value))
+            throw new Error('unsupported cyclic YAML value');
+        ancestors.add(value);
+        for (const item of Object.values(value))
+            assertJsonValue(item, ancestors);
+        ancestors.delete(value);
+        return;
+    }
+    throw new Error('unsupported non-JSON YAML value');
+}
+function compare(base, companion, path, difference) {
+    if (Object.is(base, companion))
+        return;
+    if (Array.isArray(base) && Array.isArray(companion)) {
+        const length = Math.max(base.length, companion.length);
+        for (let index = 0; index < length; index++)
+            compare(base[index], companion[index], pointer(path, index), difference);
+        return;
+    }
+    if (isRecord(base) && isRecord(companion)) {
+        for (const key of [...new Set([...Object.keys(base), ...Object.keys(companion)])].toSorted(compareCodeUnits))
+            compare(base[key], companion[key], pointer(path, key), difference);
+        return;
+    }
+    difference(path, base, companion);
+}
+function assertSuffix(suffix) {
+    if (!suffix || /[\\/]/u.test(suffix))
+        throw new Error('companionSuffix must be a non-empty filename suffix');
+}
+/** Compares recursive `<name>.yml`/`.yaml` rules with `<name>-tsx` companions. */
+export function compareAstGrepCompanions(options) {
+    const suffix = options.companionSuffix ?? '-tsx';
+    assertSuffix(suffix);
+    const rules = resolve(options.rules);
+    assertPhysicalPath(rules);
+    const files = yamlFiles(rules);
+    const basesByStem = new Map();
+    const companions = [];
+    for (const file of files) {
+        const fileStem = stem(file);
+        if (fileStem.endsWith(suffix))
+            companions.push({ file, baseStem: fileStem.slice(0, -suffix.length) });
+        else
+            basesByStem.set(fileStem, [...(basesByStem.get(fileStem) ?? []), file]);
+    }
+    const companionsByStem = new Map();
+    for (const { file, baseStem } of companions)
+        companionsByStem.set(baseStem, [...(companionsByStem.get(baseStem) ?? []), file]);
+    for (const [baseStem, companionFiles] of companionsByStem)
+        if (companionFiles.length > 1)
+            throw new Error(`${baseStem}: duplicate companion rules: ${companionFiles.toSorted(compareCodeUnits).join(', ')}`);
+    const differences = [];
+    for (const { file: companionFile, baseStem } of companions) {
+        const bases = basesByStem.get(baseStem) ?? [];
+        if (!bases.length)
+            throw new Error(`${companionFile}: missing base companion`);
+        if (bases.length > 1)
+            throw new Error(`${companionFile}: duplicate base companions: ${bases.toSorted(compareCodeUnits).join(', ')}`);
+        const baseFile = bases[0];
+        const normalize = options.normalize ?? ((document) => document);
+        const base = normalize(loadDocument(rules, baseFile), { file: baseFile, role: 'base' });
+        const companion = normalize(loadDocument(rules, companionFile), {
+            file: companionFile,
+            role: 'companion',
+        });
+        assertJsonValue(base);
+        assertJsonValue(companion);
+        compare(base, companion, '', (path, baseValue, companionValue) => {
+            differences.push({
+                baseFile,
+                companionFile,
+                path,
+                base: baseValue,
+                companion: companionValue,
+            });
+        });
+    }
+    return differences;
+}

package/dist/ast-grep-examples/index.d.mts

@@ -1,3 +1,5 @@
+export { compareAstGrepCompanions } from './companion-parity.mts';
+export type { AstGrepCompanionContext, AstGrepCompanionDifference, AstGrepCompanionParityOptions, } from './companion-parity.mts';
 interface AstGrepResult {
     status: number | null;
     stdout?: string;
@@ -12,4 +14,3 @@ export interface AstGrepExamplesOptions {
 }
 export declare function astGrepExamplesArguments(options: AstGrepExamplesOptions): string[];
 export declare function runAstGrepExamples(options: AstGrepExamplesOptions): number;
-export {};

package/dist/ast-grep-examples/index.mjs

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 import picomatch from 'picomatch';
 import { parse as yamlLoad, stringify as yamlDump } from 'yaml';
+export { compareAstGrepCompanions } from './companion-parity.mjs';
 export function astGrepExamplesArguments(options) {
     return [
         'test',

package/dist/coverage-transport/outcome.d.mts

@@ -14,15 +14,16 @@ export type BlobPrimaryState = 'true' | 'false' | 'skipped';
 export declare function isBlobPrimaryState(value: string | undefined): value is BlobPrimaryState;
 /**
  * Sibling to `assertCoverageTransportOutcome` for the Vitest blob. `true`/`false` are the S3
- * upload step's `blob` output; `skipped` means that step never ran. GitHub fallback is always
- * attempted when enabled — workflows must not gate it on `blob != 'true'`.
+ * upload step's `blob` output; `skipped` means that step never ran. Workflows gate the GitHub
+ * fallback on `blob != 'true'`, so a persisted S3 primary with no GitHub artifact attempt is the
+ * expected steady state, not a degraded one.
  */
 export declare function assertCoverageTransportBlobOutcome(suite: string, primaryPersisted: BlobPrimaryState, artifactAttempt1: StepOutcome, artifactAttempt2: StepOutcome, emit?: (line: string) => void): boolean;
 export type AppendOutput = (path: string, data: string) => void;
 /**
- * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. GitHub-fallback blob upload
- * must always be attempted when enabled; do not gate it on this signal. The upload subcommand's
- * exit code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
+ * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. Workflows gate the
+ * GitHub-fallback blob upload on this signal (`blob != 'true'`). The upload subcommand's exit
+ * code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
  */
 export declare function writeUploadOutcomeOutput(outcome: {
     readonly blob: boolean;

package/dist/coverage-transport/outcome.mjs

@@ -41,15 +41,13 @@ export function isBlobPrimaryState(value) {
 }
 /**
  * Sibling to `assertCoverageTransportOutcome` for the Vitest blob. `true`/`false` are the S3
- * upload step's `blob` output; `skipped` means that step never ran. GitHub fallback is always
- * attempted when enabled — workflows must not gate it on `blob != 'true'`.
+ * upload step's `blob` output; `skipped` means that step never ran. Workflows gate the GitHub
+ * fallback on `blob != 'true'`, so a persisted S3 primary with no GitHub artifact attempt is the
+ * expected steady state, not a degraded one.
  */
 export function assertCoverageTransportBlobOutcome(suite, primaryPersisted, artifactAttempt1, artifactAttempt2, emit = (line) => process.stderr.write(`${line}\n`)) {
     const artifactSucceeded = artifactAttempt1 === 'success' || artifactAttempt2 === 'success';
     if (primaryPersisted === 'true') {
-        if (!artifactSucceeded) {
-            emit(`::warning::Vitest blob persisted only to S3 for suite=${suite}; GitHub artifact fallback is degraded.`);
-        }
         return true;
     }
     if (artifactSucceeded) {
@@ -62,9 +60,9 @@ export function assertCoverageTransportBlobOutcome(suite, primaryPersisted, arti
     return false;
 }
 /**
- * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. GitHub-fallback blob upload
- * must always be attempted when enabled; do not gate it on this signal. The upload subcommand's
- * exit code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
+ * Writes `blob=true|false` to `$GITHUB_OUTPUT` for outcome reporting. Workflows gate the
+ * GitHub-fallback blob upload on this signal (`blob != 'true'`). The upload subcommand's exit
+ * code tracks the coverage pair, not the blob. A no-op outside CI (`githubOutputPath` unset).
  */
 export function writeUploadOutcomeOutput(outcome, githubOutputPath, appendOutput = appendFileSync) {
     if (githubOutputPath)

package/dist/gha-check-run/cli.d.mts

@@ -0,0 +1,2 @@
+import { type GhExec } from '../gha-post-review/github.mts';
+export declare function runCheckRunCli(argv?: readonly string[], env?: NodeJS.ProcessEnv, exec?: GhExec): number;