@sackville-mcp/mutate 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Curtis Autery
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/index.d.mts

@@ -0,0 +1,347 @@
+//#region src/config.d.ts
+/**
+ * Diff-scoping config EMITTERS for the Python mutation tools (ADR 0010 addendum 2). These turn a
+ * selected-file scope into a per-run tool config, PINNED to the slice-0 captures of the installed
+ * cosmic-ray 8.4.6 / mutmut 3.5.0 (see `test/fixtures/README.md`) — never doc-derived guesses:
+ *
+ * - cosmic-ray scopes via a `module-path` FILE LIST (Fork A — verified 8.4.6 accepts a list); its
+ *   `excluded-modules` SUBTRACTS from the scope via exact path AND fnmatch glob, so an inherited
+ *   exclusion that matches a selected file is reconciled (stripped), never copied blind (blocker #3).
+ * - mutmut scopes via `paths_to_mutate` (Fork B was WRONG — 3.5.0 has NO `only_mutate`/`source_paths`;
+ *   `paths_to_mutate` + `do_not_mutate` are the real keys, Fork F). Scoping a subset breaks the
+ *   baseline unless the rest of the source tree is `also_copy`'d so unscoped tests still import; an
+ *   inherited `do_not_mutate` glob matching a selected file is stripped (blocker #3, mutmut form).
+ *
+ * Both emitters are PURE (TOML in → TOML out via `smol-toml`). They reduce SPURIOUS inconclusives by
+ * reconciling exclusions up front; the load-bearing under-scope guarantee is the POST-SPAWN
+ * {@link reconcileScope} guard in the runner, which folds any genuinely-unmutated selected file to
+ * inconclusive regardless of why (absence-is-never-a-pass).
+ */
+/** Thrown when a scoped config cannot be safely synthesized (empty scope, missing base table, etc.). */
+declare class ScopeEmitError extends Error {
+  constructor(message: string);
+}
+/**
+ * The operator's declared source tree, read from a cosmic-ray base config's `module-path` (a single
+ * string or a list). Used as the default `ownedRoots` to confine the diff scope (Fork C): a changed
+ * `.py` outside this tree is `unmatched` (report-gap), never silently scoped. Pure.
+ */
+declare function cosmicModulePathRoots(baseToml: string): string[];
+interface ScopedCosmicRayConfig {
+  /** The synthesized per-run `cosmic-ray.toml` text. */
+  toml: string;
+  /** The selected file list written to `module-path` (canonical form). */
+  modulePath: string[];
+  /** Inherited `excluded-modules` entries removed because they would subtract a selected file. */
+  strippedExclusions: string[];
+}
+/**
+ * Synthesize a per-run cosmic-ray config from a base config + the selected files. Overrides
+ * `module-path` to the canonical selected FILE LIST and reconciles `excluded-modules`: any entry
+ * (exact or fnmatch glob) that matches a selected file is stripped (it would otherwise silently
+ * subtract that file — blocker #3); non-colliding entries are preserved. All other keys/tables
+ * (`timeout`, `test-command`, `[cosmic-ray.distributor]`, …) are preserved verbatim. Pure.
+ */
+declare function synthesizeScopedCosmicRayConfig(baseToml: string, selectedFiles: string[]): ScopedCosmicRayConfig;
+/** The operator's `[tool.mutmut] paths_to_mutate` — the default `ownedRoots` for a scoped mutmut run. */
+declare function mutmutPathsToMutate(basePyproject: string): string[];
+/** The operator's inherited `[tool.mutmut] do_not_mutate` globs (reconciled against the scope). */
+declare function mutmutDoNotMutate(basePyproject: string): string[];
+interface MutmutScopePlan {
+  /** The selected files written to `paths_to_mutate` (canonical form). */
+  pathsToMutate: string[];
+  /** Sibling source files to `also_copy` so unscoped tests still import (source tree minus scope). */
+  alsoCopy: string[];
+  /** Inherited `do_not_mutate` globs preserved (those that do NOT collide with the scope). */
+  doNotMutate: string[];
+  /** Inherited `do_not_mutate` globs removed because they would exclude a selected file (blocker #3). */
+  strippedDoNotMutate: string[];
+}
+/**
+ * Plan a scoped mutmut run. `paths_to_mutate` = the selected files; `also_copy` = every other source
+ * file in `allSourceFiles` (so a test importing an unscoped sibling module still resolves in mutmut's
+ * `mutants/` sandbox — verified necessary in slice 0). An inherited `do_not_mutate` glob that matches
+ * a selected file is stripped (it would otherwise exclude a file we deliberately scoped). Pure given
+ * `allSourceFiles` (the runner derives it by walking the owned roots).
+ */
+declare function planMutmutScope(selectedFiles: string[], allSourceFiles: string[], inheritedDoNotMutate?: string[]): MutmutScopePlan;
+/**
+ * Render a `pyproject.toml` for a scoped mutmut run: merge the {@link MutmutScopePlan}'s
+ * `paths_to_mutate`/`also_copy` (+ reconciled `do_not_mutate`) into the base pyproject's
+ * `[tool.mutmut]` table (Fork F: only slice-0-verified keys), preserving every other section and any
+ * other verified `[tool.mutmut]` key the operator set (e.g. `pytest_add_cli_args`). An empty
+ * `do_not_mutate` is omitted entirely. Pure.
+ */
+declare function synthesizeScopedMutmutPyproject(basePyproject: string, plan: MutmutScopePlan): string;
+//#endregion
+//#region src/summarize.d.ts
+/**
+ * Pure mutation-report summarizer — the first slice of `@sackville-mcp/mutate`, and the one
+ * with no I/O and no Stryker dependency.
+ *
+ * Mutation testing asks "are the tests meaningful?" — it perturbs the source (a `+`
+ * becomes `-`, a `true` becomes `false`) and re-runs the suite; a mutant that survives is
+ * a behaviour the tests do not actually pin down. Under Sackville's TDD gate the agent
+ * wrote a passing test, but a passing test can still assert nothing useful — surviving
+ * mutants are the catch for that, the natural complement to coverage's forgotten-assertion
+ * catch (covered-but-unkilled vs added-but-uncovered).
+ *
+ * This module reads the **mutation-testing-elements report schema** (`schemaVersion`,
+ * `files[path].mutants[].status`) that Stryker emits as `mutation-report.json`. The schema
+ * is stable and decoupled from the Stryker version (ADR 0010 update 2026-06-01), so this
+ * core carries no `@stryker-mutator/*` import — it is unit-tested against a committed
+ * golden report. Producing a real report is a gated, injected `stryker run` (a later slice).
+ *
+ * Metric definitions mirror mutation-testing-elements exactly:
+ *   detected   = killed + timeout
+ *   undetected = survived + noCoverage
+ *   covered    = detected + survived            (NoCoverage excluded — it was never run)
+ *   valid      = detected + undetected
+ *   invalid    = compileErrors + runtimeErrors
+ *   total      = valid + invalid + ignored + pending
+ *   mutationScore                 = detected / valid   (null when valid === 0)
+ *   mutationScoreBasedOnCoveredCode = detected / covered (null when covered === 0)
+ */
+/** Mutant statuses from the mutation-testing-elements schema. */
+type MutantStatus = 'Killed' | 'Survived' | 'NoCoverage' | 'Timeout' | 'CompileError' | 'RuntimeError' | 'Ignored' | 'Pending';
+interface MutantPosition {
+  line: number;
+  column?: number;
+}
+interface Mutant {
+  id: string;
+  mutatorName: string;
+  status: MutantStatus;
+  replacement?: string;
+  location?: {
+    start: MutantPosition;
+    end?: MutantPosition;
+  };
+}
+interface MutationFile {
+  language?: string;
+  source?: string;
+  mutants: Mutant[];
+}
+interface MutationReport {
+  schemaVersion?: string;
+  thresholds?: {
+    high: number;
+    low: number;
+  };
+  files: Record<string, MutationFile>;
+}
+interface StatusCounts {
+  killed: number;
+  survived: number;
+  timeout: number;
+  noCoverage: number;
+  compileErrors: number;
+  runtimeErrors: number;
+  ignored: number;
+  pending: number;
+}
+interface MutationMetrics {
+  counts: StatusCounts;
+  detected: number;
+  undetected: number;
+  covered: number;
+  valid: number;
+  invalid: number;
+  totalMutants: number;
+  /** detected / valid (percent); null when there are no valid mutants. */
+  mutationScore: number | null;
+  /** detected / covered (percent); null when no covered mutants. */
+  mutationScoreBasedOnCoveredCode: number | null;
+}
+interface FileSummary {
+  path: string;
+  metrics: MutationMetrics;
+}
+/** A surviving (or never-covered) mutant — the actionable test gap. */
+interface Survivor {
+  file: string;
+  mutatorName: string;
+  status: 'Survived' | 'NoCoverage';
+  line: number;
+}
+interface MutationSummary {
+  metrics: MutationMetrics;
+  files: FileSummary[];
+  /** Survived + NoCoverage mutants, sorted by file then line — what to go fix. */
+  survivors: Survivor[];
+}
+/** Summarize a Stryker mutation report into aggregate + per-file metrics and the survivor list. Pure. */
+declare function summarizeMutation(report: MutationReport): MutationSummary;
+//#endregion
+//#region src/cosmic-ray.d.ts
+/** Parse `cosmic-ray dump <session.sqlite>` JSON-lines into a mutation-testing-elements report. Pure. */
+declare function parseCosmicRayDump(jsonl: string): MutationReport;
+//#endregion
+//#region src/mutmut.d.ts
+/** Parse `mutmut results --all true` text into a mutation-testing-elements report. Pure. */
+declare function parseMutmutResults(text: string): MutationReport;
+//#endregion
+//#region src/run.d.ts
+/** Thrown when the paired operator gate denies a run. */
+declare class MutateGateError extends Error {
+  constructor(message: string);
+}
+interface RunMutationConfig {
+  /** The project to run Stryker in. */
+  projectRoot: string;
+  /** OPERATOR allowlist of roots the runner may execute in. Load-bearing even with allowRun. */
+  allowedRoots: string[];
+  /** OPERATOR opt-in to actually run mutation testing. Deny-by-default. */
+  allowRun: boolean;
+  /** Wall-clock cap (ms) passed to the runner. */
+  timeoutMs?: number;
+}
+interface RunMutationInput {
+  /**
+   * Changed source files to scope mutation to. Stryker → `--mutate`; the Python tools → a synthesized
+   * scoped config (cosmic-ray `module-path` list / mutmut `paths_to_mutate`). `undefined` ⇒ the
+   * project default (whole project, today's behavior); a supplied list scopes the run, and a selection
+   * that resolves to no mutable in-tree `.py` is a pre-spawn noop (`ran:false`, never a spawn).
+   */
+  mutateFiles?: string[];
+  /** Reuse Stryker's incremental cache (`--incremental`) — faster re-runs. */
+  incremental?: boolean;
+  /** cosmic-ray config path (relative to projectRoot). Default `cosmic-ray.toml`. */
+  configPath?: string;
+  /**
+   * OPTIONAL operator source roots the diff scope is confined to (Fork C). A changed `.py` outside
+   * them is `unmatched` (report-gap), never scoped. Default: the tool config's declared source tree
+   * (cosmic-ray `module-path`).
+   */
+  ownedRoots?: string[];
+}
+/** Injected command runner — executes `stryker <argv>` and yields its exit status. */
+type MutationRunner = (argv: string[], opts: {
+  cwd: string;
+  timeoutMs?: number;
+}) => Promise<{
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}>;
+interface RunMutationResult {
+  ran: boolean;
+  exitCode: number;
+  /** Files mutation was scoped to (empty ⇒ the project's configured set). */
+  scopedFiles: string[];
+  /** Which mutation tool produced the summary. */
+  tool?: 'stryker' | 'mutmut' | 'cosmic-ray';
+  /**
+   * The on-disk JSON report path (Stryker). Optional: the Python tools (mutmut/cosmic-ray) emit
+   * their report to STDOUT, so there is no report file to surface.
+   */
+  reportPath?: string;
+  summary: MutationSummary;
+  /** A scope was requested but resolved to no mutable in-tree `.py` ⇒ pre-spawn noop (case (a)). */
+  scopeEmpty?: boolean;
+  /** Changed `.py` files outside the owned tree / deleted — surfaced as a gap (Fork C), never scoped. */
+  unmatched?: string[];
+  /** The files the run was SELECTED to mutate (before reconciliation) — what we asked the tool for. */
+  requestedFiles?: string[];
+}
+/** Default live runner: spawn the local `stryker` as a subprocess (used by the bin, not the gate). */
+declare const defaultStrykerRunner: MutationRunner;
+/** Default live runner: spawn the local `mutmut` as a subprocess (used by the bin, not the gate). */
+declare const defaultMutmutRunner: MutationRunner;
+/** Default live runner: spawn the local `cosmic-ray` as a subprocess (used by the bin, not the gate). */
+declare const defaultCosmicRayRunner: MutationRunner;
+/**
+ * Run mutation testing behind the operator gate and summarize the report. The actual
+ * `stryker` invocation is the injected `runner` (default {@link defaultStrykerRunner}); the
+ * JSON report is read from `deps.reportPath` (default: Stryker's
+ * `<projectRoot>/reports/mutation/mutation.json`).
+ */
+declare function runMutation(config: RunMutationConfig, input: RunMutationInput, deps?: {
+  runner?: MutationRunner;
+  reportPath?: string;
+}): Promise<RunMutationResult>;
+/**
+ * mutmut sibling of {@link runMutation} (ADR 0010 addendum, the lightweight Python option). Spawns
+ * `mutmut run` (mutate + test; a non-zero exit just means survivors exist, not an error) then reads
+ * `mutmut results --all true` from STDOUT and feeds the pure {@link parseMutmutResults}. No report
+ * file. (Diff-scoping is staged — mutmut 3.x scopes via its own config, not a clean CLI file list.)
+ */
+declare function runMutmut(config: RunMutationConfig, input: RunMutationInput, deps?: {
+  runner?: MutationRunner; /** Existence check for the selected files (FS by default; injected in tests). */
+  exists?: (path: string) => boolean; /** Enumerate the `.py` files under the owned roots (for `also_copy`); FS walk by default. */
+  listSourceFiles?: (ownedRoots: string[], projectRoot: string) => string[]; /** The fresh sandbox cwd to run in (the sticky `mutants/` cache can't leak). Default mkdtemp. */
+  sandboxDir?: string;
+}): Promise<RunMutationResult>;
+/**
+ * cosmic-ray sibling of {@link runMutation} (ADR 0010 addendum, the PRIMARY Python tool — its dump
+ * carries real file:line:operator, so survivors are actionable). Drives the three-step workflow
+ * against an operator-authored config (`input.configPath`, default `cosmic-ray.toml` — it carries
+ * the project's test-command + module scope) over a throwaway session DB: `init` → `exec` → `dump`,
+ * reading the `dump` JSON-lines from STDOUT and feeding the pure {@link parseCosmicRayDump}. The
+ * {@link assertComplete} guard makes an empty or partially-executed session inconclusive, never a
+ * clean pass. (Diff-scoping by synthesizing the per-run config from `mutateFiles` is staged.)
+ */
+declare function runCosmicRay(config: RunMutationConfig, input: RunMutationInput, deps?: {
+  runner?: MutationRunner;
+  sessionDir?: string; /** Existence check for the selected files (FS by default; injected in tests). */
+  exists?: (path: string) => boolean; /** Scoped config filename written into projectRoot (relative). Default `.sackville-cosmic.toml`. */
+  scopedConfigName?: string;
+}): Promise<RunMutationResult>;
+//#endregion
+//#region src/scope.d.ts
+interface MutationScope {
+  /** Mutable, existing, in-tree `.py` files to scope the run to (repo-relative, normalized, deduped, sorted). */
+  files: string[];
+  /** Changed `.py` files that are out-of-tree, deleted, or otherwise unplaceable — surfaced as a
+   * gap (report-gap), NEVER silently folded into `files` (that would be absence-as-a-pass). */
+  unmatched: string[];
+}
+/**
+ * Derive the mutation scope from the changed files. A changed file is selected only when it is a
+ * `.py` file, lives under one of the operator's `ownedRoots`, AND exists on disk (`exists`,
+ * injected — FS by default in the runner, faked in tests, mirroring `selectPytestScope`'s
+ * `testExists`). A `.py` file that is out-of-tree or non-existent (deleted/renamed/typo) is
+ * `unmatched`, never scoped. Non-`.py` files are irrelevant to mutation and dropped. Pure given
+ * `exists`. Whole-project fallback is NOT decided here — it is the caller's (`mutateFiles ===
+ * undefined`) or the cosmic-ray emitter's (`no-scope` on the base config) concern.
+ */
+declare function selectMutationScope(mutateFiles: string[], ownedRoots: string[], exists: (path: string) => boolean): MutationScope;
+interface ScopeReconciliation {
+  /** Selected files the tool ACTUALLY mutated (≥1 mutant) — report this as the run's true scope,
+   * never the merely-requested set. */
+  mutatedFiles: string[];
+  /** Selected files the tool NEVER SAW (absent from the per-file summary) — partial under-scope.
+   * A non-empty `missing` MUST make the run inconclusive (absence-as-a-pass otherwise). */
+  missing: string[];
+}
+/**
+ * Post-spawn partial-under-scope guard. Given the files the run was SELECTED to mutate and the
+ * tool's {@link MutationSummary} (whose `files[]` carries a per-file record for every file the
+ * tool SAW — even one it found no mutants in), determine which selected files were genuinely
+ * mutated and which the tool never saw at all. A selected file present in the summary with zero
+ * mutants is SEEN-BUT-EMPTY (benign — no mutable code); a selected file ABSENT from the summary
+ * was never mutated (the partial-scope sentinel) and goes in `missing`. Paths are normalized on
+ * both sides before comparison. Pure.
+ */
+declare function reconcileScope(selected: string[], summary: MutationSummary): ScopeReconciliation;
+/**
+ * Convert a Python source PATH to its dotted module form (`pkg/calc.py` → `pkg.calc`,
+ * `pkg/__init__.py` → `pkg`). The package-relative prefix is unknown here, so this is the FULL
+ * relative-path dotted form; {@link reconcileMutmutScope} matches it against mutmut's module names
+ * by suffix to tolerate src-layout projects.
+ */
+declare function pyPathToModule(path: string): string;
+/**
+ * The mutmut-specific post-spawn guard. Unlike cosmic-ray, mutmut's {@link MutationSummary} is keyed
+ * by DOTTED MODULE (`pkg.calc`), not path, AND it emits NO record for a scoped file that produced
+ * zero mutants (slice 0: seen-but-empty is INDISTINGUISHABLE from never-seen — Fork B2). So this is
+ * deliberately CONSERVATIVE: a selected file is "mutated" only if some module with ≥1 mutant matches
+ * its dotted form (equal, or a suffix either way — tolerating flat AND src layouts); every other
+ * selected file is `missing` (⇒ the runner throws inconclusive). Some false-inconclusives, ZERO
+ * false-passes (absence-is-never-a-pass). Pure.
+ */
+declare function reconcileMutmutScope(selectedPaths: string[], summary: MutationSummary): ScopeReconciliation;
+//#endregion
+export { type FileSummary, type Mutant, type MutantPosition, type MutantStatus, MutateGateError, type MutationFile, type MutationMetrics, type MutationReport, type MutationRunner, type MutationScope, type MutationSummary, type MutmutScopePlan, type RunMutationConfig, type RunMutationInput, type RunMutationResult, ScopeEmitError, type ScopeReconciliation, type ScopedCosmicRayConfig, type StatusCounts, type Survivor, cosmicModulePathRoots, defaultCosmicRayRunner, defaultMutmutRunner, defaultStrykerRunner, mutmutDoNotMutate, mutmutPathsToMutate, parseCosmicRayDump, parseMutmutResults, planMutmutScope, pyPathToModule, reconcileMutmutScope, reconcileScope, runCosmicRay, runMutation, runMutmut, selectMutationScope, summarizeMutation, synthesizeScopedCosmicRayConfig, synthesizeScopedMutmutPyproject };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/config.ts","../src/summarize.ts","../src/cosmic-ray.ts","../src/mutmut.ts","../src/run.ts","../src/scope.ts"],"mappings":"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"}