@telorun/analyzer 0.61.0 → 0.62.1

package/src/analyzer.ts

@@ -8,7 +8,7 @@ import {
   plainChainOf,
   type CelSurface,
 } from "@telorun/templating";
-import type { DiagnosticFix } from "./types.js";
+import type { DiagnosticData, DiagnosticFix } from "./types.js";
 import {
   AliasResolver,
   moduleScopedDefResolver,
@@ -89,17 +89,19 @@ import {
   BINDINGS_ANNOTATION,
   bindingContextProperties,
   bindingPathChain,
-  CEL_RESERVED_WORDS,
   findBindingSites,
   resolveBindingOrder,
   schemaAtChain,
   type BindingSites,
 } from "./cel-bindings.js";
+import { CEL_RESERVED_WORDS, checkName } from "./identifier-name.js";
+import { validateIdentifierNames } from "./validate-identifier-names.js";
 import { validateExtends } from "./validate-extends.js";
 import { validateLogging } from "./validate-logging.js";
 import { validateModuleArtifact } from "./validate-module-artifact.js";
 import { validateIncludePlacement } from "./validate-include-placement.js";
 import { validateModuleMetadata } from "./validate-module-metadata.js";
+import { validateRequires } from "./validate-requires.js";
 import { validateBaseMapping } from "./validate-base-mapping.js";
 import { validateInvocationContract } from "./validate-invocation-contract.js";
 import { collectStepInputIssues } from "./validate-step-inputs.js";
@@ -1029,6 +1031,86 @@ export interface StaticAnalyzerOptions {
   celHandlers?: CelHandlers;
 }
 
+/**
+ * Files belonging to a module this runtime declared itself unable to read.
+ *
+ * Attribution is by FILE rather than by resource identity, the same choice
+ * `remapMigratedPaths` makes and for the same reason: a diagnostic carries at
+ * most two routing facts and routinely only one, so indexing by resource would
+ * leave every diagnostic without `data.resource` unreachable.
+ *
+ * **A module NAME is not a graph-unique key.** Names are module-scoped, so two
+ * libraries may both be called `Store` — CLAUDE.md names this exact hazard for
+ * migration provenance ("two libraries declaring a Store would share one
+ * bucket"), where the answer is to narrow or not remap at all. Same answer here:
+ * the gated doc's own `metadata.source` is always suppressed, and a name is used
+ * to reach its `include:` partials only when that name identifies exactly ONE
+ * module doc in the set. Where it does not, the partials keep their diagnostics
+ * rather than risk silencing an unrelated library's — a stray extra diagnostic is
+ * a far cheaper failure than a hidden one.
+ *
+ * A module doc with no `source` contributes nothing — suppressing on a guess
+ * would hide diagnostics belonging to files nobody named.
+ */
+function filesOfUnreadableModules(
+  manifests: ResourceManifest[],
+  requiresDiagnostics: AnalysisDiagnostic[],
+): ReadonlySet<string> {
+  const files = new Set<string>();
+  const gatedNames = new Set<string>();
+
+  for (const d of requiresDiagnostics) {
+    if (d.code !== "MODULE_REQUIRES_NEWER_RUNTIME") continue;
+    const data = d.data as DiagnosticData | undefined;
+    // The gated document itself, addressed by the file it was declared in.
+    if (typeof data?.filePath === "string" && data.filePath) files.add(data.filePath);
+    const name = data?.resource?.name;
+    if (typeof name === "string") gatedNames.add(name);
+  }
+  if (files.size === 0 && gatedNames.size === 0) return files;
+
+  // How many module docs answer to each gated name — the ambiguity test.
+  const docsPerName = new Map<string, number>();
+  for (const m of manifests) {
+    if (m.kind !== "Telo.Application" && m.kind !== "Telo.Library") continue;
+    const name = (m.metadata as { name?: string } | undefined)?.name;
+    if (typeof name === "string" && gatedNames.has(name)) {
+      docsPerName.set(name, (docsPerName.get(name) ?? 0) + 1);
+    }
+  }
+
+  for (const m of manifests) {
+    const metadata = (m.metadata ?? {}) as Record<string, unknown>;
+    const owner = metadata.module;
+    if (typeof owner !== "string" || !gatedNames.has(owner)) continue;
+    if (docsPerName.get(owner) !== 1) continue; // ambiguous — do not guess
+    if (typeof metadata.source === "string" && metadata.source) files.add(metadata.source);
+  }
+  return files;
+}
+
+/**
+ * Drop every diagnostic anchored in a file whose module this runtime cannot
+ * read, except the gate diagnostic itself.
+ *
+ * A filter rather than a guard on each validator: threading "skip this module"
+ * through thirty validators would make each one responsible for a rule none of
+ * them owns, and a validator added later would silently opt out of it. A
+ * diagnostic with no `filePath` is KEPT — suppression must never be the default
+ * for something it cannot attribute.
+ */
+function suppressUnreadableModuleDiagnostics(
+  diagnostics: AnalysisDiagnostic[],
+  unreadableFiles: ReadonlySet<string>,
+): AnalysisDiagnostic[] {
+  if (unreadableFiles.size === 0) return diagnostics;
+  return diagnostics.filter((d) => {
+    if (d.code === "MODULE_REQUIRES_NEWER_RUNTIME") return true;
+    const filePath = (d.data as DiagnosticData | undefined)?.filePath;
+    return typeof filePath !== "string" || !unreadableFiles.has(filePath);
+  });
+}
+
 export class StaticAnalyzer {
   private readonly celEnv: Environment;
 
@@ -1527,6 +1609,25 @@ export class StaticAnalyzer {
         });
       }
     }
+    // Declared runtime requirements, FIRST among the validators and suppressing
+    // the rest for any module this runtime cannot read. A module that adopted
+    // newer syntax also produces the vocabulary errors that syntax causes here —
+    // an unknown `use` token, an object where a zone annotation expects a
+    // pointer, an `additionalProperties` violation against a kernel-owned
+    // schema — every one of which is true and blames the module's author for a
+    // version skew. Reporting them beside the gate would bury the one message
+    // that names the actual cause and the actual fix.
+    const requiresDiagnostics = validateRequires(allManifests as unknown as ResourceManifest[], {
+      teloVersion: options?.teloVersion,
+      hostVersions: options?.hostVersions,
+      entryModules: rootModules,
+    });
+    const unreadableFiles = filesOfUnreadableModules(
+      allManifests as unknown as ResourceManifest[],
+      requiresDiagnostics,
+    );
+    diagnostics.push(...requiresDiagnostics);
+
     if (!options?.skipValidation) {
       diagnostics.push(
         ...validateSchemaTypeRefs(allManifests, defs, aliases, aliasesByModule, rootModules),
@@ -1543,6 +1644,19 @@ export class StaticAnalyzer {
       // these fields, which is precisely why they need a check: a mistyped one
       // has no runtime failure mode that would ever surface it.
       diagnostics.push(...validateModuleMetadata(allManifests, defs, aliases));
+      // Every author-written name. Telo has no lexer, so a name's shape is
+      // unchecked where it is declared and its consequences land at whichever
+      // CEL site reads it — for a hyphen, sometimes as silent arithmetic. Takes
+      // the call graph for step names rather than re-walking the step arrays.
+      diagnostics.push(
+        ...validateIdentifierNames(
+          allManifests as unknown as ResourceManifest[],
+          defs,
+          aliases,
+          rootModules,
+          getCallGraph(),
+        ),
+      );
       // A file embed resolves at resource creation, so one written on a doc that
       // is never instantiated is read by nothing and would ship silently.
       diagnostics.push(...validateIncludePlacement(allManifests));
@@ -1556,7 +1670,7 @@ export class StaticAnalyzer {
     // normalisation have already run above; that's all downstream
     // consumers (prepare, init loop) require.
     if (options?.skipValidation) {
-      return diagnostics;
+      return suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles);
     }
 
     // Build a name→manifest map for looking up referenced resources
@@ -2109,14 +2223,33 @@ export class StaticAnalyzer {
 
               for (const name of Object.keys(declared)) {
                 const shadows = inScope.has(name);
-                if (!shadows && !keywords.has(name)) continue;
+                if (shadows || keywords.has(name)) {
+                  diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "BINDING_NAME_RESERVED",
+                    source: SOURCE,
+                    message: shadows
+                      ? `${m.kind}/${bindingsName}: binding '${name}' shadows a variable already in scope here (${[...inScope].sort().join(", ")}). Rename the binding — a scope variable always wins, so this one would never be read.`
+                      : `${m.kind}/${bindingsName}: binding '${name}' is a CEL keyword, so no expression can read it as a reference. Rename the binding.`,
+                    data: {
+                      resource: resourceRef,
+                      filePath: bindingsFile,
+                      path: `${celBindingSites.field}.${name}`,
+                    },
+                  });
+                  continue;
+                }
+                // A binding is read by bare name, so it lives in the same
+                // identifier space as a resource or step name and breaks the
+                // same way. The keyword tier is unreachable here — the check
+                // above owns it, and can also say what is being shadowed.
+                const violation = checkName(name, "value", "binding name");
+                if (!violation) continue;
                 diagnostics.push({
-                  severity: DiagnosticSeverity.Error,
-                  code: "BINDING_NAME_RESERVED",
+                  severity: violation.severity,
+                  code: violation.code,
                   source: SOURCE,
-                  message: shadows
-                    ? `${m.kind}/${bindingsName}: binding '${name}' shadows a variable already in scope here (${[...inScope].sort().join(", ")}). Rename the binding — a scope variable always wins, so this one would never be read.`
-                    : `${m.kind}/${bindingsName}: binding '${name}' is a CEL keyword, so no expression can read it as a reference. Rename the binding.`,
+                  message: `${m.kind}/${bindingsName}: ${violation.message}`,
                   data: {
                     resource: resourceRef,
                     filePath: bindingsFile,
@@ -2514,7 +2647,10 @@ export class StaticAnalyzer {
 
     // Reroute diagnostics on synthetic (inline-extracted) resources back to
     // the chain root so position-index lookups land on the parent doc.
-    return rewriteSyntheticOrigins(diagnostics, allManifests);
+    return rewriteSyntheticOrigins(
+      suppressUnreadableModuleDiagnostics(diagnostics, unreadableFiles),
+      allManifests,
+    );
   }
 
   analyzeErrors(

package/src/builtins.ts

@@ -1,6 +1,29 @@
-import { manifestFragment } from "./manifest-schemas.js";
+import { manifestFragment, manifestFragmentRef, withSchemaFragments } from "./manifest-schemas.js";
+
+/** A slot holding author-written JSON Schema. Localized and hoisted by
+ *  {@link withSchemaFragments} on the enclosing schema, which is what makes the
+ *  `#/$defs` pointer resolve inside whatever AJV compiles.
+ *
+ *  `KindSchema` and `JsonSchema7` share a body; the name is the discriminator
+ *  the IDE reads off the `x-telo-fragment` stamp to decide whether the
+ *  `x-telo-*` vocabulary belongs here. A kind's own `schema:` is where it does;
+ *  a `status:` block or an `inputType:` describes plain data, where it does not. */
+const kindSchemaSlot = {
+  title: "Schema",
+  description: "Configuration this kind accepts, as JSON Schema plus `x-telo-*` annotations.",
+  $ref: manifestFragmentRef("KindSchema"),
+};
+
+/** Observed state a kind reports while running, as a data schema. `required:` is
+ *  rejected separately by `validateObservedStateDeclarations`, which can say why
+ *  and what to write instead. */
+const observedStateSlot = {
+  title: "Observed state",
+  description:
+    "What a resource of this kind reports while running, published at `resources.<name>.status.<field>`.",
+  $ref: manifestFragmentRef("JsonSchema7"),
+};
 import type { ResourceDefinition } from "@telorun/sdk";
-import { OBSERVED_STATE_SCHEMA } from "./validate-observed-state.js";
 
 /** Descriptive provenance a module declares about itself, shared by
  *  `Telo.Application` and `Telo.Library`.
@@ -24,6 +47,32 @@ const PROVENANCE_METADATA = {
   documentation: { type: "string" },
 };
 
+/** The declared runtime requirements block, shared by `Telo.Application` and
+ *  `Telo.Library` — the two module kinds, whose schemas are otherwise
+ *  independent and would drift.
+ *
+ *  **Deliberately says only "these are objects", and nothing about the values.**
+ *  The grammar belongs to `requires-block.ts`, which is the single reader, and
+ *  every rule that matters — `^` and `~` refused, a bare version refused, bounds
+ *  that must not exclude each other, an upper bound that must name a version that
+ *  exists — needs a parse and a comparison, not a schema. Adding `type: "string"`
+ *  here bought nothing and cost a duplicate: `telo: 80` then produced BOTH a
+ *  `SCHEMA_VIOLATION` and a `REQUIRES_INVALID` for one node, one of them phrased
+ *  by a layer that does not know what the value is for.
+ *
+ *  Left open at both tiers for the same reason. An unrecognized axis is reported
+ *  by the reader with the vocabulary it knows — a far better message than AJV's —
+ *  and, critically, is SUPPRESSED while the `telo` requirement is itself unmet,
+ *  since an older runtime not knowing a newer axis is a consequence of the
+ *  version skew rather than a second defect. AJV cannot express that ordering. */
+const REQUIRES_SCHEMA = {
+  type: "object",
+  properties: {
+    host: { type: "object" },
+  },
+  additionalProperties: true,
+};
+
 /** Author-declared subset of `files:` that ships in the artifact's lazily
  *  materialized `assets` layer. Optional: an unclaimed file joins the `common`
  *  layer, which is pulled alongside any controller layer, so omitting this costs
@@ -278,13 +327,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
     // kernel registers this controller directly at boot, before any lazy
     // resolution — it states truthfully who provides it.
     controllers: [{ runtime: "kernel", entry: "Telo.JsonSchema" }],
-    schema: {
+    schema: withSchemaFragments({
       type: "object",
       properties: {
         schema: {
           title: "Schema",
           description: "JSON Schema definition for the declared data type.",
-          type: "object",
+          $ref: manifestFragmentRef("JsonSchema7"),
         },
         extends: {
           title: "Extends",
@@ -319,13 +368,13 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
       },
       required: ["schema"],
       additionalProperties: false,
-    },
+    }),
   },
   {
     kind: "Telo.Definition",
     metadata: { name: "Abstract", module: "Telo" },
     capability: "Telo.Template",
-    schema: {
+    schema: withSchemaFragments({
       type: "object",
       properties: {
         kind: { type: "string" },
@@ -336,15 +385,15 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           additionalProperties: true,
         },
         capability: { type: "string" },
-        schema: { type: "object", additionalProperties: true },
-        status: OBSERVED_STATE_SCHEMA,
+        schema: kindSchemaSlot,
+        status: observedStateSlot,
       },
       required: ["metadata"],
       // Telo.Abstract is an extension point by design — it must accept forward-compatible
       // fields (e.g. inputType/outputType from the typed-abstracts plan) without requiring
       // the analyzer to enumerate them here.
       additionalProperties: true,
-    },
+    }),
   },
   {
     kind: "Telo.Definition",
@@ -362,11 +411,17 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
     // matching how Run.Sequence steps factor dispatch from data. The dispatch
     // entry-point (`invoke` / `provide` / `run`) determines how `inputs`/`result`
     // are interpreted at runtime. See analyzer/nodejs/plans/template-internal-cel-validation.md.
-    schema: {
+    schema: withSchemaFragments({
       type: "object",
       additionalProperties: true,
       properties: {
-        status: OBSERVED_STATE_SCHEMA,
+        // The kind's own configuration contract. Declared as a slot for the
+        // first time here: it was reachable only as an unnamed extra property,
+        // so nothing could say what belonged in it — no completion inside a
+        // `schema:` block, and a misspelled keyword surviving to a runtime
+        // failure that named a different field.
+        schema: kindSchemaSlot,
+        status: observedStateSlot,
         resources: {
           type: "array",
           items: {
@@ -536,7 +591,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           },
         },
       },
-    },
+    }),
   },
   {
     kind: "Telo.Definition",
@@ -787,6 +842,9 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
         // CLI flag — so a level derived from the host environment goes through a
         // `variables:` entry read with `!cel`. See kernel/specs/logging.md §12.
         logging: ROOT_LOGGING_SCHEMA,
+        // The runtime range this module is verified against. See
+        // `analyzer/nodejs/src/requires-block.ts`.
+        requires: REQUIRES_SCHEMA,
       },
       required: ["metadata"],
       additionalProperties: false,
@@ -877,6 +935,9 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           },
           additionalProperties: true,
         },
+        // The runtime range this module is verified against. See
+        // `analyzer/nodejs/src/requires-block.ts`.
+        requires: REQUIRES_SCHEMA,
       },
       required: ["metadata"],
       additionalProperties: false,

package/src/cel-bindings.ts

@@ -20,34 +20,9 @@ export interface BindingSites {
   scopeNames: Set<string>;
 }
 
-/**
- * CEL keywords. A binding named after one is unreachable — `true` lexes as a
- * literal, `in` as an operator — so it is reserved alongside the scope names,
- * which turns silence into a diagnostic.
- */
-export const CEL_RESERVED_WORDS: readonly string[] = [
-  "as",
-  "break",
-  "const",
-  "continue",
-  "else",
-  "false",
-  "for",
-  "function",
-  "if",
-  "import",
-  "in",
-  "let",
-  "loop",
-  "namespace",
-  "null",
-  "package",
-  "return",
-  "true",
-  "var",
-  "void",
-  "while",
-];
+// CEL keywords live in `identifier-name.ts` — a binding named after one is
+// unreachable for exactly the reason a resource or step named after one is, so
+// the list belongs to the identifier vocabulary rather than to this file.
 
 /** Locate a kind's bindings field and the scope names its annotated contexts
  *  declare. Returns undefined for a kind that declares no bindings region. */

package/src/definition-registry.ts

@@ -116,11 +116,36 @@ export class DefinitionRegistry {
   registerNamedTypeSchema(id: string, schema: Record<string, any>): boolean {
     if (this.definitionSchemaIds.has(id)) return false;
     if (this.registeredSchemaIds.has(id) || this.ajv.getSchema(id)) return true;
-    this.ajv.addSchema(schema, id);
+    if (!this.tryAddSchema(schema, id)) return true;
     this.registeredSchemaIds.add(id);
     return true;
   }
 
+  /**
+   * Register a schema, surviving one AJV refuses.
+   *
+   * `addSchema` META-VALIDATES and THROWS, and a throw here escapes the whole
+   * analyze pass: one author schema with `minimum: "3"` in it aborted the run
+   * with AJV's own unanchored text and took every other diagnostic in the file
+   * down with it — including the anchored one that says exactly which keyword is
+   * wrong. Registration is a lookup table for `$ref` resolution, so failing to
+   * fill one entry costs a reference that could not have resolved anyway.
+   *
+   * Nothing is swallowed: an unregisterable schema is invalid, and the two
+   * checks that report it both run afterwards and both anchor on the offending
+   * line — `SCHEMA_VIOLATION` from the `KindSchema` / `JsonSchema7` fragment the
+   * slot points at, and `SCHEMA_COMPILE_ERROR` from {@link schemaCompileError},
+   * which wraps `compile` for this same reason.
+   */
+  private tryAddSchema(schema: Record<string, any>, id: string): boolean {
+    try {
+      this.ajv.addSchema(schema, id);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
   /** True when a schema is registered under `id` (a canonical `telo://` type id
    *  or a definition `$id`). Used to flag schema `$ref`s that resolve to nothing. */
   hasSchemaId(id: string): boolean {
@@ -187,7 +212,10 @@ export class DefinitionRegistry {
     if (this.ajv.getSchema(id)) {
       throw new Error(`Duplicate definition schema $id: "${id}" is already registered`);
     }
-    this.ajv.addSchema(schema, id);
+    // A schema AJV refuses is left unregistered rather than aborting the pass —
+    // see {@link tryAddSchema}. The id stays claimed either way, so a later
+    // named type cannot quietly take a kind's place.
+    this.tryAddSchema(schema, id);
     this.registeredSchemaIds.add(id);
     this.definitionSchemaIds.add(id);
   }