sarif-to-comment 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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

package/README.md

@@ -228,13 +228,28 @@ If that comparison can't establish the old side, you may pass `oldSourceCommit`
 
 ```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
 
@@ -242,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
 
@@ -270,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;
+}