@beehexa/hexasync-template-context 2608.20.18 → 2608.20.31

package/dist/walk.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One walk over a composed component's steps, yielding every context finding in it — Story 8.13.
+ *
+ * ### Why this exists rather than living in the rule
+ *
+ * Story 8.6 measured `checkPath` and `unknownStepKey` against the corpus from a walk written inside its own spec, and
+ * Story 8.13 needs the same walk inside a validation rule. Two walks would be two chances to disagree about which
+ * stage key a pusher uses or where a webhook keeps its steps — and the 8.6 measurement had **exactly that bug**: it
+ * special-cased only `current` for pushers, so `pusher.before.*` was checked against `beforePullSteps`, a key a pusher
+ * does not have. It surfaced as 84 false findings the moment the rule widened.
+ *
+ * So the walk is here, both callers use it, and the corpus parity in 8.13 is structural rather than re-asserted.
+ */
+import { type ReferenceFinding } from './references.js';
+/** The four context phases, and the stage key each one is spelled with per collection. */
+export declare const PHASE_STAGE: Readonly<Record<'pullers' | 'pushers', Readonly<Record<string, string>>>>;
+export type ContextRuleId = 'root-has-no-child' | 'unknown-step-key';
+export interface ContextFinding extends ReferenceFinding {
+    /** Which of the two checks produced it, so a caller can choose a severity per rule. */
+    readonly rule: ContextRuleId;
+    /** The phase whose steps were being read, for the message and for locating the step. */
+    readonly phase: string;
+    /** The step the expression was authored in. `(step)` when the key is absent or not a scalar. */
+    readonly stepKey: string;
+    readonly stepIndex: number;
+}
+/**
+ * Every context finding in one component.
+ *
+ * ⚠️ Silent about two things by design, and the silences are load-bearing: an unknown ROOT may be a local variable or
+ * a loop binding, and a segment deeper than the step key may be composed at run time. A rule that reported those
+ * would fire on nearly every template in the corpus and be switched off within a day, taking the real findings with
+ * it.
+ */
+export declare function contextFindingsFor(component: unknown, collection: 'pullers' | 'pushers'): readonly ContextFinding[];
+//# sourceMappingURL=walk.d.ts.map

package/dist/walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.d.ts","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AAIzB,0FAA0F;AAC1F,eAAO,MAAM,WAAW,EAAE,QAAQ,CAChC,MAAM,CAAC,SAAS,GAAG,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CA4BhE,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,kBAAkB,CAAC;AAErE,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,uFAAuF;IACvF,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAQD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,OAAO,EAClB,UAAU,EAAE,SAAS,GAAG,SAAS,GAChC,SAAS,cAAc,EAAE,CAmH3B"}

package/dist/walk.js

@@ -0,0 +1,162 @@
+/**
+ * One walk over a composed component's steps, yielding every context finding in it — Story 8.13.
+ *
+ * ### Why this exists rather than living in the rule
+ *
+ * Story 8.6 measured `checkPath` and `unknownStepKey` against the corpus from a walk written inside its own spec, and
+ * Story 8.13 needs the same walk inside a validation rule. Two walks would be two chances to disagree about which
+ * stage key a pusher uses or where a webhook keeps its steps — and the 8.6 measurement had **exactly that bug**: it
+ * special-cased only `current` for pushers, so `pusher.before.*` was checked against `beforePullSteps`, a key a pusher
+ * does not have. It surfaced as 84 false findings the moment the rule widened.
+ *
+ * So the walk is here, both callers use it, and the corpus parity in 8.13 is structural rather than re-asserted.
+ */
+import { checkPath, expressionsIn, pathsIn, unknownStepKey, } from './references.js';
+import { resolveEnvironment, stepFactsFrom } from './environment.js';
+import { isNewKindPuller } from './detect.js';
+/** The four context phases, and the stage key each one is spelled with per collection. */
+export const PHASE_STAGE = {
+    pullers: {
+        before: 'beforePullSteps',
+        current: 'pullSteps',
+        after: 'afterPullSteps',
+        final: 'finalSteps',
+    },
+    /**
+     * ⛔ A pusher spells its phases `…PushSteps`. Measured 2026-08-14 across the corpus, counting KEY-LINE OCCURRENCES
+     * (`grep -rhoE '^\s+[a-zA-Z]+Steps:'`, which counts a key once per authored and per composed file):
+     * `beforePushSteps` 1,688 · `afterPushSteps` 1,654 · `pushSteps` 1,941.
+     *
+     * ⚠️ The BASIS matters and was missing when these were first recorded. Counting distinct components that declare
+     * the array instead gives ~1,612 / 1,625 / 1,939, and the Epic 8 review re-derived the occurrence figures as
+     * 1,661 / 1,630 / 1,914 with a slightly different expression — three methods, three answers, all defensible. The
+     * numbers are here to show the two spellings are of the same order, nothing finer; do not treat a small drift as
+     * a regression without re-running the exact command above.
+     *
+     * `finalSteps` appears **nowhere**, in either collection, on every method — so `final` is an empty phase by
+     * construction rather than by accident. That is the load-bearing part, and it is the one that reproduces exactly.
+     */
+    pushers: {
+        before: 'beforePushSteps',
+        current: 'pushSteps',
+        after: 'afterPushSteps',
+        final: 'finalSteps',
+    },
+};
+const arrayAt = (value, key) => {
+    const holder = value;
+    const at = holder?.[key];
+    return Array.isArray(at) ? at : [];
+};
+/**
+ * Every context finding in one component.
+ *
+ * ⚠️ Silent about two things by design, and the silences are load-bearing: an unknown ROOT may be a local variable or
+ * a loop binding, and a segment deeper than the step key may be composed at run time. A rule that reported those
+ * would fire on nearly every template in the corpus and be switched off within a day, taking the real findings with
+ * it.
+ */
+export function contextFindingsFor(component, collection) {
+    const holder = component;
+    if (!holder || typeof holder !== 'object')
+        return [];
+    const stages = PHASE_STAGE[collection];
+    const newKind = collection === 'pullers' && isNewKindPuller(holder);
+    const phases = {};
+    for (const phase of Object.keys(stages)) {
+        phases[phase] = arrayAt(holder, stages[phase]).map((step) => stepFactsFrom(step));
+    }
+    const keysByPhase = Object.fromEntries(Object.keys(stages).map((phase) => [
+        phase,
+        phases[phase].map((facts) => facts.key),
+    ]));
+    const position = (collection === 'pushers'
+        ? 'pusher-step'
+        : newKind
+            ? 'new-kind-puller-step'
+            : 'legacy-puller-step');
+    const findings = [];
+    for (const phase of Object.keys(stages)) {
+        arrayAt(holder, stages[phase]).forEach((step, stepIndex) => {
+            const environment = resolveEnvironment({
+                position,
+                component: { collection, hasStepsArray: newKind, phases },
+                phase,
+                stepIndex,
+            });
+            const raw = step?.['key'];
+            const stepKey = typeof raw === 'string' || typeof raw === 'number'
+                ? String(raw)
+                : '(step)';
+            /**
+             * ⛔ A step that will not serialize must not silence the whole family.
+             *
+             * `JSON.stringify` throws on a cyclic object, and `runValidation` swallows a throwing rule with a
+             * `console.warn` — so ONE such component would discard every CTX finding in the project, including the good
+             * ones already computed. The `yaml` parser does build cyclic objects from a recursive anchor
+             * (`a: &x { self: *x }`) and the cycle survives the CLI's parse/stringify round trip, so this is reachable
+             * rather than theoretical, even though no corpus file uses anchors today. Skipping one step is a bounded loss;
+             * losing the rule is not.
+             */
+            let serialized;
+            try {
+                serialized = JSON.stringify(step) ?? '';
+            }
+            catch {
+                return;
+            }
+            const seen = new Set();
+            for (const expression of expressionsIn(serialized)) {
+                for (const path of pathsIn(expression)) {
+                    /**
+                     * ⛔ Deduplicated PER STEP. One authored expression is commonly repeated across a step's fields — the
+                     * corpus's worst case reads the same broken watermark path seven times in one step — and seven identical
+                     * findings on one line is a report an author scrolls past. The measurement counts occurrences; a report
+                     * addresses lines.
+                     */
+                    if (seen.has(path))
+                        continue;
+                    seen.add(path);
+                    const rootFinding = checkPath(path, environment);
+                    if (rootFinding) {
+                        findings.push({
+                            ...rootFinding,
+                            rule: 'root-has-no-child',
+                            phase,
+                            stepKey,
+                            stepIndex,
+                        });
+                        continue;
+                    }
+                    /**
+                     * ⛔ The step-key check runs ONLY under a root this position actually has.
+                     *
+                     * `unknownStepKey` matches the segment name (`current`, `history`, …) wherever it appears; it does not
+                     * know whose context it is in. So a NEW-KIND puller — which shares no `puller.*` root at all (§3) —
+                     * produced `current has no step called X` for a path whose real problem is that `puller` does not exist
+                     * there. The corpus reported 0 such findings, which read like proof and was luck: no new-kind component
+                     * in it happens to carry a stale `puller.*` path. A unit test found it in one run.
+                     *
+                     * An unknown root stays SILENT rather than becoming a finding of its own — it may be a local variable or
+                     * a loop binding, which is the same reason `checkPath` leaves it alone.
+                     */
+                    const root = path.split('.')[0];
+                    if (!root || !environment.roots.has(root))
+                        continue;
+                    const stepFinding = unknownStepKey(path, keysByPhase);
+                    if (stepFinding) {
+                        findings.push({
+                            ...stepFinding,
+                            rule: 'unknown-step-key',
+                            phase,
+                            stepKey,
+                            stepIndex,
+                        });
+                    }
+                }
+            }
+        });
+    }
+    return findings;
+}
+//# sourceMappingURL=walk.js.map

package/dist/walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk.js","sourceRoot":"","sources":["../src/walk.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beehexa/hexasync-template-context",
-  "version": "2608.20.18",
+  "version": "2608.20.31",
   "description": "The authoring context engine — given a component and a caret, what an author may legally reference.",
   "license": "SEE LICENSE IN ../../LICENSE",
   "type": "module",