jscpd-rs 0.1.0

package/docs/junior-task-template.md

@@ -0,0 +1,62 @@
+# Junior Task Template
+
+Use this as the prompt body for `pi --no-session --tools read,edit,bash -p`.
+
+```text
+Junior helper task.
+Goal: <one concrete deliverable>
+Scope: edit only <exact file list>; read <exact reference files>.
+Allowed actions:
+- read <files>
+- edit <files>
+- run exactly `<verification command>` from <worktree path>
+Verification: <exact command and expected high-level result>
+Rules:
+- stay in scope
+- follow the nearest existing pattern
+- do not change production logic unless explicitly requested
+- do not edit generated files unless the task says so
+- do not touch external repositories
+- stop on blockers instead of guessing
+Output: Russian report with Result, Evidence, Verification, Blockers.
+```
+
+## Example: Add One Test
+
+```text
+Junior helper task.
+Goal: Add one unit test proving weak mode skips TOML hash comments in the generic tokenizer.
+Scope: edit only src/tokenizer.rs, preferably only the #[cfg(test)] module.
+Allowed actions:
+- read src/tokenizer.rs
+- edit src/tokenizer.rs
+- run exactly `cargo test tokenizer::tests::weak_mode_skips_generic_toml_comments` from /tmp/jscpd-rs-junior/toml-comments
+Verification: the exact cargo test above passes.
+Rules:
+- follow the existing weak_mode_skips_generic_comments test style
+- do not change production tokenizer logic
+- use format `toml`
+- assert exact token slices for the non-comment tokens
+- stop on blockers
+Output: Russian report with Result, Evidence, Verification, Blockers.
+```
+
+## Example: Add One Format Smoke Fixture
+
+```text
+Junior helper task.
+Goal: Add a tiny smoke fixture and test for format <format>.
+Scope: edit only <fixture files> and <one test file>.
+Allowed actions:
+- read docs/format-porting.md
+- read the nearest existing test
+- edit only the files listed in Scope
+- run exactly `scripts/check-format.sh <format> <target>` from /tmp/jscpd-rs-junior/<task>
+Verification: the exact check-format command passes.
+Rules:
+- keep fixtures minimal
+- do not claim upstream parity
+- do not edit src/formats.rs by hand
+- stop on blockers
+Output: Russian report with Result, Evidence, Verification, Blockers.
+```

package/docs/junior-workflow.md

@@ -0,0 +1,87 @@
+# Junior Workflow
+
+This project can use a local junior agent for bounded implementation tasks. The
+main agent remains responsible for scope, architecture, review, verification,
+commits, and pushes.
+
+## Rules
+
+- Run at most one junior agent process at a time.
+- Do not run junior work in the main checkout. Use a dedicated git worktree.
+- Give small implementation tasks with an example, exact files, and exact tests.
+- Do not delegate architecture, compatibility policy, broad reviews, or release
+  decisions.
+- Do not let a junior touch external repositories outside the dedicated
+  worktree.
+- Treat junior output as a patch proposal. Review every diff before merging.
+- Prefer `pi` for one-shot tasks because `--no-session` and `--tools` make the
+  allowed surface explicit. Use `opencode` only as fallback.
+
+## Worktree Loop
+
+Create a worktree:
+
+```bash
+scripts/junior-worktree.sh <task-slug>
+```
+
+Run the junior from the printed worktree path:
+
+```bash
+cd "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>"
+pi --no-session --tools read,edit,bash -p '<prompt from docs/junior-task-template.md>'
+```
+
+Review from the main checkout:
+
+```bash
+git -C "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>" status --short
+git -C "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>" diff
+```
+
+If the patch is useful, apply it deliberately from the main checkout using
+`git diff`, `git apply`, cherry-pick, or a manual patch. After review:
+
+```bash
+git worktree remove "${JUNIOR_WORKTREE_ROOT:-${TMPDIR:-/tmp}/jscpd-rs-junior}/<task-slug>"
+git branch -D junior/<branch-name>
+```
+
+## Good Junior Tasks
+
+- Add one unit test following an existing nearby test.
+- Add one small reporter or output-format test after the implementation exists.
+- Add support for one comment style in a generic/native tokenizer.
+- Add or update a small fixture for one format.
+- Port one small function from upstream when the target shape is already clear.
+- Run `scripts/check-format.sh <format> <target>` and report exact output.
+
+## Prompt Notes
+
+- Prefer implementation or test tasks over broad read-only scouting. A scout
+  prompt that is too procedural may produce a task plan instead of executing the
+  checks.
+- For read-only fact gathering, explicitly say: "Execute the checks now; do not
+  write instructions or a plan."
+- Keep fact-gathering prompts to exact files and exact commands. If there are
+  many commands, give a shell loop instead of asking the junior to design one.
+- Do not use junior output as evidence until the main agent verifies the exact
+  commands or diff.
+
+## Bad Junior Tasks
+
+- Review a whole commit or subsystem.
+- Decide whether compatibility is acceptable.
+- Refactor detector/tokenizer architecture.
+- Change generated format registry by hand.
+- Touch multiple unrelated files.
+- Run broad benchmarks or modify local third-party repositories.
+
+## Review Checklist
+
+- The diff only touches allowed files.
+- The implementation follows an existing local pattern.
+- Tests are exact enough to catch broken structure, not only `contains` checks.
+- Commands in the report match commands actually run.
+- `cargo fmt`, `cargo test`, and relevant scripts pass from the main checkout.
+- Any accepted patch is committed by the main agent, not by the junior.

package/docs/migrating-from-jscpd.md

@@ -0,0 +1,193 @@
+# 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.
+
+The migration goal for the first release is practical CLI/reporting
+compatibility for CI and local scans, not exact JavaScript package API parity.
+
+## Quick Command Mapping
+
+Cargo install:
+
+```bash
+cargo install jscpd-rs --locked
+jscpd --threshold 5 --exitCode 1 src
+```
+
+npm/npx after npm publication:
+
+```bash
+npx jscpd-rs --threshold 5 --exitCode 1 src
+```
+
+Common upstream command:
+
+```bash
+npx jscpd src --reporters console,json --threshold 5 --exitCode 1
+```
+
+Equivalent `jscpd-rs` command:
+
+```bash
+jscpd src --reporters console,json --threshold 5 --exitCode 1
+```
+
+When installed from npm, the package exposes `jscpd-rs`, `jscpd`, and
+`jscpd-server` bin names. The `jscpd` bin is an installed alias for the native
+CLI so existing scripts can be tested with minimal command changes in a
+controlled environment.
+
+## Config Files
+
+`jscpd-rs` reads the same common config locations:
+
+- `.jscpd.json`
+- `package.json#jscpd`
+
+Example:
+
+```json
+{
+  "path": ["src", "packages"],
+  "format": ["javascript", "typescript", "rust"],
+  "minLines": 5,
+  "minTokens": 50,
+  "threshold": 5,
+  "reporters": ["console", "json", "sarif"],
+  "output": "report",
+  "ignore": ["target/**", "node_modules/**", "dist/**"],
+  "gitignore": true,
+  "noTips": true
+}
+```
+
+CLI arguments are applied after config loading, so command-line values can
+override project defaults.
+
+## Commonly Compatible Workflows
+
+The first release targets these upstream-style workflows:
+
+- local duplicate scan with `jscpd .`;
+- threshold-based CI failure with `--threshold` and `--exitCode`;
+- format filtering with `--format`;
+- `.gitignore` and explicit `--ignore` handling;
+- report generation with built-in reporters;
+- Git blame reports with `--blame`;
+- server startup with `jscpd-server`;
+- snippet checks through the native REST/MCP server.
+
+Built-in native reporters:
+
+- `ai`
+- `badge`
+- `console`
+- `consoleFull`
+- `csv`
+- `html`
+- `json`
+- `markdown`
+- `sarif`
+- `silent`
+- `threshold`
+- `xcode`
+- `xml`
+
+Machine-readable reporters are treated as compatibility-sensitive: JSON, SARIF,
+XML, CSV, and Markdown should keep the shape expected by automation.
+
+## Compatibility Model
+
+The release gate is coverage-first. On the same inputs and options, `jscpd-rs`
+must not miss duplicated source lines reported by upstream `jscpd`.
+
+Exact clone pair identity, pair ordering, token totals, and some fragment
+boundaries may differ while duplicated upstream source lines remain covered.
+Extra Rust findings are allowed during convergence, but compatibility reports
+keep them visible as `extra` findings.
+
+This policy matters for multi-way clones: two implementations can pick
+different clone pairs while still covering the same duplicated source ranges.
+
+## Known First-Release Limits
+
+These are intentional first-release limits:
+
+- dynamic npm reporters, stores, listeners, and plugins are not loaded;
+- unknown external reporter/store names keep upstream-style warnings where
+  upstream continues;
+- HTML reports are self-contained and practically compatible, not
+  pixel-perfect;
+- long-tail formats use a synchronized format registry plus generic native
+  tokenization unless a fixture or public-repo gate proves a more specific
+  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.
+
+## Compare On Your Repository
+
+Run upstream and `jscpd-rs` with the same high-level options and compare the
+generated JSON reports:
+
+```bash
+node jscpd/apps/jscpd/bin/jscpd src \
+  --reporters json \
+  --output /tmp/jscpd-upstream \
+  --min-tokens 50 \
+  --min-lines 5 \
+  --exitCode 0
+
+jscpd src \
+  --reporters json \
+  --output /tmp/jscpd-rs \
+  --min-tokens 50 \
+  --min-lines 5 \
+  --exitCode 0
+```
+
+The repository scripts include the same coverage-first comparator used by the
+release gates:
+
+```bash
+FORMAT=typescript MIN_TOKENS=50 MIN_LINES=5 STRICT=coverage \
+  scripts/compat.sh /path/to/project
+```
+
+If `jscpd-rs` misses duplicated lines that upstream reports, that is a
+compatibility bug. If `jscpd-rs` reports additional findings, include them in
+the issue too; they help decide whether a tokenizer or boundary rule needs
+tightening.
+
+## CI Migration Pattern
+
+Existing upstream-style CI:
+
+```yaml
+- run: npx jscpd src --reporters console,json --threshold 5 --exitCode 1
+```
+
+Cargo-based `jscpd-rs` CI:
+
+```yaml
+- uses: dtolnay/rust-toolchain@stable
+- run: cargo install jscpd-rs --locked
+- run: jscpd src --reporters console,json --threshold 5 --exitCode 1
+```
+
+npm/npx-based `jscpd-rs` CI after npm publication:
+
+```yaml
+- uses: dtolnay/rust-toolchain@stable
+- uses: actions/setup-node@v5
+  with:
+    node-version: 22
+- 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.
+

package/docs/npm-release.md

@@ -0,0 +1,116 @@
+# Npm Release Preparation
+
+Current npm readiness snapshot:
+
+- Date: 2026-06-01.
+- Baseline commit: `e343350`; rerun `scripts/npm-package-check.sh` on the
+  exact checkout before npm publish.
+- GitHub Actions `release-gate`: passed on run `26743839098`.
+- Local checks passed: `cargo test`, `scripts/package-check.sh`,
+  `scripts/npm-package-check.sh`, local `npx --no-install` smoke for
+  `jscpd-rs`, `jscpd`, and `jscpd-server`.
+- Package name status: `npm view jscpd-rs version` returned `E404`.
+- 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:
+
+- `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.
+
+Local verification:
+
+```bash
+scripts/npm-package-check.sh
+```
+
+That script verifies:
+
+- `package.json` version matches `Cargo.toml`;
+- `npm pack` includes the expected Rust source and npm shim files;
+- `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;
+- `npx --package <local-tarball> jscpd-rs --version` works.
+
+Before actual publication, run:
+
+```bash
+git status --short
+npm whoami
+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.
+
+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
+Cargo/GitHub first-publication gate and intentionally checks that the crate name
+and release tag are still available.
+
+If the package name is still free and the npm account is logged in:
+
+```bash
+scripts/npm-package-check.sh
+npm publish --access public
+```
+
+If the account requires a one-time password for publish:
+
+```bash
+npm publish --access public --otp 123456
+```
+
+## Trusted Publishing
+
+Trusted Publishing is the preferred npm path for CI/CD publishing. npm trusts a
+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:
+
+```text
+.github/workflows/npm-publish.yml
+```
+
+Configure npm:
+
+1. Open the `jscpd-rs` package settings on npmjs.com.
+2. Go to **Trusted Publisher**.
+3. Select **GitHub Actions**.
+4. Use these values:
+   - Organization or user: `vv-bogdanov`
+   - Repository: `jscpd-rs`
+   - Workflow filename: `npm-publish.yml`
+   - Environment name: leave empty
+   - Allowed actions: `npm publish`
+
+Then publish from GitHub:
+
+1. Open GitHub Actions.
+2. Select the `npm-publish` workflow.
+3. Click **Run workflow** on `main`.
+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.

package/docs/public-benchmark-suite.md

@@ -0,0 +1,81 @@
+# Public Benchmark Suite
+
+The release benchmark suite uses popular public repositories cloned under
+`${XDG_CACHE_HOME:-$HOME/.cache}/jscpd-rs/public-bench/repos` by default. These
+clones are generated local state outside this git repo.
+
+Keep benchmark repositories outside this project tree unless you intentionally
+disable parent `.gitignore` effects. Upstream `jscpd` respects parent ignore
+files and can silently skip repo-internal benchmark directories that are
+gitignored.
+
+Upstream `jscpd` does not currently ship a public-repository performance suite.
+Its monorepo scripts expose `pnpm test`, CI runs build/lint/test plus
+`./apps/jscpd/bin/jscpd ./fixtures`, and the README benchmark note is based on
+the local `fixtures/` directory. This suite is therefore a project-owned release
+gate for product-scale speed checks.
+
+Configured cases:
+
+| Case | Repository | Branch | Format |
+| --- | --- | --- | --- |
+| `react` | `https://github.com/facebook/react.git` | `main` | `javascript` |
+| `next` | `https://github.com/vercel/next.js.git` | `canary` | `typescript` |
+| `vscode` | `https://github.com/microsoft/vscode.git` | `main` | `typescript` |
+| `prometheus` | `https://github.com/prometheus/prometheus.git` | `main` | `go` |
+| `rust` | `https://github.com/rust-lang/rust.git` | `main` | `rust` |
+
+Usage:
+
+```bash
+LIST=1 scripts/public-bench-suite.sh
+CASES=react,next RUNS=3 scripts/public-bench-suite.sh
+CHECK_COMPAT=1 CASES=react scripts/public-bench-suite.sh
+MIN_SPEEDUP=10 CASES=react,next RUNS=3 scripts/public-bench-suite.sh
+UPSTREAM_TIMEOUT=600s CASES=vscode RUNS=1 scripts/public-bench-suite.sh
+PUBLIC=1 PUBLIC_CASES=react,next PUBLIC_RUNS=3 scripts/release-gate.sh
+```
+
+Default behavior clones missing repositories with `--depth=1`, runs Rust and
+upstream `jscpd` through `scripts/bench.sh`, and writes raw benchmark output to
+`$BENCH_ROOT/results`. It also writes a TSV summary to
+`$BENCH_ROOT/results/summary.tsv` with case, commit, format, Rust average,
+upstream average, speedup, and compatibility status. Set `UPDATE=1` to refresh
+existing clones. Set `MIN_SPEEDUP` to make the suite fail when any selected
+case falls below the required upstream/Rust speedup. Each upstream timing run is
+bounded by `UPSTREAM_TIMEOUT` (`600s` by default) so optional stress cases cannot
+hang a release gate indefinitely; set `RUST_TIMEOUT` or `UPSTREAM_TIMEOUT` to an
+empty value to disable that side's timeout.
+
+When `CHECK_COMPAT=1` is enabled, the suite runs the same coverage-first report
+comparison used by the fixture gates. `react`, `next`, and `prometheus` include
+narrow allowlists for upstream overextended ranges documented in
+`docs/upstream-bugs.md`; those entries are printed as ignored line-coverage
+exceptions in the comparison output. New public benchmark misses should be fixed
+or documented before they are added to this allowlist.
+
+Recorded release-candidate measurements on May 31, 2026:
+
+```bash
+scripts/release-candidate.sh
+```
+
+| Case | Commit | Format | Rust avg | Upstream avg | Speedup | Compat |
+| --- | --- | --- | ---: | ---: | ---: | --- |
+| `react` | `f0dfee3` | `javascript` | 0.199097s | 10.079214s | 50.62x | pass |
+| `next` | `2bbb67b9` | `typescript` | 0.262433s | 14.715736s | 56.07x | pass |
+| `prometheus` | `a0524ee` | `go` | 0.085239s | 4.642435s | 54.46x | pass |
+
+`kubernetes` was also checked as a Go stress case, but upstream `jscpd` ran out
+of memory with the default Node heap, so it is intentionally not part of the
+default release suite.
+
+`vscode` is configured as an optional TypeScript stress case, but it is not part
+of the default release suite yet. On May 31, 2026, Rust completed the timing run
+in `1.464358s` at commit `e4074382`, while upstream was still running after
+more than nine minutes and the exploratory run was stopped before compatibility
+comparison. Keep it behind an explicit `CASES=vscode` run until we decide on a
+separate slow-suite policy.
+
+Before publication, rerun the suite on the selected cases and copy the measured
+averages into `docs/compat-baseline.md` or release notes with commit hashes.