@effected/source 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+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/LineIndex.js

@@ -0,0 +1,258 @@
+// src/LineIndex.ts
+const LF = 10;
+const CR = 13;
+const LS = 8232;
+const PS = 8233;
+const requireInteger = (name, value) => {
+	if (!Number.isInteger(value)) throw new RangeError(`LineIndex: ${name} must be an integer, received ${value}`);
+};
+const requireLength = (length) => {
+	requireInteger("length", length);
+	if (length < 0) throw new RangeError(`LineIndex: length must not be negative, received ${length}`);
+};
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+/**
+* A line table over one source text, built once and queried many times:
+* offset to `{ line, character }` and back, the number of lines, and where
+* each line starts and ends.
+*
+* @remarks
+* Positions are zero-based and `character` counts UTF-16 code units, LSP's
+* default encoding (see {@link SourcePosition}). Building the index is one
+* forward scan, `O(n)`; every lookup is a binary search, `O(log n)`, so build
+* one per text and reuse it rather than rescanning for every diagnostic.
+*
+* Out-of-range input clamps instead of throwing, following
+* `vscode-languageserver-textdocument`'s `TextDocument`, which most LSP
+* servers already use:
+*
+* - an offset below `0` reads as `0`, and one past the end as `text.length`;
+* - an offset inside a two-character terminator (the `\n` of a `\r\n`) reads
+*   as the end of its line, because no position can name the middle of a
+*   terminator;
+* - a `character` past the end of its line reads as the end of the line's
+*   text, before its terminator, and a negative one as the line's start;
+* - a `line` below `0` reads as offset `0`, and one past the last line as
+*   `text.length`.
+*
+* A value that is not an integer (`NaN`, `1.5`, `Infinity`) is a programmer
+* error, not out-of-range input, and throws a `RangeError`: clamping `NaN`
+* would silently answer "line 0".
+*
+* Every text has at least one line. The empty text has one empty line, and a
+* text ending in a terminator has an empty last line after it, so `"a\n"` has
+* two lines, as an editor shows it.
+*
+* `character` can name the low half of a surrogate pair; LSP leaves that to
+* the client, and so does this index. It offers no code-point encoding:
+* every LSP client must accept UTF-16, and each kit format package reports
+* UTF-16 offsets.
+*
+* There is no shared-instance contract. Nothing checks `instanceof LineIndex`,
+* and every value it returns is a plain record, so two installed copies of
+* this package interoperate at runtime. At the type level the class does
+* not: its `private` members make TypeScript compare it nominally, so a
+* `LineIndex` from one copy is not assignable to another copy's `LineIndex`.
+* Type a signature that takes or returns an index with the structural
+* {@link SourceIndex} interface this class implements, never with the class.
+*
+* @example
+* ```ts
+* import { LineIndex } from "@effected/source";
+*
+* const index = LineIndex.make("name: kit\r\nversion: 1\n");
+* console.log(index.lineCount);
+* // => 3
+* console.log(index.positionAt(11));
+* // => { line: 1, character: 0 }
+* console.log(index.offsetAt({ line: 1, character: 9 }));
+* // => 20
+* console.log(index.lineText(1));
+* // => "version: 1"
+* ```
+*
+* @public
+*/
+var LineIndex = class LineIndex {
+	text;
+	lineBreaks;
+	starts;
+	constructor(text, lineBreaks, starts) {
+		this.text = text;
+		this.lineBreaks = lineBreaks;
+		this.starts = starts;
+	}
+	/**
+	* Build the line table for `text` with one forward scan.
+	*
+	* @param text - The source text.
+	* @param options - Which characters end a line; see {@link LineIndexOptions}.
+	* @returns The index.
+	*/
+	static make(text, options) {
+		const lineBreaks = options?.lineBreaks ?? "lsp";
+		const starts = [0];
+		const length = text.length;
+		for (let i = 0; i < length; i++) {
+			const code = text.charCodeAt(i);
+			if (code === LF) starts.push(i + 1);
+			else if (code === CR) {
+				if (i + 1 < length && text.charCodeAt(i + 1) === LF) {
+					starts.push(i + 2);
+					i++;
+				} else if (lineBreaks !== "lf") starts.push(i + 1);
+			} else if ((code === LS || code === PS) && lineBreaks === "unicode") starts.push(i + 1);
+		}
+		return new LineIndex(text, lineBreaks, starts);
+	}
+	/** The number of lines, at least `1`. */
+	get lineCount() {
+		return this.starts.length;
+	}
+	/**
+	* The zero-based line that contains `offset`. An offset at a terminator
+	* belongs to the line the terminator ends.
+	*
+	* @param offset - A UTF-16 offset, clamped to `[0, text.length]`.
+	* @returns The line number.
+	*/
+	lineAt(offset) {
+		requireInteger("offset", offset);
+		const target = clamp(offset, 0, this.text.length);
+		let low = 0;
+		let high = this.starts.length - 1;
+		while (low < high) {
+			const mid = low + high + 1 >> 1;
+			if (this.starts[mid] <= target) low = mid;
+			else high = mid - 1;
+		}
+		return low;
+	}
+	/**
+	* The offset of the first character of `line`.
+	*
+	* @param line - A zero-based line, clamped to `[0, lineCount - 1]`.
+	* @returns The line's start offset.
+	*/
+	lineStart(line) {
+		return this.starts[this.clampLine(line)];
+	}
+	/**
+	* The offset just past the last character of `line`'s text, which is
+	* where its terminator starts, or `text.length` on the last line.
+	*
+	* @param line - A zero-based line, clamped to `[0, lineCount - 1]`.
+	* @returns The line's end offset, excluding its terminator.
+	*/
+	lineEnd(line) {
+		return this.endOf(this.clampLine(line));
+	}
+	/**
+	* The text of `line`, without its terminator.
+	*
+	* @param line - A zero-based line, clamped to `[0, lineCount - 1]`.
+	* @returns The line's text.
+	*/
+	lineText(line) {
+		const index = this.clampLine(line);
+		return this.text.slice(this.starts[index], this.endOf(index));
+	}
+	/**
+	* The zero-based `{ line, character }` of `offset`.
+	*
+	* @param offset - A UTF-16 offset, clamped to `[0, text.length]`; one
+	*   inside a `\r\n` reads as the end of its line.
+	* @returns The position.
+	*/
+	positionAt(offset) {
+		const line = this.lineAt(offset);
+		const target = clamp(offset, 0, this.text.length);
+		const start = this.starts[line];
+		return {
+			line,
+			character: Math.min(target, this.endOf(line)) - start
+		};
+	}
+	/**
+	* The offset of a zero-based `{ line, character }`.
+	*
+	* @param position - The position. A `line` past the last reads as
+	*   `text.length` and one below `0` as `0`; a `character` past the line's
+	*   text reads as the line's end, before its terminator.
+	* @returns The UTF-16 offset.
+	*/
+	offsetAt(position) {
+		requireInteger("line", position.line);
+		requireInteger("character", position.character);
+		if (position.line < 0) return 0;
+		if (position.line >= this.starts.length) return this.text.length;
+		const start = this.starts[position.line];
+		const end = this.endOf(position.line);
+		return clamp(start + position.character, start, end);
+	}
+	/**
+	* The {@link SourceSpan} (LSP `Range`) of an offset range.
+	*
+	* @param range - The range; its `length` must not be negative.
+	* @returns The start and exclusive end positions.
+	*/
+	spanOf(range) {
+		requireLength(range.length);
+		return {
+			start: this.positionAt(range.offset),
+			end: this.positionAt(range.offset + range.length)
+		};
+	}
+	/**
+	* The {@link SourceRange} of a {@link SourceSpan}, after each position is
+	* clamped as {@link LineIndex.offsetAt} clamps it.
+	*
+	* @param span - The span; `end` must not precede `start`.
+	* @returns The offset and length.
+	*/
+	rangeOf(span) {
+		const start = this.offsetAt(span.start);
+		const end = this.offsetAt(span.end);
+		if (end < start) throw new RangeError(`LineIndex: span end ${span.end.line}:${span.end.character} precedes its start ${span.start.line}:${span.start.character}`);
+		return {
+			offset: start,
+			length: end - start
+		};
+	}
+	/**
+	* The {@link SourceLocation} of a range: the range itself, unchanged,
+	* with the position of its start. The shape a diagnostic carries.
+	*
+	* @param range - The range; its `length` must be a non-negative integer,
+	*   as {@link LineIndex.spanOf} requires.
+	* @returns `offset`, `length`, `line` and `character`.
+	*/
+	locationOf(range) {
+		requireLength(range.length);
+		const { line, character } = this.positionAt(range.offset);
+		return {
+			offset: range.offset,
+			length: range.length,
+			line,
+			character
+		};
+	}
+	/**
+	* Where `line`'s text ends, derived from the next line's start rather
+	* than stored: the next start minus the terminator's length, two for a
+	* `\r\n` and one for every other terminator, or `text.length` on the
+	* last line. Keeping one table halves the index's memory; the lookup
+	* stays `O(1)` after the `O(log n)` search that found the line.
+	*/
+	endOf(line) {
+		const next = this.starts[line + 1];
+		if (next === void 0) return this.text.length;
+		return this.text.charCodeAt(next - 1) === LF && this.text.charCodeAt(next - 2) === CR ? next - 2 : next - 1;
+	}
+	clampLine(line) {
+		requireInteger("line", line);
+		return clamp(line, 0, this.starts.length - 1);
+	}
+};
+
+export { LineIndex };

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @effected/source
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@effected%2Fsource?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/source)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
+[![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
+
+Source-text positions as plain values: a line index that turns an offset into an LSP-style zero-based line and character and back, and the range, position and diagnostic shapes the `@effected` format packages share. No service, no platform, no `effect`, and no dependency at all.
+
+> **Pre-`1.0.0`.** This package is part of the `@effected/*` kit, still in `0.x`
+> development. It has no dependencies, not even `effect`.
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version. Full
+> policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/source
+
+A parser reports where something went wrong as an offset into the text. An editor, a language server and a person all want a line and a column. The conversion looks like a five-line loop, and that loop is easy to get subtly wrong: which characters end a line, what an offset between the `\r` and `\n` of a Windows line ending means, and whether a column counts code units or characters. This package is the conversion written once, by the rules the Language Server Protocol uses.
+
+## Install
+
+```bash
+npm install @effected/source
+```
+
+```bash
+pnpm add @effected/source
+```
+
+Requires Node.js >=24.11.0. No dependencies and no peers. ESM-only: import it from an ES module.
+
+## Usage
+
+```ts
+import { LineIndex } from "@effected/source";
+
+const index = LineIndex.make("name: kit\r\nversion: 1\n");
+
+index.positionAt(11);
+// { line: 1, character: 0 }
+
+index.offsetAt({ line: 1, character: 9 });
+// 20
+
+index.spanOf({ offset: 11, length: 7 });
+// { start: { line: 1, character: 0 }, end: { line: 1, character: 7 } }
+```
+
+- **`LineIndex.make(text, options?)`** builds the line table once; every query after that is a binary search. `positionAt` and `offsetAt` convert both ways, `lineCount`, `lineAt`, `lineStart`, `lineEnd` and `lineText` describe the lines, and `spanOf`, `rangeOf` and `locationOf` convert ranges.
+- **Positions are zero-based** and `character` counts UTF-16 code units, LSP's default. Add 1 to both for a person.
+- **Lines end at `\n`, `\r\n` or a bare `\r`** by default. `lineBreaks: "lf"` ends them at `\n` only, and `lineBreaks: "unicode"` also at U+2028 and U+2029.
+- **Out-of-range input clamps** to the nearest valid position, as `vscode-languageserver-textdocument` does. A value that is not an integer throws a `RangeError`.
+- **`SourcePosition`, `SourceRange`, `SourceSpan`, `SourceLocation` and `SourceDiagnostic`** are structural interfaces, so the diagnostics and ranges of `@effected/jsonc`, `@effected/yaml`, `@effected/toml` and `@effected/markdown` can be read through them as they are.
+
+## Documentation
+
+The guide and the API reference are at [effected.spencerbeg.gs/source](https://effected.spencerbeg.gs/source).
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -0,0 +1,359 @@
+/**
+ * A zero-based line and character in a source text, the shape of an LSP
+ * `Position`.
+ *
+ * @remarks
+ * Both fields count from `0`. `character` counts UTF-16 code units from the
+ * start of the line, which is LSP's default position encoding and what a
+ * JavaScript string index already is, so an astral character such as an emoji
+ * occupies two. A line is ended by `\n`, `\r\n` or a bare `\r` unless the
+ * {@link LineIndex} that produced the position was built with another
+ * {@link (LineBreaks:type)} rule.
+ *
+ * This is a structural interface, not a class: any `{ line, character }`
+ * record satisfies it, so the kit's format packages can return their own
+ * classes and still be read through it, and two installed copies of this
+ * package never disagree about what a position is.
+ *
+ * A human reader counts from 1. Add 1 to both fields when printing a
+ * position for a person, and keep the structured value zero-based.
+ *
+ * @public
+ */
+interface SourcePosition {
+  /** The zero-based line number. */
+  readonly line: number;
+  /** The zero-based offset within the line, in UTF-16 code units. */
+  readonly character: number;
+}
+/**
+ * A span of a source text as a start offset and a length, both in UTF-16 code
+ * units: the characters `[offset, offset + length)`.
+ *
+ * @remarks
+ * The shape every kit format package uses for a range (`JsoncRange`,
+ * `YamlRange`, `TomlRange`, `MarkdownRange`) and for the positional part of an
+ * edit, so any of them satisfies this interface as it stands. A `length` of
+ * `0` is an empty span, an insertion point.
+ *
+ * Offsets are string indices, not bytes and not code points. Convert to a
+ * line and character with {@link LineIndex.spanOf}.
+ *
+ * @public
+ */
+interface SourceRange {
+  /** The zero-based UTF-16 offset of the first character. */
+  readonly offset: number;
+  /** The number of UTF-16 code units in the span. */
+  readonly length: number;
+}
+/**
+ * Where something sits in a source text, said both ways: the
+ * {@link SourceRange} (`offset`, `length`) and the {@link SourcePosition} of
+ * its start (`line`, `character`, zero-based).
+ *
+ * @remarks
+ * The positional core of every kit diagnostic. `JsoncParseErrorDetail`
+ * satisfies it, and so do `YamlDiagnostic`, `TomlDiagnostic`,
+ * `MarkdownDiagnostic` and `YamlToken`. {@link LineIndex.locationOf} builds
+ * one from a range.
+ *
+ * @public
+ */
+interface SourceLocation extends SourceRange, SourcePosition {}
+/**
+ * A diagnostic about a source text: a machine-readable `code`, a
+ * human-readable `message`, and its {@link SourceLocation}.
+ *
+ * @remarks
+ * A structural contract, not a base class. Each format package keeps its own
+ * diagnostic class, its own `code` union and its own error types, which stay
+ * part of that package's API; this interface only names the shape they
+ * already share, so a consumer (an LSP server, a CLI printing annotations, a
+ * lint host) can be written once over any of them. `YamlDiagnostic`,
+ * `TomlDiagnostic` and `MarkdownDiagnostic` satisfy it as they stand.
+ * `JsoncParseErrorDetail` carries no `message`, so it satisfies
+ * {@link SourceLocation} only.
+ *
+ * `Code` narrows the code union for a consumer that knows which package the
+ * diagnostic came from; the default accepts any.
+ *
+ * @typeParam Code - The diagnostic code union.
+ *
+ * @public
+ */
+interface SourceDiagnostic<Code extends string = string> extends SourceLocation {
+  /** The machine-readable diagnostic code. */
+  readonly code: Code;
+  /** The human-readable description. */
+  readonly message: string;
+}
+/**
+ * A span of a source text as two {@link SourcePosition}s, the shape of an LSP
+ * `Range`. `end` is exclusive.
+ *
+ * @remarks
+ * The line-and-character twin of {@link SourceRange}. An LSP server reports
+ * and receives this shape; a parser reports offsets. {@link LineIndex.spanOf}
+ * and {@link LineIndex.rangeOf} convert between them.
+ *
+ * @public
+ */
+interface SourceSpan {
+  /** The position of the first character. */
+  readonly start: SourcePosition;
+  /** The position just past the last character. */
+  readonly end: SourcePosition;
+}
+/**
+ * The public surface of a line index, as a structural interface: what
+ * {@link LineIndex} answers, with nothing that ties a value to one copy of
+ * this package.
+ *
+ * @remarks
+ * Type a signature that takes or returns a line index with this interface,
+ * never with the `LineIndex` class. The class has `private` members, and
+ * TypeScript compares a class with `private` members nominally: when two
+ * copies of `@effected/source` are installed (a format package on one
+ * version, its consumer on another), a `LineIndex` built by one copy is not
+ * assignable to the other copy's `LineIndex` type (TS2345, "Types have
+ * separate declarations of a private property"). Every member here is a
+ * public method or a readonly property, so an index from any copy satisfies
+ * this interface from any other.
+ *
+ * Construct one with {@link LineIndex.make}; this interface has no
+ * constructor of its own, and nothing checks `instanceof`.
+ *
+ * @example
+ * ```ts
+ * import type { SourceIndex, SourcePosition } from "@effected/source";
+ * import { LineIndex } from "@effected/source";
+ *
+ * const startOf = (index: SourceIndex, offset: number): SourcePosition => index.positionAt(offset);
+ * console.log(startOf(LineIndex.make("a\nb"), 2));
+ * // => { line: 1, character: 0 }
+ * ```
+ *
+ * @public
+ */
+interface SourceIndex {
+  /** The text this index was built over. */
+  readonly text: string;
+  /** The rule that decided where lines end. */
+  readonly lineBreaks: LineBreaks;
+  /** The number of lines, at least `1`. */
+  readonly lineCount: number;
+  /** The zero-based line that contains `offset`; see {@link LineIndex.lineAt}. */
+  lineAt(offset: number): number;
+  /** The offset of the first character of `line`; see {@link LineIndex.lineStart}. */
+  lineStart(line: number): number;
+  /** The offset where `line`'s terminator starts; see {@link LineIndex.lineEnd}. */
+  lineEnd(line: number): number;
+  /** The text of `line`, without its terminator; see {@link LineIndex.lineText}. */
+  lineText(line: number): string;
+  /** The `{ line, character }` of `offset`; see {@link LineIndex.positionAt}. */
+  positionAt(offset: number): SourcePosition;
+  /** The offset of a position; see {@link LineIndex.offsetAt}. */
+  offsetAt(position: SourcePosition): number;
+  /** The span of an offset range; see {@link LineIndex.spanOf}. */
+  spanOf(range: SourceRange): SourceSpan;
+  /** The offset range of a span; see {@link LineIndex.rangeOf}. */
+  rangeOf(span: SourceSpan): SourceRange;
+  /** The location of a range; see {@link LineIndex.locationOf}. */
+  locationOf(range: SourceRange): SourceLocation;
+}
+/**
+ * Which characters end a line, for {@link LineIndex.make}.
+ *
+ * @remarks
+ * - `"lsp"` (the default): `\n`, `\r\n` and a bare `\r`, the Language Server
+ *   Protocol's rule. `\r\n` is one terminator. Markdown, TOML, YAML (its
+ *   tokens, lint lines and diagnostics alike) and an LSP client all count
+ *   lines this way.
+ * - `"lf"`: a line ends at `\n` only. `\r\n` is still one terminator (the
+ *   `\r` is not part of the line's text), but a bare `\r` is an ordinary
+ *   character. No kit package uses it now; it stays for a consumer that must
+ *   reproduce a `\n`-only line count, such as a tool that splits on `\n`.
+ * - `"unicode"`: the `"lsp"` rule plus U+2028 LINE SEPARATOR and U+2029
+ *   PARAGRAPH SEPARATOR, each a terminator on its own. `@effected/jsonc`
+ *   counts its diagnostics' lines this way, as its scanner does. An LSP
+ *   client does not, so a position computed under this rule disagrees with
+ *   the client's after the first separator.
+ *
+ * @public
+ */
+type LineBreaks = "lsp" | "lf" | "unicode";
+/**
+ * Options for {@link LineIndex.make}.
+ *
+ * @public
+ */
+interface LineIndexOptions {
+  /**
+   * Which characters end a line. Defaults to `"lsp"`: `\n`, `\r\n` and a
+   * bare `\r`.
+   */
+  readonly lineBreaks?: LineBreaks;
+}
+/**
+ * A line table over one source text, built once and queried many times:
+ * offset to `{ line, character }` and back, the number of lines, and where
+ * each line starts and ends.
+ *
+ * @remarks
+ * Positions are zero-based and `character` counts UTF-16 code units, LSP's
+ * default encoding (see {@link SourcePosition}). Building the index is one
+ * forward scan, `O(n)`; every lookup is a binary search, `O(log n)`, so build
+ * one per text and reuse it rather than rescanning for every diagnostic.
+ *
+ * Out-of-range input clamps instead of throwing, following
+ * `vscode-languageserver-textdocument`'s `TextDocument`, which most LSP
+ * servers already use:
+ *
+ * - an offset below `0` reads as `0`, and one past the end as `text.length`;
+ * - an offset inside a two-character terminator (the `\n` of a `\r\n`) reads
+ *   as the end of its line, because no position can name the middle of a
+ *   terminator;
+ * - a `character` past the end of its line reads as the end of the line's
+ *   text, before its terminator, and a negative one as the line's start;
+ * - a `line` below `0` reads as offset `0`, and one past the last line as
+ *   `text.length`.
+ *
+ * A value that is not an integer (`NaN`, `1.5`, `Infinity`) is a programmer
+ * error, not out-of-range input, and throws a `RangeError`: clamping `NaN`
+ * would silently answer "line 0".
+ *
+ * Every text has at least one line. The empty text has one empty line, and a
+ * text ending in a terminator has an empty last line after it, so `"a\n"` has
+ * two lines, as an editor shows it.
+ *
+ * `character` can name the low half of a surrogate pair; LSP leaves that to
+ * the client, and so does this index. It offers no code-point encoding:
+ * every LSP client must accept UTF-16, and each kit format package reports
+ * UTF-16 offsets.
+ *
+ * There is no shared-instance contract. Nothing checks `instanceof LineIndex`,
+ * and every value it returns is a plain record, so two installed copies of
+ * this package interoperate at runtime. At the type level the class does
+ * not: its `private` members make TypeScript compare it nominally, so a
+ * `LineIndex` from one copy is not assignable to another copy's `LineIndex`.
+ * Type a signature that takes or returns an index with the structural
+ * {@link SourceIndex} interface this class implements, never with the class.
+ *
+ * @example
+ * ```ts
+ * import { LineIndex } from "@effected/source";
+ *
+ * const index = LineIndex.make("name: kit\r\nversion: 1\n");
+ * console.log(index.lineCount);
+ * // => 3
+ * console.log(index.positionAt(11));
+ * // => { line: 1, character: 0 }
+ * console.log(index.offsetAt({ line: 1, character: 9 }));
+ * // => 20
+ * console.log(index.lineText(1));
+ * // => "version: 1"
+ * ```
+ *
+ * @public
+ */
+export declare class LineIndex implements SourceIndex {
+  /** The text this index was built over. */
+  readonly text: string;
+  /** The rule that decided where lines end. */
+  readonly lineBreaks: LineBreaks;
+  private readonly starts;
+  private constructor();
+  /**
+   * Build the line table for `text` with one forward scan.
+   *
+   * @param text - The source text.
+   * @param options - Which characters end a line; see {@link LineIndexOptions}.
+   * @returns The index.
+   */
+  static make(text: string, options?: LineIndexOptions): LineIndex;
+  /** The number of lines, at least `1`. */
+  get lineCount(): number;
+  /**
+   * The zero-based line that contains `offset`. An offset at a terminator
+   * belongs to the line the terminator ends.
+   *
+   * @param offset - A UTF-16 offset, clamped to `[0, text.length]`.
+   * @returns The line number.
+   */
+  lineAt(offset: number): number;
+  /**
+   * The offset of the first character of `line`.
+   *
+   * @param line - A zero-based line, clamped to `[0, lineCount - 1]`.
+   * @returns The line's start offset.
+   */
+  lineStart(line: number): number;
+  /**
+   * The offset just past the last character of `line`'s text, which is
+   * where its terminator starts, or `text.length` on the last line.
+   *
+   * @param line - A zero-based line, clamped to `[0, lineCount - 1]`.
+   * @returns The line's end offset, excluding its terminator.
+   */
+  lineEnd(line: number): number;
+  /**
+   * The text of `line`, without its terminator.
+   *
+   * @param line - A zero-based line, clamped to `[0, lineCount - 1]`.
+   * @returns The line's text.
+   */
+  lineText(line: number): string;
+  /**
+   * The zero-based `{ line, character }` of `offset`.
+   *
+   * @param offset - A UTF-16 offset, clamped to `[0, text.length]`; one
+   *   inside a `\r\n` reads as the end of its line.
+   * @returns The position.
+   */
+  positionAt(offset: number): SourcePosition;
+  /**
+   * The offset of a zero-based `{ line, character }`.
+   *
+   * @param position - The position. A `line` past the last reads as
+   *   `text.length` and one below `0` as `0`; a `character` past the line's
+   *   text reads as the line's end, before its terminator.
+   * @returns The UTF-16 offset.
+   */
+  offsetAt(position: SourcePosition): number;
+  /**
+   * The {@link SourceSpan} (LSP `Range`) of an offset range.
+   *
+   * @param range - The range; its `length` must not be negative.
+   * @returns The start and exclusive end positions.
+   */
+  spanOf(range: SourceRange): SourceSpan;
+  /**
+   * The {@link SourceRange} of a {@link SourceSpan}, after each position is
+   * clamped as {@link LineIndex.offsetAt} clamps it.
+   *
+   * @param span - The span; `end` must not precede `start`.
+   * @returns The offset and length.
+   */
+  rangeOf(span: SourceSpan): SourceRange;
+  /**
+   * The {@link SourceLocation} of a range: the range itself, unchanged,
+   * with the position of its start. The shape a diagnostic carries.
+   *
+   * @param range - The range; its `length` must be a non-negative integer,
+   *   as {@link LineIndex.spanOf} requires.
+   * @returns `offset`, `length`, `line` and `character`.
+   */
+  locationOf(range: SourceRange): SourceLocation;
+  /**
+   * Where `line`'s text ends, derived from the next line's start rather
+   * than stored: the next start minus the terminator's length, two for a
+   * `\r\n` and one for every other terminator, or `text.length` on the
+   * last line. Keeping one table halves the index's memory; the lookup
+   * stays `O(1)` after the `O(log n)` search that found the line.
+   */
+  private endOf;
+  private clampLine;
+}
+export type { LineBreaks, LineIndexOptions, SourceDiagnostic, SourceIndex, SourceLocation, SourcePosition, SourceRange, SourceSpan };
+//# sourceMappingURL=index.d.ts.map

package/index.js

@@ -0,0 +1,3 @@
+import { LineIndex } from "./LineIndex.js";
+
+export { LineIndex };

package/package.json

@@ -1,6 +1,45 @@
 {
-  "name": "@effected/source",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@effected/source",
+	"version": "0.1.0",
+	"private": false,
+	"description": "Source-text positions as plain values: a line index over a text, LSP-style line and character, and the structural range and diagnostic shapes the kit's format packages share.",
+	"keywords": [
+		"source",
+		"position",
+		"line",
+		"character",
+		"offset",
+		"lsp",
+		"diagnostic",
+		"range",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/source#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/source"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.59.4"
+    }
+  ]
+}