@telorun/analyzer 0.65.0 → 0.67.0

package/src/flatten-for-analyzer.ts

@@ -2,6 +2,12 @@ import type { ResourceManifest } from "@telorun/sdk";
 import type { LoadedGraph, LoadedModule } from "./loaded-types.js";
 import type { LoadedFile } from "./loaded-types.js";
 import { isModuleKind } from "./module-kinds.js";
+import {
+  injectedDeclarations,
+  readLibraryLifecycle,
+  readResourceInputs,
+  type ResourceInput,
+} from "./resource-input.js";
 import type { ZoneModuleDocuments } from "./zone-module-documents.js";
 
 /** One parsed `exports.resources` / `exports.kinds` entry. `name` is the exported
@@ -23,7 +29,7 @@ export function parseExportEntry(entry: string): ParsedExportEntry {
 }
 
 /** The import-boundary forwarding rule, shared by `flattenForAnalyzer` (the
- *  CLI / kernel loader path) and the telo-editor's workspace projection so the
+ *  CLI / kernel loader path) and telo studio's workspace projection so the
  *  two cannot drift. Given one module's stamped manifests and whether that
  *  module is the analysis entry (root), returns the manifests that cross into
  *  the consumer's flat analysis list:
@@ -414,6 +420,12 @@ function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void
   // the kernel parses them. A module that declares none is absent, leaving importers ungated
   // (see stampExportedKinds).
   const declaredKinds = new Map<string, readonly string[]>();
+  /** Each library's declared `resources:` block, by module name — the inward
+   *  half, stamped onto its importers below. */
+  const requiredResources = new Map<string, readonly ResourceInput[]>();
+  /** Libraries declaring `lifecycle: shared` — a singleton every import
+   *  resolves to, so a per-import override of it is a contradiction. */
+  const sharedModules = new Set<string>();
   for (const [source, mod] of graph.modules) {
     if (source === graph.rootSource) continue; // root is an Application — no exports
     const libDoc = mod.owner.manifests.find((m) => m && isModuleKind(m.kind)) as
@@ -424,6 +436,9 @@ function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void
     ownerSourceOf.set(moduleName, mod.owner.source);
     specs.push(...reExportSpecsFromExports(moduleName, libDoc.exports?.resources));
     kindModules.push({ module: moduleName, exportsKinds: libDoc.exports?.kinds });
+    const inputs = readResourceInputs(libDoc);
+    if (inputs.length > 0) requiredResources.set(moduleName, inputs);
+    if (readLibraryLifecycle(libDoc) === "shared") sharedModules.add(moduleName);
     if (libDoc.exports?.kinds !== undefined) {
       declaredKinds.set(moduleName, libDoc.exports.kinds.map((e) => parseExportEntry(e).name));
     }
@@ -440,15 +455,100 @@ function forwardReExports(graph: LoadedGraph, result: ResourceManifest[]): void
   // Telo.Import manifests so the analyzer can register the re-export mappings.
   const exportedKinds = resolveExportedKinds(kindModules, aliasToModule);
   const imports: Array<{ manifest: ResourceManifest; targetModule: string }> = [];
+  const sources: Array<{ manifest: ResourceManifest; targetSource: string }> = [];
   for (const m of result) {
     if (m.kind !== "Telo.Import") continue;
     const owner = (m.metadata as { source?: string } | undefined)?.source;
     const alias = m.metadata?.name as string | undefined;
-    const target = owner && alias ? graph.importEdges.get(owner)?.get(alias)?.targetModuleName : undefined;
-    if (target) imports.push({ manifest: m, targetModule: target });
+    const edge = owner && alias ? graph.importEdges.get(owner)?.get(alias) : undefined;
+    if (edge?.targetModuleName) imports.push({ manifest: m, targetModule: edge.targetModuleName });
+    if (edge?.targetSource) sources.push({ manifest: m, targetSource: edge.targetSource });
   }
+  stampResolvedSource(sources);
   stampReExportedKinds(imports, exportedKinds);
   stampExportedKinds(imports, declaredKinds);
+  stampRequiredResources(imports, requiredResources, aliasToModule);
+  stampSharedLifecycle(imports, sharedModules);
+}
+
+/** Stamp `metadata.resolvedSource` — the canonical resolved URL of an import's
+ *  target — onto every `Telo.Import`. It is the identity the kernel keys a
+ *  singleton's registry on, so a check that has to decide whether two imports
+ *  reach the SAME library has to key on it too: `resolvedModuleName` is the
+ *  module's own name, which two versions of it share. */
+export function stampResolvedSource(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetSource: string }>,
+): void {
+  for (const { manifest, targetSource } of imports) {
+    (manifest.metadata as Record<string, unknown>).resolvedSource = targetSource;
+  }
+}
+
+/** Stamp `metadata.sharedLibrary` onto every `Telo.Import` whose target declares
+ *  `lifecycle: shared`, so the consumer's pass can reject the per-import
+ *  overrides a singleton has no room for. Stamped on `metadata` for the same
+ *  reason `exportedKinds` is — the `Telo.Import` schema forbids extra top-level
+ *  fields. */
+export function stampSharedLifecycle(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetModule: string }>,
+  shared: ReadonlySet<string>,
+): void {
+  for (const { manifest, targetModule } of imports) {
+    if (!shared.has(targetModule)) continue;
+    (manifest.metadata as Record<string, unknown>).sharedLibrary = true;
+  }
+}
+
+/** Stamp `metadata.requiredResources` — the target library's declared
+ *  `resources:` block, with each kind constraint CANONICALIZED in the library's
+ *  own alias scope — onto every `Telo.Import` whose target declares one.
+ *
+ *  Canonicalized here because this is the only point where the target's own
+ *  import edges are in hand: the consumer's pass sees the flattened list, from
+ *  which the library doc and its alias scope are both gone, so an entry written
+ *  `Sql.Connection` would otherwise be read against whatever the CONSUMER
+ *  happens to alias `Sql` to. Stamped on `metadata` for the same reason
+ *  `exportedKinds` is — the `Telo.Import` schema forbids extra top-level
+ *  fields. An entry whose alias resolves to nothing is stamped with its kind
+ *  unchanged; `validate-resource-inputs.ts` reports that against the library
+ *  that wrote it. */
+export function stampRequiredResources(
+  imports: ReadonlyArray<{ manifest: ResourceManifest; targetModule: string }>,
+  declared: ReadonlyMap<string, readonly ResourceInput[]>,
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): void {
+  for (const { manifest, targetModule } of imports) {
+    const inputs = declared.get(targetModule);
+    if (!inputs?.length) continue;
+    // A plain name → canonical-kind MAP, deliberately not a list of
+    // `{name, kind}` objects: that shape is character-identical to a resolved
+    // `!ref`, and every reference walk in the analyzer recognises a reference by
+    // exactly those two keys — so the stamp would be read as a malformed
+    // reference sitting in `metadata`.
+    const table: Record<string, string> = {};
+    for (const input of inputs) {
+      table[input.name] = canonicalizeInputKind(input.kind, targetModule, aliasToModule);
+    }
+    (manifest.metadata as Record<string, unknown>).requiredResources = table;
+  }
+}
+
+/** `Alias.Kind` → `<owning module>.Kind` in the DECLARING library's scope.
+ *  `Self.` names the library itself and `Telo.` the kernel built-ins, both of
+ *  which cross no import edge. An unresolvable prefix is returned unchanged. */
+function canonicalizeInputKind(
+  kind: string,
+  ownModule: string,
+  aliasToModule: (module: string, alias: string) => string | undefined,
+): string {
+  const dot = kind.indexOf(".");
+  if (dot <= 0) return kind;
+  const alias = kind.slice(0, dot);
+  const suffix = kind.slice(dot + 1);
+  if (alias === "Self") return `${ownModule}.${suffix}`;
+  if (alias === "Telo") return kind;
+  const module = aliasToModule(ownModule, alias);
+  return module ? `${module}.${suffix}` : kind;
 }
 
 /** Collect every imported library's FULL document set for the zone stage's
@@ -498,7 +598,20 @@ function collectModuleManifests(mod: LoadedModule): ResourceManifest[] {
   for (const p of mod.partials) {
     partials.push(...stampFile(p, ownerModuleName(mod.owner)));
   }
-  return [...owner, ...partials];
+  const all = [...owner, ...partials];
+  // A library's `resources:` block declares the instances it requires from
+  // whoever imports it. Standing a kind-only declaration behind each entry is
+  // what makes `!ref connection` resolve and `resources.connection.<field>` type
+  // in the library's OWN pass — the only pass that sees its internals, since a
+  // consumer's flattened analysis drops the library doc. `selectModuleManifests-
+  // ForAnalysis` drops them again for a non-root module (they are not exported),
+  // and the kernel's import controller filters them out in favour of the
+  // borrowed instance itself.
+  const moduleDoc = all.find((m) => isModuleKind(m.kind));
+  if (moduleDoc) {
+    all.push(...injectedDeclarations(moduleDoc, moduleDoc.metadata?.name as string | undefined));
+  }
+  return all;
 }
 
 function ownerModuleName(file: LoadedFile): string | undefined {

package/src/import-resolution-diagnostics.ts

@@ -46,7 +46,7 @@ function messageFor(e: GraphLoadError, code: ReturnType<typeof classify>): strin
 /**
  * Convert a graph's import failures (`graph.errors`) into structured, coded
  * diagnostics. This is the single source of truth for surfacing a broken
- * import — every host (CLI, VS Code, telo-editor) routes these instead of each
+ * import — every host (CLI, VS Code, telo studio) routes these instead of each
  * re-deriving the channel and drifting (the VS Code extension used to drop it
  * entirely, showing nothing for a broken import).
  *

package/src/index.ts

@@ -21,10 +21,31 @@ export {
     selectModuleManifestsForAnalysis,
     stampExportedKinds,
     stampReExportedKinds,
+    stampRequiredResources,
+    stampResolvedSource,
+    stampSharedLifecycle,
     type ParsedExportEntry,
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
-export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export {
+  buildEvalPaths,
+  celEvalModeAt,
+  celEvalSites,
+  declaresCelRegion,
+  evalPathCovers,
+  mergeCelEvalSites,
+  pathMatchesScope,
+  NO_CEL_EVAL_SITES,
+} from "./eval-paths.js";
+export type { CelEvalSites } from "./eval-paths.js";
+export {
+  injectedDeclarations,
+  isInjectedDeclaration,
+  readLibraryLifecycle,
+  readResourceInputs,
+  readSuppliedResources,
+} from "./resource-input.js";
+export type { LibraryLifecycle, ResourceInput } from "./resource-input.js";
 export {
   BINDINGS_ANNOTATION,
   bindingContextProperties,
@@ -96,8 +117,17 @@ export type {
   ResourceGraphNode,
   StepGraphNode,
 } from "./call-graph.js";
-export { buildReferenceFieldMap, isRefEntry, isScopeEntry } from "./reference-field-map.js";
-export type { ReferenceFieldMap, RefFieldEntry } from "./reference-field-map.js";
+export {
+  buildReferenceFieldMap,
+  isRefEntry,
+  isScopeEntry,
+  satisfiesValueBranch,
+} from "./reference-field-map.js";
+export type {
+  ReferenceFieldMap,
+  RefFieldEntry,
+  ValueBranchValidator,
+} from "./reference-field-map.js";
 export {
   hasDeclaredUse,
   isRefSlot,
@@ -181,6 +211,8 @@ export {
   readRawResourceRules,
   resolveRuleSubjects,
   findDynamicLeaf,
+  dynamicNode,
+  type DynamicLeaf,
   type ResourceRule,
   type ResourceRuleSeverity,
   type RuleSubject,
@@ -211,11 +243,32 @@ export {
   type ReferrerRuleIssue,
   type ReferrerRuleFinding,
   type ReferrerRuleDiagnostic,
+  type ReferrerRuleContext,
+  type ReferrerRuleDeclarationContext,
 } from "./validate-referrer-rules.js";
-export { RULE_BUDGET_MS } from "./rule-condition.js";
+export {
+  PeerBinder,
+  analyzerPeerBinder,
+  analyzerPeersTarget,
+  entryBoundary,
+  navigatePath,
+  referenceValueOf,
+  shapeMatches,
+  type DeclarationLookup,
+  type PeerAliasScope,
+  type PeerBinderEnv,
+  type PeerBinderRegistry,
+  type PeerBinding,
+  type PeerBindingFailure,
+  type PeerBindingResult,
+  type PeersTarget,
+} from "./peer-binding.js";
+export { RULE_BUDGET_MS, UNTAGGED_CONDITION } from "./rule-condition.js";
 export {
   readSchemaProjection,
+  type ProjectionReference,
   readSchemaMap,
+  schemaMapBranch,
   readProjectionFrom,
   readProjectionRef,
   manifestListScope,

package/src/inline-imports.ts

@@ -54,6 +54,7 @@ export function inlineImportManifests(
       source,
       ...(entry.variables !== undefined ? { variables: entry.variables } : {}),
       ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
+      ...(entry.resources !== undefined ? { resources: entry.resources } : {}),
       ...(entry.runtime !== undefined ? { runtime: entry.runtime } : {}),
       ...(entry.logging !== undefined ? { logging: entry.logging } : {}),
     } as unknown as ResourceManifest;

package/src/manifest-visitor.ts

@@ -16,6 +16,8 @@ import {
   type RefFieldEntry,
   type SchemaFromFieldEntry,
 } from "./reference-field-map.js";
+import type { ModuleScopes } from "./alias-resolver.js";
+import { templateBodies, withTemplateSelf } from "./template-body.js";
 import { extractContextsFromSchema, pathMatchesScope } from "./validate-cel-context.js";
 
 /**
@@ -150,6 +152,10 @@ export interface VisitOptions {
    *  Opt-in: the validators / dependency graph must NOT enable it (those refs
    *  are runtime-resolved, not boot dependencies). */
   discoverNestedRefs?: boolean;
+  /** Root (consumer-owned) module names, paired with `aliasesByModule` so a
+   *  nested kind inside an imported library's definition resolves through THAT
+   *  library's aliases. */
+  rootModules?: ReadonlySet<string>;
 }
 
 /** Synthetic entry for a value-tree-discovered ref — these carry no declared
@@ -204,6 +210,15 @@ const pathUnderPrefix = (fieldPath: string, prefix: string): boolean =>
   fieldPath.startsWith(prefix + ".") ||
   fieldPath.startsWith(prefix + "[");
 
+/** The per-declaring-module alias tables, when the caller threaded them. A
+ *  nested kind inside an imported library's definition is written through THAT
+ *  library's aliases. */
+function moduleScopes(options: VisitOptions): ModuleScopes | undefined {
+  return options.aliasesByModule && options.rootModules
+    ? { aliasesByModule: options.aliasesByModule, rootModules: options.rootModules }
+    : undefined;
+}
+
 export function visitManifest(
   resources: ResourceManifest[],
   registry: DefinitionRegistry,
@@ -359,7 +374,32 @@ export function visitManifest(
     }
 
     if (wantsCel) {
-      const contexts = definition?.schema ? extractContextsFromSchema(definition.schema) : [];
+      // The INHERITANCE-RESOLVED schema: an `extends` child is authored against
+      // merge(parent, own), so a context region the parent declares is in force
+      // on the child. Reading the child's own schema typed the region on
+      // whichever kind happened to declare it and left every descendant's
+      // expressions unchecked — silently, which for a typing rule means the
+      // check simply stops existing.
+      const authorSchema = registry.effectiveSchemaOf(definition);
+      const contexts = authorSchema ? extractContextsFromSchema(authorSchema) : [];
+      // A `Telo.Definition`'s `resources:` entries are DECLARATIONS of another
+      // kind, so the CEL inside one belongs to THAT kind — its own
+      // `x-telo-context` regions, rebased under the entry's path. `self` is
+      // merged into each, since the nested kind knows nothing about the
+      // configuration its enclosing template was given. Without this a nested
+      // body saw one fixed permissive context: `inputs` and `item` undefined
+      // wherever the nested kind declares them, `error` offered everywhere.
+      for (const body of templateBodies(r, registry, aliases, moduleScopes(options))) {
+        const bodySchema = registry.effectiveSchemaOf(body.definition);
+        if (!bodySchema) continue;
+        for (const ctx of extractContextsFromSchema(bodySchema, body.scopePrefix)) {
+          contexts.push({ scope: ctx.scope, schema: withTemplateSelf(ctx.schema) });
+        }
+      }
+      // Longest scope wins, as `extractContextsFromSchema` already orders its
+      // own: a nested kind's region is deeper than the enclosing definition's
+      // blanket `$.resources[*]`, so it takes precedence.
+      contexts.sort((a, b) => b.scope.length - a.scope.length);
       walkCelExpressions(r, "", (expr, path, engineName, surface) => {
         let contextSchema: Record<string, any> | undefined;
         let matchedScope: string | undefined;

package/src/migrations/entries/index.ts

@@ -2,9 +2,11 @@
 // Source: analyzer/migrations/*.json (lexically ordered).
 import e0 from "./normalize-value-types.json" with { type: "json" };
 import e1 from "./ref-slot-scalar-type.json" with { type: "json" };
+import e2 from "./schema-prepare-bucket.json" with { type: "json" };
 
 /** Every entry file, in the order the driver applies them. */
 export const MIGRATION_ENTRY_FILES: ReadonlyArray<readonly [file: string, data: unknown]> = [
   ["normalize-value-types.json", e0],
   ["ref-slot-scalar-type.json", e1],
+  ["schema-prepare-bucket.json", e2],
 ];

package/src/migrations/entries/schema-prepare-bucket.json

@@ -0,0 +1,27 @@
+{
+  "$comment": "`inKind` names the two backend schema kinds by their canonical `<module>.<Kind>` spelling, which is what a document's `kind:` carries after alias resolution. `under` is the key itself: the bucket is a top-level field of the resource, so the region and the match are the same node \u2014 the tightest containment this vocabulary can state. NAMING A MODULE'S KIND FROM A CORE ENTRY IS A DEBT, not a pattern: it is the one place the analyzer knows a standard-library kind by name. It is contained because `inKind` is a filter \u2014 an entry naming an absent kind matches nothing \u2014 and it MOVES into `modules/postgres` and `modules/sqlite` when the module-migration surface lands. Do not add another; see analyzer/migrations/README.md.",
+  "id": "schema-prepare-bucket",
+  "code": "SQL_BEFORE_MIGRATIONS_RENAMED",
+  "severity": "warning",
+  "reason": "`beforeMigrations:` is now `prepare:`. Every documented use of it was data preparation for a narrowing the reconciliation pass is about to attempt \u2014 backfill before NOT NULL, make values fit before a length reduction, convert before a non-widening type change \u2014 and each is what a refusal already tells the author to write. The old name said where it ran relative to the OTHER bucket; the new one says what it is for, which is what those refusals need to name. Nothing re-runs: the ledger stores the migration key alone, so moving an entry between the two maps changes no history.",
+  "rules": [
+    {
+      "match": {
+        "key": "beforeMigrations",
+        "inKind": [
+          "Postgres.Schema",
+          "SQLite.Schema"
+        ],
+        "under": [
+          "beforeMigrations"
+        ]
+      },
+      "patch": [
+        {
+          "op": "rename-key",
+          "to": "prepare"
+        }
+      ]
+    }
+  ]
+}