svelte-shaker-engine-scan-native 0.1.0

package/README.md

@@ -0,0 +1,156 @@
+# svelte-shaker-engine-scan-native
+
+Optional **native (napi) prop scanner** for svelte-shaker — the fast path behind
+ESLint's [`svelte/no-useless-props`](https://github.com/sveltejs/eslint-plugin-svelte).
+
+It parses every component with **rsvelte natively, in parallel (rayon)** and walks
+rsvelte's **typed AST directly** — the full-AST `serde_json::Value` (the ~12 MB
+template skeleton) is never built — so the whole-program scan no longer parses in
+JS, ships a serialized AST across the JS boundary, or materializes the AST as JSON
+at all.
+
+```
+buildAnalyzeInputSync (JS crawl: resolve edges, read files)
+        │  { files: [{id, code}], edges }   (JSON string)
+        ▼
+   scan()  ── rayon ─▶ rsvelte parse ─▶ typed-AST walk (no Value)
+        │
+        ▼  { fileId: [{name, start, end}] }  (JSON string, UTF-16 offsets)
+```
+
+### Two layers, both exhaustive
+
+never-passed needs far less than a full model: `find_never_passed_props` only tests
+`had_spread || explicit.contains(name)`, so a call site is just `{ had_spread,
+explicit: set<name> }` — no literal values, value sets, defaults, `local`, or
+shadow/debug names. So `scan` (`typed_scan.rs`) walks:
+
+- The **template** over the typed `TemplateNode` enum. An exhaustive `match` makes a
+  forgotten node kind a COMPILE error — a node can never be silently skipped (which
+  could drop a call site or an escape and cause a false positive).
+- **JS expressions** (the small instance `<script>` + each embedded template
+  expression) via rsvelte's `as_json()`, walked generically — `serde_json` visits
+  every child, so escape detection (the one analysis whose incompleteness would
+  cause a false positive) is provably exhaustive. rsvelte exposes no typed JS-AST
+  walker, and rsvelte_lint itself reads the JS AST as JSON; a hand-rolled per-variant
+  JS walker would risk exactly the missed-variant false positives this rule forbids.
+
+`scan_via_value` keeps the Value-engine path (serialize each AST and run
+`svelte_shaker_engine::find_never_passed_props`) as the differential **oracle** for
+`scan` and as a drop-in fallback.
+
+## Soundness
+
+The output is **pinned byte-for-byte to the JS engine**, two ways:
+
+- `tests/native-never-passed.test.ts` pins `scan` (typed) against the TS
+  `findNeverPassedProps` — name **and** span, including non-ASCII source (UTF-16
+  remap), rename, namespace/barrel edges, spread, and body/snippet cases.
+- The corpus benchmark pins `scan` (typed) === `scan_via_value` (oracle) === the JS
+  engine on the full flygate corpus (650 components): same 18 files, same 53 reports,
+  zero diffs. The oracle path reuses `svelte_shaker_engine::find_never_passed_props`,
+  which is itself pinned to the TS engine by the `wasm-never-passed` test.
+
+A parse error on any file yields no model for it (it is silently skipped), so a
+broken file can only ever make the scan **under-report**, never produce a false
+positive.
+
+## Build
+
+Local dev / tests build straight off cargo — the loader (`index.cjs`) finds the
+`target/{release,debug}` cdylib automatically:
+
+```sh
+cargo build --release        # from this directory
+```
+
+Distribution prebuilds use [`@napi-rs/cli`](https://napi.rs):
+
+```sh
+pnpm build                   # napi build --platform --release --no-js
+```
+
+### rsvelte dependency
+
+This crate depends on `rsvelte_core`, pinned in `Cargo.toml` to the exact **git
+rev** the scanner is validated against. rsvelte is public, so `cargo` fetches it
+with no credentials. (The CI workflow sets `CARGO_NET_GIT_FETCH_WITH_CLI=true` only
+to skip rsvelte's private ecosystem-test submodules, which `rsvelte_core`'s build
+doesn't use.)
+
+For local dev against a side-by-side `rsvelte` checkout, override without editing
+`Cargo.toml` via an uncommitted `.cargo/config.toml`:
+
+```toml
+[patch."https://github.com/baseballyama/rsvelte"]
+rsvelte_core = { path = "../../../../rsvelte/crates/rsvelte_core" }
+```
+
+## Publishing
+
+The package bundles every platform's `.node` and is published by the
+`prebuild-native-scanner.yml` workflow (build matrix → one `npm publish`). rsvelte is
+public and publishing is **tokenless via npm Trusted Publishers (OIDC)** — no repo
+secret at all, exactly like the main `svelte-shaker` release.
+
+**One-time bootstrap** (Trusted Publishers can only be configured on a package that
+already exists): publish `0.1.0` once manually from a local checkout, then register
+the repo + workflow as a Trusted Publisher.
+
+```sh
+# from packages/svelte-shaker/engine-scan-native, logged in to npm:
+pnpm install --ignore-workspace
+pnpm exec napi build --platform --release --no-js --output-dir .   # builds this host's .node
+npm publish --access public                                        # publishes 0.1.0
+# then: npmjs.com/package/svelte-shaker-engine-scan-native/access -> add Trusted Publisher
+#   (repo baseballyama/svelte-shaker, workflow prebuild-native-scanner.yml)
+```
+
+(The bootstrap publish only contains this host's binary; the next workflow run
+republishes a bumped version with all 5 platforms.) From then on, run the workflow
+(`workflow_dispatch` with `publish: true`, or push a
+`svelte-shaker-engine-scan-native@<version>` tag) and it publishes tokenlessly.
+
+Consumers get the speedup automatically once it is installed (e.g. as an optional
+dependency); the ESLint rule loads it when present and falls back to the JS/WASM
+engine otherwise.
+
+## Performance
+
+On the flygate corpus (650 components, Apple Silicon, release build), warm, full
+`scan` (input JSON in -> report JSON out):
+
+| path                        | median | min    |
+| --------------------------- | ------ | ------ |
+| **`scan` (typed, default)** | **~57 ms** | **~49 ms** |
+| `scan_via_value` (oracle)   | ~297 ms | ~277 ms |
+
+vs. the JS path (svelte/compiler parse + JS analyze) at ~680 ms. The typed path is
+~5× faster than the Value path and hits the ~50 ms target, with byte-identical
+results. (`scanProfile()` returns the typed-vs-Value split.)
+
+The escape-detection parent-context subtlety — a top-level `{X}` counts as a
+value-use only because its parent is an `ExpressionTag` — is handled in
+`expression_escapes`: each embedded expression is walked with its root treated as a
+value position (it always sits in one in the template), matching the engine's
+whole-tree walk. The corpus oracle confirms this is exact.
+
+## Resident daemon (`ScanDaemon`) — incremental re-scan
+
+For an editor / LSP, parsing dominates a scan (~37 ms of the ~41 ms), so the daemon
+caches each file's lightweight model (props, escapes, call sites — no AST) and
+re-parses only what changed:
+
+```js
+const d = new addon.ScanDaemon();
+d.init(JSON.stringify({ files, edges })); // full scan once at startup
+// on edit — pass only the changed files + the full current edges:
+d.update(JSON.stringify({ files: [changed], edges, removed: [deletedId] }));
+```
+
+A single-file edit re-scans in **~1.3 ms** (vs ~41 ms cold) on the 650-component
+corpus, and the result is **byte-identical to a cold `scan`** (`init === scan`,
+`update === scan(edited)` — pinned by `tests/native-daemon.test.ts`). It is sound to
+re-parse only the changed files because a file's edges (`from == id`) derive solely
+from its own imports, so an unchanged file's model can never go stale. Output keys
+are sorted by file id, so cold and incremental scans agree exactly.

package/index.cjs

@@ -0,0 +1,87 @@
+// Loader for the native prop-scanner addon.
+//
+// Resolves the N-API binary across three layouts, in order:
+//   1. A prebuilt, platform-named `.node` next to this file (the PUBLISHED
+//      layout produced by `@napi-rs/cli`, e.g. `*.darwin-arm64.node`).
+//   2. Any `*.node` next to this file (defensive: a differently-named prebuild).
+//   3. The in-repo `cargo build` output under `target/{release,debug}` — copied
+//      to a `.node` alongside this loader on demand — so tests and local dev work
+//      straight off a `cargo build` with no `napi build` / publish step.
+//
+// The single export is `{ scan }`, matching the `#[napi] fn scan` in `src/lib.rs`.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { platform, arch } = process;
+
+/** The bare cargo cdylib filename for this platform (renamed to `.node` for require). */
+const DYLIB = {
+  darwin: 'libsvelte_shaker_engine_scan_native.dylib',
+  linux: 'libsvelte_shaker_engine_scan_native.so',
+  win32: 'svelte_shaker_engine_scan_native.dll',
+}[platform];
+
+function tryRequire(p) {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return require(p);
+  } catch {
+    return null;
+  }
+}
+
+function loadAddon() {
+  // 1) Prebuilt platform-named `.node` (published layout).
+  const prebuilt = path.join(
+    __dirname,
+    `svelte-shaker-engine-scan-native.${platform}-${arch}.node`,
+  );
+  if (fs.existsSync(prebuilt)) {
+    const mod = tryRequire(prebuilt);
+    if (mod) return mod;
+  }
+
+  // 2) In-repo cargo output (dev/test): copy `target/<profile>/<dylib>` to a
+  //    `.node` and load. Checked BEFORE generic siblings so a fresh `cargo build`
+  //    always wins over a stale `local-*.node` copy from an earlier build.
+  if (DYLIB) {
+    for (const profile of ['release', 'debug']) {
+      const dylib = path.join(__dirname, 'target', profile, DYLIB);
+      if (!fs.existsSync(dylib)) continue;
+      const nodeCopy = path.join(__dirname, `local-${profile}.node`);
+      // Refresh the copy only when the build is newer, so a rebuild is picked up
+      // by the next fresh process without re-copying on every load.
+      try {
+        const srcMtime = fs.statSync(dylib).mtimeMs;
+        const dstMtime = fs.existsSync(nodeCopy) ? fs.statSync(nodeCopy).mtimeMs : -1;
+        if (srcMtime > dstMtime) fs.copyFileSync(dylib, nodeCopy);
+      } catch {
+        /* fall through to require attempt */
+      }
+      const mod = tryRequire(nodeCopy);
+      if (mod) return mod;
+    }
+  }
+
+  // 3) Any other `*.node` next to this file (defensive: a differently-named prebuild).
+  let siblings = [];
+  try {
+    siblings = fs.readdirSync(__dirname);
+  } catch {
+    /* no dir listing */
+  }
+  for (const file of siblings) {
+    if (file.endsWith('.node')) {
+      const mod = tryRequire(path.join(__dirname, file));
+      if (mod) return mod;
+    }
+  }
+
+  throw new Error(
+    `svelte-shaker-engine-scan-native: no native binary found for ${platform}-${arch} ` +
+      `(looked for a prebuilt .node and a target/{release,debug} build)`,
+  );
+}
+
+module.exports = loadAddon();

package/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Scan a whole resolved program for never-passed props (typed path — the default).
+ *
+ * `inputJson` is the JSON of `{ files: { id: string; code: string }[]; edges:
+ * ResolvedEdge[] }` — the output of svelte-shaker's `buildAnalyzeInputSync` crawl
+ * (resolution already done). Returns the JSON of `{ [fileId: string]: { name:
+ * string; start: number; end: number }[] }` with UTF-16 offsets, keys sorted by
+ * file id — the same shape as the WASM `find_never_passed_props_json` and the TS
+ * `findNeverPassedProps`.
+ *
+ * Synchronous; requires Node >= 22.12.
+ */
+export declare function scan(inputJson: string): string;
+
+/**
+ * The Value-engine oracle / fallback: serializes each AST to the rsvelte JSON shape
+ * and runs the validated `find_never_passed_props`. Output is identical to {@link
+ * scan}; kept as the differential reference and a drop-in fallback.
+ */
+export declare function scanViaValue(inputJson: string): string;
+
+/** Profiling helper: returns `{ typedMs, valueMs, files }` for the same input. */
+export declare function scanProfile(inputJson: string): string;
+
+/**
+ * In-memory scan state for incremental re-scans (editor / LSP). Construct once,
+ * `init` with the full program, then `update` per change set — `update` re-parses
+ * only the changed files and re-runs the cheap whole-program assembly over the
+ * cached models, so a single-file edit re-scans in ~1 ms instead of a full scan,
+ * byte-identical to a cold {@link scan}.
+ */
+export declare class ScanDaemon {
+  constructor();
+  /** Full scan: parse every file and cache its model. Same input as {@link scan}. */
+  init(inputJson: string): string;
+  /**
+   * Incremental re-scan. `inputJson` is `{ files: { id, code }[]; edges:
+   * ResolvedEdge[]; removed?: string[] }` — `files` are the changed/added files,
+   * `edges` the full current edge set, `removed` the deleted file ids.
+   */
+  update(inputJson: string): string;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "svelte-shaker-engine-scan-native",
+  "version": "0.1.0",
+  "description": "Native (napi) prop-scanner for svelte-shaker: parses with rsvelte and runs the validated never-passed-props engine in-process.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/baseballyama/svelte-shaker.git",
+    "directory": "packages/svelte-shaker/engine-scan-native"
+  },
+  "files": [
+    "index.cjs",
+    "index.d.ts",
+    "*.node"
+  ],
+  "main": "index.cjs",
+  "types": "index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "napi build --platform --release --no-js --output-dir .",
+    "build:debug": "napi build --platform --no-js --output-dir ."
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4"
+  },
+  "napi": {
+    "binaryName": "svelte-shaker-engine-scan-native",
+    "targets": [
+      "x86_64-apple-darwin",
+      "aarch64-apple-darwin",
+      "x86_64-unknown-linux-gnu",
+      "aarch64-unknown-linux-gnu",
+      "x86_64-pc-windows-msvc"
+    ]
+  },
+  "engines": {
+    "node": ">=22.12"
+  }
+}