@vscode/diff 0.0.2-0

package/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

package/README.md

@@ -0,0 +1,64 @@
+# @vscode/diff
+
+> ⚠️ **Experimental** — this package is in early development. The API may change without notice and bugs are expected. Do not depend on it for production workloads yet.
+
+A high-performance diff library, ported from the diff algorithm used inside VS Code. Ships with two interchangeable backends:
+
+- **TypeScript** (default) — pure JS, no native dependencies.
+- **WebAssembly** — same algorithm compiled from Rust via `wasm-pack`. Typically ~1.5–3× faster on larger inputs.
+
+Both produce identical results.
+
+## Install
+
+```sh
+npm install @vscode/diff
+```
+
+## Usage
+
+```ts
+import { createDiffComputer } from '@vscode/diff';
+
+// TS backend (synchronous-feeling, no init required)
+const ts = await createDiffComputer();
+const result = ts.computeDiff(original, modified, {
+    ignoreTrimWhitespace: false,
+    computeMoves: false,
+});
+
+// WASM backend (loads the .wasm module on first call)
+const wasm = await createDiffComputer({ useWasm: true });
+const result2 = wasm.computeDiff(original, modified);
+```
+
+`computeDiff` returns a [`DiffResult`](./src/diff/api/types.ts) containing:
+
+- `edits` — an `AnnotatedStringEdit` describing the text-level changes (offset-based, suitable for applying directly).
+- `moves` — detected block moves (when `computeMoves: true`).
+- `hitTimeout` — `true` if computation exceeded `maxComputationTimeMs`.
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `maxComputationTimeMs` | `0` (no limit) | Cap the diff time; falls back to a coarser result on timeout. |
+| `ignoreTrimWhitespace` | `false` | Treat lines as equal when they differ only in leading/trailing whitespace. |
+| `computeMoves` | `false` | Detect moved blocks. |
+| `extendToSubwords` | `false` | Refine inner changes to subword boundaries. |
+
+## Performance
+
+Across all bundled test fixtures (46 cases, total median time in ms):
+
+| Backend | Total | vs TS | vs native Rust |
+|---|---:|---:|---:|
+| TS (V8) | 113.7 | 1.00× | 2.86× slower |
+| WASM | 72.5 | 0.64× | 1.82× slower |
+| Native Rust (reference) | 39.8 | 0.35× | 1.00× |
+
+Run `node scripts/bench.mjs` to reproduce.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SECURITY.md

@@ -0,0 +1,14 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V1.0.0 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which
+includes all source code repositories in our GitHub organizations.
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+For security reporting information, locations, contact information, and policies,
+please review the latest guidance for Microsoft repositories at
+[https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

package/dist/index.d.ts

@@ -0,0 +1,223 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+/**
+ * A range of offsets (0-based).
+ */
+declare class OffsetRange {
+    readonly start: number;
+    readonly endExclusive: number;
+    static ofLength(length: number): OffsetRange;
+    static ofStartAndLength(start: number, length: number): OffsetRange;
+    constructor(start: number, endExclusive: number);
+    get isEmpty(): boolean;
+    get length(): number;
+    delta(offset: number): OffsetRange;
+    deltaStart(offset: number): OffsetRange;
+    deltaEnd(offset: number): OffsetRange;
+    equals(other: OffsetRange): boolean;
+    containsRange(other: OffsetRange): boolean;
+    contains(offset: number): boolean;
+    join(other: OffsetRange): OffsetRange;
+    intersect(other: OffsetRange): OffsetRange | undefined;
+    intersects(other: OffsetRange): boolean;
+    intersectsOrTouches(other: OffsetRange): boolean;
+    slice<T>(arr: readonly T[]): T[];
+    toString(): string;
+}
+
+/**
+ * A pair of ranges, one in `original`, one in `modified`.
+ */
+declare class OffsetRangeMapping {
+    readonly original: OffsetRange;
+    readonly modified: OffsetRange;
+    constructor(original: OffsetRange, modified: OffsetRange);
+    toString(): string;
+}
+
+/**
+ * A single atomic replacement: replace `range` in the input with `newText`.
+ */
+declare class StringReplacement {
+    readonly range: OffsetRange;
+    readonly newText: string;
+    constructor(range: OffsetRange, newText: string);
+    get isEmpty(): boolean;
+    toString(): string;
+}
+/**
+ * A set of replacements applied in parallel to one input string.
+ *
+ * Invariants:
+ *  - replacements are sorted by `range.start`
+ *  - replacements do not overlap (touching is allowed)
+ *  - all ranges live in the same coordinate space (the input passed to `apply`)
+ */
+declare class StringEdit {
+    readonly replacements: readonly StringReplacement[];
+    static readonly empty: StringEdit;
+    static single(replacement: StringReplacement): StringEdit;
+    /**
+     * Validates that replacements are sorted and non-overlapping.
+     */
+    static of(replacements: readonly StringReplacement[]): StringEdit;
+    private constructor();
+    get isEmpty(): boolean;
+    apply(text: string): string;
+    /**
+     * Returns an edit `E` such that `E.apply(this.apply(input)) === input`.
+     */
+    inverse(input: string): StringEdit;
+    /**
+     * Joins touching replacements and drops no-ops.
+     */
+    normalize(): StringEdit;
+    toString(): string;
+}
+
+/**
+ * Annotation attached to a replacement. `join` decides whether two
+ * adjacent annotations can be merged during `normalize()`.
+ */
+interface IEditData<T> {
+    join(other: T): T | undefined;
+}
+/**
+ * An atomic replacement carrying user-defined metadata.
+ */
+declare class AnnotatedStringReplacement<T extends IEditData<T>> {
+    readonly range: OffsetRange;
+    readonly newText: string;
+    readonly data: T;
+    constructor(range: OffsetRange, newText: string, data: T);
+    get isEmpty(): boolean;
+    toString(): string;
+}
+/**
+ * A set of annotated replacements applied in parallel.
+ *
+ * Invariants: same as `StringEdit` (sorted by `range.start`, non-overlapping,
+ * shared coordinate space).
+ */
+declare class AnnotatedStringEdit<T extends IEditData<T>> {
+    readonly replacements: readonly AnnotatedStringReplacement<T>[];
+    static empty<T extends IEditData<T>>(): AnnotatedStringEdit<T>;
+    static single<T extends IEditData<T>>(replacement: AnnotatedStringReplacement<T>): AnnotatedStringEdit<T>;
+    static of<T extends IEditData<T>>(replacements: readonly AnnotatedStringReplacement<T>[]): AnnotatedStringEdit<T>;
+    private constructor();
+    get isEmpty(): boolean;
+    apply(text: string): string;
+    inverse(input: string, invertData: (data: T) => T): AnnotatedStringEdit<T>;
+    /**
+     * Joins touching replacements when their annotations join. Drops no-ops.
+     */
+    normalize(): AnnotatedStringEdit<T>;
+    mapData<U extends IEditData<U>>(f: (data: T) => U): AnnotatedStringEdit<U>;
+    stripData(): StringEdit;
+    toString(): string;
+}
+/**
+ * Diff result annotation.
+ *
+ * Carries flags describing the nature of the replacement. For now only
+ * `isFormattingChange` is exposed; more flags (e.g. move source/target,
+ * semantic category) can be added later.
+ */
+declare class DiffAnnotation implements IEditData<DiffAnnotation> {
+    /** Whether the replacement is purely a formatting change (whitespace, indentation, etc.). */
+    readonly isFormattingChange: boolean;
+    static readonly change: DiffAnnotation;
+    static readonly formatting: DiffAnnotation;
+    private constructor();
+    join(other: DiffAnnotation): DiffAnnotation | undefined;
+    toString(): string;
+}
+
+/**
+ * A block of text that was moved between two locations.
+ *
+ * `range` locates the block in `original` and in `modified` (offsets in the
+ * respective full texts). `innerEdit` describes the changes inside the moved
+ * block, with offsets local to the slice (i.e. `0` is the start of the slice).
+ */
+declare class Move {
+    readonly range: OffsetRangeMapping;
+    readonly innerEdit: StringEdit;
+    constructor(range: OffsetRangeMapping, innerEdit: StringEdit);
+    toString(): string;
+}
+
+/**
+ * Output of a diff computation.
+ */
+declare class DiffResult {
+    /**
+     * Parallel set of replacements transforming `original` into `modified`,
+     * excluding any replacements that are part of a `Move`.
+     *
+     * When no moves are computed: `edits.apply(original) === modified`.
+     */
+    readonly edits: AnnotatedStringEdit<DiffAnnotation>;
+    /**
+     * Detected text moves. Empty unless `DiffOptions.computeMoves` is set.
+     */
+    readonly moves: readonly Move[];
+    /**
+     * `true` if the algorithm aborted because of `maxComputationTimeMs`.
+     * The result is still valid but may be coarser than ideal.
+     */
+    readonly hitTimeout: boolean;
+    constructor(
+    /**
+     * Parallel set of replacements transforming `original` into `modified`,
+     * excluding any replacements that are part of a `Move`.
+     *
+     * When no moves are computed: `edits.apply(original) === modified`.
+     */
+    edits: AnnotatedStringEdit<DiffAnnotation>, 
+    /**
+     * Detected text moves. Empty unless `DiffOptions.computeMoves` is set.
+     */
+    moves: readonly Move[], 
+    /**
+     * `true` if the algorithm aborted because of `maxComputationTimeMs`.
+     * The result is still valid but may be coarser than ideal.
+     */
+    hitTimeout: boolean);
+}
+interface DiffOptions {
+    /**
+     * Algorithm hint. Pure-TS computer auto-selects based on input size if omitted.
+     * The WASM computer currently ignores this hint.
+     */
+    algorithm?: 'myers' | 'dynamic-programming';
+    /** Maximum computation time in milliseconds. 0 (default) means no timeout. */
+    maxComputationTimeMs?: number;
+    /** Ignore leading and trailing whitespace differences. Default: false. */
+    ignoreTrimWhitespace?: boolean;
+    /** Detect moved blocks of text. Default: false. */
+    computeMoves?: boolean;
+    /** Extend diffs to subword boundaries. Default: false. */
+    extendToSubwords?: boolean;
+}
+interface IDiffComputer {
+    computeDiff(original: string, modified: string, options?: DiffOptions): DiffResult;
+}
+
+interface CreateDiffComputerOptions {
+    /**
+     * Use the WASM-backed implementation. Loads the WASM module on first creation.
+     * Default: false (pure-TS implementation).
+     */
+    useWasm?: boolean;
+    /**
+     * Algorithm hint passed to the computer.
+     */
+    algorithm?: 'myers' | 'dynamic-programming';
+}
+declare function createDiffComputer(options?: CreateDiffComputerOptions): Promise<IDiffComputer>;
+
+export { AnnotatedStringEdit, AnnotatedStringReplacement, DiffAnnotation, DiffResult, Move, OffsetRange, OffsetRangeMapping, StringEdit, StringReplacement, createDiffComputer };
+export type { CreateDiffComputerOptions, DiffOptions, IDiffComputer, IEditData };