@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/repos/identity.ts

@@ -1,89 +0,0 @@
-/**
- * Canonical repository identity: what the machine-wide store, the index cache
- * and the lockfile key a repository by.
- *
- * A repository's short name (`sous-recipes`) is a CONSUMER's label. Two
- * projects may call the same repository different things, and two different
- * repositories may be called the same thing in two projects, so a short name
- * can never key anything shared between projects. The identity can: it is
- * derived from the location the repository actually lives at, so every project
- * on a machine agrees about it.
- *
- *     github.com/sous-io/sous-recipes
- *     gitlab.example.com/group/subgroup/project
- *     localhost/home/me/Projects/my-recipes
- *
- * The shape is `<host>/<owner path>/<name>`, lowercased, with any `.git`
- * suffix already gone (the providers strip it while canonicalizing). Short
- * names stay exactly where they were: in a project's config, in its lockfile
- * keys, and in everything sous prints, because that is what a person typed.
- */
-
-import type { CanonicalRepo } from "./providers/provider.js";
-import { REPO_NAME_PATTERN } from "./formats/patterns.js";
-
-/**
- * The canonical identity of a repository, as every machine-wide key spells it.
- *
- * repoIdentity({ host: "GitHub.com", owner: "sous-io", name: "sous-recipes" });
- * // -> "github.com/sous-io/sous-recipes"
- *
- * @param canonical - The repository, taken apart by its provider.
- */
-export function repoIdentity(canonical: CanonicalRepo): string {
-  const name = canonical.name.replace(/\.git$/i, "");
-  return identitySegments(`${canonical.host}/${canonical.owner}/${name}`).join("/");
-}
-
-/**
- * The path segments an identity is made of, with empty segments dropped and
- * every segment lowercased. A local repository's owner is an absolute path, so
- * its leading separator would otherwise produce an empty first segment.
- *
- * identitySegments("localhost//home/me/recipes");
- * // -> ["localhost", "home", "me", "recipes"]
- *
- * @param identity - The identity, or the pieces of one joined with slashes.
- */
-export function identitySegments(identity: string): string[] {
-  return identity
-    .split("/")
-    .map((segment) => segment.trim().toLowerCase())
-    .filter((segment) => segment.length > 0);
-}
-
-/**
- * A short name derived from an identity, used when sous has to name a
- * repository a project has never added (a dependency's locator URL, for
- * instance) before the person has chosen a name for it.
- *
- * shortNameFromIdentity("github.com/sous-io/sous-recipes"); // -> "sous-recipes"
- *
- * @param identity - The repository's canonical identity.
- */
-export function shortNameFromIdentity(identity: string): string {
-  const segments = identitySegments(identity);
-  const last = segments[segments.length - 1] ?? "";
-  const cleaned = last
-    .replace(/[^a-z0-9-]+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-+|-+$/g, "");
-
-  // A short name is lowercase kebab-case starting with a letter. A repository
-  // whose name starts with a digit, or is made entirely of characters a name
-  // may not carry, still needs something to be called.
-  if (REPO_NAME_PATTERN.test(cleaned)) return cleaned;
-  return cleaned.length === 0 ? "repository" : `repo-${cleaned}`;
-}
-
-/**
- * True when two identities name the same repository. Identities are already
- * normalized, so this is a plain comparison; it exists so callers read as what
- * they mean rather than as a string equality.
- *
- * @param left - One identity.
- * @param right - The other.
- */
-export function sameRepoIdentity(left: string, right: string): boolean {
-  return left === right;
-}

package/src/lib/repos/index.ts

@@ -1,57 +0,0 @@
-/**
- * The Repositories layer: every on-disk format, the loaders that read them, and
- * the ref parser that names what is inside them.
- *
- * Import from here rather than from the individual modules, so later phases
- * (the store, the providers, the resolver, the CLI surface) have one place to
- * look for what this layer offers.
- */
-
-// The regular expressions in formats/patterns.js reach here through
-// formats/common.js, which re-exports them; listing patterns.js again would
-// make every one of those names an ambiguous star export.
-export * from "./formats/common.js";
-export * from "./formats/repo-manifest.js";
-export * from "./formats/recipe-manifest.js";
-export * from "./formats/index-file.js";
-export * from "./formats/lockfile.js";
-export * from "./formats/store-entry.js";
-export * from "./formats/links-map.js";
-export * from "./load-manifest.js";
-export * from "./identity.js";
-
-// Phase 2a: the machine-wide recipe store, under the user-level sous directory.
-export * from "./store/contract.js";
-export * from "./store/hash.js";
-export * from "./store/recipe-store.js";
-export * from "./store/settings.js";
-
-// Phase 6a: the CLI surface for editable checkouts (`sous repo init`, `link`,
-// `unlink`). The links map and its ignore hygiene, the thin git layer both of
-// them use, and the scaffold that `repo init` writes.
-export * from "./links.js";
-export * from "./git-clone.js";
-export * from "./scaffold/index.js";
-
-// Phase 2b: the store contract, the providers, the resolver, the trust layer
-// and the lockfile service.
-export * from "./providers/index.js";
-export * from "./resolver.js";
-export * from "./managed-layer.js";
-export * from "./trust.js";
-export * from "./lock-service.js";
-export * from "./freshness.js";
-
-// Phase 3: the consumer surface. Where a locked recipe's files are, the
-// namespace resolver and compile targets built from that, and the service the
-// `repo`, `subscribe` and `unsubscribe` commands drive.
-export * from "./locked-recipes.js";
-export * from "./locked-namespace-resolver.js";
-export * from "./subscription-service.js";
-
-// Phase 7: the core namespace. The recipe that ships inside the package, the
-// seed that puts it in the store on first run, and the built-in repository and
-// subscription every project gets unless it opts out.
-export * from "./core-recipe.js";
-export * from "./seed.js";
-export * from "./defaults.js";

package/src/lib/repos/links.ts

@@ -1,356 +0,0 @@
-/**
- * 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 unless
- * `--remove` asks it to delete one sous cloned.
- *
- * 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, the local answers file, and the directory linked checkouts are
- * cloned into.
- */
-export const IGNORE_BLOCK_ENTRIES = [
-  LINKS_FILENAME,
-  "sous.state.json",
-  "sous.pid",
-  ".env.local",
-  `${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");
-}