@intentius/chant 0.37.0 → 0.38.0

package/src/op/emulator-freshness.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Generalized from `lexicons/fly/src/emulator-freshness.test.ts` (#1345), which
+ * covered fly's two pins. The check now reads every lexicon's declared spec.
+ */
+
+import { describe, test, expect } from "vitest";
+import { compare, parseVersion, latestRelease, checkFreshness, formatResult, unpinned } from "./emulator-freshness";
+import type { EmulatorSpec } from "./emulator-lifecycle";
+
+const spec = (over: Partial<EmulatorSpec> = {}): EmulatorSpec => ({
+  name: "chant-x",
+  image: "org/x:1.0.0",
+  containerPort: 1,
+  healthPath: "/h",
+  ...over,
+});
+
+describe("parseVersion", () => {
+  test("reads the tag off an image ref", () => {
+    expect(parseVersion("ghcr.io/intentius/mudflaps:0.4.1")).toBe("0.4.1");
+  });
+
+  test("strips a leading v", () => {
+    expect(parseVersion("floci/floci:v1.5.34")).toBe("1.5.34");
+  });
+
+  test("a registry port is not a tag", () => {
+    // `localhost:5000/floci` has a colon before the last slash.
+    expect(parseVersion("localhost:5000/floci")).toBe("");
+  });
+
+  test("an untagged ref has no version", () => {
+    expect(parseVersion("floci/floci")).toBe("");
+  });
+});
+
+describe("compare", () => {
+  test("behind when latest is newer", () => {
+    expect(compare("x", "0.4.1", "0.5.0").behind).toBe(true);
+  });
+
+  test("current when equal", () => {
+    expect(compare("x", "1.5.34", "1.5.34").behind).toBe(false);
+  });
+
+  test("not behind when the pin is ahead of the latest release", () => {
+    expect(compare("x", "2.0.0", "1.9.9").behind).toBe(false);
+  });
+
+  test("compares numerically, not lexically", () => {
+    // "10" < "9" as strings; the whole point of the parse.
+    expect(compare("x", "1.9.0", "1.10.0").behind).toBe(true);
+  });
+
+  test("a shorter version is padded with zeros", () => {
+    expect(compare("x", "1.5", "1.5.1").behind).toBe(true);
+    expect(compare("x", "1.5", "1.5.0").behind).toBe(false);
+  });
+
+  test("normalizes the v prefix out of the report", () => {
+    expect(compare("x", "v1.0.0", "v1.0.1")).toMatchObject({ pinned: "1.0.0", latest: "1.0.1" });
+  });
+});
+
+describe("unpinned", () => {
+  test("flags a floating tag", () => {
+    expect(unpinned([spec({ image: "floci/floci:latest" })]).map((s) => s.name)).toEqual(["chant-x"]);
+  });
+
+  test("flags an untagged image", () => {
+    expect(unpinned([spec({ image: "floci/floci" })])).toHaveLength(1);
+  });
+
+  test("a pinned image is not flagged", () => {
+    expect(unpinned([spec()])).toEqual([]);
+  });
+});
+
+describe("checkFreshness", () => {
+  const fakeFetch = (tag: string) =>
+    (async () => ({ ok: true, json: async () => ({ tag_name: tag }) })) as unknown as typeof fetch;
+
+  test("checks each spec that declares an upstream", async () => {
+    const results = await checkFreshness(
+      [spec({ name: "a", upstream: { repo: "o/a" } }), spec({ name: "b", upstream: { repo: "o/b" } })],
+      fakeFetch("1.0.0"),
+    );
+    expect(results.map((r) => r.name)).toEqual(["a", "b"]);
+  });
+
+  test("skips a spec with no upstream — a locally built image has no release feed", async () => {
+    expect(await checkFreshness([spec()], fakeFetch("9.9.9"))).toEqual([]);
+  });
+
+  test("skips a spec whose image carries no version", async () => {
+    expect(
+      await checkFreshness([spec({ image: "floci/floci", upstream: { repo: "o/a" } })], fakeFetch("1.0.0")),
+    ).toEqual([]);
+  });
+
+  test("reports behind when the release is newer than the pin", async () => {
+    const [result] = await checkFreshness(
+      [spec({ image: "org/x:1.0.0", upstream: { repo: "o/x" } })],
+      fakeFetch("1.2.0"),
+    );
+    expect(result).toMatchObject({ pinned: "1.0.0", latest: "1.2.0", behind: true });
+  });
+});
+
+describe("latestRelease", () => {
+  test("returns the tag name", async () => {
+    const fetchImpl = (async () => ({ ok: true, json: async () => ({ tag_name: "v2.1.0" }) })) as unknown as typeof fetch;
+    expect(await latestRelease("o/r", fetchImpl)).toBe("v2.1.0");
+  });
+
+  test("throws on a non-ok response rather than reporting a bogus version", async () => {
+    const fetchImpl = (async () => ({ ok: false, status: 404 })) as unknown as typeof fetch;
+    await expect(latestRelease("o/r", fetchImpl)).rejects.toThrow("HTTP 404");
+  });
+
+  test("throws when the release has no tag", async () => {
+    const fetchImpl = (async () => ({ ok: true, json: async () => ({}) })) as unknown as typeof fetch;
+    await expect(latestRelease("o/r", fetchImpl)).rejects.toThrow("no tag_name");
+  });
+});
+
+describe("formatResult", () => {
+  test("marks a behind pin", () => {
+    expect(formatResult(compare("chant-floci", "1.0.0", "1.1.0"))).toContain("behind");
+  });
+
+  test("marks a current pin", () => {
+    expect(formatResult(compare("chant-floci", "1.1.0", "1.1.0"))).toContain("current");
+  });
+});

package/src/op/emulator-freshness.ts

@@ -0,0 +1,102 @@
+/**
+ * How far behind an emulator's pinned image is (#1345, generalizing #808 T2).
+ *
+ * This began as `lexicons/fly/src/emulator-freshness.ts`, checking fly's two
+ * pins against their GitHub releases. The other three emulators — Floci for aws,
+ * floci-az, floci-gcp — ran `:latest`, so there was nothing to be behind and
+ * nothing to check: an image could change underneath a passing local test suite
+ * with no record in the repo of what moved.
+ *
+ * With the pin and its upstream declared on {@link EmulatorSpec}, the check
+ * covers every emulator any lexicon ships, and a new one is included by
+ * declaring `upstream` rather than by editing a list here.
+ *
+ * Advisory, never gating. Per the bump policy (#808) a pin moves when a
+ * consuming test needs the newer emulator, not because a release happened.
+ */
+
+import type { EmulatorSpec } from "./emulator-lifecycle";
+
+export interface FreshnessResult {
+  /** The emulator's container name, e.g. `chant-mudflaps`. */
+  name: string;
+  /** Pinned version, no leading `v`. */
+  pinned: string;
+  /** Latest released version, no leading `v`. */
+  latest: string;
+  /** True when the latest release is newer than the pin. */
+  behind: boolean;
+}
+
+/** The version tag of an image ref (`ghcr.io/x/mudflaps:0.3.1` → `0.3.1`). */
+export function parseVersion(image: string): string {
+  const lastColon = image.lastIndexOf(":");
+  const lastSlash = image.lastIndexOf("/");
+  // A registry port (`localhost:5000/x`) is not a tag.
+  if (lastColon < 0 || lastColon < lastSlash) return "";
+  return image.slice(lastColon + 1).replace(/^v/, "");
+}
+
+function toParts(version: string): number[] {
+  return version.replace(/^v/, "").split(".").map((n) => parseInt(n, 10) || 0);
+}
+
+/** Compare pinned against latest as dotted numeric versions. */
+export function compare(name: string, pinned: string, latest: string): FreshnessResult {
+  const p = toParts(pinned);
+  const l = toParts(latest);
+  let behind = false;
+  for (let i = 0; i < Math.max(p.length, l.length); i++) {
+    const a = p[i] ?? 0;
+    const b = l[i] ?? 0;
+    if (b > a) {
+      behind = true;
+      break;
+    }
+    if (b < a) break;
+  }
+  return { name, pinned: pinned.replace(/^v/, ""), latest: latest.replace(/^v/, ""), behind };
+}
+
+/** The latest release tag for a repo, via the GitHub REST API. */
+export async function latestRelease(repo: string, fetchImpl: typeof fetch = fetch): Promise<string> {
+  const headers: Record<string, string> = { Accept: "application/vnd.github+json" };
+  if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+  const res = await fetchImpl(`https://api.github.com/repos/${repo}/releases/latest`, { headers });
+  if (!res.ok) throw new Error(`releases/latest ${repo}: HTTP ${res.status}`);
+  const body = (await res.json()) as { tag_name?: string };
+  if (!body.tag_name) throw new Error(`releases/latest ${repo}: no tag_name`);
+  return body.tag_name;
+}
+
+/**
+ * Check every spec that declares an upstream. A spec without one is skipped
+ * rather than reported — an emulator built from a local image has no release
+ * feed to be behind.
+ */
+export async function checkFreshness(
+  specs: readonly EmulatorSpec[],
+  fetchImpl: typeof fetch = fetch,
+): Promise<FreshnessResult[]> {
+  const pinned = specs.filter((s) => s.upstream?.repo && parseVersion(s.image));
+  return Promise.all(
+    pinned.map(async (s) =>
+      compare(s.name, parseVersion(s.image), await latestRelease(s.upstream!.repo, fetchImpl)),
+    ),
+  );
+}
+
+/** One-line human summary of a result. */
+export function formatResult(r: FreshnessResult): string {
+  return r.behind
+    ? `⚠ ${r.name}: pinned ${r.pinned}, latest ${r.latest} — behind`
+    : `✓ ${r.name}: pinned ${r.pinned} is current (latest ${r.latest})`;
+}
+
+/** Emulator images that carry no version tag — `:latest` or none at all. */
+export function unpinned(specs: readonly EmulatorSpec[]): EmulatorSpec[] {
+  return specs.filter((s) => {
+    const version = parseVersion(s.image);
+    return version === "" || version === "latest";
+  });
+}

package/src/op/emulator-lifecycle.ts

@@ -22,6 +22,20 @@ export interface EmulatorSpec {
   ready?: (healthBody: string) => boolean;
   /** Extra `docker run` args inserted before the image (e.g. a socket mount). */
   runArgs?: readonly string[];
+  /**
+   * Where {@link image} is published, so how far behind the pin is can be
+   * answered (#1345).
+   *
+   * fly pinned its two emulators and tracked their freshness; aws, azure and gcp
+   * ran `floci/*:latest`, which is the drift a pin exists to stop — a local test
+   * suite that passes today and fails tomorrow because an image moved underneath
+   * it, with nothing in the repo recording what changed. Declaring the upstream
+   * makes the check general instead of one lexicon's private tooling.
+   */
+  upstream?: {
+    /** `owner/repo` whose latest GitHub release names the current version. */
+    repo: string;
+  };
 }
 
 /**
@@ -36,6 +50,41 @@ export interface EmulatorCapability {
   env(endpoint: string): Record<string, string>;
 }
 
+/**
+ * What a plugin declares: one emulator, or several (#1345).
+ *
+ * fly ships two — mudflaps for the Machines API and spritzer for Sprites — and
+ * a single-spec field could describe only one of them, so both stayed
+ * unreachable from `chant emulator` while the repo's docs presented them as
+ * first-class local targets.
+ */
+export type EmulatorDeclaration = EmulatorCapability | readonly EmulatorCapability[];
+
+/** Every emulator a plugin declares, normalized to a list. */
+export function emulatorsOf(declaration: EmulatorDeclaration | undefined): readonly EmulatorCapability[] {
+  if (!declaration) return [];
+  return Array.isArray(declaration) ? declaration : [declaration as EmulatorCapability];
+}
+
+/** Sentinel that cannot collide with a real endpoint or a credential value. */
+const ENDPOINT_PROBE = "chant-endpoint-probe://0";
+
+/**
+ * The env vars whose value *is* the endpoint, as opposed to the credentials and
+ * region an emulator also needs (#1345).
+ *
+ * Derived by asking `env()` for a sentinel and keeping the keys that carry it,
+ * so a lexicon states the mapping once in the place it already states it. The
+ * alternative — `LEXICON_ENDPOINT_ENV_VAR`, a hand-maintained map in core — held
+ * two of the four lexicons that have one, and its module doc asserted azure had
+ * none while `describe-resources.ts` read `AZURE_ENDPOINT_URL` on every call.
+ */
+export function endpointEnvVars(capability: EmulatorCapability): string[] {
+  return Object.entries(capability.env(ENDPOINT_PROBE))
+    .filter(([, value]) => value === ENDPOINT_PROBE)
+    .map(([key]) => key);
+}
+
 /** Per-call overrides for {@link EmulatorLifecycle.up} / `runCommand`. */
 export interface EmulatorUpArgs {
   name?: string;

package/src/op/index.ts

@@ -9,8 +9,10 @@ export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForSta
          spritesUp, spritesDown } from "./builders";
 export { OpResource } from "./resource";
 export { safeHeartbeat, sleep } from "./activity-runtime";
-export { emulatorLifecycle } from "./emulator-lifecycle";
-export type { EmulatorSpec, EmulatorCapability, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
+export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-lifecycle";
+export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
+export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
+export type { FreshnessResult } from "./emulator-freshness";
 export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";

package/src/ownership.ts

@@ -128,3 +128,44 @@ export function readOwnership(
     env: typeof env === "string" ? env : undefined,
   };
 }
+
+/**
+ * A read path that can resolve an ownership verdict from the marker (#1348).
+ *
+ * Per-path rather than per-lexicon because the answer genuinely differs by
+ * path: aws stamps tags at synthesis and reads them on the deep observation and
+ * on live export, but `describeResources` is sourced from
+ * `describe-stack-resources`, which returns no tags at all — so an `owned: true`
+ * thin read against aws can only answer `unknown`.
+ */
+export type OwnershipReadPath = "describeResources" | "observeResourcesDeep" | "exportResources";
+
+/**
+ * Where a lexicon can stamp and read chant's ownership marker (#1348).
+ *
+ * `ResourceMetadata.ownership` documents an obligation — a lexicon with no
+ * marker channel on a path must stamp `unknown` rather than degrade silently,
+ * because the change set never escalates `unknown` to a delete — and that
+ * obligation had no type, no declaration, and no check. A caller could not
+ * learn whether `owned: true` was answerable except by asking and reading a
+ * warning on stderr afterwards, which is invisible to `lifecycle plan`, which
+ * is where the wrong delete gets proposed.
+ *
+ * Absent means the lexicon has no marker channel at all: every verdict it
+ * returns must be `unknown`. Declaring one is a claim the conformance suite
+ * checks — on a declared path, verdicts must be `owned` or `foreign`.
+ */
+export interface OwnershipChannel {
+  /** The provider-native keys this lexicon stamps into. */
+  readonly keys: ChannelKeys;
+  /** The read paths that resolve a verdict from the marker. */
+  readonly reads: readonly OwnershipReadPath[];
+}
+
+/** Whether this lexicon resolves a real verdict on `path`, or can only say `unknown`. */
+export function resolvesOwnershipOn(
+  channel: OwnershipChannel | undefined,
+  path: OwnershipReadPath,
+): boolean {
+  return channel?.reads.includes(path) ?? false;
+}

package/src/serializer.ts

@@ -52,6 +52,22 @@ export interface Serializer {
    */
   rulePrefix: string;
 
+  /**
+   * Further id families this lexicon owns, beyond {@link rulePrefix} (#1349).
+   *
+   * The prefix exists so ids do not collide when several lexicons are loaded
+   * together — forgejo wraps github's rules as `WFJ-GHA0xx` for exactly that
+   * reason. It was declared and checked by nothing, and k8s quietly shipped
+   * five `ARGO0xx` checks outside its own `WK8`.
+   *
+   * A second family is sometimes right: Argo CD is a distinct product surface
+   * that happens to be covered by the k8s lexicon, and renaming published ids
+   * would break every `chant-disable ARGO001` in the wild. Declaring it keeps
+   * the collision guarantee while allowing the split — an undeclared family is
+   * a tier-1 failure.
+   */
+  extraRulePrefixes?: readonly string[];
+
   /**
    * Serializes the entities to a string representation
    * @param entities - Map of entity name to Declarable entity