@telorun/analyzer 0.70.0 → 0.72.0

package/src/manifest-visitor.ts

@@ -17,6 +17,7 @@ import {
   type SchemaFromFieldEntry,
 } from "./reference-field-map.js";
 import type { ModuleScopes } from "./alias-resolver.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 import { templateBodies, withTemplateSelf } from "./template-body.js";
 import { extractContextsFromSchema, pathMatchesScope } from "./validate-cel-context.js";
 
@@ -65,8 +66,21 @@ export interface ScopeBoundaryEvent {
   source: ResourceManifest;
   /** Dot-form prefixes of every `x-telo-scope` field on this resource. */
   scopePrefixes: string[];
-  /** Scope-field JSON Pointer → manifests declared within that scope. */
+  /** VISIBILITY pointer (an `x-telo-scope` entry, e.g. `/steps`) → the manifests
+   *  visible there. Keyed by where scoped names may be REFERENCED, which is not
+   *  where they are DECLARED: `Run.Sequence` declares `x-telo-scope:
+   *  ["/steps", "/targets"]` on its `with:` field, so one declaration appears
+   *  under two keys and neither names `with`. Use {@link declarations} for the
+   *  declaration site. */
   manifestsByPointer: Map<string, ResourceManifest[]>;
+  /** Every inline declaration inside this resource's scopes, ONCE each, with the
+   *  concrete path it is written at in the owner's document (`with[0]`).
+   *
+   *  A diagnostic about a scoped resource has to anchor there: the resource is
+   *  not a top-level document, so position lookup finds the OWNER and then walks
+   *  this path into it. Deriving one from a visibility pointer instead names a
+   *  region the declaration is not in (`steps[0]`). */
+  declarations: { manifest: ResourceManifest; path: string }[];
   /** Names of every resource declared inside this resource's scopes. Used by
    *  the dependency graph to drop boot edges to scoped (on-demand) targets. */
   enclosedNames: Set<string>;
@@ -237,7 +251,14 @@ export function visitManifest(
     if (!r.metadata?.name || !r.kind) continue;
     if (skipKinds?.has(r.kind)) continue;
 
-    const resolvedKind = aliases?.resolveKind(r.kind);
+    // A resource's own kind is written in the alias scope of the module that
+    // DECLARED it — see `moduleAliasScope`, which is the one place that rule
+    // lives. Resolving it through the entry's aliases alone left `definition`
+    // undefined for every forwarded resource, so its `x-telo-context` regions
+    // contributed nothing and `request` / `result` read as unknown identifiers
+    // inside the library's own routes, on a file the consumer cannot fix.
+    const moduleScope = moduleAliasScope(r.metadata, aliases, aliasesByModule);
+    const resolvedKind = moduleScope?.resolveKind(r.kind);
     const definition =
       registry.resolve(r.kind) ??
       (resolvedKind ? registry.resolve(resolvedKind) : undefined);
@@ -249,8 +270,8 @@ export function visitManifest(
     const emittedRefPaths = wantsNested ? new Set<string>() : null;
 
     if (wantsRefs || wantsScope || wantsSchemaFrom) {
-      const baseMap = aliases
-        ? registry.getFieldMapForKind(r.kind, aliases)
+      const baseMap = moduleScope
+        ? registry.getFieldMapForKind(r.kind, moduleScope)
         : registry.getFieldMap(r.kind);
 
       // Expanded map drives ref/scope sites when requested; schema-from sites
@@ -263,6 +284,7 @@ export function visitManifest(
       if (refScopeMap && (wantsRefs || wantsScope)) {
         const manifestsByPointer = new Map<string, ResourceManifest[]>();
         const scopeRefEntries: { path: string; refName: string }[] = [];
+        const declarations: { manifest: ResourceManifest; path: string }[] = [];
         for (const [fieldPath, entry] of refScopeMap) {
           if (!isScopeEntry(entry)) continue;
           const raw: ResourceManifest[] = [];
@@ -270,6 +292,7 @@ export function visitManifest(
             const items = Array.isArray(fe.value) ? fe.value : [fe.value];
             items.forEach((v, i) => {
               if (!v || typeof v !== "object") return;
+              const declarationPath = Array.isArray(fe.value) ? `${fe.path}[${i}]` : fe.path;
               // A scope entry must be an inline resource definition; a `!ref`
               // (tagged sentinel or resolved `{kind, name}`) is not — record it
               // so a static diagnostic flags it instead of registering a
@@ -280,12 +303,13 @@ export function visitManifest(
                 (typeof rec.kind === "string" && typeof rec.name === "string")
               ) {
                 scopeRefEntries.push({
-                  path: Array.isArray(fe.value) ? `${fe.path}[${i}]` : fe.path,
+                  path: declarationPath,
                   refName: isRefSentinel(v) ? v.source : String(rec.name),
                 });
                 return;
               }
               raw.push(v as ResourceManifest);
+              declarations.push({ manifest: v as ResourceManifest, path: declarationPath });
             });
           }
           const pointers = Array.isArray(entry.scope) ? entry.scope : [entry.scope];
@@ -305,6 +329,7 @@ export function visitManifest(
             source: r,
             scopePrefixes,
             manifestsByPointer,
+            declarations,
             enclosedNames,
             scopeRefEntries,
           });

package/src/migrations/report.ts

@@ -21,7 +21,7 @@ import type {
   MigrationPath,
   MigrationRewrite,
 } from "./types.js";
-import type { AnalysisDiagnostic, DiagnosticFix } from "../types.js";
+import { DiagnosticTag, type AnalysisDiagnostic, type DiagnosticFix } from "../types.js";
 
 /** One patch that applied, as the reporting side needs to see it. */
 export interface AppliedPatch {
@@ -63,6 +63,10 @@ export function toDiagnostic(
     severity: applied.entry.severity,
     code: applied.entry.code,
     source: "telo-analyzer",
+    // A migration IS a deprecation — a legacy spelling still read, and the one
+    // an author is being asked to stop writing — so the range carries the tag
+    // whatever severity the entry chose for itself.
+    tags: [DiagnosticTag.Deprecated],
     message: `${rewrite.summary}\n${applied.entry.reason}\n${closing}`,
     data: {
       filePath: source,

package/src/module-alias-scope.ts

@@ -0,0 +1,94 @@
+import { AliasResolver, scopeResolverForModule, type ModuleScopes } from "./alias-resolver.js";
+
+/**
+ * WHICH ALIAS TABLE A MANIFEST'S OWN NAMES ARE WRITTEN IN.
+ *
+ * An application analysis is flattened, so an imported library's definitions and
+ * exported instances are checked in the CONSUMER's pass. But every alias-qualified
+ * name on such a manifest — its `kind:`, its `extends:`, an `x-telo-schema-from`
+ * anchor — was written against the alias map of the module that DECLARED it. A
+ * library writes `kind: Http.Api` through an import the consumer has no reason to
+ * have, so resolving it through the entry's table finds nothing, and everything
+ * derived from the definition silently goes missing: the field map (Phase-5
+ * injection blind to a forwarded resource's ref slots) and the `x-telo-context`
+ * regions (`request` / `result` reported as unknown identifiers on a file the
+ * consumer cannot edit).
+ *
+ * **There are TWO fallbacks, not one, and this file is where they are told
+ * apart** — that is the whole reason they live together. They agree on every
+ * module that has a table, and differ on a non-root module that has none:
+ *
+ *  - {@link moduleAliasScope} falls back to the GLOBAL table. For a question
+ *    asked about an arbitrary manifest, where a missing entry means "this is the
+ *    entry's own", which is what the global table answers correctly.
+ *  - {@link declaringModuleScope} falls back to an EMPTY table for a non-root
+ *    module. For canonicalizing what a library DECLARED, where resolving its
+ *    `Http.Api` through the consumer's imports would silently bind a library's
+ *    kind to whatever the app happens to import under that alias — a wrong
+ *    answer, which is worse than none.
+ *
+ * Both rest on one invariant neither states inline: **a root module is never a
+ * key in `aliasesByModule`** — a root's imports are registered into the global
+ * table instead (see the `rootModules` guards in `analyze()`) — so for a
+ * consumer-owned manifest the two rules coincide and neither fallback is a
+ * degradation.
+ *
+ * Every READ of the rule goes through one of these two. What legitimately does
+ * not, and why, so the next reader does not have to re-derive it: the three
+ * sites in `analyze()` that POPULATE `aliasesByModule` (a write, not a lookup),
+ * and `resolve-ref-sentinels`, whose module is known non-root by construction and
+ * whose fallback is the raw kind rather than another table — a different rule
+ * that happens to read the same map.
+ */
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M;
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A | undefined,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M | undefined;
+export function moduleAliasScope<A extends KindResolver, M extends KindResolver>(
+  metadata: { module?: unknown } | undefined,
+  aliases: A | undefined,
+  aliasesByModule: ReadonlyMap<string, M> | undefined,
+): A | M | undefined {
+  const declaringModule = metadata?.module;
+  if (typeof declaringModule !== "string") return aliases;
+  return aliasesByModule?.get(declaringModule) ?? aliases;
+}
+
+/** All this rule needs of a resolver, and deliberately all it asks for:
+ *  `ModuleScopes` already types its map this way so a caller can hand over a
+ *  lighter table, and requiring the full `AliasResolver` here would have made
+ *  the one site that does (a template body) reach for a cast. */
+interface KindResolver {
+  resolveKind(kind: string): string | undefined;
+}
+
+/** An empty table, shared: a non-root module with no aliases of its own resolves
+ *  nothing rather than resolving through the consumer's. One instance because it
+ *  is immutable in use and allocating one per call put a resolver on a per-schema
+ *  loop. */
+const NO_ALIASES = new AliasResolver();
+
+/**
+ * The scope a DECLARING module's own alias-form names are canonicalized in — the
+ * root-aware half of the rule above, and the one that must never fall through to
+ * the consumer's table. See this file's header for why the two differ.
+ */
+export function declaringModuleScope(
+  ownModule: string | undefined,
+  aliases: AliasResolver,
+  scopes: { aliasesByModule: Map<string, AliasResolver>; rootModules: Set<string> },
+): AliasResolver {
+  const own = scopeResolverForModule(ownModule, scopes.rootModules, scopes.aliasesByModule);
+  if (own) return own;
+  // Root (or unknown-and-therefore-treated-as-root): the global table IS its
+  // import map. A non-root module with no table of its own resolves nothing.
+  return ownModule && !scopes.rootModules.has(ownModule) ? NO_ALIASES : aliases;
+}
+
+export type { ModuleScopes };

package/src/{zone-module-documents.ts → module-documents.ts}

@@ -1,19 +1,23 @@
 import type { ResourceManifest } from "@telorun/sdk";
 
 /**
- * One imported library's FULL document set, for the zone stage's per-library
- * export derivation — what the flattened analysis view no longer holds, since
- * it forwards only each library's export surface and never its internal
- * dispatch chain.
+ * One imported library's FULL document set — what the flattened analysis view
+ * no longer holds, since it forwards only each library's export surface and
+ * never its internal dispatch chain.
+ *
+ * Named for what it CARRIES rather than for who asked first: the zone stage's
+ * per-library export derivation was the original consumer, and the throws walk
+ * is the second — a third should not have to import "zone" to ask about
+ * something else again.
  *
  * Plain data in a module of its own, deliberately. It is produced by the
- * loading side (`collectZoneModuleDocuments`), named in `AnalysisOptions`, and
+ * loading side (`collectModuleDocuments`), named in `AnalysisOptions`, and
  * consumed by the projection; putting it in any of the three would make the
  * other two import that one, and `types.ts` ↔ the projection is a genuine
  * cycle. A leaf module with no imports of its own breaks it without an inline
  * `import(...)` type expression standing in for the dependency nobody wanted.
  */
-export interface ZoneModuleDocuments {
+export interface ModuleDocuments {
   /** The library's module name (its `Telo.Library` doc's `metadata.name`). */
   module: string;
   /** Stable source identity of the library's owner file — the cache key. */

package/src/ref-sentinel-target.ts

@@ -0,0 +1,46 @@
+import { isRefSentinel } from "@telorun/templating";
+
+/**
+ * What a `!ref` names, parsed once.
+ *
+ * THE single reader of the tag's grammar, on the `ref-slot.ts` / `zone-slot.ts`
+ * precedent. Three passes had grown their own parse of the same scalar and they
+ * disagreed: one took the source verbatim, one split on the first dot and
+ * dropped every alias but `Self`, one split on the LAST dot and dropped the
+ * alias entirely — so the same `!ref Alias.name` named three different things
+ * depending on which pass was asking, and the loosest of the three resolved a
+ * bare name against whatever manifest happened to share it.
+ *
+ * The grammar itself is one line and is not in dispute: `!ref <name>` or
+ * `!ref <Alias>.<name>`, split on the FIRST dot, because that is what
+ * `resolveRefSentinels` does and a name may not contain one
+ * (`INVALID_NAME` rejects it at every declaration site).
+ *
+ * What this deliberately does NOT do is decide what to look up. A reduction is
+ * the caller's, and the three genuinely differ: an edge in the call graph points
+ * at a cross-module target and tolerates not resolving it; a zone correlation
+ * refuses to bind anything it cannot resolve exactly; a throws walk resolves in
+ * the DECLARING library first. Each states its own, over one parse.
+ *
+ * Browser-safe.
+ */
+export interface RefSentinelTarget {
+  /** The scalar as written, for a caller that wants the author's spelling. */
+  source: string;
+  /** The prefix before the first dot, `Self` included and not normalized away —
+   *  a caller that treats `Self` as "no alias" says so itself. */
+  alias?: string;
+  /** The segment after the first dot, or the whole scalar when there is none. */
+  name: string;
+}
+
+/** Parse a `!ref` sentinel. Returns `undefined` for anything that is not one —
+ *  including the `{kind, name}` object `resolveRefSentinels` rewrites it into,
+ *  which is a different shape with a different reader. */
+export function refSentinelTarget(value: unknown): RefSentinelTarget | undefined {
+  if (!isRefSentinel(value)) return undefined;
+  const source = value.source;
+  const dot = source.indexOf(".");
+  if (dot <= 0) return { source, name: source };
+  return { source, alias: source.slice(0, dot), name: source.slice(dot + 1) };
+}

package/src/ref-slot.ts

@@ -94,6 +94,21 @@ export interface RefSlot {
    *  that carries this call's arguments. Replaces
    *  `x-telo-topology-role: inputs`. */
   inputs?: string;
+  /** Throws raised by the target — or by anything the target drives — surface
+   *  through the DECLARING resource, so its own throws union includes the
+   *  target's and its catch scope encloses the target's.
+   *
+   *  It exists because the relation is real where `use` correctly says nothing:
+   *  `Http.Server.mounts[].mount` is a `dependency` (the server holds the mount
+   *  and calls a convention method on it — control reaches a route through the
+   *  MOUNT's own `trigger.inbound` slot, not through this one), yet a throw from
+   *  that route is exactly what the server renders. Following every `dependency`
+   *  edge instead would drag a connection's throws into a router's denominator.
+   *
+   *  Declared by the kind that HOLDS, because only it knows the throws surface
+   *  through it, and it is the same fact its runtime establishes by rethrowing —
+   *  so the annotation and the behaviour cannot disagree. */
+  throwsThrough?: boolean;
   /** `x-telo-inline: true` on the slot or any `anyOf` branch — accepts an inline
    *  `{kind, ...config}` definition, not only a `!ref`. */
   inline: boolean;
@@ -228,6 +243,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
   const uses = new Set<RefUse>();
   let useCases: RefUseCases | undefined;
   let inputs: string | undefined;
+  let throwsThrough = false;
 
   for (const carrier of nodes) {
     const annotation = carrier["x-telo-ref"];
@@ -239,6 +255,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
     for (const use of normalizeUses(obj.use)) uses.add(use);
     useCases ??= readUseCases(obj.use);
     if (typeof obj.inputs === "string") inputs ??= obj.inputs;
+    if (obj.throwsThrough === true) throwsThrough = true;
   }
 
   const slot: RefSlot = {
@@ -249,6 +266,7 @@ export function readRefSlot(node: Record<string, any> | undefined): RefSlot | un
   };
   if (useCases) slot.useCases = useCases;
   if (inputs !== undefined) slot.inputs = inputs;
+  if (throwsThrough) slot.throwsThrough = true;
   return slot;
 }
 
@@ -274,6 +292,7 @@ export function refSlotAnnotation(slot: RefSlot): Record<string, unknown> {
   else if (slot.uses.length === 1) annotation.use = slot.uses[0];
   else if (slot.uses.length > 1) annotation.use = slot.uses;
   if (slot.inputs !== undefined) annotation.inputs = slot.inputs;
+  if (slot.throwsThrough) annotation.throwsThrough = true;
   return annotation;
 }
 

package/src/resolve-schema-type-refs.ts

@@ -1,6 +1,7 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { canonicalTypeSchemaId, parseTeloTypeRef } from "@telorun/sdk";
 import type { AliasResolver } from "./alias-resolver.js";
+import { moduleAliasScope } from "./module-alias-scope.js";
 
 /** Schema-bearing fields on a Telo.Definition / Telo.Type resource. */
 const SCHEMA_FIELDS = ["schema", "inputType", "outputType"];
@@ -96,7 +97,7 @@ export function resolveSchemaTypeRefs(
 
   for (const r of resources) {
     const ownModule = (r.metadata as { module?: string } | undefined)?.module;
-    const resolver = (ownModule ? aliasesByModule?.get(ownModule) : undefined) ?? aliases;
+    const resolver = moduleAliasScope(r.metadata, aliases, aliasesByModule);
     const resolveAuthority = (authority: string): string | undefined =>
       authority === "Self" ? ownModule : resolver?.moduleForAlias(authority);
     for (const field of SCHEMA_FIELDS) {