@starci/eslint-canon-fe 8.4.39 → 8.4.40

package/runtime/scripts/lib/language.mjs

@@ -15,7 +15,7 @@ export const SECOND_LANGUAGE_LETTER = /[À-ÃÈ-ÊÌÍÒ-ÕÙÚÝà-ãè-êìí
 export const hasSecondLanguage = (text) => typeof text === 'string' && SECOND_LANGUAGE_LETTER.test(text.normalize('NFC'));
 
 /** Every line of `text` with a Vietnamese letter: `[{ line, column }]`, both 1-based. */
-export function secondLanguageHits(text) {
+function secondLanguageHits(text) {
   const hits = [];
   String(text).split(/\r?\n/).forEach((raw, index) => {
     const match = SECOND_LANGUAGE_LETTER.exec(raw.normalize('NFC'));
@@ -24,6 +24,99 @@ export function secondLanguageHits(text) {
   return hits;
 }
 
+/** The named bindings of an import from the backend message catalog contract. */
+function messageCatalogBindings(ts, statement) {
+  if (!ts.isImportDeclaration(statement) || statement.moduleSpecifier.text !== '@modules/platform/i18n') return null;
+  return statement.importClause?.namedBindings ?? null;
+}
+
+/** The local type names imported from the backend message catalog contract. */
+function messageBundleImports(ts, source) {
+  const named = new Set();
+  const namespaces = new Set();
+  for (const statement of source.statements) {
+    const bindings = messageCatalogBindings(ts, statement);
+    if (!bindings) continue;
+    if (ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    for (const entry of ts.isNamedImports(bindings) ? bindings.elements : []) {
+      if ((entry.propertyName ?? entry.name).text === 'MessageBundle') named.add(entry.name.text);
+    }
+  }
+  return { named, namespaces };
+}
+
+/** A declaration that introduces a same-named local type or namespace. */
+function declaresTypeName(ts, statement, name) {
+  if (statement.name?.text !== name) return false;
+  return [ts.isTypeAliasDeclaration, ts.isInterfaceDeclaration, ts.isClassDeclaration, ts.isEnumDeclaration, ts.isModuleDeclaration]
+    .some(predicate => predicate(statement));
+}
+
+/** A type reference bound to the imported MessageBundle contract, including import aliases. */
+function isMessageBundleType(ts, type, imports) {
+  if (!type || !ts.isTypeReferenceNode(type)) return false;
+  const name = type.typeName;
+  if (ts.isIdentifier(name)) return imports.named.has(name.text) && !shadowsImportedType(ts, type, name.text);
+  return ts.isQualifiedName(name) && ts.isIdentifier(name.left)
+    && imports.namespaces.has(name.left.text) && name.right.text === 'MessageBundle' && !shadowsImportedType(ts, type, name.left.text);
+}
+
+/** A local declaration or generic type parameter takes precedence over a same-named import. */
+function shadowsImportedType(ts, node, name) {
+  for (let scope = node.parent; scope; scope = scope.parent) {
+    if (scope.typeParameters?.some(parameter => parameter.name.text === name)) return true;
+    if (scope.statements?.some(statement => declaresTypeName(ts, statement, name))) return true;
+  }
+  return false;
+}
+
+/** The literal object supplied by a variable typed with the imported MessageBundle contract. */
+function messageCatalogObject(ts, node, imports) {
+  if (!ts.isVariableDeclaration(node) || !node.initializer) return null;
+  let value = node.initializer;
+  const type = ts.isSatisfiesExpression(value) ? value.type : node.type;
+  if (ts.isSatisfiesExpression(value)) value = value.expression;
+  return isMessageBundleType(ts, type, imports) && ts.isObjectLiteralExpression(value) ? value : null;
+}
+
+/** Literal string values in the Vietnamese locale of one message catalog. */
+function vietnameseValueRanges(ts, catalog, source) {
+  const ranges = [];
+  for (const locale of catalog.properties) {
+    if (!ts.isPropertyAssignment(locale) || locale.name.text !== 'vi' || !ts.isObjectLiteralExpression(locale.initializer)) continue;
+    for (const message of locale.initializer.properties) {
+      if (ts.isPropertyAssignment(message) && ts.isStringLiteralLike(message.initializer))
+        ranges.push({ start: message.initializer.getStart(source), end: message.initializer.end });
+    }
+  }
+  return ranges;
+}
+
+/** Literal Vietnamese message values of typed catalogs; keys, comments, English values and expressions remain source. */
+function messageBundleValueRanges(ts, source) {
+  const imports = messageBundleImports(ts, source);
+  const ranges = [];
+  const visit = (node) => {
+    const catalog = messageCatalogObject(ts, node, imports);
+    if (catalog) ranges.push(...vietnameseValueRanges(ts, catalog, source));
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return ranges;
+}
+
+/** Source-language hits, treating only literal vi values of typed backend MessageBundle objects as translated product data. */
+export function sourceLanguageHits(rel, text, ts) {
+  if (!hasSecondLanguage(text)) return [];
+  if (!ts || !/\.[cm]?tsx?$/.test(rel)) return secondLanguageHits(text);
+  const source = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true);
+  let sourceText = text;
+  for (const range of messageBundleValueRanges(ts, source).sort((left, right) => right.start - left.start)) {
+    sourceText = sourceText.slice(0, range.start) + sourceText.slice(range.start, range.end).replace(/[^\r\n]/g, ' ') + sourceText.slice(range.end);
+  }
+  return secondLanguageHits(sourceText);
+}
+
 /**
  * The Vietnamese fields of one failure-code entry: the operator text the owner mandated for the failure-code catalog
  * (scripts/checks/check-failure-codes.mjs types the entry with exactly these). causes_vi is the list companion of the three scalar fields.

package/runtime/scripts/lib/package-at.mjs

@@ -0,0 +1,62 @@
+// scripts/lib/package-at.mjs — a package the runtime does not ship (playwright, esbuild, tailwindcss) comes from the
+// project that owns it: node resolution from that project's directory, walking up its node_modules.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { skillRoot } from '../../engine/runtime-root.mjs';
+
+/** The package.json of `name` as resolved from `dir`, or null. */
+export const packageAt = (dir, name) => {
+  try { return createRequire(path.join(dir, 'package.json')).resolve(`${name}/package.json`); } catch { return null; }
+};
+
+/** This runtime's own `starci` bin (packages/cli is the only package that declares one). */
+const RUNTIME_STARCI_BIN = path.join(skillRoot, 'packages', 'cli', 'bin', 'starci.mjs');
+
+/** The `starci` bin of the @starci/cli that `dir` installs (a product runs its own pinned CLI), else this runtime's own. */
+function starciBin(dir) {
+  const packageFile = packageAt(dir, '@starci/cli');
+  if (packageFile) {
+    try {
+      const { bin } = JSON.parse(fs.readFileSync(packageFile, 'utf8'));
+      const rel = typeof bin === 'string' ? bin : bin?.starci;
+      const file = rel ? path.join(path.dirname(packageFile), rel) : null;
+      if (file && fs.existsSync(file)) return file;
+    } catch { /* an unreadable install falls back to the runtime's own CLI */ }
+  }
+  return RUNTIME_STARCI_BIN;
+}
+
+/** The first of `names` resolvable from the first of `dirs` that has one: {name, root, packageFile, version} or null. */
+export function findPackage(dirs, names) {
+  for (const dir of dirs.filter(Boolean)) {
+    for (const name of names) {
+      const packageFile = packageAt(dir, name);
+      if (!packageFile) continue;
+      const require = createRequire(packageFile);
+      return { name, root: path.dirname(packageFile), packageFile, version: require(packageFile).version };
+    }
+  }
+  return null;
+}
+
+/** The CommonJS entry of a package found by findPackage. */
+export const requirePackage = (found) => createRequire(found.packageFile)(found.name);
+
+/** The TypeScript compiler resolvable from the first of `dirs` (an app root, then the caller's own), or null. */
+export const loadTypescript = (...dirs) => {
+  const located = findPackage(dirs, ['typescript']);
+  return located ? requirePackage(located) : null;
+};
+
+/**
+ * The app's command line and the app implementation behind it: `bin` the `starci` bin of the app's installed @starci/cli, else
+ * this runtime's packages/cli/bin/starci.mjs (starciBin); `dir` the @starci/hfs that answers
+ * `starci app` - the app's own install, else the one beside its @starci/cli, else this runtime's packages/hfs - whose runtime
+ * slice the gate's base lint (scripts/gates/gate.mjs) and the READ digest (scripts/gates/read-digest.mjs) load in-process.
+ */
+export function hfsEntry(root) {
+  const cli = packageAt(root, '@starci/cli');
+  const manifest = packageAt(root, '@starci/hfs') ?? (cli && packageAt(path.dirname(cli), '@starci/hfs'));
+  return { dir: manifest ? path.dirname(manifest) : path.join(skillRoot, 'packages', 'hfs'), bin: starciBin(root) };
+}

package/runtime/scripts/lib/same-text.mjs

@@ -0,0 +1,5 @@
+// same-text.mjs - text equality that ignores the line-ending form and a trailing blank tail (a git runner may trim stdout, a work tree may
+// carry CRLF): the one comparison the database rules use for a committed file against its base or against a regenerated one.
+
+/** True when both texts exist and are equal once CRLF is folded to LF and trailing whitespace at the end is dropped. */
+export const sameText = (a, b) => a !== null && b !== null && a.replaceAll('\r\n', '\n').trimEnd() === b.replaceAll('\r\n', '\n').trimEnd();

package/runtime/scripts/lib/ts-analysis.mjs

@@ -25,3 +25,13 @@ export function importsOf(ts, sourceFile, { moduleKey = 'module', stringLiterals
 
 /** Catalog values unwrap parentheses, `as`, and `satisfies`, preserving assertions and non-null nodes. */
 export const unwrapCatalogExpression = (ts, node) => unwrapExpression(ts, node, { typeAssertions: false, nonNullExpressions: false });
+
+/** Bind this file in isolation: the compiler resolves lexical names, but imports and library files are never loaded. */
+export function lexicalChecker(ts, source) {
+  const options = { noLib: true, noResolve: true, allowJs: true };
+  const host = ts.createCompilerHost(options);
+  host.getSourceFile = (file) => file === source.fileName ? source : undefined;
+  host.fileExists = () => false;
+  host.readFile = () => undefined;
+  return ts.createProgram([source.fileName], options, host).getTypeChecker();
+}

package/size-and-state-budget.mjs

@@ -205,9 +205,9 @@ const readsData = (context, fn, seen = new Set()) => {
  * No hand-written polling loop in a component or hook.
  *
  * A timer is polling when what it runs READS DATA (see `readsData`, decided by the type of each call, not by a name): a
- * `setInterval`, or a `setTimeout` whose callback schedules the enclosing function again. The FE convention names no shared clock
- * owner (knowledge/hfs/README.md section 6: "one refresh mechanism per resource, poll or socket"), so a timer that only ticks time
- * or state - a `useNow`-style one-minute clock behind `useSyncExternalStore` - is not a second refresh mechanism.
+ * `setInterval`, or a `setTimeout` whose callback schedules the enclosing function again. A timer that only ticks time or state
+ * is not a data-refresh mechanism. Grammar's live-time ownership is independently enforced by `no-app-relative-clock` in
+ * `grammar-boundary.mjs`.
  */
 export const noHandRolledPolling = {
   meta: {

package/surface-rules.mjs

@@ -0,0 +1,230 @@
+/** Grammar owns surface nesting and the single content edge of a panel list (ANATOMY-2, PADDING-0). */
+import { attributeValue, stringOf } from "./lib/ast.mjs"
+import { importOf, isFn, patternPath, unwrap, variableOf } from "./lib/bindings.mjs"
+import { typedClassStrings, typedPropertyStrings } from "./lib/typed-class-values.mjs"
+import { reactHookOf } from "./lib/react.mjs"
+
+const GRAMMAR_ENTRY = /^@starci\/grammar(?:\/(?:common|core|heritage|offset-pop))?$/
+const SURFACES = new Set([
+  "SurfaceCard", "SurfaceListCard", "SurfaceAccordionCard", "Rail", "Sidebar",
+  "Dialog", "Drawer", "AlertDialog", "Popover",
+])
+const FIELDS = new Set([
+  "Input", "TextField", "Textarea", "TextArea", "SearchField", "NumberField", "DateField", "TimeField",
+  "Select", "ComboBox", "DatePicker", "DateRangePicker", "Checkbox", "CheckboxGroup", "RadioGroup", "PressableField", "OtpInput",
+])
+const CLASS_BUILDERS = new Set(["cn", "clsx", "classNames", "cva", "tv"])
+
+/** Resolve a JSX name to its Grammar export and optional compound parts, preserving lexical import identity. */
+const grammarName = (context, name) => {
+  if (name.type === "JSXMemberExpression") {
+    const owner = grammarName(context, name.object)
+    return owner === null ? null : [...owner, name.property.name]
+  }
+  if (name.type !== "JSXIdentifier") return null
+  const imported = importOf(context, name)
+  if (!imported || !GRAMMAR_ENTRY.test(imported.source)) return null
+  if (imported.imported !== null) return [imported.imported]
+  const binding = variableOf(context, name)?.defs.find((definition) => definition.type === "ImportBinding")
+  return binding?.node.type === "ImportNamespaceSpecifier" ? [] : null
+}
+
+/** Class and variant expressions expose their statically authored strings, including const aliases and cn branches. */
+const authoredStrings = (context, input, seen = new Set(), mode = "classes") => {
+  const node = unwrap(input?.type === "JSXExpressionContainer" ? input.expression : input)
+  if (!node || seen.has(node)) return []
+  seen.add(node)
+  const text = stringOf(node)
+  if (text !== null) return [{ node, text }]
+  if (node.type === "TemplateElement") return [{ node, text: node.value.cooked ?? node.value.raw }]
+  if (node.type === "Identifier") {
+    const values = bindingValues(context, node)
+    return values.length ? values.flatMap((value) => authoredStrings(context, value, seen, mode)) : typedClassStrings(context, node, mode)
+  }
+  if (node.type === "MemberExpression") {
+    const propertyName = node.computed ? stringOf(node.property) : node.property.name
+    const values = propertyValues(context, node.object, propertyName)
+    return values.length ? values.flatMap((value) => authoredStrings(context, value, seen, mode)) : typedClassStrings(context, node, mode)
+  }
+  const children = stringChildren(node, mode)
+  return children.flatMap((child) => authoredStrings(context, child, seen, mode))
+}
+
+/** Only value-bearing positions contribute classes; object keys support cn's conditional class dictionary. */
+const stringChildren = (node, mode) => {
+  if (node.type === "TemplateLiteral") return mode === "classes" ? [...node.quasis, ...node.expressions] : []
+  if (node.type === "ArrayExpression") return node.elements
+  if (node.type === "CallExpression") return mode === "classes" ? node.arguments : []
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate]
+  if (node.type === "LogicalExpression") return node.operator === "&&" ? [node.right] : [node.left, node.right]
+  if (node.type === "ObjectExpression") return node.properties.flatMap((property) => property.type === "Property" ? [property.key, property.value] : [property.argument])
+  return []
+}
+
+/** A declared React component is a separate render tree; inline collection/render callbacks keep the surrounding context. */
+const componentBoundary = (context, node) => {
+  if (!isFn(node)) return false
+  if (node.parent?.type === "CallExpression" && ["memo", "forwardRef"].includes(reactHookOf(context, node.parent))) return true
+  if (node.parent?.type === "JSXExpressionContainer" || node.parent?.type === "CallExpression" && node.parent.arguments.includes(node)) return false
+  const name = node.id?.name ?? (node.parent?.type === "VariableDeclarator" ? node.parent.id.name : null)
+  return name !== null && /^[A-Z]/.test(name)
+}
+
+/** The Grammar ancestors whose rendered content contains this node, excluding an overlay's trigger. */
+function* surfaceAncestors(context, node) {
+  const triggers = new Set()
+  for (let current = node.parent; current; current = current.parent) {
+    if (componentBoundary(context, current)) return
+    if (current.type === "JSXAttribute" && current.name.name === "trigger") triggers.add(current.parent)
+    if (current.type === "JSXElement" && !triggers.has(current.openingElement)) yield current.openingElement
+  }
+}
+
+const isSurface = (context, node, descendant) => {
+  const name = grammarName(context, node.name)
+  if (name?.length !== 1) return false
+  if (SURFACES.has(name[0])) return true
+  if (name[0] !== "ChatWorkspace") return false
+  for (let current = descendant; current && current !== node.parent; current = current.parent) {
+    if (current.type === "JSXAttribute" && current.parent === node && current.name.name === "rail") return true
+  }
+  return false
+}
+const classTokens = (text) => text.split(/\s+/).map((token) => token.split(":").at(-1).replace(/^!|!$/g, ""))
+const rawSurface = (token) => /^bg-surface(?:-[a-z0-9-]+)?(?:\/[^\s]+)?$/.test(token)
+const horizontalPadding = (token) => /^(?:px|ps|pe)-.+$/.test(token)
+
+/** Computed keys select their evaluated static name, rather than the identifier's spelling. */
+const propertyName = (context, property) => {
+  if (!property.computed) return property.key.name ?? property.key.value
+  const values = authoredStrings(context, property.key, new Set(), "variant")
+  return values.length === 1 ? values[0].text : null
+}
+
+/** A binding selects its own object property; sibling declarations do not become its value. */
+const bindingValues = (context, node, seen = new Set()) => {
+  const definition = variableOf(context, node)?.defs.find((entry) => entry.type === "Variable")
+  if (!definition) return []
+  const path = patternPath(definition.node.id, node.name)
+  if (path === null) return []
+  return path.reduce((values, key) => values.flatMap((value) => propertyValues(context, value, key, seen)), [definition.node.init]).filter(Boolean)
+}
+
+/** Static object spreads retain the same published-prop obligations as ordinary JSX attributes. */
+const propertyValues = (context, input, key, seen = new Set()) => {
+  const node = unwrap(input)
+  if (!node || seen.has(node)) return []
+  seen.add(node)
+  if (node.type === "Identifier") {
+    return bindingValues(context, node, seen).flatMap((value) => propertyValues(context, value, key, seen))
+  }
+  if (node.type === "MemberExpression") {
+    const member = node.computed ? stringOf(node.property) : node.property.name
+    return propertyValues(context, node.object, member, seen).flatMap((value) => propertyValues(context, value, key, seen))
+  }
+  if (node.type === "ConditionalExpression") return [node.consequent, node.alternate].flatMap((branch) => propertyValues(context, branch, key, seen))
+  if (node.type !== "ObjectExpression") return []
+  return node.properties.flatMap((property) => {
+    if (property.type === "SpreadElement") return propertyValues(context, property.argument, key, seen)
+    return propertyName(context, property) === key ? [property.value] : []
+  })
+}
+
+const propStrings = (context, entry, name, mode = "classes") => {
+  if (entry.type === "JSXSpreadAttribute") {
+    const values = propertyValues(context, entry.argument, name)
+    return values.length ? values.flatMap((value) => authoredStrings(context, value, new Set(), mode)) : typedPropertyStrings(context, entry.argument, name, mode)
+  }
+  return entry.name.name === name ? authoredStrings(context, attributeValue(entry), new Set(), mode) : []
+}
+
+/** An explicit section caption excludes the row's own content subtree. */
+const inSectionCaption = (context, node) => {
+  for (const ancestor of surfaceAncestors(context, node.parent)) {
+    const owner = grammarName(context, ancestor.name)
+    if (owner?.[0] !== "ListBox") continue
+    if (owner[1] === "Item") return false
+    if (["Section", "Header", "SectionHeader"].includes(owner[1])) return true
+  }
+  return false
+}
+
+/** ANATOMY-2: Grammar provides the secondary default; apps cannot force primary or paint a raw surface. */
+export const nestedControlVariant = {
+  meta: {
+    type: "problem",
+    docs: { description: "ANATOMY-2: nested fields use Grammar's secondary default and surfaces belong to Grammar." },
+    schema: [],
+    messages: {
+      primary: "FE_NESTED_VARIANT: a field inside a Grammar surface cannot force variant=\"primary\". Omit variant so Grammar supplies secondary through its nesting context.",
+      surface: "FE_NESTED_VARIANT: bg-surface paints a surface in app CSS. Compose SurfaceCard, Rail, Sidebar or another Grammar surface instead.",
+    },
+  },
+  create(context) {
+    const reported = new Set()
+    const checkClasses = (value) => {
+      for (const entry of authoredStrings(context, value)) {
+        if (!classTokens(entry.text).some(rawSurface) || reported.has(entry.node)) continue
+        reported.add(entry.node)
+        context.report({ node: entry.node, messageId: "surface" })
+      }
+    }
+    return {
+      JSXOpeningElement(node) {
+        const name = grammarName(context, node.name)
+        const variant = node.attributes.find((entry) => propStrings(context, entry, "variant", "variant").some((value) => value.text === "primary"))
+        if (name?.length !== 1 || !FIELDS.has(name[0]) || !variant) return
+        if ([...surfaceAncestors(context, node.parent)].some((ancestor) => isSurface(context, ancestor, node))) context.report({ node: variant, messageId: "primary" })
+      },
+      JSXAttribute(node) {
+        if (["className", "class", "classNames"].includes(node.name.name)) checkClasses(node.value)
+      },
+      CallExpression(node) {
+        if (node.callee.type === "Identifier" && CLASS_BUILDERS.has(node.callee.name)) checkClasses(node)
+      },
+      VariableDeclarator(node) {
+        if (/[Cc]lass/.test(node.id.name ?? "") || /(?:^|[/\\])classNames\.[cm]?[jt]sx?$/.test(context.filename)) checkClasses(node.init)
+      },
+      Property(node) {
+        if (["className", "class", "classNames"].includes(propertyName(context, node))) checkClasses(node.value)
+      },
+    }
+  },
+}
+
+/** PADDING-0: app padding wrappers cannot add a second horizontal inset to Grammar's list or section caption. */
+export const noListPanelPadding = {
+  meta: {
+    type: "problem",
+    docs: { description: "PADDING-0: panel lists and section captions share the Grammar surface's content edge." },
+    schema: [],
+    messages: { padding: "FE_LIST_PANEL_PADDING: horizontal padding stacks with the Grammar list inset. Remove this wrapper padding and use ListBox inset=\"panel\" so rows and section captions share the panel content edge." },
+  },
+  create(context) {
+    const reported = new Set()
+    const check = (opening) => {
+      const className = opening.attributes.find((entry) => ["className", "class"].some((name) => propStrings(context, entry, name).some((value) => classTokens(value.text).some(horizontalPadding))))
+      if (!className || reported.has(className)) return
+      reported.add(className)
+      context.report({ node: className, messageId: "padding" })
+    }
+    return {
+      JSXOpeningElement(node) {
+        const name = grammarName(context, node.name)
+        if (name?.[0] === "ListBox" && (name.length === 1 || ["Section", "Header", "SectionHeader"].includes(name[1]))) {
+          check(node)
+          for (const ancestor of surfaceAncestors(context, node.parent)) {
+            check(ancestor)
+            if (isSurface(context, ancestor, node)) break
+          }
+        } else if (inSectionCaption(context, node)) check(node)
+      },
+    }
+  },
+}
+
+/** The surface laws ship at error in every composing source tree. */
+export const rules = { "nested-control-variant": nestedControlVariant, "no-list-panel-padding": noListPanelPadding }
+
+/** No app can lower or omit a surface law. */
+export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/swr-family.mjs

@@ -1,8 +1,9 @@
 /** R285: API operations are wrapped by the SWR family before product code calls them. */
 import { hfsOf } from "./lib/hfs.mjs"
 import { readFileSync, readdirSync } from "node:fs"
-import { join } from "node:path"
+import { dirname, join, resolve } from "node:path"
 import { stringOf, walk } from "./lib/ast.mjs"
+import { functionOf } from "./lib/bindings.mjs"
 import { classOf, fileOf, globalReferences, isApiLayer, isProductSource, resolveImport } from "./lib/scope.mjs"
 import { why } from "./lib/why.mjs"
 
@@ -13,7 +14,7 @@ const isSwrHook = (context) => {
 }
 
 /** Cache providers and revalidation may be used by consumers; only request hooks own operations. */
-const isRequestHook = (name) => /^useSWR(?:Immutable|Infinite|Mutation)?$/.test(name) || name === "default"
+const isRequestHook = (name) => /^useSWR(?:Immutable|Infinite|Mutation|Subscription)?$/.test(name) || name === "default"
 const swrSource = (value) => value === "swr" || value.startsWith("swr/")
 const propertyName = (node) => node.computed ? node.property.value : node.property.name
 
@@ -68,8 +69,11 @@ export const swrOnlyInFamily = {
   },
 }
 
+/** The slot of the stream reader: only a stream operation of the API layer imports it, never an SWR hook, even inside a fetcher. */
+const STREAM_READER_SLOT = "fe.transport.stream"
+
 /** Type imports stay available; the API layer may compose its own operations and helpers. */
-const isOperationSource = (context, value) => {
+const isOperationSource = (context, value, only) => {
   if (typeof value !== "string") return false
   const hfs = hfsOf(context)
   let target = resolveImport(context, value)
@@ -93,7 +97,43 @@ const isOperationSource = (context, value) => {
   const candidates = /\.[cm]?[jt]sx?$/.test(target) ? [target] : [`${target}.ts`, `${target}.tsx`, `${target}/index.ts`, `${target}/index.tsx`, target]
   const found = candidates.map((file) => hfs.classify(file)).filter((entry) => entry.status === "owned")
   if (found.some((entry) => ["fe.transport.outcome", "fe.package.api.outcome"].includes(entry.slot))) return false
-  return found.some((entry) => ["fe.modules.api", "fe.package.api", "fe.transport.client", "fe.package.api.client"].includes(entry.slot))
+  if (only !== undefined) return found.some((entry) => entry.slot === only)
+  return found.some((entry) => ["fe.modules.api", "fe.package.api", "fe.transport.client", "fe.transport.stream", "fe.package.api.client"].includes(entry.slot))
+}
+
+/** The generated input-bounds module holds constants and a pure reader derived from the contract, never an operation. */
+const BOUNDS_MODULE = /(?:^|\/)__generated__\/input-bounds\.ts$/
+const RE_EXPORT = /export\s*\{([^}]*)\}\s*from\s*["']([^"']+)["']/g
+const ENTRY = /^\s*(type\s+)?([\w$]+)(?:\s+as\s+([\w$]+))?\s*$/
+
+/** True when the named export of `target` is, through a chain of relative named re-exports, defined by a generated input-bounds module. */
+const isBoundsExport = (target, name, depth = 0) => {
+  if (depth > 4) return false
+  for (const file of [`${target}.ts`, `${target}/index.ts`, target]) {
+    if (BOUNDS_MODULE.test(file.replaceAll("\\", "/"))) return true
+    let text
+    try { text = readFileSync(file, "utf8") } catch { continue }
+    for (const [, list, source] of text.matchAll(RE_EXPORT)) {
+      if (!source.startsWith(".")) continue
+      for (const entry of list.split(",")) {
+        const [, kind, origin, exported] = ENTRY.exec(entry) ?? []
+        if (origin !== undefined && kind === undefined && (exported ?? origin) === name && isBoundsExport(resolve(dirname(file), source), origin, depth + 1)) return true
+      }
+    }
+  }
+  return false
+}
+
+/** An import of named values that all come from a generated input-bounds module is data, not an operation. */
+const importsOnlyBounds = (context, node, value) => {
+  const specifiers = node.specifiers?.filter((s) => s.importKind !== "type" && s.exportKind !== "type") ?? []
+  if (!specifiers.length || typeof value !== "string") return false
+  const target = resolveImport(context, value)
+  if (target === null) return false
+  return specifiers.every((s) => {
+    const name = s.imported?.name ?? s.imported?.value ?? s.local?.name ?? s.local?.value
+    return (s.type === "ImportSpecifier" || s.type === "ExportSpecifier") && typeof name === "string" && isBoundsExport(target, name)
+  })
 }
 
 const unwrap = (node) => {
@@ -162,7 +202,7 @@ export const operationsOnlyInSwrHooks = {
     if (!isProductSource(context) || isApiLayer(context)) return {}
     const imports = []
     const inspect = (node, value) => {
-      if (isOperationSource(context, value)) imports.push({ node, value })
+      if (isOperationSource(context, value) && !importsOnlyBounds(context, node, value)) imports.push({ node, value, reader: isOperationSource(context, value, STREAM_READER_SLOT) })
     }
     return {
       ImportDeclaration(node) {
@@ -180,7 +220,95 @@ export const operationsOnlyInSwrHooks = {
       "Program:exit"(program) {
         if (!imports.length) return
         const wrapped = isSwrHook(context) ? wrappedOperations(context, program, imports) : new Set()
-        for (const { node, value } of imports) if (!wrapped.has(node)) context.report({ node, messageId: "outside", data: { source: value } })
+        for (const { node, value, reader } of imports) if (reader || !wrapped.has(node)) context.report({ node, messageId: "outside", data: { source: value } })
+      },
+    }
+  },
+}
+
+/** A stream operation: `modules/api/sse/<area>/stream-<channel>` or `modules/api/graphql/subscriptions/subscription-<name>`. */
+const STREAM_OPERATION = /modules\/api\/(?:sse\/[^/]+\/stream-[^/]+|graphql\/subscriptions\/subscription-[^/]+)(?:\.tsx?)?$/
+
+/** A subscription hook file of the SWR family: `useSubscribe<X>Swr.ts`. */
+const isSubscriptionHook = (context) => isSwrHook(context) && /^useSubscribe[A-Z0-9]\w*Swr\.ts$/.test(fileOf(context).replaceAll("\\", "/").split("/").at(-1) ?? "")
+
+/** The `onOpen` property of an object literal, else undefined. */
+const onOpenOf = (options) =>
+  options?.type === "ObjectExpression"
+    ? options.properties.find((property) => property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "onOpen")
+    : undefined
+
+/** True when a function calls `mutate` (the bound mutate of a hook or the one of `useSWRConfig`): the revalidation of the snapshot query. */
+const callsMutate = (source, handler) => {
+  let found = false
+  walk(source, handler.body, (node) => {
+    if (found) return false
+    if (node.type !== "CallExpression") return undefined
+    const callee = unwrap(node.callee)
+    if ((callee?.type === "Identifier" && callee.name === "mutate") || (callee?.type === "MemberExpression" && propertyName(callee) === "mutate")) found = true
+    return undefined
+  })
+  return found
+}
+
+/** True when a callee is a stream operation: a named import, a member of a namespace import, or a const alias of either. */
+const isStreamCallee = (source, input, locals, seen = new Set()) => {
+  const node = unwrap(input)
+  if (node?.type === "MemberExpression") {
+    const object = unwrap(node.object)
+    return object?.type === "Identifier" && locals.get(object.name) === "namespace" && bindingOf(source, object)?.defs[0]?.type === "ImportBinding"
+  }
+  if (node?.type !== "Identifier") return false
+  const variable = bindingOf(source, node)
+  if (!variable || seen.has(variable) || variable.defs.length !== 1) return false
+  const definition = variable.defs[0]
+  if (definition.type === "ImportBinding") return locals.get(variable.name) === "named"
+  if (definition.node.type !== "VariableDeclarator" || definition.parent.kind !== "const") return false
+  return isStreamCallee(source, definition.node.init, locals, new Set([...seen, variable]))
+}
+
+/**
+ * A stream or subscription has no replay of what it missed (graphql-ws has none, an SSE reconnect replays a bounded buffer), so the
+ * subscription hook revalidates the snapshot query each time the stream opens: its call of the stream operation (named, through a
+ * namespace or an alias) passes an `onOpen` handler that calls `mutate`, and a subscription hook that calls no stream operation at
+ * all is not one (FE-REALTIME-2).
+ */
+export const subscriptionRefetchesSnapshot = {
+  meta: {
+    type: "problem",
+    docs: { description: "FE_SUBSCRIPTION_NO_SNAPSHOT: a subscription hook passes the stream operation an onOpen handler that revalidates the snapshot query." },
+    schema: [],
+    messages: {
+      missing:
+        "FE_SUBSCRIPTION_NO_SNAPSHOT: this call of a stream operation has no `onOpen` handler that calls `mutate`. A stream carries changes, not the state: pass `onOpen: () => void mutate(<snapshot query key>)` so the screen reads its snapshot with the query each time the stream (re)opens.",
+      noStream:
+        "FE_SUBSCRIPTION_NO_SNAPSHOT: a `useSubscribe<X>Swr` hook calls one stream operation (`modules/api/sse/<area>/stream-*.ts` or `modules/api/graphql/subscriptions/subscription-*.ts`) and revalidates its snapshot query in `onOpen`; this file calls none.",
+    },
+  },
+  create(context) {
+    if (!isProductSource(context) || !isSubscriptionHook(context)) return {}
+    const source = context.sourceCode ?? context.getSourceCode()
+    const locals = new Map()
+    let calls = 0
+    return {
+      ImportDeclaration(node) {
+        if (node.importKind === "type" || typeof node.source.value !== "string") return
+        const target = resolveImport(context, node.source.value)
+        if (target === null || !STREAM_OPERATION.test(target.replaceAll("\\", "/"))) return
+        for (const specifier of node.specifiers) {
+          if (specifier.importKind === "type") continue
+          if (specifier.type === "ImportSpecifier") locals.set(specifier.local.name, "named")
+          if (specifier.type === "ImportNamespaceSpecifier") locals.set(specifier.local.name, "namespace")
+        }
+      },
+      CallExpression(node) {
+        if (!isStreamCallee(source, node.callee, locals)) return
+        calls += 1
+        const handler = functionOf(context, onOpenOf(node.arguments[0])?.value)
+        if (!handler || !callsMutate(source, handler)) context.report({ node, messageId: "missing" })
+      },
+      "Program:exit"(program) {
+        if (calls === 0) context.report({ node: program, messageId: "noStream" })
       },
     }
   },
@@ -190,8 +318,9 @@ export const operationsOnlyInSwrHooks = {
 Object.assign(why, {
   "swr-only-in-family": { code: "FE_SWR_OUTSIDE_FAMILY", en: "A request hook is used outside the SWR family.", fix: "Call the operation's SWR wrapper hook." },
   "operations-only-in-swr-hooks": { code: "FE_OP_OUTSIDE_SWR_HOOK", en: "An API operation is consumed outside an SWR wrapper.", fix: "Wrap the operation in hooks/swr/." },
+  "subscription-refetches-snapshot": { code: "FE_SUBSCRIPTION_NO_SNAPSHOT", en: "A subscription hook does not revalidate its snapshot query when the stream opens.", fix: "Pass the stream operation an onOpen handler that revalidates the snapshot query key." },
 })
 
 /** R285's published lint enforcers. */
-export const rules = { "swr-only-in-family": swrOnlyInFamily, "operations-only-in-swr-hooks": operationsOnlyInSwrHooks }
+export const rules = { "swr-only-in-family": swrOnlyInFamily, "operations-only-in-swr-hooks": operationsOnlyInSwrHooks, "subscription-refetches-snapshot": subscriptionRefetchesSnapshot }
 export const recommended = Object.fromEntries(Object.keys(rules).map((name) => [`starci-fe/${name}`, "error"]))

package/transport.mjs

@@ -28,12 +28,13 @@ import { typed } from "./lib/types.mjs"
 
 /**
  * The canonical transport libraries and the one place each may be imported (fe-stack graphql, rest and realtime): Apollo in
- * the API layer, axios in its REST calls, socket.io-client in `hooks/socketio`. Matched on the package a specifier names.
+ * the API layer, axios in its REST calls, graphql-ws in the Apollo clients folder, socket.io-client in `hooks/socketio`. Matched on the package a specifier names.
  */
 const PLACED_TRANSPORTS = new Map([
   ["@apollo/client", { where: "the API layer (`modules/api`)", allowed: (context) => isApiLayer(context) }],
   ["axios", { where: "the REST calls of the API layer (`modules/api/rest/`)", allowed: (context) => isApiRest(context) }],
   ["socket.io-client", { where: "`hooks/socketio/`", allowed: (context) => inSlot(context, "fe.hooks.socketio") }],
+  ["graphql-ws", { where: "the Apollo clients of the API layer (`modules/api/graphql/clients/`, or the shared api package's `graphql/clients/`)", allowed: (context) => isApiClient(context) }],
 ])
 
 /**