@telorun/analyzer 0.11.0 → 0.12.1

package/src/validate-references.ts

@@ -1,17 +1,13 @@
 import type { ResourceManifest } from "@telorun/sdk";
-import { isRefEntry, isScopeEntry, isSchemaFromEntry, isInlineResource, resolveFieldValues, type RefFieldEntry } from "./reference-field-map.js";
+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,88 @@ 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).
+  // Group manifests by name to detect collisions. Two subtleties:
+  //
+  //   1. Some analyzer hosts emit the SAME physical document twice through
+  //      their pipeline — e.g. the telo-editor's `toAnalysisManifests` walks
+  //      each workspace module's documents independently, and a file
+  //      reachable from two angles (entry module + `include:` partial)
+  //      shows up twice. The fingerprint includes `sourceLine` so identical
+  //      docs (same kind, name, source, AND source line) collapse to one,
+  //      while two textually-separate documents in the same file (different
+  //      source lines) keep separate fingerprints and trip the diagnostic.
+  //   2. The diagnostic carries a precomputed `range` pointing at the
+  //      duplicate's source line — editor hosts that resolve diagnostic
+  //      positions via a `${file}::${kind}::${name}` lookup would otherwise
+  //      collide on duplicates (Map.set overwrites) and place the squiggle
+  //      ambiguously. The explicit `range` short-circuits that lookup.
+  // Dedup pipeline echoes — the same physical document emitted twice
+  // through an analyzer host's pipeline. Keyed on (kind, name, source,
+  // sourceLine), so two textually-distinct docs in the same file (same
+  // 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.
+  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)) 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;
+    // `analyze()` guarantees both fields are present on non-system manifests.
+    const meta = r.metadata as unknown as { source: string; sourceLine: number };
+    const fingerprint = `${r.kind} ${name} ${meta.source} ${meta.sourceLine}`;
+    if (seen.has(fingerprint)) continue;
+    seen.add(fingerprint);
+    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) {
+      const dupMeta = dup.metadata as { source?: string; sourceLine?: number } | undefined;
+      const range =
+        typeof dupMeta?.sourceLine === "number"
+          ? {
+              start: { line: dupMeta.sourceLine, character: 0 },
+              end: { line: dupMeta.sourceLine, character: Number.MAX_SAFE_INTEGER },
+            }
+          : undefined;
+      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)`,
+        ...(range ? { range } : {}),
+        data: {
+          resource: { kind: dup.kind, name },
+          filePath: dupMeta?.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;
@@ -142,9 +213,41 @@ export function validateReferences(
         }
       }
 
-      for (const val of resolveFieldValues(r, fieldPath)) {
+      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.
@@ -166,8 +269,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "UNRESOLVED_REFERENCE",
               source: SOURCE,
-              message: `${resourceLabel}: reference at '${fieldPath}' → resource '${val}' not found`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
             continue;
           }
@@ -177,8 +280,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "REFERENCE_KIND_MISMATCH",
               source: SOURCE,
-              message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
           }
           continue;
@@ -196,8 +299,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "INVALID_REFERENCE",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' must have string 'kind' and 'name' fields`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' must have string 'kind' and 'name' fields`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -209,8 +312,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "REFERENCE_KIND_MISMATCH",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' → ${kindErrors.join("; ")}`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' → ${kindErrors.join("; ")}`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
 
@@ -223,8 +326,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "UNRESOLVED_REFERENCE",
             source: SOURCE,
-            message: `${resourceLabel}: reference at '${fieldPath}' → resource '${refVal.name}' not found`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: reference at '${concretePath}' → resource '${refVal.name}' not found`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
       }
@@ -317,7 +420,7 @@ export function validateReferences(
           continue;
         }
 
-        for (const fieldValue of resolveFieldValues(r, fieldPath)) {
+        for (const { value: fieldValue, path: concretePath } of resolveFieldEntries(r, fieldPath)) {
           if (fieldValue == null) continue;
           const issues = registry.validateWithRefs(fieldValue, subSchema as Record<string, any>);
           for (const issue of issues) {
@@ -325,8 +428,8 @@ export function validateReferences(
               severity: DiagnosticSeverity.Error,
               code: "DEPENDENT_SCHEMA_MISMATCH",
               source: SOURCE,
-              message: `${resourceLabel}: '${fieldPath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
-              data: { resource: resourceData, filePath, path: fieldPath },
+              message: `${resourceLabel}: '${concretePath}' does not match schema from '${anchorName}${jsonPointer}': ${issue}`,
+              data: { resource: resourceData, filePath, path: concretePath },
             });
           }
         }
@@ -347,10 +450,10 @@ export function validateReferences(
       const anchorValues = resolveFieldValues(r, anchorPath);
       if (anchorValues.length === 0) continue; // anchor field not set — nothing to validate
 
-      const fieldValues = resolveFieldValues(r, fieldPath);
+      const fieldEntries = resolveFieldEntries(r, fieldPath);
 
-      for (let i = 0; i < fieldValues.length; i++) {
-        const fieldValue = fieldValues[i];
+      for (let i = 0; i < fieldEntries.length; i++) {
+        const { value: fieldValue, path: concretePath } = fieldEntries[i];
         if (fieldValue == null) continue;
 
         // For absolute paths, the single anchor applies to all field values.
@@ -367,8 +470,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "SCHEMA_FROM_MISSING_PATH",
             source: SOURCE,
-            message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -379,8 +482,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "SCHEMA_FROM_MISSING_PATH",
             source: SOURCE,
-            message: `${resourceLabel}: x-telo-schema-from at '${fieldPath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: x-telo-schema-from at '${concretePath}' → kind '${refVal.kind}' has no schema path '${jsonPointer}'`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
           continue;
         }
@@ -391,8 +494,8 @@ export function validateReferences(
             severity: DiagnosticSeverity.Error,
             code: "DEPENDENT_SCHEMA_MISMATCH",
             source: SOURCE,
-            message: `${resourceLabel}: '${fieldPath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
-            data: { resource: resourceData, filePath, path: fieldPath },
+            message: `${resourceLabel}: '${concretePath}' does not match schema from '${refVal.kind}${jsonPointer}': ${issue}`,
+            data: { resource: resourceData, filePath, path: concretePath },
           });
         }
       }

package/src/with-synthetic-positions.ts

@@ -0,0 +1,48 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import { REF_VALIDATION_SKIP_KINDS } from "./system-kinds.js";
+
+/**
+ * Stamp `metadata.source` and `metadata.sourceLine` on every non-system
+ * manifest that lacks them, returning a new array with cloned `metadata`
+ * objects for the affected entries.
+ *
+ * `StaticAnalyzer.analyze()` requires position info on every non-system
+ * manifest (the dedup that backs `DUPLICATE_RESOURCE_NAME` reads
+ * `(source, sourceLine)` to distinguish pipeline echoes from real
+ * collisions). Production callers — the `Loader`, `flattenForAnalyzer`,
+ * the telo-editor's `emitDocsFor`, the VSCode extension — all stamp
+ * positions already. This helper is the escape hatch for **programmatic
+ * callers** (tests, ad-hoc scripts) that construct `ResourceManifest`
+ * literals without going through a loader: it gives every otherwise-naked
+ * manifest a synthetic, deterministic position so the analyzer's
+ * invariant holds without each test having to spell positions out.
+ *
+ * The synthetic source defaults to `"<programmatic>"` — override via
+ * `source` when a stable, recognisable label helps diagnostic output.
+ * Each unstamped manifest gets a unique `sourceLine` (1-based array
+ * index) so two real duplicates supplied without positions retain
+ * distinct fingerprints and still trip `DUPLICATE_RESOURCE_NAME`.
+ *
+ * Manifests that already carry `metadata.source` and `metadata.sourceLine`
+ * pass through unchanged.
+ */
+export function withSyntheticPositions(
+  manifests: ResourceManifest[],
+  source: string = "<programmatic>",
+): ResourceManifest[] {
+  return manifests.map((m, i) => {
+    if (REF_VALIDATION_SKIP_KINDS.has(m.kind)) return m;
+    const meta = m.metadata as { source?: string; sourceLine?: number } | undefined;
+    const hasSource = typeof meta?.source === "string" && meta.source.length > 0;
+    const hasLine = typeof meta?.sourceLine === "number";
+    if (hasSource && hasLine) return m;
+    return {
+      ...m,
+      metadata: {
+        ...m.metadata,
+        source: hasSource ? meta!.source : source,
+        sourceLine: hasLine ? meta!.sourceLine : i,
+      },
+    } as ResourceManifest;
+  });
+}