@objectstack/lint 17.0.0-rc.4 → 17.0.0-rc.6

package/dist/{runtime-Cs64ShwN.d.cts → runtime-B50yywI_.d.cts}

@@ -55,10 +55,8 @@ type AuthoringRuleTier = 'gating' | 'advisory';
 /**
  * Which tier of the stack a rule reads.
  *
- * - `normalized` — the `normalizeStackInput` output, BEFORE the Zod parse. The
- *   rules that need it check keys the parse strips (a flat list view in
- *   `views: []`, `userFilters` on an object list view, a `visibleOn` alias): by
- *   the time `result.data` exists the evidence is gone.
+ * - `normalized` — the `normalizeStackInput` output, run before this package's
+ *   caller had a chance to Zod-parse.
  * - `parsed` — the post-parse stack, where defaults are filled and shapes are
  *   settled.
  *
@@ -66,6 +64,53 @@ type AuthoringRuleTier = 'gating' | 'advisory';
  * `os validate`'s verdict to give), so it runs BOTH tiers on the normalized
  * stack. Every rule here is written to tolerate that — it is what `os lint`
  * already did for the reference-integrity suite and the security linter.
+ *
+ * ## What `normalized` does NOT buy, measured (#6073)
+ *
+ * This tier used to be justified as "the rules that need it check keys the
+ * parse strips — a flat list view in `views: []`, `userFilters` on an object
+ * list view, a `visibleOn` alias — by the time `result.data` exists the
+ * evidence is gone". **All three of those examples were measured false**, each
+ * for its own reason, and the pins live in `authoring-rule-input-tier.test.ts`:
+ *
+ *  1. `defineStack` — the documented and universal way a TS config declares a
+ *     stack — PARSES at definition time, so for such a config the value every
+ *     command hands this registry is already `result.data`: parse-time defaults
+ *     filled (`flow.runAs === 'user'`), unknown keys resolved. Re-normalizing it
+ *     cannot resurrect anything. That half was measured in #5693 and re-measured
+ *     here.
+ *  2. But nothing is lost, because since #4001 the two cited view schemas do not
+ *     STRIP — they REFUSE. `ViewSchema` and `ObjectListViewSchema` are strict, so
+ *     `defineStack` throws on the flat list view and on `quickFilters` /
+ *     `userFilters: { element: 'tabs' }`, naming the same sites the rules name,
+ *     one layer earlier and with the schema's own fix hint. Measured end to end:
+ *     `os lint` and `os validate` on an example app carrying the flat view both
+ *     refuse the config at LOAD, before any rule runs.
+ *  3. The `visibleOn` alias never reaches this tier on ANY input shape: the
+ *     ADR-0087 D2 conversion (`view-visibleOn-to-visibleWhen`,
+ *     `page-component-visibility-to-visibleWhen`) folds it into `visibleWhen`
+ *     INSIDE `normalizeStackInput` — one layer before the tier, not during the
+ *     parse. #6318 acted on that: the alias-KEY rule this premise justified
+ *     (`visibility-alias-deprecated`) was retired, since the D2 conversion
+ *     notice already covers its whole evidence surface with better wording and
+ *     a stated retirement window. The alias-KEY half of premise 3 is therefore
+ *     no longer merely false — there is nothing left reading it.
+ *
+ * ## What it does buy, and why the tier stays
+ *
+ * The surviving reason is the one `validate-functional-completeness.ts` states
+ * and the measurement confirms: a `normalized`-tier finding reaches the author
+ * even when an unrelated schema error elsewhere would stop the parse. On the
+ * raw (non-`defineStack`) path that is not theoretical — `os validate` stops at
+ * the schema step and reports zero rule findings, while `os lint`, which never
+ * parses, still names `view-container-shape` and
+ * `list-view-filters-in-views-mode`. Plus the plain fact that `os lint` has no
+ * parsed stack to give.
+ *
+ * So: read `normalized` as "does not REQUIRE a parsed stack", never as "is
+ * guaranteed to see pre-parse evidence". A new rule whose only evidence is a key
+ * a strict schema rejects is a rule that will never fire — put the diagnostic in
+ * the schema instead, where #4001 already puts it.
  */
 type AuthoringRuleInputTier = 'normalized' | 'parsed';
 /** Per-run inputs a rule may need beyond the stack itself. */

package/dist/{runtime-Cs64ShwN.d.ts → runtime-B50yywI_.d.ts}

@@ -55,10 +55,8 @@ type AuthoringRuleTier = 'gating' | 'advisory';
 /**
  * Which tier of the stack a rule reads.
  *
- * - `normalized` — the `normalizeStackInput` output, BEFORE the Zod parse. The
- *   rules that need it check keys the parse strips (a flat list view in
- *   `views: []`, `userFilters` on an object list view, a `visibleOn` alias): by
- *   the time `result.data` exists the evidence is gone.
+ * - `normalized` — the `normalizeStackInput` output, run before this package's
+ *   caller had a chance to Zod-parse.
  * - `parsed` — the post-parse stack, where defaults are filled and shapes are
  *   settled.
  *
@@ -66,6 +64,53 @@ type AuthoringRuleTier = 'gating' | 'advisory';
  * `os validate`'s verdict to give), so it runs BOTH tiers on the normalized
  * stack. Every rule here is written to tolerate that — it is what `os lint`
  * already did for the reference-integrity suite and the security linter.
+ *
+ * ## What `normalized` does NOT buy, measured (#6073)
+ *
+ * This tier used to be justified as "the rules that need it check keys the
+ * parse strips — a flat list view in `views: []`, `userFilters` on an object
+ * list view, a `visibleOn` alias — by the time `result.data` exists the
+ * evidence is gone". **All three of those examples were measured false**, each
+ * for its own reason, and the pins live in `authoring-rule-input-tier.test.ts`:
+ *
+ *  1. `defineStack` — the documented and universal way a TS config declares a
+ *     stack — PARSES at definition time, so for such a config the value every
+ *     command hands this registry is already `result.data`: parse-time defaults
+ *     filled (`flow.runAs === 'user'`), unknown keys resolved. Re-normalizing it
+ *     cannot resurrect anything. That half was measured in #5693 and re-measured
+ *     here.
+ *  2. But nothing is lost, because since #4001 the two cited view schemas do not
+ *     STRIP — they REFUSE. `ViewSchema` and `ObjectListViewSchema` are strict, so
+ *     `defineStack` throws on the flat list view and on `quickFilters` /
+ *     `userFilters: { element: 'tabs' }`, naming the same sites the rules name,
+ *     one layer earlier and with the schema's own fix hint. Measured end to end:
+ *     `os lint` and `os validate` on an example app carrying the flat view both
+ *     refuse the config at LOAD, before any rule runs.
+ *  3. The `visibleOn` alias never reaches this tier on ANY input shape: the
+ *     ADR-0087 D2 conversion (`view-visibleOn-to-visibleWhen`,
+ *     `page-component-visibility-to-visibleWhen`) folds it into `visibleWhen`
+ *     INSIDE `normalizeStackInput` — one layer before the tier, not during the
+ *     parse. #6318 acted on that: the alias-KEY rule this premise justified
+ *     (`visibility-alias-deprecated`) was retired, since the D2 conversion
+ *     notice already covers its whole evidence surface with better wording and
+ *     a stated retirement window. The alias-KEY half of premise 3 is therefore
+ *     no longer merely false — there is nothing left reading it.
+ *
+ * ## What it does buy, and why the tier stays
+ *
+ * The surviving reason is the one `validate-functional-completeness.ts` states
+ * and the measurement confirms: a `normalized`-tier finding reaches the author
+ * even when an unrelated schema error elsewhere would stop the parse. On the
+ * raw (non-`defineStack`) path that is not theoretical — `os validate` stops at
+ * the schema step and reports zero rule findings, while `os lint`, which never
+ * parses, still names `view-container-shape` and
+ * `list-view-filters-in-views-mode`. Plus the plain fact that `os lint` has no
+ * parsed stack to give.
+ *
+ * So: read `normalized` as "does not REQUIRE a parsed stack", never as "is
+ * guaranteed to see pre-parse evidence". A new rule whose only evidence is a key
+ * a strict schema rejects is a rule that will never fire — put the diagnostic in
+ * the schema instead, where #4001 already puts it.
  */
 type AuthoringRuleInputTier = 'normalized' | 'parsed';
 /** Per-run inputs a rule may need beyond the stack itself. */