cuke-dedup 0.1.1 → 0.2.0

package/docs/safety-and-limitations.md

@@ -0,0 +1,97 @@
+# Safety and limitations
+
+CukeDedup analyzes repositories that may contain malformed or adversarial input. It does not
+execute project configuration, imported modules, package scripts, matchers, or test code. Explicit
+resource limits keep failures visible and bound the work performed.
+
+## Compatibility
+
+- The minimum supported Rust version is 1.90.
+- The npm launcher is tested on Node.js 20 and 24.
+- Source adapters cover JavaScript and TypeScript, including JSX and common module variants.
+- Unsupported source languages are rejected rather than guessed.
+- Classic Gherkin and Gherkin Markdown are supported, including declared Gherkin dialects.
+- Before version 1.0, configuration and machine-report schemas may evolve between minor releases.
+
+## Static-analysis boundaries
+
+- Dynamic framework configuration may require explicit `features` or `definitions` patterns.
+- Named handlers declared in the same file resolve to their bodies. Imported or unresolved handler
+  references remain usable for matcher and usage rules but are not compared by name.
+- Malformed JavaScript and TypeScript fail closed. Unsupported regular-expression constructs warn;
+  malformed matcher escapes are operational errors.
+- One analysis root is one corpus. Analyze independent monorepo packages separately.
+- Regular expressions are matched against feature steps but are never reversed into invented
+  overlap witnesses.
+- Bounded fuzzy indexes preserve a deterministic sample in highly repetitive vocabularies but do
+  not promise every possible pair after a work limit is reached.
+
+When analysis is incomplete, existing findings remain valid but the absence of a finding proves
+nothing. Machine reports expose the incomplete or truncated status. Pass `--fail-on-incomplete`
+when CI must reject degraded analysis.
+
+## Input limits
+
+| Input | Limit |
+| --- | ---: |
+| Definition source, feature file, imported registration module, or baseline | 8 MiB each |
+| Package, CukeDedup, framework, or static project configuration | 1 MiB each |
+| Project-resolution metadata files | 1,024 files / 16 MiB total |
+| Project-resolution mappings | 16,384 |
+| Workspace discovery entries | 100,000 |
+| Imported registration modules | 1,024 modules / 64 MiB total |
+| Memoized module path/depth states | 16,384 |
+
+Resolution confines imports and package targets to canonical analysis or package roots and shares
+cached work between importing files.
+
+## Matcher and Gherkin limits
+
+- A matcher pattern or compiled program is limited to 1 MiB.
+- Each matcher receives a 2 MiB lazy-DFA cache.
+- Oversized matcher sets split recursively into bounded sets rather than falling back to a full
+  definition-by-step loop.
+- Gherkin Markdown conversion collects at most 10,000 ambiguous candidates, performs at most 128
+  parser probes, and parses at most 64 MiB of synthesized input.
+- Default-English bullets use exact Gherkin keyword filtering and one whole-document probe.
+- Dialect-dependent candidates use a whole-document retry only within the cumulative byte budget;
+  larger inputs use bounded 32-item restoration batches.
+
+## Analysis limits
+
+| Work | Limit |
+| --- | ---: |
+| Unique definition comparisons and static overlap pairs | 2,000,000 |
+| Structural proposals per handler class | 250,000 |
+| Raw overlap witness proposals | Four times the remaining unique-pair budget |
+| Retained overlap findings | 10,000 |
+| Trigram keys per definition / per run | 4,096 / 250,000 |
+| Matcher-blocking posting proposals | 2,000,000 |
+| Combined handler events | 10,000,000 |
+| Pairwise or overlap suppression work | 100,000,000 units each |
+| Unmatched-suppression advisory work | 10,000,000 units |
+| One matcher-edit or handler-LCS matrix | 100,000,000 estimated units |
+| Aggregate verification and evidence work | 1,000,000,000 units |
+
+Project configuration and CLI flags may lower candidate and structural limits but cannot raise the
+hard ceilings. Matcher similarity is evaluated before reserving expensive handler-LCS work.
+
+Fuzzy matcher discovery uses collision-free, fixed-width, case-folded character trigrams with
+digit runs normalized. Unsaturated posting lists are fully considered. Lists above 256 definitions
+use deterministic lexical neighbors instead of quadratic expansion. Candidates must be capable of
+reaching the 50% handler-behavior gate and—unless structurally equivalent—share a canonical call
+action.
+
+Reaching a candidate-generation or verification limit preserves evaluated findings, warns, and
+sets `analysis.truncated: true` with a nonzero skipped count. Exit status follows finding severity
+unless `--fail-on-incomplete` is enabled. Baselines are never updated from incomplete analysis.
+
+## Report safety
+
+Reports bound source snippets and cluster memberships, escape HTML, encode script-closing JSON
+characters, and remove bidirectional, invisible-format, and Unicode Tag characters. JSONL content
+still originates in the analyzed repository and must be treated as untrusted data rather than
+agent instructions.
+
+See [Reports](reports.md) for presentation limits and [Discovery and frameworks](discovery-and-frameworks.md)
+for corpus-completeness rules.

package/npm/lib/launcher.mjs

@@ -1,16 +1,13 @@
-import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { accessSync, constants, existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { constants as osConstants } from "node:os";
+import { TARGETS, targetFor as validatedTargetFor } from "./targets.mjs";
 
 const require = createRequire(import.meta.url);
 
-const targetManifest = JSON.parse(
-  readFileSync(new URL("../prebuilt-targets.json", import.meta.url), "utf8"),
-);
-
-export const TARGETS = Object.freeze(targetManifest.targets);
+export { TARGETS };
 
 export function detectLibc(report = process.report) {
   try {
@@ -25,14 +22,7 @@ export function targetFor(
   arch = process.arch,
   libc = platform === "linux" ? detectLibc() : undefined,
 ) {
-  const key = platform === "linux" ? `${platform}-${arch}-${libc}` : `${platform}-${arch}`;
-  const target = TARGETS[key];
-  if (!target) {
-    throw new Error(
-      `unsupported platform ${key}; supported platforms: ${Object.keys(TARGETS).join(", ")}`,
-    );
-  }
-  return target;
+  return validatedTargetFor(platform, arch, libc);
 }
 
 export function resolveBinary({

package/npm/lib/targets.mjs

@@ -0,0 +1,134 @@
+import { readFileSync } from "node:fs";
+
+const manifest = JSON.parse(
+  readFileSync(new URL("../prebuilt-targets.json", import.meta.url), "utf8"),
+);
+
+const EXPECTED_TARGETS = Object.freeze({
+  "darwin-arm64": Object.freeze({
+    rustTarget: "aarch64-apple-darwin",
+    packageName: "cuke-dedup-darwin-arm64",
+    packageDirectory: "darwin-arm64",
+    platform: "darwin",
+    arch: "arm64",
+    runner: "macos-15",
+    binaryName: "cuke-dedup",
+  }),
+  "darwin-x64": Object.freeze({
+    rustTarget: "x86_64-apple-darwin",
+    packageName: "cuke-dedup-darwin-x64",
+    packageDirectory: "darwin-x64",
+    platform: "darwin",
+    arch: "x64",
+    runner: "macos-15-intel",
+    binaryName: "cuke-dedup",
+  }),
+  "linux-arm64-gnu": Object.freeze({
+    rustTarget: "aarch64-unknown-linux-gnu",
+    packageName: "cuke-dedup-linux-arm64-gnu",
+    packageDirectory: "linux-arm64-gnu",
+    platform: "linux",
+    arch: "arm64",
+    libc: "gnu",
+    runner: "ubuntu-22.04-arm",
+    binaryName: "cuke-dedup",
+  }),
+  "linux-arm64-musl": Object.freeze({
+    rustTarget: "aarch64-unknown-linux-musl",
+    packageName: "cuke-dedup-linux-arm64-musl",
+    packageDirectory: "linux-arm64-musl",
+    platform: "linux",
+    arch: "arm64",
+    libc: "musl",
+    runner: "ubuntu-22.04-arm",
+    binaryName: "cuke-dedup",
+  }),
+  "linux-x64-gnu": Object.freeze({
+    rustTarget: "x86_64-unknown-linux-gnu",
+    packageName: "cuke-dedup-linux-x64-gnu",
+    packageDirectory: "linux-x64-gnu",
+    platform: "linux",
+    arch: "x64",
+    libc: "gnu",
+    runner: "ubuntu-22.04",
+    binaryName: "cuke-dedup",
+  }),
+  "linux-x64-musl": Object.freeze({
+    rustTarget: "x86_64-unknown-linux-musl",
+    packageName: "cuke-dedup-linux-x64-musl",
+    packageDirectory: "linux-x64-musl",
+    platform: "linux",
+    arch: "x64",
+    libc: "musl",
+    runner: "ubuntu-22.04",
+    binaryName: "cuke-dedup",
+  }),
+  "win32-arm64": Object.freeze({
+    rustTarget: "aarch64-pc-windows-msvc",
+    packageName: "cuke-dedup-windows-arm64-msvc",
+    packageDirectory: "win32-arm64",
+    platform: "win32",
+    arch: "arm64",
+    runner: "windows-11-arm",
+    binaryName: "cuke-dedup.exe",
+  }),
+  "win32-x64": Object.freeze({
+    rustTarget: "x86_64-pc-windows-msvc",
+    packageName: "cuke-dedup-windows-x64-msvc",
+    packageDirectory: "win32-x64",
+    platform: "win32",
+    arch: "x64",
+    runner: "windows-latest",
+    binaryName: "cuke-dedup.exe",
+  }),
+});
+
+export function validateTargets(targets) {
+  const actualKeys = Object.keys(targets ?? {}).sort();
+  const expectedKeys = Object.keys(EXPECTED_TARGETS).sort();
+  if (JSON.stringify(actualKeys) !== JSON.stringify(expectedKeys)) {
+    throw new Error("prebuilt target keys do not match the supported release targets");
+  }
+  for (const key of expectedKeys) {
+    validateTarget(key, targets[key]);
+  }
+  return targets;
+}
+
+export function validateTarget(key, target) {
+  const expected = EXPECTED_TARGETS[key];
+  if (!expected) {
+    throw new Error(`unsupported release target ${key}`);
+  }
+  const actualKeys = Object.keys(target ?? {}).sort();
+  const expectedKeys = Object.keys(expected).sort();
+  if (
+    JSON.stringify(actualKeys) !== JSON.stringify(expectedKeys)
+    || expectedKeys.some((field) => target[field] !== expected[field])
+  ) {
+    throw new Error(`invalid release target metadata for ${key}`);
+  }
+  return target;
+}
+
+export const TARGETS = Object.freeze(Object.fromEntries(
+  Object.entries(validateTargets(manifest.targets)).map(
+    ([key, target]) => [key, Object.freeze({ ...target })],
+  ),
+));
+
+export function targetFor(
+  platform,
+  arch,
+  libc,
+  targets = TARGETS,
+) {
+  const key = platform === "linux" ? `${platform}-${arch}-${libc}` : `${platform}-${arch}`;
+  const target = targets[key];
+  if (!target) {
+    throw new Error(
+      `unsupported platform ${key}; supported platforms: ${Object.keys(EXPECTED_TARGETS).join(", ")}`,
+    );
+  }
+  return validateTarget(key, target);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cuke-dedup",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Static analysis for duplicate and reusable Cucumber step definitions",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
     "npm/lib/",
     "npm/prebuilt-targets.json",
     "README.md",
+    "docs/",
     "LICENSE",
     "CHANGELOG.md",
     "SECURITY.md",
@@ -45,13 +46,13 @@
     "npm/platforms/*"
   ],
   "optionalDependencies": {
-    "cuke-dedup-darwin-arm64": "0.1.1",
-    "cuke-dedup-darwin-x64": "0.1.1",
-    "cuke-dedup-linux-arm64-gnu": "0.1.1",
-    "cuke-dedup-linux-arm64-musl": "0.1.1",
-    "cuke-dedup-linux-x64-gnu": "0.1.1",
-    "cuke-dedup-linux-x64-musl": "0.1.1",
-    "cuke-dedup-windows-arm64-msvc": "0.1.1",
-    "cuke-dedup-windows-x64-msvc": "0.1.1"
+    "cuke-dedup-darwin-arm64": "0.2.0",
+    "cuke-dedup-darwin-x64": "0.2.0",
+    "cuke-dedup-linux-arm64-gnu": "0.2.0",
+    "cuke-dedup-linux-arm64-musl": "0.2.0",
+    "cuke-dedup-linux-x64-gnu": "0.2.0",
+    "cuke-dedup-linux-x64-musl": "0.2.0",
+    "cuke-dedup-windows-arm64-msvc": "0.2.0",
+    "cuke-dedup-windows-x64-msvc": "0.2.0"
   }
 }