@lunora/advisor

@lunora/advisor is a set of lints over your Lunora app, modeled on Supabase's splinter. Each lint is a pure rule over a normalized LintContext; runAdvisor() runs a set of them and flattens the results into a single list of findings that the CLI, the Vite plugin, and the Studio Advisors view all render.

You rarely call this package directly. @lunora/codegen runs the static lints during lunora dev and lunora codegen, so a problem shows up in your terminal and in Studio while you work. Most of them run before the code ships, unlike an advisor that can only inspect a live database.

Two evidence tiers

A lint draws its evidence from one of two sources:

• static: runs against the declared defineSchema (tables, indexes, relations) plus the query reads and inserts the codegen feeder discovers in your function bodies. Deterministic and runnable at build time. Most lints are static.
• runtime: reads observed signal from a running deployment (per-shard traffic, table scans, index hits, row samples). Three lints are runtime-only; they need a live worker.

Every finding carries a level (ERROR, WARN, or INFO) and a category of SECURITY, PERFORMANCE, or SCHEMA.

How findings surface

The runtime tier is filled by the Studio backend from each shard's durable counters; it appears in the same Advisors view once a deployment has traffic.

Static lints

Security

Secrets, injection & SSRF:

IDOR & unscoped access (a user-derived key/id reaches a resource without a server-scoped check):

RLS, masking & output shape:

Auth configuration (createAuth):

HTTP handlers, procedures & rate limits:

Storage, AI, containers & payments:

Performance

Schema

Runtime lints

These read observed signal off a live deployment, so they only fire once a worker has traffic.

Run the lints yourself

Adapt your schema with fromServerSchema and pass it to runAdvisor. The source option restricts to one tier: pass "static" to skip the runtime lints, which need a live deployment:

import { fromServerSchema, runAdvisor } from "@lunora/advisor";

import schema from "./lunora/schema";

const findings = runAdvisor({ schema: fromServerSchema(schema) }, { source: "static" });

for (const finding of findings) {
    console.log(`[${finding.level}] ${finding.name}: ${finding.detail}`);
}

runAdvisor(context, options) returns a flat Finding[] in lint-declaration order. Each finding has level, name, title, detail, description, remediation, categories, source, and metadata. Options:

• lints: the set to run. Defaults to ALL_LINTS; STATIC_LINTS and RUNTIME_LINTS are also exported, as is each lint by name (e.g. unindexedForeignKey).
• source: restrict to "static" or "runtime". Omit to run both.

Feeding the runtime lints

The runtime tier reads shardTraffic, tableScans, indexHits, and tableSamples off the LintContext. The Studio backend fills those from each shard's durable counters.

An Analytics-Engine-backed alternative feeder, loadAnalyticsRuntimeMetrics, exists in source (src/ae-metrics.ts) but is quarantined: not exported from @lunora/advisor's package root, and not importable by consumers of the published package. Nothing in the runtime writes the AE events it would read, so wiring it up today would silently read as "no dead indexes" rather than "no data" for the index_utilization lint. It stays internal, as groundwork for a future writer, until that gap closes. See the docblock atop ae-metrics.ts for the full read contract.

Health map — score, verdicts, baseline

The lints above answer "what is wrong?". scoreAdvisor() answers "how are we doing, and did it get worse?" by rolling a lint run up into a weighted score, a grade, and a per-procedure verdict you can commit and diff in CI.

It is a pure function over findings you already have, so it never re-runs a lint:

import { fromServerSchema, runAdvisor, scoreAdvisor } from "@lunora/advisor";

import schema from "./lunora/schema";

const context = { schema: fromServerSchema(schema) };
const map = scoreAdvisor(context.procedureProtections ?? [], runAdvisor(context, { source: "static" }));

console.log(map.score, map.grade); // e.g. 84 "good"

How a score is built

Every procedure starts at 100 and loses each fired rule's weight, charged once however many times that rule fires, so one lint hitting five call sites costs the same as one hitting a single call site.

A lint may override its own penalty with Lint.weight. Those per-procedure scores roll into a weighted mean: public handlers count double, internal ones and queries count half. Findings that name no procedure (schema shape, wrangler.jsonc config) land in a project bucket weighted against the procedure population, so schema debt still moves the grade.

Grades band the global score: excellent (≥ 90), good (≥ 70), needs-work (≥ 50), at-risk below that.

From the command line

lunora advisor does all of this for you: it scores the app, writes lunora.advisor.map.json, and gates on it.

lunora advisor                    # score, print a summary, write the artifact
lunora advisor --all              # every procedure, grouped by file
lunora advisor --entry m#send     # one procedure and the rules that fired
lunora advisor --min-score 80     # exit 1 below 80
lunora advisor --baseline         # exit 1 on any regression vs the committed map
lunora advisor --no-write         # score without touching the artifact

The artifact is stamped deterministically, so committing it and re-running leaves no diff unless something actually changed.

Gate CI on a committed baseline

Write the map to lunora.advisor.map.json, commit it, and compare against it on each run. compareToBaseline reports five independent regression signals: the global score fell, an existing procedure got worse, a procedure started failing, a procedure's findings grew without its score moving, or the project bucket gained findings.

import { compareToBaseline, parseAdvisorMap } from "@lunora/advisor";

const baseline = parseAdvisorMap(JSON.parse(await readFile("lunora.advisor.map.json", "utf8")));

if (baseline === undefined) {
    // Missing, hand-edited, or written by an older MAP_VERSION.
    throw new Error("advisor baseline is unreadable; regenerate it");
}

const diff = compareToBaseline(map, baseline);

if (!diff.comparable) {
    throw new Error(`baseline not comparable: ${diff.reason}`);
}

if (diff.regressed) {
    process.exitCode = 1;
}

The artifact is deterministic apart from its timestamp: pass generatedAt to make it byte-stable. @lunora/codegen exposes toAdvisorContext() to build the context straight from the feeder.