@telorun/analyzer 0.59.0 → 0.61.0

package/src/release/version-stamp.ts

@@ -0,0 +1,142 @@
+/**
+ * Writing a module's one version into every manifest it owns.
+ *
+ * A module has a single version across `telo.yaml`, `nodejs/package.json` and
+ * `rust/Cargo.toml`. Three formats, one rule: find the scalar, splice over its
+ * span, touch nothing else. That is `yaml-source-edit.ts`'s primitive — the same
+ * one the quick fix, `telo migrate` and `telo upgrade`'s pin rewrite use — so a
+ * bump lands as a one-line diff instead of a re-serialized file that re-folds
+ * every block scalar in a 900-line manifest.
+ *
+ * Each stamp returns `undefined` when the file carries no version to write,
+ * which is not an error: a module may own only a `telo.yaml`, and 42 of the
+ * standard library's packages have no Rust crate. A file that *has* a version in
+ * a shape this cannot address is a hard error instead, because silently skipping
+ * it would publish an artifact whose manifests disagree about what it is.
+ */
+
+import { defaultCustomTags } from "@telorun/templating";
+import { isScalar, parseAllDocuments, parseDocument, type Scalar } from "yaml";
+import { applyTextEdits, renderFixReplacement } from "../yaml-source-edit.js";
+
+export class VersionStampError extends Error {}
+
+/** Replace the scalar at `[start, end)` with `version`, re-quoted in the
+ *  author's own style. */
+function spliceScalar(text: string, node: Scalar, version: string, where: string): string {
+  const range = node.range;
+  if (!range) {
+    throw new VersionStampError(`${where}: the version scalar carries no source range.`);
+  }
+  const [start, end] = range;
+  const source = text.slice(start, end);
+  const replacement = renderFixReplacement(source, version);
+  if (replacement === undefined) {
+    throw new VersionStampError(
+      `${where}: the version is written as '${source}', which cannot be rewritten in place. ` +
+        `Write it as a plain or quoted scalar on one line.`,
+    );
+  }
+  return applyTextEdits(text, [{ start, end, newText: replacement }]);
+}
+
+/**
+ * `metadata.version` on the **module doc** — the first document, the one whose
+ * kind is `Telo.Application` or `Telo.Library`. Deliberately not "any
+ * `metadata.version` in the file": a `Telo.Definition` further down may carry
+ * one, and the regex-replacement changie was configured with matched by line
+ * shape rather than by position, which is why it needed a hand-maintained count
+ * of how many lines it was allowed to hit.
+ */
+export function stampManifestVersion(
+  text: string,
+  version: string,
+  where: string,
+): string | undefined {
+  const docs = parseAllDocuments(text, { customTags: defaultCustomTags() });
+  const doc = docs[0];
+  if (!doc) return undefined;
+  const metadata = doc.get("metadata", true);
+  if (!metadata || typeof (metadata as { get?: unknown }).get !== "function") return undefined;
+  const node = (metadata as { get(key: string, keepScalar: boolean): unknown }).get(
+    "version",
+    true,
+  );
+  if (!isScalar(node)) return undefined;
+  return spliceScalar(text, node, version, where);
+}
+
+/** Read the module doc's `metadata.version` without rewriting it. */
+export function readManifestVersion(text: string): string | undefined {
+  const docs = parseAllDocuments(text, { customTags: defaultCustomTags() });
+  const first = docs[0]?.toJSON() as { kind?: unknown; metadata?: { version?: unknown } } | undefined;
+  if (first?.kind !== "Telo.Application" && first?.kind !== "Telo.Library") return undefined;
+  const version = first.metadata?.version;
+  return typeof version === "string" ? version : undefined;
+}
+
+/**
+ * The top-level `"version"` of a `package.json`.
+ *
+ * Parsed with the YAML reader rather than `JSON.parse`, because JSON is a YAML
+ * subset and this one needs the node's *source range* — `JSON.parse` discards it,
+ * and re-serializing with `JSON.stringify` would reformat a file whose
+ * indentation, key order and trailing newline are all conventions someone chose.
+ */
+export function stampPackageVersion(
+  text: string,
+  version: string,
+  where: string,
+): string | undefined {
+  const doc = parseDocument(text);
+  const node = doc.get("version", true);
+  if (!isScalar(node)) return undefined;
+  return spliceScalar(text, node, version, where);
+}
+
+/**
+ * `version` in a `Cargo.toml`'s `[package]` table.
+ *
+ * Scanned rather than parsed: TOML is not YAML, adding a TOML parser to the
+ * browser-safe analyzer for one scalar is not a trade worth making, and the
+ * shape being addressed is the canonical one cargo itself writes. The scan is
+ * bounded to the `[package]` table so a `version` under `[dependencies.x]`
+ * cannot be hit, and a `[package]` whose version is not a simple quoted scalar
+ * is refused rather than guessed at.
+ */
+export function stampCrateVersion(
+  text: string,
+  version: string,
+  where: string,
+): string | undefined {
+  const table = /^[ \t]*\[package\][ \t]*$/m.exec(text);
+  if (!table) return undefined;
+  const bodyStart = table.index + table[0].length;
+  const next = /^[ \t]*\[/m.exec(text.slice(bodyStart));
+  const bodyEnd = next ? bodyStart + next.index : text.length;
+
+  const entry = /^([ \t]*version[ \t]*=[ \t]*)(".*?"|'.*?')[ \t]*$/m.exec(
+    text.slice(bodyStart, bodyEnd),
+  );
+  if (!entry) {
+    // A `[package]` with `version.workspace = true` inherits from the workspace
+    // and genuinely has nothing here to stamp; anything else is a shape this
+    // cannot address, and writing nothing would leave the crate behind.
+    if (/^[ \t]*version[ \t]*\.[ \t]*workspace[ \t]*=/m.test(text.slice(bodyStart, bodyEnd))) {
+      return undefined;
+    }
+    if (/^[ \t]*version[ \t]*=/m.test(text.slice(bodyStart, bodyEnd))) {
+      throw new VersionStampError(
+        `${where}: [package].version is not a quoted scalar on one line, so it cannot be ` +
+          `rewritten in place.`,
+      );
+    }
+    return undefined;
+  }
+
+  const start = bodyStart + entry.index + entry[1].length;
+  const quote = entry[2][0];
+  return applyTextEdits(text, [
+    { start, end: start + entry[2].length, newText: `${quote}${version}${quote}` },
+  ]);
+}

package/src/release/workspace-config.ts

@@ -0,0 +1,81 @@
+/**
+ * `telo-workspace.yaml` — the release anchor.
+ *
+ * Every path the release system names — a module key, a ledger entry, a
+ * fragment's `modules:` — is relative to this file's directory. That is the
+ * whole of its job: **its location is the anchor**, and its one field names the
+ * subtrees that may hold modules, which is not derivable (a whole-tree scan
+ * would read every example and every cached `.telo/manifests` copy as a released
+ * module).
+ *
+ * The file is **optional and read only by `telo release`**. Nothing else — not
+ * `run`, `check`, `publish`, `install`, `upgrade`, `migrate`, `module`, and not
+ * the kernel — looks for it, so a single-manifest repo, a bare `examples/`
+ * directory and a third-party module checkout keep working with nothing added.
+ * Any field added later must be true of the whole tree, not derivable from it,
+ * and harmless by its absence.
+ *
+ * Parsing lives here, in the browser-safe half, because the editor answers
+ * "what does changing this library bump?" from the same model. Finding the file
+ * on disk is the CLI's half — this side takes text.
+ */
+
+import { parseDocument } from "yaml";
+
+export const WORKSPACE_FILENAME = "telo-workspace.yaml";
+
+export interface WorkspaceConfig {
+  /**
+   * Gitignore-style patterns, workspace-relative, naming the subtrees that may
+   * hold modules (`modules/*`, `apps/*`). A pattern names a place to look, never
+   * a module: what makes a directory a module is its `telo.yaml`.
+   */
+  readonly modules: readonly string[];
+}
+
+export class WorkspaceConfigError extends Error {}
+
+/**
+ * Parse the marker file's text.
+ *
+ * Strict about its one field, because there is nothing here to be lenient with:
+ * an empty or absent `modules:` names no subtree, so discovery would find no
+ * module and every gate would silently pass over a whole repo.
+ */
+export function parseWorkspaceConfig(text: string, where: string): WorkspaceConfig {
+  let value: unknown;
+  try {
+    value = parseDocument(text).toJSON();
+  } catch (err) {
+    throw new WorkspaceConfigError(
+      `${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new WorkspaceConfigError(`${where} must be a YAML mapping.`);
+  }
+  const record = value as Record<string, unknown>;
+
+  for (const key of Object.keys(record)) {
+    if (key !== "modules") {
+      throw new WorkspaceConfigError(
+        `${where}: unknown field '${key}'. The workspace marker carries only 'modules:' — ` +
+          `the subtrees that may hold modules.`,
+      );
+    }
+  }
+
+  const modules = record.modules;
+  if (!Array.isArray(modules) || modules.some((entry) => typeof entry !== "string")) {
+    throw new WorkspaceConfigError(
+      `${where}: 'modules' must be a list of path patterns, e.g. [modules/*, apps/*].`,
+    );
+  }
+  if (modules.length === 0) {
+    throw new WorkspaceConfigError(
+      `${where}: 'modules' is empty, so no directory can ever be discovered as a module. ` +
+        `List the subtrees that hold them, e.g. [modules/*, apps/*].`,
+    );
+  }
+  return { modules: modules as string[] };
+}

package/src/schema-compat.ts

@@ -3,7 +3,6 @@ import addFormats from "ajv-formats";
 import {
   isRefSentinel,
   isTaggedSentinel,
-  ManifestRootSchema,
   producedTypeOf,
 } from "@telorun/templating";
 import {
@@ -14,6 +13,7 @@ import {
   valueTypeOf,
   valueTypePlaceholder,
 } from "@telorun/sdk";
+import { ManifestRootSchema } from "./manifest-schemas.js";
 import { registerTeloKeywords } from "./value-type-keyword.js";
 
 const Ajv = (AjvModule as any).default ?? AjvModule;

package/src/validate-module-artifact.ts

@@ -5,7 +5,9 @@ import {
   ArtifactSelectorError,
   PLATFORM_AXES,
   selectorFromQualifiers,
+  selectorKey,
 } from "./artifact-selector.js";
+import { readLibraryCandidates, type LibraryCandidate } from "./module-library.js";
 import { DiagnosticSeverity, type AnalysisDiagnostic } from "./types.js";
 
 const SOURCE = "telo-analyzer";
@@ -38,10 +40,64 @@ export function validateModuleArtifact(manifests: ResourceManifest[]): AnalysisD
   for (const manifest of manifests) {
     validateLayerIndex(manifest, out);
     validateControllerSelectors(manifest, out);
+    validateLibraryCandidates(manifest, out);
   }
   return out;
 }
 
+/**
+ * The `exports.code:` block on a `Telo.Library` doc.
+ *
+ * Reported here rather than left to the loader for the same reason a controller
+ * selector is: an entry that cannot be read names no entry point, so a
+ * consumer's bundle falls back to *inlining* the library — the module scope
+ * duplication this whole mechanism exists to remove — and it does so silently, on
+ * someone else's machine.
+ */
+function validateLibraryCandidates(manifest: ResourceManifest, out: AnalysisDiagnostic[]): void {
+  // `Telo.Library` only. An application is a root with no importer, so it has no
+  // `exports:` block at all — and its schema is `additionalProperties: false`,
+  // so AJV already rejects the key by name in this same pass. A second
+  // diagnostic on that node would be two squiggles saying one thing.
+  if (manifest.kind !== "Telo.Library") return;
+  const metadata = manifest.metadata as { name?: string; source?: string } | undefined;
+  const { candidates, problems } = readLibraryCandidates(manifest);
+  const resource = { kind: manifest.kind, name: metadata?.name };
+
+  for (const problem of problems) {
+    out.push({
+      severity: DiagnosticSeverity.Error,
+      code: "LIBRARY_CANDIDATE_INVALID",
+      source: SOURCE,
+      message: `Telo.Library/${metadata?.name ?? "(unnamed)"}: ${problem.origin}: ${problem.detail}`,
+      data: { resource, filePath: metadata?.source, path: "exports/code" },
+    });
+  }
+
+  // One specifier per selector: two candidates of one format claiming the same
+  // specifier leave the resolution ambiguous, and two specifiers for one format
+  // mean a consumer's import resolves by whichever candidate is read first.
+  const seen = new Map<string, LibraryCandidate>();
+  for (const candidate of candidates) {
+    const key = selectorKey(candidate.selector);
+    const first = seen.get(key);
+    if (first) {
+      out.push({
+        severity: DiagnosticSeverity.Error,
+        code: "LIBRARY_CANDIDATE_DUPLICATE",
+        source: SOURCE,
+        message:
+          `Telo.Library/${metadata?.name ?? "(unnamed)"}: two 'exports.code' entries declare the ` +
+          `selector ${key} ('${first.specifier}' and '${candidate.specifier}'). A module has one ` +
+          `entry point per format — which is what makes "one specifier, one module scope" true.`,
+        data: { resource, filePath: metadata?.source, path: "exports/code" },
+      });
+      continue;
+    }
+    seen.set(key, candidate);
+  }
+}
+
 /** `local_path` names the source `path=` was built from, so a working copy runs
  *  with no build step. It is inert in a published artifact — which ships no
  *  `src/` — and contributes nothing to the selector, so it never affects which

package/src/validate-step-inputs.ts

@@ -9,7 +9,8 @@ import {
   validateAgainstSchema,
 } from "./schema-compat.js";
 import { plainChainOf } from "@telorun/templating";
-import { valueTypeOf } from "@telorun/sdk";
+import { isLiveSlot, valueTypeOf } from "@telorun/sdk";
+import { manifestFragmentOf } from "./manifest-schemas.js";
 import {
   analyzerContractScope,
   containerOf,
@@ -25,7 +26,7 @@ export interface StepInputIssue {
   message: string;
   /** Set when the issue is a type-argument disagreement rather than a contract
    *  shape violation — the two read differently and deserve their own code. */
-  code?: "CEL_TYPE_ARGUMENT_MISMATCH";
+  code?: "CEL_TYPE_ARGUMENT_MISMATCH" | "LIVE_VALUE_RETRIED";
 }
 
 
@@ -118,15 +119,30 @@ export function collectStepInputIssues(
       // that silence is exactly where a stream of the wrong element used to
       // flow. The comparison is covariant and gradual: an omitted argument is
       // *any* in both directions, so only a definite conflict is reported.
-      if (stepContext) {
+      // The roots a plain chain may name here, each paired with the schema it is
+      // navigated against. `steps.` is the step map (analyzer state, supplied by
+      // the caller). `inputs.` is the ENCLOSING kind's own declared inputType,
+      // which is how a value produced OUTSIDE this resource reaches a step at
+      // all: an HTTP route maps `request.body` into its handler's inputs, and the
+      // handler forwards `inputs.body` onward — the shape a live value most often
+      // arrives in, and the one covering only `steps.` missed entirely. A root
+      // this cannot resolve contributes nothing rather than guessing at a schema.
+      const roots: Array<[string, Record<string, any>]> = [];
+      if (stepContext) roots.push(["steps.", stepContext]);
+      const ownContract = resolveContract(
+        "inputType",
+        manifest,
+        contractScope.resolveIn(manifest.kind as string, readingModule),
+        contractScope,
+      );
+      if (ownContract) roots.push(["inputs.", ownContract.schema]);
+
+      if (roots.length > 0) {
         for (const [inputName, inputValue] of Object.entries(values)) {
           const chain = plainChainOf(inputValue);
-          // The step context is rooted at the STEP MAP, so a `steps.` prefix is
-          // the namespace name and not a property of it. Only that namespace is
-          // navigated: `inputs.` and a named binding resolve elsewhere, and
-          // guessing at a root this does not hold would compare the wrong schema.
-          if (!chain?.startsWith("steps.")) continue;
-          const produced = navigateSchemaToExprPath(stepContext, chain.slice("steps.".length));
+          const root = chain ? roots.find(([prefix]) => chain.startsWith(prefix)) : undefined;
+          if (!chain || !root) continue;
+          const produced = navigateSchemaToExprPath(root[1], chain.slice(root[0].length));
           const slotSchema = (contract.schema.properties as Record<string, any> | undefined)?.[
             inputName
           ];
@@ -138,6 +154,28 @@ export function collectStepInputIssues(
           // broad new Error-severity check hidden behind an argument-specific
           // name. Both sides must declare a value type for the question to be
           // about arguments at all.
+          // A LIVE value is consumed by reading, so it exists exactly once —
+          // that is what `live` says in the vocabulary, and re-attempting a
+          // dispatch that already read it re-sends nothing. Reported here rather
+          // than through a slot-specific annotation because both facts are
+          // already declared: the value's liveness by its value type, and the
+          // re-attempt by the retry policy. No kind is named.
+          if (isLiveSlot(produced)) {
+            const retry = declaredRetry(step, stepItemSchema, invokedManifest, invokedDef);
+            if (retry !== undefined) {
+              out.push({
+                path: `${stepPath}.${inputsField}.${inputName}`,
+                targetLabel: invokedName ?? invokedKind ?? "the invoked resource",
+                message:
+                  `'${inputName}' is a live value, which is consumed by reading and so exists ` +
+                  `once — but ${retry} re-attempts the dispatch, and a re-attempt would pass ` +
+                  `nothing. Collect it to a value first, or chunk the work so each attempt ` +
+                  `carries its own replayable piece.`,
+                code: "LIVE_VALUE_RETRIED",
+              });
+              continue;
+            }
+          }
           if (!valueTypeOf(produced) || !valueTypeOf(slotSchema)) continue;
           const { compatible, issues } = checkSchemaCompatibility(produced, slotSchema, (ref) =>
             defs.schemaForId(ref),
@@ -170,3 +208,65 @@ export function collectStepInputIssues(
   return out;
 }
 
+/**
+ * Where a re-attempt is declared for this dispatch, described for a diagnostic,
+ * or undefined when none is.
+ *
+ * A field declares one when its schema was expanded from a shared retry fragment
+ * — the shape the author pointed at, rather than a marker they had to remember to
+ * write beside it. Which fragment also says WHERE the budget is, so the two
+ * spellings a kind may carry (a policy object, or the deprecated bare count) need
+ * no guessing between them and no rule about which one wins.
+ *
+ * Two sites are consulted because there are two real ones: the STEP's own policy
+ * — `retry` on the kernel-owned dispatch site — and the TARGET's, a field on an
+ * arbitrary kind, because `Http.Request` re-attempts inside its own `invoke()`
+ * where only it can tell a 429 from a 500. A live value is equally doomed by
+ * either. EVERY retry-bearing field at a site is checked, not the first, since
+ * `Http.Request` carries both spellings and property order must not decide which
+ * is seen.
+ *
+ * Only a STATICALLY KNOWN non-zero budget counts. An `attempts` written as CEL
+ * says nothing here, and guessing would report a conflict against a manifest that
+ * may never retry — the same posture the `use` case-map selector takes.
+ */
+function declaredRetry(
+  step: Record<string, any>,
+  stepItemSchema: Record<string, any> | undefined,
+  invokedManifest: Record<string, any> | undefined,
+  invokedDef: Record<string, any> | undefined,
+): string | undefined {
+  for (const [field, budget] of retryFields(stepItemSchema)) {
+    if (budget(step?.[field]) > 0) return `the step's \`${field}\``;
+  }
+  for (const [field, budget] of retryFields(invokedDef?.schema as Record<string, any>)) {
+    if (budget(invokedManifest?.[field]) > 0) return `the target's \`${field}\``;
+  }
+  return undefined;
+}
+
+/** How each shared retry fragment carries its budget. Keyed on fragment name —
+ *  the analyzer's own built-ins, never a module's kind — so a kind that adopts a
+ *  shape is covered without naming it here. */
+const RETRY_BUDGET: Record<string, (value: unknown) => number> = {
+  RetryPolicy: (value) => {
+    if (!value || typeof value !== "object") return 0;
+    const attempts = (value as Record<string, unknown>).attempts;
+    return typeof attempts === "number" ? attempts : 0;
+  },
+  RetryAttempts: (value) => (typeof value === "number" ? value : 0),
+};
+
+/** Every property of `schema` whose shape came from a retry fragment, paired with
+ *  the reader for that fragment's budget. */
+function retryFields(
+  schema: Record<string, any> | undefined,
+): Array<[string, (value: unknown) => number]> {
+  if (!schema) return [];
+  const out: Array<[string, (value: unknown) => number]> = [];
+  for (const [key, sub] of gatherPropertySchemas(schema)) {
+    const budget = RETRY_BUDGET[manifestFragmentOf(sub) ?? ""];
+    if (budget) out.push([key, budget]);
+  }
+  return out;
+}