ReviewOS

stacks/stx

lint: ship stx-strict ESLint preset that errors on the documented footguns (bare function refs, view-level scripts, store value imports, etc.)

#1744
Closed glennmichael123 opened this 22 days ago · 1 comment
22 days ago

Problem

The following footguns are documented in adopter memory but cause silent runtime misbehavior with no compiler error:

  1. Bare function ref in event handler — @click="toggleLike" does nothing; only @click="toggleLike()" works
  2. View-level <script client> — silently dropped; only components get scopes
  3. Store value imports — value imports from outside resources/stores/ get silently stripped from store bundles
  4. signal() call-syntax inside :for — falls back to a path that leaves the loop var as a signal function → comparisons silently always return the same branch
  5. x-class array mixing static + conditional — breaks transform / translate-x-* utilities
  6. Bare browser globals shadowed by store signals — location.search resolves to the search store's location signal, throws, kills the rest of <script client>
  7. Backticks in HTML comments inside .stx — leak into merged setup function and flip JS parser into template-literal mode
  8. Backticks inside // line comments (in .ts files) — Bun parser chokes silently
  9. stx directives inside HTML comments — @push/@include/etc. get substituted at the comment location, busting page structure
  10. @include can't forward :for loop var into a partial with <script client> — loop var hits scope boundary
  11. window.stx._rp unset on hard reload — dynamic route components must parse location.pathname instead
  12. <template> tags in stx — SSG bug strips parent trees
  13. Web Components (hyphenated tags) in stx templates — hyphenated tags are stx component refs

Every one of these is a place where the code looks correct but does nothing or does the wrong thing. The framework knows these are footguns (they're either in docs or in adopter memory notes). The linter should catch them at write time.

Proposed: @stacksjs/eslint-config-stx-strict

ESLint preset with one rule per footgun:

Rule IDCatches
stx/no-bare-function-ref-in-event@click="toggleLike" without parens
stx/no-view-level-script-client<script client> at the top level of a view file
stx/store-value-imports-must-be-localImports from non-resources/stores/ paths in store files
stx/no-signal-call-in-for-iteration-varsignal() call inside :for body
stx/x-class-array-no-static-stringsx-class="[cond ? '...' : '', 'static']"
stx/use-window-prefixed-globalsBare location / history / localStorage in scopes with stores
stx/no-backticks-in-html-commentsBackticks inside <!-- --> blocks in .stx
stx/no-backticks-in-line-commentsBackticks inside // comments in .ts
stx/no-stx-directives-in-html-comments@push / @include inside <!-- -->
stx/no-for-loop-var-in-include@include('x', { v: loopVar }) where the partial has <script client>
stx/no-template-tag-in-stx<template> outside known-safe directive use
stx/no-web-components-in-templateshyphenated lowercase tags that aren't stx components

Adopters opt in via:

{ "extends": ["@stacksjs/eslint-config-stx-strict"] }

Or the strict preset becomes the default in create-stacks-app so new projects get it from day 1.

Prior art

  • @vue/eslint-config-typescript + Vue official rules — catches Vue-specific footguns
  • eslint-plugin-react — catches React footguns (missing keys, exhaustive deps, etc.)
  • @typescript-eslint — catches TS-specific footguns
  • eslint-plugin-svelte — Svelte equivalent

Every framework has its strict-mode lint preset. Stacks documents the footguns but doesn't ship the lint rules.

Impact

  • Bug-class elimination: every documented footgun becomes a build-time error.
  • Onboarding: new adopters can't accidentally write the broken pattern.
  • Code review: reviewer doesn't have to remember the 13 footguns.

Phasing

  • Phase 1: Top 5 most-hit rules (bare function ref, view-level script client, store value imports, signal call in :for, backticks in HTML comments)
  • Phase 2: Remaining 8 rules
  • Phase 3: Auto-fix where safe (stx/no-bare-function-ref-in-event can auto-add parens)

Happy to PR Phase 1 — the rules are essentially "grep + AST check," each is ~50 LOC.

22 days ago

Phase 1 landed in ff9d4c9.

Shipped: lintStxStrict(source, options) in src/strict-lint.ts — a self-contained detection engine (no package imports → cheap + trivially testable) returning { ruleId, message, line, column, severity }[]. The hard part (correct detection, low false-positive rate) is done; wiring into pickier / CLI / editor is a thin follow-up.

Convention note: per CLAUDE.md (pickier, never eslint), this ships the rule logic as a reusable function rather than an @stacksjs/eslint-config-stx-strict preset. Pickier (or any host) can consume it. Rules toggle via options.rules; view/component classification is path-derived or forced via options.fileKind.

The 5 Phase-1 rules:

ruleIdcatches
stx/no-bare-function-ref-in-event@click="toggleLike" (no parens)
stx/no-view-level-script-client<script client> in a view file
stx/store-value-imports-must-be-localvalue import/re-export escaping resources/stores/
stx/no-signal-call-in-for-iteration-varcalling a :for loop var like a signal
stx/no-backticks-in-html-commentsa backtick inside <!-- -->

Quality: two adversarial review passes (20 agents) hunted false positives/negatives — 8 confirmed and fixed, all pinned with regressions:

  • colon-namespaced events (@update:modelValue) were missed (now matched; denylist keyed on the pre-colon segment so @model:foo stays a directive)
  • export { x } from '…' re-exports weren't inspected (now checked — re-exports are part of the store bundle)
  • the :for rule only extracted the first destructured var → (item, idx) ⇒ idx() slipped through (now extracts every bound var, JS + Blade forms)
  • a $ loop var broke the call regex ($ is an anchor) → now regex-escaped
  • loop-var calls in attributes on the :for element itself (, void/self-closing <input>) were missed → search region now includes the opening tag (with the :for value masked) + body
  • nested same-named :for double-reported → deduped by (ruleId, line, column)

43 tests — every rule's must-flag set + a battery of must-NOT-flag look-alikes.

Deferred to Phase 2 (per the issue): the remaining 8 footguns (web-components / hyphenated tags, <template> tags, @include loop-var forwarding, x-class static+conditional mixing, bare browser globals shadowed by store signals, backticks in // comments, stx directives in HTML comments, window.stx._rp on hard reload), plus Phase 3 auto-fix and the pickier-rule/CLI/create-stacks-app wiring.

Closing Phase 1 — the top-5 detection logic is the foundation.

Sign in to comment on this issue.