sygnal 5.4.0 → 6.1.0

package/src/extra/diagnostics/checks/index.ts

@@ -17,15 +17,59 @@
  * | SYG104 | intent selector only matches inside a child component  | dom.ts         |
  * | SYG105 | EVENTS type emitted-not-selected / selected-not-emitted| events.ts      |
  * | SYG106 | parent prop overwritten by a reserved view argument    | props.ts       |
+ * | SYG112 | reply action has no model entry                        | replies.ts     |
+ * | SYG630 | cached request that isn't idempotent (POST + cache)    | fetch.ts       |
+ * | SYG631 | validate is not a Standard Schema                      | fetch.ts       |
+ * | SYG632 | invalidate matched nothing (info)                      | fetch.ts       |
+ * | SYG633 | abort names a lane its requests don't use              | fetch.ts       |
+ * | SYG635 | cache: true / staleTime / prefetch without queryCache() | fetch.ts       |
+ * | SYG115 | unknown DOM event shorthand (DOM.key(...))             | shorthand.ts   |
+ * | SYG124 | component where a control or selector is expected      | controls.ts    |
+ * | SYG140 | widget emitted an event it doesn't declare             | widgets.ts     |
+ * | SYG142 | widget command not declared (also a reserved name)     | elementCommands.ts, widgets.ts |
+ * | SYG143 | widget tag used as a selector                          | widgets.ts     |
+ * | SYG144 | declared widget event the host also fires (info)       | widgets.ts     |
+ * | SYG660 | widget mount / update / unmount threw (660/661/662)    | widgets.ts     |
+ * | SYG430 | VirtualCollection: no bounded height; SYG431 items without ids; SYG432 item not one element; SYG433 scroll target not in the list; SYG434 bad estimateSize / overscan | virtual.ts |
+ * | SYG125 | control given component statics / bad spec vnode()     | controls.ts    |
+ * | SYG127 | behavior key in initialState / unresolvable uses entry | behaviors.ts   |
+ * | SYG230 | form: field name not in values; SYG231 not a Standard Schema; SYG232 submit dropped (info); SYG233 value missing from the schema output | forms.ts |
+ * | SYG234 | form submit action has no model entry; SYG235 check names an unknown field / sets reply fields; SYG236 rows without an id | forms.ts |
+ * | SYG145 | sortable: item without its id attribute; SYG146 item / handle selector matches nothing; SYG147 from is not an array | sortable.ts |
+ * | SYG116 | EVENTS value with no string type (a function)          | events.ts      |
+ * | SYG130 | href() names no route / leaves out a param             | router.ts      |
+ * | SYG131 | route params the pattern doesn't use                   | router.ts      |
+ * | SYG132 | declaration static never sent: a root without initialState    | router.ts      |
+ * | SYG133 | SPA router inside a Vike app                           | router.ts      |
+ * | SYG422 | timer spec makeTimerDriver() can't run                 | timers.ts      |
+ * | SYG643 | timers/connections/resources/browser with no driver    | timers.ts      |
+ * | SYG663 | browser entry / BROWSER command that can't run         | browserSources.ts |
+ * | SYG664 | browser source the driver wasn't made with             | browserSources.ts |
+ * | SYG665 | browser source failed with no error action             | browserSources.ts |
+ * | SYG668 | intersection / resize with no element to observe       | browserSources.ts |
+ * | SYG673 | malformed chat stream event (makeChatDriver)           | chat.ts        |
+ * | SYG675 | tool sent non-strict under strict (L-2 transports, info)| chat.ts        |
+ * | SYG677 | chat request sent from outside a component             | chat.ts        |
+ * | SYG238 | a root with a model but no initialState: renders nothing | state.ts       |
+ * | SYG223 | persist pick/omit key not in initialState              | persist.ts     |
+ * | SYG224 | persist on a component that isn't the root             | persist.ts     |
+ * | SYG645 | viewTransitions without makeViewTransitionDOMDriver(), or not an array | viewTransitions.ts |
  * | SYG201 | STATE reducer dropped keys                             | state.ts       |
  * | SYG202 | STATE reducer returned undefined                       | state.ts       |
+ * | SYG221 | set() called with a string                             | state.ts       |
+ * | SYG222 | same object returned after an in-place mutation        | state.ts       |
  * | SYG301 | RxJS operator used on an xstream stream                | rxjsHints.ts   |
  * | SYG401 | Collection `from` missing or not an array              | collections.ts |
- * | SYG501 | strict: view uses positional (props, state, ...) args  | strict.ts      |
- * | SYG502 | strict: STATE reducer returned the unchanged state     | strict.ts      |
- * | SYG504 | strict: 'ACTION | SINK' shorthand model key           | strict.ts      |
+ * | SYG421 | invalid data (dataset) key in a view                   | dataset.ts     |
+ * | SYG612 | a form 6.0 removed (also SYG501/504 statically)        | next.ts        |
+ * | SYG502 | retired in 6.0 (never reported; GS-4)                  | —              |
+ * | SYG508 | strict: select()/errors() round trip on a reply source | replies.ts    |
+ * | —      | D152: shared statics frozen (initialState deep)        | statics.ts     |
  * | —      | inspect(): the runtime app graph (2B)                  | inspect.ts     |
  *
+ * SYG112, SYG130-133 (PLAN-3), SYG115/116/221/421 (G-143) SYG124/125 (PLAN-4 CT-1) and SYG127 (GS-1) are dev-entry-only codes: their severities live in
+ * DEV_CODE_SEVERITY (codes.ts), registered by ./shared, not in the main bundle.
+ *
  * Strict checks (SYG5xx) only report after configureStrict(true) (or
  * renderComponent(C, { strict: true }), or globalThis.__SYGNAL_STRICT__).
  */
@@ -38,16 +82,35 @@ import {eventsCheck} from './events'
 import {propsCheck} from './props'
 import {collectionsCheck} from './collections'
 import {domCheck} from './dom'
+import {shorthandCheck} from './shorthand'
+import {controlsCheck, installControlHooks} from './controls'
+import {elementCommandsCheck, installElementCommandHooks} from './elementCommands'
+import {installWidgetHooks} from './widgets'
+import {installVirtualHooks} from './virtual'
+import {behaviorsCheck} from './behaviors'
+import {formsCheck, installFormHooks} from './forms'
+import {installSortableHooks} from './sortable'
+import {datasetCheck} from './dataset'
 import {strictCheck} from './strict'
+import {repliesCheck} from './replies'
+import {routerCheck, installRouterHooks} from './router'
+import {fetchCheck} from './fetch'
+import {timersCheck, installTimerHooks} from './timers'
+import {installBrowserSourceHooks} from './browserSources'
+import {installChatHooks} from './chat'
+import {persistCheck} from './persist'
+import {viewTransitionsCheck} from './viewTransitions'
+import {staticsCheck} from './statics'
 import {installRxjsHints} from './rxjsHints'
 import {inspectCheck, installInspect} from './inspect'
+import {nextHooks} from './next'
 
 export {checkEventBus} from './events'
 export {configureStrict, isStrictEnabled} from './strict'
 export type {EventBusSummary} from './events'
 export {RXJS_HINTS} from './rxjsHints'
 export {inspect} from './inspect'
-export type {InspectGraph, InspectComponent, InspectAction, InspectActionTrigger, InspectChild, InspectSelector, InspectDiagnostic, InspectOptions} from './public'
+export type {InspectResource, InspectCacheEntry, InspectGraph, InspectComponent, InspectAction, InspectActionTrigger, InspectChild, InspectSelector, InspectControl, InspectDiagnostic, InspectOptions, InspectRecentAction} from './public'
 export {listCodes, getCodeInfo} from '../codes'
 export type {DiagnosticCodeInfo} from '../codes'
 
@@ -59,7 +122,20 @@ export const checks: DiagnosticCheck[] = [
   propsCheck,
   collectionsCheck,
   domCheck,
+  shorthandCheck,
+  controlsCheck,
+  elementCommandsCheck,
+  behaviorsCheck,
+  formsCheck,
+  datasetCheck,
   strictCheck,
+  repliesCheck,
+  routerCheck,
+  fetchCheck,
+  timersCheck,
+  persistCheck,
+  viewTransitionsCheck,
+  staticsCheck,
   inspectCheck,
 ]
 
@@ -75,10 +151,33 @@ export function installChecks(): () => void {
   const unregister = checks.map(check => core.registerCheck(check))
   const uninstallHints = installRxjsHints(Stream && Stream.prototype)
   const uninstallInspect = installInspect()
+  const uninstallRouter = installRouterHooks()
+  const uninstallControls = installControlHooks()
+  const uninstallTimers = installTimerHooks()
+  const uninstallBrowser = installBrowserSourceHooks()
+  const uninstallChat = installChatHooks()
+  const uninstallElementCommands = installElementCommandHooks()
+  const uninstallWidgets = installWidgetHooks()
+  const uninstallVirtual = installVirtualHooks()
+  const uninstallForms = installFormHooks()
+  const uninstallSortable = installSortableHooks()
+  // PLAN-4.6 R4: the core reads its hooks from the bridge once per app (checks/next.ts)
+  ;(core.layers ||= new Set()).add(nextHooks)
   const uninstall = () => {
+    core.layers?.delete(nextHooks)
     unregister.forEach(fn => fn())
     uninstallHints()
     uninstallInspect()
+    uninstallRouter()
+    uninstallControls()
+    uninstallTimers()
+    uninstallBrowser()
+    uninstallChat()
+    uninstallElementCommands()
+    uninstallWidgets()
+    uninstallVirtual()
+    uninstallForms()
+    uninstallSortable()
     if (core.__uninstallChecks === uninstall) core.__uninstallChecks = undefined
   }
   core.__uninstallChecks = uninstall

package/src/extra/diagnostics/checks/inspect.ts

@@ -6,16 +6,19 @@
  *   onIntent    registers the instance (name, parent, kind) and its intent
  *               action names; claims the EVENTS.select() types seen since the
  *               previous onIntent (intent runs synchronously right before it)
- *   onModel     action -> sinks; and wraps the component's own EVENTS model
- *               stream (component.model$.EVENTS, before initSinks merges it)
- *               in an identity map that records the emitted types. Since
- *               B-023 the driver-side emitter name (onBusEmit) is the
- *               emitting component's, but it is only a name, and this
- *               graph is per instance, so the per-instance tap stays.
- *   onReducer   which model-only actions actually ran (=> dispatched by next())
+ *   onModel     action -> sinks
+ *   onSink      (checks/next.ts: eventEmitted) the EVENTS types the instance emitted. Since
+ *               B-023 the driver-side emitter name (onBusEmit) is the emitting
+ *               component's, but it is only a name, and this graph is per instance
+ *   onReducer   which model-only actions actually ran (=> dispatched by next(),
+ *               unless a request named them as reply actions: replies.ts, 'reply')
  *   onBusEmit   EVENTS types seen on the bus
  *   onBusSelect EVENTS types selected (see onIntent)
+ *   onRender    (PLAN-4 CT-1) the controls the instance renders: its own vtree, up to the
+ *               isolated child components, through ./controls' vnode -> control map
  *   onDispose   prunes the instance
+ *   (PLAN-4 2-C) the action log (./actionLog: actionHooks, a layer of checks/next.ts) feeds
+ *               inspect({ actions }): the recent actions (the last RECENT_MAX, any instance)
  * Selectors come from the DOM check (real DOM) or from renderComponent (mock
  * DOM, passed in as options.selectors). The same shape is produced statically
  * by `sygnal-check --graph`; the JSON Schema is
@@ -27,10 +30,13 @@
  * (window.__SYGNAL_DEVTOOLS__, which is getDevTools()) once it exists.
  */
 import type {DiagnosticCheck} from '../index'
-import type {InspectGraph, InspectComponent, InspectOptions, InspectSelector, InspectDiagnostic, InspectChild} from './public'
-import {bridge, onReset, nameOf, isPlainObject, BUILTIN_ACTIONS} from './shared'
+import type {InspectGraph, InspectComponent, InspectOptions, InspectSelector, InspectDiagnostic, InspectChild, InspectResource, InspectControl, InspectRecentAction} from './public'
+import {clockNow} from './actionLog'
+import type {ActionListener, ActionRecord} from './actionLog'
+import {bridge, onReset, nameOf, isPlainObject, BUILTIN_ACTIONS, replySeen} from './shared'
 import {checkEventBus} from './events'
 import {selectorStatus} from './dom'
+import {controlOfVnode, keyOfSelector} from './controls'
 
 type Kind = InspectComponent['kind']
 
@@ -47,34 +53,42 @@ interface Rec {
   fired: Set<string>
   eventsSelected: Set<string>
   eventsEmitted: Set<string>
+  /** CT-1: controls seen in its renders, by key (first-seen order) */
+  controls: Map<string, {element: string | null; kind?: string}>
 }
 
 let records = new Map<any, Rec>()
 let pendingSelects: string[] = []
 /** every EVENTS type seen on the bus */
 let busTypes = new Set<string>()
+/** PLAN-4 2-C (GS-10): the most recent actions of any instance, oldest first */
+const RECENT_MAX = 200
+let recent: ActionRecord[] = []
+let epoch = clockNow()
+export const actionListener: ActionListener = {
+  action(r) { if (recent.push(r) > RECENT_MAX) recent.shift() },
+}
 
 onReset(() => {
   records = new Map()
   pendingSelects = []
   busTypes = new Set()
+  recent = []
+  epoch = clockNow()
 })
 const uniq = <T>(list: Iterable<T>): T[] => [...new Set(list)]
 
+const NEXT_KIND: Record<string, Kind> = {root: 'root', child: 'child', item: 'collection-item', page: 'switchable'}
+
 function kindOf(c: any): Kind {
-  const s = (c && c.sources) || {}
-  if (typeof s.__parentComponentNumber !== 'number') return 'root'
-  // Collection items get PARENT: null (src/component.ts instantiateCollection)
-  if ('PARENT' in s && s.PARENT === null) return 'collection-item'
-  // switchable() adds a lower-case `state` source next to the component's own (src/switchable.ts)
-  if (c.stateSourceName !== 'state' && 'state' in s && s.state !== s[c.stateSourceName]) return 'switchable'
-  return 'child'
+  // PLAN-4.6 R4: the core's instance view says it (checks/next.ts)
+  return (c && c.__next && NEXT_KIND[c.__next.kind]) || 'child'
 }
 
 function ensure(c: any): Rec {
   let r = records.get(c)
   if (!r) {
-    const parent = c && c.sources && c.sources.__parentComponentNumber
+    const parent = c && c.__next && c.__next.parentId
     r = {
       instance: c,
       id: String(c && c._componentNumber),
@@ -87,6 +101,7 @@ function ensure(c: any): Rec {
       fired: new Set(),
       eventsSelected: new Set(),
       eventsEmitted: new Set(),
+      controls: new Map(),
     }
     records.set(c, r)
   }
@@ -116,7 +131,7 @@ export const inspectCheck: DiagnosticCheck = {
     attachDevtools()
     const r = ensure(component)
     const intent$ = component && component.intent$
-    r.intentActions = intent$ && typeof intent$.addListener === 'function' ? null : (actionNames || [])
+    r.intentActions = actionNames || []
     r.injected = new Set((intent$ && typeof intent$ === 'object' && intent$.__sygnalTestActions) || [])
     for (const t of pendingSelects) r.eventsSelected.add(t)
     pendingSelects = []
@@ -125,16 +140,11 @@ export const inspectCheck: DiagnosticCheck = {
   onModel(component, modelMap) {
     const r = ensure(component)
     r.modelMap = modelMap || {}
-    const model$ = component && component.model$
-    const events$ = model$ && model$.EVENTS
-    if (events$ && typeof events$.map === 'function' && !events$.__sygnalInspect) {
-      const tapped = events$.map((ev: any) => {
-        if (ev && typeof ev.type === 'string') r.eventsEmitted.add(ev.type)
-        return ev
-      })
-      tapped.__sygnalInspect = true
-      model$.EVENTS = tapped
-    }
+  },
+
+  onRender(component, root) {
+    const r = records.get(component)
+    if (r) collectControls(root, r.controls, true)
   },
 
   onReducer(component, action) {
@@ -151,6 +161,45 @@ export const inspectCheck: DiagnosticCheck = {
   },
 }
 
+/** PLAN-4.6 R4 (onSink): an EVENTS value the instance sent */
+export function eventEmitted(component: any, ev: any): void {
+  const r = records.get(component)
+  if (r && ev && typeof ev.type === 'string') r.eventsEmitted.add(ev.type)
+}
+
+/**
+ * CT-1: record the controls in a component's rendered tree (data-control="<Key>"), stopping at
+ * isolated child components (their root carries data.isolate on the real DOM, a '.___<scope>'
+ * class in the mock DOM): the controls inside belong to the child.
+ */
+function collectControls(v: any, out: Rec['controls'], root: boolean): void {
+  if (!v || typeof v != 'object') return
+  if (!root && typeof v.sel == 'string' && ((v.data && v.data.isolate) || v.sel.includes('.___'))) return
+  const key = v.data && v.data.attrs && v.data.attrs['data-control']
+  if (typeof key == 'string' && !out.has(key)) {
+    const control = controlOfVnode(v)
+    const spec = control && control.spec
+    out.set(key, spec && typeof spec == 'object'
+      ? {element: null, kind: String(spec.kind)}
+      : {element: typeof spec == 'string' ? spec : typeof v.sel == 'string' ? v.sel.split(/[.#]/)[0] : null})
+  }
+  for (const k of [].concat(v.children || [], (v.data && v.data.portalChildren) || [])) collectControls(k, out, false)
+}
+
+/** CT-1: the controls a component rendered, `listened` from its intent's selectors */
+function controlsOf(r: Rec, selectors: InspectSelector[]): InspectControl[] | undefined {
+  if (!r.controls.size) return undefined
+  const listened = new Set<string>()
+  for (const s of selectors) for (const m of s.selector.matchAll(/\[data-control="([^"]+)"\]/g)) listened.add(m[1])
+  return [...r.controls].map(([name, {element, kind}]) => ({name, element, ...(kind ? {kind} : {}), listened: listened.has(name)}))
+}
+
+/** CT-1: mark a selector that is a control ([data-control="<Key>"]) with its key */
+const withControl = (s: InspectSelector): InspectSelector => {
+  const key = keyOfSelector(s.selector)
+  return key ? {...s, control: key} : s
+}
+
 const slim = (d: any): InspectDiagnostic => {
   const out: InspectDiagnostic = {code: d.code, severity: d.severity, message: d.message}
   if (d.component) out.component = d.component
@@ -166,10 +215,12 @@ const slim = (d: any): InspectDiagnostic => {
 function actionsOf(r: Rec): InspectComponent['actions'] {
   const intent = (r.intentActions || []).filter(a => !r.injected.has(a))
   const names = uniq([...intent, ...Object.keys(r.modelMap)]).filter(a => typeof a === 'string' && !a.startsWith('__'))
+  const replies = replySeen.get(r.instance)
   return names.map(name => ({
     name,
     trigger: BUILTIN_ACTIONS.has(name) ? 'builtin'
       : intent.includes(name) ? 'intent'
+      : replies?.has(name) ? 'reply'
       : !r.injected.has(name) && r.fired.has(name) ? 'next'
       : 'unknown',
     sinks: [...(r.modelMap[name] || [])],
@@ -181,6 +232,32 @@ function stateKeysOf(c: any, calculated: string[]): string[] {
   return isPlainObject(s) ? Object.keys(s).filter(k => !calculated.includes(k)) : []
 }
 
+/** PLAN-3 5-3: the instance's resources (`resources` static) and their state slots */
+function resourcesOf(c: any): InspectResource[] | undefined {
+  const res = c && c.view && c.view.resources
+  if (!res || typeof res !== 'object') return undefined
+  const s = c.currentState || {}
+  return Object.keys(res).map(name => {
+    const r = s[name] || {}
+    return {name, status: r.status ?? 'idle', refreshing: !!r.refreshing, hasData: r.data !== undefined, error: r.error ? String(r.error.message ?? r.error) : undefined}
+  })
+}
+
+/** PLAN-3 5-3: the cache entries of every makeFetchDriver source the instances use, by sink name (sinks with an empty cache left out) */
+function cacheOf(recs: Rec[]): InspectGraph['cache'] {
+  const out: NonNullable<InspectGraph['cache']> = {}
+  for (const r of recs) {
+    const sources = r.instance && r.instance.sources
+    if (!sources || typeof sources !== 'object') continue
+    for (const k of Object.keys(sources)) {
+      const src = sources[k]
+      if (out[k] || !src || src.__sygnalStatic !== 'resources' || typeof src.__inspect !== 'function') continue
+      try { const list = src.__inspect().cache; if (list.length) out[k] = list } catch (_) { /* a driver without the cache listing */ }
+    }
+  }
+  return out
+}
+
 /**
  * renderComponent's mock DOM (src/extra/testing.ts passes its listener registry):
  * listener paths are the select() chain with isolation scopes as '.___<scope>' entries;
@@ -219,16 +296,16 @@ function mockSelectors(mock: MockDom): Record<string, InspectSelector[]> {
 
 function selectorsOf(r: Rec, options: InspectOptions, diags: any[]): InspectSelector[] {
   const given = options.selectors && options.selectors[r.id]
-  if (given) return given.map(s => ({...s}))
+  if (given) return given.map(s => withControl({...s}))
   return (selectorStatus(r.instance) || []).map(({selector, matched, crossed}) => {
     const hit = diags.find(d => d.code === 'SYG104' && d.component === r.name && d.data && d.data.selector === selector)
     const missed = diags.some(d => d.code === 'SYG103' && d.component === r.name && d.data && d.data.selector === selector)
-    return {
+    return withControl({
       selector,
       events: null,
       matched: matched === null && missed ? false : matched,
       isolationHit: crossed ? ((hit && hit.data.child) || 'a child component') : null,
-    }
+    })
   })
 }
 
@@ -267,6 +344,8 @@ export function inspect(options: InspectOptions = {}): InspectGraph {
   const components: InspectComponent[] = recs.map(r => {
     const c = r.instance
     const calculated = c && c.calculated && typeof c.calculated === 'object' ? Object.keys(c.calculated) : []
+    const selectors = selectorsOf(r, options, diags)
+    const controls = controlsOf(r, selectors)
     return {
       name: r.name,
       id: r.id,
@@ -280,11 +359,14 @@ export function inspect(options: InspectOptions = {}): InspectGraph {
       eventsEmitted: [...r.eventsEmitted],
       eventsSelected: [...r.eventsSelected],
       children: childrenOf(r, all),
-      selectors: selectorsOf(r, options, diags),
+      selectors,
+      ...(controls ? {controls} : {}),
       diagnostics: diags.filter(d => d && d.component === r.name).map(slim),
+      ...(resourcesOf(c) ? {resources: resourcesOf(c)} : {}),
     }
   })
 
+  const cache = cacheOf(recs) || {}
   const events: InspectGraph['events'] = {}
   const ev = (type: string) => events[type] || (events[type] = {emitters: [], selectors: []})
   const add = (list: string[], name: string) => { if (!list.includes(name)) list.push(name) }
@@ -301,9 +383,35 @@ export function inspect(options: InspectOptions = {}): InspectGraph {
     components,
     events,
     diagnostics: diags.filter(d => d && (!d.component || !names.has(d.component))).map(slim),
+    ...(Object.keys(cache).length ? {cache} : {}),
+    ...(options.actions ? {recentActions: recentActions(options.actions, ids)} : {}),
   }
 }
 
+/** a JSON-safe copy of an action's data (dropped when it doesn't serialize, or is large: a DOM event) */
+function jsonData(d: any): {data?: any} {
+  if (d === undefined) return {}
+  try {
+    const text = JSON.stringify(d)
+    return text === undefined || text.length > 1000 ? {} : {data: JSON.parse(text)}
+  } catch (_) { return {} }
+}
+
+/** PLAN-4 2-C: the last `limit` actions (true: all kept) of the listed instances */
+function recentActions(limit: true | number, ids: Set<string> | undefined): InspectRecentAction[] {
+  const list = ids ? recent.filter(r => ids.has(r.instance)) : recent
+  const n = limit === true ? list.length : Math.max(0, Math.floor(limit))
+  return list.slice(list.length - n).map(r => ({
+    type: r.type,
+    ...jsonData(r.data),
+    component: r.component,
+    instance: r.instance,
+    sinks: [...r.sinks],
+    cause: r.cause,
+    at: r.time - epoch,
+  }))
+}
+
 /** Publish inspect() on the core bridge and the devtools object. Returns an uninstall function. */
 export function installInspect(): () => void {
   const core = bridge()