@wairon/cli 5.1.1-dev.43 → 5.1.1-dev.45

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.43";
+    WAIRON_VERSION = "5.1.1-dev.45";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     SUPPORTED_ALIASES = ["wai"];
     SCAN_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
@@ -1287,6 +1287,11 @@ function passesIntentFloor(text2, methodName) {
   if (norm(t) === norm(methodName)) return false;
   return true;
 }
+function parseDeclaredCall(ref) {
+  const at = ref.lastIndexOf(".");
+  if (at <= 0 || at === ref.length - 1) return null;
+  return { compId: ref.slice(0, at), methodName: ref.slice(at + 1) };
+}
 function methodSourceFile(method2, implementationSourcePath) {
   return method2.sourcePath || implementationSourcePath || void 0;
 }
@@ -1917,6 +1922,31 @@ var init_specs = __esm({
       intent: import_zod7.z.string().optional(),
       /** Conformance tier for THIS method (overrides the spec-level default). */
       conformance: ConformanceTierSchema.optional(),
+      /**
+       * The calls this method makes, when its narrative does not show them.
+       *
+       * The mirror of the contract's `invokedBy`: that declares the caller
+       * OUTSIDE the modeled graph, this declares the callees INSIDE it. It lives
+       * here and not on the L3 method because what a method CALLS is a property
+       * of the realization — the detail dial that hides the steps is here, and two
+       * implementations of one contract may reach different collaborators —
+       * whereas an external caller is a fact about the contract's role that must
+       * hold for every realization.
+       *
+       * Each entry names one target the way the debt register and a lint allow
+       * name a unit: `<component>.<method>` (a `covers` entry is the same
+       * spelling with the step number a declaration has no equivalent of). A
+       * third vocabulary for "which method" would be the worse outcome.
+       *
+       * The narrative graph walk takes exactly these edges for a method with no
+       * narrative, and NOTHING else: an undeclared collaborator is not reached,
+       * so a lower detail dial no longer vouches for everything the component
+       * declares. Each entry gets the same target validation a `call` step gets
+       * (the component resolves, the caller declares it, the method is on its
+       * contract). Refused beside a non-empty narrative, where the steps already
+       * say what is called and a second spelling could only disagree.
+       */
+      calls: import_zod7.z.array(import_zod7.z.string().min(1)).optional(),
       /**
        * The code-level name realizing this contract method in the sourcePath
        * file, when it legitimately differs from the intent-language contract
@@ -1953,7 +1983,16 @@ var init_specs = __esm({
        * stereotypes should bind tech directly (TECH_ON_LOGIC_COMPONENT).
        */
       technologies: import_zod7.z.array(import_zod7.z.string()).optional(),
-      methods: import_zod7.z.array(MethodImplementationSchema).default([]),
+      methods: import_zod7.z.array(MethodImplementationSchema).default([]).superRefine((methods, ctx) => {
+        methods.forEach((m, i) => {
+          if (!m.calls?.length || m.narrative.length === 0) return;
+          ctx.addIssue({
+            code: import_zod7.z.ZodIssueCode.custom,
+            path: [i, "calls"],
+            message: `Method "${m.name}" declares calls AND a narrative \u2014 \`calls\` says what a method calls when its narrative does not show it, and this one has ${m.narrative.length} step(s) that already do. Add the call step, or drop the declaration.`
+          });
+        });
+      }),
       /** Spec-level narrative detail default for all methods (each may override). */
       detail: NarrativeDetailSchema.optional(),
       /** Spec-level conformance tier default (each method may override). */
@@ -9838,16 +9877,36 @@ var init_contract_symmetry = __esm({
 });
 
 // src/core/rules/narrative/narrative-target-references.ts
-var narrativeTargetReferencesRule;
+var targetsOf, narrativeTargetReferencesRule;
 var init_narrative_target_references = __esm({
   "src/core/rules/narrative/narrative-target-references.ts"() {
     "use strict";
+    init_models();
+    targetsOf = (implMethod) => {
+      const entries = [];
+      for (const step of implMethod.narrative) {
+        if (step.type !== "call" && step.type !== "dispatch" && step.type !== "register") continue;
+        entries.push({
+          kind: step.type,
+          stepNumber: step.stepNumber,
+          targetComponent: step.targetComponent,
+          targetMethod: step.targetMethod,
+          assertsGuarantees: step.assertsGuarantees
+        });
+      }
+      for (const ref of implMethod.calls ?? []) {
+        const parsed = parseDeclaredCall(ref);
+        entries.push(parsed ? { kind: "declared", targetComponent: parsed.compId, targetMethod: parsed.methodName } : { kind: "declared", unparsed: ref });
+      }
+      return entries;
+    };
     narrativeTargetReferencesRule = {
       name: "narrative-target-references",
-      description: "A narrative call, dispatch or register step must name a target component, and a target method unless it dispatches. A target this tree contains must be a collaborator the calling component declares, must carry the named method on one of its interfaces, and that method must declare every semantic guarantee the step asserts.",
+      description: `A narrative call, dispatch or register step must name a target component, and a target method unless it dispatches; a method's declared calls name the same pair as one "<component>.<method>" reference, the spelling the conformance debt register and a lint allow name a unit with. A target this tree contains must be a collaborator the calling component declares, must carry the named method on one of its interfaces, and that method must declare every semantic guarantee the entry asserts.`,
       codes: [
         { code: "MISSING_TARGET_COMPONENT", defaultSeverity: "error", summary: "Call/register step missing targetComponent" },
         { code: "MISSING_TARGET_METHOD", defaultSeverity: "error", summary: "Call/register step missing targetMethod" },
+        { code: "MALFORMED_DECLARED_CALL", defaultSeverity: "error", summary: 'Declared call that is not a "<component>.<method>" reference' },
         { code: "UNDECLARED_DEPENDENCY_CALL", defaultSeverity: "error", summary: "Call step targets a component the caller does not depend on or own" },
         { code: "INVALID_TARGET_METHOD_REFERENCE", defaultSeverity: "error", summary: "Call step targets a method not on any target interface" },
         { code: "NARRATIVE_SEMANTIC_UNBACKED", defaultSeverity: "warning", summary: "Narrative asserts a guarantee the called contract does not declare" }
@@ -9859,25 +9918,35 @@ var init_narrative_target_references = __esm({
           const isDraftCtx = ctx.isImplementationDraft(impl);
           const caller = ctx.componentMap.get(contract.component);
           for (const implMethod of impl.methods) {
-            for (const step of implMethod.narrative) {
-              if (step.type !== "call" && step.type !== "dispatch" && step.type !== "register") continue;
-              if (!step.targetComponent) {
+            for (const entry of targetsOf(implMethod)) {
+              const where = entry.stepNumber === void 0 ? "" : ` (step ${entry.stepNumber})`;
+              if (entry.unparsed !== void 0) {
+                ctx.addIssue(
+                  "error",
+                  "MALFORMED_DECLARED_CALL",
+                  `Method "${implMethod.name}" in implementation "${impl.id}" declares the call "${entry.unparsed}", which is not a "<component>.<method>" reference \u2014 the spelling the conformance debt register and a lint allow name a unit with.`,
+                  impl.id,
+                  isDraftCtx
+                );
+                continue;
+              }
+              if (!entry.targetComponent) {
                 ctx.addIssue(
                   "error",
                   "MISSING_TARGET_COMPONENT",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${step.type} step (${step.stepNumber}) missing "targetComponent".`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${entry.kind} step (${entry.stepNumber}) missing "targetComponent".`,
                   impl.id,
                   isDraftCtx
                 );
                 continue;
               }
-              const target = step.targetComponent;
-              const verb = step.type === "dispatch" ? "dispatches through" : step.type === "register" ? "registers callback" : "calls";
-              if (step.type !== "dispatch" && !step.targetMethod) {
+              const target = entry.targetComponent;
+              const verb = entry.kind === "dispatch" ? "dispatches through" : entry.kind === "register" ? "registers callback" : entry.kind === "declared" ? "declares a call to" : "calls";
+              if (entry.kind !== "dispatch" && !entry.targetMethod) {
                 ctx.addIssue(
                   "error",
                   "MISSING_TARGET_METHOD",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${step.type} step (${step.stepNumber}) missing "targetMethod".`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${entry.kind} step (${entry.stepNumber}) missing "targetMethod".`,
                   impl.id,
                   isDraftCtx
                 );
@@ -9888,16 +9957,16 @@ var init_narrative_target_references = __esm({
                 ctx.addIssue(
                   "error",
                   "UNDECLARED_DEPENDENCY_CALL",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" (component "${caller.id}") ${verb} component "${target}" (step ${step.stepNumber}) but component "${caller.id}" does not list "${target}" as a dependency.`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" (component "${caller.id}") ${verb} component "${target}"${where} but component "${caller.id}" does not list "${target}" as a dependency.`,
                   impl.id,
                   isDraftCtx || ctx.isComponentDraft(caller.id)
                 );
               }
-              if (step.type === "dispatch") continue;
+              if (entry.kind === "dispatch") continue;
               const targetInterfaces = ctx.interfacesByComponent.get(target) ?? [];
               let targetMethodSpec;
               for (const targetIntf of targetInterfaces) {
-                const found = targetIntf.methods.find((m) => m.name === step.targetMethod);
+                const found = targetIntf.methods.find((m) => m.name === entry.targetMethod);
                 if (found) {
                   targetMethodSpec = found;
                   break;
@@ -9907,19 +9976,19 @@ var init_narrative_target_references = __esm({
                 ctx.addIssue(
                   "error",
                   "INVALID_TARGET_METHOD_REFERENCE",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} method "${step.targetMethod}" on component "${target}" which is not defined on any of its interfaces (step ${step.stepNumber}).`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} method "${entry.targetMethod}" on component "${target}" which is not defined on any of its interfaces${where}.`,
                   impl.id,
                   isDraftCtx || ctx.isComponentDraft(target)
                 );
                 continue;
               }
               const declared = new Set(targetMethodSpec.guarantees ?? []);
-              for (const g of step.assertsGuarantees ?? []) {
+              for (const g of entry.assertsGuarantees ?? []) {
                 if (!declared.has(g)) {
                   ctx.addIssue(
                     "warning",
                     "NARRATIVE_SEMANTIC_UNBACKED",
-                    `Step ${step.stepNumber} of "${implMethod.name}" in implementation "${impl.id}" explicitly asserts guarantee "${g}", but the method it calls \u2014 "${step.targetMethod}" on "${target}" \u2014 does not list "${g}" among its L3 contract guarantees. Declare it on that method (and ensure its shape can deliver it), or revise the narrative.`,
+                    `Step ${entry.stepNumber} of "${implMethod.name}" in implementation "${impl.id}" explicitly asserts guarantee "${g}", but the method it calls \u2014 "${entry.targetMethod}" on "${target}" \u2014 does not list "${g}" among its L3 contract guarantees. Declare it on that method (and ensure its shape can deliver it), or revise the narrative.`,
                     impl.id,
                     isDraftCtx || ctx.isComponentDraft(target)
                   );
@@ -12610,15 +12679,11 @@ function walk(ctx, seeds, options = {}) {
         if (edge.methodName) enqueueMethod(edge.compId, edge.methodName);
       }
     }
-    if (methodImpl.narrative.length === 0) {
-      const comp = ctx.componentMap.get(compId);
-      if (comp && effectiveDetail(methodImpl, impl, comp).level !== "full") {
-        for (const depId of [...comp.dependsOn, ...comp.owns]) {
-          if (!ctx.componentMap.has(depId)) continue;
-          reachComponent(depId);
-          enqueueAllMethods(depId);
-        }
-      }
+    for (const ref of methodImpl.calls ?? []) {
+      const parsed = parseDeclaredCall(ref);
+      if (!parsed || !ctx.componentMap.has(parsed.compId)) continue;
+      reachComponent(parsed.compId);
+      enqueueMethod(parsed.compId, parsed.methodName);
     }
   }
   return {
@@ -12683,7 +12748,9 @@ var init_unused_detection = __esm({
                 "INVOKED_BY_REDUNDANT",
                 `Method "${m.name}" on component "${intf.component}" declares invokedBy (${m.invokedBy.kind}), but the internal narrative walk already reaches it \u2014 the declaration is stale; remove it.`,
                 intf.id,
-                isDraftCtx
+                isDraftCtx,
+                void 0,
+                { at: m.name }
               );
             }
           }
@@ -12711,7 +12778,11 @@ var init_unused_detection = __esm({
                   "UNUSED_METHOD",
                   `Method "${m.name}" on component "${comp.id}" is defined but never called by any narrative step.`,
                   intf.id,
-                  isDraftCtx
+                  isDraftCtx,
+                  void 0,
+                  // The site is the method, so an allow covers exactly the one it
+                  // names - never its neighbours on the same interface.
+                  { at: m.name }
                 );
               }
             }
@@ -28723,7 +28794,8 @@ function createMcpServer(options = {}) {
     conformance: conformanceEnum.optional().describe("Conformance tier for this method (overrides the spec default)"),
     symbol: import_zod11.z.string().optional().describe("Code-level name realizing this contract method in the sourcePath file, when it legitimately differs from the intent-language contract name (e.g. put realized by saveSnapshot)"),
     ext: import_zod11.z.record(import_zod11.z.unknown()).optional().describe("Opaque pack/tool extension data for this method (namespaced keys) \u2014 preserved verbatim"),
-    narrative: import_zod11.z.array(narrativeStepInput).optional()
+    narrative: import_zod11.z.array(narrativeStepInput).optional(),
+    calls: import_zod11.z.array(import_zod11.z.string().min(1)).optional().describe('The calls this method makes, when its narrative does not show them (detail: intent, or calls-only with no steps authored) \u2014 each as "<component>.<method>", the spelling the debt register and lint allows name a unit with. The narrative walk takes exactly these edges and no others, so an undeclared collaborator is NOT reached: this is what keeps unused-detection honest at a lower detail dial. Each entry is validated like a call step (the component resolves, this component declares it, the method is on its contract). Refused beside a non-empty narrative \u2014 add the call step there instead')
   };
   const implMethodInputFields = Object.keys(implMethodShape);
   const implInput = {
@@ -28744,7 +28816,7 @@ 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). 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. 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
     },