@wairon/cli 5.1.1-dev.64 → 5.1.1-dev.66

package/dist/index.js

@@ -5819,6 +5819,24 @@ var ImplementationSpecSchema = import_zod8.z.object({
    * stereotypes should bind tech directly (TECH_ON_LOGIC_COMPONENT).
    */
   technologies: import_zod8.z.array(import_zod8.z.string()).optional(),
+  /**
+   * The parameter names THIS realization takes BEFORE the ones its contract
+   * declares — a config object, a data root, the transport handles a portal is
+   * handed. Supplied by whatever wires the component up, never by the caller
+   * the contract describes, which is why they belong to the realization and
+   * not to the contract: another realization of the same contract may hold
+   * them as fields instead.
+   *
+   * Declared rather than guessed, because a leading parameter the contract
+   * does not name is otherwise indistinguishable from one it named under a
+   * different name — `seed(config)` realized as `bootstrapInstance(cfg)` reads
+   * as a dropped parameter to anything that infers. A leading parameter this
+   * list does not name is a finding (UNDECLARED_PARAM), and only a LEADING run
+   * is dropped: one of these names appearing after the contract's own
+   * parameters is not wiring, it is an argument in the middle of the caller's
+   * list.
+   */
+  injectedParams: import_zod8.z.array(import_zod8.z.string()).optional(),
   methods: import_zod8.z.array(MethodImplementationSchema).default([]).superRefine((methods, ctx) => {
     methods.forEach((m, i) => {
       if (!m.calls?.length || m.narrative.length === 0) return;
@@ -11549,7 +11567,7 @@ function defaultTargetConfig(type) {
     enabled: true
   };
 }
-var WAIRON_VERSION = "5.1.1-dev.64";
+var WAIRON_VERSION = "5.1.1-dev.66";
 var GITHUB_REPO = "SYW-Apps/Waffle-AIron";
 var ARCHITECT_AGENT_ID = "agent-architect";
 var ARCHITECT_TEMPLATE_ID = "architect";
@@ -16881,6 +16899,166 @@ var typeShapeRule = {
   }
 };
 
+// src/core/rules/conformance/param-conformance.ts
+function omittable(optional) {
+  return optional ? "may be left out" : "is required";
+}
+function unitOf2(parameter, position) {
+  return parameter.name ?? `#${position + 1}`;
+}
+function judge(declared, realized, injected, typeAgrees) {
+  let wiring = 0;
+  while (wiring < realized.length && realized[wiring].name !== void 0 && injected.has(realized[wiring].name)) wiring++;
+  const taken = realized.slice(wiring);
+  const matched = Math.min(declared.length, taken.length);
+  const found = {
+    unrealized: /* @__PURE__ */ new Map(),
+    undeclared: /* @__PURE__ */ new Map(),
+    renamed: /* @__PURE__ */ new Map(),
+    optionality: /* @__PURE__ */ new Map()
+  };
+  for (const param of declared.slice(matched)) {
+    found.unrealized.set(param.name, { unit: param.name, told: `"${param.name}"` });
+  }
+  taken.slice(matched).forEach((param, index) => {
+    const unit = unitOf2(param, wiring + matched + index);
+    found.undeclared.set(unit, { unit, told: `"${unit}"` });
+  });
+  for (let position = 0; position < matched; position++) {
+    const param = declared[position];
+    const at = taken[position];
+    if (at.name !== void 0 && at.name !== param.name && typeAgrees(param, at)) {
+      found.renamed.set(`${param.name}\u2192${at.name}`, {
+        unit: param.name,
+        told: `"${param.name}" (the code calls it "${at.name}")`
+      });
+    }
+    if (!!param.optional !== at.optional) {
+      found.optionality.set(`${param.name}:${at.optional}`, {
+        unit: param.name,
+        told: `"${param.name}" (the contract says it ${omittable(!!param.optional)}, the code says it ${omittable(at.optional)})`
+      });
+    }
+  }
+  return found;
+}
+function agreed(judgements, reading) {
+  const [first, ...rest] = judgements;
+  return [...first[reading]].filter(([fact]) => rest.every((other) => other[reading].has(fact))).map(([, finding]) => finding);
+}
+var paramConformanceRule = {
+  name: "param-conformance",
+  description: "Code-to-contract for the SIGNATURE, the last of the three readings a spec-driven gate never made: a contract declares `params`, and nothing ever compared them to the parameters of the function that realizes the method. A contract could promise an argument the code does not take, take one the contract never mentions \u2014 including a secret \u2014 or name the same argument two different things, and the brief handed to an implementer would carry the contract's version. Parameters are matched by POSITION against the tail of the realization's list, and the declared type is what tells a rename from a dropped argument: `seed(config: HostConfig)` realized as `bootstrapInstance(cfg: HostConfig)` is one parameter under two names, which anything matching on names alone reads as a parameter the code lost. What a realization takes BEFORE the contract's own parameters is wiring, and it is declared on the implementation as `injectedParams` rather than inferred, because an inferred prefix cannot be told from a renamed first argument. A method the named file only CALLS is left to `methodRealization`, which already reports that the body is not here.",
+  codes: [
+    {
+      code: "UNREALIZED_PARAM",
+      defaultSeverity: "warning",
+      summary: "A contract declares a parameter the function realizing the method does not take \u2014 the contract promises an argument that would go nowhere, and every brief and caller built from it passes one",
+      // Measured code↔spec drift, parameter by parameter, at a site the
+      // finding names — which is why every one of them hands over `parts`.
+      carryable: true
+    },
+    {
+      code: "UNDECLARED_PARAM",
+      defaultSeverity: "warning",
+      summary: "The realizing function takes a parameter no contract parameter names and no declared injection accounts for \u2014 an argument a caller must supply that the design never mentions",
+      carryable: true
+    },
+    {
+      code: "PARAM_NAME_MISMATCH",
+      defaultSeverity: "warning",
+      summary: "A contract parameter and the one realizing it agree on position and type but not on name \u2014 the contract, the ERD and every brief say one word while the code says another",
+      carryable: true
+    },
+    {
+      code: "PARAM_OPTIONALITY",
+      defaultSeverity: "warning",
+      summary: "A contract and its realization disagree about whether a parameter may be left out \u2014 one of them is telling a caller an argument is required when it is not, or the reverse",
+      carryable: true
+    }
+  ],
+  check(ctx) {
+    const code = ctx.codeIndex();
+    const codeNameOf = /* @__PURE__ */ new Map();
+    for (const type of ctx.types) {
+      const named = type.symbol ?? type.name;
+      codeNameOf.set(type.id, named);
+      if (type.subsystem) codeNameOf.set(`${type.subsystem}.${type.id}`, named);
+    }
+    const normalize3 = (text) => text.replace(/\s+/g, " ").trim();
+    const typeAgrees = (declared, realized) => {
+      if (!realized.type) return false;
+      const stated = normalize3(declared.type);
+      return stated === realized.type || codeNameOf.get(stated) === realized.type;
+    };
+    for (const { implementation, method, sourceFile, draftContext } of ctx.implementationMethods()) {
+      const contract = ctx.interfaceMap.get(implementation.contract);
+      const declared = contract?.methods.find((m) => m.name === method.name)?.params ?? [];
+      if (declared.length === 0 || !sourceFile) continue;
+      const file = pathKey(sourceFile);
+      const facts = code.factsAt(file);
+      if (!facts || facts.status !== "analyzed" || facts.analysisGrade !== "exact") continue;
+      const symbol = method.symbol ?? method.name;
+      const signatures = facts.functionParams;
+      if (!signatures || !Object.prototype.hasOwnProperty.call(signatures, symbol)) continue;
+      const candidates = signatures[symbol];
+      if (candidates.length === 0) continue;
+      const injected = new Set(implementation.injectedParams ?? []);
+      const judgements = candidates.map((realized) => judge(declared, realized, injected, typeAgrees));
+      const subject = candidates.length > 1 ? `every function called "${symbol}" in "${file}"` : `the function "${symbol}" in "${file}"`;
+      const opening = subject.charAt(0).toUpperCase() + subject.slice(1);
+      const unrealized = agreed(judgements, "unrealized");
+      if (unrealized.length > 0) {
+        ctx.addIssue(
+          "warning",
+          "UNREALIZED_PARAM",
+          `Method "${method.name}" of contract "${implementation.contract}" declares ${unrealized.length} parameter(s) ${subject} does not take \u2014 ${unrealized.map((found) => found.told).join(", ")}. The contract is promising an argument that would go nowhere, and nothing breaks at a call site to correct it: every brief and every caller built from the contract passes one. Take the parameter in the code, or drop it from the contract.`,
+          implementation.id,
+          draftContext,
+          void 0,
+          { at: method.name, covers: unrealized.map((found) => found.unit) }
+        );
+      }
+      const undeclared = agreed(judgements, "undeclared");
+      if (undeclared.length > 0) {
+        ctx.addIssue(
+          "warning",
+          "UNDECLARED_PARAM",
+          `${opening} realizing method "${method.name}" of contract "${implementation.contract}" takes ${undeclared.length} parameter(s) the contract does not declare and no declared injection accounts for \u2014 ${undeclared.map((found) => found.told).join(", ")}. An argument a caller must supply that the design never mentions is how a credential ends up in a signature nobody has read against its contract. Declare it on the contract, name it in the implementation's \`injectedParams\` when whatever wires this component up supplies it (a LEADING run only), or take it out of the signature.`,
+          implementation.id,
+          draftContext,
+          void 0,
+          { at: method.name, covers: undeclared.map((found) => found.unit) }
+        );
+      }
+      const renamed = agreed(judgements, "renamed");
+      if (renamed.length > 0) {
+        ctx.addIssue(
+          "warning",
+          "PARAM_NAME_MISMATCH",
+          `Method "${method.name}" of contract "${implementation.contract}" and ${subject} agree on position and type but not on name for ${renamed.length} parameter(s) \u2014 ${renamed.map((f) => f.told).join("; ")}. The contract, the ERD and every brief carry one word and the code answers to another, which is a rename nobody recorded rather than a different argument \u2014 the declared type agreeing is what says so. Rename one side to the other.`,
+          implementation.id,
+          draftContext,
+          void 0,
+          { at: method.name, covers: renamed.map((found) => found.unit) }
+        );
+      }
+      const disagreed = agreed(judgements, "optionality");
+      if (disagreed.length > 0) {
+        ctx.addIssue(
+          "warning",
+          "PARAM_OPTIONALITY",
+          `Method "${method.name}" of contract "${implementation.contract}" and ${subject} disagree about whether ${disagreed.length} parameter(s) may be left out \u2014 ${disagreed.map((f) => f.told).join("; ")}. One of them is telling a caller an argument is required when it is not, or the reverse. Omittable is the code's word for it: a default value and a rest parameter make an argument omittable exactly as a question mark does.`,
+          implementation.id,
+          draftContext,
+          void 0,
+          { at: method.name, covers: disagreed.map((found) => found.unit) }
+        );
+      }
+    }
+  }
+};
+
 // src/core/rules/conformance/unclaimed-source.ts
 var unclaimedSourceRule = {
   name: "unclaimed-source",
@@ -18343,11 +18521,14 @@ var SDD_RULES = [
   integrationSimWiringRule,
   integrationSimCoverageRule,
   // The data model's own claim on code — does the file hold the type, and is
-  // it the SHAPE the spec claims — and then the question no spec can ask from
-  // the spec side: which files are named by nothing at all. Last in the
-  // family because that one reads what all the others named.
+  // it the SHAPE the spec claims — then the SIGNATURE, the third reading:
+  // does the code take the arguments the contract promises. And then the
+  // question no spec can ask from the spec side: which files are named by
+  // nothing at all. Last in the family because that one reads what all the
+  // others named.
   typeRealizationRule,
   typeShapeRule,
+  paramConformanceRule,
   unclaimedSourceRule,
   exportConformanceRule,
   couplingRule,
@@ -18665,6 +18846,7 @@ function walkExact(ts, sourceText, fileName) {
   const fieldTypes = /* @__PURE__ */ new Map();
   const localTypes = /* @__PURE__ */ new Map();
   const typeShapes = /* @__PURE__ */ new Map();
+  const functionParams = /* @__PURE__ */ new Map();
   const mutableBindings = /* @__PURE__ */ new Set();
   const schemaConstants = /* @__PURE__ */ new Map();
   const derivedAliases = [];
@@ -18794,6 +18976,14 @@ function walkExact(ts, sourceText, fileName) {
     }
     return void 0;
   };
+  const declaredParameters = (fn) => (fn.parameters ?? []).map((parameter) => {
+    const fact = {
+      optional: !!parameter.questionToken || !!parameter.initializer || !!parameter.dotDotDotToken
+    };
+    if (ts.isIdentifier(parameter.name)) fact.name = parameter.name.text;
+    if (parameter.type) fact.type = parameter.type.getText(sf).replace(/\s+/g, " ").trim();
+    return fact;
+  });
   const collectFunctionFacts = (fn) => {
     let score = 1;
     const callees = /* @__PURE__ */ new Map();
@@ -18836,6 +19026,9 @@ function walkExact(ts, sourceText, fileName) {
       const sites = calls.get(fnName) ?? /* @__PURE__ */ new Map();
       for (const [key, site] of facts.callees) sites.set(key, site);
       calls.set(fnName, sites);
+      const signatures = functionParams.get(fnName) ?? [];
+      signatures.push(declaredParameters(node));
+      functionParams.set(fnName, signatures);
     }
     if (ts.isPropertyDeclaration(node)) recordFieldType(node.name, node.type);
     else if (ts.isParameter(node) && node.parent && ts.isConstructorDeclaration(node.parent) && isParameterProperty(node)) {
@@ -18943,7 +19136,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, mutableBindings, reexportOnly };
+  return { declared, anchors, exported, imports, reexports, starExports, namedReexports, complexity, calls, importBindings, typeOnlyBindings, fieldTypes, localTypes, typeShapes, functionParams, mutableBindings, reexportOnly };
 }
 function resolveRelativeModule(fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
@@ -19126,6 +19319,7 @@ function buildCodeModel(implementations, types, projectRoot, sourceRoots = [], e
             fieldTypes: Object.fromEntries([...facts.fieldTypes].map(([k, v]) => [k, [...v]])),
             localTypes: Object.fromEntries([...facts.localTypes].map(([k, v]) => [k, [...v]])),
             typeShapes: Object.fromEntries(facts.typeShapes),
+            functionParams: Object.fromEntries(facts.functionParams),
             topLevelMutableBindings: [...facts.mutableBindings],
             reexportOnly: facts.reexportOnly
           };