sarif-to-comment 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # sarif-to-comment
 
+## 0.2.0
+
+### Minor Changes
+
+- Write, inspect and extend SARIF without an analyzer, and turn staged Git changes into suggested fixes.
+
+  - New library functions `createSarifDocument`, `addSarifComment`, `inspectSarif` and `addStagedChangesToSarif`, with TypeScript declarations. They work on ordinary in-memory SARIF, never change their input, and accept SARIF from any producer.
+  - New CLI commands `init`, `add-comment`, `inspect`, `add-staged-changes` and `publish`.
+  - `--format human|json` on every command: JSON mode prints exactly one document for every outcome, errors included.
+  - `add-staged-changes` reads only the Git index, never unstaged working-tree content. It attaches a change to a finding only when the finding's lines lie within the change, and fails with an explanation for changes it cannot represent. An existing output file is preserved under a timestamped `.old.` name.
+  - Publishing is unchanged. The original flag-only command keeps its exact behavior, output and exit statuses.
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # 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**:
+Write, inspect and publish [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html) findings as **one GitHub draft pull request review**:
 
 - general feedback in the review body;
 - findings on changed lines as inline comments;
@@ -8,6 +8,13 @@ Publish a ready [SARIF 2.1.0](https://docs.oasis-open.org/sarif/sarif/v2.1.0/err
 
 It is sent in a single create-review request.
 
+The SARIF can come from any analyzer. Or you can write it yourself, with no analyzer:
+- create a document and add findings on lines or line ranges;
+- add the changes you staged with Git as suggested fixes on those findings;
+- inspect the result before publishing.
+
+Every step reads and writes ordinary SARIF and is optional. SARIF from an analyzer can be inspected, given staged changes or published directly, without any setup step.
+
 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.
@@ -15,13 +22,16 @@ The scope is deliberately narrow:
 - **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.
+Requires Node.js 22 or later. There are two surfaces, the **library** (SARIF in memory) and the **CLI** (SARIF files); 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.
+- **[Getting started](https://unpkg.com/sarif-to-comment/docs/getting-started.md):**
+  - credentials, the reviewed commit, the source root and the state path;
+  - complete library and CLI examples for publishing an analyzer's SARIF, and for writing a review yourself from staged changes;
+  - 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.
 
@@ -91,7 +101,8 @@ GH_TOKEN=... npx sarif-to-comment \
   --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.
+- **Optional flags:** `--source-root FILE_URI`, `--old-source-commit FULLSHA`, `--ignore-approval-hold` and `--format human|json`. Run `sarif-to-comment --help` for details; it needs no token and makes no request.
+- **Command form:** `sarif-to-comment publish` followed by the same flags does exactly the same thing. With `--format json` either form prints one JSON document (`status`, `review`, `statePath` and the Markdown `message`), with the same exit status.
 - **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.
@@ -104,6 +115,35 @@ GH_TOKEN=... npx sarif-to-comment \
 | 3 | uncertain: retry with the same `--state` |
 | 1 | usage error, unreadable or unparsable SARIF file, refused request, or operational failure (details on stderr) |
 
+## Quick start: write a review yourself
+
+```sh
+# In the repository, with your proposed change staged (git add); unstaged edits are ignored.
+npx sarif-to-comment init --output review.sarif --tool-name "Review agent"
+npx sarif-to-comment add-comment --sarif review.sarif --file src/parse.js --line 2 \
+  --message "Handle the empty-input case."
+npx sarif-to-comment add-staged-changes --sarif review.sarif --output review.staged.sarif \
+  --worktree . --repo acme/widgets --commit c0dec0dec0dec0dec0dec0dec0dec0dec0dec0de
+npx sarif-to-comment inspect --sarif review.staged.sarif
+GH_TOKEN=... npx sarif-to-comment publish --sarif review.staged.sarif --repo acme/widgets --pull 42 \
+  --commit c0dec0dec0dec0dec0dec0dec0dec0dec0dec0de --state /var/lib/reviews/acme-widgets-42.json
+```
+
+The library has the same operations for in-memory SARIF: `createSarifDocument`, `addSarifComment`, `inspectSarif`, `addStagedChangesToSarif` and `publishSarifReview`. Each returns a new document or a view and never changes its input.
+
+- **Line numbers** refer to the reviewed commit. For a file the reviewed commit doesn't have, they refer to its staged content.
+- **Associating changes with findings.** Only the staged index is read. A staged change becomes a fix on a finding only when the finding's lines lie within the lines the change replaces; neither is enlarged.
+  - A finding that only partly overlaps a change stays a comment. The receipt says so.
+  - A change that no finding explains is kept as a short factual finding attributed to `sarif-to-comment`. A change that only adds lines replaces no reviewed line, so it is never credited to a nearby finding; the receipt marks it `insertion: true`.
+  - Findings that already have fixes are never changed. If your staged change differs from such a fix on the same lines, the command fails rather than choose between them.
+- **Files.** `init` refuses to overwrite an existing file. `add-comment` updates its SARIF file in place, atomically. `add-staged-changes` writes a separate output; if that output file already exists, it's first renamed to `<UTC time>.old.<name>`, and a failed run writes no output.
+- **Output.** `inspect` shows every finding in full, with its locations and fixes, plus log-level and inline external properties verbatim. Only fix previews are shortened, visibly. It doesn't check whether the file can be published.
+  - `--format json` on any command prints one JSON document for every outcome, errors included. Exit statuses are the same in both formats.
+  - Exit statuses: 0 success; 2 content refused (not valid SARIF, or a staged change that can't be represented); 1 usage or operational error. `publish` keeps the exit statuses below.
+- **Changes that can't be represented.** Staged edits to UTF-8 text files become fixes. Publication still checks native-suggestion compatibility: empty reviewed files, or files containing only a byte-order mark, have no source line for an inline suggestion and are blocked. File creations and deletions become proposed file operations: `inspect` shows them, but `publish` doesn't support them yet and blocks the review. `add-staged-changes` fails, naming the path, for mode changes, symbolic links, submodules, binary or non-UTF-8 files, conflicts and intent-to-add entries.
+
+See the [getting-started guide](https://unpkg.com/sarif-to-comment/docs/getting-started.md#write-a-review-yourself) for complete, tested examples of both surfaces and of SARIF from an analyzer.
+
 ## 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.
@@ -181,7 +221,8 @@ If that comparison can't establish the old side, you may pass `oldSourceCommit`
 - 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.
-- Releases from the private source repository carry no npm provenance attestation (see [Releasing](#releasing)).
+- Authoring can't yet remove or correct a finding in place, and there's no standalone check that a document can be published; `publish` performs every check. Staged file creations and deletions can be recorded in SARIF, but can't be published yet.
+- 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
 
@@ -242,7 +283,11 @@ Changesets pre mode (prereleases) is not part of this release path.
 
      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.
 
-   The workflow publishes but does not create git tags. npm records the published commit (`gitHead`). Maintainers may run `pnpm changeset git-tag` locally and push the tags if they want them.
+   **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.
 
@@ -259,4 +304,4 @@ On the package's **Settings → Trusted publishing** page, add a GitHub Actions
 
 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.** npm attaches provenance automatically only when the source repository is public. The source repository is private, so its releases carry no provenance attestation. The workflow deliberately does not pass `--provenance`, which would fail for a private repository. If the repository is made public, npm will add provenance with no workflow change.
+**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

@@ -2,263 +2,17 @@
 'use strict';
 
 /**
- * Thin command-line interface over publishSarifReview (src/index.cjs).
+ * The sarif-to-comment executable. All behavior lives in src/cli.cjs, which
+ * documents the commands, the flag-only publisher, output formats and exit
+ * statuses; this file only connects it to the process.
  *
- * 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
+ * main({ argv, env, stdout, stderr, stdin?, cwd? }, internals?) -> Promise<exitCode>
+ *   Exported for the test wrappers; `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;
-}
+const { main } = require('../src/cli.cjs');
 
 if (require.main === module) {
   main({ argv: process.argv.slice(2), env: process.env, stdout: process.stdout, stderr: process.stderr }).then(
@@ -267,7 +21,7 @@ if (require.main === module) {
     },
     (err) => {
       process.stderr.write(`sarif-to-comment: unexpected failure: ${err && err.message}\n`);
-      process.exitCode = EXIT.failure;
+      process.exitCode = 1;
     },
   );
 }

package/docs/api/index.md

@@ -24,7 +24,7 @@ Description
 
 </td><td>
 
-Publish a ready SARIF 2.1.0 document as one GitHub draft pull request review.
+Author, inspect and extend SARIF 2.1.0, and publish it as one GitHub draft pull request review.
 
 
 </td></tr>

package/docs/api/sarif-to-comment.addsarifcomment.md

@@ -0,0 +1,91 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sarif-to-comment](./sarif-to-comment.md) &gt; [addSarifComment](./sarif-to-comment.addsarifcomment.md)
+
+## addSarifComment() function
+
+Adds one finding on a line or line range to a copy of a SARIF document.
+
+**Signature:**
+
+```typescript
+export declare function addSarifComment(sarif: object, comment: ISarifComment): AddSarifCommentOutcome;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+sarif
+
+
+</td><td>
+
+object
+
+
+</td><td>
+
+A SARIF log as a parsed JSON object.
+
+
+</td></tr>
+<tr><td>
+
+comment
+
+
+</td><td>
+
+[ISarifComment](./sarif-to-comment.isarifcomment.md)
+
+
+</td><td>
+
+The finding.
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+[AddSarifCommentOutcome](./sarif-to-comment.addsarifcommentoutcome.md)
+
+`added` with the new document, or `invalid` if the input is not schema-valid SARIF or has no run.
+
+## Exceptions
+
+`TypeError` for a malformed comment, a run index out of range, or a document with several runs and no `run` choice.
+
+## Remarks
+
+Works on any schema-valid SARIF, whether it came from[createSarifDocument()](./sarif-to-comment.createsarifdocument.md) or from another producer. The input is copied and never changed; every existing run, finding and property is kept. Only what you supply is written: no source is read, so lines are checked later, by [addStagedChangesToSarif()](./sarif-to-comment.addstagedchangestosarif.md) and by publication.
+
+## Example
+
+
+```ts
+import { createSarifDocument, addSarifComment } from 'sarif-to-comment';
+
+let sarif = createSarifDocument({ tool: { name: 'Review agent' } });
+const added = addSarifComment(sarif, { file: 'src/parse.js', line: 2, message: 'Handle empty input.' });
+if (added.status === 'added') sarif = added.sarif;
+```
+

package/docs/api/sarif-to-comment.addsarifcommentoutcome.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sarif-to-comment](./sarif-to-comment.md) &gt; [AddSarifCommentOutcome](./sarif-to-comment.addsarifcommentoutcome.md)
+
+## AddSarifCommentOutcome type
+
+Every outcome of [addSarifComment()](./sarif-to-comment.addsarifcomment.md)<!-- -->, discriminated by `status`<!-- -->.
+
+**Signature:**
+
+```typescript
+export type AddSarifCommentOutcome = IAddedSarifCommentOutcome | IInvalidSarifOutcome;
+```
+**References:** [IAddedSarifCommentOutcome](./sarif-to-comment.iaddedsarifcommentoutcome.md)<!-- -->, [IInvalidSarifOutcome](./sarif-to-comment.iinvalidsarifoutcome.md)
+

package/docs/api/sarif-to-comment.addstagedchangesoutcome.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sarif-to-comment](./sarif-to-comment.md) &gt; [AddStagedChangesOutcome](./sarif-to-comment.addstagedchangesoutcome.md)
+
+## AddStagedChangesOutcome type
+
+Every outcome of [addStagedChangesToSarif()](./sarif-to-comment.addstagedchangestosarif.md)<!-- -->, discriminated by `status`<!-- -->.
+
+**Signature:**
+
+```typescript
+export type AddStagedChangesOutcome = IAddedStagedChangesOutcome | IInvalidSarifOutcome | IFailedStagedChangesOutcome;
+```
+**References:** [IAddedStagedChangesOutcome](./sarif-to-comment.iaddedstagedchangesoutcome.md)<!-- -->, [IInvalidSarifOutcome](./sarif-to-comment.iinvalidsarifoutcome.md)<!-- -->, [IFailedStagedChangesOutcome](./sarif-to-comment.ifailedstagedchangesoutcome.md)
+

package/docs/api/sarif-to-comment.addstagedchangestosarif.md

@@ -0,0 +1,66 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [sarif-to-comment](./sarif-to-comment.md) &gt; [addStagedChangesToSarif](./sarif-to-comment.addstagedchangestosarif.md)
+
+## addStagedChangesToSarif() function
+
+Adds the changes staged in a Git index, relative to a reviewed commit, to a copy of a SARIF document as fixes on the findings they belong to.
+
+**Signature:**
+
+```typescript
+export declare function addStagedChangesToSarif(input: IAddStagedChangesInput): Promise<AddStagedChangesOutcome>;
+```
+
+## Parameters
+
+<table><thead><tr><th>
+
+Parameter
+
+
+</th><th>
+
+Type
+
+
+</th><th>
+
+Description
+
+
+</th></tr></thead>
+<tbody><tr><td>
+
+input
+
+
+</td><td>
+
+[IAddStagedChangesInput](./sarif-to-comment.iaddstagedchangesinput.md)
+
+
+</td><td>
+
+The document, worktree, reviewed commit and repository.
+
+
+</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;[AddStagedChangesOutcome](./sarif-to-comment.addstagedchangesoutcome.md)<!-- -->&gt;
+
+`added` with the new document and a receipt, `invalid` for input that is not schema-valid SARIF, or `failed`<!-- -->.
+
+## Exceptions
+
+`TypeError` for malformed input; an `Error` when Git cannot be run, the worktree is not in a repository, or the reviewed commit is not available locally.
+
+## Remarks
+
+Reads one snapshot of the index and the reviewed commit by blob identity; working-tree files, filters and hooks are never used, and nothing in the repository is changed. Applying the resulting replacements to the reviewed files reproduces the staged files exactly.
+
+A finding receives a change only when its lines lie within the change's reviewed lines; neither is enlarged. Findings with their own fixes are never changed. A change no finding explains is added as a factual result in a new run attributed to this package. File creation and deletion become proposed file operations, which inspection shows but the current publisher refuses. Unsupported changes fail the whole call rather than being dropped.
+