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

package/dist/cli/index.js

@@ -65,7 +65,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.69";
+    WAIRON_VERSION = "5.1.1-dev.70";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -14374,6 +14374,135 @@ var init_param_conformance = __esm({
   }
 });
 
+// src/core/rules/conformance/route-coverage.ts
+function liesUnder2(path71, prefix) {
+  return path71 === prefix || path71.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;
+var init_route_coverage = __esm({
+  "src/core/rules/conformance/route-coverage.ts"() {
+    "use strict";
+    init_models();
+    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((method2) => {
+              const endpoint = method2.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;
 var init_unclaimed_source = __esm({
@@ -14695,14 +14824,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;
 var init_method_cohesion = __esm({
@@ -14767,7 +14903,7 @@ var init_coupling_health = __esm({
         { 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();
@@ -14839,10 +14975,10 @@ var init_coupling_health = __esm({
             );
           }
         }
-        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",
@@ -15475,7 +15611,7 @@ var init_complexity_and_metadata = __esm({
         { 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) {
@@ -15495,7 +15631,7 @@ var init_complexity_and_metadata = __esm({
             );
           }
         }
-        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);
@@ -15509,7 +15645,7 @@ var init_complexity_and_metadata = __esm({
             "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",
@@ -15919,6 +16055,7 @@ var init_repository = __esm({
     init_type_realization();
     init_type_shape();
     init_param_conformance();
+    init_route_coverage();
     init_unclaimed_source();
     init_export_conformance();
     init_carried_debt();
@@ -16098,6 +16235,7 @@ var init_repository = __esm({
       typeRealizationRule,
       typeShapeRule,
       paramConformanceRule,
+      routeCoverageRule,
       unclaimedSourceRule,
       exportConformanceRule,
       couplingRule,
@@ -16267,6 +16405,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 = [];
@@ -16438,6 +16577,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) {
@@ -16449,6 +16649,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)) {
@@ -16556,7 +16762,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;
@@ -16740,6 +16946,7 @@ function buildCodeModel(implementations, types, projectRoot2, sourceRoots = [],
             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
           };
@@ -33580,7 +33787,7 @@ async function runDomainsAdd(options = {}) {
       type: "input",
       name: "domainName",
       message: "Display name:",
-      default: (answers) => answers.domainId.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")
+      default: (answers2) => answers2.domainId.split(/[-_]/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ")
     },
     {
       type: "input",
@@ -33592,7 +33799,7 @@ async function runDomainsAdd(options = {}) {
       type: "input",
       name: "ownedPathsRaw",
       message: "Owned path globs (comma-separated):",
-      default: (answers) => answers.domainPath ? `${answers.domainPath}/**` : "",
+      default: (answers2) => answers2.domainPath ? `${answers2.domainPath}/**` : "",
       validate: (v) => v.trim().length > 0 || "At least one owned path is required"
     }
   ]);
@@ -41209,12 +41416,12 @@ var ApprovalRegistry = class {
         `Approval request "${id}" is ${current2.status}, not approved; only an approved request can be completed.`
       );
     }
-    const completed = { ...current2, status: "completed" };
+    const completed2 = { ...current2, status: "completed" };
     const next = [...requests];
-    next[idx] = completed;
+    next[idx] = completed2;
     persistRequests(this.dataDir, next);
     this.store.replaceAll(next);
-    return completed;
+    return completed2;
   }
   /**
    * Flip every pending request whose expiresAt is at or before the supplied
@@ -45509,6 +45716,21 @@ function adminPlaceProject(cfg, sessionId, projectId, unitId) {
 function adminRemoveUnit(cfg, sessionId, unitId, disposition) {
   removeUnit(cfg, sessionId, unitId, disposition);
 }
+function adminGetLandscape(cfg, sessionId) {
+  return generateLandscape(cfg, sessionId);
+}
+function adminGetHealth(cfg, sessionId) {
+  return getHealthReport(cfg, sessionId);
+}
+function adminGetUsage(cfg, sessionId) {
+  return getUsage(cfg, sessionId);
+}
+function adminListApprovals(cfg, sessionId) {
+  return listPendingRequests(cfg, sessionId);
+}
+function adminDecideApproval(cfg, sessionId, decision) {
+  return decideRequest(cfg, sessionId, decision);
+}
 function bodyScope(body) {
   return {
     scopeKind: body?.scopeKind ? String(body.scopeKind) : void 0,
@@ -46100,16 +46322,16 @@ async function handleWebRequest(cfg, req, res, body, url, ctx) {
         return sendJson(res, 200, { entries: adminGetShareAccessLog(cfg, sessionId, url.searchParams.get("linkId") ?? "", limit) });
       }
       if (req.method === "GET" && parts.length === 3 && parts[2] === "landscape") {
-        return sendJson(res, 200, generateLandscape(cfg, sessionId));
+        return sendJson(res, 200, adminGetLandscape(cfg, sessionId));
       }
       if (req.method === "GET" && parts.length === 3 && parts[2] === "health") {
-        return sendJson(res, 200, getHealthReport(cfg, sessionId));
+        return sendJson(res, 200, adminGetHealth(cfg, sessionId));
       }
       if (req.method === "GET" && parts.length === 3 && parts[2] === "usage") {
-        return sendJson(res, 200, { usage: getUsage(cfg, sessionId) });
+        return sendJson(res, 200, { usage: adminGetUsage(cfg, sessionId) });
       }
       if (req.method === "GET" && parts.length === 3 && parts[2] === "approvals") {
-        return sendJson(res, 200, { requests: listPendingRequests(cfg, sessionId) });
+        return sendJson(res, 200, { requests: adminListApprovals(cfg, sessionId) });
       }
       if (req.method === "POST" && parts.length === 4 && parts[2] === "approvals" && parts[3] === "decide") {
         const decision = {
@@ -46121,7 +46343,7 @@ async function handleWebRequest(cfg, req, res, body, url, ctx) {
           decidedAt: ""
           // set server-side
         };
-        return sendJson(res, 200, decideRequest(cfg, sessionId, decision));
+        return sendJson(res, 200, adminDecideApproval(cfg, sessionId, decision));
       }
     }
     sendJson(res, 404, { error: "not found" });
@@ -47022,6 +47244,7 @@ var WEB_MUTATION_PATHS = /* @__PURE__ */ new Set([
   "/web/admin/share/refresh",
   "/web/admin/share/update",
   "/web/admin/share/remove",
+  "/web/admin/approvals/decide",
   "/web/projects/packs",
   "/web/projects/packs/upload",
   "/web/projects/packs/remove",