@telorun/analyzer 0.62.1 → 0.63.0

package/dist/resolve-zone-containment.js

@@ -0,0 +1,212 @@
+import { propertySchemas, resolveLocalRef } from "./manifest-navigation.js";
+import { isStepSlot } from "./step-slot.js";
+import { readProvidesZone } from "./zone-slot.js";
+const moduleOf = (node) => node.manifest.metadata?.module;
+/** The schema node at a field-map path, following `[]` into `items`, `{}` into
+ *  `additionalProperties` and local `$defs` refs. Same navigation the projection
+ *  performs — a slot's annotations live wherever this lands. */
+function schemaNodeAt(rootSchema, slotPath) {
+    if (!rootSchema)
+        return undefined;
+    let current = rootSchema;
+    for (const segment of slotPath.split(".")) {
+        if (!current)
+            return undefined;
+        const bare = segment.replace(/(\[\]|\{\})+$/g, "");
+        let next = propertySchemas(current).find(([k]) => k === bare)?.[1];
+        for (const marker of segment.slice(bare.length).match(/\[\]|\{\}/g) ?? []) {
+            next = resolveLocalRef(marker === "[]"
+                ? next?.items
+                : next?.additionalProperties, rootSchema);
+            if (!next || typeof next !== "object")
+                return undefined;
+        }
+        current = resolveLocalRef(next, rootSchema);
+    }
+    return current;
+}
+/**
+ * Does a zone's lifetime extend through this edge?
+ *
+ * EVERY member of `use` must be `call`. This is the landed reduction, and its
+ * asymmetry with the propagation rule is deliberate: a set says several
+ * relations hold at once, so a slot declaring `[call, detached]` really does
+ * detach on some dispatch, and a detached dispatch is never inside the caller's
+ * zone. An edge whose `use` could not be read extends nothing either — the
+ * conservative direction HERE, since over-reporting containment would invent
+ * failures inside regions that are correct.
+ */
+function extendsZone(edge) {
+    return edge.use.length > 0 && !edge.unresolved && edge.use.every((u) => u === "call");
+}
+/** Uses on an edge that leave the region, for the boundary record. */
+function escapingUses(edge) {
+    return edge.use.filter((u) => u !== "call" && u !== "dependency" && u !== "schema");
+}
+/** Walk down from one entry edge, collecting what the zone reaches. */
+function collect(graph, entries, contents, boundaries) {
+    const queue = [...entries];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (contents.has(current.node.id))
+            continue;
+        contents.set(current.node.id, { node: current.node, via: current.via });
+        // A resource's own step nodes are part of whatever region reaches the
+        // resource: a step is where a check anchors (`the retry at
+        // importAll/fetch`), and its outgoing edge is the dispatch a rule judges.
+        const stepNodes = current.node.type === "resource" ? graph.steps(current.node.id) : [];
+        for (const step of stepNodes) {
+            if (contents.has(step.id))
+                continue;
+            queue.push({
+                node: step,
+                via: [...current.via, step.name ? `step '${step.name}'` : step.path],
+            });
+        }
+        const owner = current.node.type === "resource"
+            ? current.node
+            : graph.nodes.get(current.node.owner);
+        for (const edge of graph.edgesFrom(current.node.id)) {
+            if (edge.use.every((u) => u === "dependency" || u === "schema"))
+                continue;
+            const target = edge.to ? graph.nodes.get(edge.to) : undefined;
+            if (!extendsZone(edge)) {
+                if (owner && escapingUses(edge).length > 0) {
+                    boundaries.push({
+                        edge,
+                        from: owner,
+                        via: current.via,
+                        escaping: escapingUses(edge),
+                    });
+                }
+                continue;
+            }
+            if (!target)
+                continue;
+            queue.push({
+                node: target,
+                via: [...current.via, `${edge.slot} → ${edge.toName}`],
+            });
+        }
+    }
+}
+/**
+ * Every region in the graph opened by a slot declaring `attribute`.
+ *
+ * The provider itself is NOT in `contents` — a zone constrains what runs inside
+ * its body, not the resource that establishes it. A transaction's own
+ * `connection:` dependency is outside the region it opens, and a rule that
+ * treated the provider as contained would report the provider against its own
+ * constraint.
+ */
+export function findZoneRegions(graph, resolveDef, attribute) {
+    const regions = [];
+    for (const node of graph.nodes.values()) {
+        if (node.type !== "resource")
+            continue;
+        const def = resolveDef(node.kind, moduleOf(node));
+        const rootSchema = def?.schema;
+        if (!rootSchema)
+            continue;
+        // The providing slots of this kind, found by walking its own declared
+        // properties rather than by knowing any kind's field names.
+        for (const [slot, slotSchema] of providingSlots(rootSchema)) {
+            const provides = readProvidesZone(slotSchema);
+            const reason = provides?.attributes[attribute];
+            if (!provides || typeof reason !== "string")
+                continue;
+            const contents = new Map();
+            const boundaries = [];
+            // Shape one: the slot carries a step array natively. Its steps are the
+            // body, and they are owned by this resource, so they are found by path
+            // rather than by an edge.
+            if (isStepSlot(slotSchema)) {
+                const entries = graph
+                    .steps(node.id)
+                    .filter((step) => step.array === slot || step.array.startsWith(`${slot}[`))
+                    .map((step) => ({
+                    node: step,
+                    via: [step.name ? `step '${step.name}'` : step.path],
+                }));
+                collect(graph, entries, contents, boundaries);
+            }
+            else {
+                // Shape two: the slot references an executable. Its edges are the body.
+                // Entered regardless of the slot's OWN use — a providing slot
+                // establishes its zone before the enclosing lifetime terminates on that
+                // use, which is what lets a detached durable body both shed every
+                // enclosing zone and open its own.
+                const entries = graph
+                    .edgesFrom(node.id)
+                    .filter((edge) => edge.slot === slot && edge.to)
+                    .map((edge) => ({
+                    node: graph.nodes.get(edge.to),
+                    via: [`${slot} → ${edge.toName}`],
+                }))
+                    .filter((entry) => entry.node !== undefined);
+                collect(graph, entries, contents, boundaries);
+            }
+            regions.push({
+                attribute,
+                reason,
+                provider: node,
+                slot,
+                attributes: provides.attributes,
+                contents,
+                boundaries,
+            });
+        }
+    }
+    return regions;
+}
+/** Field-map paths of every slot in a kind's schema carrying a provides-zone
+ *  annotation, with the schema node at each. Walks properties, array items and
+ *  `additionalProperties`, resolving local `$ref`s — the paths the call graph's
+ *  own edges are keyed by, so a slot found here matches an edge's `slot`. */
+function providingSlots(rootSchema) {
+    const found = [];
+    const seen = new Set();
+    const walk = (schema, path) => {
+        const node = resolveLocalRef(schema, rootSchema);
+        if (!node || typeof node !== "object" || seen.has(node))
+            return;
+        seen.add(node);
+        if (path && readProvidesZone(node))
+            found.push([path, node]);
+        for (const [key, child] of propertySchemas(node)) {
+            const childPath = path ? `${path}.${key}` : key;
+            walk(child, childPath);
+            // A slot's zone annotation may sit on the ARRAY (`steps`) or on its item
+            // (`routes[].handler`); both are real field-map paths.
+            const items = resolveLocalRef(child?.items, rootSchema);
+            if (items)
+                walk(items, `${childPath}[]`);
+            const additional = resolveLocalRef(child?.additionalProperties, rootSchema);
+            if (additional)
+                walk(additional, `${childPath}{}`);
+        }
+    };
+    walk(rootSchema, "");
+    return found;
+}
+/** Convenience for a consumer that only wants membership: every node id inside
+ *  any region opened by `attribute`, mapped to the region that contains it. */
+export function containmentIndex(regions) {
+    const index = new Map();
+    for (const region of regions) {
+        for (const id of region.contents.keys()) {
+            if (!index.has(id))
+                index.set(id, region);
+        }
+    }
+    return index;
+}
+/** The manifests a region's contents belong to — what a diagnostic anchors on. */
+export function regionManifests(region) {
+    const out = [];
+    for (const { node } of region.contents.values()) {
+        if (node.type === "resource")
+            out.push(node.manifest);
+    }
+    return out;
+}

package/dist/resolve-zone-requirements.d.ts

@@ -35,6 +35,11 @@ export interface ZoneRequirementSpec {
      *  check compares against `exports.resources`. */
     correlationName?: string;
     reason?: string;
+    /** Attributes the satisfying zone must declare. Carried across the export
+     *  boundary with the rest of the requirement: a consumer discharging a
+     *  library's open requirement must meet the same guarantee the library's own
+     *  internals would have. */
+    attributes?: string[];
     /** Label of the requiring resource (`sql.Command 'charge'`). */
     origin: string;
     /** Resource names on the propagation path so far, origin first. */

package/dist/resolve-zone-requirements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-zone-requirements.d.ts","sourceRoot":"","sources":["../src/resolve-zone-requirements.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolve-zone-requirements.d.ts","sourceRoot":"","sources":["../src/resolve-zone-requirements.ts"],"names":[],"mappings":"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"}

package/dist/resolve-zone-requirements.js

@@ -232,6 +232,7 @@ export function projectZoneRequirements(args) {
             if (!bucket.some((r) => `${r.zone}\0${r.correlation ?? ""}` === req.key)) {
                 bucket.push({
                     zone: req.zone,
+                    ...(req.attributes.length > 0 ? { attributes: req.attributes } : {}),
                     correlation: req.correlation,
                     correlationLabel: req.correlationLabel,
                     correlationName: req.correlationName,
@@ -255,16 +256,44 @@ export function projectZoneRequirements(args) {
             // site. Checked BEFORE termination, so a terminating provider slot
             // (a detached durable body) still discharges its own zone.
             const callerDef = resolveDef(caller.kind, moduleOf(caller));
-            const slotSchema = schemaNodeAt(callerDef?.schema, edge.slot);
+            // WHICH slot establishes the zone depends on the body's SHAPE, and both
+            // shapes are real. A ref body annotates the slot the edge itself names
+            // (`Sql.Transaction.steps`, holding a `!ref` to an executable). A NATIVE
+            // body annotates the step ARRAY, while the edge comes from a step inside
+            // it and names that step's own `invoke:` — so looking only at `edge.slot`
+            // finds no annotation and the enclosing zone never discharges anything.
+            // Handling one shape would make every requirement inside a natively-bodied
+            // zone unsatisfiable, which is exactly what a durable workflow's body is.
+            const bodySlot = from.type === "step" ? from.array.replace(/\[\d+\].*$/, "") : edge.slot;
+            const slotSchema = schemaNodeAt(callerDef?.schema, bodySlot);
             const provides = readProvidesZone(slotSchema);
             if (provides && callerDef && req.accepted.has(canonicalOf(callerDef))) {
+                // A native body's annotation sits on the array, whose enclosing object
+                // IS the resource root — so its correlation pointer anchors there,
+                // rather than at the step item the edge happens to come from.
                 const providerKey = provides.key
-                    ? resolveProviderKey(caller, edge, provides.key, resolveName)
+                    ? from.type === "step"
+                        ? resolveStaticKey(caller, [provides.key], resolveName)
+                        : resolveProviderKey(caller, edge, provides.key, resolveName)
                     : undefined;
                 const discharged = req.correlation === undefined ||
                     (providerKey !== undefined && correlationIdOf(providerKey) === req.correlation);
-                if (discharged)
+                if (discharged) {
+                    // The zone is the right KIND but may not make the promise the
+                    // requirement is built on. Reported here rather than at the providing
+                    // module, because this is the only point where both halves are in
+                    // hand: the requirement's demanded attributes and the slot that would
+                    // satisfy it. The requirement still discharges — the zone IS open, so
+                    // reporting it unsatisfied as well would name the same defect twice
+                    // with opposite words.
+                    const missing = req.attributes.filter((a) => !(a in provides.attributes));
+                    if (missing.length > 0) {
+                        emit(DiagnosticSeverity.Error, "ZONE_ATTRIBUTE_MISSING", edge, caller, req, via, `reaches a ${canonicalOf(callerDef)} zone that does not declare ` +
+                            `${missing.join(", ")}, so the guarantee this requirement is built on ` +
+                            `does not hold inside it`);
+                    }
                     continue;
+                }
             }
             // A dynamic selector is already a hard diagnostic (validate-ref-slots);
             // zones do not re-report it — and must not propagate through a use they
@@ -352,14 +381,24 @@ export function projectZoneRequirements(args) {
             continue;
         const def = resolveDef(node.kind, meta?.module);
         const schema = def?.schema;
-        if (!def || !schema?.properties)
+        if (!def || !schema)
             continue;
-        for (const [field, propSchema] of Object.entries(schema.properties)) {
-            const requires = readRequiresZone(propSchema);
+        // A requirement at the SCHEMA ROOT is unconditional: every instance of the
+        // kind must be inside the zone, whatever it is configured with. A parking
+        // kind is exactly that shape — it has no option that turns the requirement
+        // on — and a field-level annotation would have to be attached to some
+        // arbitrary property and would then read "…when you set this one".
+        const slots = [[schema, undefined]];
+        for (const [field, propSchema] of Object.entries((schema.properties ?? {}))) {
+            slots.push([propSchema, field]);
+        }
+        for (const [slotSchema, field] of slots) {
+            const requires = readRequiresZone(slotSchema);
             if (!requires)
                 continue;
-            if (node.manifest[field] === undefined)
+            if (field !== undefined && node.manifest[field] === undefined) {
                 continue;
+            }
             const zoneDef = resolveDef(requires.zone, def.metadata.module);
             if (!zoneDef)
                 continue; // ZONE_PROVIDER_UNRESOLVED is reported at registration
@@ -368,6 +407,7 @@ export function projectZoneRequirements(args) {
             const req = {
                 zone,
                 accepted: acceptedFor(zone),
+                attributes: requires.attributes,
                 correlation: target ? correlationIdOf(target) : undefined,
                 correlationLabel: target ? labelOf(target) : undefined,
                 correlationName: target?.name,
@@ -396,6 +436,7 @@ export function projectZoneRequirements(args) {
                 const req = {
                     zone: spec.zone,
                     accepted: zoneDef ? acceptedFor(spec.zone) : new Set([spec.zone]),
+                    attributes: spec.attributes ?? [],
                     correlation: spec.correlation,
                     correlationLabel: spec.correlationLabel,
                     correlationName: spec.correlationName,

package/dist/resource-rule.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The single reader for `x-telo-resource-rules` — a kind declaring, as data,
+ * relationships between the fields of one resource that JSON Schema cannot
+ * state: an index naming a column its table does not declare, a foreign key
+ * whose two sides differ in length, a rename whose source is still declared.
+ *
+ * The predicate is CEL over `self` (the whole resource) and `this` (the element
+ * under test), so correlating two collections is a comprehension closure rather
+ * than a path language with wildcard bindings to design. `in:` names the
+ * collection to iterate and IS the diagnostic anchor: iterating what the pointer
+ * names is what makes a reported path exist by construction.
+ *
+ * Vocabulary borrowed from `Telo.JsonSchema.rules` — `condition` true when the
+ * rule HOLDS, the subject bound as `this`, plus `code` and `message` — because
+ * two CEL rule vocabularies with opposite polarity is a trap an author falls
+ * into once per rule. The two mechanisms stay separate: a `Telo.JsonSchema` rule
+ * runs at dispatch against a value, this one at `telo check` against a manifest.
+ *
+ * Lenient by design, the `ref-slot.ts` precedent: anything unreadable here reads
+ * as absent, and `validate-resource-rules.ts` is the strict half that reports it.
+ *
+ * Browser-safe: no Node built-ins.
+ */
+export declare const RESOURCE_RULES_ANNOTATION = "x-telo-resource-rules";
+export type ResourceRuleSeverity = "error" | "warning";
+export interface ResourceRule {
+    /** JSON Pointer to the collection to iterate. Absent = the whole-resource
+     *  form, which reports at the resource rather than at an element. */
+    readonly in?: string;
+    /** CEL source. TRUE when the rule holds. */
+    readonly condition: string;
+    /** The rule's own name, carried in `data.rule`. Never a diagnostic code —
+     *  every violation reports under the analyzer-owned envelope. */
+    readonly code: string;
+    readonly message: string;
+    readonly severity: ResourceRuleSeverity;
+    /** Position in the annotation array — the anchor for a declaration defect. */
+    readonly index: number;
+}
+/** One element a rule is evaluated against. */
+export interface RuleSubject {
+    /** Dotted/bracketed path from the resource root, for `data.path`. */
+    readonly path: string;
+    readonly value: unknown;
+    /** Present when the collection is a map: the entry's key. */
+    readonly key?: string;
+}
+/** A precompiled `!cel` node keeps its author-written text on `source`; a plain
+ *  string is taken verbatim so a rule reads the same however the loader was
+ *  configured (a round-trip view runs with `compile` off). */
+export declare function celSourceOf(value: unknown): string | undefined;
+/** The annotation exactly as written, for the strict half. `undefined` when the
+ *  kind declares none; a non-array is returned as-is so the shape can be
+ *  reported rather than silently skipped. */
+export declare function readRawResourceRules(schema: unknown): unknown;
+/** Every rule this kind declares that is well-formed enough to run. */
+export declare function readResourceRules(schema: unknown): ResourceRule[];
+/** Split a JSON Pointer into its unescaped segments. `/` alone is the root. */
+export declare function pointerSegments(pointer: string): string[] | undefined;
+/** Navigate a pointer within a value, stopping at anything that is not a plain
+ *  container. Returns `undefined` for a pointer that does not resolve — which a
+ *  resource legitimately produces by omitting an optional collection. */
+export declare function resolvePointer(value: unknown, pointer: string): unknown;
+/** Path prefix for a pointer, in the dotted/bracketed spelling diagnostics use
+ *  (`foreignKeys[0].references`), so `data.path` is one grammar throughout. */
+export declare function pointerToPath(pointer: string): string;
+/**
+ * The elements a rule iterates. An array yields one subject per item, a map one
+ * per entry with its key bound; a collection that is absent yields none, which
+ * is a rule that had nothing to say rather than a rule that failed.
+ *
+ * A scalar at the pointer is `undefined` — not an empty list — because that is a
+ * declaration defect the strict half reports, and an empty list would hide it.
+ */
+export declare function resolveRuleSubjects(config: unknown, pointer: string): RuleSubject[] | undefined;
+/**
+ * Path of the first CEL leaf inside a value, or `undefined` when every leaf is
+ * literal. A rule reading an expression would be evaluating a placeholder, so
+ * the subject is skipped — and the skip is reported, never silent.
+ *
+ * Stops at nested inline `{ kind }` declarations for the reason every other walk
+ * does: that CEL belongs to the nested kind, evaluated in its own scope.
+ */
+export declare function findDynamicLeaf(value: unknown, base?: string): string | undefined;
+/**
+ * The nodes a condition actually READS, resolved against the resource and the
+ * element under test — the input to the dynamic-leaf check.
+ *
+ * Scanning the whole subject instead would make the check useless in exactly
+ * the shape it matters most: a resource-wide rule takes the whole resource as
+ * its subject, so one unrelated `!cel` anywhere (a `version:` read from
+ * `module.version`, which is the conventional spelling) would switch off every
+ * such rule. Chains are the same primitive the binding-order derivation uses:
+ * parsed, never lexed, so a name inside a string literal reads nothing.
+ *
+ * A chain stops at a computed index (`INDEX_SEGMENT`): what it selects is not
+ * known statically, so the node reached so far is what gets checked — the
+ * over-approximating direction, which errs toward skipping rather than toward
+ * evaluating a placeholder.
+ */
+export declare function readNodes(chains: readonly (readonly string[])[], 
+/** The bindings in scope, by name — `self`/`this`/`key` for a resource rule,
+ *  `self`/`referrer` for a referrer rule. A chain rooted at a name that is not
+ *  bound reads nothing. */
+roots: Record<string, unknown>): unknown[];
+//# sourceMappingURL=resource-rule.d.ts.map

package/dist/resource-rule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-rule.d.ts","sourceRoot":"","sources":["../src/resource-rule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B;yEACqE;IACrE,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;qEACiE;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,+CAA+C;AAC/C,MAAM,WAAW,WAAW;IAC1B,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAeD;;8DAE8D;AAC9D,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI9D;AAED;;6CAE6C;AAC7C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAG7D;AAED,uEAAuE;AACvE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,YAAY,EAAE,CA0BjE;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAOrE;AAED;;yEAEyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAiBvE;AAED;+EAC+E;AAC/E,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,GACd,WAAW,EAAE,GAAG,SAAS,CAe3B;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,SAAK,GAAG,MAAM,GAAG,SAAS,CAiB7E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE;AACtC;;2BAE2B;AAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,EAAE,CAqBX"}