@telorun/analyzer 0.71.0 → 0.72.0

package/src/schema-error-report.ts

@@ -53,10 +53,42 @@ const UNION_KEYWORDS = new Set(["anyOf", "oneOf"]);
  *  further in. These are what make a branch implausible. */
 const SHAPE_KEYWORDS = new Set(["required", "type", "additionalProperties", "enum", "const"]);
 
+/** Keywords that exist to DISCRIMINATE, so a mismatch is positive evidence that
+ *  the value is not this branch — at any depth, not only at the union node.
+ *
+ *  Depth is otherwise the tiebreak, and it inverts exactly here: a branch that
+ *  agreed on the discriminator and failed one constraint reported at the union
+ *  node loses to every branch that disagreed about the discriminator one level
+ *  in. That is how a `capability: Telo.Service` document declaring a forbidden
+ *  key was reported as `/capability must be equal to constant` — naming neither
+ *  the key at fault nor a branch the value could ever have been. */
+const DISCRIMINATOR_KEYWORDS = new Set(["const", "enum"]);
+
+/** RFC 6901 escapes: `~1` is a literal `/` in the key, `~0` a literal `~`.
+ *  Decoded wherever a segment is shown or matched, because encoded it is not the
+ *  key the manifest holds — a content map (`application/json`) anchors nowhere
+ *  and reads wrong in the sentence. `~0` is expanded LAST, or `~01` would decode
+ *  to `/` instead of the literal `~1` it encodes. */
+function unescapeSegment(part: string): string {
+  return part.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/** The whole pointer, segment by segment, for prose that quotes it verbatim. */
+function unescapePointer(pointer: string): string {
+  return pointer
+    .split("/")
+    .map((segment, i) => (i === 0 ? segment : unescapeSegment(segment)))
+    .join("/");
+}
+
 /* ------------------------------------------------------------------ prose */
 
 export function formatSingleError(err: AjvErrorLike): string {
-  const p = err.instancePath || "/";
+  // Unescaped for the same reason the path is: a reader acting on this sentence
+  // needs the key the manifest holds (`application/json`), not its RFC 6901
+  // encoding. Reporting one form in `path` and the other in `message` made one
+  // diagnostic disagree with itself.
+  const p = unescapePointer(err.instancePath || "") || "/";
   const params = err.params ?? {};
   switch (err.keyword) {
     case "additionalProperties":
@@ -67,6 +99,16 @@ export function formatSingleError(err: AjvErrorLike): string {
       return `${p} ${err.message ?? "is invalid"} (${(params.allowedValues as unknown[])?.join(" | ")})`;
     case "type":
       return `${p} must be ${params.type}${describeActual(err)}`;
+    // A `false` schema at a property is how a branch forbids a key it otherwise
+    // declares. AJV's own text ("boolean schema is false") describes the schema
+    // rather than the value, and the path is the only part a reader can act on.
+    case "false schema":
+      return `${p} is not allowed here`;
+    // `not:` says a forbidden shape matched, and AJV reports nothing about the
+    // inner schema — so the honest message says where, and no more. A branch
+    // that wants to name the key writes `properties: { <key>: false }` instead.
+    case "not":
+      return `${p} matches a shape that is not allowed here`;
     default:
       return `${p} ${err.message ?? "is invalid"}`;
   }
@@ -130,11 +172,13 @@ function describeAlternatives(errors: AjvErrorLike[], unionInstancePath: string)
 }
 
 /** Is this branch a plausible reading of the value — does it accept the value's
- *  shape at the union node itself, and only disagree further in? */
+ *  shape at the union node itself, and agree with every discriminator it pins? */
 function isPlausible(errors: AjvErrorLike[], unionInstancePath: string): boolean {
-  return !errors.some(
-    (e) => (e.instancePath || "") === unionInstancePath && SHAPE_KEYWORDS.has(e.keyword ?? ""),
-  );
+  return !errors.some((e) => {
+    const keyword = e.keyword ?? "";
+    if (DISCRIMINATOR_KEYWORDS.has(keyword)) return true;
+    return (e.instancePath || "") === unionInstancePath && SHAPE_KEYWORDS.has(keyword);
+  });
 }
 
 /**
@@ -392,7 +436,7 @@ export function ajvErrorToPath(err: AjvErrorLike): string {
   let result = "";
   for (const part of parts) {
     if (/^\d+$/.test(part)) result += `[${part}]`;
-    else result += result ? `.${part}` : part;
+    else result += result ? `.${unescapeSegment(part)}` : unescapeSegment(part);
   }
   if (err.keyword === "required" && err.params?.missingProperty) {
     const missing = err.params.missingProperty as string;

package/src/schema-keywords.ts

@@ -386,7 +386,10 @@ export const TELO_SCHEMA_ANNOTATIONS: Record<
   },
   "x-telo-catches-for": {
     title: "Catches for",
-    description: "Names the field whose failures this branch list handles.",
+    description:
+      "Whose failures this catch list renders: a sibling field naming the handler, " +
+      "or the EMPTY string for everything this resource drives — a scope-level list, " +
+      "which owes coverage of nothing itself and answers for every site it encloses.",
     type: "string",
   },
 };

package/src/schema-walk.ts

@@ -9,6 +9,8 @@
  * scope rule is consumed by the IDE, which must not pull the pass in behind it.
  */
 import { MANIFEST_SCHEMA_URI, ManifestRootSchema } from "./manifest-schemas.js";
+import { readRefSlot, type RefSlot } from "./ref-slot.js";
+import { readStepSlot, type StepSlot } from "./step-slot.js";
 
 /** Resolve a local `$ref` (only `#/$defs/<name>` form) against the root schema.
  *  Non-refs and unresolved refs pass through unchanged. */
@@ -142,3 +144,57 @@ export function walkStepArray(
     }
   });
 }
+/** A slot through which a resource drives another. */
+export type DrivenSlot =
+  | { kind: "step"; slot: StepSlot; data: unknown[]; path: string }
+  | { kind: "ref"; slot: RefSlot; data: unknown; path: string };
+
+/**
+ * Every slot of one resource through which it drives another, schema and data in
+ * tandem.
+ *
+ * One traversal with two consumers — the inherited union here, and the catch
+ * scope enclosure in `validate-throws-coverage.ts` — because both ask the same
+ * structural question and two copies would eventually disagree about where the
+ * walk stops. It terminates on the manifest's own depth, and it stops AT a step
+ * slot (that traversal owns everything below it, `try`/`catch` subtraction
+ * included) and AT a reference slot (a resolved ref is a leaf, `{kind, name}`,
+ * with nothing beneath it to visit).
+ */
+export function forEachDrivenSlot(
+  schema: unknown,
+  data: unknown,
+  visit: (slot: DrivenSlot) => void,
+  path = "",
+): void {
+  if (!schema || typeof schema !== "object" || data === undefined || data === null) return;
+  const node = schema as Record<string, any>;
+
+  const stepSlot = readStepSlot(node);
+  if (stepSlot) {
+    if (Array.isArray(data)) visit({ kind: "step", slot: stepSlot, data, path });
+    return;
+  }
+
+  const refSlot = readRefSlot(node);
+  if (refSlot) {
+    visit({ kind: "ref", slot: refSlot, data, path });
+    return;
+  }
+
+  const props = node.properties as Record<string, any> | undefined;
+  if (props && typeof data === "object" && !Array.isArray(data)) {
+    const obj = data as Record<string, unknown>;
+    for (const [key, propSchema] of Object.entries(props)) {
+      if (obj[key] === undefined) continue;
+      forEachDrivenSlot(propSchema, obj[key], visit, path ? `${path}.${key}` : key);
+    }
+  }
+
+  if (node.items && Array.isArray(data)) {
+    for (const [i, item] of data.entries()) {
+      forEachDrivenSlot(node.items, item, visit, `${path}[${i}]`);
+    }
+  }
+}
+

package/src/telo-version.ts

@@ -6,4 +6,4 @@
 // written against, and every kernel in every language reports the same scale.
 
 /** The surface generation this analyzer implements. */
-export const TELO_SURFACE_VERSION = "0.87.0";
+export const TELO_SURFACE_VERSION = "0.88.0";

package/src/types.ts

@@ -11,6 +11,19 @@ export const DiagnosticSeverity = {
 } as const;
 export type DiagnosticSeverity = (typeof DiagnosticSeverity)[keyof typeof DiagnosticSeverity];
 
+/** Matches LSP DiagnosticTag values exactly.
+ *  https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#diagnosticTag
+ *
+ *  Declared whole rather than trimmed to what Telo emits today, for the reason
+ *  the severity ladder above is: it is someone else's closed vocabulary, and a
+ *  partial copy of one is what drifts. `Unnecessary` (rendered faded) has an
+ *  obvious future consumer in the unused-declaration checks. */
+export const DiagnosticTag = {
+  Unnecessary: 1,
+  Deprecated: 2,
+} as const;
+export type DiagnosticTag = (typeof DiagnosticTag)[keyof typeof DiagnosticTag];
+
 /** Default entry-point filename when a directory is given instead of a file. */
 export const DEFAULT_MANIFEST_FILENAME = "telo.yaml";
 
@@ -70,6 +83,11 @@ export interface AnalysisDiagnostic {
   /** e.g. "telo-analyzer" */
   source?: string;
   message: string;
+  /** What KIND of thing this is, orthogonal to how loudly it asks to be dealt
+   *  with. A deprecation is warning-grade *and* a deprecation; severity alone
+   *  can only say the first, which is why an editor renders a deprecated symbol
+   *  struck through rather than merely yellow. */
+  tags?: DiagnosticTag[];
   /** Telo-specific extras such as { resource: { kind, name }, path } */
   data?: unknown;
 }

package/src/validate-identifier-names.ts

@@ -1,8 +1,13 @@
-import type { ResourceManifest } from "@telorun/sdk";
+import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
 
-import type { AliasResolver } from "./alias-resolver.js";
+import {
+  moduleScopedDefResolver,
+  type AliasResolver,
+  type ModuleScopes,
+} from "./alias-resolver.js";
 import type { CallGraph } from "./call-graph.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
+import { inheritedCapability, type DefResolver } from "./extends-resolution.js";
 import {
   TYPE_LEVEL_DOC_KINDS,
   checkName,
@@ -44,8 +49,10 @@ export function validateIdentifierNames(
   aliases: AliasResolver,
   rootModules: Set<string>,
   graph: CallGraph,
+  scopes: ModuleScopes,
 ): AnalysisDiagnostic[] {
   const out: AnalysisDiagnostic[] = [];
+  const resolveDef = moduleScopedDefResolver<ResourceDefinition>(registry, aliases, scopes);
 
   for (const manifest of manifests) {
     const metadata = manifest.metadata as Record<string, unknown> | undefined;
@@ -65,7 +72,7 @@ export function validateIdentifierNames(
     const ownModule = metadata?.module as string | undefined;
     if (ownModule && !rootModules.has(ownModule)) continue;
 
-    const level = levelFor(manifest, registry, aliases);
+    const level = levelFor(manifest, resolveDef, ownModule);
     push(out, checkName(name, level, surfaceFor(manifest.kind)), {
       kind: manifest.kind,
       name,
@@ -126,20 +133,32 @@ export function validateIdentifierNames(
  * a resource. Capability-driven rather than by kind name, so no resource kind
  * is hardcoded here.
  *
+ * **The capability is the INHERITED one**, not the leaf declaration. Capability
+ * is inherited and immutable along `extends` — a kind omits it to take its
+ * ancestor's — so reading the leaf answers `undefined` for every kind that does,
+ * and the fallback then calls a type a value. That is not hypothetical: it is
+ * exactly `Type.JsonSchema`, a pure alias of the built-in (`extends:
+ * Telo.JsonSchema`, no `capability:` of its own), so a shape declared through
+ * the deprecated spelling was reported as miscased while the identical
+ * declaration written as `kind: Telo.JsonSchema` was not. Renaming on that
+ * report is worse than the warning: `extends:` between two named shapes is not a
+ * reference slot, so the inheritance edge does not move with the name.
+ *
  * An unresolvable kind falls back to value level — the honest default, since
  * `UNDEFINED_KIND` already reports the real problem and guessing type level
  * would stack a case error on top of it.
  */
 function levelFor(
   manifest: ResourceManifest,
-  registry: DefinitionRegistry,
-  aliases: AliasResolver,
+  resolveDef: DefResolver & { in(kind: string, module?: string): ResourceDefinition | undefined },
+  ownModule: string | undefined,
 ): NameLevel {
   if (TYPE_LEVEL_DOC_KINDS.has(manifest.kind as string)) return "type";
-  // The root resolver is the right one unconditionally: every manifest
-  // reaching here belongs to a root module, the others having been skipped.
-  const canonical = aliases.resolveKind(manifest.kind as string) ?? (manifest.kind as string);
-  return registry.resolve(canonical)?.capability === "Telo.Type" ? "type" : "value";
+  // The top-level lookup is in the module that WROTE the `kind:` — a root one,
+  // the others having been skipped above — while the chain walk re-scopes at
+  // every hop, since an `extends` alias belongs to the file declaring it.
+  const def = resolveDef.in(manifest.kind as string, ownModule);
+  return inheritedCapability(def, resolveDef) === "Telo.Type" ? "type" : "value";
 }
 
 /** The noun phrase a diagnostic uses as its subject. */

package/src/validate-ref-slots.ts

@@ -38,7 +38,9 @@ export interface RefSlotIssue {
     | "X_TELO_REF_MISSING_USE"
     | "X_TELO_REF_MISSING_KIND"
     | "X_TELO_REF_USE_CONFLICT"
-    | "X_TELO_REF_DYNAMIC_SELECTOR";
+    | "X_TELO_REF_DYNAMIC_SELECTOR"
+    | "X_TELO_REF_UNKNOWN_KEY"
+    | "X_TELO_REF_INVALID_THROWS_THROUGH";
   /** The definition (schema issues) or resource (selector issues) at fault. */
   manifest: ResourceManifest;
   /** Schema path of the slot (schema issues) or concrete value path of the
@@ -140,9 +142,47 @@ function checkAnnotation(
     }
   }
 
+  // `throwsThrough` is read as `=== true`, so anything else is silently absent —
+  // and absent means the declaring resource's catch scope stops enclosing what
+  // it holds, so every route under it starts reporting UNCOVERED_THROW_CODE with
+  // nothing naming the cause. The same failure `X_TELO_REF_INVALID_USE` exists
+  // to prevent, one key over.
+  if (obj.throwsThrough !== undefined && typeof obj.throwsThrough !== "boolean") {
+    issues.push({
+      code: "X_TELO_REF_INVALID_THROWS_THROUGH",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares 'throwsThrough: ${JSON.stringify(obj.throwsThrough)}', ` +
+        `which is not a boolean. Only 'true' declares that throws from this slot's target ` +
+        `surface through the declaring resource; anything else reads as absent, which ` +
+        `silently stops its catch list from enclosing what it holds.`,
+    });
+  }
+
+  // Closed, for the reason the token sets are: a misspelled key is indexed by
+  // nothing and read by nothing, so it validates, ships, and does exactly what
+  // omitting it would.
+  for (const key of Object.keys(obj)) {
+    if (REF_ANNOTATION_KEYS.has(key)) continue;
+    issues.push({
+      code: "X_TELO_REF_UNKNOWN_KEY",
+      manifest,
+      path,
+      message:
+        `x-telo-ref at '${path}' declares unrecognized key '${key}'. Known keys: ` +
+        `${[...REF_ANNOTATION_KEYS].sort().join(", ")}. An unrecognized key is read by nothing, ` +
+        `so it has exactly the effect of leaving it out.`,
+    });
+  }
+
   return declaredUses(use);
 }
 
+/** Every key the structured `x-telo-ref` form accepts — the write side of
+ *  `readRefSlot`'s read side. Adding one belongs in both. */
+const REF_ANNOTATION_KEYS = new Set(["kind", "use", "inputs", "throwsThrough"]);
+
 /** True when a node is a reference slot: it carries `x-telo-ref` directly or on
  *  an `anyOf`/`oneOf` branch. */
 function carriesRefAnnotation(obj: Record<string, unknown>): boolean {

package/src/validate-references.ts

@@ -562,14 +562,44 @@ export function validateReferences(
 
           for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
             if (fieldValue == null) continue;
-            const issues = registry.validateWithRefs(fieldValue, subSchema as Record<string, any>);
+            // CEL leaves become schema-shaped placeholders first, exactly as the
+            // sibling-ref branch below does and for the same reason: a slot
+            // anchored at a shared value-shape is overwhelmingly written as
+            // expressions, so validating it raw reports every one of them as a
+            // type error and the check fires only on the literal case nobody
+            // writes. Omitting it here made one annotation mean two different
+            // things depending on which branch resolved it — a `when:` typed
+            // `boolean` accepted a `!cel` at a route's inline slot and rejected
+            // the identical expression at a slot anchored on the carrier that
+            // declares that very shape.
+            const substituted = substituteCelFields(
+              fieldValue,
+              subSchema as Record<string, any>,
+            );
+            // Anchored at the offending node INSIDE the value, not at the slot:
+            // a `returns:` list is an array of entries, and reporting every one
+            // of its issues on the `returns:` line puts three diagnostics on one
+            // line and none on the entry that is wrong.
+            const issues = registry.validateResourceConfig(
+              substituted,
+              subSchema as Record<string, any>,
+            );
             for (const issue of issues) {
               diagnostics.push({
                 severity: DiagnosticSeverity.Error,
                 code: "DEPENDENT_SCHEMA_MISMATCH",
                 source: SOURCE,
-                message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-                data: { resource: resourceData, filePath, path: concretePath },
+                message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue.message}`,
+                data: {
+                  resource: resourceData,
+                  filePath,
+                  // An index-first sub-path (`[0].content`) joins with no dot.
+                  path: !issue.path
+                    ? concretePath
+                    : issue.path.startsWith("[")
+                      ? `${concretePath}${issue.path}`
+                      : `${concretePath}.${issue.path}`,
+                },
               });
             }
           }