@telorun/analyzer 0.8.1 → 0.10.0

package/src/flatten-for-analyzer.ts

@@ -0,0 +1,134 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { LoadedFile, LoadedGraph, LoadedModule } from "./loaded-types.js";
+import { isModuleKind } from "./module-kinds.js";
+
+/** Produce the flat manifest list `analyze()` consumes today.
+ *
+ *  Combines the entry module's manifests with `Telo.Definition`,
+ *  `Telo.Abstract`, and `Telo.Import` docs forwarded from imported libraries.
+ *  Stamps three flavours of metadata along the way:
+ *
+ *  - `metadata.source` and `metadata.sourceLine` — already on each manifest
+ *    from `parseLoadedFile`, copied here unchanged.
+ *  - `metadata.module` — the owning module's `Telo.Application` /
+ *    `Telo.Library` `metadata.name`, applied to non-module manifests that
+ *    don't already carry one.
+ *  - `metadata.resolvedModuleName` / `metadata.resolvedNamespace` — for every
+ *    `Telo.Import` manifest, looked up via `graph.importEdges` to find the
+ *    target module's own `Telo.Library` identity. Without this, the
+ *    analyzer's alias resolver and `validate-extends` fall back to
+ *    path-derived identity and produce spurious diagnostics.
+ *
+ *  Position metadata (`positionIndex`) is NOT stamped on manifests —
+ *  callers look it up via `findPositions(graph, ...)` on the LoadedGraph. */
+export function flattenForAnalyzer(graph: LoadedGraph): ResourceManifest[] {
+  const result: ResourceManifest[] = [];
+
+  const stampedEntry = collectModuleManifests(graph.entry);
+  result.push(...stampedEntry);
+
+  const seen = new Set<string>([graph.rootSource]);
+  const queue: string[] = [graph.rootSource];
+
+  while (queue.length > 0) {
+    const fromSource = queue.shift()!;
+    const edges = graph.importEdges.get(fromSource);
+    if (!edges) continue;
+
+    for (const edge of edges.values()) {
+      if (seen.has(edge.targetSource)) continue;
+      seen.add(edge.targetSource);
+      queue.push(edge.targetSource);
+
+      const targetModule = graph.modules.get(edge.targetSource);
+      if (!targetModule) continue;
+
+      const stamped = collectModuleManifests(targetModule);
+      for (const m of stamped) {
+        if (
+          m.kind === "Telo.Definition" ||
+          m.kind === "Telo.Abstract" ||
+          m.kind === "Telo.Import"
+        ) {
+          result.push(m);
+        }
+      }
+    }
+  }
+
+  // Stamp resolved import identity on every Telo.Import in the result by
+  // reading the edge's pre-resolved name/namespace — no re-derivation from
+  // manifest metadata. The edge is keyed by (owner-file, alias) which is
+  // exactly the (metadata.source, metadata.name) pair on each Telo.Import.
+  for (let i = 0; i < result.length; i++) {
+    const m = result[i];
+    if (m.kind !== "Telo.Import") continue;
+    const owner = (m.metadata as { source?: string } | undefined)?.source;
+    const alias = m.metadata?.name as string | undefined;
+    if (!owner || !alias) continue;
+    const edge = graph.importEdges.get(owner)?.get(alias);
+    if (!edge?.targetModuleName) continue;
+
+    const newMetadata: Record<string, unknown> = {
+      ...m.metadata,
+      resolvedModuleName: edge.targetModuleName,
+      resolvedNamespace: edge.targetNamespace,
+    };
+    result[i] = { ...m, metadata: newMetadata as ResourceManifest["metadata"] };
+  }
+
+  return result;
+}
+
+/** Project a LoadedModule (owner + partials) to a flat ResourceManifest[]
+ *  with `metadata.module` stamped on non-module docs. The kernel's runtime
+ *  entry load uses this to convert a `Loader.loadModule` result into the
+ *  classic ResourceManifest[] shape it iterates over. Imports are not
+ *  followed — the kernel's import-controller loads each import's module
+ *  separately at runtime. */
+export function flattenLoadedModule(mod: LoadedModule): ResourceManifest[] {
+  return collectModuleManifests(mod);
+}
+
+function collectModuleManifests(mod: LoadedModule): ResourceManifest[] {
+  const owner = stampFile(mod.owner, ownerModuleName(mod.owner));
+  const partials: ResourceManifest[] = [];
+  for (const p of mod.partials) {
+    partials.push(...stampFile(p, ownerModuleName(mod.owner)));
+  }
+  return [...owner, ...partials];
+}
+
+function ownerModuleName(file: LoadedFile): string | undefined {
+  for (const m of file.manifests) {
+    if (m && isModuleKind(m.kind)) {
+      const name = m.metadata?.name;
+      if (typeof name === "string") return name;
+    }
+  }
+  return undefined;
+}
+
+function stampFile(
+  file: LoadedFile,
+  ownerModule: string | undefined,
+): ResourceManifest[] {
+  const out: ResourceManifest[] = [];
+  for (let i = 0; i < file.manifests.length; i++) {
+    const m = file.manifests[i];
+    if (m === null || m === undefined) continue;
+    const { sourceLine } = file.positions[i];
+
+    const metadata: Record<string, unknown> = {
+      ...m.metadata,
+      source: file.source,
+      sourceLine,
+    };
+    if (ownerModule && !isModuleKind(m.kind) && !metadata.module) {
+      metadata.module = ownerModule;
+    }
+
+    out.push({ ...m, metadata: metadata as ResourceManifest["metadata"] });
+  }
+  return out;
+}

package/src/index.ts

@@ -1,8 +1,26 @@
 export { AnalysisRegistry } from "./analysis-registry.js";
 export { StaticAnalyzer } from "./analyzer.js";
+export type {
+    GraphLoadError,
+    ImportEdge,
+    LoadedFile,
+    LoadedGraph,
+    LoadedModule,
+    ParseError,
+} from "./loaded-types.js";
+export { flattenForAnalyzer, flattenLoadedModule } from "./flatten-for-analyzer.js";
 export { Loader } from "./manifest-loader.js";
 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 {
+    buildDocumentPositions,
+    buildLineOffsets,
+    buildPositionIndex,
+    documentLineOffsets,
+} from "./position-metadata.js";
+export type { DocumentPosition } from "./position-metadata.js";
 export { HttpSource } from "./sources/http-source.js";
 export { RegistrySource } from "./sources/registry-source.js";
 export { DEFAULT_MANIFEST_FILENAME, DiagnosticSeverity } from "./types.js";

package/src/loaded-types.ts

@@ -0,0 +1,86 @@
+import type { ResourceManifest } from "@telorun/sdk";
+import type { Document } from "yaml";
+import type { DocumentPosition } from "./position-metadata.js";
+import type { Range } from "./types.js";
+
+/** One physical file's parsed result. Returned for the owner manifest, for
+ *  each `include:` partial, and for each external import target.
+ *
+ *  Identity rule: every map key, every cross-reference, every editor-side
+ *  cache uses `source` — the URL the source adapter's `read()` returned. */
+export interface LoadedFile {
+  /** Canonical identity. The URL the source adapter's `read()` returned —
+   *  HTTPS for http/registry, an absolute path for local. */
+  source: string;
+  /** The URL the caller supplied (e.g. registry ref `std/javascript@0.3.0`).
+   *  Differs from `source` only for adapter-resolved URLs. */
+  requestedUrl: string;
+  /** Raw text exactly as `read()` returned it. */
+  text: string;
+  /** Per-document parsed AST, in source order. */
+  documents: Document[];
+  /** Per-document JSON projection (`doc.toJSON()`). Aligned to `documents`. */
+  manifests: Array<ResourceManifest | null>;
+  /** Per-document `{sourceLine, positionIndex}`. Aligned to `documents`. */
+  positions: DocumentPosition[];
+  /** Document-level parse errors aggregated from `yaml.Document.errors`. */
+  parseErrors: ParseError[];
+}
+
+export interface ParseError {
+  documentIndex: number;
+  message: string;
+  /** Line/character of the failure, when the yaml parser provided one. */
+  range?: Range;
+}
+
+/** An owner file plus the partial files it includes. The unit
+ *  `Loader.loadModule` returns. */
+export interface LoadedModule {
+  owner: LoadedFile;
+  /** Each `include:` target as its own LoadedFile. Empty when no `include:`.
+   *  Order matches the `include:` list (after glob expansion). */
+  partials: LoadedFile[];
+}
+
+/** Resolved Telo.Import edge: where the import points and what library
+ *  identity it resolves to. Carrying name/namespace on the edge means
+ *  `flattenForAnalyzer` can stamp `metadata.resolvedModuleName` /
+ *  `resolvedNamespace` from this single source rather than re-deriving
+ *  the target from manifest metadata, which would silently miss whenever
+ *  a future projection forgets to stamp `metadata.source` consistently. */
+export interface ImportEdge {
+  /** Canonical resolved URL of the target — a key into `modules`. */
+  targetSource: string;
+  /** Target library's `metadata.name`, or `null` when the target had no
+   *  Telo.Library doc (an error case captured in `LoadedGraph.errors`). */
+  targetModuleName: string | null;
+  /** Target library's `metadata.namespace` (or `null` when unset). */
+  targetNamespace: string | null;
+}
+
+/** An entry plus every transitively-imported library. Returned by
+ *  `Loader.loadGraph`. */
+export interface LoadedGraph {
+  /** Canonical entry source — equals `entry.owner.source`. */
+  rootSource: string;
+  entry: LoadedModule;
+  /** Map keyed by `LoadedFile.source` (canonical resolved URL). Includes
+   *  entry, partials, and every transitively reachable Telo.Import target +
+   *  its partials. */
+  modules: Map<string, LoadedModule>;
+  /** Per-Telo.Import resolution. Keyed by the resolved URL of the file the
+   *  Telo.Import was declared in, then by the import's PascalCase alias. */
+  importEdges: Map<string, Map<string, ImportEdge>>;
+  /** Surface-level errors that did not abort the graph load (e.g. an import
+   *  whose target failed to fetch). */
+  errors: GraphLoadError[];
+}
+
+export interface GraphLoadError {
+  /** URL of the file that failed to load. */
+  url: string;
+  /** Source of the import that triggered the load, or null for the entry. */
+  fromSource: string | null;
+  error: Error;
+}