@suss/ir-core 0.34.0 → 0.34.1

package/dist/schemas.cjs

@@ -449,6 +449,38 @@ function pathAfterOrigin(text) {
   const cut = withoutOrigin.search(/[?#]/);
   return cut === -1 ? withoutOrigin : withoutOrigin.slice(0, cut);
 }
+var PRIVATE_SUFFIXES = [
+  "local",
+  "internal",
+  "localhost",
+  "lan",
+  "home.arpa",
+  "svc",
+  "test",
+  "example",
+  "invalid",
+  "example.com",
+  "example.net",
+  "example.org"
+];
+var PRIVATE_IPV4 = /^(?:127\.|10\.|192\.168\.|169\.254\.|172\.(?:1[6-9]|2\d|3[01])\.|0\.0\.0\.0$)/;
+function hostnameOf(host) {
+  const lower = host.toLowerCase();
+  const name = lower.startsWith("[") ? lower.slice(0, lower.indexOf("]") + 1) : lower.split(":")[0] ?? lower;
+  return name.replace(/\.$/, "");
+}
+function hostCanBeOwn(host) {
+  const name = hostnameOf(host);
+  if (name === "[::1]" || /^\[f[cd]/.test(name) || PRIVATE_IPV4.test(name)) {
+    return true;
+  }
+  if (!name.includes(".")) {
+    return true;
+  }
+  return PRIVATE_SUFFIXES.some(
+    (suffix) => name === suffix || name.endsWith(`.${suffix}`)
+  );
+}
 
 // src/semantics/pathPattern.ts
 var ONE = { kind: "one" };
@@ -499,14 +531,18 @@ function shapedItem(segment) {
       return ".*";
     }
     if (part.startsWith("{")) {
-      return "[^/]+";
+      return /[?*]\}$/.test(part) ? "[^/]*" : "[^/]+";
     }
     return escapedForRegex(part);
   }).join("");
+  const holes = segment.match(/\{[^}]*\}|\*/g) ?? [];
+  const text = segment.replace(/\{[^}]*\}|\*/g, "");
   return {
     kind: "shaped",
     shape: segment.replace(/\{[^}]*\}/g, "{}"),
-    test: new RegExp(`^${source}$`)
+    test: new RegExp(`^${source}$`),
+    bare: holes.every((hole) => hole === "*" || /[?*]\}$/.test(hole)) ? text : null,
+    textLength: text.length
   };
 }
 function itemsOf(segment) {
@@ -526,10 +562,35 @@ function segmentsOf(alternative) {
   const trimmed = alternative.startsWith("/") ? alternative.slice(1) : alternative;
   return trimmed === "" ? [] : trimmed.split("/");
 }
+function patternSegmentsOf(alternative) {
+  const segments = segmentsOf(alternative);
+  const first = segments[0];
+  const opensWithBaseUrl = !alternative.startsWith("/") && first !== void 0 && HOLE_SEGMENT.test(first);
+  return opensWithBaseUrl ? segments.slice(1) : segments;
+}
+function pathAfterBaseUrl(path) {
+  const segments = segmentsOf(path);
+  const first = segments[0];
+  if (path.startsWith("/") || first === void 0 || segments.length < 2 || !HOLE_SEGMENT.test(first)) {
+    return path;
+  }
+  return `/${segments.slice(1).join("/")}`;
+}
+var PATTERNS = /* @__PURE__ */ new Map();
+var PATTERN_CACHE_LIMIT = 5e4;
 function patternOf(path) {
-  return alternativesOf(path).map(
-    (alternative) => segmentsOf(alternative).flatMap(itemsOf)
+  const known = PATTERNS.get(path);
+  if (known !== void 0) {
+    return known;
+  }
+  const pattern = alternativesOf(path).map(
+    (alternative) => patternSegmentsOf(alternative).flatMap(itemsOf)
   );
+  if (PATTERNS.size >= PATTERN_CACHE_LIMIT) {
+    PATTERNS.clear();
+  }
+  PATTERNS.set(path, pattern);
+  return pattern;
 }
 function literalItemsOf(path) {
   return segmentsOf(path).map((text) => ({ kind: "text", text }));
@@ -608,17 +669,104 @@ function pathSpansShapes(path) {
 function countOf(items, kinds) {
   return items.filter((item) => kinds.includes(item.kind)).length;
 }
-function pathSpecificity(path) {
-  const alternatives = patternOf(path);
-  const ranks = alternatives.map((items) => [
+function readingSpecificity(items) {
+  return [
     countOf(items, ["text"]),
     countOf(items, ["shaped"]),
     -countOf(items, ["optional", "star"])
-  ]);
-  const loosest = ranks.reduce(
-    (low, rank) => compareRanks(rank, low) < 0 ? rank : low
+  ];
+}
+function segmentFit(route, request) {
+  if (!meetOnOneSegment(route, request)) {
+    return "apart";
+  }
+  if (request.kind === "text") {
+    if (route.kind === "text") {
+      return "stated";
+    }
+    return route.kind === "shaped" ? "shaped" : "free";
+  }
+  if (absorbsAnything(route)) {
+    return "free";
+  }
+  if (request.kind !== "shaped") {
+    return "guess";
+  }
+  if (route.kind === "shaped") {
+    return "free";
+  }
+  return route.kind === "text" && request.bare === route.text ? "stated" : "guess";
+}
+function shapedText(item) {
+  return item.kind === "shaped" ? item.textLength : 0;
+}
+function betterFit(a, b) {
+  return a === void 0 || compareRanks(b, a) > 0;
+}
+function bestFit(route, request) {
+  const width = request.length + 1;
+  const best = new Array((route.length + 1) * width);
+  best[0] = [0, 0];
+  const offer = (i, j, fit) => {
+    const at = i * width + j;
+    if (betterFit(best[at], fit)) {
+      best[at] = fit;
+    }
+  };
+  for (let reached = 0; reached <= route.length + request.length; reached += 1) {
+    for (let i = Math.max(0, reached - request.length); i <= Math.min(route.length, reached); i += 1) {
+      const j = reached - i;
+      const fit = best[i * width + j];
+      if (fit === void 0) {
+        continue;
+      }
+      const left = route[i];
+      const right = request[j];
+      if (left !== void 0 && skippable(left)) {
+        offer(i + 1, j, fit);
+      }
+      if (right !== void 0 && skippable(right)) {
+        offer(i, j + 1, fit);
+      }
+      if (left === void 0 || right === void 0) {
+        continue;
+      }
+      if (left.kind === "star" && right.kind === "star") {
+        continue;
+      }
+      const kind = segmentFit(left, right);
+      if (kind === "apart" || kind === "guess") {
+        continue;
+      }
+      offer(
+        left.kind === "star" ? i : i + 1,
+        right.kind === "star" ? j : j + 1,
+        [
+          fit[0] + (kind === "stated" ? 1 : 0),
+          fit[1] + (kind === "shaped" ? shapedText(left) : 0)
+        ]
+      );
+    }
+  }
+  return best[route.length * width + request.length] ?? null;
+}
+function requestRank(route, request) {
+  let found = null;
+  for (const routeItems of patternOf(route)) {
+    for (const requestItems of patternOf(request)) {
+      const fit = bestFit(routeItems, requestItems);
+      const rank = fit === null ? null : [...fit, ...readingSpecificity(routeItems)];
+      if (rank !== null && (found === null || compareRanks(rank, found) > 0)) {
+        found = rank;
+      }
+    }
+  }
+  return found;
+}
+function isCatchAll(route) {
+  return patternOf(route).some(
+    (items) => items.length > 0 && items.every(absorbsAnything) && items.some((item) => item.kind === "star")
   );
-  return [...loosest, 1 - alternatives.length];
 }
 function compareRanks(a, b) {
   const length = Math.max(a.length, b.length);
@@ -648,7 +796,18 @@ var RestSemanticsSchema = import_zod7.z.object({
    * here so the pairing layer can see them without unwrapping any
    * metadata. Absent or empty for an inferred source.
    */
-  declaredResponses: import_zod7.z.array(import_zod7.z.number()).optional()
+  declaredResponses: import_zod7.z.array(import_zod7.z.number()).optional(),
+  /**
+   * The host a client wrote in an absolute URL, with its port
+   * (`api.example.com:8443`). A piece suss could not read is written
+   * `{name}`. Absent for a relative URL and for a route.
+   */
+  host: import_zod7.z.string().min(1).optional(),
+  /**
+   * True for a route the framework also serves with `.{format}` after
+   * its path, the way Rails serves `/search.json` from `get "search"`.
+   */
+  optionalFormat: import_zod7.z.boolean().optional()
 });
 var OPENING_HOLE = /^\{([^{}]+)\}(.*)$/;
 function baseUrlReference(semantics) {
@@ -656,7 +815,10 @@ function baseUrlReference(semantics) {
   return label === void 0 ? null : referenceFromName(patternHole(label));
 }
 function normalizePath(path) {
-  let normalized = path.replace(/:([a-zA-Z_]\w*)([?+*]?)/g, "{$1$2}");
+  let normalized = withoutParameterConstraints(path).replace(
+    /:([a-zA-Z_]\w*)([?+*]?)/g,
+    "{$1$2}"
+  );
   if (normalized.length > 1 && normalized.endsWith("/")) {
     normalized = normalized.slice(0, -1);
   }
@@ -666,6 +828,46 @@ function normalizePath(path) {
   );
   return normalized;
 }
+function withoutParameterConstraints(path) {
+  let out = "";
+  let i = 0;
+  while (i < path.length) {
+    const name = /^:[a-zA-Z_]\w*\(/.exec(path.slice(i));
+    if (name === null) {
+      out += path[i];
+      i += 1;
+      continue;
+    }
+    const open = i + name[0].length - 1;
+    const close = closingParenthesis(path, open);
+    if (close === -1) {
+      return out + path.slice(i);
+    }
+    out += path.slice(i, open);
+    i = close + 1;
+  }
+  return out;
+}
+function closingParenthesis(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === "\\") {
+      i += 1;
+      continue;
+    }
+    if (char === "(") {
+      depth += 1;
+    }
+    if (char === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
 function pathShape(path) {
   return normalizePath(path).replace(/\{[^{}]*?([?+*]?)\}/g, "{$1}");
 }
@@ -678,8 +880,39 @@ function methodsAgree(a, b) {
 function routePathAdmits(declaredPath, requestPath) {
   return patternAdmits(normalizePath(declaredPath), normalizePath(requestPath));
 }
-function routePathsMeet(a, b) {
-  return pathsMeet(normalizePath(a), normalizePath(b));
+function readHost(semantics) {
+  const host = semantics.host;
+  return host === void 0 || /[{(]/.test(host) ? void 0 : host;
+}
+function hostsAgree(a, b) {
+  return readHost(a) === readHost(b);
+}
+function hostUnread(semantics) {
+  if (semantics.host !== void 0) {
+    return readHost(semantics) === void 0;
+  }
+  return baseUrlReference(semantics) !== null;
+}
+function servedPath(semantics, path) {
+  const normalized = normalizePath(path);
+  return semantics.optionalFormat === true ? `${normalized}(|.{format})` : normalized;
+}
+function withoutHost(semantics) {
+  const { host: _host, ...rest } = semantics;
+  return rest;
+}
+function groundedBaseUrl(semantics, deployment) {
+  const reference = baseUrlReference(semantics);
+  if (reference === null) {
+    return null;
+  }
+  const base = deployment.setTo(reference);
+  if (base === null) {
+    return null;
+  }
+  const rest = OPENING_HOLE.exec(semantics.path ?? "")?.[2] ?? "";
+  const grounded = pathAfterOrigin(`${base}${rest}`);
+  return { ...semantics, path: grounded === "" ? "/" : grounded };
 }
 var restSemantics = defineBoundarySemantics({
   name: "rest",
@@ -719,19 +952,46 @@ var restSemantics = defineBoundarySemantics({
       if (semantics.method === null || semantics.path === null) {
         return null;
       }
-      return `rest ${pathShape(semantics.path)}`;
+      const shape = pathShape(pathAfterBaseUrl(normalizePath(semantics.path)));
+      const host = readHost(semantics);
+      return host === void 0 ? `rest ${shape}` : `rest //${host}${shape}`;
+    },
+    /**
+     * A spec writes `/teams/{team_id}` where the route that serves it
+     * writes `/teams/:id`. The method stays in, so a `"*"` handler is
+     * never compared with the document for one method.
+     */
+    operationKey(semantics) {
+      if (semantics.method === null || semantics.path === null) {
+        return null;
+      }
+      return `${semantics.method.toUpperCase()} ${pathShape(semantics.path)}`;
     },
     sidesAgree(a, b) {
-      return methodsAgree(a.method, b.method);
+      return methodsAgree(a.method, b.method) && hostsAgree(a, b);
     },
     spansBuckets(semantics) {
-      return semantics.path !== null && pathSpansShapes(normalizePath(semantics.path));
+      return semantics.path !== null && (semantics.optionalFormat === true || pathSpansShapes(normalizePath(semantics.path)));
     },
     bucketsMeet(a, b) {
-      return a.path !== null && b.path !== null && routePathsMeet(a.path, b.path);
+      return a.path !== null && b.path !== null && hostsAgree(a, b) && pathsMeet(servedPath(a, a.path), servedPath(b, b.path));
     },
-    bucketRank(semantics) {
-      return semantics.path === null ? [] : pathSpecificity(normalizePath(semantics.path));
+    /**
+     * A catch-all route never takes a call whose host suss could not
+     * read, since nothing else ties that call to this app.
+     */
+    pairRank(provider, consumer) {
+      if (provider.path === null || consumer.path === null) {
+        return [];
+      }
+      const route = normalizePath(provider.path);
+      if (hostUnread(consumer) && isCatchAll(route)) {
+        return null;
+      }
+      return requestRank(
+        servedPath(provider, provider.path),
+        normalizePath(consumer.path)
+      );
     },
     /**
      * The identity key, with a missing half still readable: `ANY` when
@@ -772,27 +1032,29 @@ var restSemantics = defineBoundarySemantics({
     },
     /**
      * A call whose base URL the deployment fills in, resolved to the
-     * path it reaches.
+     * path it reaches, and a call to a host that can be the project's
+     * own, with the host left out so it meets the route.
      *
-     * The source cannot settle this on its own, so the adapter leaves
-     * the hole in. `API_BASE` could be `http://backend.internal`, and
-     * then the path is `/orders`. It could equally be `/api/v2`, and
+     * The source cannot settle a base URL on its own, so the adapter
+     * leaves the hole in. `API_BASE` could be `http://backend.internal`,
+     * and then the path is `/orders`. It could equally be `/api/v2`, and
      * then the path is `/api/v2/orders`. Filling in the deployed value
-     * and reading the path back out gets the right one either way.
-     * `baseUrlReference` finds the hole that is the base URL.
+     * and reading the path back out gets the right one either way, and
+     * a base the deployment sets counts as the app's own.
      */
-    groundName(semantics, deployment) {
-      const reference = baseUrlReference(semantics);
-      if (reference === null) {
-        return null;
-      }
-      const base = deployment.setTo(reference);
-      if (base === null) {
+    /** A listed host matches with or without the port the call gives. */
+    withoutOwnHost(semantics, ownHosts) {
+      const host = semantics.host?.toLowerCase();
+      if (host === void 0) {
         return null;
       }
-      const rest = OPENING_HOLE.exec(semantics.path ?? "")?.[2] ?? "";
-      const grounded = pathAfterOrigin(`${base}${rest}`);
-      return { ...semantics, path: grounded === "" ? "/" : grounded };
+      return ownHosts.has(host) || ownHosts.has(host.replace(/:\d+$/, "")) ? withoutHost(semantics) : null;
+    },
+    groundName(semantics, deployment) {
+      const based = groundedBaseUrl(semantics, deployment);
+      const grounded = based ?? semantics;
+      const host = readHost(grounded);
+      return host !== void 0 && hostCanBeOwn(host) ? withoutHost(grounded) : based;
     },
     nameReference: baseUrlReference,
     ruleBoundary: {

package/dist/schemas.d.cts

@@ -1,2 +1,2 @@
 import 'zod';
-export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, I as typeDefinitionKey, J as withDefinitionsInlined } from './schemas-CghZNwSE.cjs';
+export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, I as typeDefinitionKey, J as withDefinitionsInlined } from './schemas-lfg8kvak.cjs';

package/dist/schemas.d.ts

@@ -1,2 +1,2 @@
 import 'zod';
-export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, I as typeDefinitionKey, J as withDefinitionsInlined } from './schemas-CghZNwSE.js';
+export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, I as typeDefinitionKey, J as withDefinitionsInlined } from './schemas-lfg8kvak.js';

package/dist/schemas.js

@@ -17,7 +17,7 @@ import {
   TypeShapeSchema,
   typeDefinitionKey,
   withDefinitionsInlined
-} from "./chunk-WOXA5GBL.js";
+} from "./chunk-A46EUIKC.js";
 export {
   BoundaryBindingSchema,
   ConfidenceInfoSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/ir-core",
-  "version": "0.34.0",
+  "version": "0.34.1",
   "type": "module",
   "description": "The type primitives every suss summary is built from: type shapes, boundary bindings, source locations and confidence.",
   "keywords": [