jscpd-rs 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.2 - 2026-06-01
+
+### Changed
+
+- Rename the Windows prebuilt npm package to `jscpd-rs-win` to avoid npm
+  registry spam-policy false positives on the previous machine-generated name.
+- Move the Linux arm64 prebuilt build to the Ubuntu 22.04 ARM runner for a more
+  stable native ARM publication path and older glibc baseline.
+- Allow npm release workflow reruns for a single prebuilt target without
+  republishing the already-published main package.
+
+## 0.1.1 - 2026-06-01
+
+### Added
+
+- npm prebuilt binary distribution wiring for Linux x64 GNU, Linux arm64 GNU,
+  macOS x64, macOS arm64, and Windows x64 MSVC platform packages.
+- Runtime npm shim resolution that prefers installed prebuilt optional
+  packages and falls back to the existing Cargo source-build path.
+- npm package checks for platform package metadata, source-build fallback, and
+  local prebuilt-package smoke tests.
+- GitHub Release npm publishing workflow that builds platform packages before
+  publishing the main `jscpd-rs` package.
+
 ## 0.1.0 - 2026-05-31
 
 First release candidate for `jscpd-rs`, a native Rust clone of upstream
@@ -62,8 +86,8 @@ Recorded release-candidate public benchmark measurements from
 - HTML output is self-contained and practically compatible, not pixel-perfect.
 - The Rust crate exposes a native Rust API, not the upstream JavaScript package
   API.
-- The npm package currently builds native binaries from source during install;
-  prebuilt platform packages are planned as a later publication improvement.
+- The `jscpd-rs@0.1.0` npm package builds native binaries from source during
+  install.
 - Full Prism grammar parity for every long-tail format is not attempted in this
   release. Formats should be promoted from generic tokenization when concrete
   coverage gates show missed upstream lines.

package/Cargo.lock

@@ -483,7 +483,7 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "jscpd-rs"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "anyhow",
  "axum",

package/Cargo.toml

@@ -1,14 +1,14 @@
 [package]
 name = "jscpd-rs"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2024"
 rust-version = "1.93"
 license = "MIT"
-description = "Fast Rust clone of jscpd"
+description = "50x+ faster duplicate-code detector for CI/CD; jscpd-compatible CLI, SARIF, JSON, HTML reports"
 readme = "README.md"
 repository = "https://github.com/vv-bogdanov/jscpd-rs"
 documentation = "https://docs.rs/jscpd-rs"
-keywords = ["jscpd", "copy-paste", "duplication", "clone-detection", "cli"]
+keywords = ["jscpd", "duplicate-code", "clone-detection", "sarif", "ci"]
 categories = ["command-line-utilities", "development-tools"]
 include = [
     "/CHANGELOG.md",

package/README.md

@@ -7,22 +7,24 @@
 [![license](https://img.shields.io/github/license/vv-bogdanov/jscpd-rs.svg?style=flat-square)](LICENSE)
 [![rust](https://img.shields.io/badge/rust-1.93%2B-dea584?style=flat-square)](https://www.rust-lang.org/)
 
-Fast native Rust clone of [`jscpd`](https://github.com/kucherenko/jscpd)
-for copy-paste and duplicate-code detection in local development and CI/CD.
-It scans a codebase, finds duplicated source fragments across files, writes
-reports for humans and automation, and can fail a build when duplication
-crosses a configured threshold.
-
-`jscpd-rs` keeps the upstream command shape, configuration formats, reports,
-exit-code workflows, and server workflow, while moving the hot path to native
-Rust. The practical goal is simple: keep duplication checks always-on without
-spending unnecessary CI minutes, developer waiting time, cloud compute budget,
-or electricity on repeated quality gates.
-
-Recorded public release-candidate benchmarks are currently 50x+ faster than
-upstream on the covered repositories. The compatibility gate is coverage-first:
-on the same inputs and options, `jscpd-rs` must not miss duplicated source lines
-reported by upstream `jscpd`.
+50x+ faster duplicate-code detector for local development, CI/CD, and code
+quality gates.
+`jscpd-rs` scans a codebase, finds copy-paste fragments across files, writes
+console, JSON, SARIF, HTML, XML, CSV, Markdown, badge, and Xcode reports, and
+can fail a build when duplication crosses a configured threshold.
+
+It is a native Rust implementation of the common
+[`jscpd`](https://github.com/kucherenko/jscpd) command-line workflow:
+upstream-style CLI flags, `.jscpd.json` and `package.json#jscpd`
+configuration, report formats, exit-code behavior, Git blame, and server
+snippet checks. The practical goal is simple: keep copy-paste detection
+always-on without spending unnecessary CI minutes, developer waiting time,
+cloud compute budget, or electricity on repeated quality gates.
+
+Recorded public benchmark baselines show 50x+ speedups over upstream on the
+covered repositories. The compatibility gate is coverage-first: on the same
+inputs and options, `jscpd-rs` must not miss duplicated source lines reported
+by upstream `jscpd`.
 
 ## Install
 
@@ -43,10 +45,11 @@ npx jscpd-rs --version
 npx jscpd-rs .
 ```
 
-The first npm package is a source-build package: install/postinstall compiles
-the native Rust binaries with Cargo. A Rust toolchain must be available on the
-installing machine. Prebuilt platform packages are a planned publication
-improvement.
+Current npm packaging note: `jscpd-rs` installs prebuilt Linux, macOS, and
+Windows binaries where available, then falls back to building from source with
+Cargo for unsupported platforms. The original `0.1.0` npm package was
+source-build only; use `0.1.2+` for the full prebuilt-first path. See
+[docs/prebuilt-binaries.md](docs/prebuilt-binaries.md).
 
 From this repository:
 
@@ -114,7 +117,7 @@ If you already use upstream `jscpd`, see
 
 ## GitHub Actions
 
-Install from crates.io after publication:
+Install from crates.io:
 
 ```yaml
 jobs:
@@ -169,6 +172,10 @@ npx skills add vv-bogdanov/jscpd-rs --skill dry-refactoring
 
 - **Fast CI/CD gates:** duplicate detection should be cheap enough to run on
   every pull request.
+- **Low-friction rollout:** npm installs use prebuilt binaries on supported
+  Linux, macOS, and Windows targets, with a Cargo fallback for other platforms.
+- **Actionable reports:** console, JSON, SARIF, HTML, XML, CSV, Markdown,
+  badge, Xcode, threshold, and AI-oriented reports are implemented natively.
 - **Lower operating cost:** shorter scans reduce paid compute minutes and
   repeated developer wait time.
 - **Native detector path:** the detector does not embed or spawn JavaScript for
@@ -181,8 +188,8 @@ npx skills add vv-bogdanov/jscpd-rs --skill dry-refactoring
 
 ## What Works Today
 
-This is pre-release software. The first release target is a coverage-first
-compatible CLI replacement for common `jscpd` workflows:
+The current release is a coverage-first compatible CLI replacement for common
+`jscpd` duplicate-code and copy-paste detection workflows:
 
 - `jscpd` and `jscpd-server` binaries with upstream-compatible command names;
 - CLI and config option surface covered by compatibility scripts;
@@ -217,7 +224,7 @@ compare their reports.
 
 ## Performance
 
-Latest recorded public benchmark baseline:
+Latest recorded public benchmark baseline for duplicate-code detection:
 
 | Repo | Format | Rust avg | Upstream avg | Speedup |
 | --- | --- | ---: | ---: | ---: |
@@ -231,8 +238,8 @@ Reproduce the public benchmark and coverage suite:
 PUBLIC=1 PUBLIC_RUNS=3 scripts/release-gate.sh
 ```
 
-The release-candidate workflow reruns the public suite before publication so
-README numbers stay tied to a concrete commit and gate output.
+Release-candidate workflows rerun the public suite before each new publication
+so README numbers stay tied to a concrete commit and gate output.
 
 ## Library API
 

package/docs/migrating-from-jscpd.md

@@ -1,8 +1,10 @@
 # Migrating From jscpd
 
-`jscpd-rs` is a native Rust implementation of the common upstream `jscpd`
-workflow. It scans source trees, reports duplicated fragments, and can fail CI
-when duplication crosses a configured threshold.
+`jscpd-rs` is a 50x+ faster duplicate-code detector and native Rust
+implementation of the common upstream `jscpd` workflow. It scans source trees,
+reports copy-paste fragments across files, writes console, JSON, SARIF, HTML,
+XML, CSV, Markdown, badge, and Xcode reports, and can fail CI when duplication
+crosses a configured threshold.
 
 The migration goal for the first release is practical CLI/reporting
 compatibility for CI and local scans, not exact JavaScript package API parity.
@@ -16,7 +18,7 @@ cargo install jscpd-rs --locked
 jscpd --threshold 5 --exitCode 1 src
 ```
 
-npm/npx after npm publication:
+npm/npx:
 
 ```bash
 npx jscpd-rs --threshold 5 --exitCode 1 src
@@ -125,8 +127,10 @@ These are intentional first-release limits:
   tokenizer is needed;
 - the Rust crate exposes a native Rust API, not the upstream JavaScript package
   API;
-- first npm packaging is source-build: a Rust/Cargo toolchain is required during
-  install until prebuilt platform packages are added.
+- `jscpd-rs@0.1.2+` npm packaging uses prebuilt binaries on supported Linux,
+  macOS, and Windows targets, with a Cargo source-build fallback for
+  unsupported platforms. The original `0.1.0` npm package was source-build
+  only.
 
 ## Compare On Your Repository
 
@@ -178,7 +182,7 @@ Cargo-based `jscpd-rs` CI:
 - run: jscpd src --reporters console,json --threshold 5 --exitCode 1
 ```
 
-npm/npx-based `jscpd-rs` CI after npm publication:
+npm/npx-based `jscpd-rs` CI:
 
 ```yaml
 - uses: dtolnay/rust-toolchain@stable
@@ -188,6 +192,7 @@ npm/npx-based `jscpd-rs` CI after npm publication:
 - run: npx jscpd-rs src --reporters console,json --threshold 5 --exitCode 1
 ```
 
-The npm source-build package still needs Rust available during installation.
-Prebuilt npm platform packages are planned as a publication improvement.
-
+`jscpd-rs@0.1.2+` npm installs use prebuilt binaries where available and fall
+back to Cargo source-build on unsupported platforms. The original `0.1.0` npm
+package still needs Rust available during installation; see the
+[prebuilt binary distribution plan](prebuilt-binaries.md).

package/docs/npm-release.md

@@ -13,18 +13,17 @@ Current npm readiness snapshot:
 - Packed artifact audit: `jscpd-rs-0.1.0.tgz`, 96 files, about 169 KiB packed,
   about 708 KiB unpacked.
 
-The first npm package is `jscpd-rs`. It exposes these bin commands:
+The npm package is `jscpd-rs`. It exposes these bin commands:
 
 - `jscpd-rs`: primary `npx jscpd-rs` entrypoint, runs the native `jscpd` CLI.
 - `jscpd`: installed alias for the native `jscpd` CLI.
 - `jscpd-server`: installed alias for the native server binary.
 
-The package is intentionally source-build for the first release candidate:
-`postinstall` runs `cargo build --release --locked --bin jscpd --bin
-jscpd-server` inside the installed npm package. This keeps the npm path simple
-and verifiable before publication. Users installing from npm need Node, npm, and
-a Rust/Cargo toolchain. Prebuilt platform packages can be added later without
-changing the CLI behavior.
+`jscpd-rs@0.1.2+` publishes prebuilt platform packages before the main
+`jscpd-rs` package. The CLI behavior stays the same, and the source-build path
+remains the fallback for unsupported platforms. The original `0.1.0` package
+was source-build only; see the
+[prebuilt binary distribution plan](prebuilt-binaries.md).
 
 Local verification:
 
@@ -36,14 +35,20 @@ That script verifies:
 
 - `package.json` version matches `Cargo.toml`;
 - `npm pack` includes the expected Rust source and npm shim files;
+- `optionalDependencies` match `npm/prebuilt-targets.json` and the current
+  package version;
 - `npm pack` includes the advertised `skills/` files used by the terminal tip;
 - forbidden paths such as `jscpd/`, `target/`, `report/`, `scripts/`, and
   `node_modules/` are not packed;
 - `npm publish --dry-run --json` succeeds without publishing;
-- installing the packed tarball without Cargo fails with the expected Rust
-  toolchain hint;
-- a local npm install exposes working `jscpd-rs`, `jscpd`, and `jscpd-server`
-  bin commands;
+  if the current version is already published, this dry-run is skipped with an
+  explicit message;
+- installing the packed tarball without Cargo and without optional prebuilt
+  packages fails with the expected Rust toolchain hint;
+- source-build fallback exposes working `jscpd-rs`, `jscpd`, and
+  `jscpd-server` bin commands;
+- a locally generated platform package exposes the same bin commands without
+  Cargo;
 - `npx --package <local-tarball> jscpd-rs --version` works.
 
 Before actual publication, run:
@@ -55,9 +60,10 @@ scripts/npm-package-check.sh
 npm view jscpd-rs version
 ```
 
-`npm view` should return `E404` for the first publication, or the package must
-already be owned by this project. Do not run `npm publish` until explicit
-release approval.
+For a new version, `npm view jscpd-rs@X.Y.Z version` should fail before the
+release and return that version after publication. Do not run `npm publish`
+manually unless the GitHub Release workflow fails and explicit fallback
+approval is given.
 
 Do not use `scripts/prepublish-check.sh` as the npm-only gate after the Cargo
 crate and GitHub tag have already been published: that script is the full
@@ -84,15 +90,25 @@ specific GitHub Actions workflow through OIDC, so the workflow can publish
 without a long-lived npm token. For public packages published from public
 repositories, npm also generates provenance attestations automatically.
 
-This repository provides a manual publish workflow:
+This repository provides a publish workflow:
 
 ```text
 .github/workflows/npm-publish.yml
 ```
 
-Configure npm:
+The workflow runs automatically when a non-draft, non-prerelease GitHub Release
+is published. It checks out the release tag, verifies that the tag matches the
+`package.json` version, verifies that the main npm version is not already
+published, builds platform packages in a native runner matrix, publishes those
+platform packages first, runs `scripts/npm-package-check.sh`, and then
+publishes the main `jscpd-rs` package.
 
-1. Open the `jscpd-rs` package settings on npmjs.com.
+It can also be run manually from GitHub Actions as a fallback by entering
+`jscpd-rs` in the confirmation input.
+
+Configure npm for every package listed in `docs/prebuilt-binaries.md`:
+
+1. Open the package settings on npmjs.com.
 2. Go to **Trusted Publisher**.
 3. Select **GitHub Actions**.
 4. Use these values:
@@ -102,7 +118,16 @@ Configure npm:
    - Environment name: leave empty
    - Allowed actions: `npm publish`
 
-Then publish from GitHub:
+Then publish automatically from GitHub:
+
+1. Update `Cargo.toml` and `package.json` to the same version.
+2. Update `package.json#optionalDependencies` to the same version for every
+   platform package.
+3. Run the release gates.
+4. Create and publish a GitHub Release with tag `vX.Y.Z`.
+5. GitHub Actions will run `npm-publish` from that release tag.
+
+Manual fallback:
 
 1. Open GitHub Actions.
 2. Select the `npm-publish` workflow.
@@ -110,7 +135,12 @@ Then publish from GitHub:
 4. Enter `jscpd-rs` for `package_name`.
 5. Run the workflow.
 
-If npm does not allow Trusted Publishing configuration before the first package
-version exists, publish the first version with either interactive 2FA or a
-short-lived granular token with bypass 2FA enabled, then immediately configure
-Trusted Publishing for future releases.
+If npm does not allow Trusted Publishing configuration before a platform package
+version exists, add a short-lived `NPM_TOKEN` GitHub secret for the first
+platform-package bootstrap, then immediately configure Trusted Publishing and
+revoke the token.
+
+After Trusted Publishing is verified, revoke temporary npm tokens and consider
+setting the npm package publishing access to disallow traditional tokens. The
+full GitHub Release publishing flow, including crates.io publishing, is tracked
+in `docs/release-checklist.md`.

package/docs/prebuilt-binaries.md

@@ -0,0 +1,89 @@
+# Prebuilt Binary Distribution
+
+`jscpd-rs` is a native Rust CLI. Starting with `jscpd-rs@0.1.2`, npm
+distribution uses a small main package plus platform-specific optional
+packages. The original `0.1.0` npm package was source-build only.
+
+The main `jscpd-rs` package keeps the public bin names: `jscpd-rs`, `jscpd`,
+and `jscpd-server`.
+
+## Runtime Behavior
+
+- The JS shim first looks for a matching prebuilt optional package.
+- If a prebuilt package is installed, the shim runs its native binary directly.
+- If no prebuilt package exists for the platform, the existing source-build
+  path remains the fallback.
+- `JSCPD_RS_FORCE_BUILD=1` forces the fallback build path.
+- `JSCPD_RS_SKIP_POSTINSTALL=1` skips install-time builds for package tests and
+  advanced users who provide binaries another way.
+
+Avoid default postinstall downloads from GitHub Releases. Optional platform
+packages are more reproducible, work better with npm mirrors and lockfiles, and
+avoid surprising network access during install.
+
+## Platform Packages
+
+The target matrix is defined in `npm/prebuilt-targets.json`.
+
+| Package | Rust target | Runner |
+| --- | --- | --- |
+| `jscpd-rs-linux-x64-gnu` | `x86_64-unknown-linux-gnu` | `ubuntu-24.04` |
+| `jscpd-rs-linux-arm64-gnu` | `aarch64-unknown-linux-gnu` | `ubuntu-22.04-arm` |
+| `jscpd-rs-darwin-x64` | `x86_64-apple-darwin` | `macos-15-intel` |
+| `jscpd-rs-darwin-arm64` | `aarch64-apple-darwin` | `macos-15` |
+| `jscpd-rs-win` | `x86_64-pc-windows-msvc` | `windows-2025` |
+
+Consider Linux musl and Windows arm64 only after install data or user reports
+show demand.
+
+## Package Checks
+
+`scripts/npm-package-check.sh` verifies:
+
+- the root npm version matches `Cargo.toml`;
+- `optionalDependencies` exactly match `npm/prebuilt-targets.json`;
+- every optional platform dependency uses the same version as the main package;
+- the main npm package contains the runtime shim and target metadata;
+- no Cargo/no prebuilt install fails with the expected Rust toolchain hint;
+- source-build fallback works with optional dependencies omitted;
+- a locally generated platform package works without Cargo;
+- `npx --package <local-tarball> jscpd-rs --version` works.
+
+## Release Workflow
+
+The GitHub Release workflow in `.github/workflows/npm-publish.yml` publishes in
+this order:
+
+1. Verify that the GitHub Release tag matches `package.json`.
+2. Build platform packages in a native runner matrix.
+3. Smoke-test `jscpd --version` and `jscpd-server --version` for each package.
+4. Publish the platform packages.
+5. Run `scripts/npm-package-check.sh`.
+6. Publish the main `jscpd-rs` package.
+
+The workflow publishes with npm provenance enabled. It is designed for Trusted
+Publishing, but `NPM_TOKEN` can be kept as a temporary bootstrap fallback for
+new platform packages if npm does not allow Trusted Publisher setup before the
+first version exists.
+
+## npm Setup
+
+Configure Trusted Publishing for each npm package with:
+
+- Organization or user: `vv-bogdanov`
+- Repository: `jscpd-rs`
+- Workflow filename: `npm-publish.yml`
+- Environment name: leave empty
+- Allowed actions: `npm publish`
+
+Packages:
+
+- `jscpd-rs`
+- `jscpd-rs-linux-x64-gnu`
+- `jscpd-rs-linux-arm64-gnu`
+- `jscpd-rs-darwin-x64`
+- `jscpd-rs-darwin-arm64`
+- `jscpd-rs-win`
+
+If a temporary npm token is used for the first platform-package bootstrap,
+revoke it after Trusted Publishing succeeds.

package/docs/release-checklist.md

@@ -178,12 +178,58 @@ two explicit commands above are a manual smoke equivalent for post-tag checks.
 Track these after the first release candidate:
 
 - Reduce noisy extra Rust findings where they are user-visible false positives.
+- Verify the first npm prebuilt platform-package publication before broad npm
+  promotion so Node users can install without Cargo; see the
+  [prebuilt binary distribution plan](prebuilt-binaries.md).
 - Add native persistent store/cache only if release-scale benchmark data needs
   it.
 - Tighten MCP Streamable HTTP SDK edge cases if real MCP clients require them.
 - Promote long-tail tokenizers only from concrete missed-coverage evidence.
 - File upstream bug reports from `docs/upstream-issue-drafts.md`.
 
+## Automated GitHub Release Publishing
+
+After the first manual Cargo/npm bootstrap, future releases should use GitHub
+Release publication as the single publish trigger.
+
+Configured workflows:
+
+- `.github/workflows/crates-publish.yml`
+- `.github/workflows/npm-publish.yml`
+
+Both workflows run on `release.published` for non-draft, non-prerelease GitHub
+Releases. Both check out the release tag and verify that `vX.Y.Z` matches the
+package version before publishing. `crates-publish` publishes the Rust crate to
+crates.io; docs.rs builds documentation automatically after crates.io accepts
+the crate. `npm-publish` builds and publishes prebuilt npm platform packages
+before publishing the main npm package.
+
+Release flow for future versions:
+
+1. Update `Cargo.toml` and `package.json` to the same version.
+2. Update `package.json#optionalDependencies` to the same version for every
+   platform package.
+3. Update `CHANGELOG.md`, README benchmark numbers, and release docs.
+4. Run the release gates, including `scripts/package-check.sh`.
+5. Commit and push `main`.
+6. Create and publish a GitHub Release with tag `vX.Y.Z`.
+7. Confirm `crates-publish` completed successfully.
+8. Confirm `npm-publish` built and published all platform packages before the
+   main `jscpd-rs` package.
+9. Check crates.io, docs.rs, and npm package pages.
+
+Trusted Publishing setup:
+
+- crates.io: configure a trusted publisher for repository
+  `vv-bogdanov/jscpd-rs` and workflow `crates-publish.yml`.
+- npm: configure a trusted publisher for repository `vv-bogdanov/jscpd-rs` and
+  workflow `npm-publish.yml` on `jscpd-rs` and every platform package listed in
+  `docs/prebuilt-binaries.md`.
+
+Use no GitHub environment name unless the workflow is updated to declare one.
+After Trusted Publishing works, revoke temporary npm/crates tokens and keep
+token-based publishing as an emergency fallback only.
+
 ## CI Speed Plan
 
 Keep this as part of the release plan:

package/docs/release-readiness.md

@@ -1,6 +1,6 @@
 # Release Readiness
 
-Last updated: 2026-05-31.
+Last updated: 2026-06-01.
 
 This is the working component checklist for the first release. The authoritative
 policy decisions are still in `docs/release-decisions.md`; this file tracks the
@@ -36,7 +36,7 @@ current implementation status.
 | Terminal cosmetics | practical parity | Important messages are gated; exact wrapping/order remains lower priority. |
 | Upstream JavaScript API parity | follow-up | Native Rust helpers cover the practical app/tokenizer/detector/statistics/store concepts, including an embeddable argv runner and tokenizer map generation; exact JS package export shape is not implemented in the Rust crate. See `docs/api-parity.md`. |
 | Server snippet matching | optimized baseline | Native `/api/check` and MCP `check_duplication` are functional and reuse project token maps from the last scan; add a dedicated window index only if real server benchmarks require it. |
-| Npm prebuilt binaries | follow-up | The first npm package is source-build: install/postinstall compiles with Cargo. Add platform-specific prebuilt packages before broad npm promotion if install speed or Rust toolchain requirements become a blocker. |
+| Npm prebuilt binaries | ready for 0.1.2 | Platform-specific optional package metadata, runtime prebuilt resolution, prebuilt/fallback package checks, and GitHub Release publishing automation are wired for `jscpd-rs@0.1.2+`. See the [prebuilt binary distribution plan](prebuilt-binaries.md). |
 | Latest full publication gate | ready | `scripts/prepublish-check.sh` passed locally on code commit `8c3da0e`, including `scripts/release-candidate.sh`, package/install verification, crate/tag availability checks, npm package/name/npx verification, and `cargo publish --dry-run --locked`. GitHub Actions default `release-gate` passed on code commit `8c3da0e` in run `26710762680`. After benchmark documentation updates, `RUN_RELEASE_CANDIDATE=0 scripts/prepublish-check.sh` is the package/dry-run refresh gate for the exact package contents being tagged. |
 
 ## Post-MVP

package/docs/user-guide.md

@@ -1,15 +1,22 @@
 # jscpd-rs User Guide
 
-`jscpd-rs` is a native Rust implementation of the common `jscpd` workflows:
-scan source trees, detect copy-paste fragments, write reports, fail CI on
-thresholds, and serve snippet checks over HTTP/MCP.
+`jscpd-rs` is a 50x+ faster duplicate-code detector for local development,
+CI/CD, and code quality gates. It scans source trees, detects copy-paste
+fragments across files, writes console, JSON, SARIF, HTML, XML, CSV, Markdown,
+badge, and Xcode reports, fails CI on duplication thresholds, and serves
+snippet checks over HTTP/MCP.
+
+It implements the common upstream `jscpd` CLI workflow with native Rust
+performance: upstream-style flags, `.jscpd.json` and `package.json#jscpd`
+configuration, Git blame, report generation, exit-code behavior, and a native
+server.
 
 This guide is intentionally user-facing. Release policy, benchmark evidence,
 and compatibility details live in the release docs linked from the README.
 
 ## Installation
 
-Install the Rust binaries from crates.io after publication:
+Install the Rust binaries from crates.io:
 
 ```bash
 cargo install jscpd-rs --locked
@@ -22,9 +29,10 @@ npm install -g jscpd-rs
 npx jscpd-rs --version
 ```
 
-The first npm package builds the native binaries from source during
-`postinstall`, so a Rust toolchain must be available. Prebuilt npm platform
-packages are planned after the first release.
+`jscpd-rs@0.1.2+` installs prebuilt Linux, macOS, and Windows binaries where
+available and falls back to building from source with Cargo for unsupported
+platforms. The original `0.1.0` npm package was source-build only. See the
+[prebuilt binary distribution plan](prebuilt-binaries.md).
 
 Install from a checkout:
 

package/npm/lib/platform.js

@@ -0,0 +1,92 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const targets = require("../prebuilt-targets.json");
+
+function packageRoot() {
+  return path.resolve(__dirname, "..", "..");
+}
+
+function exeName(name, platform = process.platform) {
+  return platform === "win32" ? `${name}.exe` : name;
+}
+
+function sourceBinaryPath(name) {
+  const targetDir =
+    process.env.CARGO_TARGET_DIR || path.join(packageRoot(), "target");
+  return path.join(targetDir, "release", exeName(name));
+}
+
+function detectLinuxLibc() {
+  if (process.platform !== "linux") {
+    return undefined;
+  }
+
+  const report =
+    process.report && typeof process.report.getReport === "function"
+      ? process.report.getReport()
+      : undefined;
+  if (report && report.header && report.header.glibcVersionRuntime) {
+    return "glibc";
+  }
+  return "musl";
+}
+
+function currentTargetKey() {
+  const libc = detectLinuxLibc();
+  for (const [key, target] of Object.entries(targets)) {
+    if (target.os !== process.platform || target.cpu !== process.arch) {
+      continue;
+    }
+    if (target.os === "linux" && target.libc !== libc) {
+      continue;
+    }
+    return key;
+  }
+  return undefined;
+}
+
+function currentTarget() {
+  const key = currentTargetKey();
+  return key ? { key, ...targets[key] } : undefined;
+}
+
+function resolvePrebuiltBinary(name) {
+  if (process.env.JSCPD_RS_FORCE_BUILD === "1") {
+    return undefined;
+  }
+
+  const target = currentTarget();
+  if (!target) {
+    return undefined;
+  }
+
+  let packageJson;
+  try {
+    packageJson = require.resolve(`${target.packageName}/package.json`, {
+      paths: [packageRoot()],
+    });
+  } catch {
+    return undefined;
+  }
+
+  const binary = path.join(path.dirname(packageJson), "bin", exeName(name, target.os));
+  return fs.existsSync(binary) ? binary : undefined;
+}
+
+function resolveBinary(name) {
+  return resolvePrebuiltBinary(name) || sourceBinaryPath(name);
+}
+
+module.exports = {
+  currentTarget,
+  currentTargetKey,
+  exeName,
+  packageRoot,
+  resolveBinary,
+  resolvePrebuiltBinary,
+  sourceBinaryPath,
+  targets,
+};

package/npm/lib/run-binary.js

@@ -3,20 +3,19 @@
 const fs = require("node:fs");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
-
-function packageRoot() {
-  return path.resolve(__dirname, "..", "..");
-}
-
-function binaryPath(name) {
-  const exe = process.platform === "win32" ? `${name}.exe` : name;
-  const targetDir =
-    process.env.CARGO_TARGET_DIR || path.join(packageRoot(), "target");
-  return path.join(targetDir, "release", exe);
-}
+const {
+  packageRoot,
+  resolvePrebuiltBinary,
+  sourceBinaryPath,
+} = require("./platform");
 
 function buildIfMissing(name) {
-  const binary = binaryPath(name);
+  const prebuilt = resolvePrebuiltBinary(name);
+  if (prebuilt) {
+    return prebuilt;
+  }
+
+  const binary = sourceBinaryPath(name);
   if (fs.existsSync(binary)) {
     return binary;
   }

package/npm/prebuilt-targets.json

@@ -0,0 +1,44 @@
+{
+  "linux-x64-gnu": {
+    "packageName": "jscpd-rs-linux-x64-gnu",
+    "description": "Prebuilt Linux x64 GNU binaries for jscpd-rs",
+    "os": "linux",
+    "cpu": "x64",
+    "libc": "glibc",
+    "rustTarget": "x86_64-unknown-linux-gnu",
+    "runner": "ubuntu-24.04"
+  },
+  "linux-arm64-gnu": {
+    "packageName": "jscpd-rs-linux-arm64-gnu",
+    "description": "Prebuilt Linux arm64 GNU binaries for jscpd-rs",
+    "os": "linux",
+    "cpu": "arm64",
+    "libc": "glibc",
+    "rustTarget": "aarch64-unknown-linux-gnu",
+    "runner": "ubuntu-22.04-arm"
+  },
+  "darwin-x64": {
+    "packageName": "jscpd-rs-darwin-x64",
+    "description": "Prebuilt macOS x64 binaries for jscpd-rs",
+    "os": "darwin",
+    "cpu": "x64",
+    "rustTarget": "x86_64-apple-darwin",
+    "runner": "macos-15-intel"
+  },
+  "darwin-arm64": {
+    "packageName": "jscpd-rs-darwin-arm64",
+    "description": "Prebuilt macOS arm64 binaries for jscpd-rs",
+    "os": "darwin",
+    "cpu": "arm64",
+    "rustTarget": "aarch64-apple-darwin",
+    "runner": "macos-15"
+  },
+  "win32-x64-msvc": {
+    "packageName": "jscpd-rs-win",
+    "description": "Prebuilt Windows x64 binaries for jscpd-rs",
+    "os": "win32",
+    "cpu": "x64",
+    "rustTarget": "x86_64-pc-windows-msvc",
+    "runner": "windows-2025"
+  }
+}

package/npm/scripts/postinstall.js

@@ -1,24 +1,29 @@
 "use strict";
 
 const fs = require("node:fs");
-const path = require("node:path");
 const { spawnSync } = require("node:child_process");
+const {
+  packageRoot,
+  resolvePrebuiltBinary,
+  sourceBinaryPath,
+} = require("../lib/platform");
 
-const root = path.resolve(__dirname, "..", "..");
+const root = packageRoot();
 const cargo = process.env.CARGO || "cargo";
-const targetDir = process.env.CARGO_TARGET_DIR || path.join(root, "target");
-const releaseDir = path.join(targetDir, "release");
-const exeSuffix = process.platform === "win32" ? ".exe" : "";
-const binaries = ["jscpd", "jscpd-server"].map((name) =>
-  path.join(releaseDir, `${name}${exeSuffix}`),
-);
+const binaryNames = ["jscpd", "jscpd-server"];
+const prebuiltBinaries = binaryNames.map(resolvePrebuiltBinary);
+const sourceBinaries = binaryNames.map(sourceBinaryPath);
 
 if (process.env.JSCPD_RS_SKIP_POSTINSTALL === "1") {
   console.log("jscpd-rs: skipping native build because JSCPD_RS_SKIP_POSTINSTALL=1");
   process.exit(0);
 }
 
-if (binaries.every((binary) => fs.existsSync(binary))) {
+if (prebuiltBinaries.every(Boolean)) {
+  process.exit(0);
+}
+
+if (sourceBinaries.every((binary) => fs.existsSync(binary))) {
   process.exit(0);
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jscpd-rs",
-  "version": "0.1.0",
-  "description": "Fast native Rust clone of jscpd for duplicate-code detection",
+  "version": "0.1.2",
+  "description": "50x+ faster duplicate-code detector for CI/CD; jscpd-compatible CLI, SARIF, JSON, HTML reports",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,22 @@
     "duplication",
     "duplicate-code",
     "code-duplication",
+    "copy-paste-detection",
     "clone-detection",
+    "code-quality",
     "ci",
+    "cicd",
     "sarif",
+    "code-scanning",
     "cli"
   ],
+  "optionalDependencies": {
+    "jscpd-rs-darwin-arm64": "0.1.2",
+    "jscpd-rs-darwin-x64": "0.1.2",
+    "jscpd-rs-linux-arm64-gnu": "0.1.2",
+    "jscpd-rs-linux-x64-gnu": "0.1.2",
+    "jscpd-rs-win": "0.1.2"
+  },
   "bin": {
     "jscpd-rs": "npm/bin/jscpd-rs.js",
     "jscpd": "npm/bin/jscpd-rs.js",

package/src/lib.rs

@@ -1,9 +1,21 @@
-#![doc(html_root_url = "https://docs.rs/jscpd-rs/0.1.0")]
+#![doc(html_root_url = "https://docs.rs/jscpd-rs/0.1.2")]
 
-//! Native Rust API for `jscpd-rs`, a high-performance Rust clone of
-//! [`jscpd`](https://github.com/kucherenko/jscpd).
+//! Native Rust API for `jscpd-rs`, a 50x+ faster duplicate-code detector for
+//! local development and CI/CD.
 //!
-//! The crate exposes the same detector core used by the `jscpd` and
+//! `jscpd-rs` scans a codebase, finds copy-paste fragments across files, writes
+//! console, JSON, SARIF, HTML, XML, CSV, Markdown, badge, and Xcode reports,
+//! and can fail a build when duplication crosses a configured threshold.
+//!
+//! It is a native Rust implementation of the common
+//! [`jscpd`](https://github.com/kucherenko/jscpd) command-line workflow:
+//! upstream-style CLI flags, `.jscpd.json` and `package.json#jscpd`
+//! configuration, report formats, exit-code behavior, Git blame, and server
+//! snippet checks. The current public benchmark suite records 50x+ speedups on
+//! pinned React, Next.js, and Prometheus cases while using a coverage-first
+//! compatibility gate against upstream `jscpd`.
+//!
+//! This crate exposes the same detector core used by the `jscpd` and
 //! `jscpd-server` binaries: option parsing, file discovery, tokenization,
 //! duplicate detection, statistics, and in-memory source checks.
 //!