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

package/dist/index.js

@@ -1222,7 +1222,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.43";
+    WAIRON_VERSION = "5.1.1-dev.44";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -1574,6 +1574,11 @@ function passesIntentFloor(text, 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(method, implementationSourcePath) {
   return method.sourcePath || implementationSourcePath || void 0;
 }
@@ -2204,6 +2209,31 @@ var init_specs = __esm({
       intent: import_zod8.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_zod8.z.array(import_zod8.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
@@ -2240,7 +2270,16 @@ var init_specs = __esm({
        * stereotypes should bind tech directly (TECH_ON_LOGIC_COMPONENT).
        */
       technologies: import_zod8.z.array(import_zod8.z.string()).optional(),
-      methods: import_zod8.z.array(MethodImplementationSchema).default([]),
+      methods: import_zod8.z.array(MethodImplementationSchema).default([]).superRefine((methods, ctx) => {
+        methods.forEach((m, i) => {
+          if (!m.calls?.length || m.narrative.length === 0) return;
+          ctx.addIssue({
+            code: import_zod8.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). */
@@ -9784,16 +9823,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" }
@@ -9805,25 +9864,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
                 );
@@ -9834,16 +9903,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;
@@ -9853,19 +9922,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)
                   );
@@ -12556,15 +12625,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 {
@@ -12629,7 +12694,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 }
               );
             }
           }
@@ -12657,7 +12724,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 }
                 );
               }
             }
@@ -27361,6 +27432,7 @@ __export(src_exports, {
   packEntryLabel: () => packEntryLabel,
   packEntryRef: () => packEntryRef,
   packStoreDir: () => packStoreDir,
+  parseDeclaredCall: () => parseDeclaredCall,
   parseTemplate: () => parseTemplate,
   parseYaml: () => parseYaml,
   passesIntentFloor: () => passesIntentFloor,
@@ -28099,6 +28171,7 @@ function loadProjectConfig4() {
   packEntryLabel,
   packEntryRef,
   packStoreDir,
+  parseDeclaredCall,
   parseTemplate,
   parseYaml,
   passesIntentFloor,