@telorun/analyzer 0.44.0 → 0.46.0

package/src/index.ts

@@ -24,10 +24,23 @@ export {
     type ReExportSpec,
 } from "./flatten-for-analyzer.js";
 export { buildEvalPaths, evalPathCovers } from "./eval-paths.js";
+export {
+  applyObservedStateNode,
+  buildObservedStateIndex,
+  buildObservedStateResourcesSchema,
+  collectRunReachableNames,
+  observedStateRead,
+  validateObservedStateDeclarations,
+  OBSERVED_STATE_SCHEMA,
+} from "./validate-observed-state.js";
+export type { AnalyzedResource, ObservedStateRead } from "./validate-observed-state.js";
+export { moduleScopedDefResolver, scopeResolverForModule } from "./alias-resolver.js";
+export type { ModuleScopes } from "./alias-resolver.js";
 export {
   ancestorChain,
   controllerBearingAncestor,
   effectiveAuthorSchema,
+  effectiveStatusSchema,
   hasOwnControllerOrTemplate,
   inheritedCapability,
   isInheritedDelegation,
@@ -60,6 +73,14 @@ 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 {
+  compareModuleVersions,
+  compareParsedModuleVersions,
+  isNewerModuleVersion,
+  isSameModuleVersion,
+  parseModuleVersion,
+} from "./module-version-order.js";
+export type { ParsedModuleVersion } from "./module-version-order.js";
 export { reconcileModuleVersions } from "./reconcile-module-versions.js";
 export type { VersionReconciliation } from "./reconcile-module-versions.js";
 export { residualEntrySchema, residualEntrySchemaMap } from "./residual-schema.js";
@@ -86,6 +107,8 @@ export { parseModuleRef, isRegistryRef } from "./sources/module-ref.js";
 export type { ParsedModuleRef } from "./sources/module-ref.js";
 export { OCI_SCHEME, isOciRef, parseOciRef } from "./sources/oci-ref.js";
 export type { ParsedOciRef } from "./sources/oci-ref.js";
+export { parseVersionedRef, withRefVersion } from "./sources/versioned-ref.js";
+export type { ParsedVersionedRef } from "./sources/versioned-ref.js";
 export { isLocalPathSource } from "./sources/local-path-ref.js";
 export {
   MANIFEST_CACHE_BASE_URL,

package/src/kernel-globals.ts

@@ -1,5 +1,6 @@
 import type { ResourceManifest } from "@telorun/sdk";
 import { residualEntrySchemaMap } from "./residual-schema.js";
+import { applyObservedStateNode } from "./validate-observed-state.js";
 
 /**
  * Kernel global names available in every CEL evaluation context at runtime.
@@ -36,6 +37,11 @@ const SYSTEM_KINDS = new Set([
  */
 export function buildKernelGlobalsSchema(
   manifests: ResourceManifest[],
+  /** Every resource a CEL read can name, including scope-declared ones (see
+   *  `buildObservedStateIndex`). Kinds that declare a `status:` get a typed,
+   *  closed `status` node; every other resource node stays open, so no flat read
+   *  that passes today can start failing. */
+  resources?: ReadonlyMap<string, { kind: string; status?: Record<string, any> }>,
 ): Record<string, any> {
   const moduleManifest =
     (manifests.find((m) => m.kind === "Telo.Application") as
@@ -55,6 +61,20 @@ export function buildKernelGlobalsSchema(
       resourceProps[name] = { type: "object", additionalProperties: true };
     }
   }
+  // Scope-declared resources (a `Run.Sequence`'s `with:`) publish like any other
+  // now, so their names resolve too — inside the scope's regions, which is where
+  // the only expressions that can name them live.
+  for (const [key, entry] of resources ?? []) {
+    if (key.includes(".")) continue;
+    resourceProps[key] ??= { type: "object", additionalProperties: true };
+    if (entry.status) applyObservedStateNode(resourceProps, key, entry.status);
+  }
+  // Imports' exported instances publish two levels deep (`resources.<Alias>.<name>`);
+  // the alias node stays open so its other keys keep resolving.
+  for (const [key, entry] of resources ?? []) {
+    if (!key.includes(".") || !entry.status) continue;
+    applyObservedStateNode(resourceProps, key, entry.status);
+  }
 
   return {
     type: "object",

package/src/module-version-order.ts

@@ -0,0 +1,91 @@
+/** SemVer precedence for module versions — the single ordering rule shared by
+ *  version reconciliation and by any host deciding whether an import is behind.
+ *
+ *  Pure and dependency-free (no `semver` package), so the analyzer stays
+ *  browser-safe and the editor can reach the same rule the kernel-side analysis
+ *  uses. A caller that cannot parse a version must not guess: an OCI digest, a
+ *  moving tag like `latest`, and a malformed pin all come back `null` rather
+ *  than being ordered by some weaker fallback. */
+
+export interface ParsedModuleVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  /** Dot-separated prerelease identifiers, or `null` for a release version. */
+  pre: string[] | null;
+}
+
+/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
+ *  isn't a plain three-part numeric core — an unparseable version is never
+ *  silently ordered. */
+export function parseModuleVersion(raw: string | undefined): ParsedModuleVersion | null {
+  if (typeof raw !== "string") return null;
+  const v = raw.startsWith("v") ? raw.slice(1) : raw;
+  const [core, ...preParts] = v.split("-");
+  const pre = preParts.length > 0 ? preParts.join("-") : null;
+  const segments = core.split(".");
+  if (segments.length !== 3) return null;
+  const [major, minor, patch] = segments.map((s) => {
+    if (!/^\d+$/.test(s)) return NaN;
+    return Number(s);
+  });
+  if ([major, minor, patch].some((n) => Number.isNaN(n))) return null;
+  return { major, minor, patch, pre: pre === null ? null : pre.split(".") };
+}
+
+/** SemVer precedence: numeric core, then a release outranks a prerelease, then
+ *  prerelease identifiers compared field-by-field (numeric < non-numeric per
+ *  spec, shorter set loses when all shared fields are equal). */
+export function compareParsedModuleVersions(
+  a: ParsedModuleVersion,
+  b: ParsedModuleVersion,
+): number {
+  if (a.major !== b.major) return a.major - b.major;
+  if (a.minor !== b.minor) return a.minor - b.minor;
+  if (a.patch !== b.patch) return a.patch - b.patch;
+  if (a.pre === null && b.pre === null) return 0;
+  if (a.pre === null) return 1;
+  if (b.pre === null) return -1;
+  const len = Math.max(a.pre.length, b.pre.length);
+  for (let i = 0; i < len; i++) {
+    const ai = a.pre[i];
+    const bi = b.pre[i];
+    if (ai === undefined) return -1;
+    if (bi === undefined) return 1;
+    const an = /^\d+$/.test(ai);
+    const bn = /^\d+$/.test(bi);
+    if (an && bn) {
+      const d = Number(ai) - Number(bi);
+      if (d !== 0) return d;
+    } else if (an !== bn) {
+      return an ? -1 : 1;
+    } else if (ai !== bi) {
+      return ai < bi ? -1 : 1;
+    }
+  }
+  return 0;
+}
+
+/** Negative / zero / positive when both versions parse, `null` when either does
+ *  not. The string-in convenience over {@link compareParsedModuleVersions}. */
+export function compareModuleVersions(a: string, b: string): number | null {
+  const left = parseModuleVersion(a);
+  const right = parseModuleVersion(b);
+  if (!left || !right) return null;
+  return compareParsedModuleVersions(left, right);
+}
+
+/** True when `candidate` is strictly newer than `current` — the test for
+ *  whether an import is behind. False when they are equal, when `current` is
+ *  ahead (a version index can lag the module's own origin, and "upgrading" to
+ *  what it knows would be a downgrade), or when either side is unparseable. */
+export function isNewerModuleVersion(candidate: string, current: string): boolean {
+  return (compareModuleVersions(candidate, current) ?? 0) > 0;
+}
+
+/** True when two tags name the same version, tolerating a `v` prefix on either
+ *  side. Falls back to exact equality for unparseable tags, so a digest still
+ *  matches itself. */
+export function isSameModuleVersion(a: string, b: string): boolean {
+  return a === b || compareModuleVersions(a, b) === 0;
+}

package/src/reconcile-module-versions.ts

@@ -1,5 +1,10 @@
 import type { ImportEdge, LoadedModule } from "./loaded-types.js";
 import { isModuleKind } from "./module-kinds.js";
+import {
+  compareParsedModuleVersions,
+  parseModuleVersion,
+  type ParsedModuleVersion,
+} from "./module-version-order.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -17,72 +22,17 @@ export interface VersionReconciliation {
   diagnostics: AnalysisDiagnostic[];
 }
 
-interface ParsedVersion {
-  major: number;
-  minor: number;
-  patch: number;
-  /** Dot-separated prerelease identifiers, or `null` for a release version. */
-  pre: string[] | null;
-}
-
 interface ModuleIdentity {
   source: string;
   identity: string;
   version: string;
-  parsed: ParsedVersion | null;
+  /** `null` for an unparseable version, which forces the group onto the
+   *  conflict path — we never silently hoist across a version we can't reason
+   *  about. */
+  parsed: ParsedModuleVersion | null;
   text: string;
 }
 
-/** Parse `X.Y.Z`, `vX.Y.Z`, or `X.Y.Z-pre.1`. Returns `null` for anything that
- *  isn't a plain three-part numeric core — an unparseable version forces the
- *  group onto the conflict path (we never silently hoist across a version we
- *  can't reason about). Pure: no dependency on the `semver` package, so the
- *  analyzer stays browser-safe and dependency-free. */
-function parseVersion(raw: string | undefined): ParsedVersion | null {
-  if (typeof raw !== "string") return null;
-  const v = raw.startsWith("v") ? raw.slice(1) : raw;
-  const [core, ...preParts] = v.split("-");
-  const pre = preParts.length > 0 ? preParts.join("-") : null;
-  const segments = core.split(".");
-  if (segments.length !== 3) return null;
-  const [major, minor, patch] = segments.map((s) => {
-    if (!/^\d+$/.test(s)) return NaN;
-    return Number(s);
-  });
-  if ([major, minor, patch].some((n) => Number.isNaN(n))) return null;
-  return { major, minor, patch, pre: pre === null ? null : pre.split(".") };
-}
-
-/** SemVer precedence: numeric core, then a release outranks a prerelease, then
- *  prerelease identifiers compared field-by-field (numeric < non-numeric per
- *  spec, shorter set loses when all shared fields are equal). */
-function compareVersions(a: ParsedVersion, b: ParsedVersion): number {
-  if (a.major !== b.major) return a.major - b.major;
-  if (a.minor !== b.minor) return a.minor - b.minor;
-  if (a.patch !== b.patch) return a.patch - b.patch;
-  if (a.pre === null && b.pre === null) return 0;
-  if (a.pre === null) return 1;
-  if (b.pre === null) return -1;
-  const len = Math.max(a.pre.length, b.pre.length);
-  for (let i = 0; i < len; i++) {
-    const ai = a.pre[i];
-    const bi = b.pre[i];
-    if (ai === undefined) return -1;
-    if (bi === undefined) return 1;
-    const an = /^\d+$/.test(ai);
-    const bn = /^\d+$/.test(bi);
-    if (an && bn) {
-      const d = Number(ai) - Number(bi);
-      if (d !== 0) return d;
-    } else if (an !== bn) {
-      return an ? -1 : 1;
-    } else if (ai !== bi) {
-      return ai < bi ? -1 : 1;
-    }
-  }
-  return 0;
-}
-
 /** The location identity of an import ref: the ref with its version stripped.
  *  Two refs share an identity when they address the same module at different
  *  versions, whatever transport owns them:
@@ -133,7 +83,7 @@ function moduleIdentityOf(mod: LoadedModule, identity: string): ModuleIdentity |
     source: mod.owner.source,
     identity,
     version,
-    parsed: parseVersion(version),
+    parsed: parseModuleVersion(version),
     text: mod.owner.text,
   };
 }
@@ -158,7 +108,7 @@ function resolveGroup(members: ModuleIdentity[]): GroupResolution {
   const winner = members.reduce((best, cur) => {
     if (!cur.parsed) return best;
     if (!best.parsed) return cur;
-    const cmp = compareVersions(cur.parsed, best.parsed);
+    const cmp = compareParsedModuleVersions(cur.parsed, best.parsed);
     if (cmp > 0) return cur;
     if (cmp === 0 && cur.source < best.source) return cur;
     return best;

package/src/sources/versioned-ref.ts

@@ -0,0 +1,77 @@
+import { splitIntegrity } from "./integrity.js";
+import { isRegistryRef } from "./module-ref.js";
+import { OCI_SCHEME } from "./oci-ref.js";
+
+/** A module ref split into the parts an upgrade needs: the version-independent
+ *  ref, the version segment it currently names, and any inline pin. */
+export interface ParsedVersionedRef {
+  /** The ref with its `@version` segment and integrity fragment removed —
+   *  `std/run`, `oci://ghcr.io/telorun/timer`. This is the identity a version
+   *  list is keyed by (the hub registers modules under exactly this form). */
+  baseRef: string;
+  /** The version segment, raw — a registry `@version`, an OCI tag, or an OCI
+   *  digest reference (`sha256:…`). The caller applies its own SemVer check. */
+  version: string;
+  /** Telo's inline `sha256-<base64url>` pin, when the ref carried one. */
+  integrity?: string;
+}
+
+/** Split a versioned module ref. Returns `null` when the ref names no
+ *  upgradeable version — a local path, a bare `https://` URL, or an OCI ref
+ *  with no explicit reference (an implicit `latest` is not a pin).
+ *
+ *  Browser-safe and transport-neutral: this is the *grammar* half of an
+ *  upgrade, shared by the kernel transports (whose `refVersion` / `withVersion`
+ *  delegate here) and the editor, which cannot use a transport at all — the
+ *  *network* half (enumerating versions) is scheme-specific and stays behind
+ *  `Transport.listVersions` on Node and the hub's `/module/versions` in the
+ *  browser. */
+export function parseVersionedRef(ref: string): ParsedVersionedRef | null {
+  const { base, integrity } = splitIntegrity(ref);
+  const at = versionSeparator(base);
+  if (at === null) return null;
+  const version = base.slice(at + 1);
+  if (!version) return null;
+  return { baseRef: base.slice(0, at), version, integrity };
+}
+
+/** `ref` rewritten to name `version`, dropping any integrity fragment (the
+ *  caller re-pins the result). Appends the version when the ref carries none —
+ *  an untagged `oci://host/repo` is still a versionable address.
+ *
+ *  Throws when the ref's grammar has no version segment at all — a relative
+ *  path, a bare `https://` URL. Producing `../lib@0.4.0` for those would write
+ *  a ref nothing can resolve, so this fails where the transport-specific
+ *  parsers it replaced (`parseOciRef` / `parseModuleRef`) also failed. */
+export function withRefVersion(ref: string, version: string): string {
+  const { base } = splitIntegrity(ref);
+  if (refGrammar(base) === null) {
+    throw new Error(
+      `Cannot set a version on '${ref}' — only registry (namespace/name@version) ` +
+        `and oci:// refs carry a version segment.`,
+    );
+  }
+  const at = versionSeparator(base);
+  return `${at === null ? base : base.slice(0, at)}@${version}`;
+}
+
+/** Which versionable ref grammar `base` is written in, or `null` when it is
+ *  neither — a relative/absolute path, a `file:`/`https://` URL. */
+function refGrammar(base: string): "oci" | "registry" | null {
+  if (base.startsWith(OCI_SCHEME)) {
+    // A host alone is not addressable; the repo path is what carries a version.
+    return base.indexOf("/", OCI_SCHEME.length) > OCI_SCHEME.length ? "oci" : null;
+  }
+  // `isRegistryRef` requires the `@`, so a version-less `std/console` is not a
+  // registry ref by this test — matching `parseModuleRef`, which throws on it.
+  return isRegistryRef(base) ? "registry" : null;
+}
+
+/** Index of the `@` that separates the version, or `null` when the ref names
+ *  none. Split on the LAST `@` so a digest reference (`repo@sha256:…`) keeps
+ *  everything before it as the ref. */
+function versionSeparator(base: string): number | null {
+  if (refGrammar(base) === null) return null;
+  const at = base.lastIndexOf("@");
+  return at > (base.startsWith(OCI_SCHEME) ? OCI_SCHEME.length : 0) ? at : null;
+}