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

package/dist/index.js

@@ -556,6 +556,31 @@ var init_project = __esm({
       kind: CarriedDebtKindSchema,
       /** The reason itself, in the author's own words — what is true here, and what paying it would take. */
       why: import_zod3.z.string().min(1),
+      /**
+       * This classification is PROVISIONAL, and this is what would settle it.
+       *
+       * A confident-sounding `why` that is wrong is worse than a missing one: it
+       * reads as settled, so nobody looks again, and the register keeps counting
+       * the finding under a kind that was never true. Nothing can check a reason
+       * for truth — `kind` and `why` are prose, and STALE_CARRIED_FINDING only
+       * ever catches "this stopped applying", never "this still applies for a
+       * reason that has become false". What a register CAN do is let an author say
+       * out loud that they are not sure yet, and then keep saying it: every run
+       * counts the groups marked here beside the kind totals, so the uncertainty
+       * is as loud as the debt.
+       *
+       * It is deliberately a SENTENCE and not a flag, and deliberately on the
+       * reason GROUP rather than the finding: what is provisional is the reason,
+       * and a reader deciding whether to pick this up needs to know what to
+       * measure — "is the adapter really realized by the file that consumes it, or
+       * is that a modelling error?" — not merely that somebody once hesitated. A
+       * finding whose own classification is uncertain while its neighbours' is not
+       * is a different reason, and belongs in its own group.
+       *
+       * There is no counterpart on `lint.allow`, and that is a decision, not an
+       * omission: see the note on ConformanceRuleConfig.carried.
+       */
+      revisit: import_zod3.z.string().min(1).optional(),
       /** The findings this reason explains. */
       findings: import_zod3.z.array(CarriedFindingSchema)
     });
@@ -601,6 +626,17 @@ var init_project = __esm({
        *   • every entry states its kind and its reason, and `wairon validate`
        *     prints the running total, so the debt is loud where a suppression is
        *     silent.
+       *
+       * A reason group may also declare itself PROVISIONAL (`revisit`), and the
+       * total says how many did. There is no such marker on a `lint.allow`, and
+       * the asymmetry is the point: an entry here does not silence anything — the
+       * finding is counted out loud on every run — so marking one uncertain adds a
+       * second dial to something already visible. An allow DOES silence, and a
+       * "provisional allow" would buy the silence and defer the decision, which is
+       * the one combination that cannot be reviewed: the finding is gone and the
+       * doubt is in a field nobody opens. The mechanism for a decision nobody has
+       * taken is to not take it — leave the warning firing — or, where the code is
+       * carryable, an entry of kind `undecided`, which is exactly that sentence.
        */
       carried: import_zod3.z.array(CarriedDebtSchema).optional()
     });
@@ -1186,7 +1222,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.42";
+    WAIRON_VERSION = "5.1.1-dev.43";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -1698,8 +1734,28 @@ var init_specs = __esm({
     LintAllowSchema = import_zod8.z.object({
       /** The issue code being allowed (see `wairon rules list`). */
       code: import_zod8.z.string(),
+      /**
+       * The SITE inside this spec the allow covers, named exactly as the finding
+       * names it (a contract method, an import edge "from -> to", a declared edge
+       * "component -> target"). A finding that names a site is covered ONLY by an
+       * allow naming that same site; a finding that names none is covered only by
+       * an allow that names none either.
+       */
+      at: import_zod8.z.string().min(1).optional(),
+      /**
+       * The units of an AGGREGATING finding this allow covers — the steps of one
+       * CALL_STEP_UNREALIZED, the crossings of one UNDECLARED_COLOCATED_CALL —
+       * each named the way the finding's own message names it. The allow silences
+       * the finding only when it lists EVERY unit reported, so a unit nobody
+       * decided on surfaces on the day it appears instead of inheriting a decision
+       * taken about its neighbours. Meaningless without `at`, and refused there.
+       */
+      covers: import_zod8.z.array(import_zod8.z.string()).optional(),
       /** Why this finding is acceptable here (e.g. "dispatcher — fan-out is the point"). */
       reason: import_zod8.z.string().min(1)
+    }).refine((a) => !a.covers?.length || !!a.at, {
+      message: "`covers` names the units of ONE finding, so it needs the `at` that says which finding \u2014 add the site, or drop covers.",
+      path: ["covers"]
     });
     LintConfigSchema = import_zod8.z.object({
       allow: import_zod8.z.array(LintAllowSchema).default([])
@@ -9640,10 +9696,10 @@ var init_lint_allows = __esm({
     "use strict";
     lintAllowsRule = {
       name: "lint-allows",
-      description: "Per-spec lint suppressions (lint.allow) must name real issue codes and actually suppress a finding \u2014 unknown codes and stale allows are flagged. Allows silence warnings only; errors always surface.",
+      description: "Per-spec lint suppressions (lint.allow) must name real issue codes and actually suppress a finding \u2014 unknown codes and stale allows are flagged. An allow covers exactly the occurrence it names: a finding that reports a site is silenced only by an allow whose `at` is that site, a finding that reports none only by an allow that names none, and an aggregating finding only by an allow whose `covers` lists every unit it reports \u2014 a unit nobody listed is named back as new instead of inheriting a decision taken about its neighbours. So a coarse allow left on a rule that names sites, and an allow whose site the run no longer reports, are both UNUSED_LINT_ALLOW, and the finding names the sites that did fire. Allows silence warnings only; errors always surface.",
       codes: [
         { code: "UNKNOWN_LINT_ALLOW_CODE", defaultSeverity: "warning", summary: "lint.allow names an issue code no registered rule emits" },
-        { code: "UNUSED_LINT_ALLOW", defaultSeverity: "warning", summary: "lint.allow entry matched no finding this run \u2014 remove the stale allow" }
+        { code: "UNUSED_LINT_ALLOW", defaultSeverity: "warning", summary: "lint.allow entry matched no finding this run \u2014 the code never fired, or it fired at sites this allow does not name" }
       ],
       check(ctx) {
         for (const a of ctx.lintAllows) {
@@ -9656,14 +9712,24 @@ var init_lint_allows = __esm({
             );
             continue;
           }
-          if (!a.used) {
-            ctx.addIssue(
-              "warning",
-              "UNUSED_LINT_ALLOW",
-              `Spec "${a.specId}" allows "${a.code}" (reason: ${a.reason}) but no such finding fired this run \u2014 remove the stale allow.`,
-              a.specId
-            );
+          if (a.used) continue;
+          const reported = ctx.sitesReported(a.specId, a.code);
+          const at = a.at ? ` at "${a.at}"` : "";
+          let why;
+          if (a.at && reported.unsited && reported.sites.length === 0) {
+            why = `findings of "${a.code}" on this spec name no site at all, so this allow must not name one \u2014 drop the \`at\``;
+          } else if (reported.sites.length > 0) {
+            const sites = reported.sites.map((s) => `"${s}"`).join("; ");
+            why = a.at ? `that code fired at ${sites} instead \u2014 retarget the allow, or remove it` : `that code fired at ${sites}, and a sited finding is covered only by an allow naming its site \u2014 give this allow an \`at\` (one per site, each with its own reason), or remove it`;
+          } else {
+            why = "no such finding fired this run \u2014 remove the stale allow";
           }
+          ctx.addIssue(
+            "warning",
+            "UNUSED_LINT_ALLOW",
+            `Spec "${a.specId}" allows "${a.code}"${at} (reason: ${a.reason}), but ${why}.`,
+            a.specId
+          );
         }
       }
     };
@@ -13682,7 +13748,13 @@ var init_dependency_conformance = __esm({
               "UNDECLARED_DEPENDENCY",
               `"${fromPath}" (realizing ${fromComponents.map((c) => c.id).join(", ")}) imports "${toPath}" (realizing ${toComponents.map((c) => c.id).join(", ")}) but no declared dependsOn/owns edge justifies it \u2014 declare the collaboration on the component that actually uses it, or route the cross-subsystem hop through the target's published surface.`,
               realization.implementationsAt(fromPath)[0]?.id,
-              draftAt(fromPath) || draftAt(toPath)
+              draftAt(fromPath) || draftAt(toPath),
+              void 0,
+              // One import edge, one indivisible fact — but one implementation
+              // maps many files and many edges, so the EDGE is the site, not the
+              // spec. Without it a single allow on the spec covers every crossing
+              // that file ever grows.
+              { at: `${fromPath} -> ${toPath}` }
             );
           }
         }
@@ -13709,7 +13781,12 @@ var init_dependency_conformance = __esm({
               "UNREALIZED_DEPENDENCY",
               `Component "${component.id}" declares ${relation} "${targetId}", but no runtime import connects their source files (${fromFiles.join(", ")} \u219B ${crossSubsystem ? `subsystem ${target.subsystem}` : filesOf(targetId).join(", ")}) \u2014 either the collaboration is wired indirectly (DI) or the declared edge is stale.`,
               impls[0]?.id ?? component.id,
-              draft
+              draft,
+              void 0,
+              // One declared edge, one indivisible fact. A component declares many,
+              // and they all anchor on its one implementation spec, so the EDGE is
+              // the site.
+              { at: `${component.id} -> ${targetId}` }
             );
           }
         }
@@ -14068,7 +14145,7 @@ var init_carried_debt = __esm({
     "use strict";
     carriedDebtRule = {
       name: "carried-debt",
-      description: "The conformance debt register (`rules.conformance.carried`) holds the code\u2194spec findings this tree carries as declared, classified debt \u2014 `unclaimed`'s one-way shape, for findings about code a spec does name. It is not a second lint.allow: an allow says a finding is wrong here by design, an entry here says the finding is right and unpaid, and each entry states which of the three kinds it is (drift: spec and code disagree; undecided: the fix waits on a modelling decision nobody has taken; unreadable: the analysis cannot follow the shape the code is written in) and why. Only a code a rule declares CARRYABLE may appear, and naming any other is an error, so the register can never widen into general-purpose suppression. An entry carries a finding only when it lists EVERY unit that finding reports, so an aggregating finding cannot grow behind it; an entry that matched nothing, that duplicates another, that names a spec the tree does not hold, or that lists a unit no longer reported is STALE_CARRIED_FINDING, so the register only shrinks. The audit is silent in a run that could not have fired the findings at all: one that built no code model, the specs outside a scoped run, and a code the project switched off.",
+      description: "The conformance debt register (`rules.conformance.carried`) holds the code\u2194spec findings this tree carries as declared, classified debt \u2014 `unclaimed`'s one-way shape, for findings about code a spec does name. It is not a second lint.allow: an allow says a finding is wrong here by design, an entry here says the finding is right and unpaid, and each entry states which of the three kinds it is (drift: spec and code disagree; undecided: the fix waits on a modelling decision nobody has taken; unreadable: the analysis cannot follow the shape the code is written in) and why. Only a code a rule declares CARRYABLE may appear, and naming any other is an error, so the register can never widen into general-purpose suppression. An entry carries a finding only when it lists EVERY unit that finding reports, so an aggregating finding cannot grow behind it; an entry that matched nothing, that duplicates another, that names a spec the tree does not hold, or that lists a unit no longer reported is STALE_CARRIED_FINDING, so the register only shrinks. The audit is silent in a run that could not have fired the findings at all: one that built no code model, the specs outside a scoped run, and a code the project switched off. Nothing can check a reason for TRUTH \u2014 a stale entry is one that stopped applying, never one that still applies for a reason that has become false \u2014 so a reason group may declare its own classification provisional (`revisit`: what would settle it), and every run counts those findings beside the kind totals.",
       codes: [
         { code: "UNCARRYABLE_FINDING", defaultSeverity: "error", summary: "The conformance debt register names an issue code no rule emits, or one no rule declares carryable \u2014 the register holds measured code\u2194spec debt, never a design rule somebody wants quiet" },
         { code: "STALE_CARRIED_FINDING", defaultSeverity: "warning", summary: "An entry of the conformance debt register carries a finding that no longer fires, or lists a unit that finding no longer reports \u2014 delete it, the register only shrinks" }
@@ -16446,12 +16523,20 @@ function buildRuleContext(opts) {
   const allowLookup = /* @__PURE__ */ new Map();
   const collectAllows = (specId, lint) => {
     for (const a of lint?.allow ?? []) {
-      const entry = { specId, code: a.code, reason: a.reason, used: false };
+      const entry = { specId, code: a.code, at: a.at, covers: a.covers, reason: a.reason, used: false };
       lintAllows.push(entry);
       if (!allowLookup.has(specId)) allowLookup.set(specId, /* @__PURE__ */ new Map());
-      allowLookup.get(specId).set(a.code, entry);
+      const forSpec = allowLookup.get(specId);
+      const forCode = forSpec.get(a.code) ?? [];
+      forCode.push(entry);
+      forSpec.set(a.code, forCode);
     }
   };
+  const sitesSeen = /* @__PURE__ */ new Map();
+  const sitesReported = (specId, code) => {
+    const seen = sitesSeen.get(`${specId}\0${code}`);
+    return { sites: [...seen?.sites ?? []], unsited: seen?.unsited ?? false };
+  };
   for (const s of subsystems) collectAllows(s.id, s.lint);
   for (const c of components) collectAllows(c.id, c.lint);
   for (const i of interfaces) collectAllows(i.id, i.lint);
@@ -16488,15 +16573,29 @@ function buildRuleContext(opts) {
     }
     const severity = getRuleSeverity(code, defaultSeverity, isDraftContext, owner);
     if (severity === "off") return;
+    let text = message;
+    if (specId) {
+      const key = `${specId}\0${code}`;
+      let seen = sitesSeen.get(key);
+      if (!seen) sitesSeen.set(key, seen = { sites: /* @__PURE__ */ new Set(), unsited: false });
+      if (parts) seen.sites.add(parts.at);
+      else seen.unsited = true;
+    }
+    let allowClaimed = false;
     if (specId) {
-      const allow = allowLookup.get(specId)?.get(code);
+      const allow = (allowLookup.get(specId)?.get(code) ?? []).find((a) => parts ? a.at === parts.at : a.at === void 0);
       if (allow) {
         allow.used = true;
-        if (severity === "warning") return;
+        allowClaimed = true;
+        const grew = (parts?.covers ?? []).filter((unit) => !(allow.covers ?? []).includes(unit));
+        if (grew.length === 0) {
+          if (severity === "warning") return;
+        } else {
+          text = `${text} A lint.allow covers this site, but not ${grew.length} part(s) of it \u2014 ${grew.map((u) => `"${u}"`).join("; ")} ${grew.length === 1 ? "is" : "are"} new. Decide on them: add them to the allow's \`covers\` with a reason that is actually true, or fix them.`;
+        }
       }
     }
-    let text = message;
-    if (specId && parts && severity === "warning") {
+    if (specId && parts && severity === "warning" && !allowClaimed) {
       const entry = carriedLookup.get(carriedKey(specId, code, parts.at));
       if (entry) {
         entry.fired = true;
@@ -16589,6 +16688,7 @@ function buildRuleContext(opts) {
     codeModel: opts.codeModel ?? emptyCodeModel(),
     roundTripIssues: opts.roundTripIssues,
     lintAllows,
+    sitesReported,
     knownIssueCodes: opts.knownIssueCodes,
     carriedFindings,
     carryableIssueCodes: opts.carryableIssueCodes ?? /* @__PURE__ */ new Set(),
@@ -19143,9 +19243,11 @@ function identityKeyOf(field, item) {
       return `${String(o.topic)} ${o.event === void 0 ? "" : String(o.event)}`;
     case "trustedLinks":
       return str(o.subsystem);
+    // lint.allow: an allow is one decision about one OCCURRENCE, so several
+    // may share a code on one spec, each naming its own site. Keyed by code
+    // alone a delta for one site would overwrite its neighbours.
     case "allow":
-      return str(o.code);
-    // lint.allow
+      return `${String(o.code)} ${o.at === void 0 ? "" : String(o.at)}`;
     case "findings":
       return str(o.code);
     // an interface method's findings
@@ -19233,6 +19335,7 @@ function identityFieldsOf(field) {
     case "trustedLinks":
       return ["subsystem"];
     case "allow":
+      return ["code", "at"];
     case "findings":
       return ["code"];
     case "invariants":