vouchington-tooling 0.13.1 → 0.13.3

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;
@@ -186,6 +191,13 @@ import {
 import { buildOpenApiDocument, writeOpenApi } from 'vouchington-tooling/openapi-document'
 import { decide, deriveRetryAttempt } from 'vouchington-tooling/transient-retry'
 import { parseCsvRows, streamCsvRows } from 'vouchington-tooling/csv'
+import {
+  extractLooseMarkdownTableRows,
+  extractMarkdownTables,
+  markdownSectionBetweenHeadings,
+  parseGfmMarkdown,
+  parseMarkdownTables,
+} from 'vouchington-tooling/markdown'
 import { readResponseBody } from 'vouchington-tooling/http-body'
 import { runAstGrepRule } from 'vouchington-tooling/ast-grep-rule'
 import { parseReviewPayload, remapReviewComments } from 'vouchington-tooling/gha-review-payload'
@@ -228,6 +240,13 @@ import {
 } from 'vouchington-tooling/gh-api-shell-quoting'
 ```
 
+`checkSccComplexity` keeps its single repository-wide scan when `scopes` is omitted. Consumers
+that need separately ratcheted areas may provide named scopes with positional `includePaths`; SCC
+runs once per scope and reports the scope in each diagnostic. Parse a consumer-owned JSON baseline
+with `parseSccComplexityBaseline` and pass it as `baseline`. Baselines are versioned, record the
+maximum permitted complexity for each `{ scope, file }`, suppress only values at or below that
+ceiling, and reject malformed, duplicate, untracked, stale, or out-of-scope entries.
+
 `shellScriptViolations`/`workflowYamlViolations` flag a `gh api` call whose argument carries an
 unquoted `?` or `&`: an unquoted `&` silently backgrounds the command and truncates the query
 (the call still exits 0), and an unquoted `?` fails loudly under zsh glob-nomatch but passes
@@ -241,6 +260,13 @@ shell script or a workflow/action YAML file is left to the caller.
 code-point limit without altering it. Its result includes the UTF-8 byte count for diagnostics; that
 byte count is not a validation limit.
 
+`vouchington-tooling/markdown` parses GFM into standard mdast/unist nodes, provides pre-order
+walking and typed searches, normalizes node text, and extracts positioned tables or heading-bounded
+source sections. `parseMarkdownTables` preserves its compact `{ cells, line }[][]` compatibility
+shape, including short table delimiters. `extractLooseMarkdownTableRows` is intentionally literal
+recovery for malformed pipe rows; callers supply table positions to exclude and retain ownership of
+their policy interpretation.
+
 `agent-harness-config` merges classifier-auto and sandbox keys into Claude, Codex, Grok, and Cursor
 config files. See [docs/agent-harness-config.md](./docs/agent-harness-config.md). `--global` updates
 home-directory configs; `--repo` updates a checkout. It does not copy allowlists, hooks, or plugins.

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/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;

package/dist/gha-check-run/cli.mjs

@@ -0,0 +1,81 @@
+import { appendFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createGhExec } from '../gha-post-review/github.mjs';
+import { completeCheckRun, createCheckRun, CheckRunError, } from './github.mjs';
+function requireEnv(name, env) {
+    const value = env[name];
+    if (!value)
+        throw new CheckRunError(`${name} is required.`);
+    return value;
+}
+function parseStatus(value) {
+    if (value !== 'in_progress' && value !== 'completed') {
+        throw new CheckRunError(`STATUS must be "in_progress" or "completed" (got "${value}").`);
+    }
+    return value;
+}
+function parseConclusion(value) {
+    if (value !== 'success' && value !== 'neutral') {
+        throw new CheckRunError(`CONCLUSION must be "success" or "neutral" (got "${value}").`);
+    }
+    return value;
+}
+function appendOutput(name, value, outputPath) {
+    if (!outputPath)
+        return;
+    appendFileSync(outputPath, `${name}=${value}\n`);
+}
+/** Builds a create-check-run input from env, requiring CONCLUSION only when STATUS is completed. */
+function readCreateInput(env) {
+    const status = parseStatus(requireEnv('STATUS', env));
+    const shared = {
+        repository: requireEnv('GITHUB_REPOSITORY', env),
+        name: requireEnv('CHECK_NAME', env),
+        headSha: requireEnv('HEAD_SHA', env),
+        title: requireEnv('TITLE', env),
+        summary: requireEnv('SUMMARY', env),
+    };
+    if (status === 'completed') {
+        return { ...shared, status, conclusion: parseConclusion(requireEnv('CONCLUSION', env)) };
+    }
+    return { ...shared, status };
+}
+function runCreate(env, exec) {
+    const id = createCheckRun(readCreateInput(env), exec);
+    appendOutput('check_run_id', id, env.GITHUB_OUTPUT);
+}
+/** No-ops when CHECK_RUN_ID is unset: the create step may have already finalized the check. */
+function runComplete(env, exec) {
+    const checkRunId = env.CHECK_RUN_ID ?? '';
+    if (checkRunId === '')
+        return;
+    completeCheckRun({
+        repository: requireEnv('GITHUB_REPOSITORY', env),
+        checkRunId,
+        conclusion: parseConclusion(requireEnv('CONCLUSION', env)),
+        title: requireEnv('TITLE', env),
+        summary: requireEnv('SUMMARY', env),
+    }, exec);
+}
+export function runCheckRunCli(argv = process.argv, env = process.env, exec = createGhExec()) {
+    const subcommand = argv[2];
+    try {
+        if (subcommand === 'create') {
+            runCreate(env, exec);
+            return 0;
+        }
+        if (subcommand === 'complete') {
+            runComplete(env, exec);
+            return 0;
+        }
+        throw new CheckRunError(`Unknown subcommand "${String(subcommand)}". Use create or complete.`);
+    }
+    catch (error) {
+        process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
+/* v8 ignore next 3 */
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    process.exitCode = runCheckRunCli();
+}

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

@@ -0,0 +1,30 @@
+import type { GhExec } from '../gha-post-review/github.mts';
+export declare class CheckRunError extends Error {
+    constructor(message: string);
+}
+export type CheckRunStatus = 'in_progress' | 'completed';
+export type CheckRunConclusion = 'success' | 'neutral';
+export type CreateCheckRunInput = {
+    repository: string;
+    name: string;
+    headSha: string;
+    title: string;
+    summary: string;
+} & ({
+    status: 'in_progress';
+    conclusion?: undefined;
+} | {
+    status: 'completed';
+    conclusion: CheckRunConclusion;
+});
+export type CompleteCheckRunInput = {
+    repository: string;
+    checkRunId: string;
+    conclusion: CheckRunConclusion;
+    title: string;
+    summary: string;
+};
+/** Creates a GitHub check run, returning the API-assigned check run id. */
+export declare function createCheckRun(input: CreateCheckRunInput, exec: GhExec): string;
+/** Transitions an existing check run to `completed` with a final conclusion. */
+export declare function completeCheckRun(input: CompleteCheckRunInput, exec: GhExec): void;

package/dist/gha-check-run/github.mjs

@@ -0,0 +1,63 @@
+export class CheckRunError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CheckRunError';
+    }
+}
+function isFullCommitSha(value) {
+    return /^[0-9a-f]{40}$/u.test(value);
+}
+function isCheckRunId(value) {
+    return /^[0-9]+$/u.test(value);
+}
+function parseCheckRunId(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CheckRunError('Check run creation response was not valid JSON.');
+    }
+    const id = parsed !== null && typeof parsed === 'object' ? parsed.id : undefined;
+    if (typeof id !== 'number' && typeof id !== 'string') {
+        throw new CheckRunError('Check run creation response did not include an id.');
+    }
+    return String(id);
+}
+/** Creates a GitHub check run, returning the API-assigned check run id. */
+export function createCheckRun(input, exec) {
+    if (!isFullCommitSha(input.headSha)) {
+        throw new CheckRunError('headSha must be a full lowercase 40-character commit SHA.');
+    }
+    const body = {
+        name: input.name,
+        head_sha: input.headSha,
+        status: input.status,
+        output: { title: input.title, summary: input.summary },
+    };
+    if (input.status === 'completed')
+        body.conclusion = input.conclusion;
+    const raw = exec(['api', '--method', 'POST', `repos/${input.repository}/check-runs`, '--input', '-'], {
+        input: JSON.stringify(body),
+    });
+    return parseCheckRunId(raw);
+}
+/** Transitions an existing check run to `completed` with a final conclusion. */
+export function completeCheckRun(input, exec) {
+    if (!isCheckRunId(input.checkRunId)) {
+        throw new CheckRunError('checkRunId must be a positive integer.');
+    }
+    const body = {
+        status: 'completed',
+        conclusion: input.conclusion,
+        output: { title: input.title, summary: input.summary },
+    };
+    exec([
+        'api',
+        '--method',
+        'PATCH',
+        `repos/${input.repository}/check-runs/${input.checkRunId}`,
+        '--input',
+        '-',
+    ], { input: JSON.stringify(body) });
+}

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

@@ -0,0 +1,2 @@
+export { CheckRunError, completeCheckRun, createCheckRun, type CheckRunConclusion, type CheckRunStatus, type CompleteCheckRunInput, type CreateCheckRunInput, } from './github.mts';
+export { runCheckRunCli } from './cli.mts';

package/dist/gha-check-run/index.mjs

@@ -0,0 +1,2 @@
+export { CheckRunError, completeCheckRun, createCheckRun, } from './github.mjs';
+export { runCheckRunCli } from './cli.mjs';

package/dist/gha-post-review/cli.mjs

@@ -3,7 +3,7 @@ import { writePostedOutput, postReviewFromEnv } from './github.mjs';
 export async function runPostReviewCli(env = process.env) {
     try {
         const result = await postReviewFromEnv(env);
-        writePostedOutput(result.posted, env.GITHUB_OUTPUT);
+        writePostedOutput(result.posted, result.commentCount, env.GITHUB_OUTPUT);
         return 0;
     }
     catch (error) {

package/dist/gha-post-review/github.d.mts

@@ -1,29 +1,13 @@
 import { execFileSync } from 'node:child_process';
-import { type PostResult, type PostReviewIo, type SanitizedReview } from './post.mts';
+import { type PostReviewResult } from './post.mts';
+export { createGhPostReviewIo, postWithGh } from './pull-io.mts';
 export type GhExec = (args: readonly string[], options?: {
     input?: string;
     env?: NodeJS.ProcessEnv;
 }) => string;
 export declare function createGhExec(exec?: typeof execFileSync): GhExec;
-export declare function postWithGh(repository: string, prNumber: string, payload: SanitizedReview, token: string, exec: GhExec): PostResult;
-export declare function writePostedOutput(posted: boolean, outputPath?: string | undefined): void;
-export declare function createGhPostReviewIo(options: {
-    repository: string;
-    prNumber: string;
-    payloadPath: string;
-    payloadBytes: Buffer;
-    token: string;
-    exec: GhExec;
-    expectedHeadSha?: string;
-    expectedBaseSha?: string;
-}): PostReviewIo;
+export declare function writePostedOutput(posted: boolean, commentCount: number, outputPath?: string | undefined): void;
 /** @deprecated Use postReviewWithTokenFromEnv or postClaudeReviewFromEnv explicitly. */
-export declare function postReviewFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, claudeIo?: import("./claude-token.mts").ClaudeTokenIo): Promise<{
-    posted: boolean;
-}>;
-export declare function postReviewWithTokenFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, token?: string | undefined): {
-    posted: boolean;
-};
-export declare function postClaudeReviewFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, claudeIo?: import("./claude-token.mts").ClaudeTokenIo): Promise<{
-    posted: boolean;
-}>;
+export declare function postReviewFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, claudeIo?: import("./claude-token.mts").ClaudeTokenIo): Promise<PostReviewResult>;
+export declare function postReviewWithTokenFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, token?: string | undefined): PostReviewResult;
+export declare function postClaudeReviewFromEnv(env?: NodeJS.ProcessEnv, exec?: GhExec, claudeIo?: import("./claude-token.mts").ClaudeTokenIo): Promise<PostReviewResult>;

package/dist/gha-post-review/github.mjs

@@ -1,11 +1,12 @@
 import { execFileSync } from 'node:child_process';
-import { appendFileSync, rmSync } from 'node:fs';
-import { parseReviewFilesJson } from '../gha-review-payload/index.mjs';
+import { appendFileSync } from 'node:fs';
 import { ReviewPayloadError } from '../gha-review-payload/index.mjs';
+import { readRegularReviewPayload } from '../gha-review-payload/index.mjs';
 import { createActionsClaudeTokenIo, withClaudeAppToken } from './claude-token.mjs';
 import { runPostReview } from './post.mjs';
+import { createGhPostReviewIo } from './pull-io.mjs';
 import { requireEnv, resolveReviewPostToken } from './token.mjs';
-import { readRegularReviewPayload } from '../gha-review-payload/index.mjs';
+export { createGhPostReviewIo, postWithGh } from './pull-io.mjs';
 export function createGhExec(exec = execFileSync) {
     return (args, options) => exec('gh', [...args], {
         encoding: 'utf8',
@@ -13,96 +14,10 @@ export function createGhExec(exec = execFileSync) {
         env: options?.env ?? process.env,
     }).trim();
 }
-export function postWithGh(repository, prNumber, payload, token, exec) {
-    try {
-        exec(['api', '--method', 'POST', `repos/${repository}/pulls/${prNumber}/reviews`, '--input', '-'], {
-            input: JSON.stringify(payload),
-            env: { ...process.env, GH_TOKEN: token, GITHUB_TOKEN: token },
-        });
-        return { ok: true, status: 201, body: '' };
-    }
-    catch (error) {
-        // oxlint-disable-next-line no-mistakes/ts-no-const-aliases -- isolate the process-error shape assertion at the catch boundary
-        const err = error;
-        const text = `${err.stdout ?? ''}${err.stderr ?? ''}${err.message ?? ''}`;
-        const status = Number(/HTTP\s+(\d{3})/u.exec(text)?.[1] ?? 0);
-        return { ok: false, status, body: text };
-    }
-}
-export function writePostedOutput(posted, outputPath = process.env.GITHUB_OUTPUT) {
+export function writePostedOutput(posted, commentCount, outputPath = process.env.GITHUB_OUTPUT) {
     if (!outputPath)
         return;
-    appendFileSync(outputPath, `posted=${posted ? 'true' : 'false'}\n`);
-}
-function readPullState(repository, prNumber, exec) {
-    let lastError;
-    for (let attempt = 1; attempt <= 3; attempt += 1) {
-        try {
-            return exec([
-                'api',
-                `repos/${repository}/pulls/${prNumber}`,
-                '--jq',
-                '[.head.sha, .base.sha, .draft, .state] | @tsv',
-            ]).split('\t');
-        }
-        catch (error) {
-            lastError = error;
-        }
-    }
-    throw lastError;
-}
-export function createGhPostReviewIo(options) {
-    const { repository, prNumber, payloadBytes, token, exec, expectedHeadSha, expectedBaseSha } = options;
-    return {
-        readFile() {
-            return payloadBytes;
-        },
-        removeFile(path) {
-            rmSync(path, { force: true });
-        },
-        getHeadSha() {
-            if (!/^[1-9][0-9]*$/u.test(prNumber)) {
-                throw new ReviewPayloadError('PR_NUMBER must be a positive integer.');
-            }
-            if (Boolean(expectedHeadSha) !== Boolean(expectedBaseSha)) {
-                throw new ReviewPayloadError('EXPECTED_HEAD_SHA and EXPECTED_BASE_SHA must be provided together.');
-            }
-            if (expectedHeadSha && !/^[0-9a-f]{40}$/u.test(expectedHeadSha)) {
-                throw new ReviewPayloadError('EXPECTED_HEAD_SHA must be a full lowercase commit SHA.');
-            }
-            if (expectedBaseSha && !/^[0-9a-f]{40}$/u.test(expectedBaseSha)) {
-                throw new ReviewPayloadError('EXPECTED_BASE_SHA must be a full lowercase commit SHA.');
-            }
-            const state = readPullState(repository, prNumber, exec);
-            const [headSha = '', baseSha = '', draft = '', pullState = ''] = state;
-            if (!/^[0-9a-f]{40}$/u.test(headSha)) {
-                throw new ReviewPayloadError(`Could not resolve PR head SHA (got "${headSha}").`);
-            }
-            if (!/^[0-9a-f]{40}$/u.test(baseSha)) {
-                throw new ReviewPayloadError(`Could not resolve PR base SHA (got "${baseSha}").`);
-            }
-            if (draft !== 'false') {
-                throw new ReviewPayloadError('Pull request became a draft before posting the review.');
-            }
-            if (pullState !== 'open') {
-                throw new ReviewPayloadError('Pull request closed before posting the review.');
-            }
-            if (expectedHeadSha && headSha !== expectedHeadSha) {
-                throw new ReviewPayloadError('PR head changed before posting the selected review.');
-            }
-            if (expectedBaseSha && baseSha !== expectedBaseSha) {
-                throw new ReviewPayloadError('PR base changed before posting the selected review.');
-            }
-            // Preserve the orchestrator-selected revision as the review commit_id after equality checks.
-            return expectedHeadSha || headSha;
-        },
-        listPullFiles() {
-            return parseReviewFilesJson(exec(['api', '--paginate', `repos/${repository}/pulls/${prNumber}/files?per_page=100`]));
-        },
-        postReview(payload) {
-            return postWithGh(repository, prNumber, payload, token, exec);
-        },
-    };
+    appendFileSync(outputPath, `posted=${posted ? 'true' : 'false'}\ncomment_count=${commentCount}\n`);
 }
 /** @deprecated Use postReviewWithTokenFromEnv or postClaudeReviewFromEnv explicitly. */
 export async function postReviewFromEnv(env = process.env, exec = createGhExec(), claudeIo = createActionsClaudeTokenIo(env)) {
@@ -116,6 +31,7 @@ function createPostWithToken(env, exec) {
     const prNumber = requireEnv('PR_NUMBER', env);
     const payloadPath = requireEnv('CODE_REVIEW_PAYLOAD_PATH', env);
     const payloadBytes = readRegularReviewPayload(payloadPath, 'required');
+    const providerName = env.PROVIDER_NAME || undefined;
     return (token) => runPostReview(payloadPath, createGhPostReviewIo({
         repository,
         prNumber,
@@ -125,7 +41,7 @@ function createPostWithToken(env, exec) {
         exec,
         expectedHeadSha: env.EXPECTED_HEAD_SHA ?? '',
         expectedBaseSha: env.EXPECTED_BASE_SHA ?? '',
-    }));
+    }), providerName);
 }
 function withTokenEnv(exec, env, token) {
     const tokenEnv = { ...env, GH_TOKEN: token, GITHUB_TOKEN: token };

package/dist/gha-post-review/post.d.mts

@@ -13,6 +13,12 @@ export type PostReviewIo = {
     listPullFiles(): PullFile[];
     postReview(payload: SanitizedReview): PostResult;
 };
-export declare function runPostReview(payloadPath: string, io: PostReviewIo): {
+export type PostReviewResult = {
     posted: boolean;
+    commentCount: number;
 };
+/**
+ * Posts a validated review, optionally prefixing the body with a provider attribution line.
+ * The attribution is cosmetic (final posted text only); it never affects staged payload bytes.
+ */
+export declare function runPostReview(payloadPath: string, io: PostReviewIo, providerName?: string): PostReviewResult;

package/dist/gha-post-review/post.mjs

@@ -6,7 +6,11 @@ MAX_REVIEW_COMMENTS as MAX_COMMENTS,
 MAX_REVIEW_PAYLOAD_BYTES as MAX_PAYLOAD_BYTES, 
 // oxlint-disable-next-line no-mistakes/ts-no-export-renaming -- preserve the package's established public compatibility name
 ReviewPayloadError as PostReviewError, } from '../gha-review-payload/index.mjs';
-export function runPostReview(payloadPath, io) {
+/**
+ * Posts a validated review, optionally prefixing the body with a provider attribution line.
+ * The attribution is cosmetic (final posted text only); it never affects staged payload bytes.
+ */
+export function runPostReview(payloadPath, io, providerName) {
     try {
         const selectedHeadSha = io.getHeadSha();
         let review = parseReviewPayload(io.readFile(payloadPath), selectedHeadSha);
@@ -20,9 +24,13 @@ export function runPostReview(payloadPath, io) {
         if (io.getHeadSha() !== selectedHeadSha) {
             throw new ReviewPayloadError('PR head changed while preparing the selected review.');
         }
-        const first = io.postReview(review);
+        const commentCount = review.comments.length;
+        const attributedReview = providerName
+            ? { ...review, body: `**${providerName} review**\n\n${review.body}` }
+            : review;
+        const first = io.postReview(attributedReview);
         if (first.ok)
-            return { posted: true };
+            return { posted: true, commentCount };
         throw new ReviewPayloadError(`GitHub review POST failed (HTTP ${first.status}).`);
     }
     finally {