@telorun/analyzer 0.14.0 → 0.16.0

package/dist/validate-references.js

@@ -4,7 +4,6 @@ import { isInlineResource, resolveFieldEntries, resolveFieldValues } from "./ref
 import { navigateJsonPointer } from "./schema-compat.js";
 import { REF_VALIDATION_SKIP_KINDS as SYSTEM_KINDS } from "./system-kinds.js";
 import { DiagnosticSeverity } from "./types.js";
-import { isModuleKind } from "./module-kinds.js";
 const SOURCE = "telo-analyzer";
 /**
  * Checks whether `kind` satisfies the ref constraint in `entry`.
@@ -99,33 +98,37 @@ export function validateReferences(resources, context) {
     // Forwarded foreign exports (an imported library's exported instances, carrying a
     // metadata.module that isn't a root module) are resolution TARGETS only: excluded from
     // duplicate detection and local name resolution, and never walked as ref sources.
-    const rootModules = new Set();
-    for (const r of resources) {
-        if (isModuleKind(r.kind) && typeof r.metadata?.name === "string") {
-            rootModules.add(r.metadata.name);
-        }
-    }
     const moduleOf = (r) => r.metadata?.module;
-    const isForeign = (r) => {
-        const mod = moduleOf(r);
-        return typeof mod === "string" && !rootModules.has(mod);
-    };
+    // Forwarded exports are flagged by flattenForAnalyzer (`metadata.forwardedExport`); they're
+    // cross-module resolution targets only — excluded from duplicate detection and local name
+    // resolution, and never walked as ref sources.
+    const isForeign = (r) => r.metadata?.forwardedExport === true;
+    // Forwarded exported instances keyed `${module}\0${name}` — the lookup that resolves
+    // whether a cross-module `!ref Alias.name` names a real exported instance.
     const byModuleName = new Map();
+    /** Modules whose import subtree was actually loaded in this analysis. A resolved
+     *  `Telo.Import` carries `resolvedModuleName` (stamped only once the edge — and thus the
+     *  imported module — resolved); forwarded exports carry `metadata.module`. Either marks
+     *  the module loaded independent of how many instances it exports, so a loaded library
+     *  that exports nothing still reports invalid cross-module refs, while partial single-file
+     *  analysis (neither present) is skipped to avoid false `UNRESOLVED_REFERENCE`. */
+    const loadedModules = new Set();
     for (const r of resources) {
+        if (r.kind === "Telo.Import") {
+            const m = r.metadata?.resolvedModuleName;
+            if (typeof m === "string")
+                loadedModules.add(m);
+            continue;
+        }
         if (!r.metadata?.name || SYSTEM_KINDS.has(r.kind) || !isForeign(r))
             continue;
-        byModuleName.set(`${moduleOf(r)}\0${r.metadata.name}`, r);
+        const m = moduleOf(r);
+        if (!m)
+            continue;
+        byModuleName.set(`${m}\0${r.metadata.name}`, r);
+        loadedModules.add(m);
     }
-    /** Whether the analysis set actually carries the named module's exported instances.
-     *  False in partial single-file analysis (the import subtree wasn't loaded) — used to
-     *  skip cross-module resolution checks rather than emit false `UNRESOLVED_REFERENCE`. */
-    const moduleLoaded = (module) => {
-        const prefix = `${module}\0`;
-        for (const key of byModuleName.keys())
-            if (key.startsWith(prefix))
-                return true;
-        return false;
-    };
+    const moduleLoaded = (module) => loadedModules.has(module);
     const localResources = resources.filter((r) => !isForeign(r));
     const byNameAll = new Map();
     const seen = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/analyzer",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Telo Analyzer - Static manifest validator for Telo manifests.",
   "keywords": [
     "telo",
@@ -42,15 +42,16 @@
     "ajv-formats": "^3.0.1",
     "jsonpath-plus": "^10.3.0",
     "yaml": "^2.8.3",
-    "@telorun/templating": "0.4.0"
+    "@telorun/templating": "0.4.1"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "@telorun/sdk": "0.17.0"
   },
   "peerDependencies": {
-    "@telorun/sdk": "0.13.0"
+    "@telorun/sdk": "*"
   },
   "scripts": {
     "build": "tsc -p tsconfig.lib.json",

package/src/alias-resolver.ts

@@ -11,6 +11,15 @@ export class AliasResolver {
     }
   }
 
+  /** 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
+   *  upstream by `flattenForAnalyzer` (only exported instances are forwarded), so a name
+   *  that isn't exported simply won't be found. */
+  moduleForAlias(alias: string): string | undefined {
+    return this.importAliases.get(alias);
+  }
+
   /** Resolves "Http.Api" → "http-server.Api". Returns undefined if alias is unknown. */
   resolveKind(kind: string): string | undefined {
     if (!kind) {

package/src/analyzer.ts

@@ -621,6 +621,11 @@ export class StaticAnalyzer {
       }
     }
     const aliasesByModule = ctx?.aliasesByModule ?? new Map<string, AliasResolver>();
+    // Per-module-scope seen aliases for DUPLICATE_IMPORT_ALIAS. Authored
+    // Telo.Import docs and synthetic-from-inline-`imports:` share one alias
+    // namespace per module, so a repeat — across either form — is an error
+    // rather than the silent last-writer-wins the resolver would otherwise do.
+    const seenAliasByScope = new Map<string, Set<string>>();
     for (const m of manifests) {
       if (isModuleKind(m.kind)) {
         const namespace = ((m.metadata as any).namespace as string | undefined) ?? null;
@@ -633,16 +638,19 @@ export class StaticAnalyzer {
         // through the same alias machinery as user-declared Telo.Imports —
         // honours the library's `exports.kinds` list, no special cases.
         if (moduleName) {
-          const exportedKinds: string[] = ((m as any).exports?.kinds as string[] | undefined) ?? [];
+          // `Self` resolves the library's own kinds UNGATED — a library may reference
+          // its own kinds regardless of `exports.kinds`, which gates importers, not
+          // internal use. This is what lets a library declare an instance of a kind it
+          // does not export (e.g. console's `writeLine`) to enforce a singleton.
           if (rootModules.has(moduleName)) {
-            aliases.registerImport("Self", moduleName, exportedKinds);
+            aliases.registerImport("Self", moduleName, []);
           } else {
             let libResolver = aliasesByModule.get(moduleName);
             if (!libResolver) {
               libResolver = new AliasResolver();
               aliasesByModule.set(moduleName, libResolver);
             }
-            libResolver.registerImport("Self", moduleName, exportedKinds);
+            libResolver.registerImport("Self", moduleName, []);
           }
         }
       }
@@ -656,6 +664,35 @@ export class StaticAnalyzer {
           | null
           | undefined;
         const ownModule = (m.metadata as { module?: string } | undefined)?.module;
+        if (alias) {
+          const scopeKey = ownModule ?? "";
+          let seen = seenAliasByScope.get(scopeKey);
+          if (!seen) {
+            seen = new Set<string>();
+            seenAliasByScope.set(scopeKey, seen);
+          }
+          if (seen.has(alias)) {
+            diagnostics.push({
+              severity: DiagnosticSeverity.Error,
+              code: "DUPLICATE_IMPORT_ALIAS",
+              source: SOURCE,
+              message:
+                `Duplicate import alias '${alias}'. An alias may be declared once per module — ` +
+                `across both inline 'imports:' entries and 'Telo.Import' documents. ` +
+                `Rename or remove the duplicate.`,
+              data: {
+                resource: { kind: "Telo.Import", name: alias },
+                filePath: (m.metadata as { source?: string } | undefined)?.source,
+                path: "metadata.name",
+              },
+            });
+            // Keep the first alias→target mapping intact; don't re-register the
+            // duplicate (last-writer-wins would shadow the original and cascade
+            // misleading follow-on diagnostics).
+            continue;
+          }
+          seen.add(alias);
+        }
         if (alias && source) {
           const targetModule =
             resolvedModuleName ?? source.split("/").filter(Boolean).pop() ?? source;
@@ -825,6 +862,15 @@ export class StaticAnalyzer {
         continue;
       }
 
+      // Forwarded exports (flagged by flattenForAnalyzer) are an imported library's exported
+      // instances, already validated in their own module's standalone analysis; their
+      // `kind`/CEL are authored in that module's scope (e.g. `Self.X` → that module, not the
+      // consumer). Re-validating against the consumer's scope yields false UNDEFINED_KIND /
+      // scope-mismatch errors, so skip — they participate here only as resolution targets.
+      if ((m.metadata as { forwardedExport?: boolean } | undefined)?.forwardedExport === true) {
+        continue;
+      }
+
       const resource = { kind: m.kind, name: m.metadata?.name as string };
 
       // Resolve kind through alias if needed; direct lookup takes priority so that
@@ -1196,7 +1242,14 @@ export class StaticAnalyzer {
     );
   }
 
-  normalize(manifests: ResourceManifest[], registry: AnalysisRegistry): ResourceManifest[] {
+  normalize(
+    manifests: ResourceManifest[],
+    registry: AnalysisRegistry,
+    // Forwarded foreign exports used only as cross-module resolution targets (see
+    // resolveRefSentinels). The kernel passes its analyzer-flattened set so the
+    // entry-only runtime pass can still resolve `!ref Alias.name`.
+    crossModuleTargets?: ResourceManifest[],
+  ): ResourceManifest[] {
     const ctx = registry._context();
     const normalized = normalizeInlineResources(
       manifests,
@@ -1207,7 +1260,13 @@ 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);
+    resolveRefSentinels(
+      normalized,
+      ctx.definitions!,
+      ctx.aliases,
+      ctx.aliasesByModule,
+      crossModuleTargets ?? [],
+    );
     return normalized;
   }
 

package/src/builtins.ts

@@ -301,6 +301,37 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
+        // Inline imports — name-keyed map sugar for separate `Telo.Import`
+        // documents. The key is the PascalCase alias (the import's
+        // `metadata.name`). Each value is either a bare source string
+        // (shorthand for `{ source }`) or the full object form. The loader
+        // desugars each entry into a synthetic `Telo.Import` before discovery;
+        // authored `Telo.Import` docs keep working alongside this. See
+        // analyzer/nodejs/src/inline-imports.ts.
+        imports: {
+          type: "object",
+          additionalProperties: {
+            oneOf: [
+              { type: "string" },
+              {
+                type: "object",
+                required: ["source"],
+                properties: {
+                  source: { type: "string" },
+                  variables: { type: "object" },
+                  secrets: { type: "object" },
+                  runtime: {
+                    oneOf: [
+                      { type: "string" },
+                      { type: "array", items: { type: "string" } },
+                    ],
+                  },
+                },
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
         // Application-level environment contract. Each entry layers `env:`
         // (required, names the source env var) and `default:` (optional, used
         // when the env var is unset) on top of an open JSON Schema property
@@ -394,10 +425,43 @@ export const KERNEL_BUILTINS: ResourceDefinition[] = [
           type: "array",
           items: { type: "string" },
         },
+        // Inline imports — same name-keyed map sugar as Telo.Application; the
+        // loader desugars each entry into a synthetic Telo.Import. See the
+        // Application schema above and analyzer/nodejs/src/inline-imports.ts.
+        imports: {
+          type: "object",
+          additionalProperties: {
+            oneOf: [
+              { type: "string" },
+              {
+                type: "object",
+                required: ["source"],
+                properties: {
+                  source: { type: "string" },
+                  variables: { type: "object" },
+                  secrets: { type: "object" },
+                  runtime: {
+                    oneOf: [
+                      { type: "string" },
+                      { type: "array", items: { type: "string" } },
+                    ],
+                  },
+                },
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
         exports: {
           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.
+            resources: {
+              type: "array",
+              items: { type: "string", not: { enum: ["variables", "secrets"] } },
+            },
           },
           additionalProperties: true,
         },

package/src/flatten-for-analyzer.ts

@@ -44,6 +44,10 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
       if (!targetModule) continue;
 
       const stamped = collectModuleManifests(targetModule);
+      const libDoc = stamped.find((m) => isModuleKind(m.kind));
+      const exportedResources = new Set<string>(
+        (libDoc as { exports?: { resources?: string[] } } | undefined)?.exports?.resources ?? [],
+      );
       for (const m of stamped) {
         if (
           m.kind === "Telo.Definition" ||
@@ -51,6 +55,22 @@ export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
           m.kind === "Telo.Import"
         ) {
           result.push(m);
+        } else if (
+          !isModuleKind(m.kind) &&
+          typeof m.metadata?.name === "string" &&
+          exportedResources.has(m.metadata.name as string)
+        ) {
+          // Forward instances listed in the library's `exports.resources` so the
+          // consumer's analyzer can resolve, gate, kind-check, and draw topology edges
+          // for cross-module `!ref Alias.name`. The gate IS this forwarding — only
+          // exported names cross the boundary. `metadata.forwardedExport` marks them as
+          // cross-module resolution targets only (keyed by `metadata.module`), so ref
+          // resolution / validation treats them as targets, never as local sources to
+          // re-validate or walk.
+          result.push({
+            ...m,
+            metadata: { ...m.metadata, forwardedExport: true } as ResourceManifest["metadata"],
+          });
         }
       }
     }

package/src/index.ts

@@ -25,6 +25,8 @@ export { isModuleKind, MODULE_KINDS } from "./module-kinds.js";
 export type { ModuleKind } from "./module-kinds.js";
 export { parseLoadedFile } from "./parse-loaded-file.js";
 export type { ParseOptions } from "./parse-loaded-file.js";
+export { desugarLoadedFile, inlineImportManifests } from "./inline-imports.js";
+export type { SyntheticImport } from "./inline-imports.js";
 export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
 export {
     buildDocumentPositions,

package/src/inline-imports.ts

@@ -0,0 +1,130 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { LoadedFile } from "./loaded-types.js";
+import { isModuleKind } from "./module-kinds.js";
+import type { DocumentPosition } from "./position-metadata.js";
+import type { PositionIndex } from "./types.js";
+
+/** A synthetic `Telo.Import` produced by desugaring an `imports:` map entry,
+ *  paired with the position metadata that pins its diagnostics back to the
+ *  authoring line in the module document. */
+export interface SyntheticImport {
+  manifest: ResourceManifest;
+  position: DocumentPosition;
+}
+
+/**
+ * Desugar a module document's inline `imports:` map into synthetic
+ * `Telo.Import` manifests. Each entry value is either a bare source string
+ * (shorthand for `{ source }`) or the full object form carrying
+ * `variables` / `secrets` / `runtime`. Malformed entries (object without a
+ * string `source`) are skipped here — the module document's own schema
+ * validation reports them against the precise `imports.<Alias>.source` path.
+ *
+ * The synthetic manifests are indistinguishable from authored `Telo.Import`
+ * documents downstream (alias registration, discovery, the kernel's
+ * import-controller), so the feature is purely additive at the declaration
+ * site. Pure and browser-safe — no I/O, no Node built-ins.
+ */
+export function inlineImportManifests(
+  moduleManifest: ResourceManifest,
+  modulePosition: DocumentPosition | undefined,
+): SyntheticImport[] {
+  const raw = (moduleManifest as { imports?: unknown }).imports;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return [];
+
+  const out: SyntheticImport[] = [];
+  for (const [alias, value] of Object.entries(raw as Record<string, unknown>)) {
+    const scalar = typeof value === "string";
+    const entry = scalar
+      ? { source: value as string }
+      : value && typeof value === "object" && !Array.isArray(value)
+        ? (value as Record<string, unknown>)
+        : undefined;
+    if (!entry || typeof entry.source !== "string") continue;
+
+    const manifest = {
+      kind: "Telo.Import",
+      metadata: { name: alias },
+      source: entry.source,
+      ...(entry.variables !== undefined ? { variables: entry.variables } : {}),
+      ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
+      ...(entry.runtime !== undefined ? { runtime: entry.runtime } : {}),
+    } as unknown as ResourceManifest;
+
+    out.push({ manifest, position: synthPosition(modulePosition, alias, scalar) });
+  }
+  return out;
+}
+
+/** Returns a copy of `file` with synthetic `Telo.Import` manifests (from the
+ *  module document's inline `imports:` map) appended to `manifests` and
+ *  `positions`. `documents` is intentionally left untouched: it is the raw
+ *  YAML-AST array round-trip consumers pair by index, and a synthetic import
+ *  has no backing node. Every flatten/discovery loop iterates `manifests` and
+ *  indexes `positions[i]` — never `documents[i]` in lockstep — so the trailing
+ *  synthetics are visible to resolution while the AST round-trip stays intact.
+ *  Returns `file` unchanged when there is no module doc or no inline imports. */
+export function desugarLoadedFile(file: LoadedFile): LoadedFile {
+  let moduleIndex = -1;
+  for (let i = 0; i < file.manifests.length; i++) {
+    const m = file.manifests[i];
+    if (m && isModuleKind(m.kind)) {
+      moduleIndex = i;
+      break;
+    }
+  }
+  if (moduleIndex < 0) return file;
+
+  const synthetic = inlineImportManifests(file.manifests[moduleIndex]!, file.positions[moduleIndex]);
+  if (synthetic.length === 0) return file;
+
+  return {
+    ...file,
+    manifests: [...file.manifests, ...synthetic.map((s) => s.manifest)],
+    positions: [...file.positions, ...synthetic.map((s) => s.position)],
+  };
+}
+
+/** Build a `DocumentPosition` for a synthetic import by re-rooting the module
+ *  document's `imports.<Alias>` position subtree at the import manifest's own
+ *  paths (`source`, `variables.*`, `metadata.name`, …). This makes a
+ *  diagnostic on the synthetic's `source` land on the `imports:` entry's
+ *  authoring line rather than a phantom document. */
+function synthPosition(
+  modulePosition: DocumentPosition | undefined,
+  alias: string,
+  scalar: boolean,
+): DocumentPosition {
+  if (!modulePosition) return { sourceLine: 0, positionIndex: new Map() };
+
+  const base = modulePosition.positionIndex;
+  const index: PositionIndex = new Map();
+
+  const keyRange = base.get(`@key:imports.${alias}`);
+  const valueRange = base.get(`imports.${alias}`);
+
+  if (keyRange) {
+    index.set("metadata.name", keyRange);
+    index.set("@key:metadata.name", keyRange);
+  }
+
+  if (scalar) {
+    // `Console: std/console@1.2.3` — the entry value IS the source scalar.
+    if (valueRange) index.set("source", valueRange);
+  } else {
+    const valuePrefix = `imports.${alias}.`;
+    const keyPrefix = `@key:imports.${alias}.`;
+    for (const [path, range] of base) {
+      if (path.startsWith(valuePrefix)) {
+        index.set(path.slice(valuePrefix.length), range);
+      } else if (path.startsWith(keyPrefix)) {
+        index.set(`@key:${path.slice(keyPrefix.length)}`, range);
+      }
+    }
+  }
+
+  if (valueRange) index.set("", valueRange);
+
+  const sourceLine = (keyRange ?? valueRange)?.start.line ?? modulePosition.sourceLine;
+  return { sourceLine, positionIndex: index };
+}

package/src/manifest-loader.ts

@@ -10,6 +10,7 @@ import type {
   LoadedGraph,
   LoadedModule,
 } from "./loaded-types.js";
+import { desugarLoadedFile } from "./inline-imports.js";
 import { isModuleKind } from "./module-kinds.js";
 import { parseLoadedFile } from "./parse-loaded-file.js";
 import {
@@ -26,6 +27,14 @@ const SYSTEM_KINDS = new Set([
   "Telo.Definition",
 ]);
 
+/** File cache variant tags: compile (c/r) × desugarImports (d/n). A desugared
+ *  and a raw load of the same file are distinct entries so neither sees the
+ *  wrong manifest tree. */
+const CACHE_VARIANTS = ["rn", "rd", "cn", "cd"] as const;
+function variantKey(options?: LoadOptions): string {
+  return `${options?.compile ? "c" : "r"}${options?.desugarImports ? "d" : "n"}`;
+}
+
 export class Loader {
   /** LoadedFile cache keyed by `${compile ? "compiled" : "raw"}:${source}`.
    *  Same dual-keying as the legacy ResourceManifest[] cache: a compile-mode
@@ -100,29 +109,25 @@ export class Loader {
    *  private mutable copy must call `parseLoadedFile` directly with the
    *  LoadedFile's `text`. */
   async loadFile(url: string, options?: LoadOptions): Promise<LoadedFile> {
-    const compileKey = options?.compile ? "compiled" : "raw";
+    const variant = variantKey(options);
     const knownSource = this.urlToSource.get(url);
     if (knownSource) {
-      const cached = this.fileCache.get(`${compileKey}:${knownSource}`);
+      const cached = this.fileCache.get(`${variant}:${knownSource}`);
       if (cached) return cached;
-      // The other compile-mode entry is cached — reparse from its text
+      // Another variant of this source is cached — reparse from its text
       // instead of re-reading the source.
       //
       // NOTE for watch-mode reactivation (cli/nodejs/src/commands/run.ts
       // currently has `setupWatchMode` commented out): this branch
       // assumes file contents don't change underneath a single Loader.
       // Reviving watch mode will need a public `invalidate(url)` (or
-      // similar) that drops both `urlToSource[url]` and the cached
-      // entries for its canonical source before the loader serves the
-      // file again.
-      const altKey = `${compileKey === "compiled" ? "raw" : "compiled"}:${knownSource}`;
-      const alt = this.fileCache.get(altKey);
-      if (alt) {
-        const reparsed = parseLoadedFile(knownSource, url, alt.text, {
-          compile: options?.compile,
-          celEnv: this.celEnv,
-        });
-        this.fileCache.set(`${compileKey}:${knownSource}`, reparsed);
+      // similar) that drops both `urlToSource[url]` and every cached
+      // variant entry for its canonical source before the loader serves
+      // the file again.
+      const altText = this.findCachedText(knownSource);
+      if (altText !== undefined) {
+        const reparsed = this.parseAndMaybeDesugar(knownSource, url, altText, options);
+        this.fileCache.set(`${variant}:${knownSource}`, reparsed);
         return reparsed;
       }
     }
@@ -135,16 +140,41 @@ export class Loader {
     // for that exact URL — hit the urlToSource fast path instead of
     // falling through to a redundant `pick(url).read(url)`.
     this.urlToSource.set(source, source);
-    const cacheKey = `${compileKey}:${source}`;
+    const cacheKey = `${variant}:${source}`;
     const cached = this.fileCache.get(cacheKey);
     if (cached && cached.text === text) return cached;
 
-    const loaded = parseLoadedFile(source, url, text, {
+    const loaded = this.parseAndMaybeDesugar(source, url, text, options);
+    this.fileCache.set(cacheKey, loaded);
+    return loaded;
+  }
+
+  /** Parse `text` into a LoadedFile, then desugar inline `imports:` when the
+   *  caller opted in. Desugaring lives here, not in the pure `parseLoadedFile`,
+   *  so round-trip consumers (the editor) keep a raw manifest/AST/position
+   *  triple they can pair by index; only resolved consumers that pass
+   *  `desugarImports` see synthetic Telo.Import manifests. */
+  private parseAndMaybeDesugar(
+    source: string,
+    requestedUrl: string,
+    text: string,
+    options?: LoadOptions,
+  ): LoadedFile {
+    const loaded = parseLoadedFile(source, requestedUrl, text, {
       compile: options?.compile,
       celEnv: this.celEnv,
     });
-    this.fileCache.set(cacheKey, loaded);
-    return loaded;
+    return options?.desugarImports ? desugarLoadedFile(loaded) : loaded;
+  }
+
+  /** Raw text of any already-cached variant for `source`, so a cache miss on
+   *  one (compile, desugar) variant reparses without a second source read. */
+  private findCachedText(source: string): string | undefined {
+    for (const v of CACHE_VARIANTS) {
+      const cached = this.fileCache.get(`${v}:${source}`);
+      if (cached) return cached.text;
+    }
+    return undefined;
   }
 
   /** Load an owner file plus every partial reachable through its `include:`
@@ -382,12 +412,13 @@ export class Loader {
    *  via parent-directory traversal. */
   async loadGraphForFile(
     fileUrl: string,
+    options?: LoadOptions,
   ): Promise<{ graph: LoadedGraph; ownerUrl: string } | null> {
     try {
-      const owner = await this.loadFile(fileUrl);
+      const owner = await this.loadFile(fileUrl, options);
       const isOwner = owner.manifests.some((m) => m && isModuleKind(m.kind));
       if (isOwner) {
-        const graph = await this.loadGraph(fileUrl);
+        const graph = await this.loadGraph(fileUrl, options);
         return { graph, ownerUrl: graph.rootSource };
       }
     } catch (err) {
@@ -404,7 +435,7 @@ export class Loader {
     if (!source.resolveOwnerOf) return null;
     const ownerUrl = await source.resolveOwnerOf(fileUrl);
     if (!ownerUrl) return null;
-    const graph = await this.loadGraph(ownerUrl);
+    const graph = await this.loadGraph(ownerUrl, options);
     return { graph, ownerUrl: graph.rootSource };
   }