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

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.64";
+    WAIRON_VERSION = "5.1.1-dev.65";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -2423,6 +2423,24 @@ var init_specs = __esm({
        * 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;
@@ -14080,6 +14098,173 @@ var init_type_shape = __esm({
   }
 });
 
+// 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;
+var init_param_conformance = __esm({
+  "src/core/rules/conformance/param-conformance.ts"() {
+    "use strict";
+    init_models();
+    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 = (text2) => text2.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: method2, sourceFile, draftContext } of ctx.implementationMethods()) {
+          const contract = ctx.interfaceMap.get(implementation.contract);
+          const declared = contract?.methods.find((m) => m.name === method2.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 = method2.symbol ?? method2.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 "${method2.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: method2.name, covers: unrealized.map((found) => found.unit) }
+            );
+          }
+          const undeclared = agreed(judgements, "undeclared");
+          if (undeclared.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "UNDECLARED_PARAM",
+              `${opening} realizing method "${method2.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: method2.name, covers: undeclared.map((found) => found.unit) }
+            );
+          }
+          const renamed = agreed(judgements, "renamed");
+          if (renamed.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "PARAM_NAME_MISMATCH",
+              `Method "${method2.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: method2.name, covers: renamed.map((found) => found.unit) }
+            );
+          }
+          const disagreed = agreed(judgements, "optionality");
+          if (disagreed.length > 0) {
+            ctx.addIssue(
+              "warning",
+              "PARAM_OPTIONALITY",
+              `Method "${method2.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: method2.name, covers: disagreed.map((found) => found.unit) }
+            );
+          }
+        }
+      }
+    };
+  }
+});
+
 // src/core/rules/conformance/unclaimed-source.ts
 var unclaimedSourceRule;
 var init_unclaimed_source = __esm({
@@ -15584,6 +15769,7 @@ var init_repository = __esm({
     init_integration_sim_coverage();
     init_type_realization();
     init_type_shape();
+    init_param_conformance();
     init_unclaimed_source();
     init_export_conformance();
     init_carried_debt();
@@ -15752,11 +15938,14 @@ var init_repository = __esm({
       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,
@@ -15925,6 +16114,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 = [];
@@ -16054,6 +16244,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();
@@ -16096,6 +16294,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)) {
@@ -16203,7 +16404,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;
@@ -16386,6 +16587,7 @@ function buildCodeModel(implementations, types, projectRoot2, sourceRoots = [],
             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
           };
@@ -30005,6 +30207,7 @@ function createMcpServer(options = {}) {
     sourcePath: import_zod11.z.string().optional().describe("Optional: target source code file path relative to project root \u2014 for a chained subproject's implementation (qualified id), relative to that subproject's root; a path given relative to this root that lands inside the subproject is re-expressed for you"),
     simPath: import_zod11.z.string().optional().describe("Optional: the committed integration-sim harness file (project-relative; N:1 sharing allowed). The validator proves it exists and its import graph wires the REAL modules (this component + each direct dependency; technology adapters may stay faked) \u2014 running it is CI's job. Declaring the first simPath in a subsystem activates MISSING_INTEGRATION_SIM for its other complete non-leaf implementations"),
     technologies: import_zod11.z.array(import_zod11.z.string()).optional().describe(`External technologies this implementation binds to (e.g. ["mysql"]) \u2014 declares this component's ownership tree as the technology's home; references outside it are flagged (TECH_LEAKAGE) and contract identifiers must stay intent-language. Only for Adapter/Store/Registry/Index components.`),
+    injectedParams: import_zod11.z.array(import_zod11.z.string()).optional().describe("The parameter names this realization takes BEFORE the ones its contract declares \u2014 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 here and not to the contract: another realization may hold them as fields instead. Declared rather than guessed, because a leading parameter the contract does not name cannot be told from one it named under a different name (`seed(config)` realized as `bootstrapInstance(cfg)`); a leading parameter this list does not name is reported (UNDECLARED_PARAM). Only a LEADING run is dropped \u2014 one of these names appearing after the contract's own parameters is an argument in the middle of the caller's list, not wiring"),
     detail: detailEnum.optional().describe("Spec-level narrative detail default for all methods"),
     conformance: conformanceEnum.optional().describe("Spec-level conformance tier default: declared | anchored | off (omitted = stereotype default: Portal \u2192 anchored, else declared)"),
     methods: import_zod11.z.array(import_zod11.z.object(implMethodShape).strict()).optional().describe("Method implementations containing L5 narratives"),
@@ -30015,11 +30218,11 @@ function createMcpServer(options = {}) {
     server,
     "sdd_write_narrative",
     {
-      description: "Write L4 Concrete Implementation spec containing L5 method narratives. Narratives are a FLAT ordered step list; flow steps (branch/switch/loop/try/parallel/jump/return/throw) jump by step number \u2014 blocks are just skipped regions. Steps may declare a `label` anchor, and every jump field has a *Label twin (toLabel, onTrueLabel, endLabel, \u2026) resolved to step numbers at write time \u2014 prefer labels over hand-counted numbers; an unresolvable label rejects the write. Detail dial per method: full (narrative required) | calls-only (call choreography suffices) | intent (prose instead of steps); omitted = stereotype default (Portal/Observer/Adapter: calls-only, Store/Index/Registry: intent, else full). A method whose narrative shows no steps declares the calls it makes in `calls` (one \"<component>.<method>\" each): the reachability walk takes exactly those edges and no others, so an intent-level method that reaches a collaborator must name it or that collaborator is reported unused. Conformance dial per method or spec: declared | anchored | off \u2014 how strictly structural conformance requires contract methods to be realized in their source file (omitted = Portal: anchored, else declared). A method whose body lives in its own file names it in the method's sourcePath; the implementation's sourcePath is the default for every method that names none. Re-authoring an existing id REPLACES the method list: a method left out of the input is REMOVED together with its narrative (and reported); spec-level lint/ext are carried forward, and the stored status is kept unless this input states a higher one. The answer carries a write receipt as structured content beside the sentence \u2014 the status written, whether a spec already held the id, and the notices a restatement raised, each as its own entry.",
+      description: "Write L4 Concrete Implementation spec containing L5 method narratives. Narratives are a FLAT ordered step list; flow steps (branch/switch/loop/try/parallel/jump/return/throw) jump by step number \u2014 blocks are just skipped regions. Steps may declare a `label` anchor, and every jump field has a *Label twin (toLabel, onTrueLabel, endLabel, \u2026) resolved to step numbers at write time \u2014 prefer labels over hand-counted numbers; an unresolvable label rejects the write. Detail dial per method: full (narrative required) | calls-only (call choreography suffices) | intent (prose instead of steps); omitted = stereotype default (Portal/Observer/Adapter: calls-only, Store/Index/Registry: intent, else full). A method whose narrative shows no steps declares the calls it makes in `calls` (one \"<component>.<method>\" each): the reachability walk takes exactly those edges and no others, so an intent-level method that reaches a collaborator must name it or that collaborator is reported unused. Conformance dial per method or spec: declared | anchored | off \u2014 how strictly structural conformance requires contract methods to be realized in their source file (omitted = Portal: anchored, else declared). A method whose body lives in its own file names it in the method's sourcePath; the implementation's sourcePath is the default for every method that names none. Parameters the realization takes BEFORE its contract's own \u2014 a config object, a data root, a portal's transport handles \u2014 are wiring, and are declared once for the spec in injectedParams; a leading parameter it does not name is reported against the contract (UNDECLARED_PARAM). Re-authoring an existing id REPLACES the method list: a method left out of the input is REMOVED together with its narrative (and reported); spec-level lint/ext are carried forward, and the stored status is kept unless this input states a higher one. The answer carries a write receipt as structured content beside the sentence \u2014 the status written, whether a spec already held the id, and the notices a restatement raised, each as its own entry.",
       inputSchema: implInput,
       outputSchema: specWriteReceiptOutput
     },
-    ({ id, name, description, contract, sourcePath, simPath, technologies, detail, conformance, methods, status: status2 }) => {
+    ({ id, name, description, contract, sourcePath, simPath, technologies, injectedParams, detail, conformance, methods, status: status2 }) => {
       try {
         const { loadInterfaceSpec: loadInterfaceSpec2, loadImplementationSpec: loadImplementationSpec2, saveImplementationSpec: saveImplementationSpec2 } = requireSpecs();
         const intf = loadInterfaceSpec2(contract);
@@ -30051,6 +30254,7 @@ function createMcpServer(options = {}) {
           sourcePath,
           simPath,
           technologies,
+          injectedParams,
           detail,
           conformance,
           // Post-resolution every cases/catches entry has its numeric step —