@lunora/advisor 1.0.0-alpha.7 → 1.0.0-alpha.70

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

@@ -79,20 +79,75 @@ 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`, `constraint_validator`) reads observed signal off the `LintContext` (`shardTraffic`, `tableScans`, `indexHits`, `tableSamples`). The Studio backend fills those from each shard's durable counters:
 
 ```ts
-import { fromServerSchema, loadAnalyticsRuntimeMetrics, runAdvisor } from "@lunora/advisor";
+import { fromServerSchema, runAdvisor } from "@lunora/advisor";
 
 import schema from "./lunora/schema";
 
-// `client` is an `@lunora/bindings/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` / `tableSamples` come from wherever
+// you read your shards' durable counters — the Studio backend reads its own.
+const findings = runAdvisor({ schema: fromServerSchema(schema), shardTraffic, tableScans, indexHits, tableSamples }, { source: "runtime" });
 ```
 
+An Analytics-Engine-backed alternative feeder (querying AE SQL 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.
 
+### 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** weight (`Lint.weight`, else a severity ladder: `ERROR` 20 / `WARN` 10 / `INFO` 5) — 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, hand-edited, or written by an older MAP_VERSION. Fail loudly —
+    // treating it as "no regression" would silently disable the gate forever.
+    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/addons/studio)**.
 
 ## Related