@sous-io/sous 0.2.36 → 1.0.1

package/src/lib/repos/formats/common.ts

@@ -1,440 +0,0 @@
-/**
- * Shared building blocks for every Repositories on-disk format.
- *
- * Each format module (repo manifest, recipe manifest, index file, lockfile,
- * store entry marker, links map) composes the primitives defined here, so a
- * namespace name, a content hash or a timestamp means exactly the same thing
- * everywhere. This module also holds the canonical file names and the shared
- * `parseFormat` helper that turns a zod failure into a readable ConfigError.
- */
-
-import { z } from "zod";
-import semver from "semver";
-import { ConfigError } from "../../errors.js";
-import {
-  CONTENT_HASH_PATTERN,
-  ENV_VAR_NAME_PATTERN,
-  ISO_TIMESTAMP_PATTERN,
-  KEBAB_NAME_PATTERN,
-  NAMESPACE_NAME_PATTERN,
-  RECIPE_KEY_PATTERN,
-  RECIPE_NAME_PATTERN,
-  REF_KEY_PATTERN,
-  REPO_IDENTITY_PATTERN,
-  REPO_NAME_PATTERN,
-  VARIABLE_NAME_PATTERN,
-} from "./patterns.js";
-
-export {
-  CONTENT_HASH_PATTERN,
-  ENV_VAR_NAME_PATTERN,
-  ISO_TIMESTAMP_PATTERN,
-  KEBAB_NAME_PATTERN,
-  NAMESPACE_NAME_PATTERN,
-  RECIPE_KEY_PATTERN,
-  RECIPE_NAME_PATTERN,
-  REF_KEY_PATTERN,
-  REPO_IDENTITY_PATTERN,
-  REPO_NAME_PATTERN,
-  VARIABLE_NAME_PATTERN,
-};
-
-// --- Format version -----------------------------------------------------------------------------
-
-/**
- * The only on-disk format version this sous understands. Every manifest, index,
- * lockfile, store entry marker and links map carries it as `formatVersion`, so
- * a future incompatible change can be detected instead of misread.
- */
-export const SUPPORTED_FORMAT_VERSION = 1;
-
-/** The `formatVersion` field, present in every Repositories format. */
-export const formatVersionSchema = z.literal(SUPPORTED_FORMAT_VERSION, {
-  message:
-    `must be ${SUPPORTED_FORMAT_VERSION}; this version of sous understands no other ` +
-    `on-disk format version`,
-});
-
-// --- Canonical file names -----------------------------------------------------------------------
-
-/** Base name (without extension) of the repo manifest, at a repo's root. */
-export const REPO_MANIFEST_BASENAME = "sous.repo";
-
-/** Base name (without extension) of a recipe manifest, in each recipe folder. */
-export const RECIPE_MANIFEST_BASENAME = "sous.recipe";
-
-/** File name of the machine-written repo index, at a repo's root. */
-export const INDEX_FILENAME = "sous.index.json";
-
-/** File name of the project lockfile, inside the project's `.sous/` directory. */
-export const LOCKFILE_FILENAME = "sous.lock.json";
-
-/** File name of the marker written beside every store entry. */
-export const STORE_ENTRY_FILENAME = ".sous.entry.json";
-
-/**
- * Directory, inside the store root, that cached repository indexes live in. It
- * is named here rather than in the index cache so the store can skip it while
- * walking its own entries without depending on the provider layer.
- */
-export const INDEX_CACHE_DIRNAME = "_indexes";
-
-/** File name of the links map, in a project's `.sous/` directory or in `$SOUS_HOME`. */
-export const LINKS_FILENAME = "sous.links.json";
-
-/**
- * Extensions a hand-written manifest may use, in the order they are tried when
- * discovering one. Both `.json` and `.jsonc` are parsed permissively (comments
- * and trailing commas are allowed); see `load-manifest.ts`.
- */
-export const MANIFEST_EXTENSIONS = [".yaml", ".yml", ".json", ".jsonc"] as const;
-
-// --- Name primitives ----------------------------------------------------------------------------
-
-/** Builds a kebab-case name schema with a message naming what is being named. */
-function kebabName(label: string, example: string) {
-  return z
-    .string()
-    .regex(
-      KEBAB_NAME_PATTERN,
-      `a ${label} must be lowercase kebab-case: a letter, then letters, digits or ` +
-        `hyphens (for example '${example}')`
-    );
-}
-
-/** A repo's short name, as used by the `repo:` qualifier on a ref. */
-export const repoNameSchema = kebabName("repo name", "sous-recipes");
-
-/**
- * A repository's canonical identity, `<host>/<owner path>/<name>`. Everything
- * shared between projects (the machine-wide store, the index cache, a
- * lockfile's record of where a recipe came from) keys by this rather than by a
- * short name, because a short name is one project's private label.
- */
-export const repoIdentitySchema = z
-  .string()
-  .regex(
-    REPO_IDENTITY_PATTERN,
-    "a repository identity must be its host followed by the path it lives at, all " +
-      "lowercase (for example 'github.com/sous-io/sous-recipes')"
-  );
-
-/** A namespace name. */
-export const namespaceNameSchema = kebabName("namespace name", "tool-usage");
-
-/** A recipe name, unique within its namespace. */
-export const recipeNameSchema = kebabName("recipe name", "task-files");
-
-/** A camelCase variable name, as declared by a recipe variable definition. */
-export const variableNameSchema = z
-  .string()
-  .regex(
-    VARIABLE_NAME_PATTERN,
-    "a variable name must be camelCase: a lowercase letter, then letters or digits " +
-      "(for example 'apiBaseUrl')"
-  );
-
-/** An explicit environment variable name for a variable definition. */
-export const envVarNameSchema = z
-  .string()
-  .regex(
-    ENV_VAR_NAME_PATTERN,
-    "an environment variable name must be upper snake case: a capital letter, then " +
-      "capitals, digits or underscores (for example 'GITHUB_TOKEN')"
-  );
-
-/** A ref key: a bare namespace, or `namespace/recipe`. Never repo-qualified or ranged. */
-export const refKeySchema = z
-  .string()
-  .regex(
-    REF_KEY_PATTERN,
-    "a ref key must be a namespace ('workflow') or a namespace and recipe " +
-      "('workflow/task-files'), with no repo qualifier and no version range"
-  );
-
-/** A recipe key: always `namespace/recipe`. */
-export const recipeKeySchema = z
-  .string()
-  .regex(
-    RECIPE_KEY_PATTERN,
-    "a recipe key must be a namespace and recipe joined by a slash " +
-      "(for example 'workflow/task-files')"
-  );
-
-/**
- * The two ways one recipe can bring in another, named after the manifest lists
- * that declare them: `subscribes` is a co-subscription, whose files land in the
- * project and whose questions are asked; `depends` is a build dependency, a
- * library whose files never reach the project's output.
- */
-export const DEPENDENCY_KINDS = ["subscribes", "depends"] as const;
-
-/** A co-subscription or a build dependency. */
-export const dependencyKindSchema = z.enum(DEPENDENCY_KINDS);
-
-/** A co-subscription or a build dependency. */
-export type DependencyKind = (typeof DEPENDENCY_KINDS)[number];
-
-// --- Value primitives ---------------------------------------------------------------------------
-
-/** An exact semantic version, as published by a recipe. */
-export const semverVersionSchema = z
-  .string()
-  .refine((value) => semver.valid(value) !== null, {
-    message:
-      "must be an exact semantic version, such as '1.4.0' or '2.0.0-beta.1'",
-  });
-
-/** A semantic version range, resolved with the same rules npm uses. */
-export const semverRangeSchema = z
-  .string()
-  .refine((value) => semver.validRange(value) !== null, {
-    message:
-      "must be a semantic version range, such as '^1.2.0', '~2.1', '>=1.0.0 <2.0.0' or '*'",
-  });
-
-/** A content hash over a recipe's files, written as `sha256-` plus lowercase hex. */
-export const contentHashSchema = z
-  .string()
-  .regex(
-    CONTENT_HASH_PATTERN,
-    "a content hash must be written as 'sha256-' followed by 64 lowercase hexadecimal characters"
-  );
-
-/** An ISO 8601 timestamp with an explicit offset. */
-export const isoTimestampSchema = z
-  .string()
-  .regex(
-    ISO_TIMESTAMP_PATTERN,
-    "must be an ISO 8601 timestamp with an offset, such as '2026-09-09T14:03:11.482Z'"
-  );
-
-/** A byte count: a whole number, never negative. */
-export const byteCountSchema = z
-  .number()
-  .int("must be a whole number of bytes")
-  .min(0, "must not be negative");
-
-/**
- * Where a repository lives. A hosted repository is named by a URL; a repository
- * on this machine, which the `local` provider reads, is named by an absolute
- * path or by the same path in `file:///...` form (which is already a URL).
- */
-export const repoUrlSchema = z.union([
-  z.url(),
-  z
-    .string()
-    .min(1, "must not be empty")
-    .refine((value) => value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value), {
-      message: "must be a repository URL, or an absolute path to one on this machine",
-    }),
-]);
-
-/** An absolute filesystem path. */
-export const absolutePathSchema = z
-  .string()
-  .min(1, "must not be empty")
-  .refine((value) => value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value), {
-    message: "must be an absolute path",
-  });
-
-/**
- * Builds a schema for a path that stays inside the directory holding the file
- * that declares it. Rejects absolute paths, backslashes, `.` and `..` segments,
- * empty segments and trailing slashes, so a manifest can never reach outside
- * its own repo or recipe.
- *
- * @param label - What the path names, used in error messages.
- * @param allowGlobs - When true, `*`, `?`, `[...]`, `{...}` and a `**` segment are allowed.
- */
-export function relativePathSchema(label: string, allowGlobs = false) {
-  return z.string().superRefine((value, ctx) => {
-    const fail = (message: string) => {
-      ctx.addIssue({ code: "custom", message: `${label} ${message}` });
-    };
-
-    if (value.length === 0) {
-      fail("must not be empty");
-      return;
-    }
-    if (value.startsWith("/") || /^[A-Za-z]:[\\/]/.test(value)) {
-      fail("must be relative, not absolute");
-      return;
-    }
-    if (value.includes("\\")) {
-      fail("must use forward slashes, never backslashes");
-      return;
-    }
-    if (value.endsWith("/")) {
-      fail("must not end with a slash");
-      return;
-    }
-    if (!allowGlobs && /[*?[\]{}]/.test(value)) {
-      fail("must be a plain path, with no glob characters");
-      return;
-    }
-
-    for (const segment of value.split("/")) {
-      if (segment.length === 0) {
-        fail("must not contain an empty path segment");
-        return;
-      }
-      if (segment === "." || segment === "..") {
-        fail("must not contain a '.' or '..' segment");
-        return;
-      }
-    }
-  });
-}
-
-// --- Object helpers -----------------------------------------------------------------------------
-
-/** True when the value is a plain object (not null, not an array). */
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-/**
- * Drops keys in the reserved `x-` extension namespace from a plain object.
- * Anything that is not a plain object passes through untouched, so the wrapped
- * object schema still reports "expected object" for a string or an array.
- */
-function stripExtensionKeys(value: unknown): unknown {
-  if (!isPlainObject(value)) return value;
-  let found = false;
-  for (const key of Object.keys(value)) {
-    if (key.startsWith("x-")) {
-      found = true;
-      break;
-    }
-  }
-  if (!found) return value;
-
-  const copy: Record<string, unknown> = {};
-  for (const [key, entry] of Object.entries(value)) {
-    if (!key.startsWith("x-")) copy[key] = entry;
-  }
-  return copy;
-}
-
-/**
- * Builds a strict object schema for a HAND-WRITTEN format: unknown keys are
- * rejected so typos surface immediately, except keys in the reserved `x-`
- * extension namespace, which are accepted and ignored. Machine-written formats
- * use `z.strictObject` or `forwardCompatibleObject` instead; nothing writes
- * extension keys into them.
- */
-export function extensibleObject<Shape extends z.ZodRawShape>(shape: Shape) {
-  return z.preprocess(stripExtensionKeys, z.strictObject(shape));
-}
-
-/**
- * Builds an object schema for a machine-written format that other versions of
- * sous publish and this one reads: the repo index. Every known key is validated
- * exactly as strictly as `z.strictObject` would, and a key this version does not
- * define is kept, unread, rather than refused.
- *
- * A later sous adds fields to the index, and a repository published by it is
- * read by every older sous a project happens to pin; refusing the whole index
- * over a field it cannot use would break those projects for nothing. The key is
- * kept rather than dropped, so a release carrying a published version forward
- * writes it back byte for byte, whichever sous runs the release.
- */
-export function forwardCompatibleObject<Shape extends z.ZodRawShape>(shape: Shape) {
-  return z.looseObject(shape);
-}
-
-/**
- * The `submissions` block a repo manifest and a recipe manifest may both carry:
- * whether the recipes it covers take proposed changes, and where to send a
- * change instead when they do not. On a repo manifest it covers every recipe;
- * on a recipe manifest it covers that recipe, and wins over the repository's.
- *
- *     submissions:
- *       allowed: false
- *       instead: Propose changes in sous-io/sous, under recipes/core/sous-skills/.
- */
-export const submissionsSchema = extensibleObject({
-  /** Whether a proposed change to the covered recipes is accepted. Defaults to true. */
-  allowed: z.boolean().default(true),
-  /** Where a change should go instead, printed when one is proposed anyway. */
-  instead: z.string().min(1, "must not be empty").optional(),
-});
-
-/** A validated `submissions` block. */
-export type Submissions = z.infer<typeof submissionsSchema>;
-
-// --- Error reporting ----------------------------------------------------------------------------
-
-/** Renders a zod issue path (`["variables",0,"name"]`) as `variables[0].name`. */
-export function formatIssuePath(parts: ReadonlyArray<PropertyKey>): string {
-  let out = "";
-  for (const part of parts) {
-    if (typeof part === "number") out += `[${part}]`;
-    else out += out.length > 0 ? `.${String(part)}` : String(part);
-  }
-  return out;
-}
-
-/**
- * Validates a value against a format schema, returning it typed. Throws a
- * ConfigError (never a raw ZodError) naming the format, the file it came from
- * and the path of every bad field.
- *
- * @param schema - The zod schema for the format.
- * @param value - The already-parsed file contents.
- * @param sourceLabel - The file path (or other label) named in error messages.
- * @param formatLabel - Plain-language name of the format, such as "recipe manifest".
- */
-export function parseFormat<Schema extends z.ZodType>(
-  schema: Schema,
-  value: unknown,
-  sourceLabel: string,
-  formatLabel: string
-): z.output<Schema> {
-  const result = schema.safeParse(value);
-  if (result.success) return result.data;
-
-  const lines: string[] = [`Invalid ${formatLabel} at ${sourceLabel}:`];
-  for (const issue of result.error.issues) {
-    const where = formatIssuePath(issue.path);
-    if (issue.code === "unrecognized_keys") {
-      const keys = issue.keys.map((key) => `'${key}'`).join(", ");
-      const location = where.length > 0 ? `under '${where}'` : "at the top level";
-      lines.push(
-        `  - unknown key ${keys} ${location}. This is likely a typo; sous ignores ` +
-          `only keys that start with 'x-'.`
-      );
-    } else if (issue.code === "invalid_key") {
-      // zod reports a bad record KEY as a generic "Invalid key in record" and
-      // hides the real reason in a nested issue list. Surface the reason, since
-      // it is the part that tells the author how to fix the key.
-      const reasons = issue.issues.map((inner) => inner.message).join("; ");
-      lines.push(`  - ${where}: invalid key; ${reasons}`);
-    } else {
-      lines.push(`  - ${where.length > 0 ? where : "(root)"}: ${issue.message}`);
-    }
-  }
-
-  throw new ConfigError(lines.join("\n"));
-}
-
-/**
- * Serializes a value as pretty-printed JSON with every object key sorted, so a
- * machine-written file produces a stable, minimal diff between runs.
- */
-export function stableJsonStringify(value: unknown): string {
-  return JSON.stringify(sortKeysDeep(value), null, 2) + "\n";
-}
-
-/** Recursively rebuilds plain objects with their keys in sorted order. */
-function sortKeysDeep(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(sortKeysDeep);
-  if (!isPlainObject(value)) return value;
-
-  const sorted: Record<string, unknown> = {};
-  for (const key of Object.keys(value).sort()) {
-    sorted[key] = sortKeysDeep(value[key]);
-  }
-  return sorted;
-}

package/src/lib/repos/formats/index-file.ts

@@ -1,253 +0,0 @@
-/**
- * The repo index: `sous.index.json` at a repo's root.
- *
- * The index is MACHINE-WRITTEN by `sous repo release` and committed alongside
- * the recipes it describes. It is the portable contract across providers: every
- * provider, whatever its API looks like, can hand back this one file, and it is
- * all sous needs to resolve a ref, enumerate published versions and check
- * whether a cached copy is current.
- *
- * Adding a repo fetches only this file. Nothing else is downloaded until a
- * project subscribes to something inside it.
- *
- * Every object in it is a `forwardCompatibleObject`: a field a later sous adds is
- * kept and ignored rather than refused, so an index published by a newer sous
- * still reads here. The fields this version defines are validated in full.
- */
-
-import { z } from "zod";
-import {
-  contentHashSchema,
-  dependencyKindSchema,
-  formatVersionSchema,
-  forwardCompatibleObject,
-  isoTimestampSchema,
-  namespaceNameSchema,
-  parseFormat,
-  recipeKeySchema,
-  relativePathSchema,
-  repoIdentitySchema,
-  repoNameSchema,
-  semverRangeSchema,
-  semverVersionSchema,
-  stableJsonStringify,
-} from "./common.js";
-import { publishedVariableDefinitionSchema } from "./variable-definition.js";
-import { namespaceOfKey } from "../../../services/ref-resolver/index.js";
-
-/**
- * One dependency of one published version, as the release resolved it.
- *
- * A SIBLING (a recipe in this same repository) always resolves to an exact
- * version, because the release that wrote this entry cut that sibling's tag or
- * found it already cut. A CROSS-REPOSITORY dependency carries the identity of
- * the repository it lives in, which is what a consumer needs in order to add
- * that repository and find the recipe in the store; the version it resolves to
- * belongs to that repository's own index, so this entry carries the range the
- * manifest declared instead.
- */
-export const indexDependencySchema = forwardCompatibleObject({
-  /** The exact version this dependency resolved to, when the release could resolve one. */
-  version: semverVersionSchema.optional(),
-  /** The range the manifest declared, recorded when no exact version could be resolved. */
-  range: semverRangeSchema.optional(),
-  /**
-   * The canonical identity of the repository publishing it
-   * (`github.com/sous-io/sous-recipes`). Omitted for a sibling, which lives in
-   * this same repository.
-   */
-  repo: repoIdentitySchema.optional(),
-  /**
-   * The entry of the version's manifest that brings this dependency in, exactly
-   * as it was written: a recipe (`workflow/task-files`, with its range when it
-   * has one), a whole namespace of this repository (`workflow`), or a locator
-   * naming a recipe in another repository. When several entries cover the same
-   * recipe, the one naming it wins over a namespace. Absent on an entry recorded
-   * before sous described recipes in the index (ADR 0010).
-   */
-  declared: z.string().min(1, "must not be empty").optional(),
-  /**
-   * Whether that brings it in as a co-subscription (`subscribes`: its files
-   * land in the project and its questions are asked) or as a build dependency
-   * (`depends`: a library only); `subscribes` when any entry covering it is a
-   * co-subscription. Recorded alongside `declared`.
-   */
-  kind: dependencyKindSchema.optional(),
-}).refine((entry) => entry.version !== undefined || entry.range !== undefined, {
-  message:
-    "must record either the exact version this dependency resolved to or the range " +
-    "the recipe declared",
-});
-
-/** One published version of one recipe. */
-export const indexVersionSchema = forwardCompatibleObject({
-  /** Content hash of the recipe folder at this version, verified after every fetch. */
-  hash: contentHashSchema,
-  /**
-   * The git tag carrying this version, shaped `namespace/recipe@version`. The
-   * index's `superRefine` checks it against the key and version it sits under,
-   * so a version can never point at a branch or at another recipe's tag.
-   */
-  tag: z.string().min(1, "must not be empty"),
-  /** True when the version is a prerelease, which ranges skip unless opted in. */
-  prerelease: z.boolean(),
-  /**
-   * True when this version is not one the repository published, but the copy of
-   * the recipe that ships inside the installed sous package, folded into the
-   * index in memory so it can be resolved like anything else.
-   *
-   * Sous never writes this onto a copy of an index it fetched; a cached index
-   * stays exactly what upstream served. The field exists so that a listing can
-   * say the version came packaged with sous rather than from the repository, and
-   * so a reader of the stand-in index sous writes for itself can tell.
-   */
-  seeded: z.boolean().optional(),
-  /** When the version was released. */
-  releasedAt: isoTimestampSchema.optional(),
-  /**
-   * What this exact version depends on, resolved at release time and keyed
-   * `namespace/recipe`. A consumer installing this version installs these
-   * versions rather than re-resolving the ranges its manifest declared, so a
-   * published version means one thing forever.
-   *
-   * The field is additive: an index written before it existed still parses, and
-   * a consumer that finds no entry falls back to the manifest's ranges. A
-   * version described in full (ADR 0010) carries this field even when it is
-   * empty, so "depends on nothing" and "not recorded" read differently.
-   */
-  dependencies: z.record(recipeKeySchema, indexDependencySchema).optional(),
-  /**
-   * The variable definitions this version's manifest publishes, in manifest
-   * order: the questions subscribing to it asks. An empty list means it asks
-   * none; an absent field means the release that recorded the version did not
-   * record them (a release made before ADR 0010), and only the recipe's own
-   * files can say.
-   */
-  variables: z.array(publishedVariableDefinitionSchema).optional(),
-  /**
-   * The version's manifest `depends` and `subscribes` lists, exactly as
-   * written, so a consumer walks a recipe whose files it has not fetched the
-   * same way it walks its manifest: a namespace still expands to what the
-   * namespace holds, including a namespace of another repository, which no
-   * key of `dependencies` can record. Written, even when empty, beside
-   * `variables`; absent on a version recorded before ADR 0010. Kept as plain
-   * strings, so a ref form a later sous accepts never breaks this reader.
-   */
-  depends: z.array(z.string().min(1, "must not be empty")).optional(),
-  subscribes: z.array(z.string().min(1, "must not be empty")).optional(),
-});
-
-/** One recipe, with every version the repo publishes of it. */
-export const indexRecipeSchema = forwardCompatibleObject({
-  /** The recipe folder, relative to the repo root. */
-  path: relativePathSchema("a recipe path"),
-  /** One-paragraph summary, copied from the recipe manifest at release time. */
-  description: z.string().optional(),
-  /** Every published version, keyed by the exact version string. */
-  versions: z
-    .record(semverVersionSchema, indexVersionSchema)
-    .refine((versions) => Object.keys(versions).length > 0, {
-      message: "must list at least one published version",
-    }),
-});
-
-/** One namespace declaration, copied from the repo manifest at release time. */
-export const indexNamespaceSchema = forwardCompatibleObject({
-  description: z.string().optional(),
-});
-
-/** The repo index schema. */
-export const indexFileSchema = forwardCompatibleObject({
-  /**
-   * A plain-language note about where this copy of the index came from. JSON
-   * has no comment syntax and an index is machine-written, so this is the one
-   * place a writer can say something to whoever opens the file. Sous ignores
-   * the value everywhere except one place: the seed index it writes for its
-   * own built-in repository carries `SEED_INDEX_COMMENT`, which is how a
-   * later run recognizes its own placeholder and is willing to replace it.
-   */
-  $comment: z.string().optional(),
-  formatVersion: formatVersionSchema,
-  /** The repo's suggested short name, copied from its manifest. */
-  name: repoNameSchema,
-  /** When this index was generated. */
-  generatedAt: isoTimestampSchema,
-  /** The version of sous that generated it. */
-  generator: semverVersionSchema,
-  /** Every namespace the repo publishes. */
-  namespaces: z.record(namespaceNameSchema, indexNamespaceSchema),
-  /** Every recipe the repo publishes, keyed `namespace/recipe`. */
-  recipes: z.record(recipeKeySchema, indexRecipeSchema),
-}).superRefine((index, ctx) => {
-  // A recipe whose namespace is not declared could never be resolved, so a
-  // release that produced one is broken; say which recipe and which namespace.
-  for (const key of Object.keys(index.recipes)) {
-    const namespace = namespaceOfKey(key);
-    if (!Object.hasOwn(index.namespaces, namespace)) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["recipes", key],
-        message:
-          `belongs to the namespace '${namespace}', which this index does not ` +
-          `declare under 'namespaces'`,
-      });
-    }
-  }
-
-  // A version's tag is what the provider fetches, so a tag that does not
-  // name this exact recipe and version is a version pointing somewhere else.
-  // Nothing on the consumer side could otherwise tell: an index publishing
-  // `1.0.0` with `tag: "main"` would hand `git clone --branch main` a moving
-  // target, whose content changes on every push and whose pinned hash then
-  // simply starts failing. Sous writes these tags itself, so requiring the
-  // shape it writes costs a correct index nothing.
-  for (const [key, recipe] of Object.entries(index.recipes)) {
-    for (const [version, published] of Object.entries(recipe.versions)) {
-      const expected = `${key}@${version}`;
-      if (published.tag === expected) continue;
-      ctx.addIssue({
-        code: "custom",
-        path: ["recipes", key, "versions", version, "tag"],
-        message:
-          `is '${published.tag}', but a published version's tag names the recipe and ` +
-          `the version it carries, so this one must be '${expected}'`,
-      });
-    }
-  }
-});
-
-/** A validated repo index. */
-export type IndexFile = z.infer<typeof indexFileSchema>;
-
-/** One recipe entry in a repo index. */
-export type IndexRecipe = z.infer<typeof indexRecipeSchema>;
-
-/** One published version entry in a repo index. */
-export type IndexVersion = z.infer<typeof indexVersionSchema>;
-
-/** One resolved dependency of one published version. */
-export type IndexDependency = z.infer<typeof indexDependencySchema>;
-
-/** One namespace entry in a repo index. */
-export type IndexNamespace = z.infer<typeof indexNamespaceSchema>;
-
-/**
- * Validates a parsed repo index, throwing a ConfigError that names the file and
- * the path of every bad field.
- *
- * @param value - The parsed contents of the index file.
- * @param sourceLabel - The index's file path or URL, named in error messages.
- */
-export function parseIndexFile(value: unknown, sourceLabel: string): IndexFile {
-  return parseFormat(indexFileSchema, value, sourceLabel, "repo index");
-}
-
-/**
- * Serializes a repo index for writing, with every object key sorted so a
- * regenerated index produces a minimal diff.
- *
- * @param index - The index to write.
- */
-export function stringifyIndexFile(index: IndexFile): string {
-  return stableJsonStringify(index);
-}