@wairon/cli 5.1.1-dev.69 → 5.1.1-dev.70

package/dist/index.js

@@ -11593,7 +11593,7 @@ function defaultTargetConfig(type) {
     enabled: true
   };
 }
-var WAIRON_VERSION = "5.1.1-dev.69";
+var WAIRON_VERSION = "5.1.1-dev.70";
 var GITHUB_REPO = "SYW-Apps/Waffle-AIron";
 var ARCHITECT_AGENT_ID = "agent-architect";
 var ARCHITECT_TEMPLATE_ID = "architect";
@@ -17163,6 +17163,128 @@ var paramConformanceRule = {
   }
 };
 
+// src/core/rules/conformance/route-coverage.ts
+function liesUnder2(path28, prefix) {
+  return path28 === prefix || path28.startsWith(prefix + "/");
+}
+function normalizeSegment(segment) {
+  return /^\{.+\}$/.test(segment) || segment.startsWith(":") ? "*" : segment;
+}
+function completed(route, heads) {
+  const variants = route.segments[0] === "*" && heads.length > 0 ? heads.map((head) => [head, ...route.segments.slice(1)]) : [route.segments];
+  return variants.map((segments) => ({
+    verb: route.verb.toUpperCase(),
+    segments: segments.map(normalizeSegment),
+    exactLength: route.exactLength,
+    key: `${route.verb.toUpperCase()} /${segments.join("/")}${route.exactLength ? "" : "/\u2026"}`
+  }));
+}
+function answers(route, endpoint) {
+  if (route.verb !== endpoint.verb) return false;
+  if (route.exactLength ? endpoint.segments.length !== route.segments.length : endpoint.segments.length < route.segments.length) return false;
+  return route.segments.every((segment, index) => segment === endpoint.segments[index]);
+}
+var routeCoverageRule = {
+  name: "route-coverage",
+  description: "Code-to-contract for the ROUTES: does every route a router actually answers have a contract endpoint, and does every contract endpoint have a route that answers it? A portal's endpoints are what its contract promises; the router is what the code serves; nothing compared the two, so a route with no contract \u2014 including a write \u2014 could run for months without a single rule noticing. The listener's mount names the router function (its `via`), and the routes are read out of that function's guards; the path segment the router never checks is the one the mount's prefix guarantees. One idiom is read \u2014 a method comparison with comparisons on the path's split segments \u2014 and a mounted router that yields no route in it is reported as unread, never passed: a check that cannot see a router must say so rather than stay quiet.",
+  codes: [
+    {
+      code: "UNDECLARED_ROUTE",
+      defaultSeverity: "warning",
+      summary: "A router answers a route that no contract endpoint of the portal it serves declares \u2014 a surface the code serves and the design never promised",
+      // Measured code↔contract drift, route by route, at the mount's router
+      // entry — which is why every one of them hands over `parts`.
+      carryable: true
+    },
+    {
+      code: "UNROUTED_ENDPOINT",
+      defaultSeverity: "warning",
+      summary: "A contract endpoint no route of the portal's router answers \u2014 the contract promises a route that no request can reach",
+      carryable: true
+    },
+    {
+      code: "UNREADABLE_ROUTER",
+      defaultSeverity: "warning",
+      summary: "A mounted portal's router yields no route this analysis can read, so its routes were not checked against the contract at all",
+      carryable: true
+    }
+  ],
+  check(ctx) {
+    const code = ctx.codeIndex();
+    const realization = ctx.realizationIndex();
+    for (const listener of ctx.components) {
+      if (listener.componentType !== "Portal") continue;
+      for (const mount of listener.mounts ?? []) {
+        const via = mount.via;
+        if (!via) continue;
+        const portal = ctx.componentMap.get(mount.portal);
+        if (!portal || portal.componentType !== "Portal") continue;
+        const [anchor] = realization.implementationsOf(portal.id).map((impl) => impl.id).sort();
+        if (!anchor) continue;
+        const holders = realization.filesOf(portal.id).map(pathKey).filter((file) => {
+          const facts = code.factsAt(file);
+          return !!facts && facts.status === "analyzed" && facts.analysisGrade === "exact" && !!facts.functionParams && Object.prototype.hasOwnProperty.call(facts.functionParams, via);
+        });
+        if (holders.length === 0) continue;
+        const read = holders.flatMap((file) => {
+          const routes = code.factsAt(file).functionRoutes;
+          return routes && Object.prototype.hasOwnProperty.call(routes, via) ? routes[via] : [];
+        });
+        const draftContext = ctx.isComponentDraft(listener.id) || ctx.isComponentDraft(portal.id);
+        const where = holders.map((file) => `"${file}"`).join(", ");
+        if (read.length === 0) {
+          ctx.addIssue(
+            "warning",
+            "UNREADABLE_ROUTER",
+            `Listener "${listener.id}" mounts portal "${portal.id}" through "${via}" in ${where}, but no branch of "${via}" reads as a route \u2014 so none of its routes were checked against the contract at all. Only one idiom is read: an \`if\` whose conditions, together with those of every enclosing \`if\`, compare \`<request>.method\` with a string and \`parts[i]\` / \`parts.length\` with literals. Silence here would read as a clean router; it is only one this analysis cannot see. Write the router in that idiom, or carry this finding with the reason it cannot be.`,
+            anchor,
+            draftContext,
+            void 0,
+            { at: via }
+          );
+          continue;
+        }
+        const heads = [...new Set(mount.prefixes.map((prefix) => prefix.split("/").filter(Boolean)[0]).filter((head) => !!head))];
+        const served = read.map((route) => completed(route, heads));
+        const endpoints = ctx.interfaceMethodsOf(portal.id).flatMap((method) => {
+          const endpoint = method.endpoint;
+          if (endpoint?.transport !== "HTTP") return [];
+          if (!mount.prefixes.some((prefix) => liesUnder2(endpoint.path, prefix))) return [];
+          return [{
+            verb: endpoint.method.toUpperCase(),
+            segments: endpoint.path.split("/").filter(Boolean).map(normalizeSegment),
+            key: `${endpoint.method.toUpperCase()} ${endpoint.path}`
+          }];
+        });
+        const undeclared = [...new Set(served.filter((variants) => !variants.some((route) => endpoints.some((endpoint) => answers(route, endpoint)))).flatMap((variants) => variants.map((route) => route.key)))].sort();
+        if (undeclared.length > 0) {
+          ctx.addIssue(
+            "warning",
+            "UNDECLARED_ROUTE",
+            `Portal "${portal.id}"'s router "${via}" (${where}), mounted by listener "${listener.id}", answers ${undeclared.length} route(s) no contract endpoint of "${portal.id}" declares \u2014 ${undeclared.map((key) => `"${key}"`).join(", ")}. A surface the code serves and the design never promised is how a write runs with no contract: no brief, no auth review, no rule reading it. Declare each as a contract method with its endpoint, or take the route out of the router.`,
+            anchor,
+            draftContext,
+            void 0,
+            { at: via, covers: undeclared }
+          );
+        }
+        const unrouted = [...new Set(endpoints.filter((endpoint) => !served.some((variants) => variants.some((route) => answers(route, endpoint)))).map((endpoint) => endpoint.key))].sort();
+        if (unrouted.length > 0) {
+          ctx.addIssue(
+            "warning",
+            "UNROUTED_ENDPOINT",
+            `Portal "${portal.id}" binds ${unrouted.length} HTTP endpoint(s) under listener "${listener.id}"'s mount that no route of its router "${via}" (${where}) answers \u2014 ${unrouted.map((key) => `"${key}"`).join(", ")}. The contract promises a route no request can reach. Route it in the router, or drop the endpoint from the contract.`,
+            anchor,
+            draftContext,
+            void 0,
+            { at: via, covers: unrouted }
+          );
+        }
+      }
+    }
+  }
+};
+
 // src/core/rules/conformance/unclaimed-source.ts
 var unclaimedSourceRule = {
   name: "unclaimed-source",
@@ -17464,14 +17586,21 @@ function isPureForwarder(methods) {
   const narrated = methods.filter((m) => (m.narrative ?? []).length > 0);
   return narrated.length > 0 && narrated.every((m) => isForwardingMethod(m.narrative ?? []));
 }
-function pureForwarderComponents(ctx) {
+function reachesCollaborator(narrative) {
+  return narrative.some((step) => step.type === "call" || step.type === "dispatch" || step.type === "register");
+}
+function isRoutingTable(methods) {
+  const reaching = methods.map((m) => m.narrative ?? []).filter(reachesCollaborator);
+  return reaching.length > 0 && reaching.every(isForwardingMethod);
+}
+function routingTableComponents(ctx) {
   const realized = /* @__PURE__ */ new Map();
   for (const impl of ctx.implementations) {
     const intf = ctx.interfaceMap.get(impl.contract);
     if (!intf) continue;
     realized.set(intf.component, [...realized.get(intf.component) ?? [], ...impl.methods]);
   }
-  return new Set([...realized].filter(([, methods]) => isPureForwarder(methods)).map(([id]) => id));
+  return new Set([...realized].filter(([, methods]) => isRoutingTable(methods)).map(([id]) => id));
 }
 var methodCohesionRule = {
   name: "method-cohesion",
@@ -17524,7 +17653,7 @@ var couplingRule = {
     { code: "MUTUAL_SUBSYSTEM_DEPENDENCY", defaultSeverity: "warning", summary: "Subsystems depend on each other without a declared trusted link" },
     { code: "INVALID_TRUSTED_LINK", defaultSeverity: "error", summary: "trustedLinks references a non-existent subsystem" },
     { code: "UNUSED_TRUSTED_LINK", defaultSeverity: "warning", summary: "trustedLinks declares a peer no dependency actually reaches" },
-    { code: "GOD_COMPONENT", defaultSeverity: "warning", summary: "Component with excessive dependency fan-out; not reported on a pure forwarder, whose every narrated method is a single hand-off" }
+    { code: "GOD_COMPONENT", defaultSeverity: "warning", summary: "Component with excessive dependency fan-out; not reported on a routing table, which reaches every collaborator it has only through single hand-offs" }
   ],
   check(ctx) {
     const subsystemDeps = /* @__PURE__ */ new Map();
@@ -17596,10 +17725,10 @@ var couplingRule = {
         );
       }
     }
-    const forwarders = pureForwarderComponents(ctx);
+    const routingTables = routingTableComponents(ctx);
     for (const comp of ctx.components) {
       const threshold = ctx.complexityConfigFor(comp.subsystem)?.maxComponentDependencies ?? DEFAULT_GOD_COMPONENT_THRESHOLD;
-      if (comp.dependsOn.length > threshold && !forwarders.has(comp.id)) {
+      if (comp.dependsOn.length > threshold && !routingTables.has(comp.id)) {
         ctx.addIssue(
           "warning",
           "GOD_COMPONENT",
@@ -18191,7 +18320,7 @@ var complexityRule = {
     { code: "DESCRIPTION_TOO_SHORT", defaultSeverity: "warning", summary: "Description is shorter than the configured minimum length" },
     { code: "EXCESSIVE_METHODS", defaultSeverity: "warning", summary: "Interface declares more methods than the configured limit" },
     { code: "EXCESSIVE_METHOD_PARAMS", defaultSeverity: "warning", summary: "Interface method declares more parameters than the configured limit" },
-    { code: "EXCESSIVE_DEPENDENCIES", defaultSeverity: "warning", summary: "Component has more dependencies than the configured limit; not reported on a pure forwarder, whose fan-out is a routing table rather than knowledge" },
+    { code: "EXCESSIVE_DEPENDENCIES", defaultSeverity: "warning", summary: "Component has more dependencies than the configured limit; not reported on a routing table, which reaches every collaborator it has only through single hand-offs" },
     { code: "EXCESSIVE_SUBSYSTEM_COMPONENTS", defaultSeverity: "warning", summary: "Subsystem has more direct components than the configured limit" }
   ],
   check(ctx) {
@@ -18211,7 +18340,7 @@ var complexityRule = {
         );
       }
     }
-    const forwarders = pureForwarderComponents(ctx);
+    const routingTables = routingTableComponents(ctx);
     for (const comp of ctx.components) {
       const docConfig = ctx.documentationConfigFor(comp.subsystem);
       const complexityConfig = ctx.complexityConfigFor(comp.subsystem);
@@ -18225,7 +18354,7 @@ var complexityRule = {
         "Component",
         isDraft
       );
-      if (complexityConfig?.maxComponentDependencies !== void 0 && comp.dependsOn.length > complexityConfig.maxComponentDependencies && !forwarders.has(comp.id)) {
+      if (complexityConfig?.maxComponentDependencies !== void 0 && comp.dependsOn.length > complexityConfig.maxComponentDependencies && !routingTables.has(comp.id)) {
         ctx.addIssue(
           "warning",
           "EXCESSIVE_DEPENDENCIES",
@@ -18675,6 +18804,7 @@ var SDD_RULES = [
   typeRealizationRule,
   typeShapeRule,
   paramConformanceRule,
+  routeCoverageRule,
   unclaimedSourceRule,
   exportConformanceRule,
   couplingRule,
@@ -18993,6 +19123,7 @@ function walkExact(ts, sourceText, fileName) {
   const localTypes = /* @__PURE__ */ new Map();
   const typeShapes = /* @__PURE__ */ new Map();
   const functionParams = /* @__PURE__ */ new Map();
+  const functionRoutes = /* @__PURE__ */ new Map();
   const mutableBindings = /* @__PURE__ */ new Set();
   const schemaConstants = /* @__PURE__ */ new Map();
   const derivedAliases = [];
@@ -19164,6 +19295,67 @@ function walkExact(ts, sourceText, fileName) {
     if (fn.body) count(fn.body);
     return { score, callees };
   };
+  const conjunctsOf = (expression, out = []) => {
+    if (ts.isParenthesizedExpression(expression)) return conjunctsOf(expression.expression, out);
+    if (ts.isBinaryExpression(expression) && expression.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken) {
+      conjunctsOf(expression.left, out);
+      conjunctsOf(expression.right, out);
+      return out;
+    }
+    out.push(expression);
+    return out;
+  };
+  const isPartsRef = (expression) => ts.isIdentifier(expression) && expression.text === "parts" || ts.isPropertyAccessExpression(expression) && expression.name.text === "parts";
+  const constraintOf = (conjunct) => {
+    if (!ts.isBinaryExpression(conjunct) || conjunct.operatorToken.kind !== ts.SyntaxKind.EqualsEqualsEqualsToken) {
+      return void 0;
+    }
+    const { left, right } = conjunct;
+    if (ts.isPropertyAccessExpression(left) && left.name.text === "method" && ts.isStringLiteral(right)) {
+      return { verb: right.text };
+    }
+    if (ts.isPropertyAccessExpression(left) && left.name.text === "length" && isPartsRef(left.expression) && ts.isNumericLiteral(right)) {
+      return { length: Number(right.text) };
+    }
+    if (ts.isElementAccessExpression(left) && isPartsRef(left.expression) && ts.isNumericLiteral(left.argumentExpression) && ts.isStringLiteral(right)) {
+      return { index: Number(left.argumentExpression.text), literal: right.text };
+    }
+    return void 0;
+  };
+  const routeOf = (conjuncts) => {
+    let verb;
+    let length;
+    const fixed = /* @__PURE__ */ new Map();
+    for (const conjunct of conjuncts) {
+      const constraint = constraintOf(conjunct);
+      if (!constraint) continue;
+      if ("verb" in constraint) verb = constraint.verb;
+      else if ("length" in constraint) length = constraint.length;
+      else fixed.set(constraint.index, constraint.literal);
+    }
+    if (verb === void 0) return void 0;
+    const count = length ?? (fixed.size > 0 ? Math.max(...fixed.keys()) + 1 : 0);
+    const segments = [];
+    for (let index = 0; index < count; index++) segments.push(fixed.get(index) ?? "*");
+    return { verb, segments, exactLength: length !== void 0 };
+  };
+  const collectRoutes = (fn) => {
+    const routes = /* @__PURE__ */ new Map();
+    const walk2 = (node, enclosing) => {
+      if (namedFunctionName(node) !== void 0) return;
+      if (ts.isIfStatement(node)) {
+        const guarded = [...enclosing, ...conjunctsOf(node.expression)];
+        const route = routeOf(guarded);
+        if (route) routes.set(`${route.verb} /${route.segments.join("/")}${route.exactLength ? "" : "/\u2026"}`, route);
+        walk2(node.thenStatement, guarded);
+        if (node.elseStatement) walk2(node.elseStatement, enclosing);
+        return;
+      }
+      ts.forEachChild(node, (child) => walk2(child, enclosing));
+    };
+    if (fn.body) walk2(fn.body, []);
+    return routes;
+  };
   const visit = (node) => {
     const fnName = namedFunctionName(node);
     if (fnName && node.body) {
@@ -19175,6 +19367,12 @@ function walkExact(ts, sourceText, fileName) {
       const signatures = functionParams.get(fnName) ?? [];
       signatures.push(declaredParameters(node));
       functionParams.set(fnName, signatures);
+      const routes = collectRoutes(node);
+      if (routes.size > 0) {
+        const known = functionRoutes.get(fnName) ?? /* @__PURE__ */ new Map();
+        for (const [key, route] of routes) known.set(key, route);
+        functionRoutes.set(fnName, known);
+      }
     }
     if (ts.isPropertyDeclaration(node)) recordFieldType(node.name, node.type);
     else if (ts.isParameter(node) && node.parent && ts.isConstructorDeclaration(node.parent) && isParameterProperty(node)) {
@@ -19282,7 +19480,7 @@ function walkExact(ts, sourceText, fileName) {
     typeShapes.set(alias.name, { origin: "derived", fields: schemaMembers(literal), methods: [] });
   }
   const reexportOnly = sf.statements.length > 0 && sf.statements.every((st) => ts.isExportDeclaration(st) && !!st.moduleSpecifier);
-  return { declared, anchors, exported, imports, reexports, starExports, namedReexports, complexity, calls, importBindings, typeOnlyBindings, fieldTypes, localTypes, typeShapes, functionParams, mutableBindings, reexportOnly };
+  return { declared, anchors, exported, imports, reexports, starExports, namedReexports, complexity, calls, importBindings, typeOnlyBindings, fieldTypes, localTypes, typeShapes, functionParams, functionRoutes, mutableBindings, reexportOnly };
 }
 function resolveRelativeModule(fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
@@ -19466,6 +19664,7 @@ function buildCodeModel(implementations, types, projectRoot, sourceRoots = [], e
             localTypes: Object.fromEntries([...facts.localTypes].map(([k, v]) => [k, [...v]])),
             typeShapes: Object.fromEntries(facts.typeShapes),
             functionParams: Object.fromEntries(facts.functionParams),
+            functionRoutes: Object.fromEntries([...facts.functionRoutes].map(([k, v]) => [k, [...v.values()]])),
             topLevelMutableBindings: [...facts.mutableBindings],
             reexportOnly: facts.reexportOnly
           };