@suss/ir-core 0.34.0 → 0.35.0

package/dist/index.cjs

@@ -54,7 +54,6 @@ __export(index_exports, {
   boundaryKey: () => boundaryKey,
   boundaryLabel: () => boundaryLabel,
   boundaryNameString: () => boundaryNameString,
-  bucketRank: () => bucketRank,
   bucketsMeet: () => bucketsMeet,
   busIdentityKey: () => busIdentityKey,
   busesAgree: () => busesAgree,
@@ -78,6 +77,7 @@ __export(index_exports, {
   groundBinding: () => groundBinding,
   groundedPairingKey: () => groundedPairingKey,
   hasNameHole: () => hasNameHole,
+  hostCanBeOwn: () => hostCanBeOwn,
   ioBinding: () => ioBinding,
   ioIdentityKey: () => ioIdentityKey,
   isGraphqlOperationBinding: () => isGraphqlOperationBinding,
@@ -98,7 +98,9 @@ __export(index_exports, {
   namesNothing: () => namesNothing,
   normalizePath: () => normalizePath,
   normalizeRuleBoundary: () => normalizeRuleBoundary,
+  operationKey: () => operationKey,
   packageExportBinding: () => packageExportBinding,
+  pairRank: () => pairRank,
   pairingKey: () => pairingKey,
   parseBoundaryName: () => parseBoundaryName,
   parseChannel: () => parseChannel,
@@ -135,7 +137,8 @@ __export(index_exports, {
   validateRule: () => validateRule,
   withDefinitionsInlined: () => withDefinitionsInlined,
   withRewrittenPaths: () => withRewrittenPaths,
-  withinScope: () => withinScope
+  withinScope: () => withinScope,
+  withoutOwnHost: () => withoutOwnHost
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -655,6 +658,38 @@ function pathAfterOrigin(text) {
 function statesAnOrigin(text) {
   return SCHEME_ORIGIN.test(text) || PROTOCOL_RELATIVE_ORIGIN.test(text);
 }
+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 HOLE_RANGE_SUFFIX = {
@@ -721,14 +756,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) {
@@ -748,10 +787,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 }));
@@ -830,17 +894,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);
@@ -870,7 +1021,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) {
@@ -878,7 +1040,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);
   }
@@ -888,6 +1053,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}");
 }
@@ -903,6 +1108,40 @@ function routePathAdmits(declaredPath, 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",
   schema: RestSemanticsSchema,
@@ -941,19 +1180,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
@@ -994,27 +1260,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: {
@@ -1460,6 +1728,13 @@ function withRewrittenPaths(binding, rewrite) {
     semantics: behavior.rewritePaths(binding.semantics, rewrite)
   };
 }
+function withoutOwnHost(binding, ownHosts) {
+  const semantics = behaviorOf(binding.semantics).withoutOwnHost?.(
+    binding.semantics,
+    ownHosts
+  );
+  return semantics === void 0 || semantics === null ? binding : { ...binding, semantics };
+}
 function groundedPairingKey(binding, deployment) {
   return pairingKey(groundBinding(binding, deployment));
 }
@@ -1475,6 +1750,10 @@ function pairingKey(binding) {
   const behavior = behaviorOf(binding.semantics);
   return (behavior.pairingKey ?? behavior.identityKey)(binding.semantics);
 }
+function operationKey(binding) {
+  const behavior = behaviorOf(binding.semantics);
+  return (behavior.operationKey ?? behavior.identityKey)(binding.semantics);
+}
 function semanticsAgree(a, b) {
   if (a.name !== b.name) {
     return false;
@@ -1492,8 +1771,12 @@ function bucketsMeet(a, b) {
   const meet = behaviorOf(a.semantics).bucketsMeet;
   return meet !== void 0 && meet(a.semantics, b.semantics);
 }
-function bucketRank(binding) {
-  return behaviorOf(binding.semantics).bucketRank?.(binding.semantics) ?? [];
+function pairRank(provider, consumer) {
+  if (provider.semantics.name !== consumer.semantics.name) {
+    return null;
+  }
+  const rank = behaviorOf(provider.semantics).pairRank;
+  return rank === void 0 ? [] : rank(provider.semantics, consumer.semantics);
 }
 function boundaryLabel(binding) {
   const behavior = behaviorOf(binding.semantics);
@@ -1681,7 +1964,9 @@ var EffectRelationSchema = RelationSchema.exclude(["provides"]);
 var import_zod15 = require("zod");
 var SuppressionSideSchema = import_zod15.z.object({
   summary: import_zod15.z.string().optional(),
-  transitionId: import_zod15.z.string().optional()
+  transitionId: import_zod15.z.string().optional(),
+  /** The field on that side, for a finding about one field and no transition. */
+  field: import_zod15.z.string().optional()
 }).optional();
 var SuppressionRuleSchema = import_zod15.z.object({
   /**
@@ -1968,7 +2253,9 @@ function restBinding(opts) {
       name: "rest",
       method: method === null ? null : method.toUpperCase(),
       path: namedOrNull(opts.path, "rest path"),
-      ...opts.declaredResponses !== void 0 ? { declaredResponses: opts.declaredResponses } : {}
+      ...opts.declaredResponses !== void 0 ? { declaredResponses: opts.declaredResponses } : {},
+      ...opts.host !== void 0 && opts.host !== "" ? { host: opts.host } : {},
+      ...opts.optionalFormat === true ? { optionalFormat: true } : {}
     },
     recognition: opts.recognition
   };
@@ -2127,7 +2414,6 @@ function ioBinding(opts) {
   boundaryKey,
   boundaryLabel,
   boundaryNameString,
-  bucketRank,
   bucketsMeet,
   busIdentityKey,
   busesAgree,
@@ -2151,6 +2437,7 @@ function ioBinding(opts) {
   groundBinding,
   groundedPairingKey,
   hasNameHole,
+  hostCanBeOwn,
   ioBinding,
   ioIdentityKey,
   isGraphqlOperationBinding,
@@ -2171,7 +2458,9 @@ function ioBinding(opts) {
   namesNothing,
   normalizePath,
   normalizeRuleBoundary,
+  operationKey,
   packageExportBinding,
+  pairRank,
   pairingKey,
   parseBoundaryName,
   parseChannel,
@@ -2208,5 +2497,6 @@ function ioBinding(opts) {
   validateRule,
   withDefinitionsInlined,
   withRewrittenPaths,
-  withinScope
+  withinScope,
+  withoutOwnHost
 });