npm - @telorun/analyzer - Versions diffs - 0.59.0 → 0.60.0 - Mend

@telorun/analyzer 0.59.0 → 0.60.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/dist/analyzer.d.ts +9 -2
package/dist/analyzer.d.ts.map +1 -1
package/dist/analyzer.js +38 -10
package/dist/builtins.d.ts.map +1 -1
package/dist/builtins.js +16 -42
package/dist/cel-environment.d.ts.map +1 -1
package/dist/cel-environment.js +35 -0
package/dist/flatten-for-analyzer.d.ts +4 -0
package/dist/flatten-for-analyzer.d.ts.map +1 -1
package/dist/flatten-for-analyzer.js +8 -0
package/dist/index.d.ts +3 -0
package/dist/index.d.ts.map +1 -1
package/dist/index.js +6 -0
package/dist/kernel-globals.d.ts +1 -1
package/dist/kernel-globals.d.ts.map +1 -1
package/dist/kernel-globals.js +15 -1
package/dist/manifest-schemas.d.ts +407 -0
package/dist/manifest-schemas.d.ts.map +1 -0
package/dist/manifest-schemas.js +396 -0
package/dist/module-file-claims.d.ts +6 -0
package/dist/module-file-claims.d.ts.map +1 -1
package/dist/module-file-claims.js +4 -0
package/dist/module-metadata-scope.d.ts +44 -0
package/dist/module-metadata-scope.d.ts.map +1 -0
package/dist/module-metadata-scope.js +82 -0
package/dist/parse-loaded-file.d.ts.map +1 -1
package/dist/parse-loaded-file.js +16 -0
package/dist/release/bump-level.d.ts +46 -0
package/dist/release/bump-level.d.ts.map +1 -0
package/dist/release/bump-level.js +80 -0
package/dist/release/changelog.d.ts +36 -0
package/dist/release/changelog.d.ts.map +1 -0
package/dist/release/changelog.js +53 -0
package/dist/release/fragment.d.ts +48 -0
package/dist/release/fragment.d.ts.map +1 -0
package/dist/release/fragment.js +84 -0
package/dist/release/index.d.ts +26 -0
package/dist/release/index.d.ts.map +1 -0
package/dist/release/index.js +18 -0
package/dist/release/ledger.d.ts +53 -0
package/dist/release/ledger.d.ts.map +1 -0
package/dist/release/ledger.js +109 -0
package/dist/release/payload-digest.d.ts +63 -0
package/dist/release/payload-digest.d.ts.map +1 -0
package/dist/release/payload-digest.js +65 -0
package/dist/release/release-plan.d.ts +128 -0
package/dist/release/release-plan.d.ts.map +1 -0
package/dist/release/release-plan.js +277 -0
package/dist/release/version-stamp.d.ts +50 -0
package/dist/release/version-stamp.d.ts.map +1 -0
package/dist/release/version-stamp.js +119 -0
package/dist/release/workspace-config.d.ts +41 -0
package/dist/release/workspace-config.d.ts.map +1 -0
package/dist/release/workspace-config.js +60 -0
package/dist/schema-compat.js +2 -1
package/dist/validate-step-inputs.d.ts +1 -1
package/dist/validate-step-inputs.d.ts.map +1 -1
package/dist/validate-step-inputs.js +99 -8
package/package.json +3 -3
package/src/analyzer.ts +41 -10
package/src/builtins.ts +16 -42
package/src/cel-environment.ts +37 -0
package/src/flatten-for-analyzer.ts +12 -0
package/src/index.ts +9 -1
package/src/kernel-globals.ts +23 -1
package/src/manifest-schemas.ts +408 -0
package/src/module-file-claims.ts +10 -0
package/src/module-metadata-scope.ts +88 -0
package/src/parse-loaded-file.ts +16 -0
package/src/release/bump-level.ts +95 -0
package/src/release/changelog.ts +62 -0
package/src/release/fragment.ts +130 -0
package/src/release/index.ts +66 -0
package/src/release/ledger.ts +142 -0
package/src/release/payload-digest.ts +83 -0
package/src/release/release-plan.ts +392 -0
package/src/release/version-stamp.ts +142 -0
package/src/release/workspace-config.ts +81 -0
package/src/schema-compat.ts +1 -1
package/src/validate-step-inputs.ts +109 -9

package/src/release/changelog.ts ADDED Viewed

@@ -0,0 +1,62 @@
+/**
+ * Rendering a module's `CHANGELOG.md` entry, and splicing it into the file.
+ *
+ * The output shape is the one changie was configured to emit — `## <version> -
+ * <date>`, `### <Kind>`, `* <body>` — so a module's history stays one document
+ * across the handover rather than changing format mid-file.
+ *
+ * Prepending rather than rewriting: a changelog is append-only history, and the
+ * only edit ever made to it is inserting the newest release above the previous
+ * one. Everything already written is untouched bytes.
+ */
+import { FRAGMENT_KIND_ORDER, type FragmentKind } from "./bump-level.js";
+export const CHANGELOG_HEADER = "# Changelog";
+export interface ChangelogRelease {
+  readonly version: string;
+  /** `YYYY-MM-DD`. Passed in rather than read from a clock, so a plan renders
+   *  identically whenever it is rendered and a test needs no clock control. */
+  readonly date: string;
+  readonly entries: readonly { readonly kind: FragmentKind; readonly body: string }[];
+}
+/** One release block. Entries group under their kind, in the vocabulary's own
+ *  order, so two releases never disagree about where `Fixed` sits. */
+export function renderChangelogRelease(release: ChangelogRelease): string {
+  const byKind = new Map<FragmentKind, string[]>();
+  for (const entry of release.entries) {
+    const list = byKind.get(entry.kind);
+    if (list) list.push(entry.body);
+    else byKind.set(entry.kind, [entry.body]);
+  }
+  const lines = [`## ${release.version} - ${release.date}`];
+  for (const kind of FRAGMENT_KIND_ORDER) {
+    const bodies = byKind.get(kind);
+    if (!bodies) continue;
+    lines.push(`### ${kind}`);
+    for (const body of bodies) lines.push(`* ${body}`);
+  }
+  return lines.join("\n") + "\n";
+}
+/**
+ * Insert a release block below the file's `# Changelog` header, creating the
+ * file's skeleton when it has none.
+ *
+ * A module with no changelog yet is the ordinary case for a new module, so this
+ * writes the header rather than failing — the alternative is a release that
+ * stops to ask for an empty file to be created by hand.
+ */
+export function prependChangelogRelease(existing: string | undefined, block: string): string {
+  const text = existing ?? "";
+  const header = text.match(/^#\s+Changelog[^\n]*\n/);
+  if (!header) {
+    const rest = text.trim();
+    return `${CHANGELOG_HEADER}\n\n${block}${rest ? `\n${rest}\n` : ""}`;
+  }
+  const after = text.slice(header[0].length).replace(/^\n+/, "");
+  return `${header[0]}\n${block}${after ? `\n${after}` : ""}`;
+}

package/src/release/fragment.ts ADDED Viewed

@@ -0,0 +1,130 @@
+/**
+ * A release fragment — one pending change, written by an author.
+ *
+ * The shape is changesets' (one file, several modules, one body) carrying
+ * changie's kind vocabulary, which is what lets one cross-cutting change be one
+ * file while the kind still drives both the level and the changelog section a
+ * line lands under. Changie's own file is the other arrangement — one module per
+ * file — so a change touching five modules meant five files repeating one
+ * sentence, and its key was the module's bare directory NAME, which two
+ * directories in different subtrees can share.
+ *
+ * A fragment names modules by **workspace-relative path**, the same key the
+ * ledger and every diagnostic use.
+ *
+ * They are plain YAML validated here, not a `Telo.*` kind: build-time repo state
+ * with no controller and no capability, which the runtime never loads.
+ */
+import { Document, parseDocument } from "yaml";
+import { isFragmentKind, type FragmentKind } from "./bump-level.js";
+/** A module's workspace-relative directory path — `modules/sql`, `apps/hub`. */
+export type ModuleKey = string;
+export interface ReleaseFragment {
+  /**
+   * Where this fragment was read from, workspace-relative. Carried so a
+   * diagnostic can name the file to fix and `apply` can delete the file it
+   * consumed.
+   */
+  readonly source: string;
+  /** The directly-changed modules this fragment declares, each with its kind. */
+  readonly modules: ReadonlyMap<ModuleKey, FragmentKind>;
+  /** The changelog line. */
+  readonly body: string;
+}
+export class FragmentError extends Error {
+  constructor(
+    readonly source: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+export function parseFragment(text: string, source: string): ReleaseFragment {
+  let value: unknown;
+  try {
+    value = parseDocument(text).toJSON();
+  } catch (err) {
+    throw new FragmentError(
+      source,
+      `${source} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new FragmentError(source, `${source} must be a YAML mapping.`);
+  }
+  const record = value as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (key !== "modules" && key !== "body") {
+      throw new FragmentError(
+        source,
+        `${source}: unknown field '${key}'. A fragment carries 'modules:' and 'body:'.`,
+      );
+    }
+  }
+  const rawModules = record.modules;
+  if (rawModules === null || typeof rawModules !== "object" || Array.isArray(rawModules)) {
+    throw new FragmentError(
+      source,
+      `${source}: 'modules' must be a mapping of module path to kind, ` +
+        `e.g. { modules/sql: Fixed }.`,
+    );
+  }
+  const modules = new Map<ModuleKey, FragmentKind>();
+  for (const [key, kind] of Object.entries(rawModules as Record<string, unknown>)) {
+    if (!isFragmentKind(kind)) {
+      throw new FragmentError(
+        source,
+        `${source}: '${key}' declares kind '${String(kind)}', which is not a release kind. ` +
+          `Use Added, Changed, Deprecated, Removed, Fixed or Security.`,
+      );
+    }
+    modules.set(normalizeModuleKey(key), kind);
+  }
+  if (modules.size === 0) {
+    throw new FragmentError(
+      source,
+      `${source}: 'modules' is empty, so this fragment releases nothing. ` +
+        `Name at least one module by its workspace-relative path.`,
+    );
+  }
+  const body = record.body;
+  if (typeof body !== "string" || body.trim() === "") {
+    throw new FragmentError(
+      source,
+      `${source}: 'body' must be the changelog line for this change.`,
+    );
+  }
+  return { source, modules, body: body.trim() };
+}
+/**
+ * Render a fragment, for `telo release add`.
+ *
+ * Serialized rather than templated so a long body folds the way the YAML writer
+ * folds it, and so a module path needing quotes gets them.
+ */
+export function serializeFragment(
+  modules: ReadonlyMap<ModuleKey, FragmentKind>,
+  body: string,
+): string {
+  const doc = new Document({
+    modules: Object.fromEntries([...modules].map(([key, kind]) => [key, kind])),
+    body,
+  });
+  return doc.toString({ lineWidth: 88 });
+}
+/** Module keys are POSIX-separated and carry no leading `./` or trailing slash,
+ *  so the same directory written three ways is one key. */
+export function normalizeModuleKey(key: string): ModuleKey {
+  return key.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+}

package/src/release/index.ts ADDED Viewed

@@ -0,0 +1,66 @@
+/**
+ * The release model: module identity, fragments, the ledger, the edge graph,
+ * level propagation and version planning.
+ *
+ * Browser-safe by construction — pure data in, plan out — so the telo editor can
+ * answer "what does changing this library bump?" from the same model the CLI
+ * releases from. Everything Node-shaped (finding the workspace, running the
+ * controller builder, building payloads, reading git, writing files) is
+ * `cli/nodejs/src/release/`.
+ */
+export {
+  FRAGMENT_KINDS,
+  FRAGMENT_KIND_ORDER,
+  applyBump,
+  compareVersions,
+  isFragmentKind,
+  isReleaseVersion,
+  levelOfKind,
+  maxLevel,
+} from "./bump-level.js";
+export type { BumpLevel, FragmentKind } from "./bump-level.js";
+export {
+  CHANGELOG_HEADER,
+  prependChangelogRelease,
+  renderChangelogRelease,
+} from "./changelog.js";
+export type { ChangelogRelease } from "./changelog.js";
+export { FragmentError, normalizeModuleKey, parseFragment, serializeFragment } from "./fragment.js";
+export type { ModuleKey, ReleaseFragment } from "./fragment.js";
+export { EMPTY_LEDGER, LEDGER_PATH, LedgerError, parseLedger, serializeLedger } from "./ledger.js";
+export type { Ledger, LedgerEntry } from "./ledger.js";
+export {
+  LOCALLY_DERIVED_LAYERS,
+  MANIFEST_LAYER,
+  diffLayerDigests,
+  layerDigestKey,
+} from "./payload-digest.js";
+export type { LayerChange, LayerDigests } from "./payload-digest.js";
+export { orderByImports, planRelease } from "./release-plan.js";
+export type {
+  ArtifactKind,
+  BumpReason,
+  ChangelogEntry,
+  ModuleEvidence,
+  PlannedModule,
+  ReleaseDiagnostic,
+  ReleaseEvidence,
+  ReleasePlan,
+} from "./release-plan.js";
+export {
+  VersionStampError,
+  readManifestVersion,
+  stampCrateVersion,
+  stampManifestVersion,
+  stampPackageVersion,
+} from "./version-stamp.js";
+export { WORKSPACE_FILENAME, WorkspaceConfigError, parseWorkspaceConfig } from "./workspace-config.js";
+export type { WorkspaceConfig } from "./workspace-config.js";

package/src/release/ledger.ts ADDED Viewed

@@ -0,0 +1,142 @@
+/**
+ * `.changes/ledger.yaml` — what each module looks like **as published**.
+ *
+ * It exists so a gate can answer "does my payload differ from what is published
+ * at my current version?" with no network call, no merge base and no
+ * credentials: a fork's PR runs the identical computation the release job runs.
+ * That is the load-bearing property — the PR gate and the publish gate compute
+ * the same number.
+ *
+ * **It is a cache, never the authority.** A committed digest can disagree with
+ * the registry — a hand edit, an `apply` whose publish then failed, a push made
+ * outside the pipeline — so `telo publish` still reads the registry, and
+ * `telo release verify` reconciles the two on demand. A *missing* entry is not
+ * drift: it means nothing is published, which is the correct reading for a
+ * module that has never shipped.
+ *
+ * **It records the registry base**, because canonicalizing a relative `imports:`
+ * source writes the destination into the manifest layer — so the digests below
+ * are digests *against that base*, and comparing them to digests taken against
+ * another one would be comparing two different artifacts.
+ */
+import { Document, parseDocument } from "yaml";
+import { isReleaseVersion } from "./bump-level.js";
+import { normalizeModuleKey, type ModuleKey } from "./fragment.js";
+import type { LayerDigests } from "./payload-digest.js";
+export const LEDGER_PATH = ".changes/ledger.yaml";
+export interface LedgerEntry {
+  /** The version these digests were taken at — the tag the artifact published
+   *  under. */
+  readonly version: string;
+  readonly layers: LayerDigests;
+}
+export interface Ledger {
+  /**
+   * The publish destination base the digests were taken against
+   * (`oci://ghcr.io/telorun`). Absent in a workspace that has published nothing
+   * yet, which is why it is optional rather than required — but a `check` that
+   * has entries and no base cannot reproduce them, and says so.
+   */
+  readonly registry?: string;
+  readonly modules: ReadonlyMap<ModuleKey, LedgerEntry>;
+}
+export class LedgerError extends Error {}
+export const EMPTY_LEDGER: Ledger = { modules: new Map() };
+export function parseLedger(text: string, where: string): Ledger {
+  let value: unknown;
+  try {
+    value = parseDocument(text).toJSON();
+  } catch (err) {
+    throw new LedgerError(
+      `${where} is not valid YAML: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+  if (value === null) return EMPTY_LEDGER;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new LedgerError(`${where} must be a YAML mapping.`);
+  }
+  const record = value as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (key !== "registry" && key !== "modules") {
+      throw new LedgerError(
+        `${where}: unknown field '${key}'. The ledger carries 'registry:' and 'modules:'.`,
+      );
+    }
+  }
+  const registry = record.registry;
+  if (registry !== undefined && typeof registry !== "string") {
+    throw new LedgerError(`${where}: 'registry' must be the publish destination base, as a string.`);
+  }
+  const rawModules = record.modules;
+  if (rawModules === undefined || rawModules === null) return { ...(registry ? { registry } : {}), modules: new Map() };
+  if (typeof rawModules !== "object" || Array.isArray(rawModules)) {
+    throw new LedgerError(`${where}: 'modules' must be a mapping of module path to entry.`);
+  }
+  const modules = new Map<ModuleKey, LedgerEntry>();
+  for (const [key, raw] of Object.entries(rawModules as Record<string, unknown>)) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new LedgerError(`${where}: entry '${key}' must be a mapping.`);
+    }
+    const entry = raw as Record<string, unknown>;
+    if (!isReleaseVersion(entry.version)) {
+      throw new LedgerError(
+        `${where}: entry '${key}' has no major.minor.patch 'version'. The ledger records the ` +
+          `version each digest was taken at; without it the digest says nothing.`,
+      );
+    }
+    const layers: Record<string, string> = {};
+    const rawLayers = entry.layers;
+    if (rawLayers !== undefined && rawLayers !== null) {
+      if (typeof rawLayers !== "object" || Array.isArray(rawLayers)) {
+        throw new LedgerError(`${where}: entry '${key}' has a non-mapping 'layers'.`);
+      }
+      for (const [layer, digest] of Object.entries(rawLayers as Record<string, unknown>)) {
+        if (typeof digest !== "string") {
+          throw new LedgerError(`${where}: entry '${key}' layer '${layer}' is not a digest string.`);
+        }
+        layers[layer] = digest;
+      }
+    }
+    modules.set(normalizeModuleKey(key), { version: entry.version, layers });
+  }
+  return { ...(registry ? { registry } : {}), modules };
+}
+/**
+ * Render the ledger.
+ *
+ * Keys are sorted so a release's ledger diff shows only the modules that moved
+ * — the file is committed and reviewed, and a map whose order followed insertion
+ * would reorder wholesale on every run.
+ */
+export function serializeLedger(ledger: Ledger): string {
+  const modules: Record<string, unknown> = {};
+  for (const key of [...ledger.modules.keys()].sort()) {
+    const entry = ledger.modules.get(key)!;
+    const layers: Record<string, string> = {};
+    for (const layer of Object.keys(entry.layers).sort()) layers[layer] = entry.layers[layer];
+    modules[key] = { version: entry.version, layers };
+  }
+  const doc = new Document({
+    ...(ledger.registry ? { registry: ledger.registry } : {}),
+    modules,
+  });
+  return (
+    "# Generated by `telo release apply` — what each module looks like as published.\n" +
+    "# A cache of the registry's answer, so a PR gate needs no credentials.\n" +
+    "# `telo release verify` reconciles it against the registry.\n" +
+    doc.toString({ lineWidth: 0 })
+  );
+}

package/src/release/payload-digest.ts ADDED Viewed

@@ -0,0 +1,83 @@
+/**
+ * A module's payload, reduced to one digest per layer — the exact answer to
+ * "did this module's artifact change?".
+ *
+ * It is exact because it is taken from the bytes: it fires for an inlined
+ * sibling's edit, for a shared-library fix, and for a transitive bump the
+ * lockfile alone moved, none of which touch a file under the module's own
+ * directory. No path-scoped rule and no declared-dependency graph can see any of
+ * them.
+ *
+ * The digest itself is `computeFilesIntegrity`, the same framing-independent
+ * content digest the published `layers:` index carries — which is what makes the
+ * ledger's recorded number and the registry's the same number, comparable
+ * without fetching a blob.
+ */
+import { PLATFORM_AXES, type ArtifactSelector, type LayerRole } from "../artifact-selector.js";
+/** Per-layer integrity, keyed by `layerDigestKey`. */
+export type LayerDigests = Readonly<Record<string, string>>;
+/** The ledger key for the module's `telo.yaml` layer. */
+export const MANIFEST_LAYER = "manifest";
+/**
+ * Ledger keys the registry cannot answer for, and so the ones `telo release
+ * verify` reconciles nothing about and must preserve.
+ *
+ * Exactly one today, and for a structural reason rather than an omission: the
+ * published `layers:` index lives *inside* `telo.yaml`, so it cannot carry that
+ * file's own digest — the entry would have to be computed over bytes containing
+ * it. Nor can the digest be recovered by hashing what the registry serves, since
+ * the transport injects the index at push time and the published text is
+ * therefore not the text the payload builder produced.
+ *
+ * It stays in the ledger regardless, because it is the only thing that sees a
+ * **manifest-only change**: a schema edit, a new kind, a description, a
+ * dependency's version moving into a pin. None of those touch a controller byte,
+ * so without this key such a module would report no drift and its fix would ship
+ * to nobody — the exact failure the digest exists to prevent.
+ */
+export const LOCALLY_DERIVED_LAYERS: ReadonlySet<string> = new Set([MANIFEST_LAYER]);
+/**
+ * A layer's identity within an artifact, as a stable, readable, YAML-plain key.
+ *
+ * A role alone is not the identity — there is one controller layer per selector
+ * — so a selector's axes join the key. Rendered as `controller/js` and
+ * `controller/napi+linux+amd64+gnu` rather than through `selectorKey`'s
+ * `axis=value;…` form, because this string is read by a human in a ledger diff
+ * and written into a plain YAML key; the axis order is `PLATFORM_AXES`, so the
+ * rendering is deterministic rather than dependent on how the selector was
+ * built.
+ */
+export function layerDigestKey(role: LayerRole | string, selector?: ArtifactSelector): string {
+  if (!selector) return role;
+  const parts = [selector.format, ...PLATFORM_AXES.map((axis) => selector[axis])].filter(
+    (value): value is string => value !== undefined,
+  );
+  return `${role}/${parts.join("+")}`;
+}
+/** A layer whose digest differs between two readings, or that exists in only
+ *  one of them. `before` / `after` are absent when the layer is absent there —
+ *  a payload that gained or lost a layer changed just as much as one whose
+ *  bytes moved. */
+export interface LayerChange {
+  readonly layer: string;
+  readonly before?: string;
+  readonly after?: string;
+}
+/** Every layer on which two readings disagree, in key order. Empty means the
+ *  payloads are byte-identical. */
+export function diffLayerDigests(before: LayerDigests, after: LayerDigests): LayerChange[] {
+  const changes: LayerChange[] = [];
+  for (const layer of [...new Set([...Object.keys(before), ...Object.keys(after)])].sort()) {
+    const a = before[layer];
+    const b = after[layer];
+    if (a !== b) changes.push({ layer, ...(a ? { before: a } : {}), ...(b ? { after: b } : {}) });
+  }
+  return changes;
+}