sygnal 5.3.6 → 5.4.0

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

@@ -0,0 +1,119 @@
+/**
+ * Shared plumbing for the runtime checks (PLAN-1 workstream 1A).
+ *
+ * The checks are bundled separately from the main 'sygnal' entry
+ * ('sygnal/diagnostics'). They must talk to the SAME diagnostics core
+ * instance the components use, so they never import the core's functions
+ * directly: `import '../index'` only makes sure the core is loaded (in the
+ * dist build that import is rewritten to the external 'sygnal' package, see
+ * rollup.config.mjs), and the functions are read from the bridge object the
+ * core publishes on globalThis.__SYGNAL_DIAGNOSTICS__.
+ */
+import '../index'
+import type {DiagnosticCheck, DiagnosticDetails, Diagnostic} from '../index'
+
+interface CoreBridge {
+  registerCheck(check: DiagnosticCheck): () => void
+  report(code: string, details: DiagnosticDetails): Diagnostic | undefined
+  [key: string]: any
+}
+
+export const bridge = (): CoreBridge => (globalThis as any).__SYGNAL_DIAGNOSTICS__
+
+export const report = (code: string, details: DiagnosticDetails): Diagnostic | undefined =>
+  bridge().report(code, details)
+
+/**
+ * report() for code that is NOT running inside a core hook (timers, wrapped
+ * methods): never throws synchronously; an 'error'-mode DiagnosticError is
+ * rethrown asynchronously, like the core does for hooks.
+ */
+export const reportSafely = (code: string, details: DiagnosticDetails): Diagnostic | undefined => {
+  try {
+    return report(code, details)
+  } catch (err) {
+    const raise = () => { throw err }
+    typeof queueMicrotask === 'function' ? queueMicrotask(raise) : setTimeout(raise)
+    return undefined
+  }
+}
+
+/** Tunables (test seam: configureChecks()). */
+export const timing = {
+  /** delay after a render before DOM checks run (lets nested renders patch) */
+  settleMs: 50,
+  /** SYG103 escalates to warn after this much render-idle time ... */
+  idleMs: 2000,
+  /** ... and only once the component has rendered at least this often */
+  minRenders: 3,
+}
+
+/** Built-in actions Sygnal dispatches itself; never "missing" or "unreachable". */
+export const BUILTIN_ACTIONS = new Set(['BOOTSTRAP', 'INITIALIZE', 'HYDRATE', 'DISPOSE', 'READY'])
+
+/** Synthetic/internal actions (`__TEST_ACTION__`, `__NOOP_ACTION__`, ...) and built-ins. */
+export const isInternalAction = (action: string): boolean =>
+  typeof action !== 'string' || action.startsWith('__') || BUILTIN_ACTIONS.has(action)
+
+let seen = new Set<string>()
+
+/** true the first time `key` is seen (dedupes reports, e.g. per component name). */
+export const once = (key: string): boolean => (seen.has(key) ? false : (seen.add(key), true))
+
+/**
+ * Forget only the once() dedupe set (G-051: renderComponent calls it through the core bridge
+ * when an outermost instance starts, so findings are reported again in every test). Unlike
+ * resetCheckState() it keeps the checks' registries, e.g. inspect()'s live records.
+ */
+export const resetOnce = (): void => { seen = new Set() }
+{
+  const core = bridge()
+  if (core) core.resetOnce = resetOnce
+}
+
+const resetters: Array<() => void> = []
+export const onReset = (fn: () => void): void => { resetters.push(fn) }
+
+/** Clear every check's dedupe/registry state (tests). */
+export function resetCheckState(): void {
+  seen = new Set()
+  resetters.forEach(fn => fn())
+}
+
+export const nameOf = (component: any): string => (component && component.name) || 'component'
+
+export const isPlainObject = (value: any): boolean =>
+  !!value && typeof value === 'object' && !Array.isArray(value) &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)
+
+/** Levenshtein distance (small strings only). */
+function distance(a: string, b: string): number {
+  const row = Array.from({length: b.length + 1}, (_, i) => i)
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0]
+    row[0] = i
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j]
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+      prev = tmp
+    }
+  }
+  return row[b.length]
+}
+
+/** Closest candidate to `name` (case-insensitive match or edit distance <= 2), if any. */
+export function suggest(name: string, candidates: Iterable<string>): string | undefined {
+  let best: string | undefined
+  let bestScore = Infinity
+  for (const c of candidates) {
+    if (c === name) continue
+    const score = c.toLowerCase() === name.toLowerCase() ? 0 : distance(c, name)
+    if (score < bestScore) { best = c; bestScore = score }
+  }
+  return bestScore <= Math.min(2, Math.floor(name.length / 3)) ? best : undefined
+}
+
+export const didYouMean = (name: string, candidates: Iterable<string>): string => {
+  const s = suggest(name, candidates)
+  return s ? ` (did you mean '${s}'?)` : ''
+}

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

@@ -0,0 +1,55 @@
+/**
+ * SYG201 — STATE reducer dropped keys that existed in the previous state (warn)
+ * SYG202 — STATE reducer returned undefined (warn)
+ *
+ * Mechanism: onReducer(component, action, prevState, nextState). Reported once
+ * per action per component name. Not reported for:
+ *   - synthetic actions (`__*`) and INITIALIZE/HYDRATE (whole-state replacement)
+ *   - keys that are calculated fields (they are re-derived after the reducer)
+ *   - keys whose previous value was undefined
+ * The set()/toggle() helpers always spread the previous state, so they can't
+ * drop keys and never trigger SYG201.
+ */
+import type {DiagnosticCheck} from '../index'
+import {report, once, nameOf, isPlainObject} from './shared'
+
+const SKIP = new Set(['INITIALIZE', 'HYDRATE'])
+
+export const stateCheck: DiagnosticCheck = {
+  id: 'state',
+
+  onReducer(component, action, prevState, nextState) {
+    if (typeof action !== 'string' || action.startsWith('__') || SKIP.has(action)) return
+    const name = nameOf(component)
+
+    if (nextState === undefined) {
+      if (!once(`SYG202:${name}:${action}`)) return
+      // Returning undefined from a Collection item's reducer is the documented way to remove
+      // the item, so only the root (where it wipes the whole app state) is a warning.
+      const sub = !!component?.isSubComponent
+      report('SYG202', {
+        component,
+        severity: sub ? 'info' : 'warn',
+        message: `The STATE reducer for '${action}' returned undefined` +
+          (sub ? ' (this removes the item if the component is a Collection item)' : ''),
+        fix: `Return the new state, e.g. (state, data) => ({ ...state, ... }), or return ABORT to leave the state unchanged`,
+        data: {action},
+      })
+      return
+    }
+
+    if (!isPlainObject(prevState) || !isPlainObject(nextState)) return
+    const calculated: Set<string> | null = component?._calculatedFieldNames || null
+    const dropped = Object.keys(prevState).filter(key =>
+      !(key in nextState) && prevState[key] !== undefined && !(calculated && calculated.has(key)))
+    if (dropped.length === 0 || !once(`SYG201:${name}:${action}`)) return
+
+    const list = dropped.map(k => `'${k}'`).join(', ')
+    report('SYG201', {
+      component,
+      message: `The STATE reducer for '${action}' returned a state without ${list}, which ${dropped.length === 1 ? 'was' : 'were'} in the previous state (likely a missing ...state spread)`,
+      fix: `Spread the previous state: (state, data) => ({ ...state, ... }). If removing ${dropped.length === 1 ? 'the key' : 'these keys'} is intended, ignore this`,
+      data: {action, droppedKeys: dropped},
+    })
+  },
+}

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

@@ -0,0 +1,112 @@
+/**
+ * Strict mode: canonical-form checks (PLAN-1 workstream 2A,
+ * dev-plans/PLAN-1-canonical-forms.md). Runtime half; sygnal-check --strict
+ * implements every rule statically.
+ *
+ * Off by default. Turn it on with any of:
+ *   - configureStrict(true)                    (this entry)
+ *   - renderComponent(C, { strict: true })     (tests)
+ *   - globalThis.__SYGNAL_STRICT__ = true      (e.g. injected by a dev tool)
+ * and diagnostics must be on (strict reports go through the same core).
+ * The flag lives on the core bridge object, so it is shared by every copy of
+ * this entry and by renderComponent.
+ *
+ * | Code   | Rule (canonical form)                    | Runtime mechanism                       |
+ * |--------|------------------------------------------|-----------------------------------------|
+ * | SYG501 | C1 destructure the view's first argument | onModel: component.view.length > 1      |
+ * | SYG502 | C3 return ABORT for "no change"          | onReducer: returned the previous state  |
+ * |        |                                          | object (undefined stays SYG202)         |
+ * | SYG504 | C5 object form, no 'ACTION | SINK' keys  | onModel: raw model keys containing '|'  |
+ * | SYG503, SYG505, SYG506, SYG507: static only (sygnal-check --strict); the
+ *   runtime can't tell emit() from { EVENTS }, a side effect from a pure
+ *   reducer, or see CHILD.select() arguments without a core hook.
+ *
+ * Every finding is reported once per component name (+ action / key).
+ * The SYG5xx severities are registered here (registerCodes) and passed
+ * explicitly, so the main bundle doesn't carry them (D29).
+ */
+import type {DiagnosticCheck} from '../index'
+import {CODE_TITLES, STRICT_CODE_SEVERITY, registerCodes} from '../codes'
+import type {DiagnosticSeverity} from '../codes'
+import {bridge, report, once, nameOf, isInternalAction} from './shared'
+
+registerCodes(Object.keys(STRICT_CODE_SEVERITY).map(code =>
+  [code, STRICT_CODE_SEVERITY[code], CODE_TITLES[code]] as [string, DiagnosticSeverity, string]))
+
+/**
+ * Turn runtime strict checks on (true), off (false), or back to the default
+ * (undefined → globalThis.__SYGNAL_STRICT__ === true).
+ */
+export function configureStrict(on?: boolean): void {
+  const core = bridge()
+  if (core) core.strict = on
+}
+
+/** Whether runtime strict checks are on. */
+export function isStrictEnabled(): boolean {
+  const flag = bridge()?.strict
+  return flag === undefined ? (globalThis as any).__SYGNAL_STRICT__ === true : flag === true
+}
+
+const strictReport = (code: string, details: Parameters<typeof report>[1]) =>
+  report(code, {severity: STRICT_CODE_SEVERITY[code], ...details})
+
+export const strictCheck: DiagnosticCheck = {
+  id: 'strict',
+
+  onModel(component) {
+    if (!isStrictEnabled() || !component) return
+    const name = nameOf(component)
+
+    // SYG501 — view(props, state, context, peers): positional use of the 2nd+ args.
+    // (A default value or a rest parameter stops Function.length, so this can
+    // miss `(props, state = {})`, but it never flags a single-argument view.)
+    const view = component.view
+    if (typeof view === 'function' && view.length > 1 && !view.__sygnalLazy && once(`SYG501:${name}`)) {
+      const extra = ['state', 'context', 'peers'].slice(0, view.length - 1)
+      strictReport('SYG501', {
+        component,
+        message: `The view takes ${view.length} positional arguments (props, ${extra.join(', ')})`,
+        fix: `Destructure the first argument instead: function ${name}({ ${extra.join(', ')}, ...props })`,
+        data: {arity: view.length},
+      })
+    }
+
+    // SYG504 — 'ACTION | SINK' shorthand keys
+    const model = component.model
+    if (!model || typeof model !== 'object') return
+    for (const key of Object.keys(model)) {
+      if (!key.includes('|')) continue
+      const [action, sink] = key.split('|').map(s => s.trim())
+      if (!action || !sink || !once(`SYG504:${name}:${key}`)) continue
+      const rewrite = sink === 'EVENTS'
+        ? `${action}: { EVENTS: event('TYPE', (state, data) => payload) }`
+        : `${action}: { ${sink}: (state, data, next) => ... }`
+      strictReport('SYG504', {
+        component,
+        message: `Model key '${key}' uses the 'ACTION | SINK' shorthand`,
+        fix: `Use the object form: ${rewrite} (merge it into an existing '${action}' entry if there is one)`,
+        data: {key, action, sink},
+      })
+    }
+  },
+
+  onReducer(component, action, prevState, nextState) {
+    if (!isStrictEnabled() || isInternalAction(action)) return  // incl. INITIALIZE/HYDRATE/DISPOSE
+    // undefined is SYG202 (state check, every mode); only the identical object here.
+    if (!prevState || typeof prevState !== 'object' || nextState === undefined) return
+    let same = nextState === prevState
+    if (!same && typeof component?.addCalculated === 'function') {
+      // with calculated fields the reducer saw addCalculated(prev) (memoized: same object)
+      try { same = component.addCalculated(prevState) === nextState } catch (_) {}
+    }
+    const name = nameOf(component)
+    if (!same || !once(`SYG502:${name}:${action}`)) return
+    strictReport('SYG502', {
+      component,
+      message: `The STATE reducer for '${action}' returned the unchanged state object`,
+      fix: `Return ABORT for "no change": ${action}: (state, data) => cond ? { ...state, ... } : ABORT`,
+      data: {action},
+    })
+  },
+}

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

@@ -0,0 +1,65 @@
+/**
+ * SYG101 — intent action has no model entry (warn)
+ * SYG102 — model entry has no intent trigger (info; it may still be reached
+ *          with next(), which is only known at call time)
+ *
+ * Mechanism: onIntent records the intent's action names per component;
+ * onModel (always called right after, once per instance) compares them with
+ * the normalized model map (shorthand already expanded by the core).
+ * Synthetic actions (`__*`, e.g. renderComponent's `__TEST_ACTION__`) and the
+ * built-ins BOOTSTRAP/INITIALIZE/HYDRATE/DISPOSE/READY are never reported.
+ * Under renderComponent, intent streams injected for model actions (so that
+ * simulateAction can dispatch them by their real names) are listed on the
+ * intent object's non-enumerable `__sygnalTestActions` property. They are not
+ * user intent actions (never reported as SYG101), and SYG102 is not reported
+ * for those model actions (the test dispatches them with simulateAction).
+ */
+import type {DiagnosticCheck} from '../index'
+import {report, once, isInternalAction, nameOf, didYouMean} from './shared'
+
+const intentActions = new WeakMap<object, string[]>()
+
+export const wiringCheck: DiagnosticCheck = {
+  id: 'wiring',
+
+  onIntent(component, actionNames) {
+    intentActions.set(component, actionNames || [])
+  },
+
+  onModel(component, modelMap) {
+    const name = nameOf(component)
+    const intent$ = component && component.intent$
+    const injected = new Set<string>(
+      (intent$ && typeof intent$ === 'object' && intent$.__sygnalTestActions) || [])
+    const actions = (intentActions.get(component) || []).filter(a => !injected.has(a))
+    intentActions.delete(component)
+    const modelActions = Object.keys(modelMap || {})
+
+    for (const action of actions) {
+      if (isInternalAction(action) || modelActions.includes(action)) continue
+      if (!once(`SYG101:${name}:${action}`)) continue
+      report('SYG101', {
+        component,
+        message: `Intent action '${action}' has no model entry, so it never does anything${didYouMean(action, modelActions)}`,
+        fix: `Add '${action}' to ${name}.model, or remove it from ${name}.intent`,
+        data: {action, modelActions},
+      })
+    }
+
+    // A single-stream intent (intent returns one action$ stream) has no
+    // action names to compare against.
+    if (intent$ && typeof intent$.addListener === 'function') return
+
+    const hmr = ([] as string[]).concat(component?.hmrActions || [])
+    for (const action of modelActions) {
+      if (isInternalAction(action) || actions.includes(action) || hmr.includes(action) || injected.has(action)) continue
+      if (!once(`SYG102:${name}:${action}`)) continue
+      report('SYG102', {
+        component,
+        message: `Model entry '${action}' has no intent action with that name${didYouMean(action, actions)}`,
+        fix: `Add '${action}' to ${name}.intent, or remove the model entry. If it is only dispatched with next('${action}'), ignore this`,
+        data: {action, intentActions: actions},
+      })
+    }
+  },
+}

package/src/extra/diagnostics/codes.ts

@@ -0,0 +1,232 @@
+/**
+ * Sygnal diagnostic code registry.
+ *
+ * Every diagnostic Sygnal reports has a stable code (`SYG123`), a default
+ * severity, a short title, and a docs anchor (`docsSlug`) on
+ * https://sygnal.js.org/reference/errors (base URL = the `site` field of
+ * docs/astro.config.mjs).
+ *
+ * The registry is stored as two parallel tables so the published bundle only
+ * carries what the runtime needs:
+ *   - CODE_SEVERITY: code → default severity (used by report(); in the bundle)
+ *   - CODE_TITLES:   code → title (docs/inspect/static-checker metadata; pure
+ *                    object literal, tree-shaken unless something imports it)
+ * getCodeInfo(code) / listCodes() assemble the full
+ * { code, severity, title, docsSlug } records. To add a code, add it to BOTH
+ * tables below (inside your reserved range), or call registerCodes() from a
+ * workstream's own module. docsSlug is always the lower-cased code
+ * ('SYG101' → https://sygnal.js.org/reference/errors#syg101).
+ *
+ * (Comments are attached to type-only declarations so the TypeScript emit
+ * drops them — keeps them out of the published bundle and the size gate.)
+ *
+ * Severity:
+ *   - 'error' — throws (or is rethrown, enriched) at the call site
+ *   - 'warn'  — console + collected (when diagnostics mode is 'warn')
+ *   - 'info'  — collected only; surfaced through inspect / test helpers
+ *
+ * Ranges (see dev-plans/PLAN-1.md §2):
+ *   SYG1xx  Wiring: intent <-> model <-> view <-> events
+ *   SYG2xx  State & reducers
+ *   SYG3xx  Streams & intent construction (incl. xstream hints)
+ *   SYG4xx  Collections, Switchable, sub-components, context
+ *   SYG5xx  Strict mode / canonical-form violations
+ *   SYG6xx  Drivers & run configuration
+ *   SYG9xx  Internal invariants
+ *
+ * ---------------------------------------------------------------------------
+ * RESERVED RANGES (PLAN-1 workstream allocation — add entries only inside the
+ * range your workstream owns; changes outside go through the coordinator):
+ *
+ *   0B (diagnostics core)    SYG900                (check-failure invariant)
+ *   1A (runtime checks)      SYG101-105, SYG110, SYG201, SYG202, SYG301,
+ *                            SYG401 (pre-seeded below), plus SYG106-199
+ *                            and SYG302-399 for new checks
+ *   1E (message retrofit)    SYG206-299, SYG402-499, SYG601-699, SYG901-999
+ *   2A (strict mode)         SYG500-599
+ *   unallocated              SYG100, SYG200, SYG203-205, SYG300, SYG400,
+ *                            SYG600 (coordinator assigns on request)
+ * ---------------------------------------------------------------------------
+ */
+export type DiagnosticSeverity = 'error' | 'warn' | 'info'
+
+export interface DiagnosticCodeInfo {
+  code: string
+  severity: DiagnosticSeverity
+  title: string
+  // anchor on the errors reference page, e.g. 'syg101' → /reference/errors#syg101
+  docsSlug: string
+}
+
+export const DOCS_BASE_URL = 'https://sygnal.js.org'
+
+export const CODE_SEVERITY: Record<string, DiagnosticSeverity> = {
+  SYG101: 'warn',
+  SYG102: 'info',
+  SYG103: 'info',
+  SYG104: 'warn',
+  SYG105: 'info',
+  SYG106: 'warn',
+  SYG110: 'warn',
+  SYG111: 'warn',
+  SYG201: 'warn',
+  SYG202: 'warn',
+  SYG301: 'error',
+  SYG401: 'warn',
+  SYG900: 'warn',
+  // ---- 1E retrofit codes (SYG206-299, 402-499, 601-699, 901-999) ----
+  SYG206: 'error',
+  SYG207: 'warn',
+  SYG208: 'warn',
+  SYG209: 'error',
+  SYG210: 'warn',
+  SYG211: 'error',
+  SYG212: 'error',
+  SYG213: 'warn',
+  SYG214: 'error',
+  SYG215: 'error',
+  SYG216: 'error',
+  SYG217: 'warn',
+  SYG218: 'error',
+  SYG219: 'warn',
+  SYG220: 'warn',
+  SYG402: 'error',
+  SYG403: 'error',
+  SYG404: 'error',
+  SYG405: 'warn',
+  SYG406: 'error',
+  SYG407: 'error',
+  SYG408: 'error',
+  SYG409: 'warn',
+  SYG410: 'error',
+  SYG411: 'error',
+  SYG412: 'error',
+  SYG413: 'error',
+  SYG414: 'error',
+  SYG415: 'error',
+  SYG416: 'error',
+  SYG417: 'warn',
+  SYG418: 'error',
+  SYG419: 'error',
+  SYG420: 'error',
+  SYG601: 'error',
+  SYG602: 'error',
+  SYG603: 'error',
+  SYG604: 'error',
+  SYG605: 'error',
+  SYG606: 'error',
+  SYG607: 'error',
+  SYG901: 'error',
+  SYG902: 'error',
+  SYG903: 'error',
+  // ---- end 1E retrofit codes ----
+}
+
+export const CODE_TITLES: Record<string, string> = {
+  // SYG1xx wiring (1A)
+  SYG101: 'Intent action has no model entry',
+  SYG102: 'Model entry is unreachable',
+  SYG103: 'Intent selector matched no rendered element',
+  SYG104: 'Intent selector crosses an isolation boundary',
+  SYG105: 'EVENTS type selected but never emitted, or emitted but never selected',
+  SYG106: 'Parent prop is overwritten by a reserved view argument',
+  SYG110: 'Intent selector not present in the component view',
+  SYG111: 'Controlled input has no input listener',
+  // SYG2xx state & reducers (1A)
+  SYG201: 'STATE reducer dropped keys from the previous state',
+  SYG202: 'STATE reducer returned undefined',
+  // SYG3xx streams & intent construction (1A)
+  SYG301: 'RxJS operator used on an xstream stream',
+  // SYG4xx collections / switchable / sub-components / context (1A)
+  SYG401: "Collection 'from' field is missing or not an array",
+  // SYG5xx strict mode / canonical forms (2A; dev-plans/PLAN-1-canonical-forms.md)
+  SYG501: 'View uses positional arguments',
+  SYG502: 'STATE reducer signals no change without ABORT',
+  SYG503: 'Side effect in a STATE reducer that returns ABORT',
+  SYG504: "'ACTION | SINK' shorthand model key",
+  SYG505: 'Non-canonical EVENTS emit',
+  SYG506: 'CHILD.select() with a string component name',
+  SYG507: 'Prop drilled through more than 2 component levels',
+  // SYG9xx internal (0B)
+  SYG900: 'A diagnostics check threw',
+  // ---- 1E retrofit codes (SYG206-299, 402-499, 601-699, 901-999) ----
+  SYG206: 'Invalid calculated field definition',
+  SYG207: 'Calculated field shadows an initialState key',
+  SYG208: 'Calculated field depends on an unknown key',
+  SYG209: 'Circular calculated field dependency',
+  SYG210: 'INITIALIZE used with a sink other than STATE',
+  SYG211: 'Invalid model shorthand entry',
+  SYG212: 'Model entry is not a function or an object of sinks',
+  SYG213: 'Duplicate model entry for the same action and sink',
+  SYG214: 'EFFECT handler threw',
+  SYG215: 'next() delay is not a number',
+  SYG216: 'Reducer threw',
+  SYG217: 'Driver-sink reducer returned undefined',
+  SYG218: 'Reducer returned an unsupported type',
+  SYG219: 'EFFECT handler returned a value',
+  SYG220: 'Calculated field threw',
+  SYG402: 'Context is not an object',
+  SYG403: 'Invalid context entry',
+  SYG404: 'Context stream errored',
+  SYG405: 'Sub-component has initialState without isolatedState',
+  SYG406: 'View threw',
+  SYG407: 'onError handler threw',
+  SYG408: 'Sub-component failed to instantiate',
+  SYG409: 'Child tried to update a calculated field',
+  SYG410: "Invalid sub-component 'state' prop",
+  SYG411: "Collection 'of' is missing or not a component",
+  SYG412: "Invalid Collection 'from' prop",
+  SYG413: 'Unnamed component factory not found',
+  SYG414: 'Component not found',
+  SYG415: "Switchable 'of' is missing or invalid",
+  SYG416: "Switchable 'current' is missing or invalid",
+  SYG417: 'Portal target not found',
+  SYG418: 'Invalid Collection sort prop',
+  SYG419: "Invalid switchable() 'name$' parameter",
+  SYG420: 'JSX tag is undefined',
+  SYG601: 'Missing or invalid sources',
+  SYG602: 'Intent is not a function',
+  SYG603: 'Intent returned an invalid value',
+  SYG604: 'Invalid hmrActions',
+  SYG605: "Intent action name contains '|'",
+  SYG606: 'calculated is not an object',
+  SYG607: 'State source not found',
+  SYG901: 'Sub-component sink stream errored',
+  SYG902: 'EFFECT stream errored',
+  SYG903: 'Component factory returned invalid sinks',
+  // ---- end 1E retrofit codes ----
+}
+
+// 2A: strict-mode (SYG5xx) default severities. Kept OUT of CODE_SEVERITY so the
+// main bundle doesn't carry them (D29: zero bytes); the 'sygnal/diagnostics'
+// entry registers them (registerCodes) and its reports pass the severity
+// explicitly. sygnal-check keeps the same table in sygnal-check/src/codes.js.
+export const STRICT_CODE_SEVERITY: Record<string, DiagnosticSeverity> = {
+  SYG501: 'warn',
+  SYG502: 'warn',
+  SYG503: 'warn',
+  SYG504: 'warn',
+  SYG505: 'warn',
+  SYG506: 'warn',
+  SYG507: 'info',
+}
+
+export function getCodeInfo(code: string): DiagnosticCodeInfo | undefined {
+  const severity = CODE_SEVERITY[code]
+  return severity && { code, severity, title: CODE_TITLES[code] || '', docsSlug: code.toLowerCase() }
+}
+
+export function listCodes(): DiagnosticCodeInfo[] {
+  return Object.keys(CODE_SEVERITY).map(c => getCodeInfo(c)!)
+}
+
+export function registerCodes(entries: Array<[string, DiagnosticSeverity, string]>): void {
+  for (const [code, severity, title] of entries) {
+    CODE_SEVERITY[code] = severity
+    CODE_TITLES[code] = title
+  }
+}
+
+export function docsUrlFor(code: string): string {
+  return `${DOCS_BASE_URL}/reference/errors#${code.toLowerCase()}`
+}