@telorun/analyzer 0.62.1 → 0.63.0

package/dist/validate-durable-regions.js

@@ -0,0 +1,336 @@
+import { isCompiledValue, VALUE_TYPES } from "@telorun/sdk";
+import { auditCalls, buildCelEnvironment, isTaggedSentinel, CEL_ENGINE } from "@telorun/templating";
+import { DiagnosticSeverity } from "./types.js";
+import { findZoneRegions, } from "./resolve-zone-containment.js";
+const SOURCE = "telo";
+/**
+ * The impure functions one CEL source actually CALLS, in source order.
+ *
+ * Parsed, never text-matched. A regex over the source is wrong in both
+ * directions and in exactly the ways this repo has already retired elsewhere:
+ * it fires on a function name inside a string literal, on an unrelated receiver
+ * method that happens to share a name, and on text inside an interpolation it
+ * has no business reading — while `analyze` already returns every call site the
+ * parser found, each carrying the `deterministic` flag resolved from the
+ * registry. One expression, one verdict, and it is the engine's.
+ *
+ * `deterministic === false` specifically: `undefined` means the name resolved to
+ * nothing, or to a function carrying no determinism metadata, and absent is not
+ * "impure" any more than it is "pure" — a name the registry cannot account for
+ * is `CEL_UNKNOWN_FUNCTION`'s to report, not this rule's to guess at.
+ */
+function impureCalls(source) {
+    let ast;
+    try {
+        ast = CEL_ENV.parse(source).ast;
+    }
+    catch {
+        // Unparseable CEL is `CEL_SYNTAX_ERROR`'s to report, and it will be, from
+        // the pass that owns the expression. Reporting nothing here is right:
+        // guessing at the calls in text that does not parse is exactly the
+        // text-matching this replaced.
+        return [];
+    }
+    const names = [];
+    for (const call of auditCalls(source, ast, CEL_ENV).calls) {
+        if (call.deterministic === false && !names.includes(call.name))
+            names.push(call.name);
+    }
+    return names;
+}
+/** One environment for the whole pass: it carries the function registry, which
+ *  is what resolves a call's determinism, and nothing manifest-specific — the
+ *  typed scope belongs to the CEL validation pass, which asks a different
+ *  question of the same expressions. */
+const CEL_ENV = buildCelEnvironment();
+/** Every CEL source string reachable in a value tree, with the path that holds
+ *  it. Stops at nested `{ kind }` declarations, which belong to another
+ *  resource. */
+function celSources(value, path, out) {
+    // A raw `${{ }}` string, which is what a consumer holding an unprecompiled
+    // manifest sees. Each interpolation is pushed SEPARATELY: the surrounding
+    // literal text is not CEL, and handing the whole string to a CEL parser
+    // fails — which would silently report no calls at all for every expression
+    // written this way.
+    if (typeof value === "string") {
+        for (const expression of interpolatedExpressions(value))
+            out.push([path, expression]);
+        return;
+    }
+    if (!value || typeof value !== "object")
+        return;
+    // By the time this pass runs the loader has PRECOMPILED every CEL slot, so the
+    // common shape is a CompiledValue rather than a string or a tag sentinel.
+    // Reading only the authored spellings is why this check was silent on every
+    // manifest that reached it — the one shape it never met was the one it always
+    // gets. An interpolated string keeps its expressions in `parts`, so those are
+    // descended into rather than read off the joined source.
+    if (isCompiledValue(value)) {
+        if (typeof value.source === "string")
+            out.push([path, value.source]);
+        for (const [i, part] of (value.parts ?? []).entries()) {
+            if (typeof part !== "string")
+                celSources(part, `${path}[${i}]`, out);
+        }
+        return;
+    }
+    // An unprecompiled `!cel` tag — what a round-trip consumer (the editor) holds,
+    // and what reaches this pass whenever precompilation was not requested. Read
+    // through the templating predicates rather than by testing a marker key: the
+    // sentinel's shape is that package's, and spelling it here is a second place
+    // it would have to be kept right.
+    if (isTaggedSentinel(value) && value.engine === CEL_ENGINE) {
+        out.push([path, value.source]);
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, i) => celSources(item, `${path}[${i}]`, out));
+        return;
+    }
+    // STOP at a nested resource declaration. Skipping the `kind` key alone was not
+    // that: it walked straight into the declaration's own configuration and
+    // reported its CEL against the enclosing resource, which is both the wrong
+    // anchor and a claim about a region that expression is not in. The boundary is
+    // the presence of `kind`, the same line Phase-5 injection and the include walk
+    // already draw.
+    const record = value;
+    if (path && typeof record.kind === "string")
+        return;
+    for (const [key, child] of Object.entries(record)) {
+        if (key === "kind" || key === "metadata")
+            continue;
+        celSources(child, path ? `${path}.${key}` : key, out);
+    }
+}
+/** The expressions inside a `${{ … }}` interpolated string, unwrapped. Balanced
+ *  on `}}` rather than on the first `}`, so an expression containing a map
+ *  literal is not cut in half. */
+function interpolatedExpressions(text) {
+    const out = [];
+    let at = 0;
+    for (;;) {
+        const open = text.indexOf("${{", at);
+        if (open < 0)
+            return out;
+        const close = text.indexOf("}}", open + 3);
+        if (close < 0)
+            return out;
+        const expression = text.slice(open + 3, close).trim();
+        if (expression)
+            out.push(expression);
+        at = close + 2;
+    }
+}
+/**
+ * `DURABLE_NONDETERMINISM` — impure CEL inside an `idempotent` region.
+ *
+ * **It keys on `idempotent`, and only there does it say something true.** Impure
+ * CEL in a *journaled* position is not a defect at all — it is the correct
+ * semantic: `now()` in a step's inputs is recorded on first execution and
+ * replayed identically, which is exactly what a durable timestamp should do.
+ *
+ * What makes the idempotent case different is that such a region re-runs on
+ * resume with its prior effects INTACT, because nothing discarded them — the
+ * region's whole claim is that re-running is a no-op. Impure CEL falsifies
+ * exactly that claim: `uuid()` as a key writes record A on the first pass and
+ * record B on the second, so the re-run is not a no-op and the assertion the
+ * author signed is false. The diagnostic can therefore say precisely that.
+ *
+ * **`atomic` is the wrong trigger, in both directions.** Too wide: collapse
+ * there is conditional on a runtime attestation, so a transaction sharing the
+ * journal's own transaction is NOT collapsed and its decisions genuinely are
+ * journaled — a static trigger would fire on the configuration this design
+ * recommends. Too narrow: an atomic zone that does re-run is a RETRY, not a
+ * replay — its effects were discarded, so a fresh timestamp is simply a fresh
+ * attempt.
+ */
+function checkNondeterminism(region, graph, reportModules, diagnostics) {
+    for (const { node } of region.contents.values()) {
+        const [manifest, base, prefix] = celScopeOf(node, graph);
+        if (!manifest || !owned(manifest, reportModules))
+            continue;
+        const found = [];
+        celSources(base, prefix, found);
+        for (const [path, source] of found) {
+            for (const fn of impureCalls(source)) {
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "DURABLE_NONDETERMINISM",
+                    source: SOURCE,
+                    message: `'${fn}()' is evaluated inside a region declared idempotent by ` +
+                        `${region.provider.kind} '${region.provider.name}' — "${region.reason}". A ` +
+                        `region with that claim re-runs on a resume with its earlier effects intact, ` +
+                        `so an expression that produces a different value each time makes the ` +
+                        `re-run something other than a no-op and the claim false. Pin the value ` +
+                        `once for the region instead of computing it per pass.`,
+                    data: {
+                        resource: { kind: manifest.kind, name: manifest.metadata?.name },
+                        filePath: manifest.metadata?.source,
+                        path,
+                    },
+                });
+                // One diagnostic per expression: naming every impure call in a single
+                // expression would repeat one fix several times.
+                break;
+            }
+        }
+    }
+}
+/**
+ * `DURABLE_DETACH_FORBIDDEN` — a detached dispatch inside a `replayed` region.
+ *
+ * Journal-on-completion would record the DISPATCH as done while the work runs
+ * on, so a resume skips it and a crash loses it — durability's exact inverse.
+ *
+ * The replacement is better than what it forbids, which is why this is an error
+ * rather than a warning: what an author wants there is a nested durable run
+ * started without awaiting, so the step's outcome is a journalable run id, the
+ * child gets its own identity and its own durability, and nothing is lost on
+ * either side. That is what Temporal's child workflows and Restate's one-way
+ * send already are.
+ *
+ * It keys off the dispatch BEING detached rather than off any kind, so it covers
+ * a detaching decorator's configured mode as readily as an explicit detach.
+ */
+function checkDetach(region, reportModules, diagnostics) {
+    for (const boundary of region.boundaries) {
+        if (!boundary.escaping.includes("detached"))
+            continue;
+        if (!owned(boundary.from.manifest, reportModules))
+            continue;
+        diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "DURABLE_DETACH_FORBIDDEN",
+            source: SOURCE,
+            message: `${boundary.from.kind} '${boundary.from.name}' dispatches '${boundary.edge.slot}' ` +
+                `detached inside a durable region (${region.provider.kind} ` +
+                `'${region.provider.name}'). Progress is recorded when a step COMPLETES, so a ` +
+                `detached dispatch would be recorded as done while its work was still running — ` +
+                `a resume would skip it and a crash would lose it, which is the opposite of what ` +
+                `durability provides. Start a nested durable run instead and let the step record ` +
+                `its run id: the work keeps its own identity and its own recovery, and nothing is ` +
+                `awaited.`,
+            data: {
+                resource: { kind: boundary.from.kind, name: boundary.from.name },
+                filePath: boundary.from.manifest.metadata?.source,
+                path: boundary.edge.path,
+            },
+        });
+    }
+}
+/**
+ * `DURABLE_UNJOURNALABLE_RESULT` — a live value in a journaled position.
+ *
+ * A live handle is consumed by reading, so it exists exactly once and a
+ * recording of it is a recording of nothing. The rule keys off the `live` field
+ * of the value-type vocabulary rather than off a type NAME, for the reason that
+ * vocabulary is data: a live type added later is covered by its entry alone, and
+ * the analyzer names a representation rather than a type.
+ *
+ * A WARNING rather than an error, and the runtime is the gate: what a step
+ * actually produces is only as knowable as its declared contract, and a kind
+ * that declares none falls back to a permissive shape that proves nothing. The
+ * runtime raises `ERR_DURABLE_UNJOURNALABLE_VALUE` at the step path that
+ * produced the value, which is as actionable and is true regardless of what was
+ * declared.
+ */
+function checkUnjournalableResults(region, resolveDef, graph, reportModules, diagnostics) {
+    for (const { node } of region.contents.values()) {
+        if (node.type !== "step")
+            continue;
+        for (const edge of graph.edgesFrom(node.id)) {
+            const target = edge.to ? graph.nodes.get(edge.to) : undefined;
+            if (!target || target.type !== "resource")
+                continue;
+            const def = resolveDef(target.kind, target.manifest.metadata?.module);
+            const declared = target.manifest.outputType ??
+                def?.outputType;
+            if (!isLiveSchema(declared))
+                continue;
+            const owner = graph.nodes.get(node.owner);
+            const manifest = owner?.type === "resource" ? owner.manifest : target.manifest;
+            if (!owned(manifest, reportModules))
+                continue;
+            diagnostics.push({
+                severity: DiagnosticSeverity.Warning,
+                code: "DURABLE_UNJOURNALABLE_RESULT",
+                source: SOURCE,
+                message: `Step '${node.name ?? node.path}' invokes ` +
+                    `${target.kind} '${target.name}', whose declared output is a live value, inside a ` +
+                    `durable region (${region.provider.kind} '${region.provider.name}'). A live handle ` +
+                    `is produced by consuming it, so it cannot be recorded and replayed — the run will ` +
+                    `fail at this step with ERR_DURABLE_UNJOURNALABLE_VALUE. Collect what you need ` +
+                    `from it into a plain value inside the step, or move the streaming work outside ` +
+                    `the durable body.`,
+                data: {
+                    resource: { kind: manifest.kind, name: manifest.metadata?.name },
+                    filePath: manifest.metadata?.source,
+                    path: node.path,
+                },
+            });
+        }
+    }
+}
+/** Is this declared type a live-representation value? Reads the annotation the
+ *  vocabulary defines rather than testing against a type name. */
+function isLiveSchema(schema) {
+    if (!schema || typeof schema !== "object")
+        return false;
+    const annotation = schema["x-telo-type"];
+    const name = typeof annotation === "string"
+        ? annotation
+        : annotation?.name;
+    if (!name) {
+        const inner = schema.schema;
+        return inner !== undefined && inner !== schema ? isLiveSchema(inner) : false;
+    }
+    // The one place a name is compared, and it is compared against the LIVE flag
+    // of the vocabulary entry rather than against a literal — so this stays true
+    // when a second live type is declared.
+    return LIVE_TYPE_NAMES.has(name);
+}
+/** Names of the value types whose representation is live, derived from the
+ *  vocabulary itself. A constant rather than one-shot mutable state: the
+ *  vocabulary is fixed at module load, so there is nothing to initialize and
+ *  nothing an initialization order could get wrong. */
+const LIVE_TYPE_NAMES = new Set([...VALUE_TYPES.values()].filter((e) => e.live).map((e) => e.name));
+/**
+ * Where a node's CEL lives, and which manifest a diagnostic about it anchors on.
+ *
+ * A STEP is where most of a body's CEL actually is — a step's `inputs`, its
+ * `when`, a branch predicate — and a step node carries no manifest of its own,
+ * so it anchors on the resource whose body declares it. Reading only resource
+ * nodes would have made this check silent for exactly the position it exists to
+ * cover.
+ */
+function celScopeOf(node, graph) {
+    if (node.type === "resource")
+        return [node.manifest, node.manifest, ""];
+    const owner = graph.nodes.get(node.owner);
+    const manifest = owner?.type === "resource" ? owner.manifest : undefined;
+    return [manifest, node.step, node.path];
+}
+/**
+ * Is this manifest the entry's to fix?
+ *
+ * Scoped by the manifest's own DECLARING MODULE, not by its file path: a
+ * published dependency's body is not the consumer's to fix (the
+ * `X_TELO_REF_UNRESOLVED` precedent), and a path is not the module — a fixture
+ * nested under one module's directory belongs to its own.
+ */
+function owned(manifest, reportModules) {
+    const module = manifest.metadata?.module;
+    return !module || reportModules.size === 0 || reportModules.has(module);
+}
+/** Every durable-region diagnostic, over one graph. */
+export function validateDurableRegions(args) {
+    const diagnostics = [];
+    for (const region of findZoneRegions(args.graph, args.resolveDef, "replayed")) {
+        checkDetach(region, args.reportModules, diagnostics);
+        checkUnjournalableResults(region, args.resolveDef, args.graph, args.reportModules, diagnostics);
+    }
+    for (const region of findZoneRegions(args.graph, args.resolveDef, "idempotent")) {
+        checkNondeterminism(region, args.graph, args.reportModules, diagnostics);
+    }
+    return diagnostics;
+}

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAuD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA8ctB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAOrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAuD/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAogBtB"}

package/dist/validate-references.js

@@ -1,8 +1,9 @@
 import { isRefSentinel } from "@telorun/templating";
 import { visitManifest } from "./manifest-visitor.js";
 import { isInlineResource, resolveFieldEntries, resolveFieldValues } from "./reference-field-map.js";
-import { navigateJsonPointer } from "./schema-compat.js";
+import { navigateJsonPointer, substituteCelFields } from "./schema-compat.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { resolveTypeFieldToSchema } from "./validate-cel-context.js";
 import { DiagnosticSeverity } from "./types.js";
 const SOURCE = "telo-analyzer";
 /**
@@ -392,11 +393,16 @@ export function validateReferences(resources, context) {
                 const ownerScope = (owningModule ? aliasesByModule?.get(owningModule) : undefined) ?? aliases;
                 const targetKind = ownerScope.resolveKind(anchorName);
                 if (!targetKind) {
+                    // Names the ALIAS, not the whole kind path: the alias is what an
+                    // author declares, and the usual cause is the import that binds it
+                    // having failed — which is reported on its own line.
+                    const aliasName = anchorName.slice(0, anchorName.indexOf("."));
                     diagnostics.push({
                         severity: DiagnosticSeverity.Error,
                         code: "SCHEMA_FROM_MISSING_PATH",
                         source: SOURCE,
-                        message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → cannot resolve alias '${anchorName}'`,
+                        message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → cannot resolve alias ` +
+                            `'${aliasName}' (in '${anchorName}'). Check the import that declares it.`,
                         data: { resource: resourceData, filePath, path: fieldPath },
                     });
                     return;
@@ -465,6 +471,42 @@ export function validateReferences(resources, context) {
                 const refVal = anchorVal;
                 if (typeof refVal.kind !== "string")
                     continue;
+                // THE INSTANCE FIRST, then the kind — the layering
+                // `x-telo-context-ref-from` already uses, and for the same reason. A
+                // kind that declares one fixed shape declares it on its definition; a
+                // kind whose shape is per instance declares it as a FIELD, and reading
+                // only the definition would type every instance against nothing. A
+                // `Durable.Await`'s `outputType:` is exactly the second: what a
+                // delivery carries is a property of that await and of no other, so a
+                // delivery naming it must be checked against the instance's own.
+                const target = typeof refVal.name === "string" ? byName.get(refVal.name) : undefined;
+                const perInstance = target === undefined
+                    ? undefined
+                    : navigateJsonPointer(target, jsonPointer);
+                if (perInstance !== undefined) {
+                    const instanceSchema = resolveTypeFieldToSchema(perInstance, resources);
+                    if (instanceSchema) {
+                        // CEL leaves become schema-shaped placeholders first. A payload is
+                        // overwhelmingly written as expressions over the call's inputs, so
+                        // validating it raw would report every one of them as a type
+                        // error — the check would fire only on the literal case, which is
+                        // the case nobody writes. What survives substitution is exactly
+                        // what is worth reporting: a missing required field, an unknown
+                        // property, a literal of the wrong type. The same treatment
+                        // `x-telo-value-schema-from` documents.
+                        const substituted = substituteCelFields(fieldValue, instanceSchema);
+                        for (const issue of registry.validateWithRefs(substituted, instanceSchema)) {
+                            diagnostics.push({
+                                severity: DiagnosticSeverity.Error,
+                                code: "DEPENDENT_SCHEMA_MISMATCH",
+                                source: SOURCE,
+                                message: `${resourceLabel}: '${concretePath}' does not match the schema '${refVal.name}' declares at '${jsonPointer}': ${issue}`,
+                                data: { resource: resourceData, filePath, path: concretePath },
+                            });
+                        }
+                        continue;
+                    }
+                }
                 const refResolvedKind = aliases.resolveKind(refVal.kind) ?? refVal.kind;
                 const refDef = registry.resolve(refVal.kind) ?? registry.resolve(refResolvedKind);
                 if (!refDef?.schema) {

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

@@ -0,0 +1,120 @@
+/**
+ * The strict half of the `x-telo-referrer-rules` accessor split
+ * (`validate-resource-rules.ts` / `validate-zone-slots.ts` precedent), plus the
+ * evaluation pass that runs a kind's rules against the resources referencing it.
+ *
+ * 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 a consumer's manifest, blaming an
+ * author for a defect in someone else's kind.
+ *
+ * A CONSUMER of the call graph with no traversal of its own: the referrers are
+ * `edgesTo` on the resource's node, exactly as the zone projection consumes the
+ * outgoing direction. What it hands back is plain findings; the caller pushes
+ * them.
+ *
+ * Ownership splits by whose defect it is, and lands one hop further out than for
+ * a resource rule. A VIOLATION belongs to the data — but the offending data is
+ * the REFERRER's, so the finding names that manifest and the analyzer reports it
+ * when the referrer is the entry's own. A rule that throws or exhausts its
+ * budget is a defect in the rule, anchored on the declaring definition.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+import type { ResourceManifest } from "@telorun/sdk";
+import { type ReferrerRule } from "./referrer-rule.js";
+export interface ReferrerRuleIssue {
+    code: "REFERRER_RULE_INVALID";
+    manifest: ResourceManifest;
+    path: string;
+    message: string;
+}
+/** One resource that reaches the resource under test, and where it does so. */
+export interface Referrer {
+    readonly manifest: ResourceManifest;
+    readonly kind: string;
+    readonly name: string;
+    /** Concrete path of the slot in the referrer (`mounts[1].mount`) — the anchor. */
+    readonly path: string;
+}
+/** One rule's verdict on one referrer. */
+export type ReferrerRuleFinding = {
+    kind: "violation";
+    rule: ReferrerRule;
+    referrer: Referrer;
+    message: string;
+} | {
+    kind: "skipped";
+    rule: ReferrerRule;
+    referrer: Referrer;
+    dynamicAt: string;
+} | {
+    kind: "failed";
+    rule: ReferrerRule;
+    referrer?: Referrer;
+    reason: string;
+} | {
+    kind: "over-budget";
+    rule: ReferrerRule;
+    referrer: Referrer;
+    elapsedMs: number;
+};
+/**
+ * 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 declare function validateReferrerRuleDeclarations(manifest: ResourceManifest): ReferrerRuleIssue[];
+/**
+ * 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 declare function evaluateReferrerRules(manifest: ResourceManifest, definitionSchema: unknown, referrers: readonly Referrer[], 
+/** 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: (filter: string, kind: string) => boolean): ReferrerRuleFinding[];
+/** 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 declare function referrerRuleExercised(rule: ReferrerRule, referrers: readonly Referrer[], kindMatches: (filter: string, kind: string) => boolean): boolean;
+/** Where a referrer-rule finding is reported, and how loudly. Plain data, so the
+ *  caller pushes it exactly as it does for the resource-rule reports. */
+export interface ReferrerRuleDiagnostic {
+    code: "REFERRER_RULE_VIOLATED" | "REFERRER_RULE_SKIPPED" | "REFERRER_RULE_INVALID" | "REFERRER_RULE_UNEXERCISED";
+    severity: "error" | "warning" | "information";
+    message: string;
+    /** The resource the finding is reported ON — the REFERRER 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.
+ *
+ * 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 declare function reportReferrerRules(manifest: ResourceManifest, definition: ResourceManifest | undefined, findings: readonly ReferrerRuleFinding[], 
+/** Whether the DECLARING definition is one of the entry's own modules. */
+declarationIsOurs: boolean): ReferrerRuleDiagnostic[];
+/** 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 declare function reportUnexercisedReferrerRule(definition: ResourceManifest, rule: ReferrerRule): ReferrerRuleDiagnostic;
+//# sourceMappingURL=validate-referrer-rules.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate-referrer-rules.d.ts","sourceRoot":"","sources":["../src/validate-referrer-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAI5B,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,+EAA+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,0CAA0C;AAC1C,MAAM,MAAM,mBAAmB,GAC3B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAMvF;;;;;;;;GAQG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,gBAAgB,GAAG,iBAAiB,EAAE,CA2EhG;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,gBAAgB,EAC1B,gBAAgB,EAAE,OAAO,EACzB,SAAS,EAAE,SAAS,QAAQ,EAAE;AAC9B;;mDAEmD;AACnD,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,GACrD,mBAAmB,EAAE,CAmEvB;AAED;;wBAEwB;AACxB,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,SAAS,QAAQ,EAAE,EAC9B,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,GACrD,OAAO,CAIT;AAED;yEACyE;AACzE,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;oEACgE;IAChE,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAKD;;;;;;;;GAQG;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,CAmE1B;AAED;;kDAEkD;AAClD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,gBAAgB,EAC5B,IAAI,EAAE,YAAY,GACjB,sBAAsB,CAexB"}