@telorun/analyzer 0.21.0 → 0.23.0

package/dist/validate-reference-forms.js

@@ -0,0 +1,91 @@
+import { isTaggedSentinel } from "@telorun/templating";
+import { visitManifest } from "./manifest-visitor.js";
+import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
+import { DiagnosticSeverity } from "./types.js";
+const SOURCE = "telo-analyzer";
+/**
+ * Reference-form validation — the single enforcement point for "a reference is
+ * written `!ref <name>` (or `!ref <Alias>.<name>`), nothing else".
+ *
+ * Runs on the RAW manifest set, BEFORE inline-resource extraction and `!ref`
+ * sentinel resolution. That ordering is load-bearing: only at this point is an
+ * author-written value still distinguishable from the resolver's own
+ * substitution. After normalization both an author's `{kind, name}` and a
+ * resolved `!ref` are the same `{kind, name}` object, so no later pass — and no
+ * JSON Schema — can tell them apart.
+ *
+ * At every `x-telo-ref` slot the only accepted value is:
+ *   - a `!ref` sentinel (or any tagged sentinel — e.g. a `${{ }}` ref passed
+ *     through a template), or
+ *   - an inline definition: a plain object with a `kind` and NO `name` (the
+ *     extractor assigns the name), or
+ *   - a `${{ }}` CEL expression string (a reference flowed through CEL).
+ *
+ * Rejected, each with an actionable diagnostic pointing at `!ref`:
+ *   - the object form `{ kind, name }` (the old reference object), and
+ *   - a bare string (the old name / dotted-FQN reference).
+ */
+export function validateReferenceForms(resources, registry, aliases, aliasesByModule) {
+    if (!aliases)
+        return [];
+    const diagnostics = [];
+    const isForeign = (r) => r.metadata?.forwardedExport === true;
+    const localResources = resources.filter((r) => !isForeign(r));
+    visitManifest(localResources, registry, {
+        onRef: (e) => {
+            const value = e.value;
+            // `!ref` and `!cel`/`${{ }}` sentinels are the supported shapes.
+            if (isTaggedSentinel(value))
+                return;
+            const r = e.source;
+            const resourceLabel = `${r.kind}/${r.metadata.name}`;
+            const resourceData = { kind: r.kind, name: r.metadata.name };
+            const filePath = r.metadata?.source;
+            const path = e.concretePath;
+            if (typeof value === "string") {
+                // A `${{ }}` reference flowed through CEL is fine; any other bare
+                // string at a ref slot is the removed string / dotted-FQN form.
+                if (value.includes("${{"))
+                    return;
+                diagnostics.push({
+                    severity: DiagnosticSeverity.Error,
+                    code: "INVALID_REFERENCE_FORM",
+                    source: SOURCE,
+                    message: `${resourceLabel}: string reference at '${path}' → '${value}' is not supported; write it as '!ref ${refHint(value)}'`,
+                    data: { resource: resourceData, filePath, path },
+                });
+                return;
+            }
+            if (value && typeof value === "object" && !Array.isArray(value)) {
+                const obj = value;
+                // A plain object is an inline definition unless it names a resource —
+                // a `name` makes it the removed `{ kind, name }` reference object.
+                if (typeof obj.name === "string" && typeof obj.kind === "string") {
+                    diagnostics.push({
+                        severity: DiagnosticSeverity.Error,
+                        code: "INVALID_REFERENCE_FORM",
+                        source: SOURCE,
+                        message: `${resourceLabel}: object reference '{ kind, name }' at '${path}' is not supported; write it as '!ref ${obj.name}'`,
+                        data: { resource: resourceData, filePath, path },
+                    });
+                }
+            }
+        },
+    }, {
+        aliases,
+        aliasesByModule,
+        skipKinds: SYSTEM_KINDS,
+        expand: true,
+        discoverNestedRefs: true,
+    });
+    return diagnostics;
+}
+/** Best-effort name for the `!ref` suggestion in a string-ref diagnostic: a
+ *  dotted-FQN (`Http.Api.UsersApi`) keeps its last segment, an alias-qualified
+ *  name (`Console.writeLine`) is left intact, a bare name passes through. */
+function refHint(value) {
+    const dotCount = (value.match(/\./g) ?? []).length;
+    if (dotCount >= 2)
+        return value.slice(value.lastIndexOf(".") + 1);
+    return value;
+}

package/dist/validate-references.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CAgftB"}
+{"version":3,"file":"validate-references.d.ts","sourceRoot":"","sources":["../src/validate-references.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AA4C/F;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,EAAE,eAAe,GACvB,kBAAkB,EAAE,CA6ctB"}

package/dist/validate-references.js

@@ -272,43 +272,10 @@ export function validateReferences(resources, context) {
                 }
                 return;
             }
-            // 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.
-            if (typeof val === "string") {
-                const lastDot = val.lastIndexOf(".");
-                const refName = lastDot > 0 ? val.slice(lastDot + 1) : val;
-                const refKindPrefix = lastDot > 0 ? val.slice(0, lastDot) : undefined;
-                const target = byName.get(refName) ?? visibleScopeManifests.find((m) => m.metadata?.name === refName);
-                if (!target) {
-                    // Cross-module reference: "Alias.ResourceName" (single dot, bare alias prefix).
-                    // The resource lives in the imported module's scope and can't be validated here.
-                    // Multi-dot prefixes like "Alias.Kind.Name" are local resources with qualified
-                    // kinds — those must be validated.
-                    if (refKindPrefix && !refKindPrefix.includes(".") && aliases.hasAlias(refKindPrefix)) {
-                        return;
-                    }
-                    diagnostics.push({
-                        severity: DiagnosticSeverity.Error,
-                        code: "UNRESOLVED_REFERENCE",
-                        source: SOURCE,
-                        message: `${resourceLabel}: reference at '${concretePath}' → resource '${val}' not found`,
-                        data: { resource: resourceData, filePath, path: concretePath },
-                    });
-                    return;
-                }
-                const kindErrors = checkKind(target.kind, 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 },
-                    });
-                }
-                return;
-            }
+            // Bare strings are no longer a reference shape — `validateReferenceForms`
+            // rejects an author-written string at a ref slot before this pass runs,
+            // and a `${{ }}` reference flowed through CEL is resolved/typed
+            // elsewhere. Anything still a string here is not a reference to resolve.
             if (typeof val !== "object")
                 return;
             const refVal = val;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,7 +42,7 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.7.0"
+    "@telorun/templating": "0.8.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",

package/src/alias-resolver.ts

@@ -3,6 +3,10 @@
 export class AliasResolver {
   private readonly importAliases = new Map<string, string>();
   private readonly importedKinds = new Map<string, Set<string>>();
+  /** `${alias}.${suffix}` → canonical `<owningModule>.<Kind>` for kinds an import
+   *  transitively RE-EXPORTS (`exports.kinds: [Alias.Kind]`), which don't live in the
+   *  import's own module. Resolved before the normal `<module>.<suffix>` construction. */
+  private readonly reExportedKinds = new Map<string, string>();
 
   registerImport(alias: string, targetModule: string, exportedKinds: string[]): void {
     this.importAliases.set(alias, targetModule);
@@ -11,6 +15,12 @@ export class AliasResolver {
     }
   }
 
+  /** Register that `<alias>.<suffix>` re-exports the kind canonically named `canonicalKind`
+   *  (owned by a module the alias's target imports, possibly several hops away). */
+  registerKindReExport(alias: string, suffix: string, canonicalKind: string): void {
+    this.reExportedKinds.set(`${alias}.${suffix}`, canonicalKind);
+  }
+
   /** Real module name an alias points at (e.g. "Console" → "console"), or undefined.
    *  Used to resolve an alias-qualified instance reference "Console.writeLine" to the
    *  forwarded resource declared in that module. The `exports.resources` gate is enforced
@@ -29,6 +39,10 @@ export class AliasResolver {
     if (dot === -1) return undefined;
     const prefix = kind.slice(0, dot);
     const suffix = kind.slice(dot + 1);
+    // Re-export takes precedence: a re-exported kind resolves to its true owning module,
+    // not `${prefix-target}.${suffix}` (and bypasses the gate — it's explicitly re-exported).
+    const reExported = this.reExportedKinds.get(`${prefix}.${suffix}`);
+    if (reExported) return reExported;
     const realModule = this.importAliases.get(prefix);
     if (!realModule) return undefined;
     const allowed = this.importedKinds.get(prefix);

package/src/analyzer.ts

@@ -5,6 +5,7 @@ import { AliasResolver } from "./alias-resolver.js";
 import { AnalysisRegistry } from "./analysis-registry.js";
 import {
   buildCelEnvironment,
+  buildImportInputCelEnvironment,
   buildTypedCelEnvironment,
   type CelHandlers,
 } from "./cel-environment.js";
@@ -36,6 +37,7 @@ import { validateExtends } from "./validate-extends.js";
 import { validateNestedInlineResources } from "./validate-nested-inline.js";
 import { validateProviderCoherence } from "./validate-provider-coherence.js";
 import { validateReferences } from "./validate-references.js";
+import { validateReferenceForms } from "./validate-reference-forms.js";
 import { validateUnusedDeclarations } from "./validate-unused-declarations.js";
 import { validateThrowsCoverage } from "./validate-throws-coverage.js";
 
@@ -705,16 +707,22 @@ export class StaticAnalyzer {
           if (resolvedModuleName) {
             defs.registerModuleIdentity(resolvedNamespace ?? null, resolvedModuleName);
           }
+          // `metadata.reExportedKinds` (stamped by flattenForAnalyzer / the editor projection)
+          // maps an exported suffix to the true owning module's canonical kind for kinds this
+          // import transitively re-exports (`exports.kinds: [Alias.Kind]`).
+          const reExportedKinds = ((m.metadata as any)?.reExportedKinds ?? {}) as Record<
+            string,
+            string
+          >;
           // Alias registration is scoped: consumer imports vs. imported-library imports.
-          if (!ownModule || rootModules.has(ownModule)) {
-            aliases.registerImport(alias, targetModule, exportedKinds);
-          } else {
-            let libResolver = aliasesByModule.get(ownModule);
-            if (!libResolver) {
-              libResolver = new AliasResolver();
-              aliasesByModule.set(ownModule, libResolver);
-            }
-            libResolver.registerImport(alias, targetModule, exportedKinds);
+          const resolver =
+            !ownModule || rootModules.has(ownModule)
+              ? aliases
+              : (aliasesByModule.get(ownModule) ??
+                aliasesByModule.set(ownModule, new AliasResolver()).get(ownModule)!);
+          resolver.registerImport(alias, targetModule, exportedKinds);
+          for (const [suffix, canonical] of Object.entries(reExportedKinds)) {
+            resolver.registerKindReExport(alias, suffix, canonical);
           }
         }
       }
@@ -774,6 +782,15 @@ export class StaticAnalyzer {
       defs.register(normalized);
     }
 
+    // Reference-form validation — enforce `!ref` as the only reference shape.
+    // Runs on the RAW manifests, BEFORE inline extraction and sentinel
+    // resolution, while an author-written `{kind, name}` is still
+    // distinguishable from the resolver's own substitution (after Phase 2/2.5
+    // they are the same object).
+    if (!options?.skipValidation) {
+      diagnostics.push(...validateReferenceForms(manifests, defs, aliases, aliasesByModule));
+    }
+
     // Phase 2: extract inline resources from x-telo-ref slots into first-class manifests
     const allManifests = normalizeInlineResources(manifests, defs, aliases, aliasesByModule);
 
@@ -781,7 +798,7 @@ export class StaticAnalyzer {
     // {kind, name} objects so downstream phases (validation, dependency graph,
     // kernel controllers) see a uniform shape. Runs after normalize so both
     // original and inline-extracted manifests have their sentinels resolved.
-    resolveRefSentinels(allManifests, defs, aliases, aliasesByModule);
+    resolveRefSentinels(allManifests, aliases, aliasesByModule);
 
     // Trusted-input fast path: when the caller has already attested that
     // this exact manifest set passes analysis (e.g. via the kernel's
@@ -854,6 +871,26 @@ export class StaticAnalyzer {
           }
         }
       }
+      // `exports.resources` entries are plain names: `Db` (local) or `Alias.Name` (re-export),
+      // mirroring `exports.kinds`. The `!ref` tag is not accepted here — a `!ref` parses to a
+      // sentinel object that the schema's CEL/ref exemption would silently pass, so reject any
+      // non-string entry with an actionable message instead.
+      const exportsResources = (m as Record<string, any>).exports?.resources;
+      if (Array.isArray(exportsResources)) {
+        for (let i = 0; i < exportsResources.length; i++) {
+          if (typeof exportsResources[i] === "string") continue;
+          diagnostics.push({
+            severity: DiagnosticSeverity.Error,
+            code: "INVALID_EXPORT",
+            source: SOURCE,
+            message:
+              `Telo.Library exports.resources[${i}]: write the exported name as a plain string — ` +
+              `'Name' to export a local instance, or 'Alias.Name' to re-export an imported one. ` +
+              `The '!ref' tag is not allowed in exports.resources.`,
+            data: { resource, filePath, path: `exports.resources.${i}` },
+          });
+        }
+      }
     }
 
     // Build typed kernel globals schema so x-telo-context chain validation
@@ -933,8 +970,27 @@ export class StaticAnalyzer {
                 },
               }
             : definition.schema;
-        // Phase 1: CEL type checking — walk data+schema together, check env.check() return types
-        const baseTypedEnv = buildTypedCelEnvironment(this.celEnv, m, undefined, moduleManifest);
+        // Phase 1: CEL type checking — walk data+schema together, check env.check() return types.
+        // A Telo.Import's variables/secrets are a config-only contract evaluated against the
+        // IMPORTING module's scope, so type them from the owning module doc (matched by
+        // `metadata.module`) and drop `resources`/`env` so referencing them is an error. A
+        // library's own internal import is validated against that library in the library's
+        // standalone analysis; in this flattened app pass the library doc is absent, so the
+        // importer is undefined here and variables/secrets fall back to a permissive `map`
+        // (no false positives) while resources/env stay rejected.
+        const importerModule =
+          m.kind === "Telo.Import"
+            ? allManifests.find(
+                (mm) =>
+                  (mm.kind === "Telo.Application" || mm.kind === "Telo.Library") &&
+                  (mm.metadata as { name?: string } | undefined)?.name ===
+                    (m.metadata as { module?: string } | undefined)?.module,
+              )
+            : undefined;
+        const baseTypedEnv =
+          m.kind === "Telo.Import"
+            ? buildImportInputCelEnvironment(this.celEnv, importerModule)
+            : buildTypedCelEnvironment(this.celEnv, m, undefined, moduleManifest);
         const celIssues = collectCelTypeIssues(
           m,
           schema,
@@ -1286,13 +1342,7 @@ export class StaticAnalyzer {
     // Resolve !ref sentinels after normalize so both the original and
     // inline-extracted manifests get their refs canonicalized to
     // {kind, name} for the kernel that consumes this output.
-    resolveRefSentinels(
-      normalized,
-      ctx.definitions!,
-      ctx.aliases,
-      ctx.aliasesByModule,
-      crossModuleTargets ?? [],
-    );
+    resolveRefSentinels(normalized, ctx.aliases, ctx.aliasesByModule, crossModuleTargets ?? []);
     return normalized;
   }
 

package/src/builtins.ts

@@ -236,7 +236,7 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
               },
               // Gated reference: run() a Runnable/Service only when the
               // `when` CEL guard holds. Discriminated by the `ref` key. `ref`
-              // is a bare name or a resolved `!ref` (`{ kind, name }`).
+              // is a `!ref` that resolves to the `{ kind, name }` shape below.
               {
                 type: "object",
                 required: ["ref"],
@@ -264,12 +264,11 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
               // with an optional `name` (for steps.<name>.result plumbing),
               // `when` guard, and `inputs`. Discriminated by the `invoke` key.
               // Control flow (if/while/switch/try) is not available here —
-              // reach for Run.Sequence. `invoke` is ref-only and must resolve
-              // to a `{ kind, name }` reference (a `!ref` / `{kind,name}`):
-              // requiring `name` rejects an inline `{ kind }` definition (no
-              // name) at analysis instead of failing at boot with an undefined
-              // resource name. The Invocable/Runnable kind set mirrors
-              // Run.Sequence invoke steps.
+              // reach for Run.Sequence. `invoke` is ref-only: a `!ref` that
+              // resolves to the `{ kind, name }` shape below. Requiring `name`
+              // rejects an inline `{ kind }` definition (no name) at analysis
+              // instead of failing at boot with an undefined resource name. The
+              // Invocable/Runnable kind set mirrors Run.Sequence invoke steps.
               {
                 type: "object",
                 required: ["invoke"],
@@ -456,8 +455,10 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "object",
           properties: {
             kinds: { type: "array", items: { type: "string" } },
-            // `variables` / `secrets` are reserved on the resources.<Alias> value-flow
-            // surface, so a library may not export instances under those names.
+            // An entry is a bare name (`Db`, a locally-owned export) or a dotted `Alias.Name`
+            // (re-export of the instance reached via this library's import aliased `Alias`,
+            // under the name `Name`) — mirroring `exports.kinds`. `variables` / `secrets` are
+            // reserved on the resources.<Alias> value-flow surface, so they may not be exported.
             resources: {
               type: "array",
               items: { type: "string", not: { enum: ["variables", "secrets"] } },

package/src/cel-environment.ts

@@ -102,3 +102,60 @@ export function buildTypedCelEnvironment(
     return baseEnv.clone();
   }
 }
+
+/** Register a `variables`/`secrets` namespace typed from a module doc's schema map
+ *  (`{ name: <schema>, … }`), falling back to dyn `map` when absent or untyped. */
+function registerConfigNamespace(
+  env: Environment,
+  block: unknown,
+  name: "variables" | "secrets",
+): void {
+  if (block !== null && typeof block === "object" && !Array.isArray(block)) {
+    const entries = Object.entries(block as Record<string, unknown>).filter(
+      ([, v]) => v !== null && typeof v === "object" && !Array.isArray(v),
+    );
+    if (entries.length > 0) {
+      const schema: Record<string, string> = {};
+      for (const [k, v] of entries) schema[k] = jsonSchemaToCelType(v as Record<string, any>);
+      (env as any).registerVariable({ name, schema });
+      return;
+    }
+  }
+  env.registerVariable(name, "map");
+}
+
+/** CEL environment for the `variables:`/`secrets:` expressions on a `Telo.Import`.
+ *
+ *  Import inputs are a config-only contract: their expressions are evaluated
+ *  against the IMPORTING module's `variables`/`secrets`, never the import's own
+ *  values map (the bug) nor the imported child's. `resources`, `env`, and `ports`
+ *  are registered as empty typed objects, so referencing them is a "No such key"
+ *  error that steers authors to a typed `variables` entry. */
+export function buildImportInputCelEnvironment(
+  baseEnv: Environment,
+  moduleManifest: ResourceManifest | undefined,
+): Environment {
+  const env = baseEnv.clone();
+  for (const brand of Object.keys(VALUE_BRAND_BASE)) {
+    (env as any).registerType(brand, { fields: {} });
+  }
+  const mod = moduleManifest as Record<string, unknown> | undefined;
+  // Typing variables/secrets from the importer's schema can fail on a malformed
+  // schema; degrade those to permissive `map` if so — but never lose the
+  // resources/env/ports rejection registered below (the catch is scoped so a
+  // typing failure can't silently re-open the config-only contract).
+  try {
+    registerConfigNamespace(env, mod?.variables, "variables");
+    registerConfigNamespace(env, mod?.secrets, "secrets");
+  } catch {
+    env.registerVariable("variables", "map");
+    env.registerVariable("secrets", "map");
+  }
+  // Override the base env's dyn `resources`/`env`/`ports` with empty typed objects
+  // so any access (`resources.X`, `env.X`) is a "No such key" error — these
+  // surfaces are not part of the config-only import contract.
+  for (const name of ["resources", "env", "ports"]) {
+    (env as any).registerVariable({ name, schema: {} });
+  }
+  return env;
+}