sarif-to-comment 0.1.1 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # sarif-to-comment
 
+## 0.2.1
+
+### Patch Changes
+
+- 6d868ab: The implementation is now strict TypeScript, and the shipped TypeScript declarations are generated from it rather than written by hand.
+
+  - No change to the public API, the CLI or behavior. The declarations describe the same functions and types as before.
+  - The packaged runtime files moved from `src/` and `bin/` to `dist/`. The package entry points are unchanged: `require('sarif-to-comment')`, `import … from 'sarif-to-comment'`, its TypeScript types and the `sarif-to-comment` command resolve through `package.json` as before. Only code that reached into the package's internal file paths is affected.
+
+## 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

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,19 +221,35 @@ 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.
+- 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
 
 ```sh
 pnpm install
-pnpm test                  # node --test test/*.test.cjs
+pnpm run build             # rebuild dist/ from src/, roll up the declarations, regenerate api-report/ and docs/api/
 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 test                  # refuse a missing or stale dist/, then node --test "test/**/*.test.mts"
 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.
+Development and release tooling need Node 22.18.0 or later, enforced by `devEngines` in `package.json`: the tests and the build, check and release scripts are TypeScript that Node runs directly by type stripping. The published package still needs only Node 22 or later (`engines`).
+
+Run `pnpm run build` before `pnpm run check` or `pnpm test`, and again after changing sources or build configuration. The tests exercise, and the package ships, the built `dist/`. `pnpm test` (and therefore `pnpm run check`) refuses a `dist/` that is missing, incomplete, or was built from different sources or configuration; it compares content hashes of every build input and output, not modification times.
+
+The implementation is strict TypeScript, and there are no hand-written declarations. The public TypeScript declarations are generated from the implementation. `src/public-api.cts` declares the public API, and the CommonJS runtime entry `src/index.cts` is checked at compile time to export exactly its functions. `tsc` emits per-module declarations, API Extractor rolls them up into the shipped `dist/sarif-to-comment.d.ts` and writes a reviewable API report (`api-report/`) and a doc model, and API Documenter renders the doc model as the Markdown reference in `docs/api/`. `pnpm run check` fails when either is out of date.
+
+`pnpm run build` rewrites `api-report/` and `docs/api/` whenever the public API or its TSDoc changes; commit them with the change. CI and the publish workflow build and then fail if either differs from the committed copy.
+
+**Repository layout.**
+- `src/*.cts`: the implementation. `tsc` compiles each module to CommonJS in `dist/*.cjs`; `src/index.cts` is the package entry and `src/sarif-to-comment.cts` the CLI executable.
+- `dist/`: build output. It is not committed; the package ships its runtime modules and the rolled-up declarations.
+- `test/`: `node:test` suites (`*.test.mts`), fixtures and helpers, run against `dist/`.
+- `scripts/*.mts`: build, type-check, API documentation and release-guard tooling.
+- `api-report/` and `docs/api/`: generated by `pnpm run build` and committed, so API changes are reviewed.
+- `vendor/`: the official SARIF 2.1.0 schema used for validation.
+- `.changeset/`: pending release notes.
 
 ## Releasing
 
@@ -201,16 +257,16 @@ Releases use [Changesets](https://changesets.dev/) for versioning and [npm trust
 
 ### 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`:
+`MAXIMUM_RELEASE_MAJOR` in `scripts/release-guard.mts` 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.
+- **The publish workflow** refuses any `package.json` version of 1.0.0 or higher, and so does the `prepublishOnly` backstop for a manual publish, which also refuses a missing or stale `dist/`.
 
 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.
+**Deliberately releasing 1.0.** In a reviewed change, raise `MAXIMUM_RELEASE_MAJOR` to `1` and update the test in `test/release.test.mts` 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
 
@@ -229,8 +285,8 @@ Changesets pre mode (prereleases) is not part of this release path.
      - 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.
+     - npm is at least 11.5.1 and Node at least 22.18.0.
+   - **When allowed:** it builds `dist/`, 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.

package/dist/artifact-files.cjs

@@ -0,0 +1,273 @@
+"use strict";
+/**
+ * File handling for the CLI's local SARIF artifacts. The library never touches
+ * files; the command-line interface uses this module so that every receipt it
+ * prints describes what actually happened on disk.
+ *
+ * Responsibilities and guarantees:
+ *   - Reading: SARIF and message files are strict UTF-8 (a leading byte-order
+ *     mark is an encoding signature and is removed); undecodable bytes are
+ *     refused rather than replaced, so nothing is silently altered.
+ *   - Exclusive creation (`createExclusive`): the content is written and
+ *     flushed to a temporary sibling, then hard-linked to the destination,
+ *     which fails if the destination exists. A file therefore appears whole or
+ *     not at all, and an output that reappeared concurrently is never
+ *     overwritten.
+ *   - Ownership (`acquireOwnership`): cooperating sarif-to-comment commands
+ *     editing or producing the same artifact exclude each other with an
+ *     exclusively created marker file, `.<name>.sarif-to-comment-lock`, beside
+ *     the artifact. A marker that already exists is reported, never taken over:
+ *     only a person can know that its owner is gone. The owner removes it when
+ *     it finishes, whatever the outcome.
+ *   - In-place replacement (`replaceIfUnchanged`): the new content is written
+ *     to a temporary sibling with the original mode; immediately before the
+ *     atomic rename the file is re-read and compared with the bytes the edit
+ *     was computed from, and an observed external change is refused. This is
+ *     not a filesystem compare-and-swap: a non-cooperating writer acting
+ *     between that check and the rename is outside the guarantee.
+ *   - Output preservation (`archiveExisting`): an existing output is moved
+ *     aside as `<YYYY-MM-DDTHH-mm-ss.SSSZ>.old.<name>` in its directory, the
+ *     stamp being the file's birth time in UTC (or its modification time when
+ *     the platform reports no birth time), with `-2`, `-3`, … appended to the
+ *     stamp on collision. The archive is an exclusive hard link followed by
+ *     removal of the original name, so it never overwrites anything.
+ *
+ * Failures a user must act on are `ArtifactError`s with actionable messages
+ * that name the paths involved.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArtifactError = void 0;
+exports.readTextFile = readTextFile;
+exports.readJsonFile = readJsonFile;
+exports.createExclusive = createExclusive;
+exports.ownershipMarkerFor = ownershipMarkerFor;
+exports.acquireOwnership = acquireOwnership;
+exports.replaceIfUnchanged = replaceIfUnchanged;
+exports.archiveExisting = archiveExisting;
+exports.sameExistingFile = sameExistingFile;
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+/** A file problem the user must resolve; the message names the paths. */
+class ArtifactError extends Error {
+}
+exports.ArtifactError = ArtifactError;
+/**
+ * A caught failure's `message`, read as a template would read `err.message`.
+ * Node's file-system calls throw Errors (SystemError), so this is their
+ * message; a value without one reads as "undefined".
+ */
+function messageOf(err) {
+    return String(typeof err === 'object' && err !== null && 'message' in err ? err.message : undefined);
+}
+/** A caught failure's Node error `code` (such as `EEXIST`), or undefined when it has none. */
+function codeOf(err) {
+    return typeof err === 'object' && err !== null && 'code' in err ? err.code : undefined;
+}
+/**
+ * Decoder for UTF-8 text files: `fatal` refuses invalid bytes instead of
+ * substituting U+FFFD; the default `ignoreBOM: false` removes a leading BOM.
+ */
+const UTF8 = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false });
+/** Reads a UTF-8 text file; `label` names it in errors (e.g. "message file"). */
+function readTextFile(file, label) {
+    let bytes;
+    try {
+        bytes = fs.readFileSync(file);
+    }
+    catch (err) {
+        throw new ArtifactError(`cannot read ${label} ${file}: ${messageOf(err)}`);
+    }
+    try {
+        return { text: UTF8.decode(bytes), bytes };
+    }
+    catch {
+        throw new ArtifactError(`${label} ${file} is not valid UTF-8; it must be UTF-8 encoded.`);
+    }
+}
+/** Reads a UTF-8 JSON file: { value, bytes } (the bytes as read, for change detection). */
+function readJsonFile(file, label) {
+    const { text, bytes } = readTextFile(file, label);
+    try {
+        const value = JSON.parse(text);
+        return { value, bytes };
+    }
+    catch (err) {
+        throw new ArtifactError(`${label} ${file} is not valid JSON: ${messageOf(err)}`);
+    }
+}
+/** Flushes a directory entry change (best effort where directories cannot be opened). */
+function syncDirectory(dir) {
+    let fd;
+    try {
+        fd = fs.openSync(dir, 'r');
+        fs.fsyncSync(fd);
+    }
+    catch {
+        // Some platforms do not allow fsync on a directory; the rename/link itself is still atomic.
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/** Writes and flushes `text` to a new uniquely named temporary sibling of `file`. */
+function writeTemporarySibling(file, text, mode) {
+    const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${String(process.pid)}.${crypto.randomUUID()}.tmp`);
+    const fd = fs.openSync(temporary, 'wx', mode ?? 0o666);
+    try {
+        fs.writeFileSync(fd, text);
+        if (mode !== undefined)
+            fs.fchmodSync(fd, mode);
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    return temporary;
+}
+/** Removes a temporary file if it is still present. */
+function discard(temporary) {
+    try {
+        fs.unlinkSync(temporary);
+    }
+    catch {
+        // Already gone.
+    }
+}
+/**
+ * Creates `file` with `text` only if it does not exist. `hooks.beforeLink`
+ * (tests only) runs after the temporary file is complete.
+ */
+function createExclusive(file, text, hooks = {}) {
+    const temporary = writeTemporarySibling(file, text);
+    try {
+        if (hooks.beforeLink)
+            hooks.beforeLink();
+        try {
+            fs.linkSync(temporary, file);
+        }
+        catch (err) {
+            if (codeOf(err) === 'EEXIST') {
+                throw new ArtifactError(`${file} already exists (it may have been created by another program); it was left unchanged.`);
+            }
+            throw new ArtifactError(`cannot create ${file}: ${messageOf(err)}`);
+        }
+    }
+    finally {
+        discard(temporary);
+    }
+    syncDirectory(path.dirname(file));
+}
+/** The ownership marker for an artifact: `.<name>.sarif-to-comment-lock` in its directory. */
+function ownershipMarkerFor(file) {
+    return path.join(path.dirname(file), `.${path.basename(file)}.sarif-to-comment-lock`);
+}
+/**
+ * Takes exclusive cooperating-writer ownership of `file` (which need not
+ * exist). Returns a release function. Throws ArtifactError if another owner
+ * holds it.
+ */
+function acquireOwnership(file) {
+    const marker = ownershipMarkerFor(file);
+    const token = `${String(process.pid)} ${new Date().toISOString()} ${crypto.randomUUID()}\n`;
+    try {
+        fs.writeFileSync(marker, token, { flag: 'wx' });
+    }
+    catch (err) {
+        if (codeOf(err) === 'EEXIST') {
+            throw new ArtifactError(`${file} is being written by another sarif-to-comment command (ownership marker ${marker}). ` +
+                `Wait for it to finish. If no such command is running, the marker is stale: delete ${marker} and run again.`);
+        }
+        throw new ArtifactError(`cannot take ownership of ${file} (marker ${marker}): ${messageOf(err)}`);
+    }
+    return function release() {
+        // Remove only our own marker: never delete one another process created.
+        try {
+            if (fs.readFileSync(marker, 'utf8') === token)
+                fs.unlinkSync(marker);
+        }
+        catch {
+            // Already removed.
+        }
+    };
+}
+/**
+ * Atomically replaces `file` with `text`, provided its content still equals
+ * `expectedBytes` immediately before the rename. `hooks.beforeReplace` (tests
+ * only) runs after the temporary file is complete.
+ */
+function replaceIfUnchanged(file, expectedBytes, text, hooks = {}) {
+    const { mode } = fs.statSync(file);
+    const temporary = writeTemporarySibling(file, text, mode & 0o7777);
+    try {
+        if (hooks.beforeReplace)
+            hooks.beforeReplace();
+        let current;
+        try {
+            current = fs.readFileSync(file);
+        }
+        catch (err) {
+            throw new ArtifactError(`${file} could not be re-read before replacement (${messageOf(err)}); it was not changed.`);
+        }
+        if (!current.equals(expectedBytes)) {
+            throw new ArtifactError(`${file} changed while this command was running; it was not overwritten. Run the command again.`);
+        }
+        fs.renameSync(temporary, file);
+    }
+    finally {
+        discard(temporary);
+    }
+    syncDirectory(path.dirname(file));
+}
+/** A stat time as the archive stamp, `YYYY-MM-DDTHH-mm-ss.SSSZ` (colons are not portable in names). */
+function archiveStamp(milliseconds) {
+    return new Date(milliseconds).toISOString().replace(/:/g, '-');
+}
+/**
+ * Moves an existing `file` aside under its archive name. Returns
+ * { path, from, timeSource: 'birth' | 'modified' }, or null if `file` does not
+ * exist. `options.stat` (tests only) replaces fs.statSync.
+ */
+function archiveExisting(file, { stat = fs.statSync } = {}) {
+    let info;
+    try {
+        info = stat(file);
+    }
+    catch (err) {
+        if (codeOf(err) === 'ENOENT')
+            return null;
+        throw new ArtifactError(`cannot examine existing output ${file}: ${messageOf(err)}`);
+    }
+    const birth = Number.isFinite(info.birthtimeMs) && info.birthtimeMs > 0;
+    const stamp = archiveStamp(birth ? info.birthtimeMs : info.mtimeMs);
+    const dir = path.dirname(file);
+    const name = path.basename(file);
+    for (let n = 1;; n += 1) {
+        const archive = path.join(dir, `${stamp}${n === 1 ? '' : `-${String(n)}`}.old.${name}`);
+        try {
+            fs.linkSync(file, archive);
+        }
+        catch (err) {
+            if (codeOf(err) === 'EEXIST')
+                continue;
+            throw new ArtifactError(`cannot archive existing output ${file} as ${archive}: ${messageOf(err)}`);
+        }
+        fs.unlinkSync(file);
+        syncDirectory(dir);
+        return { path: archive, from: file, timeSource: birth ? 'birth' : 'modified' };
+    }
+}
+/** True when two existing paths name the same file (including symbolic and hard links). */
+function sameExistingFile(a, b) {
+    let sa;
+    let sb;
+    try {
+        sa = fs.statSync(a);
+        sb = fs.statSync(b);
+    }
+    catch {
+        return false;
+    }
+    return sa.dev === sb.dev && sa.ino === sb.ino;
+}