sygnal 5.3.7 → 6.0.0

package/src/extra/diagnostics/index.ts

@@ -0,0 +1,353 @@
+/**
+ * Sygnal diagnostics core.
+ *
+ * ===========================================================================
+ * FROZEN INTERFACE (PLAN-1 workstream 0B). Changes after the 0B merge go
+ * through the coordinator. Later workstreams add checks (registerCheck) and
+ * codes (./codes.ts, inside their reserved range) — they do not change these
+ * signatures.
+ * ===========================================================================
+ *
+ * --- Reporting ------------------------------------------------------------
+ *
+ *   report(code: string, details: {
+ *     component?: string | { name?: string }   // component name or instance
+ *     message: string                          // what is wrong
+ *     fix?: string                             // how to fix it
+ *     data?: any                               // structured payload
+ *     severity?: 'error' | 'warn' | 'info'     // override the code's default
+ *   }): Diagnostic | undefined
+ *
+ *     - mode 'off'     → no-op, returns undefined (nothing collected/printed)
+ *     - code in ignore list → no-op, returns undefined
+ *     - mode 'collect' → collected, no console output
+ *     - mode 'warn'    → collected; 'warn' → console.warn, 'error' → console.error,
+ *                        'info' → collected only
+ *     - mode 'error'   → collected; 'warn'/'error' severities throw a
+ *                        DiagnosticError (err.diagnostic holds the Diagnostic);
+ *                        'info' collected only. Called directly this throws
+ *                        synchronously; raised during a hook (i.e. from a
+ *                        check) it is rethrown asynchronously — see Hooks.
+ *
+ *     `diagnostic.text` is formatted lazily (getter) on first read.
+ *
+ *   formatDiagnostic(code, details): string
+ *     → `[Sygnal SYG123] <Component>: <message>. <fix> <docsUrl>`
+ *       (works in every mode; for call sites that must keep printing in 'off')
+ *
+ *   getDiagnostics(): Diagnostic[]          // copy of the collected list
+ *   clearDiagnostics(): void
+ *   onDiagnostic(cb: (d: Diagnostic) => void): () => void   // returns unsubscribe
+ *
+ * --- Configuration --------------------------------------------------------
+ *
+ *   configureDiagnostics({ mode?: DiagnosticsMode | undefined, ignore?: string[] }): void
+ *   getDiagnosticsMode(): 'off' | 'collect' | 'warn' | 'error'
+ *   isDiagnosticsEnabled(): boolean
+ *
+ *   Mode resolution — first defined wins:
+ *     1. explicit mode: run(App, drivers, { diagnostics }) or configureDiagnostics({ mode })
+ *     2. globalThis.__SYGNAL_DEV__ (=== true → 'warn'; injected by the Vite plugin in serve)
+ *     3. 'off'
+ *   The mode is resolved at module load, on every run() call and on every
+ *   configureDiagnostics() call. `configureDiagnostics({ mode: undefined })`
+ *   clears the explicit mode and falls back to steps 2-3.
+ *   A run() call with the `diagnostics` option sets both the explicit mode and
+ *   the ignore list from it. run() WITHOUT the option resets them to the
+ *   defaults (no explicit mode, empty ignore list), so a setting from an earlier
+ *   run()/configureDiagnostics() does not leak in, unless another app is still
+ *   running (G-212: a second app or a custom element keeps the host's mode).
+ *
+ * --- Checks ---------------------------------------------------------------
+ *
+ *   registerCheck(check: DiagnosticCheck): () => void      // returns unregister
+ *
+ *   interface DiagnosticCheck {
+ *     id: string
+ *     onIntent?(component, actionNames: string[], selectorsUsed: string[] | undefined): void
+ *     onModel?(component, modelMap: Record<string, string[]>): void
+ *     onRender?(component, rootVnode: any): void
+ *     onReducer?(component, action: string, prevState: any, nextState: any, sinkName: string): void
+ *     onDispose?(component): void
+ *   }
+ *
+ *   A check that throws (other than a DiagnosticError from 'error' mode) is
+ *   isolated: the exception is reported as SYG900 and other checks still run.
+ *
+ * --- Hooks (dispatched by checks/next.ts from the core's hook layer) ----
+ *
+ *   onIntent(component, actionNames, selectorsUsed?)
+ *     after intent is built. actionNames = keys of the intent object ([] for a
+ *     single-stream intent). selectorsUsed is currently always undefined —
+ *     TODO(1A): collect via MainDOMSource.select instrumentation in src/cycle/dom.
+ *   onModel(component, modelMap)
+ *     after the model is normalized; modelMap = action → sink names, shorthand
+ *     ('A | SINK') expanded, plain functions mapped to the state sink,
+ *     includes built-ins such as INITIALIZE.
+ *   onRender(component, rootVnode)
+ *     after each render of the component (fully injected vnode, before the DOM
+ *     driver patches it; `rootVnode.elm` is populated after the patch, so DOM
+ *     checks should defer, e.g. with a microtask/timeout).
+ *   onReducer(component, action, prevState, nextState, sinkName)
+ *     after each STATE reducer returns (not for ABORT, not when the reducer
+ *     throws). nextState is the raw reducer return value (before calculated
+ *     field cleanup). Currently only fired for the state sink; sinkName is the
+ *     component's state source name.
+ *   onDispose(component)
+ *     at the start of component disposal.
+ *
+ *   onSelector(domSource, selector)          (additive, 1A)
+ *     from MainDOMSource.select() in src/cycle/dom, for every CSS selector
+ *     (not 'document' / 'body' / ':root'). domSource is the source select()
+ *     was called on (its `.namespace` holds the isolation scopes and any
+ *     earlier selectors; `._isolateModule` the DOM driver's isolate module).
+ *   onBusEmit(type, emitterName?)            (additive, 1A)
+ *     from the EVENTS driver (src/extra/eventDriver.ts) for every bus event.
+ *   onBusSelect(type)                        (additive, 1A)
+ *     from EVENTS.select(type); type is the raw argument (string, string[]
+ *     or undefined for "all events").
+ *
+ *   Checks live in the separate 'sygnal/diagnostics' entry
+ *   (src/extra/diagnostics/checks). That bundle reaches THIS module instance
+ *   through globalThis.__SYGNAL_DIAGNOSTICS__ = { registerCheck, report }
+ *   (set below), so it never carries a second copy of the core state.
+ *
+ *   onIntent and onModel are each called exactly once per component instance,
+ *   in that order, during construction (also when the component has no
+ *   intent → actionNames [], or no model → modelMap {}).
+ *
+ *   `component` is the internal Component instance (stable identity per
+ *   instance; `.name` is the component name).
+ *
+ *   In mode 'off' a hook only runs the checks registered with `always: true`
+ *   (internal: renderComponent's own bookkeeping, R2-3); none are registered
+ *   in an app, so the hooks do nothing.
+ *
+ *   Hooks NEVER throw synchronously into Sygnal's stream pipeline (a throw
+ *   there would kill the state/view stream for good). Every exception from a
+ *   check is caught. In 'error' mode a DiagnosticError raised during a hook —
+ *   by a check's report() call, or by the SYG900 report for a check that
+ *   threw a plain Error — is rethrown ASYNCHRONOUSLY (queueMicrotask, falling
+ *   back to setTimeout), so test runners still see an uncaught error while
+ *   the app's streams keep running. The remaining checks still run.
+ *   `_setAsyncThrow(fn?)` replaces the async rethrow (test seam; no argument
+ *   restores the default; `_resetDiagnostics()` also restores it).
+ *
+ * (This comment is attached to the type-only import below so the TypeScript
+ * emit drops it — keeps it out of the published bundle and the size gate.)
+ */
+import type { DiagnosticSeverity } from './codes'
+import { CODE_SEVERITY, docsUrlFor } from './codes'
+
+
+export type DiagnosticsMode = 'off' | 'collect' | 'warn' | 'error'
+
+export interface DiagnosticDetails {
+  component?: string | { name?: string }
+  message: string
+  fix?: string
+  data?: any
+  severity?: DiagnosticSeverity
+}
+
+export interface Diagnostic {
+  code: string
+  severity: DiagnosticSeverity
+  component?: string
+  message: string
+  fix?: string
+  data?: any
+  docsUrl: string
+  text: string
+  timestamp: number
+}
+
+export interface DiagnosticsOptions {
+  mode?: DiagnosticsMode
+  ignore?: string[]
+}
+
+export interface DiagnosticCheck {
+  id: string
+  /** internal: also runs when diagnostics are 'off' (renderComponent's harness hooks) */
+  always?: boolean
+  onIntent?: (component: any, actionNames: string[], selectorsUsed: string[] | undefined) => void
+  onModel?: (component: any, modelMap: Record<string, string[]>) => void
+  onRender?: (component: any, rootVnode: any) => void
+  onReducer?: (component: any, action: string, prevState: any, nextState: any, sinkName: string) => void
+  onDispose?: (component: any) => void
+  onSelector?: (domSource: any, selector: string) => void
+  onBusEmit?: (type: string, emitterName?: string) => void
+  onBusSelect?: (type: string | string[] | undefined) => void
+  /**
+   * (additive, PLAN-2 E2) Called before a component's intent runs. May return a replacement
+   * for `sources` (e.g. a Proxy that reports or fakes a source with no driver); the intent
+   * gets the last one returned. See sourcesFor().
+   */
+  sources?: (component: any, sources: any) => any
+}
+
+export class DiagnosticError extends Error {
+  diagnostic: Diagnostic
+  constructor(diagnostic: Diagnostic) {
+    super(diagnostic.text)
+    this.diagnostic = diagnostic
+  }
+}
+
+let explicitMode: DiagnosticsMode | undefined
+let mode: DiagnosticsMode = 'off'
+let enabled = false
+let ignored = new Set<string>()
+let collected: Diagnostic[] = []
+let listeners: Array<(d: Diagnostic) => void> = []
+let checks: DiagnosticCheck[] = []
+
+export function resolveDiagnosticsMode(): DiagnosticsMode {
+  mode = explicitMode || ((globalThis as any).__SYGNAL_DEV__ === true ? 'warn' : 'off')
+  enabled = mode !== 'off'
+  return mode
+}
+
+export function configureDiagnostics(options: DiagnosticsOptions = {}): void {
+  if ('mode' in options) explicitMode = options.mode
+  if (options.ignore) ignored = new Set(options.ignore)
+  resolveDiagnosticsMode()
+}
+
+/** Internal: the explicit configuration (not the resolved mode), so it can be restored exactly. */
+export function _getDiagnosticsConfig(): { mode: DiagnosticsMode | undefined, ignore: string[] } {
+  return { mode: explicitMode, ignore: [...ignored] }
+}
+
+export function getDiagnosticsMode(): DiagnosticsMode {
+  return mode
+}
+
+export function isDiagnosticsEnabled(): boolean {
+  return enabled
+}
+
+const nameOf = (c: DiagnosticDetails['component']) => (c && typeof c === 'object' ? c.name : c) || undefined
+const sentence = (s: string) => /[.!?]$/.test(s) ? s : s + '.'
+
+export function formatDiagnostic(code: string, details: DiagnosticDetails): string {
+  const name = nameOf(details.component)
+  return `[Sygnal ${code}] ${name ? name + ': ' : ''}${sentence(details.message)}` +
+    (details.fix ? ' ' + sentence(details.fix) : '') + ' ' + docsUrlFor(code)
+}
+
+export function report(code: string, details: DiagnosticDetails): Diagnostic | undefined {
+  if (!enabled || ignored.has(code)) return
+  const severity = details.severity || CODE_SEVERITY[code] || 'warn'
+  const d: Diagnostic = {
+    code,
+    severity,
+    component: nameOf(details.component),
+    message: details.message,
+    fix: details.fix,
+    data: details.data,
+    docsUrl: docsUrlFor(code),
+    get text() { return formatDiagnostic(code, this) },
+    timestamp: Date.now(),
+  }
+  if (collected.push(d) > 500) collected.shift()
+  listeners.forEach(cb => { try { cb(d) } catch (_) {} })
+  if (severity !== 'info') {
+    if (mode === 'error') throw new DiagnosticError(d)
+    if (mode === 'warn') console[severity](d.text)
+  }
+  return d
+}
+
+export function getDiagnostics(): Diagnostic[] {
+  return collected.slice()
+}
+
+export function clearDiagnostics(): void {
+  collected = []
+}
+
+export function onDiagnostic(cb: (d: Diagnostic) => void): () => void {
+  listeners = [...listeners, cb]
+  return () => { listeners = listeners.filter(l => l !== cb) }
+}
+
+export function registerCheck(check: DiagnosticCheck): () => void {
+  checks = [...checks, check]
+  return () => { checks = checks.filter(c => c !== check) }
+}
+
+type HookName = Exclude<keyof DiagnosticCheck, 'id'>
+
+const defaultAsyncThrow = (err: any): void => {
+  const raise = () => { throw err }
+  typeof queueMicrotask === 'function' ? queueMicrotask(raise) : setTimeout(raise)
+}
+let asyncThrow = defaultAsyncThrow
+
+/** Test seam: replace the async rethrow used for 'error'-mode diagnostics raised in hooks. */
+export function _setAsyncThrow(fn?: (err: any) => void): void {
+  asyncThrow = fn || defaultAsyncThrow
+}
+
+const hook = (name: HookName) => (component: any, ...args: any[]): void => {
+  for (const check of checks) {
+    if (!enabled && !check.always) continue
+    try {
+      (check[name] as any)?.(component, ...args)
+    } catch (err: any) {
+      // Never throw into the stream pipeline: 'error'-mode diagnostics (also a
+      // SYG900 escalated by 'error' mode) are rethrown asynchronously.
+      try {
+        if (err instanceof DiagnosticError) throw err
+        report('SYG900', {
+          component,
+          message: `Diagnostics check '${check.id}' threw in ${name}: ${err?.message}`,
+          data: { check: check.id, hook: name, error: err },
+        })
+      } catch (e) {
+        asyncThrow(e)
+      }
+    }
+  }
+}
+
+export const onIntent: (component: any, actionNames: string[], selectorsUsed?: string[]) => void = hook('onIntent')
+export const onModel: (component: any, modelMap: Record<string, string[]>) => void = hook('onModel')
+export const onRender: (component: any, rootVnode: any) => void = hook('onRender')
+export const onReducer: (component: any, action: string, prevState: any, nextState: any, sinkName: string) => void = hook('onReducer')
+export const onDispose: (component: any) => void = hook('onDispose')
+export const onSelector: (domSource: any, selector: string) => void = hook('onSelector')
+export const onBusEmit: (type: string, emitterName?: string) => void = hook('onBusEmit')
+export const onBusSelect: (type: string | string[] | undefined) => void = hook('onBusSelect')
+
+/**
+ * (PLAN-2 E2) The sources object a component's intent is called with: `component.sources`,
+ * wrapped by every active check with a `sources` hook (the dev entry's SYG609 check,
+ * renderComponent's fake sources). Without such a check it is `component.sources` itself.
+ */
+export function sourcesFor(component: any): any {
+  let s = component.sources
+  for (const check of checks) {
+    if (!check.sources || (!enabled && !check.always)) continue
+    try { s = check.sources(component, s) || s } catch (_) {}
+  }
+  return s
+}
+
+// Bridge for the separately bundled 'sygnal/diagnostics' checks entry.
+// PLAN-4.6 R4: the hook dispatchers too, for the dev entry's core adapter (checks/next.ts)
+;(globalThis as any).__SYGNAL_DIAGNOSTICS__ = { registerCheck, report, hooks: { onIntent, onModel, onRender, onReducer, onDispose, sourcesFor, on: isDiagnosticsEnabled } }
+
+export function _resetDiagnostics(): void {
+  explicitMode = undefined
+  ignored = new Set()
+  collected = []
+  listeners = []
+  checks = []
+  asyncThrow = defaultAsyncThrow
+  resolveDiagnosticsMode()
+}
+
+resolveDiagnosticsMode()

package/src/extra/diagnostics/legacy.ts

@@ -0,0 +1,76 @@
+/**
+ * Coded console output for Sygnal's pre-existing warnings and errors
+ * (PLAN-1 workstream 1E).
+ *
+ *   warn(code, component, message, fix?, extra?)
+ *   error(code, component, message, fix?, extra?)
+ *   fail(code, component, message, fix?): never
+ *
+ * `component` is a component instance (anything with `.name`), a name string,
+ * or undefined. `extra` (an Error, the offending value, ...) is passed to the
+ * console after the formatted text, as the old messages did.
+ *
+ * Unlike report(), warn()/error() keep printing when diagnostics are 'off',
+ * so production apps see the same messages as before (now with a code):
+ *   - 'off'     → console.warn/error(formatDiagnostic(...), extra?)
+ *   - 'collect' → report(): collected; error severity is also printed with
+ *                 console.error (so exceptions stay visible in tests), warn isn't
+ *   - 'warn'    → report(): collected and printed once by report(); `extra`
+ *                 (e.g. the caught Error with its stack) printed after it
+ *   - 'error'   → report() throws a DiagnosticError; it is rethrown
+ *                 asynchronously so the stream pipeline that hit the problem
+ *                 keeps running (same contract as the hooks in ./index)
+ *   - code in the ignore list → nothing printed
+ *
+ * fail() always throws an Error whose message is the formatted text and whose
+ * `.code` is the diagnostic code. It does not go through report(): the throw
+ * itself is the signal, in every mode.
+ *
+ * A call site that catches an exception and keeps running reports it with the
+ * core's caught() (src/core/runtime.ts: an error thrown by fail() under ITS code,
+ * G-027 / G-044), then the app's onError hook (callHook, PLAN-4 GS-11).
+ *
+ * `error` is also published on the core bridge
+ * (globalThis.__SYGNAL_DIAGNOSTICS__.error) for the separately bundled JSX
+ * runtime (SYG420).
+ *
+ * (This comment is attached to the type-only import below so the TypeScript
+ * emit drops it.)
+ */
+import type { DiagnosticSeverity } from './codes'
+import { report, formatDiagnostic, getDiagnosticsMode } from './index'
+
+const emit = (severity: Extract<DiagnosticSeverity, 'warn' | 'error'>) =>
+  (code: string, component: any, message: string, fix?: string, ...extra: any[]): void => {
+    const details = { component, message, fix, severity, data: extra[0] }
+    const mode = getDiagnosticsMode()
+    if (mode === 'off') {
+      console[severity](formatDiagnostic(code, details), ...extra)
+      return
+    }
+    try {
+      const d = report(code, details)
+      if (d && mode === 'collect' && severity === 'error') console.error(d.text, ...extra)
+      else if (d && mode === 'warn' && extra.length) console[severity](...extra)
+    } catch (err) {
+      setTimeout(() => { throw err })
+    }
+  }
+
+export const warn = emit('warn')
+export const error = emit('error')
+
+export function fail(code: string, component: any, message: string, fix?: string): never {
+  const err: any = new Error(formatDiagnostic(code, { component, message, fix }))
+  err.code = code
+  err.sygnal = [component, message, fix]
+  throw err
+}
+
+// PLAN-4 GS-11: the app's error hook (run(App, drivers, { onError })), reporting only (each app
+// has its own). A throwing hook is logged once and swallowed
+export const callHook = (hook: any, err: any, info: any): void => {
+  try { hook && hook(err, info) } catch (e) { console.error(e) }
+}
+
+;(globalThis as any).__SYGNAL_DIAGNOSTICS__.error = error