@telorun/analyzer 0.56.1 → 0.57.0

package/src/schema-compat.ts

@@ -1,6 +1,13 @@
 import AjvModule from "ajv";
 import addFormats from "ajv-formats";
-import { isRefSentinel, isTaggedSentinel, ManifestRootSchema, normalizeRefSlots } from "@telorun/templating";
+import {
+  INCLUDE_BYTES_ENGINE,
+  INCLUDE_ENGINE_NAMES,
+  isRefSentinel,
+  isTaggedSentinel,
+  ManifestRootSchema,
+  normalizeRefSlots,
+} from "@telorun/templating";
 import { binaryKeyword, isBinarySlot } from "./binary-slot.js";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;
@@ -564,6 +571,17 @@ export function substituteCelFields(
   if (isRefSentinel(data)) {
     return data;
   }
+  // A file embed's type is a CONSTANT of the tag, not a function of the slot:
+  // `!include-text` always produces a string and `!include-bytes` always
+  // produces bytes. Collapsing them to a slot-shaped placeholder like a CEL
+  // expression would make every slot accept both, so a byte embed at a
+  // `type: string` field passed `telo check` and failed at resource creation —
+  // and the reverse (text at an `x-telo-binary` slot) did too. Substituting the
+  // real type lets AJV and the `x-telo-binary` keyword reject both directions
+  // statically, with no new diagnostic code.
+  if (isTaggedSentinel(data) && INCLUDE_ENGINE_NAMES.has(data.engine)) {
+    return data.engine === INCLUDE_BYTES_ENGINE ? new Uint8Array() : "";
+  }
   if (isTaggedSentinel(data)) {
     mark();
     return celPlaceholderForSchema(resolved);

package/src/types.ts

@@ -31,6 +31,36 @@ export type PositionIndex = Map<string, Range>;
 
 /** LSP-compatible Diagnostic shape. range is optional because parsed YAML may not carry
  *  position info when only the parsed object (not raw text) is available. */
+/** A mechanically applicable repair, carried unchanged from whatever produced
+ *  it (a templating engine, a kind-name suggestion) to every consumer: CLI
+ *  JSON, IDE CodeActions, an agent applying it without re-deriving it from
+ *  prose.
+ *
+ *  `replacement` is the **whole** value at the diagnostic's `path`, corrected —
+ *  never a fragment — so applying it needs no knowledge of the language inside.
+ *  There is deliberately no sub-range: carrying one beside a whole-value
+ *  replacement gives the field two readings, and the minimal-edit reading
+ *  (splice `replacement` at `range`) produces garbage because the two measure
+ *  different strings.
+ *
+ *  One shape rather than one per producer: a `fix` field beside a
+ *  `suggestedKind` field beside a CEL-specific one would leave every host
+ *  wiring a separate action path for what is the same gesture. */
+export interface DiagnosticFix {
+  readonly replacement: string;
+}
+
+/** The `data` stamp diagnostics carry. Loose by design — passes bolt their own
+ *  keys on — but the fields every consumer reads are declared. */
+export interface DiagnosticData {
+  resource?: { kind: string; name: string };
+  filePath?: string;
+  /** Dotted path of the offending value within its resource. */
+  path?: string;
+  fix?: DiagnosticFix;
+  [key: string]: unknown;
+}
+
 export interface AnalysisDiagnostic {
   range?: Range;
   severity?: DiagnosticSeverity;
@@ -42,6 +72,13 @@ export interface AnalysisDiagnostic {
   data?: unknown;
 }
 
+/** Single reader for a diagnostic's fix, so no consumer re-derives the shape
+ *  by hand-casting `data`. */
+export function diagnosticFix(d: AnalysisDiagnostic): DiagnosticFix | undefined {
+  const fix = (d.data as DiagnosticData | undefined)?.fix;
+  return fix && typeof fix.replacement === "string" ? fix : undefined;
+}
+
 export interface ManifestSource {
   supports(url: string): boolean;
   read(url: string): Promise<{ text: string; source: string }>;

package/src/validate-include-placement.ts

@@ -0,0 +1,70 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { INCLUDE_ENGINE_NAMES, walkCelExpressions } from "@telorun/templating";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Docs that are never instantiated as resources.
+ *
+ * `Telo.Application` / `Telo.Library` are module declarations, and `Telo.Import`
+ * is a dependency edge — none of the three reaches a controller's `create()`.
+ * `Telo.Definition` and `Telo.Abstract` are deliberately absent: a definition's
+ * template body (`resources:` / `invoke:` / `run:` / `provide:`) DOES become
+ * resources, so an embed there resolves normally.
+ */
+const NEVER_INSTANTIATED: ReadonlySet<string> = new Set([
+  "Telo.Application",
+  "Telo.Library",
+  "Telo.Import",
+]);
+
+/**
+ * An `!include-text` / `!include-bytes` in a doc that is never instantiated is
+ * never read.
+ *
+ * The two tags resolve when the resource owning them is created — deferred so
+ * that loading a manifest does not pull payload layers, which is the property
+ * the artifact spec protects by giving `telo.yaml` a layer of its own. The cost
+ * of that choice is this dead spot: a doc with no `create()` has no moment at
+ * which the file would be read, so the value stays an unresolved marker and
+ * whatever reads it sees a sentinel object instead of the file's contents.
+ *
+ * Nothing else would report it. There is no controller to validate against a
+ * schema and no runtime consumer to fail, so the manifest ships looking correct
+ * — exactly the silent-no-op failure mode that makes a descriptive field worth
+ * checking. Hence an error at the one place that can see it.
+ *
+ * Deliberately narrow: it reports only where the argument is complete ("this
+ * doc is never instantiated"). A JSON-Schema region *inside* a definition —
+ * `schema:`, `inputType:` — is equally unreadable, but that is a general
+ * question about tags in schema metadata rather than one about these two, and
+ * no pass answers it for any tag today.
+ */
+export function validateIncludePlacement(manifests: ResourceManifest[]): AnalysisDiagnostic[] {
+  const out: AnalysisDiagnostic[] = [];
+  for (const manifest of manifests) {
+    if (!NEVER_INSTANTIATED.has(manifest.kind)) continue;
+    const name = (manifest.metadata as { name?: string } | undefined)?.name;
+    const filePath = (manifest.metadata as { source?: string } | undefined)?.source;
+    walkCelExpressions(manifest, "", (source, path, engineName) => {
+      if (!INCLUDE_ENGINE_NAMES.has(engineName)) return;
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "INCLUDE_OUTSIDE_RESOURCE",
+        source: SOURCE,
+        message:
+          `${manifest.kind}${name ? `/${name}` : ""}: \`!${engineName} ${source}\` at '${path}' is ` +
+          `never read — a ${manifest.kind} doc is not instantiated, and a file embed is resolved ` +
+          `when the resource holding it is created. Move it onto the resource that needs the ` +
+          `file, or read the file at runtime with Fs.File.`,
+        data: {
+          resource: { kind: manifest.kind, name: name ?? "" },
+          filePath,
+          path,
+        },
+      });
+    });
+  }
+  return out;
+}

package/src/validate-throws-coverage.ts

@@ -238,6 +238,7 @@ function checkCatchesCoverage(
   filePath: string | undefined,
   arrayPath: string,
   env: Environment,
+  handler: { kind: string; name?: string } | null,
 ): AnalysisDiagnostic[] {
   const diagnostics: AnalysisDiagnostic[] = [];
   const declaredCodes = new Set(union.codes.keys());
@@ -288,16 +289,20 @@ function checkCatchesCoverage(
   }
 
   if (!hasCatchAll) {
-    for (const code of declaredCodes) {
-      if (!covered.has(code)) {
-        diagnostics.push({
-          severity: DiagnosticSeverity.Error,
-          code: "UNCOVERED_THROW_CODE",
-          source: SOURCE,
-          message: `Code '${code}' is declared by the handler but not covered by any catches: entry (no matching \`when:\` and no catch-all).`,
-          data: { resource, filePath, path: arrayPath },
-        });
-      }
+    // One diagnostic per block, not per code: every uncovered code sits at the
+    // same `catches:` array, and one catch-all answers all of them at once. A
+    // diagnostic each repeated the same location and the same fix N times.
+    const uncovered = [...declaredCodes].filter((c) => !covered.has(c)).sort();
+    if (uncovered.length > 0) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "UNCOVERED_THROW_CODE",
+        source: SOURCE,
+        message:
+          `handler ${handler?.name ? `\`!ref ${handler.name}\`` : `\`${handler?.kind ?? "?"}\``} can throw ${uncovered.length} code${uncovered.length === 1 ? "" : "s"} that no catches: entry handles: ${uncovered.map((c) => `'${c}'`).join(", ")}. ` +
+          `Give each a matching \`when:\` (e.g. \`when: !cel "error.code == '${uncovered[0]}'"\`), or add a catch-all entry — one with no \`when:\`, placed last.`,
+        data: { resource, filePath, path: arrayPath, uncovered },
+      });
     }
   }
 
@@ -552,7 +557,7 @@ export function validateThrowsCoverage(
         const handlerRef = resolveHandlerRef(siblingData[catchesFor]);
         const union = handlerRefUnion(handlerRef, manifests, resolveCtx, scopeResolver);
         diagnostics.push(
-          ...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env),
+          ...checkCatchesCoverage(entries, union, resource, filePath, arrayPath, env, handlerRef),
         );
         diagnostics.push(
           ...checkTypedErrorData(entries, union, resource, filePath, arrayPath, env),