Skip to content
DocsconceptsDocumentation

Advisors

Splinter-style lints that catch schema, performance, and security problems — many before you deploy.

Last updated:

Advisors are lints over your schema and functions, modelled on Supabase's splinter. Each lint is a pure function that emits zero or more findings, each tagged with a level (ERROR/WARN/INFO), a category (SCHEMA/PERFORMANCE/SECURITY), and a remediation.

Unlike an advisor that only inspects a live database, most Lunora lints are static: they run at codegen/build time against the declared schema and the discovered query/insert/middleware sites, so they catch a problem before it ships. A smaller set is runtime: it needs observed signal from a running shard (full-scan attribution, index hit counts, per-shard traffic, row samples).

Findings surface in the Studio's Advisors domain (Security, row-level security (RLS), and Insights panels) and on the Home overview. Static findings ride along in the generated code; runtime findings are computed by Studio from the signal each shard reports.

Static lints

Run against the declared schema alone: deterministic, no running shard needed.

Correctness

The last five come from codegen rather than @lunora/advisor, so they are not in the programmatic ALL_LINTS catalog below — they travel the same channel to the terminal and the studio.

LintLevelDetects
index_references_unknown_fielderrorAn index references a column that doesn't exist on the table.
relation_references_unknown_tableerrorA relation targets a table that doesn't exist.
relation_references_unknown_fielderrorA relation's key column doesn't exist: the join can never resolve.
through_relation_missing_unique_indexerrorA many-to-many join table has no unique index over its two keys: a repeated connect stores the link twice.
workflow_unknown_targeterrorctx.workflows.get("name") names a workflow that isn't declared.
empty_indexwarnAn index declared with no columns: it narrows nothing.
circular_fkwarnA cycle of one relations (A → B → C → A): cascade/restrict hazards.
cross_module_table_writewarnA function writes to a table another module owns (defineModule({ tables })), coupling the two modules.
nondeterministic_query_mutationwarnA query/mutation calls Date.now/Math.random/fetch: non-deterministic reads break caching and replay. Use ctx.now for time and ctx.random() for randomness in a mutation; move network calls into an action.
procedure_not_registeredwarnAn export whose resolved TYPE is a registration — procedure, hook, reactor, mutator, shape, migration, workflow, queue, agent or container — never reached the generated output: produced by a factory or an alias, or (for the single-module kinds) sitting outside lunora/<kind>.ts.
procedure_type_check_unavailablewarnTypes don't resolve for lunora/ where codegen runs, so procedure_not_registered cannot report anything.
procedure_arguments_unreadablewarnA registered procedure's .input() record could not be read, so api.ts types fewer arguments than the runtime enforces.
procedure_return_type_erasedwarnA registered procedure's return type could neither be named nor reproduced in _generated/, so api.ts types it unknown while the runtime still returns the shape.
queue_alias_conflictwarnA wrangler.jsonc queues.producers[] entry maps a queue's binding to another queue's declared name, or two scopes alias one name to different queues; the batch goes to a handler other than the one wrangler.jsonc implies.

Performance

LintLevelDetects
unindexed_foreign_keyinfoA foreign-key column with no index leading with it: reads on it full-scan. (Honours SQLite's leftmost-prefix rule; exempts FKs onto _id.)
filter_without_indexwarnA query(...).filter(...) with no .withIndex() first: loads every row and filters in memory.
count_without_indexwarnA count() on a table with no aggregate index whose where no ordinary index covers (a bare count included): every call scans every row of the table to count them.
duplicate_indexinfoAn index whose columns are a leading prefix of another: pure write/storage overhead. (Unique indexes exempt.)
unbounded_looperrorA while (true) / for (;;) with no break, return or throw: it never ends, billing every turn.
dispatch_cycleerrorFunctions schedule or call each other (or themselves) with no guard on any hop: an endless chain.
queue_dispatch_cycleerrorA queue consumer, or a function it runs, re-enqueues to its own queue (or through a topic) on every message, with no guard on any hop: the queue never drains.
self_reschedule_without_progresswarnA guarded runAfter re-arms the same function under one second, with no cursor and no row removed: the same work every run. From one second to a minute it is an info-level poll, and a rewrite of a row on each tick does not count as progress.
unbounded_collect_on_open_rangewarnA server-driven .collect() on a withIndex range with no upper bound, and nothing in the function removes the rows it reads.
filter_after_index_scaninfoA .filter() after .withIndex() on a field the index does not cover: extend the index so the read seeks instead of scanning.
cron_every_minuteinfoA cron job that fires every minute: a Worker invocation and target dispatch billed on every fire, whether or not there is work.

Security

LintLevelDetects
hardcoded_secreterrorA secret-shaped literal (sk_live…, AKIA…, a PEM header, a high-entropy token: a 40+ character mixed-case base64 run, or a 32+ character hex run) checked into lunora/ source. Rotate it and move it to a binding/secret.
sql_injection_riskerrorA ctx.sql.query / .unsafe call builds its SQL text from non-constant values. Pass request input in the params array instead.
rls_uncovered_tablewarnA public procedure reads/writes a table that's RLS-protected elsewhere but has no .use(rls(...)): an authorization bypass.
mask_uncovered_pii_columnwarnA public procedure reads a table whose columns are masked elsewhere but has no .use(mask(...)): PII returned in the clear.
auth_api_call_without_headerswarnA ctx.authApi.<method>(...) call omits headers, so better-auth skips session authorization and runs with full privilege.
public_mutation_without_ratelimitwarnA public mutation/action installs no rateLimit. Abuse-sensitive names (login/signup/reset/magic/subscribe/contact) raise the urgency. Wrap with protectPublic.
user_creating_mutation_without_captchawarnA public procedure writes a user/session/account table (or calls ctx.mail) with no CAPTCHA. Add verifyTurnstile or protectPublic({ captcha }).
public_arg_uses_anywarnA public procedure accepts a v.any() argument: unvalidated input. Give it a concrete validator.
admin_route_without_guardwarnAn httpRoute on an admin/privileged-looking path whose handler references no auth/admin guard.
unbounded_string_arginfoA public v.string() argument with no max-length bound: a storage/DoS abuse vector. Add an enforced bound with .max(n).
container_public_internetinfoA container with enableInternet unset (defaults on): egress billed per GB, wider attack surface.

Operational

LintLevelDetects
table_without_insertinfoNo function inserts into the table: dead schema, or seeded out-of-band.
workflow_unusedinfoA declared workflow is never started: dead code (still billed), or external.
queue_without_dlqwarnA defineQueue with no deadLetterQueue: exhausted messages are dropped, not captured or replayable.
container_oversized_instanceinfoA container on a large instance type: provisioned memory/disk billed while running.
container_long_sleep_afterwarnA container's idle window (sleepAfter, capped by hardTimeout) is over an hour: each idle instance runs, and bills, that long.
topic_too_many_subscriptionsinfoA topic with more than 10 subscriptions: each publish sends to every queue, six at a time.

Runtime lints

Need observed signal from a live shard, computed by Studio.

LintLevelDetects
hot_shardwarnOne shard takes 50% or more of a shardBy(...) function's traffic while siblings idle (fires only with at least 50 total requests).
index_utilizationinfo/warnTwo checks: a dead index with zero recorded reads (info), and a hot unindexed scan, a table full-scanned ≥25× with no index (warn).
fan_out_breadthwarnA shard group with enough active shards that a cross-shard read over it would approach the per-invocation internal-subrequest ceiling.

Nothing samples existing rows against the declared constraints. A unique index declared in the schema is enforced by both backends on the normal write path, but dangling foreign keys, nulls in non-optional columns and duplicates that predate the constraint or arrived through a bulk import are unchecked today rather than clean.

Running advisors

You don't run advisors by hand in normal use; codegen runs the static set on every lunora dev save and on deploy, and the Studio computes the runtime set when you open the Advisors panels. The catalog is also available programmatically:

import { runAdvisor, STATIC_LINTS, RUNTIME_LINTS, ALL_LINTS } from "@lunora/advisor";

const findings = runAdvisor(context, { source: "static" }); // or "runtime"

Each finding carries a stable cacheKey, which dedupes findings across runs. To accept a single finding, put an inline // lunora-advisor-exempt <rule> -- <reason> directive above the code it concerns; the advisor reference explains how it attaches and what it changes.