@telorun/analyzer 0.62.1 → 0.63.0

package/dist/validate-referrer-rules.js

@@ -0,0 +1,255 @@
+import { REFERRER_RULES_ANNOTATION, readRawReferrerRules, readReferrerRules, } from "./referrer-rule.js";
+import { celSourceOf, findDynamicLeaf, readNodes } from "./resource-rule.js";
+import { RULE_BUDGET_MS, compileRuleCondition, conditionRefusals } from "./rule-condition.js";
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Report every way a kind's referrer-rule declarations are malformed. Runs on
+ * the `Telo.Definition` / `Telo.Abstract` doc, so a defect lands on the line the
+ * kind's author wrote rather than on a consumer's resource.
+ *
+ * The `referrer:` filter is NOT resolved here: it is canonicalized in the
+ * declaring module's scope by `resolveSchemaRefKinds`, the only pass holding
+ * that scope, and a name resolving to nothing is reported from there.
+ */
+export function validateReferrerRuleDeclarations(manifest) {
+    const own = manifest.schema;
+    const raw = readRawReferrerRules(own);
+    if (raw === undefined)
+        return [];
+    const base = `schema.${REFERRER_RULES_ANNOTATION}`;
+    const issues = [];
+    const issue = (path, message) => {
+        issues.push({ code: "REFERRER_RULE_INVALID", manifest, path, message });
+    };
+    if (!Array.isArray(raw)) {
+        issue(base, `'${REFERRER_RULES_ANNOTATION}' must be an array of rules.`);
+        return issues;
+    }
+    const seen = new Map();
+    raw.forEach((entry, index) => {
+        const at = `${base}[${index}]`;
+        if (!isObject(entry)) {
+            issue(at, "A rule must be an object with 'condition', 'code' and 'message'.");
+            return;
+        }
+        const condition = celSourceOf(entry.condition);
+        if (condition === undefined || condition.length === 0) {
+            issue(`${at}.condition`, "A rule needs a 'condition' — a CEL expression over 'referrer' (the resource that " +
+                "references this one) and 'self', TRUE when the rule holds. Write it with the !cel tag.");
+        }
+        if (typeof entry.code !== "string" || entry.code.length === 0) {
+            issue(`${at}.code`, "A rule needs a 'code' naming it. It is reported in the diagnostic's data.rule, " +
+                "not as a diagnostic code — every violation reports under REFERRER_RULE_VIOLATED.");
+        }
+        else {
+            const first = seen.get(entry.code);
+            if (first !== undefined) {
+                issue(`${at}.code`, `Rule code '${entry.code}' is already used by rule ${first}. A code names one rule, ` +
+                    "so two rules sharing it are indistinguishable in data.rule.");
+            }
+            else {
+                seen.set(entry.code, index);
+            }
+        }
+        if (typeof entry.message !== "string" || entry.message.length === 0) {
+            issue(`${at}.message`, "A rule needs a 'message' saying what the referrer must do — only the kind's author " +
+                "knows that, and the analyzer supplies only where and what.");
+        }
+        if (entry.referrer !== undefined && typeof entry.referrer !== "string") {
+            issue(`${at}.referrer`, "'referrer' names the kind a referring resource must be, in the same alias-qualified " +
+                "grammar as extends: (Self.Server, Http.Server, Telo.Something). Omit it to apply the " +
+                "rule to every referrer.");
+        }
+        if (entry.severity !== undefined && entry.severity !== "error" && entry.severity !== "warning") {
+            issue(`${at}.severity`, "'severity' must be 'error' or 'warning'.");
+        }
+        if (condition) {
+            for (const refusal of conditionRefusals(condition))
+                issue(`${at}.condition`, refusal);
+        }
+    });
+    return issues;
+}
+/**
+ * Run a kind's referrer rules against every resource that references one of its
+ * resources.
+ *
+ * `self` binds the referenced resource, `referrer` the one that reached it. A
+ * referrer reaching the same resource through several slots is judged ONCE — by
+ * manifest identity, since a name alone is module-scoped — because the condition
+ * reads the two manifests and nothing about the site, so a second site could only
+ * produce the identical verdict at a different path.
+ */
+export function evaluateReferrerRules(manifest, definitionSchema, referrers, 
+/** Whether a referrer of `kind` satisfies a rule's `referrer:` filter —
+ *  Liskov-substitutable, so a child of the named kind matches. Supplied by the
+ *  caller, which holds the definition registry. */
+kindMatches) {
+    const rules = readReferrerRules(definitionSchema);
+    if (rules.length === 0)
+        return [];
+    const self = manifest;
+    const findings = [];
+    for (const rule of rules) {
+        const compiled = compileRuleCondition(rule.condition, ["self", "referrer"]);
+        if ("reason" in compiled) {
+            findings.push({ kind: "failed", rule, reason: compiled.reason });
+            continue;
+        }
+        const { parsed, chains } = compiled;
+        // Identity is the MANIFEST, never `(kind, name)`: resource names are
+        // module-scoped, so two libraries each declaring a `server` of the same kind
+        // would share one bucket and the second violation would be dropped in
+        // silence — the trap the migration provenance index names.
+        const seen = new Set();
+        const started = Date.now();
+        for (const referrer of referrers) {
+            if (rule.referrer !== undefined && !kindMatches(rule.referrer, referrer.kind))
+                continue;
+            if (seen.has(referrer.manifest))
+                continue;
+            seen.add(referrer.manifest);
+            // Only the nodes this condition READS decide whether it can run — the
+            // resource-rule reasoning, and it bites harder here: the referrer is a
+            // whole manifest, so scanning all of it would disable the rule for any
+            // server carrying one unrelated expression.
+            let dynamicAt;
+            for (const node of readNodes(chains, {
+                self,
+                referrer: referrer.manifest,
+            })) {
+                dynamicAt = findDynamicLeaf(node);
+                if (dynamicAt !== undefined)
+                    break;
+            }
+            if (dynamicAt !== undefined) {
+                findings.push({ kind: "skipped", rule, referrer, dynamicAt });
+                continue;
+            }
+            let held;
+            try {
+                held = parsed({ self, referrer: referrer.manifest });
+            }
+            catch (err) {
+                findings.push({
+                    kind: "failed",
+                    rule,
+                    referrer,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+                break;
+            }
+            if (held !== true) {
+                findings.push({ kind: "violation", rule, referrer, message: rule.message });
+            }
+            const elapsed = Date.now() - started;
+            if (elapsed > RULE_BUDGET_MS) {
+                findings.push({ kind: "over-budget", rule, referrer, elapsedMs: elapsed });
+                break;
+            }
+        }
+    }
+    return findings;
+}
+/** Whether a rule found any referrer to judge — the input to the never-exercised
+ *  report, which is how a mistyped `referrer:` filter would otherwise disable a
+ *  check in silence. */
+export function referrerRuleExercised(rule, referrers, kindMatches) {
+    if (rule.referrer === undefined)
+        return referrers.length > 0;
+    const filter = rule.referrer;
+    return referrers.some((referrer) => kindMatches(filter, referrer.kind));
+}
+const nameOf = (manifest) => manifest.metadata?.name ?? "<unnamed>";
+/**
+ * Map one resource's findings to what should be reported.
+ *
+ * A violation names the declaring kind in the message. For a resource rule the
+ * reported resource IS of the kind that declared it, so the origin is implicit;
+ * here it is not — the diagnostic lands on an `Http.Server` for a rule
+ * `HttpServer.Reference` wrote — and leaving that to the author's prose would
+ * make the trail depend on remembering to write it.
+ */
+export function reportReferrerRules(manifest, definition, findings, 
+/** Whether the DECLARING definition is one of the entry's own modules. */
+declarationIsOurs) {
+    const declaringKind = manifest.kind;
+    const out = [];
+    for (const finding of findings) {
+        if (finding.kind === "violation") {
+            out.push({
+                code: "REFERRER_RULE_VIOLATED",
+                severity: finding.rule.severity,
+                message: `${finding.referrer.kind}/${nameOf(finding.referrer.manifest)} at ` +
+                    `'${finding.referrer.path}': required by ${declaringKind} — ${finding.message}`,
+                manifest: finding.referrer.manifest,
+                path: finding.referrer.path,
+                rule: finding.rule.code,
+            });
+            continue;
+        }
+        if (finding.kind === "skipped") {
+            out.push({
+                code: "REFERRER_RULE_SKIPPED",
+                severity: "information",
+                message: `${finding.referrer.kind}/${nameOf(finding.referrer.manifest)}: rule ` +
+                    `'${finding.rule.code}' from ${declaringKind} did not run at ` +
+                    `'${finding.referrer.path}' — the value holds a CEL expression at ` +
+                    `'${finding.dynamicAt}', which is not known until the resource is created. ` +
+                    "Reported rather than dropped: a check whose coverage varies invisibly reads as passing.",
+                manifest: finding.referrer.manifest,
+                path: finding.referrer.path,
+                rule: finding.rule.code,
+            });
+            continue;
+        }
+        const because = finding.kind === "failed"
+            ? `failed to evaluate: ${finding.reason}. Guard an optional field with 'in' or '.?'.`
+            : `exceeded its evaluation budget (${finding.elapsedMs}ms) and was stopped, so ` +
+                "coverage from here on is incomplete. Simplify the condition.";
+        out.push({
+            code: "REFERRER_RULE_INVALID",
+            severity: declarationIsOurs ? "error" : "warning",
+            message: `Referrer rule '${finding.rule.code}' on kind '${declaringKind}' ${because} ` +
+                `This is a defect in the rule, not in ${nameOf(manifest)}` +
+                (declarationIsOurs ? "." : " — it is declared by a module this workspace does not own."),
+            // The two halves of the anchor move together or they name a node that
+            // does not exist: the rule's own declaration site is a path in the
+            // DEFINITION, while a referrer's slot path is a path in the REFERRER. A
+            // dependency's broken rule therefore lands on the referrer it was checking
+            // — a manifest the reader owns and where the path resolves — and on the
+            // referenced resource only when there is no referrer to name (a condition
+            // that failed to compile at all).
+            ...(declarationIsOurs && definition
+                ? {
+                    manifest: definition,
+                    path: `schema.${REFERRER_RULES_ANNOTATION}[${finding.rule.index}]`,
+                }
+                : finding.referrer
+                    ? { manifest: finding.referrer.manifest, path: finding.referrer.path }
+                    : { manifest }),
+            rule: finding.rule.code,
+        });
+    }
+    return out;
+}
+/** The report for a rule nothing ever exercised — here that means no resource of
+ *  the kind was referenced by anything the filter matches, which is what a typo
+ *  in `referrer:` looks like from the outside. */
+export function reportUnexercisedReferrerRule(definition, rule) {
+    return {
+        code: "REFERRER_RULE_UNEXERCISED",
+        severity: "information",
+        message: `Referrer rule '${rule.code}' never ran: nothing` +
+            (rule.referrer === undefined ? "" : ` of kind '${rule.referrer}'`) +
+            " references a resource of this kind, so nothing has proven the condition." +
+            (rule.referrer === undefined
+                ? ""
+                : " A 'referrer' naming a kind no manifest uses disables the rule in silence."),
+        manifest: definition,
+        path: `schema.${REFERRER_RULES_ANNOTATION}[${rule.index}]`,
+        rule: rule.code,
+    };
+}

package/dist/validate-resource-rules.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The strict half of the `x-telo-resource-rules` accessor split
+ * (`validate-ref-slots.ts` / `validate-zone-slots.ts` precedent), plus the
+ * evaluation pass that runs the rules against each resource.
+ *
+ * Both halves live here because they fail in opposite directions and must agree
+ * about what a rule MEANS: a declaration the reader cannot parse is silently
+ * unenforced — the check reads as passing when it never ran — while a rule that
+ * throws would otherwise be reported against the consumer's manifest, blaming an
+ * author for a defect in someone else's kind.
+ *
+ * Scoping follows `X_TELO_REF_UNRESOLVED`, and it splits by WHOSE defect it is.
+ * A declaration defect belongs to the kind, so it is reported only for
+ * definitions in the entry's own modules. A VIOLATION belongs to the data, so it
+ * is reported wherever the offending resource is the entry's — the opposite
+ * direction, for the same reason. A rule that THROWS or runs out of budget is a
+ * defect in the rule found while checking someone else's data: the caller
+ * anchors it on the declaring definition when that is ours, and downgrades it to
+ * a warning when it is a published dependency's, so it is never an error on a
+ * line the author cannot change.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import { type ResourceRule } from "./resource-rule.js";
+/** Published name for the shared budget — see `rule-condition.ts`. */
+export declare const RESOURCE_RULE_BUDGET_MS = 50;
+export interface ResourceRuleIssue {
+    code: "RESOURCE_RULE_INVALID";
+    manifest: ResourceManifest;
+    path: string;
+    message: string;
+}
+/** One rule's verdict on one resource. */
+export type ResourceRuleFinding = {
+    kind: "violation";
+    rule: ResourceRule;
+    /** Path of the offending element, or "" for a rule with no `in:`. */
+    path: string;
+    message: string;
+} | {
+    kind: "skipped";
+    rule: ResourceRule;
+    path: string;
+    dynamicAt: string;
+} | {
+    kind: "failed";
+    rule: ResourceRule;
+    path: string;
+    reason: string;
+} | {
+    kind: "over-budget";
+    rule: ResourceRule;
+    path: string;
+    elapsedMs: number;
+};
+/**
+ * Report every way a kind's rule declarations are malformed. Runs on the
+ * `Telo.Definition` / `Telo.Abstract` doc, so a defect lands on the line the
+ * kind's author wrote rather than on a consumer's resource.
+ */
+export declare function validateResourceRuleDeclarations(manifest: ResourceManifest, 
+/**
+ * The schema an `in:` pointer is checked against — the SAME merged schema the
+ * evaluation pass reads, so the two halves cannot disagree about which fields
+ * a kind has. Reading the doc's own `schema:` here was correct only for a leaf
+ * kind: a rule declared on a parent and evaluated against a child's field
+ * would be reported invalid at the parent, and a child's rule naming an
+ * INHERITED field would be told the kind does not declare it. Both arrive as
+ * soon as rules are declared on an abstract, which is where a rule shared by
+ * every backend belongs.
+ */
+effectiveSchema?: unknown): ResourceRuleIssue[];
+/**
+ * Run a kind's rules against one resource.
+ *
+ * `self` binds the resource, `this` the element under test — the two coexist in
+ * cel-js, which is what lets a rule correlate an element against the whole
+ * (`c in self.columns`) with no path language.
+ */
+export declare function evaluateResourceRules(manifest: ResourceManifest, definitionSchema: unknown): ResourceRuleFinding[];
+/** Whether a rule found anything to iterate on this resource — the input to the
+ *  never-exercised report, which is the second way coverage varies invisibly. */
+export declare function ruleExercised(manifest: ResourceManifest, rule: ResourceRule): boolean;
+/** Where a rule finding is reported, and how loudly. Plain data, so the caller
+ *  pushes it exactly as it does for `zoneSlotIssues` / `refSlotIssues` rather
+ *  than composing severity, ownership and prose inline in the resource loop. */
+export interface ResourceRuleDiagnostic {
+    code: "RESOURCE_RULE_VIOLATED" | "RESOURCE_RULE_SKIPPED" | "RESOURCE_RULE_INVALID" | "RESOURCE_RULE_UNEXERCISED";
+    severity: "error" | "warning" | "information";
+    message: string;
+    /** The resource the finding is reported ON — the offending one for a
+     *  violation, the DECLARING definition for a defect in the rule itself. */
+    manifest: ResourceManifest;
+    path?: string;
+    rule: string;
+}
+/**
+ * Map one resource's findings to what should be reported.
+ *
+ * The split by whose defect it is lives here, with the finding vocabulary,
+ * rather than in the analyzer's resource loop: a violation belongs to the DATA
+ * and is reported on the resource, while a rule that throws or exhausts its
+ * budget is a defect in the RULE and belongs on the definition that declared it
+ * — downgraded to a warning when that definition is a published dependency's,
+ * since an error there blocks `telo check` on a line the consumer cannot change.
+ */
+export declare function reportResourceRules(manifest: ResourceManifest, definition: ResourceManifest | undefined, findings: readonly ResourceRuleFinding[], 
+/** Whether the DECLARING definition is one of the entry's own modules. */
+declarationIsOurs: boolean): ResourceRuleDiagnostic[];
+/** The report for a rule nothing ever exercised — the second way coverage varies
+ *  invisibly, beside the dynamic-leaf skip. */
+export declare function reportUnexercisedRule(definition: ResourceManifest, rule: ResourceRule): ResourceRuleDiagnostic;
+//# sourceMappingURL=validate-resource-rules.d.ts.map

package/dist/validate-resource-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-resource-rules.d.ts","sourceRoot":"","sources":["../src/validate-resource-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,OAAO,EASL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAE5B,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,KAAiB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,GAC3B;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,YAAY,CAAC;IACnB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAmCjF;;;;GAIG;AACH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,gBAAgB;AAC1B;;;;;;;;;GASG;AACH,eAAe,CAAC,EAAE,OAAO,GACxB,iBAAiB,EAAE,CA+FrB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,gBAAgB,EAC1B,gBAAgB,EAAE,OAAO,GACxB,mBAAmB,EAAE,CA4DvB;AAED;iFACiF;AACjF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAIrF;AAED;;gFAEgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EACA,wBAAwB,GACxB,uBAAuB,GACvB,uBAAuB,GACvB,2BAA2B,CAAC;IAChC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,aAAa,CAAC;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;+EAC2E;IAC3E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,gBAAgB,EAC1B,UAAU,EAAE,gBAAgB,GAAG,SAAS,EACxC,QAAQ,EAAE,SAAS,mBAAmB,EAAE;AACxC,0EAA0E;AAC1E,iBAAiB,EAAE,OAAO,GACzB,sBAAsB,EAAE,CA2D1B;AAED;+CAC+C;AAC/C,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,YAAY,GACjB,sBAAsB,CAYxB"}

package/dist/validate-resource-rules.js

@@ -0,0 +1,283 @@
+import { RULE_BUDGET_MS, compileRuleCondition, conditionRefusals } from "./rule-condition.js";
+import { RESOURCE_RULES_ANNOTATION, celSourceOf, findDynamicLeaf, pointerSegments, readRawResourceRules, readResourceRules, readNodes, resolveRuleSubjects, } from "./resource-rule.js";
+/** Published name for the shared budget — see `rule-condition.ts`. */
+export const RESOURCE_RULE_BUDGET_MS = RULE_BUDGET_MS;
+function isObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+/** Navigate a kind's own schema to the node describing what a pointer names, so
+ *  an `in:` naming a field the kind does not declare is caught at the kind. */
+function schemaAtPointer(schema, pointer) {
+    const segments = pointerSegments(pointer);
+    if (!segments)
+        return undefined;
+    let node = schema;
+    for (const segment of segments) {
+        if (!isObject(node))
+            return undefined;
+        const properties = isObject(node.properties) ? node.properties : undefined;
+        const next = properties?.[segment] ??
+            (node.type === "array" ? node.items : undefined) ??
+            (isObject(node.additionalProperties) ? node.additionalProperties : undefined);
+        if (next === undefined)
+            return undefined;
+        node = next;
+    }
+    return node;
+}
+/** True when a schema node describes something a rule can iterate. Unknown or
+ *  absent `type` passes: an open schema is not evidence of a defect. */
+function isIterableSchema(node) {
+    if (!isObject(node))
+        return true;
+    const type = node.type;
+    if (type === undefined)
+        return true;
+    const types = Array.isArray(type) ? type : [type];
+    return types.some((t) => t === "array" || t === "object");
+}
+/**
+ * Report every way a kind's rule declarations are malformed. Runs on the
+ * `Telo.Definition` / `Telo.Abstract` doc, so a defect lands on the line the
+ * kind's author wrote rather than on a consumer's resource.
+ */
+export function validateResourceRuleDeclarations(manifest, 
+/**
+ * The schema an `in:` pointer is checked against — the SAME merged schema the
+ * evaluation pass reads, so the two halves cannot disagree about which fields
+ * a kind has. Reading the doc's own `schema:` here was correct only for a leaf
+ * kind: a rule declared on a parent and evaluated against a child's field
+ * would be reported invalid at the parent, and a child's rule naming an
+ * INHERITED field would be told the kind does not declare it. Both arrive as
+ * soon as rules are declared on an abstract, which is where a rule shared by
+ * every backend belongs.
+ */
+effectiveSchema) {
+    const own = manifest.schema;
+    const schema = effectiveSchema ?? own;
+    const raw = readRawResourceRules(own);
+    if (raw === undefined)
+        return [];
+    const base = `schema.${RESOURCE_RULES_ANNOTATION}`;
+    const issues = [];
+    const issue = (path, message) => {
+        issues.push({ code: "RESOURCE_RULE_INVALID", manifest, path, message });
+    };
+    if (!Array.isArray(raw)) {
+        issue(base, `'${RESOURCE_RULES_ANNOTATION}' must be an array of rules.`);
+        return issues;
+    }
+    const seen = new Map();
+    raw.forEach((entry, index) => {
+        const at = `${base}[${index}]`;
+        if (!isObject(entry)) {
+            issue(at, "A rule must be an object with 'condition', 'code' and 'message'.");
+            return;
+        }
+        const condition = celSourceOf(entry.condition);
+        if (condition === undefined || condition.length === 0) {
+            issue(`${at}.condition`, "A rule needs a 'condition' — a CEL expression that is TRUE when the rule holds " +
+                "(the polarity Telo.JsonSchema rules use). Write it with the !cel tag.");
+        }
+        if (typeof entry.code !== "string" || entry.code.length === 0) {
+            issue(`${at}.code`, "A rule needs a 'code' naming it. It is reported in the diagnostic's data.rule, " +
+                "not as a diagnostic code — every violation reports under RESOURCE_RULE_VIOLATED.");
+        }
+        else {
+            const first = seen.get(entry.code);
+            if (first !== undefined) {
+                issue(`${at}.code`, `Rule code '${entry.code}' is already used by rule ${first}. A code names one rule, ` +
+                    "so two rules sharing it are indistinguishable in data.rule.");
+            }
+            else {
+                seen.set(entry.code, index);
+            }
+        }
+        if (typeof entry.message !== "string" || entry.message.length === 0) {
+            issue(`${at}.message`, "A rule needs a 'message' saying what the relationship means — only the kind's " +
+                "author knows that, and the analyzer supplies only where and what.");
+        }
+        if (entry.severity !== undefined &&
+            entry.severity !== "error" &&
+            entry.severity !== "warning") {
+            issue(`${at}.severity`, "'severity' must be 'error' or 'warning'.");
+        }
+        if (entry.in !== undefined) {
+            if (typeof entry.in !== "string") {
+                issue(`${at}.in`, "'in' must be a JSON Pointer to the collection the rule iterates.");
+            }
+            else if (!pointerSegments(entry.in)) {
+                issue(`${at}.in`, `'in' must be a JSON Pointer starting with '/', got '${entry.in}'.`);
+            }
+            else {
+                const node = schemaAtPointer(schema, entry.in);
+                if (node === undefined) {
+                    issue(`${at}.in`, `'in' points at '${entry.in}', which this kind's schema does not declare. ` +
+                        "The pointer is the diagnostic's anchor, so it must name a field of this kind.");
+                }
+                else if (!isIterableSchema(node)) {
+                    issue(`${at}.in`, `'in' points at '${entry.in}', which is not a collection. A rule iterates an ` +
+                        "array or a map; omit 'in' for a rule about the resource as a whole.");
+                }
+            }
+        }
+        if (condition) {
+            for (const refusal of conditionRefusals(condition))
+                issue(`${at}.condition`, refusal);
+        }
+    });
+    return issues;
+}
+/**
+ * Run a kind's rules against one resource.
+ *
+ * `self` binds the resource, `this` the element under test — the two coexist in
+ * cel-js, which is what lets a rule correlate an element against the whole
+ * (`c in self.columns`) with no path language.
+ */
+export function evaluateResourceRules(manifest, definitionSchema) {
+    const rules = readResourceRules(definitionSchema);
+    if (rules.length === 0)
+        return [];
+    const self = manifest;
+    const findings = [];
+    for (const rule of rules) {
+        const subjects = rule.in === undefined ? [{ path: "", value: self }] : resolveRuleSubjects(self, rule.in);
+        // `undefined` means the pointer resolved to a scalar — a declaration defect
+        // the strict half reports at the kind. Evaluating anyway would report it
+        // against the consumer instead.
+        if (subjects === undefined)
+            continue;
+        const compiled = compileRuleCondition(rule.condition, ["self", "this"]);
+        if ("reason" in compiled) {
+            findings.push({ kind: "failed", rule, path: "", reason: compiled.reason });
+            continue;
+        }
+        const { parsed, chains } = compiled;
+        const started = Date.now();
+        for (const subject of subjects) {
+            // Only the nodes this condition READS decide whether it can run — see
+            // `readNodes`. Scanning the whole subject would disable every
+            // resource-wide rule on any manifest containing one unrelated expression.
+            let dynamicAt;
+            for (const node of readNodes(chains, { self, this: subject.value })) {
+                dynamicAt = findDynamicLeaf(node);
+                if (dynamicAt !== undefined)
+                    break;
+            }
+            if (dynamicAt !== undefined) {
+                findings.push({ kind: "skipped", rule, path: subject.path, dynamicAt });
+                continue;
+            }
+            let held;
+            try {
+                held = parsed({ self, this: subject.value, key: subject.key ?? null });
+            }
+            catch (err) {
+                findings.push({
+                    kind: "failed",
+                    rule,
+                    path: subject.path,
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+                break;
+            }
+            if (held !== true) {
+                findings.push({ kind: "violation", rule, path: subject.path, message: rule.message });
+            }
+            const elapsed = Date.now() - started;
+            if (elapsed > RESOURCE_RULE_BUDGET_MS) {
+                findings.push({ kind: "over-budget", rule, path: subject.path, elapsedMs: elapsed });
+                break;
+            }
+        }
+    }
+    return findings;
+}
+/** Whether a rule found anything to iterate on this resource — the input to the
+ *  never-exercised report, which is the second way coverage varies invisibly. */
+export function ruleExercised(manifest, rule) {
+    if (rule.in === undefined)
+        return true;
+    const subjects = resolveRuleSubjects(manifest, rule.in);
+    return subjects !== undefined && subjects.length > 0;
+}
+/**
+ * Map one resource's findings to what should be reported.
+ *
+ * The split by whose defect it is lives here, with the finding vocabulary,
+ * rather than in the analyzer's resource loop: a violation belongs to the DATA
+ * and is reported on the resource, while a rule that throws or exhausts its
+ * budget is a defect in the RULE and belongs on the definition that declared it
+ * — downgraded to a warning when that definition is a published dependency's,
+ * since an error there blocks `telo check` on a line the consumer cannot change.
+ */
+export function reportResourceRules(manifest, definition, findings, 
+/** Whether the DECLARING definition is one of the entry's own modules. */
+declarationIsOurs) {
+    const name = manifest.metadata?.name ?? "<unnamed>";
+    const out = [];
+    for (const finding of findings) {
+        const at = finding.path === "" ? undefined : finding.path;
+        if (finding.kind === "violation") {
+            out.push({
+                // One analyzer-owned envelope: surfaces branch on `code`, so a published
+                // module free to emit any string could shadow machinery that never
+                // expected a third party in that space. The rule's own name rides in
+                // `data.rule`.
+                code: "RESOURCE_RULE_VIOLATED",
+                severity: finding.rule.severity,
+                message: `${manifest.kind}/${name}${at ? ` at '${at}'` : ""}: ${finding.message}`,
+                manifest,
+                path: at,
+                rule: finding.rule.code,
+            });
+            continue;
+        }
+        if (finding.kind === "skipped") {
+            out.push({
+                code: "RESOURCE_RULE_SKIPPED",
+                severity: "information",
+                message: `${manifest.kind}/${name}: rule '${finding.rule.code}' did not run` +
+                    `${at ? ` at '${at}'` : ""} — the value holds a CEL expression at ` +
+                    `'${finding.dynamicAt}', which is not known until the resource is created. ` +
+                    "Reported rather than dropped: a check whose coverage varies invisibly reads as passing.",
+                manifest,
+                path: at,
+                rule: finding.rule.code,
+            });
+            continue;
+        }
+        const because = finding.kind === "failed"
+            ? `failed to evaluate: ${finding.reason}. Guard an optional field with \`in\` or \`.?\`.`
+            : `exceeded its evaluation budget (${finding.elapsedMs}ms) and was stopped, so ` +
+                "coverage from here on is incomplete. Simplify the condition.";
+        out.push({
+            code: "RESOURCE_RULE_INVALID",
+            severity: declarationIsOurs ? "error" : "warning",
+            message: `Rule '${finding.rule.code}' on kind '${manifest.kind}' ${because} ` +
+                `This is a defect in the rule, not in ${name}` +
+                (declarationIsOurs ? "." : " — it is declared by a module this workspace does not own."),
+            manifest: declarationIsOurs && definition ? definition : manifest,
+            path: declarationIsOurs && definition
+                ? `schema.${RESOURCE_RULES_ANNOTATION}[${finding.rule.index}]`
+                : at,
+            rule: finding.rule.code,
+        });
+    }
+    return out;
+}
+/** The report for a rule nothing ever exercised — the second way coverage varies
+ *  invisibly, beside the dynamic-leaf skip. */
+export function reportUnexercisedRule(definition, rule) {
+    return {
+        code: "RESOURCE_RULE_UNEXERCISED",
+        severity: "information",
+        message: `Rule '${rule.code}' never ran: '${rule.in}' was empty on every resource of this kind, ` +
+            "so nothing has proven the condition. A nested typo in the condition is caught only at " +
+            "evaluation.",
+        manifest: definition,
+        path: `schema.${RESOURCE_RULES_ANNOTATION}[${rule.index}]`,
+        rule: rule.code,
+    };
+}