@telorun/analyzer 0.13.0 → 0.15.0

package/src/resolve-ref-sentinels.ts

@@ -5,43 +5,100 @@ import type { DefinitionRegistry } from "./definition-registry.js";
 import { isRefEntry } from "./reference-field-map.js";
 import { REF_RESOLUTION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 
+/** Resolved ref shape written in place of a `!ref` sentinel. `alias` is set only for
+ *  cross-module references (resolved into an imported library's exported instance). */
+type ResolvedRef = { kind: string; name: string; alias?: string };
+
 /**
  * Walks every `x-telo-ref` slot in every non-system resource and rewrites
- * `!ref <name>` sentinels in-place to `{kind: <resolved-kind>, name}`.
+ * `!ref <name>` sentinels in-place to `{kind, name}` (local) or
+ * `{kind, name, alias}` (cross-module).
  *
- * The downstream pipeline (inline normalization, dependency graph, kernel
- * controllers) expects every ref-slot value to be either a `{kind, name}`
- * object, an inline-definition object, or a legacy bare string — resolving
- * sentinels here keeps that contract intact so each consumer doesn't need
- * its own sentinel branch.
+ * Reference grammar — the tag's source string is split on the FIRST dot:
+ *   - `!ref writeLine`          → local resource `writeLine`
+ *   - `!ref Self.writeLine`     → local resource `writeLine` (explicit self-qualifier)
+ *   - `!ref Console.writeLine`  → instance `writeLine` exported by the import aliased
+ *                                 `Console`, resolved against the forwarded foreign set
  *
- * The walker assigns `kind` by name lookup (resource names are unique
- * within a manifest scope). When the name doesn't resolve in the local
- * `byName` map, the sentinel is left in place so `validateReferences`
- * can emit the `UNRESOLVED_REFERENCE` diagnostic with full context.
+ * Aliases are PascalCase identifiers without dots and resource names carry no dots
+ * (enforced as a hard diagnostic), so the first-dot split is unambiguous. When the
+ * name doesn't resolve, the sentinel is left in place so `validateReferences` emits the
+ * `UNRESOLVED_REFERENCE` diagnostic with full context.
  *
- * Mutation strategy: the field-path walker descends the resource tree
- * directly and replaces the sentinel on its parent container. Re-parsing
- * a string-encoded concrete path (the earlier shape) coupled the writer
- * to the path-encoding rules of `resolveFieldEntries` — any new path
- * marker would silently break this writer. Descending directly avoids
- * that coupling.
+ * Forwarded foreign resources (an imported library's exported instances, carrying a
+ * `metadata.module` that isn't a root module) are resolution TARGETS only — they are not
+ * re-walked as sources here, since their own ref slots belong to their own module scope.
  */
 export function resolveRefSentinels(
   resources: ResourceManifest[],
   registry: DefinitionRegistry,
   aliases?: AliasResolver,
   aliasesByModule?: Map<string, AliasResolver>,
+  // Extra foreign resources used only as cross-module resolution TARGETS (not mutated, not
+  // walked as sources). The kernel passes the analyzer-flattened set here so the runtime
+  // pass — which loads the entry module only — can still resolve `!ref Alias.name` against
+  // imported libraries' exported instances.
+  crossModuleTargets: ResourceManifest[] = [],
 ): void {
+  const moduleOf = (r: ResourceManifest): string | undefined =>
+    (r.metadata as { module?: string } | undefined)?.module;
+  // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
+  // cross-module resolution targets only — never walked as local ref sources here.
+  const isForeign = (r: ResourceManifest): boolean =>
+    (r.metadata as { forwardedExport?: boolean } | undefined)?.forwardedExport === true;
+
+  // Local resources resolve a bare / `Self.`-qualified name; forwarded foreign exports
+  // resolve an `Alias.`-qualified name keyed by (module, name).
   const byName = new Map<string, ResourceManifest>();
+  const byModuleName = new Map<string, ResourceManifest>();
   for (const r of resources) {
-    if (r.metadata?.name && !SYSTEM_KINDS.has(r.kind)) {
-      byName.set(r.metadata.name as string, r);
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind)) continue;
+    const name = r.metadata.name as string;
+    if (isForeign(r)) {
+      byModuleName.set(`${moduleOf(r)}\0${name}`, r);
+    } else {
+      byName.set(name, r);
     }
   }
+  for (const r of crossModuleTargets) {
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r)) continue;
+    byModuleName.set(`${moduleOf(r)}\0${r.metadata.name as string}`, r);
+  }
+
+  const resolveTarget = (source: string): ResolvedRef | undefined => {
+    const dot = source.indexOf(".");
+    if (dot === -1) {
+      const t = byName.get(source);
+      return t ? { kind: t.kind as string, name: source } : undefined;
+    }
+    const alias = source.slice(0, dot);
+    const name = source.slice(dot + 1);
+    if (alias === "Self") {
+      const t = byName.get(name);
+      return t ? { kind: t.kind as string, name } : undefined;
+    }
+    const module = aliases?.moduleForAlias(alias);
+    if (module) {
+      const t = byModuleName.get(`${module}\0${name}`);
+      if (t) {
+        // The foreign instance's `kind` is authored in ITS module's scope (e.g.
+        // `Self.WriteLine`); canonicalize to a scope-independent `<module>.<Kind>` for the
+        // consumer's kind check. `Self.` maps to the owning module directly — the forwarded
+        // library's Library doc (hence its `Self` alias) isn't in the consumer's manifest
+        // set — while other alias prefixes resolve via that module's forwarded import scope.
+        const rawKind = t.kind as string;
+        const foreignKind = rawKind.startsWith("Self.")
+          ? `${module}.${rawKind.slice("Self.".length)}`
+          : aliasesByModule?.get(module)?.resolveKind(rawKind) ?? rawKind;
+        return { kind: foreignKind, name, alias };
+      }
+    }
+    return undefined;
+  };
 
   for (const r of resources) {
     if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
+    if (isForeign(r)) continue;
 
     const fieldMap =
       aliases && aliasesByModule
@@ -51,45 +108,33 @@ export function resolveRefSentinels(
 
     for (const [fieldPath, entry] of fieldMap) {
       if (!isRefEntry(entry)) continue;
-      replaceSentinelsAtPath(r as Record<string, unknown>, fieldPath, byName);
+      descend(r as Record<string, unknown>, fieldPath.split("."), resolveTarget);
     }
   }
 }
 
-/** Walks `obj` along `fieldPath` (dot notation with `[]` for arrays and
- *  `{}` for additionalProperties-typed maps) and replaces any `!ref`
- *  sentinel value at the terminal slot with `{kind, name}` looked up
- *  via `byName`. Mutates the parent container in place; no string-path
- *  round-trip. */
-function replaceSentinelsAtPath(
-  obj: Record<string, unknown>,
-  fieldPath: string,
-  byName: Map<string, ResourceManifest>,
-): void {
-  const parts = fieldPath.split(".");
-  descend(obj, parts, byName);
-}
-
+/** Walks `obj` along `fieldPath` parts (dot notation with `[]` for arrays and `{}` for
+ *  additionalProperties-typed maps) and replaces any `!ref` sentinel at the terminal slot
+ *  with its resolved `{kind, name, alias?}`. Mutates the parent container in place. */
 function descend(
   obj: unknown,
   parts: string[],
-  byName: Map<string, ResourceManifest>,
+  resolve: (source: string) => ResolvedRef | undefined,
 ): void {
   if (obj == null || typeof obj !== "object" || parts.length === 0) return;
   const [head, ...rest] = parts;
 
-  // Map iteration: descend into every value of the current object.
   if (head === "{}") {
     const container = obj as Record<string, unknown>;
     for (const key of Object.keys(container)) {
       const child = container[key];
       if (rest.length === 0) {
         if (isRefSentinel(child)) {
-          const target = byName.get(child.source);
-          if (target) container[key] = { kind: target.kind as string, name: child.source };
+          const target = resolve(child.source);
+          if (target) container[key] = target;
         }
       } else {
-        descend(child, rest, byName);
+        descend(child, rest, resolve);
       }
     }
     return;
@@ -107,21 +152,21 @@ function descend(
       if (rest.length === 0) {
         const elem = val[i];
         if (isRefSentinel(elem)) {
-          const target = byName.get(elem.source);
-          if (target) val[i] = { kind: target.kind as string, name: elem.source };
+          const target = resolve(elem.source);
+          if (target) val[i] = target;
         }
       } else {
-        descend(val[i], rest, byName);
+        descend(val[i], rest, resolve);
       }
     }
   } else {
     if (rest.length === 0) {
       if (isRefSentinel(val)) {
-        const target = byName.get(val.source);
-        if (target) container[key] = { kind: target.kind as string, name: val.source };
+        const target = resolve(val.source);
+        if (target) container[key] = target;
       }
     } else {
-      descend(val, rest, byName);
+      descend(val, rest, resolve);
     }
   }
 }

package/src/resolve-throws-union.ts

@@ -1,4 +1,5 @@
 import type { ResourceDefinition, ResourceManifest } from "@telorun/sdk";
+import { isTaggedSentinel } from "@telorun/templating";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
@@ -6,6 +7,11 @@ export interface ThrowsCodeMeta {
   data?: Record<string, any>;
 }
 
+/** Code a non-`InvokeError` failure surfaces as inside a `catch` block. Mirrors
+ *  `PLAIN_ERROR_CODE` in `@telorun/run`'s `toSequenceError`: any invoke can throw
+ *  a plain error, which the catch sees as `error.code === "INTERNAL_ERROR"`. */
+export const PLAIN_ERROR_CODE = "INTERNAL_ERROR";
+
 export interface ThrowsUnion {
   /** Code → per-code metadata (data schema, etc). Keys are the declared codes. */
   codes: Map<string, ThrowsCodeMeta>;
@@ -14,6 +20,12 @@ export interface ThrowsUnion {
    *  an unknown kind was encountered, or a cycle short-circuited resolution.
    *  Callers must treat unbounded unions as requiring a catch-all entry. */
   unbounded: boolean;
+  /** True when the block can fail with a non-`InvokeError` (any `invoke:` step).
+   *  Such a failure surfaces inside an enclosing `catch` as `PLAIN_ERROR_CODE`,
+   *  so a `throw: { code: "${{ error.code }}" }` rethrow can propagate it. Not
+   *  injected into `codes` — only seeds `enclosingTryCodes` at a try/catch site,
+   *  leaving non-rethrow unions untouched. */
+  canThrowPlain?: boolean;
 }
 
 export interface ResolveCtx {
@@ -47,6 +59,7 @@ function unionInto(target: ThrowsUnion, src: ThrowsUnion): void {
     if (!target.codes.has(code)) target.codes.set(code, meta);
   }
   if (src.unbounded) target.unbounded = true;
+  if (src.canThrowPlain) target.canThrowPlain = true;
 }
 
 function definitionFor(
@@ -173,7 +186,11 @@ function collectStepThrows(
   ctx: ResolveCtx,
 ): ThrowsUnion {
   if (step[invokeField]) {
-    return resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx);
+    // Any invoked resource can throw a non-InvokeError at runtime, which an
+    // enclosing catch surfaces as PLAIN_ERROR_CODE — record that possibility.
+    const u = cloneUnion(resolveStepInvokeThrows(step, invokeField, enclosingTryCodes, ctx));
+    u.canThrowPlain = true;
+    return u;
   }
 
   if (step.throw && typeof step.throw === "object") {
@@ -188,6 +205,10 @@ function collectStepThrows(
       // out instead. Sequence-specific subtraction — the plan explicitly
       // anchors this to Run.Sequence's try/catch schema shape.
       const tryCodes = new Set(tryUnion.codes.keys());
+      // A plain (non-InvokeError) failure in the try block reaches the catch as
+      // `error.code === PLAIN_ERROR_CODE`, so a `throw: { code: error.code }`
+      // rethrow can propagate it — seed the set the catch resolves against.
+      if (tryUnion.canThrowPlain) tryCodes.add(PLAIN_ERROR_CODE);
       propagated = collectStepArrayThrows(step.catch, invokeField, tryCodes, ctx);
       // Unbounded in the try block still signals the caller to expect
       // arbitrary codes to flow through the catch (e.g. via passthrough).
@@ -247,6 +268,7 @@ function cloneUnion(u: ThrowsUnion): ThrowsUnion {
   const out = emptyUnion();
   for (const [c, m] of u.codes) out.codes.set(c, m);
   out.unbounded = u.unbounded;
+  if (u.canThrowPlain) out.canThrowPlain = true;
   return out;
 }
 
@@ -316,16 +338,22 @@ function resolveCodeExpression(
   codeInput: unknown,
   enclosingTryCodes: Set<string> | undefined,
 ): ThrowsUnion {
-  if (typeof codeInput !== "string" || codeInput.length === 0) {
+  // A `!cel`-tagged sentinel and a `${{ … }}` string must resolve identically —
+  // normalize both to the inner CEL expression (or a bare literal code).
+  let expr: string;
+  if (isTaggedSentinel(codeInput)) {
+    if (codeInput.engine !== "cel") return { codes: new Map(), unbounded: true };
+    expr = codeInput.source.trim();
+  } else if (typeof codeInput === "string" && codeInput.length > 0) {
+    const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
+    if (!match) {
+      return { codes: new Map([[codeInput, {}]]), unbounded: false };
+    }
+    expr = match[1].trim();
+  } else {
     return { codes: new Map(), unbounded: true };
   }
 
-  const match = codeInput.match(/^\s*\$\{\{\s*([\s\S]+?)\s*\}\}\s*$/);
-  if (!match) {
-    return { codes: new Map([[codeInput, {}]]), unbounded: false };
-  }
-
-  const expr = match[1].trim();
   const litMatch = expr.match(/^'([^']+)'$|^"([^"]+)"$/);
   if (litMatch) {
     const code = litMatch[1] ?? litMatch[2]!;

package/src/validate-references.ts

@@ -107,10 +107,46 @@ export function validateReferences(
   // source, different sourceLine) keep separate fingerprints and still
   // trip the diagnostic. `analyze()` enforces that every non-system
   // manifest carries both positional fields — no defensive guard needed.
+  // Forwarded foreign exports (an imported library's exported instances, carrying a
+  // metadata.module that isn't a root module) are resolution TARGETS only: excluded from
+  // duplicate detection and local name resolution, and never walked as ref sources.
+  const moduleOf = (r: ResourceManifest): string | undefined =>
+    (r.metadata as { module?: string } | undefined)?.module;
+  // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
+  // cross-module resolution targets only — excluded from duplicate detection and local name
+  // resolution, and never walked as ref sources.
+  const isForeign = (r: ResourceManifest): boolean =>
+    (r.metadata as { forwardedExport?: boolean } | undefined)?.forwardedExport === true;
+  // Forwarded exported instances keyed `${module}\0${name}` — the lookup that resolves
+  // whether a cross-module `!ref Alias.name` names a real exported instance.
+  const byModuleName = new Map<string, ResourceManifest>();
+  /** Modules whose import subtree was actually loaded in this analysis. A resolved
+   *  `Telo.Import` carries `resolvedModuleName` (stamped only once the edge — and thus the
+   *  imported module — resolved); forwarded exports carry `metadata.module`. Either marks
+   *  the module loaded independent of how many instances it exports, so a loaded library
+   *  that exports nothing still reports invalid cross-module refs, while partial single-file
+   *  analysis (neither present) is skipped to avoid false `UNRESOLVED_REFERENCE`. */
+  const loadedModules = new Set<string>();
+  for (const r of resources) {
+    if (r.kind === "Telo.Import") {
+      const m = (r.metadata as { resolvedModuleName?: unknown } | undefined)?.resolvedModuleName;
+      if (typeof m === "string") loadedModules.add(m);
+      continue;
+    }
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r)) continue;
+    const m = moduleOf(r);
+    if (!m) continue;
+    byModuleName.set(`${m}\0${r.metadata.name as string}`, r);
+    loadedModules.add(m);
+  }
+  const moduleLoaded = (module: string): boolean => loadedModules.has(module);
+  const localResources = resources.filter((r) => !isForeign(r));
+
   const byNameAll = new Map<string, ResourceManifest[]>();
   const seen = new Set<string>();
   for (const r of resources) {
-    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import") continue;
+    if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || r.kind === "Telo.Import" || isForeign(r))
+      continue;
     const name = r.metadata.name as string;
     // `analyze()` guarantees both fields are present on non-system manifests.
     const meta = r.metadata as unknown as { source: string; sourceLine: number };
@@ -148,6 +184,33 @@ export function validateReferences(
       });
     }
   }
+  // A resource name must contain no dot. The `!ref` resolver splits the tag's source on
+  // the first dot to separate an import alias from the resource name, so a dotted name
+  // would mis-resolve into a cross-module lookup. This is the load-bearing invariant of
+  // the reference grammar, so it is enforced here rather than left to the (unenforced)
+  // casing convention.
+  for (const [name, list] of byNameAll) {
+    if (!name.includes(".")) continue;
+    for (const r of list) {
+      const m = r.metadata as { source?: string; sourceLine?: number } | undefined;
+      const range =
+        typeof m?.sourceLine === "number"
+          ? {
+              start: { line: m.sourceLine, character: 0 },
+              end: { line: m.sourceLine, character: Number.MAX_SAFE_INTEGER },
+            }
+          : undefined;
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "INVALID_RESOURCE_NAME",
+        source: SOURCE,
+        message: `${r.kind}/${name}: resource name must not contain '.' — in a '!ref' the '.' separates an import alias from the resource name`,
+        ...(range ? { range } : {}),
+        data: { resource: { kind: r.kind, name }, filePath: m?.source, path: "metadata.name" },
+      });
+    }
+  }
+
   // Single-resource map for the resolution / scope lookups below — when a
   // collision exists, falling back to the first occurrence keeps the rest
   // of the pass behaving the same as before the duplicate diagnostic was
@@ -161,7 +224,7 @@ export function validateReferences(
   // enclosure (`inScope`) and the scope manifests visible to it — so this
   // handler only validates, it does not re-walk.
   visitManifest(
-    resources,
+    localResources,
     registry,
     {
       onRef: (e) => {
@@ -178,14 +241,37 @@ export function validateReferences(
         // string/inline ambiguity at the source.
         if (isRefSentinel(val)) {
           const refName = val.source;
+          const dot = refName.indexOf(".");
+          const aliasPrefix = dot > 0 ? refName.slice(0, dot) : undefined;
+
+          // Cross-module sentinel left unresolved by Phase 2.5 — it qualifies an import
+          // alias. If that module's exports are loaded in this analysis, the miss is real
+          // (name not in exports.resources, or a typo); if not (partial single-file
+          // analysis), skip rather than emit a false UNRESOLVED_REFERENCE.
+          if (aliasPrefix && aliasPrefix !== "Self" && aliases.hasAlias(aliasPrefix)) {
+            const module = aliases.moduleForAlias(aliasPrefix);
+            if (module && !moduleLoaded(module)) return;
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "UNRESOLVED_REFERENCE",
+              source: SOURCE,
+              message: `${resourceLabel}: reference at '${concretePath}' → '${refName}' is not exported by module '${module ?? aliasPrefix}' (add it to exports.resources)`,
+              data: { resource: resourceData, filePath, path: concretePath },
+            });
+            return;
+          }
+
+          // Local reference (bare name or explicit `Self.`-qualified).
+          const localName = aliasPrefix === "Self" ? refName.slice(dot + 1) : refName;
           const target =
-            byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+            byName.get(localName) ??
+            visibleScopeManifests.find((m) => m.metadata?.name === localName);
           if (!target) {
             diagnostics.push({
               severity: DiagnosticSeverity.Error,
               code: "UNRESOLVED_REFERENCE",
               source: SOURCE,
-              message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+              message: `${resourceLabel}: reference at '${concretePath}' → resource '${localName}' not found`,
               data: { resource: resourceData, filePath, path: concretePath },
             });
             return;
@@ -248,6 +334,13 @@ export function validateReferences(
         // Skip inline resources — Phase 2 normalization hasn't run yet.
         if (isInlineResource(refVal)) return;
 
+        // Polymorphic ref slots (Application `targets`) accept object forms
+        // whose references live in nested slots rather than being a `{kind,
+        // name}` ref themselves — inline `{ invoke }` and gated `{ ref }`.
+        // Those nested refs are validated via their own field-map entries, so
+        // skip the item-level structural check here.
+        if (typeof refVal.kind !== "string" && ("invoke" in refVal || "ref" in refVal)) return;
+
         // 1. Structural check
         if (typeof refVal.kind !== "string" || typeof refVal.name !== "string") {
           diagnostics.push({
@@ -273,9 +366,18 @@ export function validateReferences(
         }
 
         // 3. Resolution check — resource with this name must exist.
-        const exists =
-          byName.has(refVal.name) ||
-          visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+        let exists: boolean;
+        if (typeof refVal.alias === "string" && refVal.alias !== "Self") {
+          // Cross-module ref resolved by Phase 2.5. Validate against the forwarded
+          // exports when loaded; in partial context (module not loaded) assume resolvable.
+          const module = aliases.moduleForAlias(refVal.alias);
+          exists =
+            !module || !moduleLoaded(module) || byModuleName.has(`${module}\0${refVal.name}`);
+        } else {
+          exists =
+            byName.has(refVal.name) ||
+            visibleScopeManifests.some((m) => m.metadata?.name === refVal.name);
+        }
         if (!exists) {
           diagnostics.push({
             severity: DiagnosticSeverity.Error,
@@ -296,7 +398,7 @@ export function validateReferences(
   // validate the field value against the resulting sub-schema. Driven off the base map
   // (un-expanded) so each schema-from slot is seen as its own site.
   visitManifest(
-    resources,
+    localResources,
     registry,
     {
       onSchemaFrom: (e) => {