@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/repos/release/tags.ts

@@ -0,0 +1,243 @@
+/**
+ * Git tags as the cheap enumeration path for published recipe versions.
+ *
+ * Recipe metadata is the source of truth for versions; a tag shaped
+ * `namespace/recipe@1.2.3` is a convenience ref that points at the commit the
+ * version was published from. The two must agree, and this module is what makes
+ * that checkable: it names tags, lists them, reads a file back out of one, and
+ * materializes a tagged recipe folder so its content can be hashed.
+ *
+ * Every function takes the injectable command runner, so a test drives the whole
+ * surface against a repository made with `git init` and never reaches a network.
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { runGit, type RunOptions } from "../providers/git.js";
+import { RECIPE_KEY_PATTERN } from "../formats/patterns.js";
+
+/** One release tag, taken apart into the recipe it publishes. */
+export type RecipeTag = {
+  /** The tag exactly as git holds it, `namespace/recipe@version`. */
+  tag: string;
+  /** The recipe's namespace. */
+  namespace: string;
+  /** The recipe's name. */
+  name: string;
+  /** The exact version the tag publishes. */
+  version: string;
+};
+
+/** The recipe key (`namespace/recipe`) a tag belongs to. */
+export function recipeTagKey(tag: RecipeTag): string {
+  return `${tag.namespace}/${tag.name}`;
+}
+
+/**
+ * The tag that publishes one version of one recipe.
+ *
+ * @param namespace - The recipe's namespace.
+ * @param name - The recipe's name.
+ * @param version - The exact version being published.
+ */
+export function tagFor(namespace: string, name: string, version: string): string {
+  return `${namespace}/${name}@${version}`;
+}
+
+/**
+ * Takes a tag apart, or returns undefined when it is not a recipe release tag.
+ * A repository may carry tags of its own shape (`v1.2.0`, say), and those are
+ * simply not ours.
+ *
+ * @param tag - The tag name as git holds it.
+ */
+export function parseRecipeTag(tag: string): RecipeTag | undefined {
+  const at = tag.lastIndexOf("@");
+  if (at <= 0 || at === tag.length - 1) return undefined;
+
+  const key = tag.slice(0, at);
+  const version = tag.slice(at + 1);
+  if (!RECIPE_KEY_PATTERN.test(key)) return undefined;
+
+  const slash = key.indexOf("/");
+  return {
+    tag,
+    namespace: key.slice(0, slash),
+    name: key.slice(slash + 1),
+    version,
+  };
+}
+
+/**
+ * Every recipe release tag in a repository, in the order git lists them. Tags
+ * that are not shaped like a recipe release are left out.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param options - The command runner to use.
+ */
+export async function listRecipeTags(
+  rootDir: string,
+  options: RunOptions = {}
+): Promise<RecipeTag[]> {
+  const output = await runGit(["tag", "--list", "*@*"], {
+    cwd: rootDir,
+    run: options.run,
+  });
+  if (output.length === 0) return [];
+
+  const tags: RecipeTag[] = [];
+  for (const line of output.split("\n")) {
+    const parsed = parseRecipeTag(line.trim());
+    if (parsed !== undefined) tags.push(parsed);
+  }
+  return tags;
+}
+
+/**
+ * The contents of one file as it stood at a tag, or undefined when the tag does
+ * not carry that file.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param tag - The tag to read at.
+ * @param relativePath - The file's path relative to the repository root.
+ * @param options - The command runner to use.
+ */
+export async function readFileAtTag(
+  rootDir: string,
+  tag: string,
+  relativePath: string,
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  try {
+    return await runGit(["show", `${tag}:${toPosix(relativePath)}`], {
+      cwd: rootDir,
+      run: options.run,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * When the commit a tag points at was made, as an ISO 8601 timestamp, or
+ * undefined when git cannot say.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param tag - The tag to date.
+ * @param options - The command runner to use.
+ */
+export async function tagCommitDate(
+  rootDir: string,
+  tag: string,
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  let raw: string;
+  try {
+    raw = await runGit(["log", "-1", "--format=%cI", tag], {
+      cwd: rootDir,
+      run: options.run,
+    });
+  } catch {
+    return undefined;
+  }
+
+  const parsed = new Date(raw.trim());
+  if (Number.isNaN(parsed.getTime())) return undefined;
+  return parsed.toISOString();
+}
+
+/**
+ * Checks out the tree at a tag into a temporary directory, hands the caller the
+ * path of one folder inside it, and cleans up afterwards.
+ *
+ * A linked worktree is used rather than `git archive` piped into a tar reader:
+ * the command runner captures output as text, so an archive's bytes could not
+ * survive the trip, while a worktree puts the real files on disk where they can
+ * be read and hashed exactly as a fetched copy would be.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param tag - The tag to check out.
+ * @param subPath - The folder inside the tree to hand back, relative to the root.
+ * @param use - Called with the absolute path of that folder.
+ * @param options - The command runner to use.
+ */
+export async function withTaggedTree<T>(
+  rootDir: string,
+  tag: string,
+  subPath: string,
+  use: (dir: string) => Promise<T>,
+  options: RunOptions = {}
+): Promise<T> {
+  const workRoot = await fs.mkdtemp(path.join(os.tmpdir(), "sous-release-"));
+  const checkout = path.join(workRoot, "tree");
+
+  try {
+    await runGit(["worktree", "add", "--detach", "--quiet", checkout, tag], {
+      cwd: rootDir,
+      run: options.run,
+    });
+    return await use(path.join(checkout, ...toPosix(subPath).split("/")));
+  } finally {
+    // Remove the worktree through git first, so its administrative record goes
+    // with it; a plain delete would leave the repository listing a worktree
+    // that is no longer there.
+    try {
+      await runGit(["worktree", "remove", "--force", checkout], {
+        cwd: rootDir,
+        run: options.run,
+      });
+    } catch {
+      // The worktree was never created, or git already dropped it. Either way
+      // the temporary directory below is what actually needs removing.
+    }
+    await fs.rm(workRoot, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Creates an annotated tag on HEAD.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param tag - The tag to create.
+ * @param message - The tag's annotation message.
+ * @param options - The command runner to use.
+ */
+export async function createAnnotatedTag(
+  rootDir: string,
+  tag: string,
+  message: string,
+  options: RunOptions = {}
+): Promise<void> {
+  await runGit(["tag", "--annotate", tag, "--message", message], {
+    cwd: rootDir,
+    run: options.run,
+  });
+}
+
+/**
+ * Pushes exactly the named tags to a remote, and nothing else. Sous never
+ * pushes a branch as a side effect of tagging.
+ *
+ * @param rootDir - The repository's root directory.
+ * @param remote - The remote to push to, normally `origin`.
+ * @param tags - The tags to push.
+ * @param options - The command runner to use.
+ */
+export async function pushTags(
+  rootDir: string,
+  remote: string,
+  tags: ReadonlyArray<string>,
+  options: RunOptions = {}
+): Promise<void> {
+  if (tags.length === 0) return;
+  await runGit(["push", remote, ...tags.map((tag) => `refs/tags/${tag}`)], {
+    cwd: rootDir,
+    run: options.run,
+  });
+}
+
+/** Rewrites a path with forward slashes, which is what git speaks everywhere. */
+function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}

package/src/lib/repos/release/validate.ts

@@ -0,0 +1,463 @@
+/**
+ * Publish-side validation for a recipe repository.
+ *
+ * `sous repo release` and `sous repo submit` both refuse to do anything until
+ * the repository they are standing in describes itself consistently: every
+ * folder the repo manifest lists exists and holds a recipe manifest, every
+ * recipe belongs to a declared namespace, no two recipes share a key, and no
+ * two variable definitions quietly claim the same environment variable.
+ *
+ * Nothing here runs git or touches the network; it reads files and reports.
+ * Problems are collected rather than thrown, so one run tells an author
+ * everything that is wrong instead of only the first thing.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "../../errors.js";
+import { MANIFEST_EXTENSIONS, REPO_MANIFEST_BASENAME } from "../formats/common.js";
+import {
+  parseRecipeManifest,
+  recipeManifestKey,
+  type RecipeManifest,
+} from "../formats/recipe-manifest.js";
+import { parseRepoManifest, type RepoManifest } from "../formats/repo-manifest.js";
+import {
+  findRecipeManifest,
+  findRepoManifest,
+  loadManifestFile,
+  requireRepoManifest,
+} from "../load-manifest.js";
+import { bareName } from "../../vars/names.js";
+
+/** How serious a validation finding is. An error stops a release; a warning does not. */
+export type ProblemLevel = "error" | "warning";
+
+/** One validation finding, with enough location to act on it. */
+export type ValidationProblem = {
+  /** Whether this stops a release or only deserves saying out loud. */
+  level: ProblemLevel;
+  /** Where it was found: a repo-relative file path, with a field path when there is one. */
+  where: string;
+  /** What is wrong, in plain language, and what to do about it. */
+  message: string;
+};
+
+/** One recipe folder that was found, read and validated. */
+export type ValidatedRecipe = {
+  /** The recipe folder's path relative to the repository root, as the repo manifest lists it. */
+  path: string;
+  /** Absolute path to the recipe folder. */
+  dir: string;
+  /** Absolute path to the recipe manifest inside that folder. */
+  manifestPath: string;
+  /** The validated recipe manifest. */
+  manifest: RecipeManifest;
+  /** The recipe's key, `namespace/name`. */
+  key: string;
+  /** The manifest exactly as it was parsed, before the schema dropped its `x-` keys. */
+  raw: unknown;
+};
+
+/** Everything one pass over a repository found. */
+export type RepoValidation = {
+  /** Absolute path to the repository root. */
+  rootDir: string;
+  /** Absolute path to the repo manifest at that root. */
+  manifestPath: string;
+  /** The validated repo manifest. */
+  manifest: RepoManifest;
+  /** Every recipe that could be read, in the order the repo manifest lists them. */
+  recipes: ValidatedRecipe[];
+  /** Everything found wrong, errors and warnings together. */
+  problems: ValidationProblem[];
+};
+
+/**
+ * Environment variable names a recipe should not claim without saying it meant
+ * to: the ones an operating system, a shell or a well-known tool already owns.
+ * Claiming one is legal and occasionally correct (binding an existing
+ * `GITHUB_TOKEN` is the motivating case), so this is a warning, silenced by
+ * setting `x-intentional: true` on the definition.
+ */
+export const WELL_KNOWN_ENV_NAMES: readonly string[] = [
+  "PATH",
+  "HOME",
+  "USER",
+  "SHELL",
+  "GITHUB_TOKEN",
+  "GITLAB_TOKEN",
+  "NPM_TOKEN",
+];
+
+/**
+ * Prefixes treated the same way as the names above. `SOUS_VAR_` is deliberately
+ * exempt: every name sous derives for an answer starts with it, so warning on
+ * it would fire on every well-behaved definition in every repository.
+ */
+export const WELL_KNOWN_ENV_PREFIXES: readonly string[] = ["AWS_", "SOUS_"];
+
+/** The extension key that silences the well-known environment name warning. */
+export const INTENTIONAL_EXTENSION_KEY = "x-intentional";
+
+/**
+ * Walks up from a directory to the repository root: the first directory at or
+ * above it holding a repo manifest.
+ *
+ * @param startDir - Where to start looking, normally the working directory.
+ * @returns The absolute path of the repository root.
+ */
+export function findRepoRoot(startDir: string): string {
+  let current = path.resolve(startDir);
+
+  for (;;) {
+    if (findRepoManifest(current) !== undefined) return current;
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  throw new ConfigError(
+    `${path.resolve(startDir)} is not inside a sous recipe repository.\n` +
+      `  A recipe repository has a '${REPO_MANIFEST_BASENAME}${MANIFEST_EXTENSIONS[0]}' file at ` +
+      `its root, and sous looked in that directory and in every directory above it.\n` +
+      `  Run the command from inside a repository, or create one with 'sous repo init'.`
+  );
+}
+
+/**
+ * Reads and checks a whole recipe repository.
+ *
+ * The repo manifest itself must parse; there is nothing to report against when
+ * it does not, so that failure is thrown as a ConfigError. Everything below it
+ * is collected into `problems`, so one run surfaces every fault at once.
+ *
+ * @param rootDir - Absolute path to the repository root.
+ */
+export function validateRepo(rootDir: string): RepoValidation {
+  const manifestPath = requireRepoManifest(rootDir);
+  const manifest = parseRepoManifest(loadManifestFile(manifestPath), manifestPath);
+
+  const problems: ValidationProblem[] = [];
+  const recipes: ValidatedRecipe[] = [];
+  const seenKeys = new Map<string, string>();
+  const manifestName = path.basename(manifestPath);
+
+  for (const recipePath of manifest.recipes) {
+    const dir = path.join(rootDir, recipePath);
+    const found = readRecipe(rootDir, recipePath, dir, manifestName, problems);
+    if (found === undefined) continue;
+
+    if (!Object.hasOwn(manifest.namespaces, found.manifest.namespace)) {
+      problems.push({
+        level: "error",
+        where: `${relative(rootDir, found.manifestPath)} namespace`,
+        message:
+          `the recipe is in the namespace '${found.manifest.namespace}', which ` +
+          `${manifestName} does not declare under 'namespaces'. Declare the namespace, or ` +
+          `move the recipe into one that exists.`,
+      });
+    }
+
+    const firstPath = seenKeys.get(found.key);
+    if (firstPath !== undefined) {
+      problems.push({
+        level: "error",
+        where: relative(rootDir, found.manifestPath),
+        message:
+          `the recipe '${found.key}' is also published by ${firstPath}. A namespace and a ` +
+          `name together name exactly one recipe, so rename one of the two.`,
+      });
+    } else {
+      seenKeys.set(found.key, relative(rootDir, found.manifestPath));
+    }
+
+    problems.push(...checkSymlinks(recipePath, dir));
+
+    recipes.push(found);
+  }
+
+  problems.push(...checkVariableEnvNames(rootDir, recipes));
+
+  return { rootDir, manifestPath, manifest, recipes, problems };
+}
+
+/** True when any problem in the list is an error. */
+export function hasErrors(problems: ReadonlyArray<ValidationProblem>): boolean {
+  return problems.some((problem) => problem.level === "error");
+}
+
+/** The errors in a problem list, in the order they were found. */
+export function errorsIn(problems: ReadonlyArray<ValidationProblem>): ValidationProblem[] {
+  return problems.filter((problem) => problem.level === "error");
+}
+
+/** The warnings in a problem list, in the order they were found. */
+export function warningsIn(
+  problems: ReadonlyArray<ValidationProblem>
+): ValidationProblem[] {
+  return problems.filter((problem) => problem.level === "warning");
+}
+
+/**
+ * The reason an environment variable name deserves a warning, or undefined when
+ * it is an ordinary name. Exported so a caller can explain the rule without
+ * repeating the list.
+ *
+ * @param envName - The environment variable name a definition claims.
+ */
+export function wellKnownEnvReason(envName: string): string | undefined {
+  if (WELL_KNOWN_ENV_NAMES.includes(envName)) {
+    return `'${envName}' is a well-known name that the system or another tool already uses`;
+  }
+  if (envName.startsWith("SOUS_VAR_")) return undefined;
+  for (const prefix of WELL_KNOWN_ENV_PREFIXES) {
+    if (envName.startsWith(prefix)) {
+      return (
+        `'${envName}' starts with '${prefix}', a prefix reserved by the system or by ` +
+        `another tool`
+      );
+    }
+  }
+  return undefined;
+}
+
+// --- Internals ----------------------------------------------------------------------------------
+
+/**
+ * The message a thrown value should be reported with. A ConfigError already
+ * carries plain-language wording, and every other Error at least carries a
+ * message; anything else is rendered as it stands.
+ *
+ * @param error - The value that was thrown.
+ */
+export function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Renders an absolute path as a repository-relative one, with forward slashes. */
+function relative(rootDir: string, target: string): string {
+  return path.relative(rootDir, target).split(path.sep).join("/");
+}
+
+/**
+ * Reads one recipe folder. Returns undefined, having recorded a problem, when
+ * the folder is missing or its manifest cannot be read.
+ */
+function readRecipe(
+  rootDir: string,
+  recipePath: string,
+  dir: string,
+  manifestName: string,
+  problems: ValidationProblem[]
+): ValidatedRecipe | undefined {
+  if (!isDirectory(dir)) {
+    problems.push({
+      level: "error",
+      where: recipePath,
+      message:
+        `${manifestName} lists this recipe folder, but there is no directory there. Create ` +
+        `it, or remove the path from the 'recipes' list.`,
+    });
+    return undefined;
+  }
+
+  let manifestPath: string | undefined;
+  try {
+    manifestPath = findRecipeManifest(dir);
+  } catch (error) {
+    problems.push({
+      level: "error",
+      where: recipePath,
+      message: describeError(error),
+    });
+    return undefined;
+  }
+
+  if (manifestPath === undefined) {
+    problems.push({
+      level: "error",
+      where: recipePath,
+      message:
+        "there is no recipe manifest in this folder. Every folder listed under 'recipes' " +
+        "holds one 'sous.recipe.yaml'.",
+    });
+    return undefined;
+  }
+
+  let raw: unknown;
+  let manifest: RecipeManifest;
+  try {
+    raw = loadManifestFile(manifestPath);
+    manifest = parseRecipeManifest(raw, manifestPath);
+  } catch (error) {
+    problems.push({
+      level: "error",
+      where: relative(rootDir, manifestPath),
+      message: describeError(error),
+    });
+    return undefined;
+  }
+
+  return {
+    path: recipePath,
+    dir,
+    manifestPath,
+    manifest,
+    key: recipeManifestKey(manifest),
+    raw,
+  };
+}
+
+/** One definition's claim on an environment variable name. */
+type EnvClaim = {
+  envName: string;
+  variableName: string;
+  where: string;
+};
+
+/**
+ * Checks every variable definition in the repository against every other one.
+ *
+ * Two definitions of the SAME variable name may share an environment variable:
+ * that is the shared rung of the resolution ladder doing its job, and it is how
+ * one answer serves every recipe that asks the same question. Two definitions
+ * of DIFFERENT variable names sharing one name is a genuine collision, because
+ * a single answer would silently satisfy both.
+ */
+function checkVariableEnvNames(
+  rootDir: string,
+  recipes: ReadonlyArray<ValidatedRecipe>
+): ValidationProblem[] {
+  const problems: ValidationProblem[] = [];
+  const byEnvName = new Map<string, EnvClaim>();
+  const byVariableName = new Map<string, EnvClaim>();
+
+  for (const recipe of recipes) {
+    const definitions = recipe.manifest.variables ?? [];
+    definitions.forEach((definition, index) => {
+      const envName = bareName(definition);
+      const where =
+        `${relative(rootDir, recipe.manifestPath)} variables[${index}] ` +
+        `('${definition.name}')`;
+      const claim: EnvClaim = { envName, variableName: definition.name, where };
+
+      const byEnv = byEnvName.get(envName);
+      if (byEnv !== undefined && byEnv.variableName !== definition.name) {
+        problems.push({
+          level: "error",
+          where,
+          message:
+            `claims the environment variable '${envName}', which ${byEnv.where} already ` +
+            `claims for the different variable '${byEnv.variableName}'. Two definitions ` +
+            `cannot share one environment variable; set 'env' explicitly on one of them.`,
+        });
+      } else if (byEnv === undefined) {
+        byEnvName.set(envName, claim);
+      }
+
+      const byName = byVariableName.get(definition.name);
+      if (byName !== undefined && byName.envName !== envName) {
+        problems.push({
+          level: "warning",
+          where,
+          message:
+            `binds to '${envName}', while ${byName.where} binds the same variable name to ` +
+            `'${byName.envName}'. One answer will not serve both; give them one 'env' value ` +
+            `if they are meant to be the same question.`,
+        });
+      } else if (byName === undefined) {
+        byVariableName.set(definition.name, claim);
+      }
+
+      const reason = wellKnownEnvReason(envName);
+      if (reason !== undefined && !isIntentional(recipe.raw, index)) {
+        problems.push({
+          level: "warning",
+          where,
+          message:
+            `${reason}. An answer written there is visible to every process this project ` +
+            `starts. If that is what you meant, set '${INTENTIONAL_EXTENSION_KEY}: true' on ` +
+            `the definition to say so.`,
+        });
+      }
+    });
+  }
+
+  return problems;
+}
+
+/**
+ * True when the raw manifest marks the variable definition at `index` as an
+ * intentional claim on a well-known name.
+ *
+ * The flag is read from the RAW manifest rather than from the validated one
+ * because the recipe manifest schema accepts and then drops every key in the
+ * reserved `x-` extension namespace, so it never reaches the parsed object.
+ */
+function isIntentional(raw: unknown, index: number): boolean {
+  if (typeof raw !== "object" || raw === null) return false;
+  const variables = (raw as Record<string, unknown>).variables;
+  if (!Array.isArray(variables)) return false;
+  const entry = variables[index];
+  if (typeof entry !== "object" || entry === null) return false;
+  return (entry as Record<string, unknown>)[INTENTIONAL_EXTENSION_KEY] === true;
+}
+
+/** True when the path exists and is a directory. */
+function isDirectory(candidate: string): boolean {
+  try {
+    return fs.statSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Reports every symbolic link inside a recipe folder as an error.
+ *
+ * A published version's content hash is computed over the recipe folder, and a
+ * link points at bytes the repository does not own. Sous skips links when it
+ * hashes and when it copies into the store, so a linked file is simply not part
+ * of what a consumer receives; publishing one would ship a recipe that is
+ * missing a file it expects. The fix is always the same, so it is refused here
+ * rather than surfacing later as a puzzling absence.
+ *
+ * @param recipePath - The recipe folder's path relative to the repository root.
+ * @param dir - The recipe folder's absolute path.
+ */
+function checkSymlinks(recipePath: string, dir: string): ValidationProblem[] {
+  const problems: ValidationProblem[] = [];
+
+  const walk = (current: string, prefix: string): void => {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (entry.name === ".git") continue;
+      const relativePath = prefix.length > 0 ? `${prefix}/${entry.name}` : entry.name;
+
+      if (entry.isSymbolicLink()) {
+        problems.push({
+          level: "error",
+          where: `${recipePath}/${relativePath}`,
+          message:
+            "this is a symbolic link, and a recipe may not publish one. A published " +
+            "version's content hash covers the recipe folder itself, so sous neither " +
+            "hashes nor installs what a link points at; the file would simply be missing " +
+            "for everyone who installs the recipe. Replace the link with the file itself.",
+        });
+        continue;
+      }
+
+      if (entry.isDirectory()) walk(path.join(current, entry.name), relativePath);
+    }
+  };
+
+  walk(dir, "");
+  return problems;
+}