@telorun/analyzer 0.56.0 → 0.57.0

package/src/kernel-globals.ts

@@ -22,28 +22,43 @@ const SYSTEM_KINDS = new Set([
   "Telo.Abstract",
 ]);
 
+/** Kernel globals as ONE resource's declaring module sees them. */
+export interface KernelGlobalsIndex {
+  forResource(m: ResourceManifest): Record<string, any>;
+}
+
 /**
- * Build a typed JSON Schema describing the kernel globals available in the
- * given manifest set. Used to merge into `x-telo-context` schemas so that
- * chain-access validation recognises kernel globals without module authors
+ * Build the typed JSON Schema describing the kernel globals available to each
+ * resource in a manifest set. Used to merge into `x-telo-context` schemas so
+ * that chain-access validation recognises kernel globals without module authors
  * having to re-declare them.
  *
- * - `variables` / `secrets`: typed from the root module doc — prefer
- *   Telo.Application when present, otherwise fall back to Telo.Library.
- *   Applications are the root whose variables/secrets contract governs CEL
- *   in the outer module; Libraries are only relevant when the caller scoped
- *   the manifest list to a single library's file.
- * - `resources`: enumerates all non-system resource names
+ * `variables` / `secrets` / `ports` are typed **per declaring module**, because
+ * that is the contract the resource's CEL is evaluated against at runtime. An
+ * application analysis is flattened — `selectModuleManifestsForAnalysis` drops
+ * an imported library's module doc and carries its config blocks across as
+ * `metadata.moduleGlobals` instead — so a resource forwarded from a library is
+ * typed from that stamp, and everything else from the entry module's own doc
+ * (the only module doc left in the set).
+ *
+ * Typing every resource from the entry doc is what made a library's
+ * `variables.x` a hard error the library author could not act on, and — in the
+ * other direction — let a library read a variable it never declared whenever the
+ * app happened to declare that name.
+ *
+ * `resources` is NOT per module: it enumerates every non-system resource name in
+ * the set, and stays OPEN for a forwarded manifest (see `readModuleGlobals` for
+ * why a name list cannot be carried across the boundary honestly).
  */
-export function buildKernelGlobalsSchema(
+export function buildKernelGlobalsIndex(
   manifests: ResourceManifest[],
   /** Every resource a CEL read can name, including scope-declared ones (see
    *  `buildObservedStateIndex`). Kinds that declare a `status:` get a typed,
    *  closed `status` node; every other resource node stays open, so no flat read
    *  that passes today can start failing. */
   resources?: ReadonlyMap<string, { kind: string; status?: Record<string, any> }>,
-): Record<string, any> {
-  const moduleManifest =
+): KernelGlobalsIndex {
+  const entryDoc =
     (manifests.find((m) => m.kind === "Telo.Application") as
       | Record<string, any>
       | undefined) ??
@@ -51,6 +66,52 @@ export function buildKernelGlobalsSchema(
       | Record<string, any>
       | undefined);
 
+  const entrySchema = globalsSchema(entryDoc, buildResourcesSchema(manifests, resources));
+  const openResources = { type: "object", additionalProperties: true };
+  const byModule = new Map<string, Record<string, any>>();
+
+  return {
+    forResource(m: ResourceManifest): Record<string, any> {
+      const meta = m.metadata as { module?: string; moduleGlobals?: ModuleGlobals } | undefined;
+      const stamped = meta?.moduleGlobals;
+      if (!stamped) return entrySchema;
+      const key = meta?.module ?? "";
+      const cached = byModule.get(key);
+      if (cached) return cached;
+      const schema = globalsSchema(stamped, openResources);
+      byModule.set(key, schema);
+      return schema;
+    },
+  };
+}
+
+/** The blocks a declaring module contributes to its resources' CEL globals. */
+interface ModuleGlobals {
+  variables?: Record<string, unknown>;
+  secrets?: Record<string, unknown>;
+  ports?: Record<string, unknown>;
+}
+
+function globalsSchema(
+  doc: ModuleGlobals | Record<string, any> | undefined,
+  resourcesSchema: Record<string, any>,
+): Record<string, any> {
+  return {
+    type: "object",
+    properties: {
+      variables: buildSchemaMapSchema(doc?.variables as Record<string, any> | undefined),
+      secrets: buildSchemaMapSchema(doc?.secrets as Record<string, any> | undefined),
+      resources: resourcesSchema,
+      ports: buildPortsSchema(doc?.ports as Record<string, any> | undefined),
+    },
+  };
+}
+
+/** Every non-system resource name in the set, plus the scope-declared ones. */
+function buildResourcesSchema(
+  manifests: ResourceManifest[],
+  resources?: ReadonlyMap<string, { kind: string; status?: Record<string, any> }>,
+): Record<string, any> {
   const resourceProps: Record<string, any> = {};
   for (const m of manifests) {
     const name = m.metadata?.name as string | undefined;
@@ -76,19 +137,7 @@ export function buildKernelGlobalsSchema(
     applyObservedStateNode(resourceProps, key, entry.status);
   }
 
-  return {
-    type: "object",
-    properties: {
-      variables: buildSchemaMapSchema(moduleManifest?.variables),
-      secrets: buildSchemaMapSchema(moduleManifest?.secrets),
-      resources: {
-        type: "object",
-        properties: resourceProps,
-        additionalProperties: false,
-      },
-      ports: buildPortsSchema(moduleManifest?.ports),
-    },
-  };
+  return { type: "object", properties: resourceProps, additionalProperties: false };
 }
 
 /** Build the closed `ports` chain-access schema: each declared port is an

package/src/manifest-visitor.ts

@@ -1,5 +1,10 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
-import { isRefSentinel, isTaggedSentinel, walkCelExpressions } from "@telorun/templating";
+import {
+  isRefSentinel,
+  isTaggedSentinel,
+  walkCelExpressions,
+  type CelSurface,
+} from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 import {
@@ -114,6 +119,9 @@ export interface CelSiteEvent {
   contextSchema?: Record<string, any>;
   /** Scope of the matched context (e.g. `$.routes[*].handler`), if matched. */
   matchedScope?: string;
+  /** Where `expr` sits in the scalar at `path`, and the delimiters to restore
+   *  around a corrected expression. See `CelSurface`. */
+  surface: CelSurface;
 }
 
 export interface ManifestVisitor {
@@ -352,7 +360,7 @@ export function visitManifest(
 
     if (wantsCel) {
       const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
-      walkCelExpressions(r, "", (expr, path, engineName) => {
+      walkCelExpressions(r, "", (expr, path, engineName, surface) => {
         let contextSchema: Record<string, any> | undefined;
         let matchedScope: string | undefined;
         for (const ctx of contexts) {
@@ -362,7 +370,7 @@ export function visitManifest(
             break;
           }
         }
-        visitor.onCel!({ source: r, path, expr, engineName, contextSchema, matchedScope });
+        visitor.onCel!({ source: r, path, expr, engineName, contextSchema, matchedScope, surface });
       });
     }
 

package/src/module-file-claims.ts

@@ -0,0 +1,168 @@
+import {
+  defaultCustomTags,
+  defaultRegistry,
+  walkCelExpressions,
+  type TemplatingEngineRegistry,
+} from "@telorun/templating";
+import { PackageURL } from "packageurl-js";
+import { parseAllDocuments } from "yaml";
+import { selectorFromQualifiers, selectorKey, type ArtifactSelector } from "./artifact-selector.js";
+
+/**
+ * One module-relative file a manifest names, and the artifact layer it belongs
+ * to.
+ *
+ * The single answer to "why is this file in the payload", replacing two
+ * derivations that happened to agree: publish used to re-parse the manifest with
+ * PURL knowledge hardcoded into the CLI, and any second vocabulary — a tag that
+ * embeds a file, say — would have had to be added there by hand. Here the
+ * knowledge sits with whoever owns the syntax: a controller candidate is read by
+ * this module, and a tagged value is read by the engine that owns its tag, via
+ * `TemplatingEngine.fileClaims`. Publish maps role to layer and recognises
+ * neither.
+ *
+ * Deliberately NOT hung off `analyze()`. That pass runs over a flattened,
+ * import-inclusive manifest set, so its claims would mix in imported libraries'
+ * files — whose paths are relative to *their* module and must never join this
+ * artifact — and it would make packaging, today derivable offline from manifest
+ * text, a product of resolving the whole import graph. This is per-module by
+ * construction and needs nothing but the text.
+ *
+ * Browser-safe, like the rest of the analyzer: parsing and string work only, no
+ * filesystem. Whether a claimed file EXISTS is a separate question, asked by the
+ * Node-side caller that has a directory to look in.
+ */
+interface ClaimBase {
+  /** Module-root-relative POSIX path — relative to the directory holding
+   *  `telo.yaml`, never to the file the claim was written in. Publish inlines
+   *  every `include:` partial into the published `telo.yaml`, so a
+   *  per-file-relative path would change meaning in the artifact. */
+  readonly path: string;
+  /** Where the claim came from, for diagnostics: the PURL, or `!<tag>` and the
+   *  path of the value that carried it. */
+  readonly origin: string;
+}
+
+/**
+ * A **discriminated union**, not one shape with optional fields: a controller
+ * layer is one per selector and carries sibling patterns, and an assets layer is
+ * neither. Optional fields on a single shape put the consumer one `!` away from
+ * a crash inside `selectorKey` with no useful message, and let a producer emit a
+ * controller claim with no selector that nothing would reject.
+ */
+export type ModuleFileClaim =
+  | (ClaimBase & {
+      readonly role: "controller";
+      readonly selector: ArtifactSelector;
+      /** Extra payload patterns that belong in the same layer as this claim —
+       *  `.gitignore`-style globs over the selected files, matched by the
+       *  caller, which is the side that knows what was selected. */
+      readonly siblings: readonly string[];
+    })
+  | (ClaimBase & { readonly role: "assets" });
+
+/** `pkg:telo/local/<format>?path=…` — the bundled-controller delivery mode.
+ *  Anything else (`pkg:npm`, `pkg:cargo`) fetches from its own ecosystem and
+ *  contributes no layer. */
+const BUNDLED_TYPE = "telo";
+const BUNDLED_NAMESPACE = "local";
+
+/** Qualifier naming extra files that belong in a controller's layer — what an
+ *  entry point loads but the manifest cannot otherwise see (a `.wasm` beside its
+ *  glue, a native library opened at runtime). */
+const SIBLINGS_QUALIFIER = "siblings";
+
+/** Normalize a `path=` / sibling value to the manifest-relative POSIX form the
+ *  file selector returns, so membership is a string comparison. */
+function normalizeRelative(value: string): string {
+  return value.replace(/^\.\//, "").replace(/\\/g, "/");
+}
+
+/** Bundled-controller claims from one document's `controllers:` list. */
+function controllerClaims(json: unknown): ModuleFileClaim[] {
+  const candidates = (json as { controllers?: unknown } | null)?.controllers;
+  if (!Array.isArray(candidates)) return [];
+  const claims: ModuleFileClaim[] = [];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string") continue;
+    let parsed: PackageURL;
+    try {
+      parsed = PackageURL.fromString(candidate);
+    } catch {
+      // Not a parseable PURL — claim collection is not the place to reject it;
+      // the analyzer's own validation and the controller loader both report it
+      // with better context.
+      continue;
+    }
+    if (parsed.type !== BUNDLED_TYPE || parsed.namespace !== BUNDLED_NAMESPACE) continue;
+    const entry = parsed.qualifiers?.path;
+    if (typeof entry !== "string" || entry === "") continue;
+    claims.push({
+      role: "controller",
+      path: normalizeRelative(entry),
+      selector: selectorFromQualifiers(parsed.name, parsed.qualifiers, `controller "${candidate}"`),
+      siblings: String(parsed.qualifiers?.[SIBLINGS_QUALIFIER] ?? "")
+        .split(",")
+        .map((p) => p.trim())
+        .filter((p) => p !== ""),
+      origin: candidate,
+    });
+  }
+  return claims;
+}
+
+/** Claims contributed by tagged values, asked of the engine that owns each tag.
+ *  The walk reaches every tagged scalar in the document, so an engine that
+ *  embeds files is discovered wherever its tag was written.
+ *
+ *  The layer role is assigned HERE, not by the engine: an engine reports what it
+ *  embeds, and which layer that belongs in is this module's vocabulary. A file a
+ *  tag embeds is read only when the resource holding it is created, so `assets`
+ *  — the lazily-fetched layer — is what it is. */
+function taggedClaims(json: unknown, registry: TemplatingEngineRegistry): ModuleFileClaim[] {
+  const claims: ModuleFileClaim[] = [];
+  walkCelExpressions(json, "", (source, path, engineName) => {
+    const engine = registry.get(engineName);
+    for (const claim of engine?.fileClaims?.(source) ?? []) {
+      claims.push({ role: "assets", path: claim.path, origin: `!${engineName} at '${path}'` });
+    }
+  });
+  return claims;
+}
+
+/** Identity of a claim for de-duplication: the same file claimed twice by two
+ *  resources is one file in one layer. Role and selector are part of it because
+ *  a file two controller candidates both claim is genuinely copied into each of
+ *  their layers — dropping one would leave a platform's layer short a file it
+ *  declared it needs. */
+function claimKey(claim: ModuleFileClaim): string {
+  const selector = claim.role === "controller" ? selectorKey(claim.selector) : "";
+  return `${claim.role}\0${selector}\0${claim.path}`;
+}
+
+/**
+ * Every module-relative file the manifest names, from every syntax that can name
+ * one.
+ *
+ * `manifestText` is one module's `telo.yaml`. Publish passes the text it is
+ * about to ship — i.e. after `include:` partials have been inlined — but the
+ * answer does not depend on that: claims are root-relative, so collecting them
+ * before or after inlining gives the same set.
+ */
+export function collectModuleFileClaims(
+  manifestText: string,
+  registry: TemplatingEngineRegistry = defaultRegistry(),
+): ModuleFileClaim[] {
+  const seen = new Set<string>();
+  const claims: ModuleFileClaim[] = [];
+  for (const doc of parseAllDocuments(manifestText, { customTags: defaultCustomTags() })) {
+    const json = doc.toJSON() as unknown;
+    for (const claim of [...controllerClaims(json), ...taggedClaims(json, registry)]) {
+      const key = claimKey(claim);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      claims.push(claim);
+    }
+  }
+  return claims;
+}

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),