@lunora/advisor 1.0.0-alpha.2 → 1.0.0-alpha.200

package/LICENSE.md

@@ -103,3 +103,9 @@ Unless required by applicable law or agreed to in writing, software distributed
 under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
 CONDITIONS OF ANY KIND, either express or implied. See the License for the
 specific language governing permissions and limitations under the License.
+
+<!-- DEPENDENCIES -->
+<!-- /DEPENDENCIES -->
+
+<!-- TYPE_DEPENDENCIES -->
+<!-- /TYPE_DEPENDENCIES -->

package/README.md

@@ -36,7 +36,7 @@
 
 Schema and query lints for Lunora, modeled on Supabase's splinter. Each lint is a pure rule over a normalized `LintContext`; `runAdvisor()` runs a set and flattens their findings for the CLI, the Vite plugin, and the Studio Advisors view.
 
-Most lints are `static`: they run against the declared schema (and the query reads / inserts the codegen feeder discovers in your function bodies), so a problem surfaces at codegen time before it ships — the edge over a live-database-only advisor. A smaller `runtime` tier (`hot_shard`, `index_utilization`, `constraint_validator`) reads observed signal from a running deployment.
+Most lints are `static`: they run against the declared schema (and the query reads / inserts the codegen feeder discovers in your function bodies), so a problem surfaces at codegen time before it ships — the edge over a live-database-only advisor. A smaller `runtime` tier (`hot_shard`, `index_utilization`, `fan_out_breadth`) reads observed signal from a running deployment.
 
 Part of the [Lunora](https://github.com/anolilab/lunora) framework — a type-safe, real-time backend on Cloudflare Workers + Durable Objects with a Vite-first DX.
 
@@ -79,21 +79,78 @@ for (const finding of findings) {
 
 ### Runtime lints
 
-The runtime tier (`hot_shard`, `index_utilization`, `constraint_validator`) reads observed signal off the `LintContext` (`shardTraffic`, `tableScans`, `indexHits`, `tableSamples`). The Studio backend fills those from each shard's durable counters. As an alternative feeder, `loadAnalyticsRuntimeMetrics` reconstructs the same arrays from the Analytics Engine SQL API:
+The runtime tier (`hot_shard`, `index_utilization`, `fan_out_breadth`) reads observed signal off the `LintContext` (`shardTraffic`, `tableScans`, `indexHits`). The Studio backend fills all three from the shards' admin signal.
 
 ```ts
-import { fromServerSchema, loadAnalyticsRuntimeMetrics, runAdvisor } from "@lunora/advisor";
+import { fromServerSchema, runAdvisor } from "@lunora/advisor";
 
 import schema from "./lunora/schema";
 
-// `client` is an `@lunora/analytics` SQL client (anything with `query(sql)`).
-const metrics = await loadAnalyticsRuntimeMetrics(client, { dataset: "ANALYTICS" });
-const findings = runAdvisor({ schema: fromServerSchema(schema), ...metrics }, { source: "runtime" });
+// `shardTraffic` / `tableScans` / `indexHits` come from wherever you read your
+// shards' durable counters — the Studio backend reads its own.
+const findings = runAdvisor({ schema: fromServerSchema(schema), shardTraffic, tableScans, indexHits }, { source: "runtime" });
 ```
 
+An Analytics-Engine-backed alternative feeder (querying `ctx.analyticsSql` for `lunora.index.hit`/`lunora.shard.request`/`lunora.table.scan` events instead of the in-DO counters) was quarantined off the package root: nothing in the runtime ever writes those AE events, so `shardTraffic` and `tableScans` always came back empty. `indexHits` came back empty too, unless the caller passed `declaredIndexes` — then it listed every declared index with `reads: 0`, a real zero-reads fact rather than a stand-in for "no data". The `AnalyticsMetricsOptions` / `AnalyticsMetricsSource` / `AnalyticsRuntimeMetrics` types it would have produced are still exported from `@lunora/advisor` — they describe the still-valid, still-optional shape of `runAdvisor`'s runtime input — but the loader function itself is not, until something actually emits those events.
+
 A missing metric degrades to an empty array rather than throwing, so a partially configured read path still returns what it can.
 
-> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/addons/studio)**.
+### Observability map (score, coverage, baseline)
+
+`runAdvisor` answers "what is wrong?". `scoreAdvisor` answers "how are we doing, and did it get worse?" — a scored coverage map over your procedures. It is a pure function over findings you already have, so it never re-runs a lint:
+
+```ts
+import { fromServerSchema, runAdvisor, scoreAdvisor } from "@lunora/advisor";
+
+import schema from "./lunora/schema";
+
+const context = { schema: fromServerSchema(schema) };
+const findings = runAdvisor(context, { source: "static" });
+const map = scoreAdvisor(context.procedureProtections ?? [], findings);
+
+console.log(map.score, map.grade); // e.g. 84 "good"
+console.log(map.summary); // { clean: 9, exempt: 0, failing: 1, procedures: 12, rulesFired: 6, warned: 2 }
+```
+
+Each procedure starts at 100 and loses each fired **rule's** severity weight (`ERROR` 20 / `WARN` 10 / `INFO` 5 — severity is the only input; a lint carries no weight of its own) — charged once however many times that rule fires — then rolls up into a weighted global mean: public handlers count double, internal ones and queries half. Findings that name no procedure (schema shape, wrangler config) land in a project bucket weighted against the procedure population, so schema debt genuinely moves the grade.
+
+The verdicts are `clean` / `warned` / `failing` / `exempt` — named for severity, because the score is driven by every lint family rather than an observability family.
+
+Commit the map and gate CI on it:
+
+```ts
+import { compareToBaseline, parseAdvisorMap } from "@lunora/advisor";
+
+const baseline = parseAdvisorMap(JSON.parse(await readFile("lunora.advisor.map.json", "utf8")));
+
+if (baseline === undefined) {
+    // Missing or unreadable (hand-edited, truncated). Fail loudly — treating it
+    // as "no regression" would silently disable the gate forever. A version
+    // mismatch is not rejected here: `compareToBaseline` reports it as
+    // `comparable: false`.
+    throw new Error("advisor baseline is unreadable; regenerate lunora.advisor.map.json");
+}
+
+const diff = compareToBaseline(map, baseline);
+
+// `comparable` must be narrowed before `regressed` is reachable, so a stale
+// baseline cannot read as a clean run.
+if (!diff.comparable) {
+    throw new Error(`advisor baseline not comparable: ${diff.reason}`);
+}
+
+// Five independent signals: the global score fell, an existing procedure got
+// worse, one started failing, one's findings grew without its score moving, or
+// the project bucket gained findings. The growth signals matter because a rule is
+// charged once however many times it fires, and the project score saturates at 0.
+if (diff.regressed) {
+    process.exitCode = 1;
+}
+```
+
+`@lunora/codegen` exposes `toAdvisorContext()` to build the context straight from the feeder, and `lunora advisor` wraps all of this as a command. Full reference for the scoring, verdicts, and the baseline gate is in the [package docs](https://lunora.sh/docs/packages/advisor).
+
+> This README covers the basics. For the full API, options, and guides, see the **[documentation](https://lunora.sh/docs/packages/advisor)**.
 
 ## Related