@kalada/provider-routing 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,509 @@
+// src/composition-meter.ts
+var Meter = class {
+  work = 0;
+  depth = 0;
+  diagnostics = 0;
+  exhausted = false;
+  active = 0;
+  limits;
+  constructor(limits) {
+    this.limits = limits;
+  }
+  debit(key, amount, limit) {
+    if (this.exhausted || !Number.isSafeInteger(amount) || amount < 0 || this[key] + amount > limit) {
+      this.exhausted = true;
+      return false;
+    }
+    this[key] += amount;
+    return true;
+  }
+  charge(units) {
+    return this.debit("work", units, this.limits.work);
+  }
+  report(count) {
+    return this.debit("diagnostics", count, this.limits.diagnostics);
+  }
+  enter() {
+    if (this.exhausted || this.active >= this.limits.depth) {
+      this.exhausted = true;
+      return false;
+    }
+    this.active++;
+    this.depth = Math.max(this.depth, this.active);
+    return true;
+  }
+  leave() {
+    this.active--;
+  }
+};
+
+// src/composition-validation.ts
+var MAX_ID = 2048;
+var MAX_DIAGNOSTICS = 100;
+var id = (s) => typeof s === "string" && !!s.trim() && s.length <= MAX_ID;
+var offset = (n, length) => Number.isSafeInteger(n) && n >= 0 && n <= length;
+var range = (start, end) => Object.freeze({ start, end });
+function outcome(status, reason, document, diagnostics = []) {
+  return Object.freeze({
+    status,
+    reason,
+    snapshot: document,
+    diagnostics: Object.freeze([...diagnostics])
+  });
+}
+function checkpoint(request, document) {
+  if (request.isCancelled?.()) return "cancelled";
+  const original = request.snapshot;
+  if (original.uri !== document.uri || original.text !== document.text || original.version !== document.version || original.environmentGeneration !== document.environmentGeneration)
+    return "stale";
+  if (!request.isCurrent(document)) return "stale";
+}
+function declaredSlotsClear(slots, index, boundary, length) {
+  let previous = slots[index]?.start;
+  if (previous === void 0 || !offset(previous, length)) return false;
+  for (let i = index + 1; i < slots.length; i++) {
+    const start = slots[i]?.start;
+    if (start === void 0 || !offset(start, length)) return false;
+    if (start <= previous || start < boundary) return false;
+    previous = start;
+  }
+  return true;
+}
+function boundedExit(result, owner, start, length, maxStop) {
+  const stop = result?.stop;
+  return result?.owner === owner && offset(stop, length) && stop >= start && (maxStop === void 0 || stop <= maxStop) && result.range?.start === start && result.range?.end === stop && typeof result.reason === "string" && !!result.reason && (result.status === "valid" || result.status === "invalid" || result.status === "partial" || result.status === "unsupported");
+}
+function snapshot(input) {
+  const copy = Object.freeze({
+    uri: input?.uri,
+    text: input?.text,
+    version: input?.version,
+    environmentGeneration: input?.environmentGeneration
+  });
+  if (!id(copy.uri) || typeof copy.text !== "string" || !Number.isSafeInteger(copy.version) || copy.version < 0 || !id(copy.environmentGeneration))
+    throw new Error("Invalid snapshot");
+  return copy;
+}
+function profileCopy(p) {
+  const allowedGuests = [...p.allowedGuests];
+  if (p.version !== 1 || !id(p.hostLanguageId) || !id(p.position) || !id(p.open) || !id(p.close) || !allowedGuests.length || allowedGuests.some((guest) => !id(guest)) || new Set(allowedGuests).size !== allowedGuests.length || p.defaultGuest !== void 0 && !allowedGuests.includes(p.defaultGuest))
+    throw new Error("Invalid or ambiguous composition profile");
+  return Object.freeze({
+    version: 1,
+    hostLanguageId: p.hostLanguageId,
+    position: p.position,
+    open: p.open,
+    close: p.close,
+    defaultGuest: p.defaultGuest,
+    allowedGuests: Object.freeze(allowedGuests)
+  });
+}
+function diagnosticCopy(items, regionStart, stop, owner) {
+  if (!Array.isArray(items) || items.length > MAX_DIAGNOSTICS) return;
+  const result = [];
+  for (const item of items) {
+    const code = item?.code, start = item?.range?.start, end = item?.range?.end;
+    if (typeof code !== "string" || code.length > 128 || !/^[A-Z][A-Z0-9_]*$/u.test(code) || item?.owner !== owner || !offset(start, stop) || !offset(end, stop) || start < regionStart || end < start)
+      return;
+    result.push(Object.freeze({ owner, code, range: range(start, end) }));
+  }
+  return Object.freeze(result);
+}
+
+// src/composition-recovery.ts
+function clearBoundary(request, document, index, end) {
+  return declaredSlotsClear(request.slots, index, end, document.text.length);
+}
+function clearFailure(request, document, index, failed) {
+  if (!failed.attempt) return true;
+  const end = failed.safe ? failed.safe.stop + failed.safe.profile.close.length : failed.attempt.range.end;
+  return clearBoundary(request, document, index, end);
+}
+function recoveryFailure(request, document, index, failed, attempts, candidates, reason) {
+  if (["budget", "stale", "cancelled"].includes(failed.outcome.status))
+    return { outcome: failed.outcome };
+  if (!clearFailure(request, document, index, failed))
+    return { outcome: outcome("invalid", "OVERLAPPING_SLOT", document) };
+  if (failed.attempt) attempts.push(failed.attempt);
+  if (failed.safe && index + 1 < request.slots.length) return { safe: failed.safe };
+  return { outcome: partial(document, reason, attempts, candidates) };
+}
+function attempt(result, diagnostics) {
+  return Object.freeze({
+    owner: result.owner,
+    range: Object.freeze({ start: result.range.start, end: result.stop }),
+    status: result.status,
+    reason: result.reason,
+    diagnostics
+  });
+}
+function partial(document, reason, attempts, candidates) {
+  return Object.freeze({
+    status: "partial",
+    reason,
+    snapshot: document,
+    diagnostics: Object.freeze(attempts.flatMap((item) => item.diagnostics)),
+    attempts: Object.freeze([...attempts]),
+    candidates: Object.freeze([...candidates])
+  });
+}
+function connectorInput(document, meter, stop, start, next) {
+  return Object.freeze({
+    snapshot: document,
+    close: Object.freeze({ start: stop, end: start }),
+    nextSlot: Object.freeze({
+      position: next.position,
+      start: next.start,
+      maxStop: next.maxStop,
+      explicitGuest: next.explicitGuest
+    }),
+    meter
+  });
+}
+function connector(request, document, meter, stop, profile, next) {
+  const continuation = request.hostContinuation;
+  const start = stop + profile.close.length;
+  if (!continuation || typeof continuation.validate !== "function" || !Number.isSafeInteger(next?.start) || next.start < start || next.start > document.text.length)
+    return false;
+  if (!meter.enter()) return false;
+  let value;
+  const before = meter.work;
+  try {
+    value = continuation.validate(connectorInput(document, meter, stop, start, next));
+  } finally {
+    meter.leave();
+  }
+  const owner = value?.owner;
+  const range2 = value?.range;
+  const from = range2?.start;
+  const to = range2?.end;
+  return !meter.exhausted && owner === request.hostLanguageId && from === start && to === next.start && meter.work - before >= to - from;
+}
+
+// src/composition.ts
+var MAX_TEXT = 1e5;
+var MAX_WORK = 1e6;
+var MAX_DEPTH = 32;
+var MAX_DIAGNOSTICS2 = 100;
+function select(slot, host, profiles, guests) {
+  const profile = profiles.find((p) => p.hostLanguageId === host && p.position === slot.position);
+  if (!profile) return;
+  const chosen = slot.explicitGuest ?? profile.defaultGuest;
+  if (!chosen || !profile.allowedGuests.includes(chosen)) return;
+  const guest = guests.get(chosen);
+  return guest ? { profile, guest } : void 0;
+}
+function node(owner, start, end, children = [], subtree) {
+  return Object.freeze({
+    owner,
+    range: range(start, end),
+    children: Object.freeze([...children]),
+    subtree
+  });
+}
+function createCompositionRouter(profiles, providers) {
+  const registered = profiles.map(profileCopy);
+  const keys = registered.map((p) => `${p.hostLanguageId}\0${p.position}`);
+  if (new Set(keys).size !== keys.length) throw new Error("Overlapping host positions");
+  const guests = /* @__PURE__ */ new Map();
+  for (const provider of providers) {
+    const languageId = provider?.languageId, parse = provider?.parse;
+    if (!id(languageId) || typeof parse !== "function" || guests.has(languageId))
+      throw new Error("Invalid or duplicate guest");
+    guests.set(languageId, Object.freeze({ languageId, parse: parse.bind(provider) }));
+  }
+  return Object.freeze({
+    compose(request) {
+      const document = snapshot(request.snapshot);
+      const limits = Object.freeze({ ...request.limits });
+      if (!Number.isSafeInteger(limits.work) || limits.work < 1 || limits.work > MAX_WORK || !Number.isSafeInteger(limits.depth) || limits.depth < 1 || limits.depth > MAX_DEPTH || !Number.isSafeInteger(limits.diagnostics) || limits.diagnostics < 0 || limits.diagnostics > MAX_DIAGNOSTICS2)
+        throw new Error("Invalid budget");
+      const meter = request.meter ?? new Meter(limits);
+      try {
+        return compose(request, document, meter, registered, guests);
+      } catch {
+        return outcome("invalid", "COMPOSITION_FAILURE", document);
+      }
+    }
+  });
+}
+function compose(request, document, meter, profiles, guests) {
+  const state = checkpoint(request, document);
+  if (state) return outcome(state, state, document);
+  if (document.text.length > MAX_TEXT) return outcome("budget", "SOURCE_LIMIT", document);
+  if (!id(request.hostLanguageId) || !Array.isArray(request.slots) || request.slots.length > MAX_DIAGNOSTICS2)
+    return outcome("invalid", "INVALID_HOST", document);
+  if (!meter.enter()) return outcome("budget", "DEPTH_LIMIT", document);
+  try {
+    return walk(request, document, meter, profiles, guests);
+  } finally {
+    meter.leave();
+  }
+}
+function walk(request, document, meter, profiles, guests) {
+  const children = [];
+  let cursor = 0;
+  for (const [index, slot] of request.slots.entries()) {
+    const state = checkpoint(request, document);
+    if (state) return outcome(state, state, document);
+    if (!offset(slot?.start, document.text.length) || slot.start < cursor)
+      return outcome("invalid", "OVERLAPPING_SLOT", document);
+    const processed = processSlot(request, document, meter, profiles, guests, slot, cursor);
+    if ("outcome" in processed)
+      return walkFailure(request, document, meter, profiles, guests, index, processed);
+    const { start, stop, close, guest, subtree } = processed;
+    if (!clearBoundary(request, document, index, stop + close.length))
+      return outcome("invalid", "OVERLAPPING_SLOT", document);
+    if (slot.start > cursor) children.push(node(request.hostLanguageId, cursor, slot.start));
+    children.push(node(request.hostLanguageId, slot.start, start));
+    children.push(node(guest, start, stop, [], subtree));
+    cursor = stop + close.length;
+    children.push(node(request.hostLanguageId, stop, cursor));
+  }
+  return finishWalk(request, document, meter, children, cursor);
+}
+function walkFailure(request, document, meter, profiles, guests, index, failed) {
+  if (!clearFailure(request, document, index, failed))
+    return outcome("invalid", "OVERLAPPING_SLOT", document);
+  return failed.safe && request.hostContinuation && index + 1 < request.slots.length ? recover(request, document, meter, profiles, guests, index, failed) : failed.outcome;
+}
+function finishWalk(request, document, meter, children, cursor) {
+  if (!meter.charge(document.text.length - cursor) || meter.exhausted)
+    return outcome("budget", "WORK_LIMIT", document);
+  const state = checkpoint(request, document);
+  if (state) return outcome(state, state, document);
+  if (cursor < document.text.length)
+    children.push(node(request.hostLanguageId, cursor, document.text.length));
+  return Object.freeze({
+    status: "valid",
+    reason: "complete",
+    snapshot: document,
+    diagnostics: Object.freeze([]),
+    tree: node(request.hostLanguageId, 0, document.text.length, children)
+  });
+}
+function resumeSlot(request, document, meter, profiles, guests, slot, previous) {
+  const state = checkpoint(request, document);
+  if (state) return { outcome: outcome(state, state, document) };
+  if (!slot) return { outcome: outcome("invalid", "MISSING_SLOT", document) };
+  const entry = select(slot, request.hostLanguageId, profiles, guests);
+  if (!entry || !document.text.startsWith(entry.profile.open, slot.start))
+    return { outcome: outcome("invalid", "MISSING_NEXT_OPEN", document) };
+  if (!previous.closeCharged && !meter.charge(previous.profile.close.length))
+    return { outcome: outcome("budget", "WORK_OR_DIAGNOSTIC_LIMIT", document) };
+  if (!connector(request, document, meter, previous.stop, previous.profile, slot))
+    return {
+      outcome: outcome(meter.exhausted ? "budget" : "invalid", "CONNECTOR_REJECTED", document)
+    };
+  const after = checkpoint(request, document);
+  if (after) return { outcome: outcome(after, after, document) };
+  return processSlot(request, document, meter, profiles, guests, slot, slot.start);
+}
+function recover(request, document, meter, profiles, guests, index, failed) {
+  const attempts = [failed.attempt];
+  const candidates = [];
+  let previous = {
+    ...failed.safe,
+    closeCharged: false
+  };
+  for (let i = index + 1; i < request.slots.length; i++) {
+    const slot = request.slots[i];
+    const processed = resumeSlot(request, document, meter, profiles, guests, slot, previous);
+    if ("outcome" in processed) {
+      const decision = recoveryFailure(
+        request,
+        document,
+        i,
+        processed,
+        attempts,
+        candidates,
+        failed.outcome.reason
+      );
+      if (decision.outcome) return decision.outcome;
+      previous = { ...decision.safe, closeCharged: false };
+      continue;
+    }
+    if (!clearBoundary(request, document, i, processed.stop + processed.close.length))
+      return outcome("invalid", "OVERLAPPING_SLOT", document);
+    candidates.push(node(processed.guest, processed.start, processed.stop, [], processed.subtree));
+    previous = { stop: processed.stop, profile: processed.profile, closeCharged: true };
+  }
+  if (meter.exhausted) return outcome("budget", "WORK_LIMIT", document);
+  const state = checkpoint(request, document);
+  return state ? outcome(state, state, document) : partial(document, failed.outcome.reason, attempts, candidates);
+}
+function admit(result, entry, start, document, meter, maxStop, guestWork) {
+  const guestRange = result.range;
+  const value = {
+    owner: result.owner,
+    stop: result.stop,
+    range: { start: guestRange.start, end: guestRange.end },
+    reason: result.reason,
+    status: result.status,
+    diagnostics: result.diagnostics
+  };
+  if (!boundedExit(value, entry.guest.languageId, start, document.text.length, maxStop))
+    return { outcome: outcome("invalid", "INVALID_GUEST_EXIT", document) };
+  const copied = diagnosticCopy(value.diagnostics, start, value.stop, entry.guest.languageId);
+  if (!copied) return { outcome: outcome("invalid", "INVALID_GUEST_DIAGNOSTIC", document) };
+  if (!meter.report(copied.length) || meter.exhausted)
+    return { outcome: outcome("budget", "WORK_OR_DIAGNOSTIC_LIMIT", document) };
+  if (value.status !== "valid")
+    return {
+      outcome: outcome(value.status, value.reason, document, copied),
+      attempt: attempt(value, copied),
+      safe: value.status === "partial" && value.reason === "safe-host-close" && value.stop > start && guestWork >= value.stop - start && document.text.startsWith(entry.profile.close, value.stop) ? { stop: value.stop, profile: entry.profile } : void 0
+    };
+  return admitValid(result, value, copied, entry, start, document, meter, guestWork);
+}
+function admitValid(result, value, copied, entry, start, document, meter, guestWork) {
+  if (value.stop <= start || !document.text.startsWith(entry.profile.close, value.stop) || copied.length || value.reason !== "host-close" || !Number.isSafeInteger(guestWork) || guestWork < 1)
+    return { outcome: outcome("invalid", "INVALID_GUEST_EXIT", document) };
+  const subtree = result.subtree;
+  if (subtree === void 0)
+    return { outcome: outcome("invalid", "MISSING_GUEST_SUBTREE", document) };
+  if (!meter.charge(entry.profile.close.length))
+    return { outcome: outcome("budget", "WORK_OR_DIAGNOSTIC_LIMIT", document) };
+  return {
+    start,
+    stop: value.stop,
+    close: entry.profile.close,
+    profile: entry.profile,
+    guest: entry.guest.languageId,
+    subtree
+  };
+}
+function processSlot(request, document, meter, profiles, guests, slot, cursor) {
+  const entry = select(slot, request.hostLanguageId, profiles, guests);
+  if (!entry) return { outcome: outcome("unsupported", "UNDECLARED_GUEST_OR_POSITION", document) };
+  if (!document.text.startsWith(entry.profile.open, slot.start))
+    return { outcome: outcome("invalid", "MISSING_OPEN", document) };
+  const start = slot.start + entry.profile.open.length;
+  if (slot.maxStop !== void 0 && (!offset(slot.maxStop, document.text.length) || slot.maxStop < start))
+    return { outcome: outcome("invalid", "INVALID_MAX_STOP", document) };
+  if (!meter.charge(start - cursor) || !meter.enter())
+    return { outcome: outcome("budget", "WORK_OR_DEPTH_LIMIT", document) };
+  const workBefore = meter.work;
+  let result;
+  try {
+    result = entry.guest.parse(
+      Object.freeze({
+        snapshot: document,
+        start,
+        close: entry.profile.close,
+        context: slot.context && Object.freeze({
+          expectedType: slot.context.expectedType,
+          location: slot.context.location
+        }),
+        meter
+      })
+    );
+  } finally {
+    meter.leave();
+  }
+  const state = checkpoint(request, document);
+  if (state) return { outcome: outcome(state, state, document) };
+  if (meter.exhausted) return { outcome: outcome("budget", "GUEST_BUDGET", document) };
+  const work = meter.work - workBefore;
+  const admitted = admit(result, entry, start, document, meter, slot.maxStop, work);
+  const afterAdmission = checkpoint(request, document);
+  return afterAdmission ? { outcome: outcome(afterAdmission, afterAdmission, document) } : admitted;
+}
+
+// src/contracts.ts
+var COMPOSITION_CONTRACT_VERSION = 1;
+
+// src/index.ts
+var DIAGNOSTIC_CONTRACT_VERSION = 1;
+var MAX_TEXT2 = 1e5;
+var MAX_IDENTITY = 2048;
+var MAX_DIAGNOSTICS3 = 100;
+var MAX_CODE = 128;
+function invalid(code) {
+  return Object.freeze({
+    status: "invalid",
+    diagnostics: Object.freeze([
+      Object.freeze({ code, range: Object.freeze({ start: 0, end: 0 }) })
+    ])
+  });
+}
+function validDocument(value) {
+  return typeof value?.uri === "string" && value.uri.length > 0 && value.uri.length <= MAX_IDENTITY && typeof value.text === "string" && Number.isSafeInteger(value.version) && value.version >= 0 && typeof value.environmentGeneration === "string" && value.environmentGeneration.length > 0 && value.environmentGeneration.length <= MAX_IDENTITY;
+}
+function validDiagnostic(code, start, end, length) {
+  return /^[A-Z][A-Z0-9_]*$/u.test(code) && code.length <= MAX_CODE && Number.isSafeInteger(start) && Number.isSafeInteger(end) && start >= 0 && end >= start && end <= length;
+}
+function copyDiagnostic(item, length) {
+  const code = item?.code;
+  const range2 = item?.range;
+  const start = range2?.start;
+  const end = range2?.end;
+  if (typeof code !== "string" || typeof start !== "number" || typeof end !== "number" || !validDiagnostic(code, start, end, length))
+    return void 0;
+  return Object.freeze({ code, range: Object.freeze({ start, end }) });
+}
+function safeOutcome(value, length) {
+  const status = value?.status;
+  if (status === "unsupported") {
+    if ("diagnostics" in value) return invalid("PROVIDER_INVALID_RESULT");
+    return Object.freeze({ status: "unsupported" });
+  }
+  if (status !== "supported" && status !== "invalid") return invalid("PROVIDER_INVALID_RESULT");
+  const source = value.diagnostics;
+  if (!Array.isArray(source)) return invalid("PROVIDER_INVALID_RESULT");
+  const count = source.length;
+  if (!Number.isSafeInteger(count) || count < 0 || count > MAX_DIAGNOSTICS3)
+    return invalid("PROVIDER_INVALID_RESULT");
+  const diagnostics = [];
+  for (let index = 0; index < count; index++) {
+    const item = source[index];
+    const copied = copyDiagnostic(item, length);
+    if (!copied) return invalid("PROVIDER_INVALID_RESULT");
+    diagnostics.push(copied);
+  }
+  if (status === "supported" !== (diagnostics.length === 0))
+    return invalid("PROVIDER_INVALID_RESULT");
+  if (status === "supported")
+    return Object.freeze({ status: "supported", diagnostics: Object.freeze(diagnostics) });
+  return Object.freeze({ status: "invalid", diagnostics: Object.freeze(diagnostics) });
+}
+function createDiagnosticRouter(providers) {
+  const registered = /* @__PURE__ */ new Map();
+  for (const provider of providers) {
+    const languageId = provider?.languageId;
+    if (typeof languageId !== "string" || !languageId.trim())
+      throw new Error("Invalid language ID");
+    if (registered.has(languageId)) throw new Error("Duplicate language ID");
+    if (typeof provider.diagnose !== "function") throw new Error("Invalid provider");
+    registered.set(languageId, provider);
+  }
+  return Object.freeze({
+    diagnose(languageId, input) {
+      const provider = registered.get(languageId);
+      if (!provider) throw new Error("Unknown language ID");
+      const document = Object.freeze({
+        uri: input?.uri,
+        text: input?.text,
+        version: input?.version,
+        environmentGeneration: input?.environmentGeneration
+      });
+      if (!validDocument(document)) throw new Error("Invalid document identity");
+      let outcome2;
+      if (document.text.length > MAX_TEXT2) outcome2 = invalid("PROVIDER_SOURCE_LIMIT");
+      else {
+        try {
+          outcome2 = safeOutcome(provider.diagnose(document), document.text.length);
+        } catch {
+          outcome2 = invalid("PROVIDER_FAILURE");
+        }
+      }
+      return Object.freeze({ ...outcome2, languageId, document });
+    }
+  });
+}
+export {
+  COMPOSITION_CONTRACT_VERSION,
+  DIAGNOSTIC_CONTRACT_VERSION,
+  createCompositionRouter,
+  createDiagnosticRouter
+};

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@kalada/provider-routing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Experimental neutral whole-document diagnostic routing for Kalada consumers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/surikaterna/kalada",
+    "directory": "packages/provider-routing"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --target node22 --clean",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}