@pieceful/ravel-language-service 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Taylor
+
+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,180 @@
+# `@pieceful/ravel-language-service`
+
+Editor-neutral routing between authored [Ravel](https://github.com/jostylr/ravel) locations, virtual projections,
+and native target-language bridges. It also classifies generated workspace
+edits before an editor host is allowed to modify authored documents.
+
+The package uses absolute UTF-16 offsets at its portable boundary. An editor or
+LSP host converts line/character positions with the projection line indexes.
+It does not execute Ravel effects and never writes source, deliverables, or
+shadow files.
+
+## Request routing
+
+```js
+import { createLanguageRouter } from "@pieceful/ravel-language-service";
+
+const router = createLanguageRouter({
+  projectionService,
+  bridges: [typescriptBridge],
+  trace: (event) => telemetry.event(event),
+});
+
+await router.update(snapshot, abortSignal);
+
+const response = await router.request(
+  "completion",
+  { uri: "guide.md", offset: 120 },
+  {
+    targetId: "web",
+    artifactId: "dist/app.ts",
+    request: { options: { includeCompletionsForModuleExports: true } },
+  },
+  abortSignal,
+);
+
+if (response.status === "ok") {
+  showCompletions(response.result.items);
+}
+```
+
+For a selected source location the router:
+
+1. finds every matching projection occurrence;
+2. selects a target, artifact, stage, and optional occurrence;
+3. synchronizes all same-target, same-stage documents supported by the bridge;
+4. sends only the generated-document contract to the bridge; and
+5. maps locations and ranges back to authored source while retaining generated
+   context on the normalized result.
+
+The bridge never receives provenance maps, authored source text, source line
+indexes, or source versions.
+
+### Ambiguity is a host decision
+
+If a source position occurs in multiple targets and neither `targetId` nor a
+matching `defaultTargetId` selects one, the response is
+`{ status: "target-required", candidates }`. Multiple artifacts in the chosen
+target also return `target-required` until the host supplies `artifactId`;
+there is no silent first-artifact fallback. Use `listTargets()` to populate a
+picker and persist only a deliberate host/user choice. `stage` and
+`occurrenceId` can further pin the generated context.
+
+Several exact occurrences remaining in one target and artifact also return
+`target-required`, with `ambiguityKind: "occurrence"`, until the host supplies
+the selected `projectionId`/`occurrenceId`. Duplicate mapping candidates are
+collapsed only when their routing context is identical; generated text
+equality is not treated as semantic equivalence.
+
+Other non-throwing statuses are `unmapped`, `exact-mapping-required`,
+`bridge-unavailable`, and `capability-unavailable`. Completion, completion
+details, signature help, prepare-rename, and rename require an exact cursor
+mapping. Navigation requests can retain coarser generated context.
+
+### Cancellation, versions, and failures
+
+Pass an `AbortSignal` through both `update()` and `request()`. The router does
+not publish a superseded projection update, forwards cancellation to bridge
+open/change/request work, and checks cancellation again before returning.
+After a native response, it verifies that the selected projection version is
+still current. A stale response throws retryable `BRIDGE_STALE_DOCUMENT`
+instead of being mapped into the new snapshot.
+
+The current router serializes each complete request against projection updates:
+candidate selection, compatible-document synchronization, native execution,
+stale validation, and reverse mapping share one consistency boundary.
+Per-bridge/per-document queues prevent duplicate or out-of-order
+open/change/close operations. A queued caller can still observe cancellation
+promptly; its already-enqueued operation stays ordered and checks the same
+signal before doing work.
+
+A retryable bridge error is retried once by default when the bridge implements
+`restart()`; set `maximumRetries` in request options to change that bound.
+Cancellation is never treated as a crash and never restarts the bridge.
+Capability and routing outcomes use the statuses above. Lifecycle, native, and
+stale failures throw structured `LanguageBridgeError` values for the host to
+surface or suppress deliberately.
+
+Call `dispose()` to dispose registered bridges and forget synchronized virtual
+documents. `registerBridge()` returns an unregister function for dynamic host
+integrations.
+
+## Safe workspace-edit policy
+
+Native rename and completion code actions are never directly applicable.
+`router.request()` attaches `classifiedEdit` to those responses, or a host can
+call `classifyWorkspaceEdit()` directly:
+
+```js
+import {
+  classifyWorkspaceEdit,
+  validateSourceEditVersions,
+} from "@pieceful/ravel-language-service";
+
+const classified = classifyWorkspaceEdit(generatedWorkspaceEdit, {
+  projectionService,
+  sourceVersions: new Map([["guide.md", 17]]),
+  isWritableSource(uri) {
+    // Canonicalize the URI, resolve symlinks, and check an explicit workspace
+    // allowlist here. A string-prefix check is not sufficient.
+    return writableSourceUris.has(canonicalSourceUri(uri));
+  },
+  limits: {
+    documents: 32,
+    edits: 2_000,
+    replacementTextCodeUnits: 250_000,
+  },
+});
+
+if (classified.applicable) {
+  const versions = currentOpenDocumentVersions();
+  const checked = validateSourceEditVersions(classified.sourceEdit, versions);
+  if (checked.valid) applyAtomically(classified.sourceEdit);
+}
+```
+
+Automatic application is fail-closed. Every edit must:
+
+- target a currently known virtual document and, when supplied, its current
+  projection version;
+- map to exactly one `exact`/`identity` authored range;
+- have both a writable mapping and a projection stage that allows writable
+  edits;
+- pass the host's `isWritableSource(uri)` allowlist; and
+- carry a known, non-negative current authored version from `sourceVersions`.
+
+Completion replacement spans and prepare-rename ranges are reverse-mapped only
+through the projection occurrence selected for the request. The router exposes
+an authored primary range only when that context produces one unique writable
+`exact`/`identity` destination; zero or several destinations remain
+generated-only, so a host cannot accidentally apply a plausible range from a
+sibling expansion.
+
+The callback is the security boundary for write scope. It should compare
+canonical paths/URIs against explicit workspace roots and account for symlinks,
+case rules, and URI encoding. Omitting either the callback or a source version
+rejects the edit. Immediately before applying, call
+`validateSourceEditVersions()` with freshly read versions and apply all
+documents atomically; a missing or changed version makes validation fail.
+
+Classification outcomes are:
+
+| Classification | Meaning                                                                                                                                                        | Host behavior                                                                    |
+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `automatic`    | Every entry passed all exactness, writability, version, conflict, and size checks.                                                                             | May apply only when `applicable === true` and final version validation succeeds. |
+| `preview`      | Provenance exists but is ambiguous, anchored, transformed, or otherwise non-exact.                                                                             | Show context/preview; do not apply the returned partial edit set.                |
+| `action`       | Synthetic text can be routed only through an explicit `importDestination` policy.                                                                              | Offer a separate, host-defined action; do not treat it as a text edit.           |
+| `rejected`     | The proposal is stale, opaque, synthetic without policy, unmapped, outside the allowlist, conflicting, malformed, oversized, or contains a resource operation. | Do not apply. Surface a safe reason when useful.                                 |
+
+The overall classification is the strictest entry. Even if `sourceEdit`
+contains individually exact entries, never partially apply it when the overall
+classification is not `automatic`. Identical edits caused by repeated
+expansion are deduplicated; overlapping non-identical authored edits are
+rejected. Generated create/rename/delete operations are always rejected.
+
+Default limits are 128 documents, 5,000 edits, and 1,000,000 replacement-text
+UTF-16 code units. Hosts can lower these positive limits. Limits bound proposal
+classification, not native service execution, so adapters should enforce their
+own resource budgets too.
+
+MIT © James Taylor

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@pieceful/ravel-language-service",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Source-mapped language request routing and safe edit classification for Ravel.",
+  "license": "MIT",
+  "author": "James Taylor",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jostylr/ravel.git",
+    "directory": "packages/language-service"
+  },
+  "bugs": {
+    "url": "https://github.com/jostylr/ravel/issues"
+  },
+  "homepage": "https://ravel.jostylr.com/",
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "ravel",
+    "literate-programming",
+    "language-service",
+    "lsp",
+    "source-map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./edits": {
+      "types": "./src/edits.d.ts",
+      "default": "./src/edits.js"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@pieceful/ravel-core": "0.2.0",
+    "@pieceful/ravel-language-bridge": "0.2.0",
+    "@pieceful/ravel-projection": "0.2.0"
+  }
+}

package/src/edits.d.ts

@@ -0,0 +1,29 @@
+export interface OffsetRange { start: number; end: number; }
+export interface SourceTextEdit { range: OffsetRange; text: string; }
+export interface SourceDocumentEdit {
+  uri: string;
+  version?: number;
+  edits: SourceTextEdit[];
+}
+export type EditClassification = "automatic" | "preview" | "action" | "rejected";
+export interface ClassifiedWorkspaceEdit {
+  classification: EditClassification;
+  applicable: boolean;
+  entries: Array<Record<string, unknown>>;
+  sourceEdit: { documents: SourceDocumentEdit[] };
+}
+export function classifyWorkspaceEdit(workspaceEdit: unknown, options: {
+  projectionService: Record<string, unknown>;
+  sourceVersions?: Map<string, number> | Record<string, number>;
+  isWritableSource?: (uri: string) => boolean;
+  importDestination?: unknown;
+  limits?: {
+    documents?: number;
+    edits?: number;
+    replacementTextCodeUnits?: number;
+  };
+}): ClassifiedWorkspaceEdit;
+export function validateSourceEditVersions(
+  sourceEdit: { documents?: SourceDocumentEdit[] },
+  currentVersions: Map<string, number> | Record<string, number>
+): { valid: boolean; stale: Array<{ uri: string; expected: number; actual?: number }> };

package/src/edits.js

@@ -0,0 +1,397 @@
+const classificationRank = Object.freeze({
+  automatic: 0,
+  preview: 1,
+  action: 2,
+  rejected: 3
+});
+
+const rangeValue = (value) => {
+  if (Number.isInteger(value)) return value;
+  if (Number.isInteger(value?.offset)) return value.offset;
+  return undefined;
+};
+
+const normalizeRange = (range) => {
+  const start = rangeValue(range?.start);
+  const end = rangeValue(range?.end);
+  return Number.isInteger(start) && Number.isInteger(end) && start >= 0 && end >= start
+    ? { start, end }
+    : null;
+};
+
+const normalizedTextEdit = (edit) => {
+  const range = normalizeRange(edit?.range);
+  const text = edit?.newText ?? edit?.text;
+  if (!range || typeof text !== "string") return null;
+  return { range, text };
+};
+
+const documentEdits = (workspaceEdit) => {
+  const documents = [];
+  if (workspaceEdit?.changes && !Array.isArray(workspaceEdit.changes)) {
+    for (const [uri, edits] of Object.entries(workspaceEdit.changes)) {
+      documents.push({ uri, edits });
+    }
+  }
+  for (const change of workspaceEdit?.documentChanges ?? workspaceEdit?.documents ?? []) {
+    if (change?.kind === "create" || change?.kind === "rename" || change?.kind === "delete") {
+      documents.push({ resourceOperation: change });
+      continue;
+    }
+    documents.push({
+      uri: change?.textDocument?.uri ?? change?.uri,
+      version: change?.textDocument?.version ?? change?.version,
+      edits: change?.edits
+    });
+  }
+  return documents;
+};
+
+const projectionForUri = (service, uri) => {
+  if (typeof service?.getProjectionByUri === "function") {
+    return service.getProjectionByUri(uri);
+  }
+  if (typeof service?.listProjections === "function") {
+    return service.listProjections().find((entry) => entry.uri === uri);
+  }
+  if (service?.projections instanceof Map) {
+    return [...service.projections.values()].find((entry) => entry.uri === uri);
+  }
+  return undefined;
+};
+
+const sourceFromMatch = (match) => {
+  const source = match?.source ?? match?.sourceRange ?? match;
+  const uri = source?.uri ?? match?.uri;
+  const range = normalizeRange(source?.range ?? source);
+  return typeof uri === "string" && range ? { uri, range } : null;
+};
+
+const mappingKind = (match) =>
+  match?.kind ?? match?.mappingKind ?? match?.quality ?? match?.precision;
+
+const exactMapping = (match) => ["exact", "identity"].includes(mappingKind(match));
+
+const sourceVersionFor = (sourceVersions, uri) =>
+  sourceVersions?.get?.(uri) ?? sourceVersions?.[uri];
+
+const classifyOne = (service, projection, edit, options) => {
+  const mapped = typeof service?.toSource === "function"
+    ? service.toSource(projection.id, edit.range)
+    : [];
+  const matches = Array.isArray(mapped) ? mapped : mapped ? [mapped] : [];
+  const exact = matches.filter((match) => exactMapping(match) && sourceFromMatch(match));
+
+  if (exact.length === 1) {
+    const source = sourceFromMatch(exact[0]);
+    const sourceEdit = { ...source, text: edit.text };
+    if (exact[0].writable === false || projection.capabilities?.writableEdits === false) {
+      return {
+        classification: "rejected",
+        reason: "non-writable-mapping",
+        message: "The exact mapping is not declared writable at this projection stage.",
+        projection,
+        virtualEdit: edit,
+        sourceEdit
+      };
+    }
+    if (typeof options.isWritableSource !== "function") {
+      return {
+        classification: "rejected",
+        reason: "writability-unverified",
+        message: "The host did not prove that the mapped source is writable.",
+        projection,
+        virtualEdit: edit,
+        sourceEdit
+      };
+    }
+    if (!options.isWritableSource(source.uri)) {
+      return {
+        classification: "rejected",
+        reason: "outside-workspace",
+        message: "The mapped source is outside the writable workspace.",
+        projection,
+        virtualEdit: edit,
+        sourceEdit
+      };
+    }
+    const version = sourceVersionFor(options.sourceVersions, source.uri);
+    if (!Number.isInteger(version) || version < 0) {
+      return {
+        classification: "rejected",
+        reason: "source-version-unavailable",
+        message: "The host cannot prove that the mapped source version is current.",
+        projection,
+        virtualEdit: edit,
+        sourceEdit
+      };
+    }
+    const projectedVersion = sourceVersionFor(projection.sourceVersions, source.uri);
+    if (!Number.isInteger(projectedVersion) || projectedVersion < 0 ||
+        projectedVersion !== version) {
+      return {
+        classification: "rejected",
+        reason: "projection-source-version-mismatch",
+        message: "The projection was not built from the host-current source version.",
+        projection,
+        virtualEdit: edit,
+        sourceEdit,
+        expectedVersion: projectedVersion,
+        actualVersion: version
+      };
+    }
+    return {
+      classification: "automatic",
+      projection,
+      virtualEdit: edit,
+      sourceEdit
+    };
+  }
+
+  if (exact.length > 1) {
+    return {
+      classification: "preview",
+      reason: "ambiguous-source",
+      message: "The generated edit maps exactly to more than one authored range.",
+      projection,
+      virtualEdit: edit,
+      matches
+    };
+  }
+
+  const qualities = new Set(matches.map(mappingKind).filter(Boolean));
+  if (qualities.has("synthetic") && options.importDestination) {
+    return {
+      classification: "action",
+      reason: "import-destination",
+      message: "The generated edit needs a declared imports or preamble destination.",
+      projection,
+      virtualEdit: edit,
+      action: {
+        kind: "route-import",
+        destination: options.importDestination,
+        text: edit.text
+      }
+    };
+  }
+  if (qualities.has("anchored") || qualities.has("transformed") ||
+      qualities.has("coarse")) {
+    return {
+      classification: "preview",
+      reason: "non-exact-mapping",
+      message: "The generated edit has provenance but no exact reversible character mapping.",
+      projection,
+      virtualEdit: edit,
+      matches
+    };
+  }
+  return {
+    classification: "rejected",
+    reason: qualities.has("opaque")
+      ? "opaque-transform"
+      : qualities.has("synthetic")
+        ? "synthetic-text"
+        : "unmapped-text",
+    message: qualities.has("opaque")
+      ? "The generated edit crosses an opaque transform."
+      : qualities.has("synthetic")
+        ? "Synthetic generated text has no authored destination."
+        : "The generated edit has no authored destination.",
+    projection,
+    virtualEdit: edit,
+    matches
+  };
+};
+
+const overlaps = (left, right) =>
+  left.range.start < right.range.end && right.range.start < left.range.end ||
+  left.range.start === left.range.end && right.range.start === right.range.end &&
+    left.range.start === right.range.start;
+
+const classifyConflicts = (entries) => {
+  const byUri = new Map();
+  for (const entry of entries) {
+    if (!entry.sourceEdit) continue;
+    const list = byUri.get(entry.sourceEdit.uri) ?? [];
+    list.push(entry);
+    byUri.set(entry.sourceEdit.uri, list);
+  }
+  for (const list of byUri.values()) {
+    list.sort((left, right) =>
+      left.sourceEdit.range.start - right.sourceEdit.range.start ||
+      left.sourceEdit.range.end - right.sourceEdit.range.end
+    );
+    for (let index = 1; index < list.length; index += 1) {
+      const previous = list[index - 1];
+      const current = list[index];
+      if (!overlaps(previous.sourceEdit, current.sourceEdit)) continue;
+      const identical = previous.sourceEdit.range.start === current.sourceEdit.range.start &&
+        previous.sourceEdit.range.end === current.sourceEdit.range.end &&
+        previous.sourceEdit.text === current.sourceEdit.text;
+      if (identical) {
+        current.duplicate = true;
+        continue;
+      }
+      for (const entry of [previous, current]) {
+        entry.classification = "rejected";
+        entry.reason = "conflicting-source-edits";
+        entry.message = "Generated edits request conflicting changes to one authored range.";
+      }
+    }
+  }
+};
+
+const sourceDocuments = (entries, sourceVersions) => {
+  const documents = new Map();
+  for (const entry of entries) {
+    if (!entry.sourceEdit || entry.duplicate || entry.classification === "rejected") continue;
+    const { uri, range, text } = entry.sourceEdit;
+    const document = documents.get(uri) ?? {
+      uri,
+      version: sourceVersions?.get?.(uri) ?? sourceVersions?.[uri],
+      edits: []
+    };
+    document.edits.push({ range, text });
+    documents.set(uri, document);
+  }
+  for (const document of documents.values()) {
+    document.edits.sort((left, right) =>
+      right.range.start - left.range.start || right.range.end - left.range.end
+    );
+  }
+  return [...documents.values()].sort((left, right) => left.uri.localeCompare(right.uri));
+};
+
+const positiveLimit = (value, fallback) =>
+  Number.isInteger(value) && value > 0 ? value : fallback;
+
+const rejectedWorkspaceEdit = (reason, message, details = {}) => ({
+  classification: "rejected",
+  applicable: false,
+  entries: [{ classification: "rejected", reason, message, ...details }],
+  sourceEdit: { documents: [] }
+});
+
+export const classifyWorkspaceEdit = (workspaceEdit, options = {}) => {
+  const service = options.projectionService;
+  if (!service) throw new TypeError("classifyWorkspaceEdit requires a projectionService.");
+  const limits = {
+    documents: positiveLimit(options.limits?.documents, 128),
+    edits: positiveLimit(options.limits?.edits, 5_000),
+    replacementTextCodeUnits: positiveLimit(
+      options.limits?.replacementTextCodeUnits,
+      1_000_000
+    )
+  };
+  const documents = documentEdits(workspaceEdit);
+  if (documents.length > limits.documents) {
+    return rejectedWorkspaceEdit(
+      "edit-limit-exceeded",
+      "The generated language tool returned too many edited documents.",
+      { limit: limits.documents, actual: documents.length }
+    );
+  }
+  let editCount = 0;
+  let replacementTextCodeUnits = 0;
+  for (const document of documents) {
+    if (document.resourceOperation) continue;
+    if (!Array.isArray(document.edits)) {
+      return rejectedWorkspaceEdit(
+        "invalid-edit",
+        "The generated language tool returned an invalid edit collection."
+      );
+    }
+    editCount += document.edits.length;
+    for (const edit of document.edits) {
+      const text = edit?.newText ?? edit?.text;
+      if (typeof text === "string") replacementTextCodeUnits += text.length;
+    }
+    if (editCount > limits.edits ||
+        replacementTextCodeUnits > limits.replacementTextCodeUnits) break;
+  }
+  if (editCount > limits.edits ||
+      replacementTextCodeUnits > limits.replacementTextCodeUnits) {
+    return rejectedWorkspaceEdit(
+      "edit-limit-exceeded",
+      "The generated language tool returned an oversized workspace edit.",
+      {
+        editLimit: limits.edits,
+        editCount,
+        replacementTextCodeUnitLimit: limits.replacementTextCodeUnits,
+        replacementTextCodeUnits
+      }
+    );
+  }
+  const entries = [];
+  for (const document of documents) {
+    if (document.resourceOperation) {
+      entries.push({
+        classification: "rejected",
+        reason: "resource-operation",
+        message: "Generated language tools cannot directly create, rename, or delete authored files.",
+        resourceOperation: document.resourceOperation
+      });
+      continue;
+    }
+    const projection = projectionForUri(service, document.uri);
+    if (!projection) {
+      entries.push({
+        classification: "rejected",
+        reason: "unknown-virtual-document",
+        message: "The edit targets an unknown or closed virtual document.",
+        uri: document.uri
+      });
+      continue;
+    }
+    if (document.version !== undefined && document.version !== null &&
+        document.version !== projection.version) {
+      entries.push({
+        classification: "rejected",
+        reason: "stale-projection",
+        message: "The edit targets a stale projection version.",
+        projection,
+        expectedVersion: projection.version,
+        actualVersion: document.version
+      });
+      continue;
+    }
+    for (const supplied of document.edits) {
+      const edit = normalizedTextEdit(supplied);
+      entries.push(edit
+        ? classifyOne(service, projection, edit, options)
+        : {
+            classification: "rejected",
+            reason: "invalid-edit",
+            message: "The generated language tool returned an invalid text edit.",
+            projection,
+            virtualEdit: supplied
+          });
+    }
+  }
+  classifyConflicts(entries);
+  const classification = entries.reduce((highest, entry) =>
+    classificationRank[entry.classification] > classificationRank[highest]
+      ? entry.classification
+      : highest,
+  "automatic");
+  return {
+    classification,
+    applicable: classification === "automatic",
+    entries,
+    sourceEdit: {
+      documents: sourceDocuments(entries, options.sourceVersions)
+    }
+  };
+};
+
+export const validateSourceEditVersions = (sourceEdit, currentVersions) => {
+  const stale = [];
+  for (const document of sourceEdit?.documents ?? []) {
+    const current = currentVersions?.get?.(document.uri) ?? currentVersions?.[document.uri];
+    if (!Number.isInteger(document.version) || document.version < 0 ||
+        current !== document.version) {
+      stale.push({ uri: document.uri, expected: document.version, actual: current });
+    }
+  }
+  return { valid: stale.length === 0, stale };
+};