@telorun/analyzer 0.37.0 → 0.39.0

package/src/normalize-inline-resources.ts

@@ -10,6 +10,21 @@ const SYSTEM_KINDS = new Set([
   "Telo.Import",
 ]);
 
+/**
+ * System kinds are excluded from inline extraction by default, but a single slot
+ * may opt back in with `x-telo-inline: true` — `Telo.Application.logging.sinks`
+ * is the case this exists for.
+ *
+ * The opt-in is per slot rather than per kind because this pass runs *upstream*
+ * of schema validation on both the analyzer and runtime paths. Admitting the
+ * whole Application document would rewrite an inline `{kind, ...}` in `targets`
+ * into a valid `{kind, name}` before AJV ever saw it, silently converting a
+ * deliberate rejection into a working feature.
+ */
+function acceptsInline(resourceKind: string, entry: { inline?: boolean }): boolean {
+  return !SYSTEM_KINDS.has(resourceKind) || entry.inline === true;
+}
+
 /** Replaces characters outside [a-zA-Z0-9_] with underscores. */
 function sanitizeName(raw: string): string {
   return raw.replace(/[^a-zA-Z0-9_]/g, "_");
@@ -65,9 +80,12 @@ export function normalizeInlineResources(
 
   // Queue: all non-system resources with a name. Extracted resources are appended.
   // Filter the CLONES (not the originals) so traversal mutates copies.
+  // System kinds join the queue too: their inline-accepting slots are filtered
+  // per entry below, so a system document is walked but only its opted-in slots
+  // are extracted from.
   const queue = result.filter(
     (r): r is ResourceManifest & { metadata: { name: string } } =>
-      typeof r.metadata?.name === "string" && !!r.kind && !SYSTEM_KINDS.has(r.kind),
+      typeof r.metadata?.name === "string" && !!r.kind,
   );
 
   let i = 0;
@@ -97,6 +115,7 @@ export function normalizeInlineResources(
 
     for (const [fieldPath, entry] of fieldMap) {
       if (!isRefEntry(entry)) continue;
+      if (!acceptsInline(resource.kind, entry)) continue;
 
       const inScope = scopePrefixes.some(
         (prefix) =>

package/src/redaction-path.ts

@@ -0,0 +1,142 @@
+/**
+ * The redaction path grammar of `kernel/specs/logging.md` §14 — a hand-written
+ * parser over a closed grammar.
+ *
+ * §14.1 makes this a security requirement rather than a style preference. The
+ * implementation this syntax is borrowed from compiles paths through the
+ * `Function` constructor and validates them by "evaluate it and see whether it
+ * parses", which is exactly why that implementation must forbid user input. A
+ * real parser removes the injection surface entirely and, as a bonus, makes
+ * paths statically checkable by `telo check`.
+ *
+ * Browser-safe by construction: this module is imported by both the analyzer's
+ * static check and the kernel's runtime redaction pass, so the grammar has one
+ * definition rather than two that can drift.
+ *
+ * Grammar:
+ *
+ *     path     := segment ( "." segment | bracket )*
+ *     segment  := bareKey | "*"
+ *     bracket  := "[" ( quoted | integer | "*" ) "]"
+ *     quoted   := '"' ... '"' | "'" ... "'"
+ *
+ * More than one wildcard per path is supported — `items[*].tokens[*].value` is
+ * valid. The one-wildcard limit in the best-known implementation is an artifact
+ * of how it compiles accessors, not a property of the grammar.
+ */
+
+export type RedactionSegment = { kind: "key"; name: string } | { kind: "wildcard" };
+
+export class RedactionPathError extends Error {
+  readonly code = "INVALID_REDACTION_PATH";
+  readonly path: string;
+  readonly offset: number;
+
+  constructor(path: string, offset: number, detail: string) {
+    super(`Invalid redaction path "${path}" at position ${offset}: ${detail}`);
+    this.name = "RedactionPathError";
+    this.path = path;
+    this.offset = offset;
+  }
+}
+
+const BARE_KEY_TERMINATORS = new Set([".", "[", "]"]);
+
+/**
+ * Parse a redaction path into its segments. Throws {@link RedactionPathError}
+ * with the offending offset so `telo check` can point at the character rather
+ * than the whole path.
+ */
+export function parseRedactionPath(path: string): RedactionSegment[] {
+  if (path.length === 0) throw new RedactionPathError(path, 0, "path is empty");
+
+  const segments: RedactionSegment[] = [];
+  let index = 0;
+  let expectSegment = true;
+
+  while (index < path.length) {
+    const char = path[index]!;
+
+    if (char === "[") {
+      index = parseBracket(path, index, segments);
+      expectSegment = false;
+      continue;
+    }
+
+    if (char === ".") {
+      if (expectSegment) {
+        throw new RedactionPathError(path, index, "expected a key before '.'");
+      }
+      index += 1;
+      expectSegment = true;
+      continue;
+    }
+
+    if (char === "]") {
+      throw new RedactionPathError(path, index, "unmatched ']'");
+    }
+
+    const start = index;
+    while (index < path.length && !BARE_KEY_TERMINATORS.has(path[index]!)) index += 1;
+    const raw = path.slice(start, index);
+    if (raw.length === 0) throw new RedactionPathError(path, start, "empty key");
+    segments.push(raw === "*" ? { kind: "wildcard" } : { kind: "key", name: raw });
+    expectSegment = false;
+  }
+
+  if (expectSegment) {
+    throw new RedactionPathError(path, path.length, "path ends with a trailing '.'");
+  }
+  return segments;
+}
+
+function parseBracket(path: string, open: number, segments: RedactionSegment[]): number {
+  let index = open + 1;
+  if (index >= path.length) throw new RedactionPathError(path, open, "unterminated '['");
+
+  const quote = path[index];
+  if (quote === '"' || quote === "'") {
+    index += 1;
+    const start = index;
+    while (index < path.length && path[index] !== quote) index += 1;
+    if (index >= path.length) {
+      throw new RedactionPathError(path, start, `unterminated ${quote} quoted key`);
+    }
+    const name = path.slice(start, index);
+    if (name.length === 0) throw new RedactionPathError(path, start, "empty quoted key");
+    index += 1;
+    if (path[index] !== "]") {
+      throw new RedactionPathError(path, index, "expected ']' after quoted key");
+    }
+    segments.push({ kind: "key", name });
+    return index + 1;
+  }
+
+  const start = index;
+  while (index < path.length && path[index] !== "]") index += 1;
+  if (index >= path.length) throw new RedactionPathError(path, open, "unterminated '['");
+  const raw = path.slice(start, index);
+  if (raw.length === 0) throw new RedactionPathError(path, start, "empty '[]'");
+  if (raw === "*") {
+    segments.push({ kind: "wildcard" });
+  } else if (/^\d+$/.test(raw)) {
+    segments.push({ kind: "key", name: raw });
+  } else {
+    throw new RedactionPathError(
+      path,
+      start,
+      `expected a quoted key, an integer index, or '*', got "${raw}" — quote it as ["${raw}"]`,
+    );
+  }
+  return index + 1;
+}
+
+/** `true` when the path contains a wildcard anywhere but its last segment.
+ *  §14.2 measures intermediate wildcards at 25–55% over plain serialization,
+ *  against 1–2% for explicit paths, so a runtime may warn when one is used. */
+export function hasIntermediateWildcard(segments: readonly RedactionSegment[]): boolean {
+  for (let i = 0; i < segments.length - 1; i += 1) {
+    if (segments[i]!.kind === "wildcard") return true;
+  }
+  return false;
+}

package/src/reference-field-map.ts

@@ -8,6 +8,18 @@ export interface RefFieldEntry {
   /** x-telo-context schema declared on this ref slot, if any. Describes the CEL invocation
    *  context available to resources placed in this slot. */
   context?: Record<string, any>;
+  /** `x-telo-inline: true` — this slot accepts an inline `{kind, ...config}`
+   *  definition, not only a `!ref`.
+   *
+   *  Only meaningful on the *system* kinds (`Telo.Application` and friends),
+   *  which are otherwise excluded from inline-resource normalization wholesale.
+   *  Ordinary resource kinds accept inline definitions at every ref slot and
+   *  need no annotation. The flag exists so `logging.sinks` can opt in without
+   *  also legalizing an inline definition in `targets`, where the Application
+   *  schema rejects one deliberately — normalization runs upstream of AJV, so
+   *  an unconditional opt-in would rewrite the value into a valid shape before
+   *  the schema ever saw it. */
+  inline?: boolean;
 }
 
 /** An entry for a field that declares an execution scope (x-telo-scope). */
@@ -148,6 +160,13 @@ export function buildReferenceFieldMap(schema: Record<string, any>): ReferenceFi
   return map;
 }
 
+/** `x-telo-inline` declared on any `anyOf` branch marks the whole slot as
+ *  inline-accepting, matching how {@link collectRefs} unions branch refs. */
+function collectInlineFlag(node: Record<string, any>): boolean {
+  if (!Array.isArray(node.anyOf)) return false;
+  return node.anyOf.some((branch: Record<string, any>) => branch?.["x-telo-inline"] === true);
+}
+
 export function collectRefs(node: Record<string, any>): string[] {
   const refs: string[] = [];
   if (typeof node["x-telo-ref"] === "string") {
@@ -212,6 +231,7 @@ function traverseNode(
   if (refs.length > 0) {
     const entry: RefFieldEntry = { refs, isArray: path.includes("[]") };
     if (node["x-telo-context"]) entry.context = node["x-telo-context"] as Record<string, any>;
+    if (node["x-telo-inline"] === true || collectInlineFlag(node)) entry.inline = true;
     map.set(path, entry);
     // A node can mix item-level ref branches (a bare string / `{kind, name}`)
     // with object branches that carry their OWN nested refs — e.g. Application

package/src/schema-compat.ts

@@ -308,6 +308,13 @@ export function celTypeSatisfiesJsonSchema(celType: string, schema: Record<strin
 /** Return a literal placeholder value of the correct schema type for AJV. */
 export function celPlaceholderForSchema(schema: Record<string, any>): unknown {
   if (schema.default !== undefined) return schema.default;
+  // An enum-constrained field needs a placeholder drawn from the enum: the
+  // type-based fallbacks below ("" for a string, 0 for a number) satisfy `type`
+  // but violate `enum`, so a CEL expression feeding any enum field would report
+  // a spurious SCHEMA_VIOLATION against a value the author never wrote. The
+  // member chosen is irrelevant — only its acceptability to AJV matters, since
+  // the real value is checked at runtime once the expression resolves.
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
   switch (schema.type) {
     case "integer":
     case "number":

package/src/validate-extends.ts

@@ -29,6 +29,9 @@ const EXTENDS_ALIAS_RE = /^[A-Z][A-Za-z0-9_]*\.[A-Z][A-Za-z0-9_]*$/;
  *    (metadata.module !== "Telo"). Builtin lifecycle capabilities (Telo.Invocable, etc.)
  *    never trigger this — they're lifecycle roles by design.
  */
+/** The built-in namespace, resolvable without a `Telo.Import`. */
+const TELO_BUILTIN_ALIAS = "Telo";
+
 export function validateExtends(
   manifests: ResourceManifest[],
   registry: DefinitionRegistry,
@@ -88,7 +91,11 @@ export function validateExtends(
         });
       } else {
         const prefix = extendsValue.slice(0, extendsValue.indexOf("."));
-        if (!aliases.hasAlias(prefix)) {
+        // `Telo` needs no import: the kernel built-ins are globally resolvable
+        // by design, which is what lets a sink author depend on the kernel
+        // contract (`extends: Telo.LogSink`) rather than on a standard-library
+        // module version — see kernel/specs/logging.md §10.2.
+        if (prefix !== TELO_BUILTIN_ALIAS && !aliases.hasAlias(prefix)) {
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
             code: "EXTENDS_MALFORMED",

package/src/validate-logging.ts

@@ -0,0 +1,136 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { AliasResolver } from "./alias-resolver.js";
+import type { DefinitionRegistry } from "./definition-registry.js";
+import { parseRedactionPath, RedactionPathError } from "./redaction-path.js";
+import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
+
+const SOURCE = "telo-analyzer";
+
+/**
+ * Static validation of the `logging:` block — `kernel/specs/logging.md` §14.1
+ * and §10.3.
+ *
+ * Two things the spec explicitly says are statically detectable, so leaving them
+ * to a runtime failure would contradict Telo's "manifests must remain statically
+ * analyzable" goal:
+ *
+ * 1. **Redaction paths** parse against the closed §14 grammar. §14.1's whole
+ *    argument for a hand-written parser is that it makes paths checkable by
+ *    `telo check`; a bad path must fail here, not silently fail to redact at
+ *    runtime.
+ * 2. **`on_full: block`** is unimplementable on a single-threaded runtime and
+ *    §10.3 calls it "statically detectable by `telo check`". Catching it here —
+ *    rather than only at boot — is what lets an operator fix it before shipping.
+ */
+export function validateLogging(
+  manifests: ResourceManifest[],
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
+): AnalysisDiagnostic[] {
+  const diagnostics: AnalysisDiagnostic[] = [];
+
+  for (const manifest of manifests) {
+    const kind = manifest.kind;
+
+    // Redaction paths live on the `logging:` block of the root Application and on
+    // any `Telo.Import` / `Telo.Library` doc carrying a per-import override.
+    if (kind === "Telo.Application" || kind === "Telo.Import" || kind === "Telo.Library") {
+      validateRedactPaths(manifest, diagnostics);
+    }
+
+    // `on_full` lives on any sink instance — an inline `logging.sinks[]` entry
+    // (extracted by Phase 2 into a first-class manifest by now) or a standalone
+    // sink resource declared elsewhere and reached via `!ref`.
+    if (isSinkKind(manifest, registry, aliases, aliasesByModule)) {
+      validateOnFull(manifest, diagnostics);
+    }
+  }
+
+  return diagnostics;
+}
+
+function validateRedactPaths(manifest: ResourceManifest, out: AnalysisDiagnostic[]): void {
+  const name = (manifest.metadata as { name?: string } | undefined)?.name;
+  const filePath = (manifest.metadata as { source?: string } | undefined)?.source;
+  const resource = { kind: manifest.kind, name };
+
+  for (const { block, prefix } of loggingBlocks(manifest)) {
+    const paths = (block.redact as { paths?: unknown } | undefined)?.paths;
+    if (!Array.isArray(paths)) continue;
+    paths.forEach((path, index) => {
+      // A `!cel` path is a compiled/sentinel node by now, not a string — its
+      // value isn't known statically, so there is nothing to parse.
+      if (typeof path !== "string") return;
+      try {
+        parseRedactionPath(path);
+      } catch (err) {
+        if (!(err instanceof RedactionPathError)) throw err;
+        out.push({
+          severity: DiagnosticSeverity.Error,
+          code: "INVALID_REDACTION_PATH",
+          source: SOURCE,
+          message: `${manifest.kind}/${name ?? "(unnamed)"}: ${err.message}`,
+          data: { resource, filePath, path: `${prefix}redact.paths[${index}]` },
+        });
+      }
+    });
+  }
+}
+
+function validateOnFull(manifest: ResourceManifest, out: AnalysisDiagnostic[]): void {
+  const onFull = (manifest as { on_full?: unknown }).on_full;
+  if (onFull !== "block") return;
+  const name = (manifest.metadata as { name?: string } | undefined)?.name;
+  const filePath = (manifest.metadata as { source?: string } | undefined)?.source;
+  out.push({
+    severity: DiagnosticSeverity.Error,
+    code: "LOG_SINK_ON_FULL_UNSUPPORTED",
+    source: SOURCE,
+    message:
+      `${manifest.kind}/${name ?? "(unnamed)"}: on_full: block is not supported on a ` +
+      `single-threaded runtime — blocking the producer would stall the writer. ` +
+      `Use drop_new or drop_old.`,
+    data: { resource: { kind: manifest.kind, name }, filePath, path: "on_full" },
+  });
+}
+
+/** The root `logging:` block plus every per-import `logging:` override, each
+ *  with the dotted path prefix a diagnostic anchors against. */
+function loggingBlocks(
+  manifest: ResourceManifest,
+): Array<{ block: Record<string, unknown>; prefix: string }> {
+  const blocks: Array<{ block: Record<string, unknown>; prefix: string }> = [];
+  const root = (manifest as { logging?: unknown }).logging;
+  if (isObject(root)) blocks.push({ block: root, prefix: "logging." });
+
+  // Inline imports map: `imports.<Alias>.logging`.
+  const imports = (manifest as { imports?: unknown }).imports;
+  if (isObject(imports)) {
+    for (const [alias, entry] of Object.entries(imports)) {
+      if (!isObject(entry)) continue;
+      const block = (entry as { logging?: unknown }).logging;
+      if (isObject(block)) blocks.push({ block, prefix: `imports.${alias}.logging.` });
+    }
+  }
+  return blocks;
+}
+
+function isSinkKind(
+  manifest: ResourceManifest,
+  registry: DefinitionRegistry,
+  aliases: AliasResolver,
+  aliasesByModule?: Map<string, AliasResolver>,
+): boolean {
+  if (typeof manifest.kind !== "string") return false;
+  if (manifest.kind === "Telo.ConsoleSink" || manifest.kind === "Telo.FileSink") return true;
+  const ownModule = (manifest.metadata as { module?: string } | undefined)?.module;
+  const resolver =
+    (ownModule ? aliasesByModule?.get(ownModule) : undefined) ?? aliases;
+  const canonical = resolver.resolveKind(manifest.kind) ?? manifest.kind;
+  return registry.resolve(canonical)?.capability === "Telo.Sink";
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}