Ramonda

Diagnostics

Ramonda reports the common mistakes below at runtime, in development only. Every message is wrapped in if (__DEV__), so a production build ships none of them. Nearly every check is stripped with its message; the exception is named where it applies (RML009), because a guard that ran only in development would protect the one build that was never exposed to a request.

Every code has a page of its own, at /reference/diagnostics/ and the code in lower case — and npx ramonda-check explain RMD020 prints the same page for the version you have installed, with no network.

Arrived with a symptom rather than a code? Something is wrong lists what you can see and sends each one here.

They exist because these mistakes are silent. Almost every bug this framework has had produced a wrong result rather than an error: state landing on the wrong row, a click doing nothing, a subtree rendering into nodes nobody can see. None of them threw. A diagnostic is the framework saying the thing a stack trace never would.

Most are deduplicated by cause, so a mistake in a list of a thousand rows is reported once. Whether to dedupe is the reporting package's call, and it follows from what the fault depends on: a core diagnostic fires from the render path for a fixed piece of code, so the second report carries nothing new, while an RML miss depends on the data — the same line can miss for one record and land for the next, and collapsing those would hide the case that matters.

Error or warning says what is at stake, not how bad the code looks. An error means the end result is wrong — something renders the wrong thing, loses state, never becomes interactive, or hands you a value that is not what you asked for; the devtools panel raises its alert for these. A warning means the result is the same and the app just did more work to get there: a wasted render, a refetch, a listener re-attached.

The prefix says which package reported it: RMD is @ramonda/core, RMQ is @ramonda/query, RMF is @ramonda/form, RML is @ramonda/lens. They are listed apart below, because a reader who hits RMQ001 wants the query codes together and not one of them wedged between two core ones.

A code is stable forever and never reused. When a check is removed, its section stays and says retired — a reader who hits an old message in an old build still lands somewhere.


Capturing them

A diagnostic is also a record, so a devtools panel, a test, or a log collector can group and filter reports instead of parsing prose. A collector installs one function, and a reporting package finds it with no dependency on anything:

Every prefix arrives this way — RMD, RML, RMQ and RMF.

interface RamondaDiagnostic {
  /** Stable forever. The prefix says which package raised it. */
  code: string;
  /** Who emitted it — `"ramonda/lens"`. OpenTelemetry calls this `InstrumentationScope.name`. */
  scope: string;
  /** Mapping to OpenTelemetry SeverityNumber 5 · 9 · 13 · 17. */
  severity: "debug" | "info" | "warn" | "error";
  /** One sentence, human first. Interpolated values are fine — grouping is by `code`. */
  message: string;
  /** What to do instead. Always present for an `error`. */
  fix?: string;
  /** The values the message interpolated, structured. What a collector queries. */
  data?: Record<string, unknown>;
  /** Epoch millis. Sortable, comparable, locale-free. */
  time: number;
  /** Identifies the SOURCE of a fault. Absent means "never deduplicate this". */
  dedupKey?: string;
  /** The fault was also thrown where it happened, so whoever ran the code already met it. */
  thrown?: true;
}

declare global {
  var __RAMONDA_DIAGNOSTICS__: ((record: RamondaDiagnostic) => void) | undefined;
}

globalThis.__RAMONDA_DIAGNOSTICS__ = (record) => {
  if (record.severity === "error") myCollector.alert(record);
};

If you have @ramonda/devtools, subscribe instead of assigning. The sink is one function, so an assignment replaces whoever was there — which is normally the panel's own bridge, and it then quietly stops filling. installDiagnostics shares one sink between any number of subscribers and hands back the uninstall:

import { installDiagnostics } from "@ramonda/devtools";

const stop = installDiagnostics((record) => myCollector.alert(record));

A subscriber sees every prefix. The panel's LOGS tab is the one place that differs: RMD rows reach it through core's own log channel, so the bridge does not carry them there a second time.

The assignment above is the protocol-level form, for a package that will not take a dependency to report a warning. Write it when that is the situation, and chain what was already there:

const previous = globalThis.__RAMONDA_DIAGNOSTICS__;
globalThis.__RAMONDA_DIAGNOSTICS__ = (record) => {
  previous?.(record);
  myCollector.alert(record);
};

Four rules make it work across packages that share no code:

  • globalThis, not an event on window. The same line runs in the browser, in Node, in a worker and during a server render. A reporting package needs no dependency and no DOM.
  • A collector is optional. With nothing installed, the call is one property read and the message still goes to the console. Installing a sink adds a consumer; it does not silence the console.
  • Read tolerantly. Ignore fields you do not know, and assume only code, scope, severity, message and time. That is what lets the record grow without a version on every one of them.
  • data holds values, not live objects. A collector keeps a bounded history, and a record holding a component or a DOM node would keep it alive for as long as that history does.

The field names line up with OpenTelemetry's log data model, so bridging to a collector is a rename rather than a redesign. Anything can emit into this channel — the contract is the shape above and the name of the sink, not a package to depend on.

On the server the sink is process-wide, so a collector sees every concurrent request at once; there is no per-request attribution in the record.


Core — RMD

  • RMD001 — State written during render()
  • RMD002 — Duplicate key in a child list
  • RMD003 — Context consumed without a provider above it
  • RMD004 — Props mutated by the receiving component
  • RMD005 — Array in state mutated in place
  • RMD006 — Timer still running after unmount
  • RMD007 — Server and client rendered different output
  • RMD008 — State changed after the component was unmounted
  • RMD009 — Update loop: a component never stopped re-rendering
  • RMD011 — A function was used as a JSX tag
  • RMD012 — retired
  • RMD013 — A list item produced nothing
  • RMD014 — retired
  • RMD015 — A hook's props assigned by the hook that received them
  • RMD016 — A component updated while its element is not in the document
  • RMD017 — A deferred hydration never resumed
  • RMD018 — State written during a @compute
  • RMD019 — State set to a value that cannot be serialized
  • RMD020 — render() produced a different value the second time
  • RMD021 — A random number was read while a value was being derived
  • RMD022 — A hook's props callback built a new value for the same contents
  • RMD023 — Children built from an array need a key
  • RMD024 — A @compute recomputes without its answer changing
  • RMD025 — Per-request data read in the browser
  • RMD027 — A props callback reads a value that is not reactive
  • RMD028 — An element the HTML parser is not allowed to keep here
  • RMD029 — A boolean attribute given the string "false"
  • RMD030 — State written during [INSPECT]()
  • RMD031 — A list item that is not an element
  • RMD032 — More than one @catchError on a component
  • RMD026 — retired
  • RMD033 — State that cannot cross to the client
  • RMD034 — State written during create or mount is not carried to the client
  • RMD035 — The client's hook tree does not match the server's
  • RMD036 — The state blob could not be read
  • RMD037 — An object among JSX children that is not markup
  • RMD038 — A @watchProp selector threw
  • RMD039 — class where className was meant
  • RMD040 — More than one @ShouldUpdateOnPropsChange on one class
  • RMD043 — A <meta> with nothing to identify it
  • RMD044 — An unknown element type in JSX
  • RMD046 — More than one @StableProps on one class
  • RMD047 — A @memoized member was given an argument it cannot key on
  • RMD048 — Object in state changed in place
  • RMD049 — Two lazy functions with the same source
  • RMD050 — A decorator whose effect this member already has

Forms — RMF

  • RMF001 — a field was assigned to
  • RMF002 — the list members were used on a field that is not a list
  • RMF003 — onSubmit threw
  • RMF004 — the schema's validation rejected
  • RMF005 — a field edited through a control that hands back another kind

Query — RMQ

  • RMQ001 — a query key that cannot be hashed
  • RMQ002 — a query failed and nothing rendered it

Immutable updates — RML

  • RML001 — a path that could not be reached
  • RML002 — a path into a Map, Set or Date
  • RML003 — an array hop on something that is not an array
  • RML004 — an index outside the array
  • RML005 — a predicate that matched nothing
  • RML006 — an operation that needs a different kind of value
  • RML007 — nothing to remove
  • RML008 — a fork branch that returned nothing
  • RML009 — a key a write is refused for
  • RML010 — a chain written through twice
  • RML011 — remove() at the root
  • RMD051 — A list row cannot be told apart from its siblings
  • RMD052 — A component among JSX children, where an element was meant
  • RMD053 — The request was read with no request scope installed
  • RMD054 — A post-commit callback threw, and the failure was swallowed
  • RMD055 — A hook's props passed as a plain object
  • RMD056 — One context provided twice by the same component
  • RMD057 — A context consumed above the provider on the same component
  • RMD058 — The request blob could not be read
  • RMD059 — An async lifecycle rejected
  • RMD060 — render() is async
  • RMD061 — A ref was built while a value was being derived
  • RMD062 — A field read its model while a commit ran

Next

  • Checking your app — the same faults proved from your source, before any of these can be reported.
  • Rules — every check that runs there, one page each.
  • Reference — the other pages you come back to rather than read once.