@telorun/analyzer 1.2.0 → 1.4.0

package/src/system-kinds.ts

@@ -0,0 +1,37 @@
+/** Resource-kind sets used by analysis passes to decide what counts as a
+ *  user-defined instance vs. a system-level blueprint. Pulled into one
+ *  place so the three passes (reference validation, dependency graph,
+ *  ref-sentinel resolution) don't drift; each pass exports its own
+ *  scoped view with a comment explaining what's in and what's out. */
+
+/** Skipped by reference validation: type blueprints whose own ref slots
+ *  belong to a different phase (definition schema validation rather than
+ *  per-resource validation). Telo.Application and Telo.Library
+ *  intentionally fall through — Application has `targets` (real refs) and
+ *  Library is harmless (no ref-bearing fields). Telo.Import is also
+ *  intentionally not skipped — its `source` is not an x-telo-ref slot, so
+ *  walking it is cheap and consistent. */
+export const REF_VALIDATION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+]);
+
+/** Excluded from the dependency graph: kinds that are not runtime nodes.
+ *  Telo.Abstract is intentionally not in this set today — abstracts have
+ *  no resource manifests, so they never reach graph construction; if
+ *  that ever changes, add it explicitly. */
+export const DEPENDENCY_GRAPH_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Import",
+]);
+
+/** Skipped by `!ref` sentinel resolution: kinds whose bodies are
+ *  blueprints or import-time metadata, not resource instances with
+ *  user-referenced ref slots. Mirrors `REF_VALIDATION_SKIP_KINDS` but
+ *  also drops Telo.Import (its `source` isn't a ref slot, and walking
+ *  the field map on it is pointless since there's no registered kind). */
+export const REF_RESOLUTION_SKIP_KINDS: ReadonlySet<string> = new Set([
+  "Telo.Definition",
+  "Telo.Abstract",
+  "Telo.Import",
+]);

package/src/validate-references.ts

@@ -1,17 +1,13 @@
 import type { ResourceManifest } from "@telorun/sdk";
+import { isRefSentinel } from "@telorun/templating";
 import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldEntries, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
 import { navigateJsonPointer } from "./schema-compat.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic, type AnalysisContext } from "./types.js";
 import type { AliasResolver } from "./alias-resolver.js";
 import type { DefinitionRegistry } from "./definition-registry.js";
 
 const SOURCE = "telo-analyzer";
-/** Kinds skipped by reference validation. Telo.Application and Telo.Library
- *  are intentionally not here: Application has `targets` with x-telo-ref that
- *  must be validated, and Library has no ref-bearing fields so flows through
- *  harmlessly. Telo.Import is also not here for the same reason — its
- *  `source` field isn't x-telo-ref, so nothing gets checked. */
-const SYSTEM_KINDS = new Set(["Telo.Definition", "Telo.Abstract"]);
 
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
@@ -76,13 +72,52 @@ export function validateReferences(
   const aliasesByModule = context.aliasesByModule;
   if (!aliases || !registry) return diagnostics;
 
-  // Build outer resource lookup by name for resolution check.
-  // Exclude system kinds (Telo.Definition) — they are type blueprints, not instances,
-  // and their names (e.g. "Server", "Job") would shadow user-defined resource instances.
-  const byName = new Map<string, ResourceManifest>();
+  // Build outer resource lookup by name for resolution check, collecting
+  // every entry per name so we can surface name collisions as diagnostics
+  // (the kernel's resource registry shares one namespace across all
+  // non-system kinds — e.g. `Telo.Application HelloApi` and `Http.Api
+  // HelloApi` collide at boot with `ERR_DUPLICATE_RESOURCE`. Catching it
+  // statically removes a class of "everything analyzes clean, then the
+  // kernel refuses to start" surprises.)
+  //
+  // Telo.Import is excluded from the duplicate check on top of the
+  // SYSTEM_KINDS skip: its `metadata.name` is an alias, not a resource
+  // identity (aliases live in a separate namespace from resources, and
+  // colliding aliases vs. resource names is benign — the alias is only
+  // ever read as a kind prefix).
+  const byNameAll = 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) || r.kind === "Telo.Import") continue;
+    const name = r.metadata.name as string;
+    const existing = byNameAll.get(name);
+    if (existing) existing.push(r);
+    else byNameAll.set(name, [r]);
+  }
+  for (const [name, list] of byNameAll) {
+    if (list.length <= 1) continue;
+    const [first, ...rest] = list;
+    const firstLabel = `${first.kind}/${name}`;
+    for (const dup of rest) {
+      diagnostics.push({
+        severity: DiagnosticSeverity.Error,
+        code: "DUPLICATE_RESOURCE_NAME",
+        source: SOURCE,
+        message: `${dup.kind}/${name}: resource name collides with ${firstLabel} declared earlier (kernel runtime would fail with ERR_DUPLICATE_RESOURCE)`,
+        data: {
+          resource: { kind: dup.kind, name },
+          filePath: (dup.metadata as { source?: string } | undefined)?.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
+  // added (resolution still finds *something*; the duplicate diagnostic
+  // is what surfaces the underlying problem to the user).
+  const byName = new Map<string, ResourceManifest>();
+  for (const [name, list] of byNameAll) byName.set(name, list[0]);
 
   for (const r of resources) {
     if (!r.metadata?.name || !r.kind || SYSTEM_KINDS.has(r.kind)) continue;
@@ -145,6 +180,38 @@ export function validateReferences(
       for (const { value: val, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
         if (!val) continue;
 
+        // `!ref <name>` sentinel — bare resource name marked at parse time as a
+        // reference. Look it up against the slot's x-telo-ref constraint exactly
+        // like the legacy bare-string path; the only difference is the value's
+        // shape (a TaggedSentinel rather than a raw string), which removed the
+        // string/inline ambiguity at the source.
+        if (isRefSentinel(val)) {
+          const refName = val.source;
+          const target =
+            byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
+          if (!target) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "UNRESOLVED_REFERENCE",
+              source: SOURCE,
+              message: `${resourceLabel}: reference at '${concretePath}' → resource '${refName}' not found`,
+              data: { resource: resourceData, filePath, path: concretePath },
+            });
+            continue;
+          }
+          const kindErrors = checkKind(target.kind as string, entry, registry, aliases);
+          if (kindErrors.length > 0) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "REFERENCE_KIND_MISMATCH",
+              source: SOURCE,
+              message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+              data: { resource: resourceData, filePath, path: concretePath },
+            });
+          }
+          continue;
+        }
+
         // Name-only reference (plain string) — look up by name to validate.
         // Qualified references use "Kind.Name" format (e.g. "Http.Api.PaymentApi");
         // extract the resource name from the last dot segment.