@pieceful/ravel-projection 0.2.0

package/src/index.d.ts

@@ -0,0 +1,331 @@
+export type SnapshotId = string;
+export type ProjectionId = string;
+export type ArtifactId = string;
+export type TargetId = string;
+export type PieceId = string;
+export type OccurrenceId = string;
+export type ProjectionStage = "authoring" | "assembled" | "transformed" | "emitted";
+export type MappingKind = "exact" | "anchored" | "transformed" | "opaque" | "synthetic";
+export type MappingQuality = MappingKind;
+export type Affinity = "left" | "right" | "none";
+export type PositionEncoding = "utf-8" | "utf-16" | "utf-32";
+
+export interface OffsetRange { start: number; end: number; }
+export interface SourcePosition { line: number; column: number; offset: number; }
+export interface SourceRange { start: SourcePosition; end: SourcePosition; }
+export interface SourceLocation { uri: string; range: SourceRange; }
+export interface ProjectionCapabilities {
+  navigation: boolean;
+  diagnostics: boolean;
+  completion: boolean;
+  writableEdits: boolean;
+}
+export interface TransformStep {
+  kind?: "transform";
+  name?: string;
+  phase?: number;
+  source?: SourceLocation;
+}
+
+export interface ProjectionSegment {
+  readonly virtual: OffsetRange;
+  readonly source?: SourceLocation;
+  readonly pieceId?: PieceId;
+  readonly occurrenceId?: OccurrenceId;
+  readonly expansionPath: readonly PieceId[];
+  readonly kind: MappingKind;
+  readonly role?: string;
+  readonly startAffinity?: "left" | "right";
+  readonly endAffinity?: "left" | "right";
+  readonly transformChain?: readonly TransformStep[];
+}
+
+export interface ExpansionOccurrence {
+  readonly id: OccurrenceId;
+  readonly pieceId: PieceId;
+  readonly projectionId: ProjectionId;
+  readonly virtual: OffsetRange;
+  readonly invocationSource?: SourceLocation;
+  readonly definitionSource?: SourceLocation;
+  readonly expansionPath: readonly PieceId[];
+  readonly parentOccurrenceId?: OccurrenceId;
+  readonly childOccurrenceIds: readonly OccurrenceId[];
+  readonly implicit?: boolean;
+}
+
+export interface LineIndex {
+  readonly text: string;
+  readonly textLength: number;
+  readonly lineStarts: readonly number[];
+}
+
+export interface ProjectionIndexes {
+  readonly virtual: readonly number[];
+  readonly virtualMaxEnds: readonly number[];
+  readonly source: Readonly<Record<string, readonly number[]>>;
+  readonly sourceMaxEnds: Readonly<Record<string, readonly number[]>>;
+  readonly occurrenceById: Readonly<Record<string, number>>;
+  readonly children: Readonly<Record<string, readonly number[]>>;
+}
+
+export interface ProjectionDiagnostic {
+  code: string;
+  severity: "error" | "warning" | "info";
+  message: string;
+  source: SourceLocation;
+  related?: SourceLocation[];
+}
+
+export interface VirtualDocument {
+  readonly id: ProjectionId;
+  readonly uri: string;
+  readonly snapshotId: SnapshotId;
+  readonly sourceVersions: Readonly<Record<string, number>>;
+  readonly version: number;
+  readonly workspaceId: string;
+  readonly artifactId: ArtifactId;
+  readonly targetId: TargetId;
+  readonly stage: ProjectionStage;
+  readonly languageId: string;
+  readonly text: string;
+  readonly mappings: readonly ProjectionSegment[];
+  readonly occurrences: readonly ExpansionOccurrence[];
+  readonly lineIndex: LineIndex;
+  readonly sourceLineIndexes: Readonly<Record<string, LineIndex>>;
+  readonly indexes: ProjectionIndexes;
+  readonly contentHash: string;
+  readonly inputHash: string;
+  readonly artifactSource?: SourceLocation;
+  readonly projectionDiagnostics: readonly ProjectionDiagnostic[];
+  readonly capabilities: ProjectionCapabilities;
+}
+
+export interface ProjectionBuildOptions {
+  artifactId?: ArtifactId;
+  targetId?: TargetId;
+  workspaceId?: string;
+  stage?: ProjectionStage;
+  languageId?: string;
+  projectionId?: ProjectionId;
+  uri?: string;
+  path?: string;
+  snapshotId?: SnapshotId;
+  sourceVersions?: Record<string, number>;
+  sourceTexts?: Map<string, string> | Record<string, string>;
+  version?: number;
+  prefix?: string;
+  suffix?: string;
+  rootPieceId?: PieceId;
+  capabilities?: Partial<ProjectionCapabilities>;
+  signal?: AbortSignal;
+}
+
+export interface ProjectionSelection {
+  projectionId?: ProjectionId;
+  targetId?: TargetId;
+  artifactId?: ArtifactId;
+  stage?: ProjectionStage;
+  occurrenceId?: OccurrenceId;
+  affinity?: Affinity;
+  projectionVersion?: number;
+}
+
+export interface ProjectionMappingMatch {
+  projectionId: ProjectionId;
+  uri: string;
+  projectionVersion: number;
+  snapshotId: SnapshotId;
+  virtual: OffsetRange;
+  virtualOffset?: number;
+  relatedVirtual?: OffsetRange;
+  source?: SourceLocation;
+  sourceOffset?: number;
+  sourceOverlap?: OffsetRange;
+  pieceId?: PieceId;
+  occurrenceId?: OccurrenceId;
+  quality: MappingQuality;
+  role: string;
+  affinity?: Affinity;
+  writable: boolean;
+  segmentIndex: number;
+}
+
+export type MappingQueryResult =
+  | { readonly ok: true; readonly matches: readonly ProjectionMappingMatch[] }
+  | { readonly ok: false; readonly reason: string; readonly matches: readonly [] };
+
+export interface GeneratedHighlight {
+  range: OffsetRange;
+  kind: string;
+  categories: readonly string[];
+  mappingKind: MappingKind;
+  pieceId?: PieceId;
+  occurrenceId?: OccurrenceId;
+}
+export interface ExpansionBreadcrumbItem {
+  occurrenceId: OccurrenceId;
+  pieceId: PieceId;
+  label: string;
+  virtual: OffsetRange;
+  invocationSource?: SourceLocation;
+}
+export interface OccurrenceSummary {
+  occurrenceId: OccurrenceId;
+  pieceId: PieceId;
+  targetId: TargetId;
+  artifactId: ArtifactId;
+  stage: ProjectionStage;
+  virtual: OffsetRange;
+  pathLabel: string;
+}
+export interface GeneratedContext {
+  readonly ok: true;
+  readonly projection: VirtualDocument;
+  readonly projectionVersion: number;
+  readonly selectedOccurrenceId: OccurrenceId;
+  readonly visibleRange: OffsetRange;
+  readonly highlights: readonly GeneratedHighlight[];
+  readonly breadcrumb: readonly ExpansionBreadcrumbItem[];
+  readonly siblings: readonly OccurrenceSummary[];
+}
+export type GeneratedContextResult = GeneratedContext | { readonly ok: false; readonly reason: string };
+
+export interface ProjectionTextEdit { range: OffsetRange; text: string; }
+export interface ProjectionTextChange {
+  kind: "none" | "incremental" | "full";
+  changes: readonly ProjectionTextEdit[];
+}
+export interface ProjectionDelta {
+  readonly snapshotId: SnapshotId;
+  readonly sourceVersions: Readonly<Record<string, number>>;
+  readonly opened: readonly VirtualDocument[];
+  readonly changed: readonly VirtualDocument[];
+  readonly unchanged: readonly VirtualDocument[];
+  readonly closed: readonly VirtualDocument[];
+  readonly textChanges: Readonly<Record<ProjectionId, ProjectionTextChange>>;
+  readonly projectionDiagnostics: readonly ProjectionDiagnostic[];
+}
+export interface ProjectionSnapshot {
+  readonly id?: SnapshotId;
+  readonly snapshotId?: SnapshotId;
+  readonly version?: number;
+  readonly program: Record<string, any>;
+  readonly sourceVersions?: Readonly<Record<string, number>>;
+  readonly sourceTexts?: Readonly<Record<string, string>>;
+  readonly projections?: readonly ProjectionBuildOptions[] | ((snapshot: ProjectionSnapshot) => readonly ProjectionBuildOptions[]);
+}
+
+export interface ProjectionServiceOptions {
+  workspaceId?: string;
+  targetId?: TargetId;
+  stage?: ProjectionStage;
+  projections?: readonly ProjectionBuildOptions[] | ((snapshot: ProjectionSnapshot) => readonly ProjectionBuildOptions[]);
+  yieldEvery?: number;
+  maxRetainedSnapshots?: number;
+  backgroundDebounceMs?: number;
+  scheduler?: () => Promise<void>;
+  trace?: (event: Readonly<Record<string, unknown>>) => void;
+}
+
+export class ProjectionService {
+  constructor(options?: ProjectionServiceOptions);
+  update(snapshot: ProjectionSnapshot, signal?: AbortSignal): Promise<ProjectionDelta>;
+  scheduleUpdate(snapshot: ProjectionSnapshot, options?: { signal?: AbortSignal; priority?: "background" | "interactive" }): Promise<ProjectionDelta>;
+  getProjection(id: ProjectionId): VirtualDocument | undefined;
+  getProjectionByUri(uri: string): VirtualDocument | undefined;
+  listProjections(): readonly VirtualDocument[];
+  listProjectionsForSource(source: SourceLocation): readonly Array<{ projectionId: ProjectionId; uri: string; artifactId: ArtifactId; targetId: TargetId; stage: ProjectionStage; version: number }>;
+  listOccurrences(pieceId: PieceId, targetId?: TargetId): readonly ExpansionOccurrence[];
+  toVirtual(source: SourceLocation | { uri: string; offset: number }, selection?: ProjectionSelection): readonly ProjectionMappingMatch[];
+  toSource(projectionId: ProjectionId, virtual: OffsetRange | number, options?: ProjectionSelection): readonly ProjectionMappingMatch[];
+  generatedContext(occurrenceId: OccurrenceId, options?: GeneratedContextOptions): GeneratedContextResult;
+  getStats(): Readonly<{ built: number; reused: number; cancelled: number; updates: number; retainedSnapshots: number; currentProjections: number }>;
+  dispose(): void;
+}
+
+export interface GeneratedContextOptions {
+  surroundingLines?: number;
+  projectionVersion?: number;
+  sourceSelection?: SourceLocation;
+}
+
+export function createProjectionId(options?: ProjectionBuildOptions): ProjectionId;
+export function createVirtualUri(options?: ProjectionBuildOptions & { path?: string }): string;
+export function buildVirtualDocument(program: Record<string, any>, options?: ProjectionBuildOptions): VirtualDocument;
+export function projectionInputHash(program: Record<string, any>, options?: ProjectionBuildOptions): string;
+export function createLineIndex(text?: string): LineIndex;
+export function positionAt(index: LineIndex, offset: number, encoding?: PositionEncoding): { ok: true; position: { line: number; character: number; offset: number } } | { ok: false; reason: string };
+export function offsetAt(index: LineIndex, position: { line: number; character: number }, encoding?: PositionEncoding): { ok: true; offset: number } | { ok: false; reason: string };
+export function lineRangeAt(index: LineIndex, line: number): { ok: true; range: OffsetRange } | { ok: false; reason: string };
+export function lineWindow(index: LineIndex, range: OffsetRange, surroundingLines?: number): { ok: true; range: OffsetRange } | { ok: false; reason: string };
+export function buildProjectionIndexes(segments?: readonly ProjectionSegment[], occurrences?: readonly ExpansionOccurrence[]): ProjectionIndexes;
+export function coalesceProjectionSegments(segments?: readonly ProjectionSegment[]): readonly ProjectionSegment[];
+export function mapVirtualOffset(document: VirtualDocument, offset: number, options?: ProjectionSelection): MappingQueryResult;
+export function mapVirtualRange(document: VirtualDocument, range: OffsetRange, options?: ProjectionSelection): MappingQueryResult;
+export function mapSourceOffset(document: VirtualDocument, uri: string, offset: number, options?: ProjectionSelection): MappingQueryResult;
+export function mapSourceRange(document: VirtualDocument, uri: string, range: OffsetRange, options?: ProjectionSelection): MappingQueryResult;
+export function validateProjectionSegments(text: string, segments?: readonly ProjectionSegment[]): readonly Array<{ code: string; message: string }>;
+export function sameProjectionMapping(left: ProjectionSegment, right: ProjectionSegment): boolean;
+export function generatedContext(document: VirtualDocument, occurrenceId: OccurrenceId, options?: GeneratedContextOptions): GeneratedContextResult;
+export function navigateGeneratedSelection(document: VirtualDocument, range: OffsetRange, options?: ProjectionSelection): MappingQueryResult;
+export function createProjectionService(options?: ProjectionServiceOptions): ProjectionService;
+export function createProjectionTextChange(previousText: string, nextText: string, options?: { minimumReuseRatio?: number }): ProjectionTextChange;
+
+export type TransformSpanMode = "copy" | "mapped" | "inserted" | "removed";
+export interface TransformOffsetSpan { input: OffsetRange; output: OffsetRange; mode: TransformSpanMode; }
+export interface OffsetMap {
+  kind: "offset";
+  name: string;
+  inputLength: number;
+  outputLength: number;
+  spans: readonly TransformOffsetSpan[];
+}
+export interface SourceMapPoint {
+  generated: { line: number; column: number };
+  source?: string;
+  original?: { line: number; column: number };
+  name?: string;
+}
+export interface NormalizedSourceMap {
+  kind: "source-map";
+  sourceRoot?: string;
+  sources: readonly string[];
+  sourcesContent: readonly (string | null)[];
+  entries: readonly SourceMapPoint[];
+}
+export type TransformMappingCapability =
+  | { kind: "identity" }
+  | OffsetMap
+  | { kind: "source-map"; entries: readonly SourceMapPoint[] }
+  | { kind: "opaque"; anchor?: SourceLocation };
+export interface OffsetTransformResult { ok: true; text: string; map: OffsetMap; }
+
+export function identityTransformMap(input: string | number): OffsetMap | { kind: "invalid"; reason: string };
+export function createIndentOffsetMap(input: string, count?: number): OffsetTransformResult | { ok: false; reason: string };
+export function createDedentOffsetMap(input: string): (OffsetTransformResult & { amount: number }) | { ok: false; reason: string };
+export function createEolOffsetMap(input: string, eol?: "\n" | "\r\n"): OffsetTransformResult | { ok: false; reason: string };
+export function validateTransformMapping(mapping: TransformMappingCapability): { ok: boolean; reason?: string; index?: number };
+export function composeOffsetMaps(...maps: Array<OffsetMap | readonly OffsetMap[]>): { ok: true; map: OffsetMap } | { ok: false; reason: string };
+export function mapTransformOffset(mapping: OffsetMap, offset: number, options?: { direction?: "output-to-input" | "input-to-output"; affinity?: Affinity }): { ok: boolean; reason?: string; matches: readonly number[] };
+export function opaqueTransformMap(anchor?: SourceLocation): { kind: "opaque"; anchor?: SourceLocation };
+export function stageCapabilities(stage: ProjectionStage, overrides?: Partial<ProjectionCapabilities>): ProjectionCapabilities;
+export function validateAnalysisTransform(descriptor: { pure?: boolean; effect?: unknown; effects?: readonly unknown[]; authorities?: readonly unknown[]; mapping?: TransformMappingCapability; map?: TransformMappingCapability }): { ok: boolean; reason?: string };
+export function normalizeSourceMap(sourceMap: Record<string, any>): { ok: true; map: NormalizedSourceMap } | { ok: false; reason: string };
+export function applyTransformMap(document: VirtualDocument, outputText: string, capability: TransformMappingCapability | { map: TransformMappingCapability }, options?: {
+  signal?: AbortSignal;
+  inputSource?: string;
+  transformSource?: SourceLocation;
+  transformChain?: readonly TransformStep[];
+  name?: string;
+  stage?: ProjectionStage;
+  languageId?: string;
+  projectionId?: ProjectionId;
+  uri?: string;
+  path?: string;
+  version?: number;
+  capabilities?: Partial<ProjectionCapabilities>;
+}): { ok: true; document: VirtualDocument } | { ok: false; reason: string };
+
+export const MAPPING_KINDS: readonly MappingKind[];
+export const PROJECTION_STAGES: readonly ProjectionStage[];
+export const POSITION_ENCODINGS: readonly PositionEncoding[];

package/src/index.js

@@ -0,0 +1,68 @@
+export {
+  createProjectionId,
+  createVirtualUri,
+  buildVirtualDocument,
+  projectionInputHash
+} from "./builder.js";
+
+export {
+  createLineIndex,
+  positionAt,
+  offsetAt,
+  lineRangeAt,
+  lineWindow
+} from "./line-index.js";
+
+export {
+  buildProjectionIndexes,
+  coalesceProjectionSegments,
+  mapVirtualOffset,
+  mapVirtualRange,
+  mapSourceOffset,
+  mapSourceRange,
+  validateProjectionSegments,
+  sameProjectionMapping
+} from "./mapping.js";
+
+export {
+  generatedContext,
+  navigateGeneratedSelection
+} from "./context.js";
+
+export {
+  ProjectionService,
+  createProjectionService,
+  createProjectionTextChange
+} from "./service.js";
+
+export {
+  identityTransformMap,
+  createIndentOffsetMap,
+  createDedentOffsetMap,
+  createEolOffsetMap,
+  validateTransformMapping,
+  composeOffsetMaps,
+  mapTransformOffset,
+  opaqueTransformMap,
+  normalizeSourceMap,
+  applyTransformMap,
+  stageCapabilities,
+  validateAnalysisTransform
+} from "./transforms.js";
+
+export const MAPPING_KINDS = Object.freeze([
+  "exact",
+  "anchored",
+  "transformed",
+  "opaque",
+  "synthetic"
+]);
+
+export const PROJECTION_STAGES = Object.freeze([
+  "authoring",
+  "assembled",
+  "transformed",
+  "emitted"
+]);
+
+export const POSITION_ENCODINGS = Object.freeze(["utf-8", "utf-16", "utf-32"]);

package/src/internal.js

@@ -0,0 +1,163 @@
+export const mappingKinds = new Set([
+  "exact",
+  "anchored",
+  "transformed",
+  "opaque",
+  "synthetic"
+]);
+
+export const projectionStages = new Set([
+  "authoring",
+  "assembled",
+  "transformed",
+  "emitted"
+]);
+
+export const affinities = new Set(["left", "right", "none"]);
+
+export const isInteger = (value) => Number.isInteger(value);
+
+export const validOffsetRange = (range, { allowEmpty = true } = {}) =>
+  range !== null && typeof range === "object" &&
+  isInteger(range.start) && range.start >= 0 &&
+  isInteger(range.end) && range.end >= range.start &&
+  (allowEmpty || range.end > range.start);
+
+export const clone = (value) => {
+  if (value === undefined || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map(clone);
+  return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, clone(child)]));
+};
+
+export const deepFreeze = (value, seen = new Set()) => {
+  if (value === null || typeof value !== "object" || seen.has(value)) return value;
+  seen.add(value);
+  for (const child of Object.values(value)) deepFreeze(child, seen);
+  return Object.freeze(value);
+};
+
+const compareText = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+
+export const stableStringify = (value) => {
+  const visit = (entry) => {
+    if (entry === null || typeof entry !== "object") return JSON.stringify(entry);
+    if (Array.isArray(entry)) return "[" + entry.map(visit).join(",") + "]";
+    return "{" + Object.keys(entry).sort(compareText)
+      .map((key) => JSON.stringify(key) + ":" + visit(entry[key]))
+      .join(",") + "}";
+  };
+  return visit(value);
+};
+
+/** A deterministic, portable content hash. This is an identity checksum, not cryptography. */
+export const stableHash = (value) => {
+  const text = typeof value === "string" ? value : stableStringify(value);
+  let first = 2166136261;
+  let second = 2246822519;
+  for (let index = 0; index < text.length; index += 1) {
+    const code = text.charCodeAt(index);
+    first ^= code;
+    first = Math.imul(first, 16777619);
+    second ^= code + (index & 255);
+    second = Math.imul(second, 3266489917);
+  }
+  return (first >>> 0).toString(16).padStart(8, "0") +
+    (second >>> 0).toString(16).padStart(8, "0");
+};
+
+export const abortError = (message = "Projection operation was aborted.") => {
+  const error = new Error(message);
+  error.name = "AbortError";
+  return error;
+};
+
+export const throwIfAborted = (signal) => {
+  if (signal?.aborted) throw signal.reason?.name === "AbortError"
+    ? signal.reason
+    : abortError(typeof signal.reason === "string" ? signal.reason : undefined);
+};
+
+export const sourceOffset = (position) => isInteger(position) ? position : position?.offset;
+
+export const sourceRangeOffsets = (source) => {
+  const range = source?.range ?? source;
+  const start = sourceOffset(range?.start);
+  const end = sourceOffset(range?.end);
+  return isInteger(start) && isInteger(end) && start >= 0 && end >= start
+    ? { start, end }
+    : null;
+};
+
+export const sourceLocation = (source) => {
+  if (!source || typeof source.uri !== "string") return undefined;
+  const offsets = sourceRangeOffsets(source);
+  if (!offsets) return undefined;
+  const start = source.range?.start ?? { line: 0, column: 0, offset: offsets.start };
+  const end = source.range?.end ?? { line: 0, column: 0, offset: offsets.end };
+  return clone({
+    uri: source.uri,
+    range: {
+      start: {
+        line: isInteger(start.line) ? start.line : 0,
+        column: isInteger(start.column) ? start.column : 0,
+        offset: offsets.start
+      },
+      end: {
+        line: isInteger(end.line) ? end.line : 0,
+        column: isInteger(end.column) ? end.column : 0,
+        offset: offsets.end
+      }
+    }
+  });
+};
+
+export const advancePosition = (start, text, count) => {
+  let line = start.line;
+  let column = start.column;
+  for (let index = 0; index < count; index += 1) {
+    if (text[index] === "\n") {
+      line += 1;
+      column = 0;
+    } else {
+      column += 1;
+    }
+  }
+  return { line, column, offset: start.offset + count };
+};
+
+export const sliceSourceLocation = (source, text, start, end) => {
+  const normalized = sourceLocation(source);
+  if (!normalized) return undefined;
+  return {
+    uri: normalized.uri,
+    range: {
+      start: advancePosition(normalized.range.start, text, start),
+      end: advancePosition(normalized.range.start, text, end)
+    }
+  };
+};
+
+export const sameSourceLocation = (left, right) => stableStringify(left) === stableStringify(right);
+
+export const rangesOverlap = (left, right, { includeBoundary = false } = {}) =>
+  includeBoundary
+    ? left.start <= right.end && right.start <= left.end
+    : left.start < right.end && right.start < left.end;
+
+export const containsOffset = (range, offset, affinity = "none") => {
+  if (range.start === range.end) return offset === range.start;
+  if (offset > range.start && offset < range.end) return true;
+  if (offset === range.start) return affinity !== "left";
+  if (offset === range.end) return affinity !== "right";
+  return false;
+};
+
+export const encodeUriPart = (value) => encodeURIComponent(String(value));
+
+export const encodeVirtualPath = (value) => String(value).split("/")
+  .map((part) => encodeURIComponent(part))
+  .join("/");
+
+export const defaultCapabilities = (stage) => deepFreeze(stage === "emitted"
+  ? { navigation: true, diagnostics: true, completion: false, writableEdits: false }
+  : { navigation: true, diagnostics: true, completion: true, writableEdits: true });

package/src/line-index.js

@@ -0,0 +1,130 @@
+import { deepFreeze, isInteger } from "./internal.js";
+
+const encodings = new Set(["utf-8", "utf-16", "utf-32"]);
+
+const unitsFor = (text, encoding) => {
+  if (encoding === "utf-16") return text.length;
+  let units = 0;
+  for (const character of text) {
+    if (encoding === "utf-32") units += 1;
+    else {
+      const code = character.codePointAt(0);
+      units += code <= 0x7f ? 1 : code <= 0x7ff ? 2 : code <= 0xffff ? 3 : 4;
+    }
+  }
+  return units;
+};
+
+const contentEnd = (index, line) => {
+  const start = index.lineStarts[line];
+  const next = index.lineStarts[line + 1] ?? index.text.length;
+  let end = next;
+  if (end > start && index.text[end - 1] === "\n") end -= 1;
+  if (end > start && index.text[end - 1] === "\r") end -= 1;
+  return end;
+};
+
+export const createLineIndex = (text = "") => {
+  if (typeof text !== "string") text = String(text ?? "");
+  const lineStarts = [0];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "\n") lineStarts.push(index + 1);
+  }
+  return deepFreeze({ text, textLength: text.length, lineStarts });
+};
+
+const lineAt = (index, offset) => {
+  let low = 0;
+  let high = index.lineStarts.length;
+  while (low + 1 < high) {
+    const middle = (low + high) >>> 1;
+    if (index.lineStarts[middle] <= offset) low = middle;
+    else high = middle;
+  }
+  return low;
+};
+
+export const positionAt = (index, offset, encoding = "utf-16") => {
+  if (!index || typeof index.text !== "string" || !isInteger(offset) ||
+      offset < 0 || offset > index.text.length || !encodings.has(encoding)) {
+    return { ok: false, reason: "invalid-position" };
+  }
+  const line = lineAt(index, offset);
+  const end = contentEnd(index, line);
+  const safeOffset = Math.min(offset, end);
+  return {
+    ok: true,
+    position: {
+      line,
+      character: unitsFor(index.text.slice(index.lineStarts[line], safeOffset), encoding),
+      offset
+    }
+  };
+};
+
+export const offsetAt = (index, position, encoding = "utf-16") => {
+  if (!index || typeof index.text !== "string" || !position ||
+      !isInteger(position.line) || position.line < 0 ||
+      !isInteger(position.character) || position.character < 0 ||
+      position.line >= index.lineStarts.length || !encodings.has(encoding)) {
+    return { ok: false, reason: "invalid-position" };
+  }
+  const start = index.lineStarts[position.line];
+  const end = contentEnd(index, position.line);
+  if (position.character === 0) return { ok: true, offset: start };
+  if (encoding === "utf-16") {
+    if (position.character > end - start) return { ok: false, reason: "character-out-of-range" };
+    const offset = start + position.character;
+    if (offset > start && offset < end) {
+      const previous = index.text.charCodeAt(offset - 1);
+      const current = index.text.charCodeAt(offset);
+      if (previous >= 0xd800 && previous <= 0xdbff && current >= 0xdc00 && current <= 0xdfff) {
+        return { ok: false, reason: "split-character" };
+      }
+    }
+    return { ok: true, offset };
+  }
+
+  let units = 0;
+  let offset = start;
+  for (const character of index.text.slice(start, end)) {
+    const width = character.length;
+    const next = unitsFor(character, encoding);
+    if (units + next > position.character) return { ok: false, reason: "split-character" };
+    units += next;
+    offset += width;
+    if (units === position.character) return { ok: true, offset };
+  }
+  return { ok: false, reason: "character-out-of-range" };
+};
+
+export const lineRangeAt = (index, line) => {
+  if (!index || !isInteger(line) || line < 0 || line >= index.lineStarts.length) {
+    return { ok: false, reason: "invalid-line" };
+  }
+  return {
+    ok: true,
+    range: {
+      start: index.lineStarts[line],
+      end: index.lineStarts[line + 1] ?? index.text.length
+    }
+  };
+};
+
+export const lineWindow = (index, range, surroundingLines = 3) => {
+  if (!index || !range || !isInteger(range.start) || !isInteger(range.end) ||
+      range.start < 0 || range.end < range.start || range.end > index.text.length) {
+    return { ok: false, reason: "invalid-range" };
+  }
+  const count = isInteger(surroundingLines) && surroundingLines >= 0 ? surroundingLines : 3;
+  const first = Math.max(0, lineAt(index, range.start) - count);
+  const lastOffset = range.end > range.start ? range.end - 1 : range.end;
+  const last = Math.min(index.lineStarts.length - 1, lineAt(index, lastOffset) + count);
+  return {
+    ok: true,
+    range: {
+      start: index.lineStarts[first],
+      end: index.lineStarts[last + 1] ?? index.text.length
+    }
+  };
+};