sarif-to-comment 0.0.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# sarif-to-comment
+
+## 0.1.1
+
+### Patch Changes
+
+- e3a0c2a: Correct the release documentation shipped in the README.
+
+  - Provenance is described conditionally. Trusted publishing authenticates with OIDC from a private or public repository, but npm attaches a provenance attestation only when the source repository is public at publish time. Version 0.1.0 carries a verified attestation; a release from a private repository has none.
+  - Release commits are no longer said to be recorded as `gitHead`, which is absent from the registry metadata for 0.1.0. The commit is identified by the `publish.yml` run and, when present, the provenance attestation; tags remain optional.
+
+## 0.1.0
+
+### Minor Changes
+
+- d13d144: First release: publish a ready SARIF 2.1.0 document as one GitHub draft pull request review.
+
+  - Library (`publishSarifReview`, in-memory SARIF) and CLI (`sarif-to-comment`) share one validation, placement and publication core.
+  - Whole-review validation: invalid, inconsistent, unsupported or held input blocks the entire review before any write.
+  - General feedback in the review body, exact inline comments on changed lines, and supported fixes as native suggestions, sent in one create-review request pinned to the reviewed commit.
+  - Durable, never-duplicating delivery: a caller-chosen state path records intent before sending, and retries confirm the review on GitHub instead of creating another.
+  - TypeScript declarations, a getting-started guide and generated API reference are included in the package.

package/README.md

@@ -0,0 +1,266 @@
+# sarif-to-comment
+
+Publish a ready [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html) document as **one GitHub draft pull request review**:
+
+- general feedback in the review body;
+- findings on changed lines as inline comments;
+- supported fixes as native suggestions.
+
+It is sent in a single create-review request.
+
+The scope is deliberately narrow:
+
+- **One-way.** SARIF goes to GitHub once. The tool never updates, reconciles, submits, restores or deletes a review afterwards. Supplying a new SARIF document (with a new state path) creates a separate review.
+- **Drafts only.** The review is created pending. A person submits it on GitHub.
+- **Whole review or nothing.** If any finding can't be published faithfully, nothing is published, and the tool explains why.
+- **Never duplicated.** A durable state file makes retries confirm the existing review instead of creating another.
+
+Requires Node.js 22 or later. There are two surfaces, the **library** (SARIF in memory) and the **CLI** (a SARIF file); both run the same code.
+
+## Documentation
+
+These documents are included in the package. The links open them on unpkg (for the latest published version) and need no access to the source repository.
+
+- **[Getting started](https://unpkg.com/sarif-to-comment/docs/getting-started.md):** credentials, the reviewed commit, source root and state path, a complete library example and a complete CLI example, and how to handle every outcome.
+- **[API reference](https://unpkg.com/sarif-to-comment/docs/api/index.md):** generated by API Documenter from the package's TypeScript declarations.
+- **[Changelog](https://unpkg.com/sarif-to-comment/CHANGELOG.md):** release notes produced by Changesets.
+
+After installation, the same files are in `node_modules/sarif-to-comment/docs/` and `node_modules/sarif-to-comment/CHANGELOG.md`.
+
+## Installation
+
+```sh
+npm install sarif-to-comment
+npx sarif-to-comment --help
+```
+
+The package ships:
+- the library (CommonJS, usable from ES modules) with TypeScript declarations;
+- the CLI;
+- the vendored official SARIF schema;
+- the documentation above.
+
+It has three runtime dependencies (`ajv`, `ajv-draft-04`, `ajv-formats`).
+
+## Quick start: library
+
+SARIF is passed as an in-memory object; no temporary file is needed.
+
+```js
+import { publishSarifReview } from 'sarif-to-comment';
+
+const outcome = await publishSarifReview({
+  sarif, // the parsed SARIF log (a plain JSON object)
+  destination: { owner: 'acme', repo: 'widgets', pullNumber: 42 },
+  reviewedCommit: 'c0dec0dec0dec0dec0dec0dec0dec0dec0dec0de', // full 40-character SHA
+  statePath: '/var/lib/my-linter/reviews/acme-widgets-42-run-1817.json', // absolute; keep it
+  token: process.env.GH_TOKEN, // a personal access token or user token
+  // sourceRootUri: 'file:///home/ci/work/widgets/', // optional: repo root in the producer's file system
+  // oldSourceCommit: '<full SHA>',                  // optional: see "Old-side source"
+  // options: { ignoreApprovalHold: true },          // optional: see "Approval hold"
+});
+
+console.log(outcome.markdown); // always a human-readable explanation
+if (outcome.status === 'published') console.log(outcome.review.url);
+```
+
+`status` is one of:
+- `published`: the publication is complete, and `review` has the review's `id` and `url`. A repeated call answers from the state file without contacting GitHub, so a person may since have submitted, edited or deleted the review; the tool does not check.
+- `blocked`: nothing was written anywhere.
+- `uncertain`: retry with the same `statePath`.
+- `rejected`: GitHub refused the request; it is never resent.
+
+The contract is `status` plus `markdown`, and `review` or `statePath` where listed. Internal diagnostic codes are not part of it and may change. The [getting-started guide](https://unpkg.com/sarif-to-comment/docs/getting-started.md) has a complete, runnable version of this example with outcome handling.
+
+The promise rejects for:
+- invalid input (a `TypeError`, before any network request);
+- a corrupt state file, or a state path reused for different input;
+- operational failures, such as a network error or an unreachable pull request.
+
+A rejection never contains the token.
+
+The `sarif` value is copied when the call starts, so changing your object afterwards has no effect. Getters are never run. The copy refuses cycles and values JSON can't represent (functions, `undefined`, `NaN`, class instances and so on), rather than silently dropping them.
+
+## Quick start: CLI
+
+```sh
+GH_TOKEN=... npx sarif-to-comment \
+  --sarif results.sarif \
+  --repo acme/widgets --pull 42 \
+  --commit c0dec0dec0dec0dec0dec0dec0dec0dec0dec0de \
+  --state /var/lib/my-linter/reviews/acme-widgets-42-run-1817.json
+```
+
+- **Optional flags:** `--source-root FILE_URI`, `--old-source-commit FULLSHA` and `--ignore-approval-hold`. Run `sarif-to-comment --help` for details; it needs no token and makes no request.
+- **Same core as the library:** the CLI reads the file, calls the same `publishSarifReview`, and prints the same Markdown to stdout.
+- **File encoding:** the SARIF file must be UTF-8 JSON.
+  - A leading UTF-8 byte-order mark is ignored, so the CLI and a library caller passing the same parsed document produce the same publication.
+  - A file that is not valid UTF-8 (including UTF-16) is refused before any request is made. Its bytes are never silently replaced.
+
+| Exit status | Meaning |
+| --- | --- |
+| 0 | published (or already published) |
+| 2 | blocked: nothing was published |
+| 3 | uncertain: retry with the same `--state` |
+| 1 | usage error, unreadable or unparsable SARIF file, refused request, or operational failure (details on stderr) |
+
+## Credentials
+
+Use a GitHub **personal access token or user token**. It needs permission to read the repository and to create pull request reviews; for a fine-grained token that is *Contents: Read* and *Pull requests: Read and write*. The CLI reads `GH_TOKEN`, or else `GITHUB_TOKEN`; there is no token flag.
+
+Authentication uses the authenticated user's identity. GitHub App installation tokens, including the automatic `GITHUB_TOKEN` of GitHub Actions workflows, are **not supported**.
+
+The token is never written to the state file, never included in any fingerprint, and never printed. It is redacted from errors.
+
+This review credential is unrelated to how the package itself is published. npm releases use [trusted publishing](https://docs.npmjs.com/trusted-publishers/), a maintainer concern described under [Releasing](#releasing).
+
+## The state path: retries, recovery and concurrency
+
+`statePath` (`--state`) is the durable identity of **one** publication. You choose it, and you must keep it.
+
+- Before anything is sent, the tool writes the complete intended review and a hidden marker to that file and flushes it to disk. Only the process that creates the file sends, and it sends once.
+- **Retry with the same state path.** A later run never sends again. It returns the recorded result, or checks GitHub for the marker and confirms the complete review. It doesn't need the branch to still exist or the SARIF to still apply, because it works from the saved request.
+- **After an `uncertain` result, do not delete the state file.** Delivery could not be confirmed: the response may have been lost, or the review may not be visible yet. The file is the only record that a review may already exist, and deleting it risks a duplicate. Retry later with the same path. The tool never repairs or restores anything it finds.
+- **A new state path means a new, separate review.** Use one only when you deliberately want another review, for example for new SARIF.
+- Concurrent runs on the same state path are safe: exactly one sends and the others only check.
+- **The state path is bound to its input.**
+  - Reusing it with different SARIF, a different pull request or commit, or a different source root or old-side candidate is refused.
+  - An unresolved publication also checks the authenticated account.
+  - Completed and rejected records return without authentication or network calls; the API still requires a token-shaped input.
+- The state file is created with owner-only permissions. It requires a local file system that supports hard links.
+
+## One pending review per account
+
+GitHub lets an account hold only **one pending (draft) review per pull request**, and refuses a second one with HTTP 422. If your account already has a draft on the pull request — made by a person or by an earlier run — publication is `rejected`. The tool never submits, edits or deletes an existing draft to make room. A person has to submit or delete it on GitHub, and then you publish again with a new state path.
+
+A refused request is recorded in the state file. Later runs with that path report the refusal without contacting GitHub, and never resend it.
+
+## Supported SARIF (first-milestone profile)
+
+- **Whole-review validation.** The document is validated against the official SARIF 2.1.0 schema, then checked for consistency against the pull request's actual source. Invalid input or an unsupported finding, source association or fix blocks the entire review. Every accepted finding is included; this is not a lossless rendering of all SARIF metadata.
+- **General findings.** A result without a location goes in the review body.
+- **Findings with a location.** A result with one physical location becomes an inline comment when it maps exactly onto a line of the pull request's diff at the reviewed commit. Otherwise it goes in the body with an exact permalink to that commit and a copy of the source. Nothing is ever placed on a nearby or different line.
+- **Suggestions.** A fix with one text replacement on the reviewed head, inside the diff, becomes a native GitHub suggestion.
+  - A located result must refer to the same file and revision, with its lines contained in the replacement's lines. Otherwise this profile refuses the association; keep the correct finding location and separate the feedback from the unsupported fix.
+  - Cases GitHub doesn't apply faithfully are refused before anything is written: raw CR in the suggestion payload, nested triple-backtick fences, blank-only replacements and unsafe final-line deletions.
+- **Refused features.** Multiple locations, related locations, code flows, graphs, stacks, attachments, suppressions, alternative or multi-file fixes, and file creation or deletion proposals are refused with an explanation.
+- **Metadata limits.**
+  - Producer fingerprints, rank and occurrence counts are not rendered.
+  - A logical location accompanying a physical location is not rendered; a logical-only location is unsupported.
+  - Taxonomy classifications remain in preparation evidence but are not shown in the review.
+- **Result limits.** Results are limited to 100 inline comments, 60,000 characters per body or comment, and about 1 MB per request. These are conservative product limits, not GitHub maxima.
+- **Pull request limits.** Pull requests changing more than 3,000 files, and source files larger than 1,000,000 bytes or not valid UTF-8, are refused rather than read partially. A file whose patch GitHub omits cannot receive inline comments.
+
+### Approval hold
+
+A run or result may declare `properties.sarifToComment.approval: "awaiting-approval"`. Publication then stops with `blocked`.
+
+`options.ignoreApprovalHold` (`--ignore-approval-hold`) overrides **only** that hold, never any other check. The override is not part of the publication's identity, so a retry doesn't need to repeat it.
+
+### Reviewed commit and historical reviews
+
+The review is always tied to `reviewedCommit`, even when the author's branch has moved on since. If the pull request's head has advanced past the reviewed commit, the tool doesn't retarget the review. Findings that can no longer be anchored inline go in the body as exact links to the reviewed commit.
+
+### Old-side source
+
+Findings about deleted or original lines need to know the diff's old side. By default the tool asks GitHub to compare the pull request, and verifies each old file by reversing the pull request's own patch against the exact file contents. Old-side source of renamed files is not supported.
+
+If that comparison can't establish the old side, you may pass `oldSourceCommit` (`--old-source-commit`) as a candidate. It is verified the same way, never trusted blindly, and it becomes part of the publication's identity. SARIF provenance naming other revisions is still published as general feedback. It is never chosen automatically as the diff's old side.
+
+## Limitations
+
+- **Live verification.** The library and CLI have been verified against live GitHub. The runs covered:
+  - complete pending reviews, with exact source and original-anchor readback;
+  - rendered inline comments and suggestions, and general feedback;
+  - branch advance;
+  - read-only recovery after a discarded create response and after a process kill.
+
+  These bounded fixture runs do not establish every host failure mode or suggestion shape. Native application of one-line-to-three, two-lines-to-one and middle-line deletion suggestions was verified by exact resulting file bytes and Git blob identities. Inline-only and CRLF-source review bodies also read back exactly. The evidence is recorded in the source repository (`docs/milestone-e2e-evidence.md` and `docs/suggestion-application-e2e.md`).
+- Only `https://api.github.com` is supported.
+- The hidden marker only identifies a review; it is not a secret. A human edit to an unconfirmed draft leaves delivery `uncertain` rather than being "fixed".
+- The durability steps (write, flush, then send) are ordered for crash safety, but that has not been tested against power loss.
+- GitHub Enterprise Server and GitHub App installation tokens are not supported.
+- There is no review maintenance, re-review or synchronisation back to SARIF.
+- npm attaches a provenance attestation only when the source repository is public at publish time. A release published while the repository is private has no provenance attestation (see [Releasing](#releasing)).
+
+## Development
+
+```sh
+pnpm install
+pnpm test                  # node --test test/*.test.cjs
+pnpm run check             # lint, types, API report/docs freshness, release plan, tests (read-only)
+pnpm run build             # regenerate api-report/ and docs/api/ after changing types/index.d.ts
+pnpm changeset             # describe a change for the next release
+```
+
+The public TypeScript declarations are written by hand in `types/index.d.ts` and must match the CommonJS runtime in `src/index.cjs`. API Extractor checks them and writes a reviewable API report (`api-report/`) and a doc model. API Documenter renders the doc model as the Markdown reference in `docs/api/`. `pnpm run check` fails when either is out of date.
+
+## Releasing
+
+Releases use [Changesets](https://changesets.dev/) for versioning and [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) for publication. They are published only by the GitHub Actions workflow `.github/workflows/publish.yml`, which authenticates with a short-lived OIDC token. There is no npm token in the repository or its secrets.
+
+### Versions stay below 1.0.0
+
+`MAXIMUM_RELEASE_MAJOR` in `scripts/release-guard.cjs` is `0`. Until someone deliberately raises it in a reviewed change, nothing can version or publish `1.0.0` or higher, including prereleases such as `1.0.0-rc.0`:
+
+- **`pnpm run check`** (run in CI on every pull request) fails if a pending changeset would reach 1.0.0. A `major` changeset is refused with an explanation. It is never quietly converted to a smaller bump; choose `minor` yourself if the change shouldn't start 1.0.
+- **`pnpm run release:version`** refuses the same plans before `changeset version` changes any file.
+- **What counts as the plan.** The guard doesn't parse changeset files itself. It runs the real `changeset version` in a throwaway copy and judges the version and changelog entry Changesets produces, so any front matter Changesets accepts is judged by its actual effect. That includes quoted values such as `"sarif-to-comment": "major"`. A changeset Changesets can't read is refused, not ignored.
+- **The publish workflow** refuses any `package.json` version of 1.0.0 or higher, and so does the `prepublishOnly` backstop for a manual publish.
+
+Changesets pre mode (prereleases) is not part of this release path.
+
+**Deliberately releasing 1.0.** In a reviewed change, raise `MAXIMUM_RELEASE_MAJOR` to `1` and update the test in `test/release.test.cjs` that pins its value. That is the only step: a `major` changeset then versions and publishes `1.0.0` through the normal flow above, while `2.0.0` and above stay blocked.
+
+### Making a release
+
+1. With each change, add a changeset (`pnpm changeset`) choosing `patch` or `minor`, and merge it to `main` with the change.
+2. To release, run `pnpm run release:version` on an up-to-date `main`. It checks the pending plan, then runs `changeset version`, which:
+   - bumps `package.json`;
+   - writes the `CHANGELOG.md` entry;
+   - consumes the changesets.
+
+   Review and commit the result, then push it to `main`, for example through a pull request.
+3. When that version bump reaches `main`, `.github/workflows/publish.yml` runs. It runs only for `main` pushes that change `package.json`, and never for pull requests or other branches. Its release guard decides first:
+   - **Already on npm:** a version that is already published is a no-op.
+   - **Otherwise, refused unless all of these hold:**
+     - the version is stable and below 1.0.0;
+     - `CHANGELOG.md`'s newest entry is that version, which shows Changesets produced it;
+     - pre mode is off;
+     - the package metadata is publishable, with the exact repository URL;
+     - the commit is on `main`;
+     - npm is at least 11.5.1 and Node at least 22.14.0.
+   - **When allowed:** it runs `pnpm run check`, packs the tarball, verifies it contains exactly the distribution files, and publishes that tarball.
+
+   Publishes never overlap, and a publish in progress is never cancelled.
+4. **If publishing fails**, what to do depends on where the cause is. A version npm has already accepted can never be republished.
+   - **Outside the repository:** a transient registry, network or runner failure, or npm trusted-publisher settings that are missing or wrong. Correct it there, then re-run the failed workflow run. A re-run executes the same commit with the same workflow file, so it is only the right tool when nothing in the repository needs to change.
+   - **In the repository:** the release guard, the workflow, a test, the package contents or its metadata. A re-run would repeat the same code, and a push to `main` that doesn't change `package.json` does not start a publish run. Merge the fix to `main`, then prepare the next patch release:
+     1. add a `patch` changeset with `pnpm changeset`;
+     2. run `pnpm run release:version`;
+     3. merge the resulting commit.
+
+     That commit changes `package.json`, so the workflow runs with the fixed code and publishes the new version. The version that failed stays unpublished; its changelog entry remains as history.
+
+   **Recording the release commit.** The workflow publishes the verified tarball but doesn't create git tags, and npm's registry metadata for 0.1.0 records no `gitHead`. Do not assume that field identifies a tarball release. The commit is identified in two places:
+   - by the successful `publish.yml` workflow run for that commit on `main`;
+   - when the repository is public at publish time, by the version's npm provenance attestation, which names the source repository, workflow and commit.
+
+   Maintainers who want tags can run `pnpm changeset git-tag` locally on that commit and push the tags.
+
+**First release.** The release history starts from npm's pre-existing `0.0.0`, the bootstrap baseline for this package. The initial `minor` changeset versions that baseline to **0.1.0**, with the first changelog entry, and 0.1.0 is the first version this workflow publishes. Later releases follow the same steps from whatever version `package.json` then holds.
+
+### One-time setup (npmjs.com)
+
+On the package's **Settings → Trusted publishing** page, add a GitHub Actions trusted publisher:
+
+| Field | Value |
+| --- | --- |
+| Organization or user | `mike-north` |
+| Repository | `sarif-to-comment` |
+| Workflow filename | `publish.yml` |
+| Environment | *(leave empty)* |
+
+npm requires `repository.url` in `package.json` to match this repository exactly. It is `git+https://github.com/mike-north/sarif-to-comment.git`. Once a trusted release has succeeded, npm recommends setting **Publishing access** to *Require two-factor authentication and disallow tokens*.
+
+**Provenance.** Trusted publishing authenticates with OIDC from a private or public repository alike. npm attaches a provenance attestation automatically only when the source repository is public at publish time; a release from a private repository has no provenance attestation. That limitation comes from npm, not from this workflow, and the workflow never changes repository visibility. Version 0.1.0 was published from the repository while it was public, and its npm provenance attestation verifies, naming commit `3797ca6efe2156d4c952fad7fed10b569f1dcbbb` and `.github/workflows/publish.yml`. The workflow deliberately does not pass `--provenance`, which fails for a private repository; npm adds provenance on its own whenever the repository is public.

package/bin/sarif-to-comment.cjs

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Thin command-line interface over publishSarifReview (src/index.cjs).
+ *
+ * Reads one SARIF JSON file, calls the same library operation library
+ * consumers use, and prints that operation's Markdown. It has no rendering,
+ * placement or delivery logic of its own: argument parsing, file reading,
+ * credential selection and exit-status mapping are its only concerns.
+ *
+ * Usage:
+ *   sarif-to-comment --sarif FILE --repo OWNER/REPO --pull N --commit FULLSHA
+ *                    --state ABSOLUTE_FILE [--source-root ABSOLUTE_FILE_URI]
+ *                    [--old-source-commit FULLSHA] [--ignore-approval-hold]
+ *   sarif-to-comment --help
+ *
+ * Flags accept `--flag value` or `--flag=value`. Unknown, missing, valueless
+ * or repeated flags and positional arguments are usage errors.
+ * `--ignore-approval-hold` takes no value and bypasses only an approval hold.
+ * There is no token flag and no reset/force-resend flag: `--state` is the
+ * durable identity of one publication; retry with the same path.
+ *
+ * Credential: GH_TOKEN, else GITHUB_TOKEN (empty counts as unset). Both are
+ * treated as user/PAT credentials; automatic Actions tokens are not claimed to
+ * be supported. The token never appears in output; any occurrence in an error
+ * is redacted. `--help` needs no token and makes no network call.
+ *
+ * Output and exit status:
+ *   stdout: the operation's Markdown for any outcome
+ *   stderr: usage, input-file and operational errors (actionable, redacted)
+ *   0 published   2 blocked   3 uncertain
+ *   1 usage error, unreadable/unparsable SARIF file, operational failure,
+ *     local state refusal, or GitHub refusal of the create request
+ *
+ * ---------------------------------------------------------------------------
+ * main({ argv, env, stdout, stderr }, internals?) -> Promise<exitCode>
+ *   argv: arguments after the executable; env: environment variables;
+ *   stdout/stderr: writable streams. `internals` is passed through to
+ *   publishSarifReview (private test seam). Running this file directly calls
+ *   main with the process and sets process.exitCode.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { publishSarifReview } = require('../src/index.cjs');
+
+/** Exit status per public outcome (and for help); every refusal or failure is 1. */
+const EXIT = Object.freeze({ help: 0, published: 0, failure: 1, blocked: 2, uncertain: 3, rejected: 1 });
+
+/** Flags that take exactly one value. */
+const VALUE_FLAGS = new Set(['--sarif', '--repo', '--pull', '--commit', '--state', '--source-root', '--old-source-commit']);
+
+/**
+ * Decoder for SARIF files, which are UTF-8 JSON (SARIF 2.1.0 §3.1, RFC 8259
+ * §8.1). `fatal` refuses bytes that are not valid UTF-8 instead of silently
+ * substituting U+FFFD, which would change what is fingerprinted and
+ * published. A leading UTF-8 byte-order mark is an encoding signature, not
+ * JSON content, so it is removed (the decoder's default, `ignoreBOM: false`);
+ * the library then sees exactly the document a caller would pass in memory.
+ */
+const SARIF_DECODER = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false });
+
+/** Flags that take no value. */
+const BOOLEAN_FLAGS = new Set(['--ignore-approval-hold']);
+
+/** Flags every publication needs. */
+const REQUIRED_FLAGS = ['--sarif', '--repo', '--pull', '--commit', '--state'];
+
+const md = String.raw;
+
+const USAGE = md`sarif-to-comment — publish a ready SARIF file as one GitHub draft review
+
+Usage:
+  sarif-to-comment --sarif FILE --repo OWNER/REPO --pull N --commit FULLSHA
+                   --state ABSOLUTE_FILE [--source-root ABSOLUTE_FILE_URI]
+                   [--old-source-commit FULLSHA] [--ignore-approval-hold]
+  sarif-to-comment --help
+
+Options:
+  --sarif FILE                   SARIF 2.1.0 JSON file to publish.
+  --repo OWNER/REPO              Repository of the pull request.
+  --pull N                       Pull request number.
+  --commit FULLSHA               Full 40-character commit the review is about.
+  --state ABSOLUTE_FILE          Durable publication state. Retry with the same
+                                 file; never delete it after an uncertain
+                                 result. A new file starts a separate review.
+  --source-root ABSOLUTE_FILE_URI
+                                 Repository root in the SARIF producer's file
+                                 system (file:///.../ ending in "/").
+  --old-source-commit FULLSHA    Candidate commit for the diff's old side, used
+                                 only when GitHub's comparison cannot establish
+                                 it; verified against the pull request's patches.
+  --ignore-approval-hold         Publish despite an approval hold (bypasses only
+                                 the hold, never validation).
+  --help                         Show this help. Needs no token, makes no request.
+
+Credentials:
+  GH_TOKEN, or else GITHUB_TOKEN: a GitHub personal access token or user token.
+  GitHub App installation tokens (including the automatic Actions token) are
+  not supported. There is no token flag.
+
+Exit status:
+  0  published (or already published)
+  2  blocked: nothing was published
+  3  uncertain: delivery could not be confirmed; retry with the same --state
+  1  usage error, unreadable SARIF file, refused request, or operational failure
+`;
+
+/** A command-line mistake the user can fix by changing the arguments. */
+class UsageError extends Error {}
+
+/** Parses argv into { help } or { values, flags } exactly; throws UsageError. */
+function parseArgs(argv) {
+  if (argv.includes('--help') || argv.includes('-h')) return { help: true };
+  const values = new Map();
+  const flags = new Set();
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith('--')) throw new UsageError(`unexpected argument ${arg}`);
+    const eq = arg.indexOf('=');
+    const name = eq === -1 ? arg : arg.slice(0, eq);
+    if (name === '--token') {
+      throw new UsageError('unknown option --token: the token is read only from GH_TOKEN or GITHUB_TOKEN');
+    }
+    if (BOOLEAN_FLAGS.has(name)) {
+      if (eq !== -1) throw new UsageError(`${name} takes no value`);
+      if (flags.has(name)) throw new UsageError(`${name} was given more than once`);
+      flags.add(name);
+      continue;
+    }
+    if (!VALUE_FLAGS.has(name)) throw new UsageError(`unknown option ${name}`);
+    if (values.has(name)) throw new UsageError(`${name} was given more than once`);
+    let value;
+    if (eq !== -1) {
+      value = arg.slice(eq + 1);
+    } else {
+      value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) throw new UsageError(`${name} requires a value`);
+      i += 1;
+    }
+    if (value === '') throw new UsageError(`${name} requires a non-empty value`);
+    values.set(name, value);
+  }
+  const missing = REQUIRED_FLAGS.filter((flag) => !values.has(flag));
+  if (missing.length > 0) throw new UsageError(`missing required option ${missing.join(', ')}`);
+  return { help: false, values, flags };
+}
+
+/** Converts parsed flags into library input fields; throws UsageError. */
+function interpretArgs({ values, flags }) {
+  const repo = /^([^/\s]+)\/([^/\s]+)$/.exec(values.get('--repo'));
+  if (!repo) throw new UsageError('--repo must be OWNER/REPO');
+  const pull = values.get('--pull');
+  if (!/^[1-9][0-9]*$/.test(pull) || !Number.isSafeInteger(Number(pull))) {
+    throw new UsageError('--pull must be a positive pull request number');
+  }
+  const commitFlag = (flag) => {
+    const value = values.get(flag);
+    if (value !== undefined && !/^[0-9a-f]{40}$/.test(value)) {
+      throw new UsageError(`${flag} must be a full 40-character lowercase commit SHA`);
+    }
+    return value;
+  };
+  const statePath = values.get('--state');
+  if (!path.isAbsolute(statePath)) throw new UsageError('--state must be an absolute file path');
+  const sourceRootUri = values.get('--source-root');
+  if (sourceRootUri !== undefined && !(sourceRootUri.startsWith('file:') && sourceRootUri.endsWith('/'))) {
+    throw new UsageError('--source-root must be an absolute file: URI ending in "/"');
+  }
+  const input = {
+    destination: { owner: repo[1], repo: repo[2], pullNumber: Number(pull) },
+    reviewedCommit: commitFlag('--commit'),
+    statePath,
+  };
+  const oldSourceCommit = commitFlag('--old-source-commit');
+  if (oldSourceCommit !== undefined) input.oldSourceCommit = oldSourceCommit;
+  if (sourceRootUri !== undefined) input.sourceRootUri = sourceRootUri;
+  if (flags.has('--ignore-approval-hold')) input.options = { ignoreApprovalHold: true };
+  return { sarifPath: values.get('--sarif'), input };
+}
+
+/** The credential from the environment: GH_TOKEN, else GITHUB_TOKEN; empty is unset. */
+function tokenFrom(env) {
+  if (typeof env.GH_TOKEN === 'string' && env.GH_TOKEN !== '') return env.GH_TOKEN;
+  if (typeof env.GITHUB_TOKEN === 'string' && env.GITHUB_TOKEN !== '') return env.GITHUB_TOKEN;
+  return undefined;
+}
+
+/** An error's message and cause chain, one line each. */
+function describeError(err) {
+  const lines = [];
+  const seen = new Set();
+  for (let current = err; current !== undefined && current !== null && !seen.has(current); current = current.cause) {
+    seen.add(current);
+    lines.push(lines.length === 0 ? String(current.message ?? current) : `  caused by: ${current.message ?? current}`);
+    if (!(current instanceof Error)) break;
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Runs the CLI. Returns the exit status; never throws for expected failures.
+ */
+async function main({ argv, env, stdout, stderr }, internals) {
+  const token = tokenFrom(env);
+  const safe = (text) => (token === undefined ? String(text) : String(text).split(token).join('[redacted]'));
+  const fail = (message) => {
+    stderr.write(`sarif-to-comment: ${safe(message)}\n`);
+    return EXIT.failure;
+  };
+
+  let parsed;
+  let request;
+  try {
+    parsed = parseArgs(argv);
+    if (parsed.help) {
+      stdout.write(USAGE);
+      return EXIT.help;
+    }
+    request = interpretArgs(parsed);
+  } catch (err) {
+    if (err instanceof UsageError) return fail(`${err.message}\nRun sarif-to-comment --help for usage.`);
+    throw err;
+  }
+  if (token === undefined) {
+    return fail('no GitHub token: set GH_TOKEN (or GITHUB_TOKEN) to a personal access token or user token.');
+  }
+
+  let bytes;
+  try {
+    bytes = fs.readFileSync(request.sarifPath);
+  } catch (err) {
+    return fail(`cannot read SARIF file ${request.sarifPath}: ${err.message}`);
+  }
+  let text;
+  try {
+    text = SARIF_DECODER.decode(bytes);
+  } catch {
+    return fail(
+      `SARIF file ${request.sarifPath} is not valid UTF-8; nothing was published. SARIF files must be UTF-8 encoded JSON.`,
+    );
+  }
+  let sarif;
+  try {
+    sarif = JSON.parse(text);
+  } catch (err) {
+    return fail(`SARIF file ${request.sarifPath} is not valid JSON: ${err.message}`);
+  }
+
+  let outcome;
+  try {
+    outcome = await publishSarifReview({ ...request.input, sarif, token }, internals);
+  } catch (err) {
+    return fail(describeError(err));
+  }
+  const markdown = safe(outcome.markdown);
+  stdout.write(markdown.endsWith('\n') ? markdown : `${markdown}\n`);
+  return EXIT[outcome.status] ?? EXIT.failure;
+}
+
+if (require.main === module) {
+  main({ argv: process.argv.slice(2), env: process.env, stdout: process.stdout, stderr: process.stderr }).then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (err) => {
+      process.stderr.write(`sarif-to-comment: unexpected failure: ${err && err.message}\n`);
+      process.exitCode = EXIT.failure;
+    },
+  );
+}
+
+module.exports = { main };

package/docs/api/index.md

@@ -0,0 +1,32 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md)
+
+## API Reference
+
+## Packages
+
+<table><thead><tr><th>
+
+Package
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+[sarif-to-comment](./sarif-to-comment.md)
+
+
+</td><td>
+
+Publish a ready SARIF 2.1.0 document as one GitHub draft pull request review.
+
+
+</td></tr>
+</tbody></table>
+

package/docs/api/sarif-to-comment.iblockedoutcome.markdown.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sarif-to-comment](./sarif-to-comment.md) &gt; [IBlockedOutcome](./sarif-to-comment.iblockedoutcome.md) &gt; [markdown](./sarif-to-comment.iblockedoutcome.markdown.md)
+
+## IBlockedOutcome.markdown property
+
+Every problem, with a pointer into the SARIF document.
+
+**Signature:**
+
+```typescript
+readonly markdown: string;
+```