@sous-io/sous 0.1.1 → 0.2.1

package/src/lib/repos/links.ts

@@ -0,0 +1,353 @@
+/**
+ * Reading and writing the links map, and the ignore hygiene that goes with it.
+ *
+ * A link redirects one repository's resolution away from the store and at a
+ * real working copy on disk, which is how a maintainer edits recipes: edits
+ * happen in a checkout, never in the store. `sous repo link` writes an entry
+ * here; `sous repo unlink` removes it and leaves the checkout alone.
+ *
+ * Two maps exist. The project's `.sous/sous.links.json` covers one project; the
+ * machine-wide `$SOUS_HOME/sous.links.json` covers every project on the machine,
+ * which is how two projects share one checkout. Both are read, and the project's
+ * entries win, because the narrower decision is the more deliberate one.
+ *
+ * Neither map is committed. A link bypasses versions, the lockfile and freshness
+ * checks, and those bypasses belong to one person's machine rather than to the
+ * team; the ignore hygiene in this module is what keeps them out of the
+ * repository, and `describeLinkedRepos` is what keeps them visible in build
+ * output instead of silently changing what a build produces.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { ConfigError } from "../errors.js";
+import { resolveSousHome, resolveStoreRoot } from "../sous-home.js";
+import { LINKS_FILENAME } from "./formats/common.js";
+import {
+  ensureProjectReposDirectory,
+  ensureSousHomeDirectory,
+} from "../../utils/sous-directory.js";
+import {
+  createEmptyLinksMap,
+  mergeLinksMaps,
+  parseLinksMap,
+  stringifyLinksMap,
+  type LinksMap,
+  type RepoLink,
+} from "./formats/links-map.js";
+import { loadJsonFile } from "./load-manifest.js";
+
+/** Directory name, inside `.sous/` or `$SOUS_HOME`, holding linked checkouts. */
+export const REPOS_DIRNAME = "repos";
+
+/** Opening marker of the block sous maintains in `.sous/.gitignore`. */
+export const IGNORE_BLOCK_START = "# >>> sous managed (do not edit between these markers)";
+
+/** Closing marker of the block sous maintains in `.sous/.gitignore`. */
+export const IGNORE_BLOCK_END = "# <<< sous managed";
+
+/**
+ * The entries sous keeps inside its managed block in `.sous/.gitignore`. All of
+ * them are machine-local: the links map, the build state file, the watcher's
+ * PID file, and the directory linked checkouts are cloned into.
+ */
+export const IGNORE_BLOCK_ENTRIES = [
+  LINKS_FILENAME,
+  "sous.state.json",
+  "sous.pid",
+  `${REPOS_DIRNAME}/`,
+] as const;
+
+// --- Locations ----------------------------------------------------------------------------------
+
+/**
+ * The user-level sous directory, re-exported under the name this module has
+ * always used. The one definition lives in `src/lib/sous-home.ts`, so the store,
+ * the links maps and the auto-injected `${sousHome}` variable can never disagree
+ * about where it is.
+ *
+ * @param env - The environment to read, so tests need not mutate the real one.
+ */
+export function resolveSousHomeDir(env: NodeJS.ProcessEnv = process.env): string {
+  return resolveSousHome(env);
+}
+
+/**
+ * Path to the project's links map.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ */
+export function projectLinksPath(sousDir: string): string {
+  return path.join(sousDir, LINKS_FILENAME);
+}
+
+/**
+ * Path to the machine-wide links map.
+ *
+ * @param env - The environment to read.
+ */
+export function globalLinksPath(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(resolveSousHomeDir(env), LINKS_FILENAME);
+}
+
+/**
+ * The directory a project's own linked checkouts are cloned into.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ */
+export function projectReposDir(sousDir: string): string {
+  return path.join(sousDir, REPOS_DIRNAME);
+}
+
+/**
+ * The directory machine-wide linked checkouts are cloned into, shared by every
+ * project on the machine.
+ *
+ * @param env - The environment to read.
+ */
+export function globalReposDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(resolveSousHomeDir(env), REPOS_DIRNAME);
+}
+
+/**
+ * The directories nothing sous deletes may ever reach into: the project's linked
+ * checkouts, the machine-wide linked checkouts, and the machine-wide recipe
+ * store.
+ *
+ * A linked checkout is somebody's working copy with unpushed edits in it, and
+ * the store is shared by every project on the machine, so a stale state entry
+ * pointing into either one must never turn `sous prune` or `sous clear` into a
+ * data loss. Prune and clear only ever touch paths recorded in the state file,
+ * which nothing here writes; this is the belt that survives a future bug.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ * @param env - The environment to read.
+ */
+export function protectedRepoPaths(
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): string[] {
+  return [projectReposDir(sousDir), globalReposDir(env), resolveStoreRoot(env)];
+}
+
+// --- Reading ------------------------------------------------------------------------------------
+
+/**
+ * Reads a links map from a path, returning an empty map when the file does not
+ * exist. A file that exists but cannot be read or does not validate raises a
+ * ConfigError naming it, rather than being quietly treated as empty: a link
+ * changes what a build produces, so losing one must never pass unnoticed.
+ *
+ * @param filePath - Absolute path to the links file.
+ */
+export function readLinksFile(filePath: string): LinksMap {
+  if (!fs.existsSync(filePath)) return createEmptyLinksMap();
+  return parseLinksMap(loadJsonFile(filePath, "links map"), filePath);
+}
+
+/**
+ * Reads the project's links map.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ */
+export function readProjectLinks(sousDir: string): LinksMap {
+  return readLinksFile(projectLinksPath(sousDir));
+}
+
+/**
+ * Reads the machine-wide links map.
+ *
+ * @param env - The environment to read.
+ */
+export function readGlobalLinks(env: NodeJS.ProcessEnv = process.env): LinksMap {
+  return readLinksFile(globalLinksPath(env));
+}
+
+/**
+ * Reads both maps and merges them into the one map the rest of sous consults,
+ * with the project's entries winning over the machine-wide ones.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ * @param env - The environment to read.
+ */
+export function readEffectiveLinks(
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): Record<string, RepoLink> {
+  return mergeLinksMaps(readGlobalLinks(env), readProjectLinks(sousDir));
+}
+
+/**
+ * The working copy sous should read for a repository, or undefined when the
+ * repository is not linked and resolution should fall through to the store.
+ *
+ * @param repoName - The repository's configured short name.
+ * @param sousDir - The project's discovered `.sous/` directory.
+ * @param env - The environment to read.
+ */
+export function linkedPathFor(
+  repoName: string,
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): string | undefined {
+  return readEffectiveLinks(sousDir, env)[repoName]?.path;
+}
+
+// --- Writing ------------------------------------------------------------------------------------
+
+/**
+ * Writes a links map, creating its directory if needed. Returns the path it was
+ * written to.
+ *
+ * @param filePath - Absolute path to the links file.
+ * @param map - The map to write.
+ */
+export function writeLinksFile(filePath: string, map: LinksMap): string {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, stringifyLinksMap(map), "utf8");
+  return filePath;
+}
+
+/**
+ * Writes the project's links map.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ * @param map - The map to write.
+ */
+export function writeProjectLinks(sousDir: string, map: LinksMap): string {
+  return writeLinksFile(projectLinksPath(sousDir), map);
+}
+
+/**
+ * Writes the machine-wide links map.
+ *
+ * @param map - The map to write.
+ * @param env - The environment to read.
+ */
+export function writeGlobalLinks(
+  map: LinksMap,
+  env: NodeJS.ProcessEnv = process.env
+): string {
+  // The machine-wide map is the first thing many users ever put in `$SOUS_HOME`,
+  // so this is where that directory usually gets its own explanation.
+  ensureSousHomeDirectory(resolveSousHomeDir(env));
+  return writeLinksFile(globalLinksPath(env), map);
+}
+
+// --- Build output notice ------------------------------------------------------------------------
+
+/**
+ * The lines a build prints when anything is linked, so a checkout standing in
+ * for a published repository is never a silent change. Returns an empty array
+ * when nothing is linked, which is the signal to print nothing at all.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ * @param env - The environment to read.
+ */
+export function describeLinkedRepos(
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): string[] {
+  const links = readEffectiveLinks(sousDir, env);
+  const names = Object.keys(links).sort();
+  if (names.length === 0) return [];
+
+  const lines = [
+    names.length === 1
+      ? "One repository is LINKED to a working copy on this machine."
+      : `${names.length} repositories are LINKED to working copies on this machine.`,
+    "Their recipes are read from those checkouts, so versions, the lockfile and",
+    "freshness checks do not apply to them.",
+    "",
+  ];
+
+  for (const name of names) {
+    lines.push(`${name} -> ${links[name]!.path}`);
+  }
+
+  lines.push("");
+  lines.push("Run 'sous repo unlink <name>' to go back to the published versions.");
+  return lines;
+}
+
+// --- Ignore hygiene -----------------------------------------------------------------------------
+
+/**
+ * Makes sure git ignores everything sous keeps inside `.sous/` that belongs to
+ * one machine rather than to the team. Two files are maintained, and both are
+ * safe to write again on every link:
+ *
+ * - `.sous/repos/.gitignore`, holding a single `*`, so a linked checkout cloned
+ *   underneath it is invisible to the project's own repository (the `*` covers
+ *   the ignore file itself, so the directory contributes nothing at all).
+ * - a delimited managed block inside `.sous/.gitignore`. Only the lines between
+ *   the markers are ever rewritten; anything the user put above or below them is
+ *   left exactly as it was.
+ *
+ * @param sousDir - The project's discovered `.sous/` directory.
+ */
+export function ensureReposIgnoreFiles(sousDir: string): void {
+  const reposDir = ensureProjectReposDirectory(projectReposDir(sousDir));
+  writeIfChanged(path.join(reposDir, ".gitignore"), "*\n");
+
+  const gitignorePath = path.join(sousDir, ".gitignore");
+  const existing = fs.existsSync(gitignorePath)
+    ? fs.readFileSync(gitignorePath, "utf8")
+    : undefined;
+  writeIfChanged(gitignorePath, applyManagedIgnoreBlock(existing, gitignorePath));
+}
+
+/**
+ * Returns the contents of `.sous/.gitignore` with sous's managed block present
+ * and up to date, leaving every line outside the markers untouched. Exported so
+ * the behavior can be tested without touching a filesystem.
+ *
+ * @param existing - The file's current contents, or undefined when there is no file.
+ * @param label - The file's path, named if the block turns out to be damaged.
+ */
+export function applyManagedIgnoreBlock(
+  existing: string | undefined,
+  label = ".sous/.gitignore"
+): string {
+  const block = [IGNORE_BLOCK_START, ...IGNORE_BLOCK_ENTRIES, IGNORE_BLOCK_END];
+
+  if (existing === undefined || existing.trim() === "") {
+    return `${block.join("\n")}\n`;
+  }
+
+  const lines = existing.split("\n");
+  const start = lines.findIndex((line) => line.trim() === IGNORE_BLOCK_START);
+
+  if (start === -1) {
+    const prefix = existing.endsWith("\n") ? existing : `${existing}\n`;
+    const separator = prefix.endsWith("\n\n") ? "" : "\n";
+    return `${prefix}${separator}${block.join("\n")}\n`;
+  }
+
+  const end = lines.findIndex(
+    (line, index) => index > start && line.trim() === IGNORE_BLOCK_END
+  );
+
+  if (end === -1) {
+    throw new ConfigError(
+      `The sous managed block in ${label} has no closing marker.\n` +
+        `  It opens with '${IGNORE_BLOCK_START}' but the line '${IGNORE_BLOCK_END}' ` +
+        `is missing, so sous cannot tell where the block ends.\n` +
+        `  Add the closing marker back, or delete the opening one, and run the ` +
+        `command again.`
+    );
+  }
+
+  const rebuilt = [...lines.slice(0, start), ...block, ...lines.slice(end + 1)];
+  const joined = rebuilt.join("\n");
+  return joined.endsWith("\n") ? joined : `${joined}\n`;
+}
+
+// --- Helpers ------------------------------------------------------------------------------------
+
+/** Writes a file only when its contents would change, so links stay idempotent. */
+function writeIfChanged(filePath: string, contents: string): void {
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, "utf8") === contents) return;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, contents, "utf8");
+}

package/src/lib/repos/load-manifest.ts

@@ -0,0 +1,236 @@
+/**
+ * Reading Repositories files off disk.
+ *
+ * Manifests are HAND-WRITTEN, and deliberately never JavaScript: trust in the
+ * Repositories system rests on being able to read a repo's whole surface
+ * without executing any of its code. So a manifest is YAML (`.yaml`, `.yml`) or
+ * JSON (`.json`, `.jsonc`), and the JSON dialect is permissive, allowing line
+ * comments, block comments and trailing commas, so a manifest can explain
+ * itself.
+ *
+ * Machine-written files (the index, the lockfile, store entry markers, the
+ * links map) are strict JSON; nothing writes a comment into them, so nothing
+ * needs to tolerate one.
+ *
+ * Every function here returns raw, unvalidated data. Pass the result to the
+ * matching `parseX` helper in `formats/` to validate it.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { parse as parseJsonc, printParseErrorCode, type ParseError } from "jsonc-parser";
+import { ConfigError } from "../errors.js";
+import {
+  MANIFEST_EXTENSIONS,
+  RECIPE_MANIFEST_BASENAME,
+  REPO_MANIFEST_BASENAME,
+} from "./formats/common.js";
+
+/** Reads a file as UTF-8, raising a ConfigError naming it when that fails. */
+function readFileText(filePath: string, label: string): string {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch (error) {
+    const reason = (error as NodeJS.ErrnoException).code === "ENOENT" ? "does not exist" : "could not be read";
+    throw new ConfigError(
+      `The ${label} at ${filePath} ${reason}.\n` +
+        `  ${(error as Error).message}`
+    );
+  }
+}
+
+/** Turns a jsonc-parser error offset into a `line N, column N` string. */
+function describeOffset(text: string, offset: number): string {
+  const before = text.slice(0, offset);
+  const line = before.split("\n").length;
+  const column = offset - before.lastIndexOf("\n");
+  return `line ${line}, column ${column}`;
+}
+
+/**
+ * Parses permissive JSON: standard JSON plus line comments, block comments and
+ * trailing commas. Used for hand-written `.json` and `.jsonc` files, and for
+ * `.jsonc` config layers.
+ *
+ * @param text - The file's contents.
+ * @param sourceLabel - The file path, named in error messages.
+ */
+export function parseJsoncText(text: string, sourceLabel: string): unknown {
+  const errors: ParseError[] = [];
+  const value = parseJsonc(text, errors, {
+    allowTrailingComma: true,
+    disallowComments: false,
+  });
+
+  if (errors.length > 0) {
+    const first = errors[0]!;
+    throw new ConfigError(
+      `Could not parse ${sourceLabel} as JSON:\n` +
+        `  ${printParseErrorCode(first.error)} at ${describeOffset(text, first.offset)}.\n` +
+        `  Comments and trailing commas are allowed; anything else must be valid JSON.`
+    );
+  }
+
+  return value;
+}
+
+/**
+ * Parses YAML, raising a ConfigError that carries the parser's own message.
+ *
+ * @param text - The file's contents.
+ * @param sourceLabel - The file path, named in error messages.
+ */
+export function parseYamlText(text: string, sourceLabel: string): unknown {
+  try {
+    return YAML.parse(text);
+  } catch (error) {
+    throw new ConfigError(
+      `Could not parse ${sourceLabel} as YAML:\n  ${(error as Error).message}`
+    );
+  }
+}
+
+/**
+ * Loads a hand-written manifest, picking the parser by extension: `.yaml` and
+ * `.yml` are YAML, `.json` and `.jsonc` are permissive JSON. Returns raw,
+ * unvalidated data.
+ *
+ * @param filePath - Absolute path to the manifest file.
+ */
+export function loadManifestFile(filePath: string): unknown {
+  const extension = path.extname(filePath).toLowerCase();
+  const text = readFileText(filePath, "manifest");
+
+  if (extension === ".yaml" || extension === ".yml") {
+    return parseYamlText(text, filePath);
+  }
+  if (extension === ".json" || extension === ".jsonc") {
+    return parseJsoncText(text, filePath);
+  }
+
+  throw new ConfigError(
+    `Cannot read the manifest at ${filePath}: '${extension}' is not a manifest format.\n` +
+      `  A manifest is written as ${MANIFEST_EXTENSIONS.join(", ")}. Manifests are never ` +
+      `JavaScript, because sous must be able to read a repository without running its code.`
+  );
+}
+
+/**
+ * Loads a machine-written JSON file (the index, a lockfile, a store entry
+ * marker, a links map) with strict JSON parsing. Returns raw, unvalidated data.
+ *
+ * @param filePath - Absolute path to the file.
+ * @param label - Plain-language name of the file, used in error messages.
+ */
+export function loadJsonFile(filePath: string, label: string): unknown {
+  const text = readFileText(filePath, label);
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new ConfigError(
+      `Could not parse the ${label} at ${filePath} as JSON:\n  ${(error as Error).message}\n` +
+        `  This file is written by sous; if it has been edited by hand, restoring it from ` +
+        `version control is usually the quickest fix.`
+    );
+  }
+}
+
+/** True when the path exists and is a regular file. */
+function isFile(candidate: string): boolean {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Finds the one manifest with the given base name in a directory, trying each
+ * supported extension. Returns undefined when there is none.
+ *
+ * Two manifests in one directory is a hard error rather than a first-match-win,
+ * mirroring how sous treats two primary configs in one `.sous/` directory: a
+ * silent winner would make the repo's behavior depend on an implementation
+ * detail.
+ *
+ * @param directory - The directory to look in.
+ * @param baseName - The manifest base name, without an extension.
+ * @param label - Plain-language name of the manifest, used in error messages.
+ */
+export function findManifest(
+  directory: string,
+  baseName: string,
+  label: string
+): string | undefined {
+  const found: string[] = [];
+  for (const extension of MANIFEST_EXTENSIONS) {
+    const candidate = path.join(directory, `${baseName}${extension}`);
+    if (isFile(candidate)) found.push(candidate);
+  }
+
+  if (found.length > 1) {
+    const names = found.map((entry) => path.basename(entry)).join(", ");
+    throw new ConfigError(
+      `Found more than one ${label} in ${directory}: ${names}.\n` +
+        `  A directory holds exactly one ${label}. Remove the copies you do not want, ` +
+        `so it is never ambiguous which one sous reads.`
+    );
+  }
+
+  return found[0];
+}
+
+/**
+ * Finds the repo manifest at the root of a repository.
+ *
+ * @param repoRoot - The repository's root directory.
+ */
+export function findRepoManifest(repoRoot: string): string | undefined {
+  return findManifest(repoRoot, REPO_MANIFEST_BASENAME, "repo manifest");
+}
+
+/**
+ * Finds the recipe manifest in a recipe folder.
+ *
+ * @param recipeDir - The recipe's directory.
+ */
+export function findRecipeManifest(recipeDir: string): string | undefined {
+  return findManifest(recipeDir, RECIPE_MANIFEST_BASENAME, "recipe manifest");
+}
+
+/**
+ * Finds the repo manifest and raises a ConfigError naming the directory when
+ * there is none, for callers that require one.
+ *
+ * @param repoRoot - The repository's root directory.
+ */
+export function requireRepoManifest(repoRoot: string): string {
+  const found = findRepoManifest(repoRoot);
+  if (found === undefined) {
+    throw new ConfigError(
+      `No repo manifest in ${repoRoot}.\n` +
+        `  A sous repository declares itself with a '${REPO_MANIFEST_BASENAME}${MANIFEST_EXTENSIONS[0]}' ` +
+        `file at its root.`
+    );
+  }
+  return found;
+}
+
+/**
+ * Finds the recipe manifest and raises a ConfigError naming the directory when
+ * there is none, for callers that require one.
+ *
+ * @param recipeDir - The recipe's directory.
+ */
+export function requireRecipeManifest(recipeDir: string): string {
+  const found = findRecipeManifest(recipeDir);
+  if (found === undefined) {
+    throw new ConfigError(
+      `No recipe manifest in ${recipeDir}.\n` +
+        `  Every directory listed under 'recipes' in a repo manifest holds a ` +
+        `'${RECIPE_MANIFEST_BASENAME}${MANIFEST_EXTENSIONS[0]}' file.`
+    );
+  }
+  return found;
+}