@telorun/analyzer 0.67.0 → 0.69.0

package/src/index.ts

@@ -84,15 +84,19 @@ export {
   isInheritedDelegation,
   mappingFieldFor,
   needsContractMapping,
+  publishedOwnFields,
   resolveParent,
 } from "./extends-resolution.js";
 export type { ContractDirection, DefResolver } from "./extends-resolution.js";
+export { validateSensitiveSlots } from "./validate-sensitive-slots.js";
+export type { SensitiveSlotIssue } from "./validate-sensitive-slots.js";
 export {
   defaultBearingPaths,
   declaredScalarPaths,
   PERMISSIVE_CONTRACT,
   resolveContract,
   resolveContractSchema,
+  sensitivePaths,
   withLiveValuesSkipped,
 } from "./invocation-contract.js";
 export type {
@@ -108,7 +112,13 @@ export {
   RedactionPathError,
 } from "./redaction-path.js";
 export type { RedactionSegment } from "./redaction-path.js";
-export { buildCallGraph, projectToPairs, resourceId } from "./call-graph.js";
+export {
+  buildCallGraph,
+  nodeIdFor,
+  projectToPairs,
+  resolveScopedName,
+  resourceId,
+} from "./call-graph.js";
 export type {
   BuildCallGraphOptions,
   CallGraph,
@@ -117,6 +127,31 @@ export type {
   ResourceGraphNode,
   StepGraphNode,
 } from "./call-graph.js";
+export {
+  AMBIENT_CAPABILITIES,
+  buildModuleGraph,
+  contentKey,
+  edgeClassOf,
+  isAmbientCapability,
+  isAmbientHold,
+  isOrderedRow,
+  isUnwired,
+} from "./module-graph.js";
+export type {
+  BuildModuleGraphOptions,
+  EdgeClass,
+  GraphEdge,
+  GraphKind,
+  GraphNode,
+  GraphPort,
+  GraphRegion,
+  GraphRow,
+  ModuleGraph,
+  ModuleGraphDeps,
+  NodeOwnership,
+  PortSlot,
+  RowKind,
+} from "./module-graph.js";
 export {
   buildReferenceFieldMap,
   isRefEntry,
@@ -300,7 +335,12 @@ export { validateDynamicSelectors, validateRefSlotDeclarations } from "./validat
 export type { RefSlotIssue } from "./validate-ref-slots.js";
 export { validateValueTypeSlots } from "./validate-value-type-slots.js";
 export type { ValueTypeSlotIssue } from "./validate-value-type-slots.js";
-export { checkSchemaCompatibility, resolveRefIn, selectUnionBranch } from "./schema-compat.js";
+export {
+  checkSchemaCompatibility,
+  collectProperties,
+  resolveRefIn,
+  selectUnionBranch,
+} from "./schema-compat.js";
 export type { CompatibilityResult, ExternalSchemaResolver } from "./schema-compat.js";
 export {
   ajvErrorToPath,
@@ -358,7 +398,6 @@ export {
 } 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 { defaultSources } from "./sources/default-sources.js";
 export {
   splitIntegrity,
@@ -369,8 +408,6 @@ export {
   sha256Base64Url,
   IntegrityError,
 } from "./sources/integrity.js";
-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";

package/src/invocation-contract.ts

@@ -334,6 +334,77 @@ export function defaultBearingPaths(
   return out;
 }
 
+/** Every path in `schema` the author marked `x-telo-sensitive: true` — the
+ *  values a trace payload must carry as `[redacted]` rather than verbatim.
+ *
+ *  It exists because making a credential a dispatched `Telo.Invocable` turns its
+ *  material into an invoke OUTPUT, and invoke inputs and outputs ride the debug
+ *  wire on every call under `--inspect` — which is every watch session. The
+ *  kernel's substring scrubbing does not reach them: it has one call site, the
+ *  resource-Created event's properties.
+ *
+ *  Declared by the kind that OWNS the contract, so the kernel names no kind and
+ *  any module opts in — the `x-telo-eval` shape. Exempting "an Http.Credential
+ *  result" directly would be kind-knowledge in the kernel, and would stop at
+ *  that one kind while the same token surfaces wherever else a contract carries
+ *  it.
+ *
+ *  Bounded by the schema's declarations exactly as {@link defaultBearingPaths}
+ *  is: a contract marking nothing walks nothing at dispatch. The key is kept and
+ *  only the value replaced, per the logging spec §14 — a payload that silently
+ *  loses a key reads as a value that was never produced. */
+export function sensitivePaths(
+  schema: Record<string, any>,
+  resolveRef?: (ref: string) => Record<string, any> | undefined,
+): string[][] {
+  const out: string[][] = [];
+
+  const walk = (node: unknown, path: string[], chain: readonly object[]): void => {
+    if (!node || typeof node !== "object") return;
+    let s = node as Record<string, any>;
+    if (chain.includes(s)) return;
+    if (resolveRef && typeof s.$ref === "string") {
+      const target = resolveRef(s.$ref);
+      if (!target || chain.includes(target)) return;
+      s = { ...target, ...s, $ref: undefined };
+    }
+    const here = [...chain, node as object];
+
+    // A marked node is redacted WHOLE, so there is nothing below it to mark:
+    // descending would emit paths into a value that is already gone. The EMPTY
+    // path is legal and means the whole value — a contract whose entire output
+    // is the secret is the simplest shape there is, and refusing it silently
+    // (which `path.length > 0` did) left exactly that case unredacted.
+    if (s["x-telo-sensitive"] === true) {
+      out.push(path);
+      return;
+    }
+
+    const properties = s.properties as Record<string, any> | undefined;
+    if (properties) {
+      for (const [key, child] of Object.entries(properties)) walk(child, [...path, key], here);
+    }
+    // A map whose VALUES are secrets — `additionalProperties: {x-telo-sensitive}`
+    // — is the shape a headers or query bag takes, and it carries no property
+    // names to walk. `{}` is the wildcard segment, the `[]` precedent one axis
+    // over.
+    for (const key of ["additionalProperties", "patternProperties"] as const) {
+      const node = s[key];
+      if (!node || typeof node !== "object") continue;
+      if (key === "additionalProperties") walk(node, [...path, "{}"], here);
+      else for (const child of Object.values(node)) walk(child, [...path, "{}"], here);
+    }
+    for (const branch of ["allOf", "anyOf", "oneOf"] as const) {
+      const list = s[branch];
+      if (Array.isArray(list)) for (const child of list) walk(child, path, here);
+    }
+    if (s.items) walk(s.items, [...path, "[]"], here);
+  };
+
+  walk(schema, [], []);
+  return out;
+}
+
 /** The scalar form a declared node's value takes at runtime. `int64` and
  *  `double` are the two JSON scalars whose runtime representation is NOT decided
  *  by the value that arrives: a CEL integer is a BigInt and a CEL double a JS

package/src/loaded-types.ts

@@ -12,9 +12,9 @@ import type { AstDocument } from "./yaml-ast.js";
  *  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. */
+   *  HTTPS for a remote module, an absolute path for local. */
   source: string;
-  /** The URL the caller supplied (e.g. registry ref `std/javascript@0.3.0`).
+  /** The URL the caller supplied (e.g. `oci://ghcr.io/telorun/javascript@0.3.0`).
    *  Differs from `source` only for adapter-resolved URLs. */
   requestedUrl: string;
   /** Raw text exactly as `read()` returned it. */
@@ -65,8 +65,8 @@ export interface LoadedModule {
 export interface ImportEdge {
   /** Canonical resolved URL of the target — a key into `modules`. */
   targetSource: string;
-  /** The import's `source` exactly as authored — a registry ref, an `oci://`
-   *  or `https://` ref, or a relative path. Version reconciliation keys on
+  /** The import's `source` exactly as authored — an `oci://` or `https://`
+   *  ref, or a relative path. Version reconciliation keys on
    *  this (minus its version), since it names the module's location
    *  independently of what the module declares about itself. */
   targetRef: string;

package/src/manifest-analysis.ts

@@ -27,7 +27,14 @@ import { CelScopeQuery, type CelScopeQueryContext } from "./cel-scope-query.js";
 import { DefinitionRegistry } from "./definition-registry.js";
 import type { ContractDirection } from "./extends-resolution.js";
 import { analyzerContractScope, resolveContract } from "./invocation-contract.js";
+import { buildCallGraph, type CallGraph } from "./call-graph.js";
 import { findManifest } from "./find-manifest.js";
+import {
+  buildModuleGraph,
+  type BuildModuleGraphOptions,
+  type ModuleGraph,
+  type ModuleGraphDeps,
+} from "./module-graph.js";
 import { isModuleKind } from "./module-kinds.js";
 
 /**
@@ -43,6 +50,8 @@ export interface ManifestRef {
 export class ManifestAnalysis {
   private readonly scopes: ModuleScopes;
   private celScopeQuery: CelScopeQuery | undefined;
+  private callGraphMemo: CallGraph | undefined;
+  private moduleGraphMemo: ModuleGraph | undefined;
 
   constructor(
     readonly manifests: ResourceManifest[],
@@ -62,6 +71,36 @@ export class ManifestAnalysis {
     return (this.celScopeQuery ??= new CelScopeQuery(this.manifests, this.ctx));
   }
 
+  /** What calls what. Built on first use and kept, so the projection and any
+   *  other consumer over this set share one. */
+  private get callGraph(): CallGraph {
+    return (this.callGraphMemo ??= buildCallGraph(this.manifests, this.ctx.defs, {
+      aliases: this.ctx.aliases,
+      aliasesByModule: this.ctx.aliasesByModule,
+    }));
+  }
+
+  /**
+   * The module graph: boxes, ordered rows and classed edges — the projection an
+   * editor draws.
+   *
+   * Here rather than on the registry because it is the registry AND a manifest
+   * set, which is the pairing this class exists to name; a fifth
+   * `registry.x(manifests, …)` factory is the accretion naming it stopped. It
+   * shares this analysis's call graph rather than building one of its own.
+   *
+   * `deps` is supplied by the registry, which owns capability resolution — this
+   * class holds the manifests, not the rules for reading a kind.
+   */
+  moduleGraph(deps: ModuleGraphDeps, options: BuildModuleGraphOptions = {}): ModuleGraph {
+    return (this.moduleGraphMemo ??= buildModuleGraph(
+      this.manifests,
+      this.callGraph,
+      deps,
+      options,
+    ));
+  }
+
   /** The manifest a `(kind, name)` pair addresses. */
   resourceFor(kind: string | undefined, name: string | undefined): ResourceManifest | undefined {
     return findManifest(this.manifests, kind, name);

package/src/manifest-loader.ts

@@ -146,7 +146,7 @@ export class Loader {
    *  when a URL it has already canonicalised is requested again — kernel
    *  load → boot and the import-controller each ask the loader for the same
    *  modules. Without this fast path every duplicate request re-runs the
-   *  source's `read()` (a `fetch` for `RegistrySource`, a disk read for
+   *  source's `read()` (a `fetch` for `HttpSource`, a disk read for
    *  `LocalFileSource`). */
   private readonly urlToSource = new Map<string, string>();
 
@@ -157,8 +157,7 @@ export class Loader {
   /** Sources are resolved in order — the first whose `supports(url)` matches
    *  wins. The caller (composition root) decides which concrete sources exist
    *  and supplies them; `defaultSources()` bundles the browser-safe built-ins
-   *  (HTTP + registry) for the common case. `register()` prepends a source at
-   *  runtime. */
+   *  (HTTP) for the common case. `register()` prepends a source at runtime. */
   constructor(sources: ManifestSource[] = [], options: LoaderInitOptions = {}) {
     this.sources = [...sources];
     this.celEnv = buildCelEnvironment(options.celHandlers);
@@ -181,7 +180,7 @@ export class Loader {
     // entry are populated in `urlToSource` + `fileCache` in one read.
     // Callers (kernel.load) immediately call `loadGraph(entryUrl)`
     // afterwards — without this priming, the entry file would be read
-    // twice (twice over the network for `RegistrySource`).
+    // twice (twice over the network for `HttpSource`).
     const file = await this.loadFile(url);
     return file.source;
   }
@@ -469,7 +468,7 @@ export class Loader {
 
   /** Resolve an `import` URL against the file it appears in. Relative /
    *  absolute-path forms run through the owning `ManifestSource`'s
-   *  `resolveRelative`; registry refs and full URLs pass through
+   *  `resolveRelative`; scheme-qualified refs and full URLs pass through
    *  unchanged. Exposed so the import-controller (and any other
    *  caller-side resolver) lands on the *exact same* canonical URL the
    *  loader used when walking the entry graph — divergent resolution

package/src/manifest-schemas.ts

@@ -241,6 +241,10 @@ export const InvokeStepSchema = {
     when: {
       title: "When",
       description: "CEL guard — the dispatch is skipped when it evaluates false.",
+      // The same role `if:` and `while:` carry: it is the expression that
+      // decides whether the statement runs, and a surface showing what a step
+      // is conditional on should not have to know which keyword spelled it.
+      "x-telo-topology-role": "predicate",
       type: "string",
     },
     retry: {