@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/repos/ref.ts

@@ -0,0 +1,513 @@
+/**
+ * The ref parser.
+ *
+ * A "ref" is how everything in the Repositories system names a namespace or a
+ * recipe: on the command line, in a project's subscriptions, and in a recipe
+ * manifest's `depends` and `subscribes` lists. The grammar is deliberately
+ * small and prefix-free:
+ *
+ *     ref := [ repo ":" ] namespace [ "/" recipe [ "@" range ] ]
+ *
+ *     workflow                              a whole namespace
+ *     workflow/task-files                   one recipe, any version
+ *     workflow/task-files@^1.2.0            one recipe, constrained
+ *     sous-recipes:workflow/task-files      the same recipe in a named repo
+ *
+ * The repo qualifier is only needed when the same ref resolves in more than one
+ * added repo; refs otherwise resolve across every added repo's cached index.
+ * A version range applies to a recipe, never to a namespace, because namespaces
+ * are not versioned.
+ */
+
+import semver from "semver";
+import { ConfigError } from "../errors.js";
+import {
+  NAMESPACE_NAME_PATTERN,
+  RECIPE_NAME_PATTERN,
+  REPO_NAME_PATTERN,
+} from "./formats/patterns.js";
+
+/** A parsed ref. `recipe` is absent for a namespace ref; `range` needs a recipe. */
+export type ParsedRef = {
+  /** The repo short name from a `repo:` qualifier, when one was given. */
+  repo?: string;
+  /** The namespace. Always present. */
+  namespace: string;
+  /** The recipe name, when the ref names a recipe rather than a whole namespace. */
+  recipe?: string;
+  /** The semantic version range, when one was given. Only legal with a recipe. */
+  range?: string;
+};
+
+/** The one-line reminder appended to every ref error. */
+const SYNTAX_HELP =
+  "A ref is written as 'namespace', 'namespace/recipe', 'namespace/recipe@<range>' or " +
+  "'repo:namespace/recipe@<range>'.";
+
+/** Builds a ConfigError that quotes the offending input and shows the grammar. */
+function refError(input: string, problem: string): ConfigError {
+  return new ConfigError(`Invalid ref '${input}': ${problem}\n  ${SYNTAX_HELP}`);
+}
+
+/**
+ * Parses a ref string into its parts, throwing a ConfigError that quotes the
+ * input and shows the grammar when it does not fit.
+ *
+ * @param input - The ref as written by a user or a manifest.
+ */
+export function parseRef(input: string): ParsedRef {
+  if (typeof input !== "string") {
+    throw refError(String(input), "a ref must be a string.");
+  }
+
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw refError(input, "a ref must not be empty.");
+  }
+
+  if (trimmed.startsWith("@")) {
+    throw refError(
+      input,
+      "refs take no '@' prefix. The '@' character introduces a version range only, " +
+        "as in 'workflow/task-files@^1.2.0'."
+    );
+  }
+  if (trimmed.startsWith("~")) {
+    throw refError(
+      input,
+      "refs take no '~' prefix. The '~' sigil belongs to template include lines " +
+        "('@~workflow/file.md'); a ref itself is written without it."
+    );
+  }
+
+  // Split the version range off first, so the rest is pure path and qualifier.
+  let body = trimmed;
+  let range: string | undefined;
+  const atIndex = body.indexOf("@");
+  if (atIndex !== -1) {
+    if (body.indexOf("@", atIndex + 1) !== -1) {
+      throw refError(input, "a ref may carry at most one '@' version range.");
+    }
+    range = body.slice(atIndex + 1).trim();
+    body = body.slice(0, atIndex);
+    if (range.length === 0) {
+      throw refError(input, "the '@' is not followed by a version range.");
+    }
+  }
+
+  // Then the repo qualifier.
+  let repo: string | undefined;
+  const colonIndex = body.indexOf(":");
+  if (colonIndex !== -1) {
+    if (body.indexOf(":", colonIndex + 1) !== -1) {
+      throw refError(input, "a ref may carry at most one 'repo:' qualifier.");
+    }
+    repo = body.slice(0, colonIndex);
+    body = body.slice(colonIndex + 1);
+    if (repo.length === 0) {
+      throw refError(input, "the repo qualifier before ':' is empty.");
+    }
+    if (!REPO_NAME_PATTERN.test(repo)) {
+      throw refError(
+        input,
+        `the repo qualifier '${repo}' must be lowercase kebab-case: a letter, then ` +
+          "letters, digits or hyphens."
+      );
+    }
+  }
+
+  // What is left is the namespace, optionally followed by a recipe.
+  const segments = body.split("/");
+  if (segments.length > 2) {
+    throw refError(
+      input,
+      "a ref has at most two path segments, a namespace and a recipe."
+    );
+  }
+
+  const [namespace, recipe] = segments;
+  if (namespace === undefined || namespace.length === 0) {
+    throw refError(input, "the namespace is empty.");
+  }
+  if (!NAMESPACE_NAME_PATTERN.test(namespace)) {
+    throw refError(
+      input,
+      `the namespace '${namespace}' must be lowercase kebab-case: a letter, then ` +
+        "letters, digits or hyphens."
+    );
+  }
+
+  if (recipe !== undefined) {
+    if (recipe.length === 0) {
+      throw refError(input, "the recipe name after '/' is empty.");
+    }
+    if (!RECIPE_NAME_PATTERN.test(recipe)) {
+      throw refError(
+        input,
+        `the recipe name '${recipe}' must be lowercase kebab-case: a letter, then ` +
+          "letters, digits or hyphens."
+      );
+    }
+  }
+
+  if (range !== undefined) {
+    if (recipe === undefined) {
+      throw refError(
+        input,
+        "a version range applies to a recipe, and namespaces are not versioned. " +
+          "Name a recipe, as in 'workflow/task-files@^1.2.0'."
+      );
+    }
+    if (semver.validRange(range) === null) {
+      throw refError(
+        input,
+        `'${range}' is not a version range. Ranges follow npm's rules, such as ` +
+          "'^1.2.0', '~2.1', '>=1.0.0 <2.0.0' or '*'."
+      );
+    }
+  }
+
+  const parsed: ParsedRef = { namespace };
+  if (repo !== undefined) parsed.repo = repo;
+  if (recipe !== undefined) parsed.recipe = recipe;
+  if (range !== undefined) parsed.range = range;
+  return parsed;
+}
+
+/**
+ * Parses a ref, returning undefined instead of throwing. Use this where a bad
+ * ref is reported through another mechanism, such as a zod issue.
+ *
+ * @param input - The ref as written.
+ */
+export function tryParseRef(input: string): ParsedRef | undefined {
+  try {
+    return parseRef(input);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * True when the input parses as a ref.
+ *
+ * @param input - The ref as written.
+ */
+export function isValidRef(input: string): boolean {
+  return tryParseRef(input) !== undefined;
+}
+
+/**
+ * Renders a parsed ref back into its canonical written form. Round-trips with
+ * parseRef, apart from surrounding whitespace.
+ *
+ * @param parsed - The ref parts.
+ */
+export function formatRef(parsed: ParsedRef): string {
+  const qualifier = parsed.repo === undefined ? "" : `${parsed.repo}:`;
+  const recipe = parsed.recipe === undefined ? "" : `/${parsed.recipe}`;
+  const range = parsed.range === undefined ? "" : `@${parsed.range}`;
+  return `${qualifier}${parsed.namespace}${recipe}${range}`;
+}
+
+/**
+ * The ref's identity, with the repo qualifier and the version range dropped:
+ * `namespace` for a namespace ref, `namespace/recipe` for a recipe ref. This is
+ * the key everything else is stored under (subscriptions, the index, the
+ * lockfile), so the same recipe is never recorded twice under two spellings.
+ *
+ * @param parsed - The ref parts.
+ */
+export function refKey(parsed: ParsedRef): string {
+  return parsed.recipe === undefined
+    ? parsed.namespace
+    : `${parsed.namespace}/${parsed.recipe}`;
+}
+
+/** True when the ref names a whole namespace rather than a single recipe. */
+export function isNamespaceRef(parsed: ParsedRef): boolean {
+  return parsed.recipe === undefined;
+}
+
+// --- Dependency refs ----------------------------------------------------------------------------
+
+/**
+ * The default host of each provider that can appear as a dependency locator's
+ * scheme. A locator whose repository path does not begin with a host segment
+ * (a segment carrying a dot) means the provider's own public host.
+ *
+ * The values match the `GITHUB_HOST` and `GITLAB_HOST` constants the providers
+ * themselves use; they are repeated here because the ref parser deliberately
+ * imports nothing from the provider layer, which is built on top of it.
+ */
+export const DEPENDENCY_PROVIDER_HOSTS: Readonly<Record<string, string>> = {
+  github: "github.com",
+  gitlab: "gitlab.com",
+};
+
+/**
+ * A dependency as a recipe manifest writes it, in either of the two spellings
+ * `depends` and `subscribes` accept.
+ *
+ * A SIBLING is a recipe in the same repository, written as a bare ref; a REMOTE
+ * is a recipe in another repository, written as a locator URL whose scheme is
+ * the provider's identifier.
+ */
+export type DependencyRef = {
+  /** Whether the target lives in this repository or in another one. */
+  kind: "sibling" | "remote";
+  /** The provider identifier the locator's scheme named. Remote refs only. */
+  provider?: string;
+  /** The host the repository lives on, explicit or the provider's default. */
+  host?: string;
+  /** The repository's path on that host, such as `sous-io/sous-recipes`. */
+  repoPath?: string;
+  /** The repository's canonical identity, `<host>/<repoPath>`. Remote refs only. */
+  canonicalRepo?: string;
+  /** The namespace the target recipe belongs to. */
+  namespace: string;
+  /**
+   * The recipe's name. A sibling ref may name a whole namespace and leave this
+   * out; a locator URL always names a recipe, because its last two path
+   * segments are by rule the namespace and the recipe.
+   */
+  recipe?: string;
+  /** The version range, when one was written. */
+  range?: string;
+};
+
+/** The one-line reminder appended to every dependency ref error. */
+const DEPENDENCY_SYNTAX_HELP =
+  "A dependency is written either as a bare ref naming a recipe in this same repository " +
+  "('workflow/task-files', optionally with a range such as 'workflow/task-files@^1.1'), " +
+  "or as a locator URL naming a recipe in another repository " +
+  "('github://sous-io/sous-recipes/workflow/task-files@^1.1').";
+
+/** Builds a ConfigError that quotes the offending dependency and shows the grammar. */
+function dependencyError(input: string, problem: string): ConfigError {
+  return new ConfigError(
+    `Invalid dependency '${input}': ${problem}\n  ${DEPENDENCY_SYNTAX_HELP}`
+  );
+}
+
+/** The scheme a locator URL leads with, when it leads with one. */
+const LOCATOR_SCHEME_PATTERN = /^([a-z][a-z0-9+.-]*):\/\/(.*)$/i;
+
+/**
+ * Parses one entry of a recipe manifest's `depends` or `subscribes` list.
+ *
+ * parseDependencyRef("workflow/task-files");
+ * // -> { kind: "sibling", namespace: "workflow", recipe: "task-files" }
+ *
+ * parseDependencyRef("github://sous-io/sous-recipes/workflow/sat@^1.1");
+ * // -> { kind: "remote", provider: "github", host: "github.com",
+ * //      repoPath: "sous-io/sous-recipes",
+ * //      canonicalRepo: "github.com/sous-io/sous-recipes",
+ * //      namespace: "workflow", recipe: "sat", range: "^1.1" }
+ *
+ * @param input - The dependency exactly as the manifest wrote it.
+ */
+export function parseDependencyRef(input: string): DependencyRef {
+  if (typeof input !== "string") {
+    throw dependencyError(String(input), "a dependency must be a string.");
+  }
+
+  const trimmed = input.trim();
+  if (trimmed.length === 0) {
+    throw dependencyError(input, "a dependency must not be empty.");
+  }
+
+  const locator = LOCATOR_SCHEME_PATTERN.exec(trimmed);
+  if (locator !== null) return parseRemoteDependency(input, locator[1]!, locator[2]!);
+
+  // Anything without a scheme is a sibling, so it follows the ordinary ref
+  // grammar; the one thing a manifest may no longer write is the consumer-side
+  // 'repo:' qualifier, which names a short name only that project knows.
+  if (trimmed.includes(":")) {
+    throw dependencyError(
+      input,
+      "a 'repo:' qualifier names a short name that only the consuming project knows, so " +
+        "it cannot appear in a published manifest. Name the other repository by its " +
+        "location instead, as in 'github://owner/repository/namespace/recipe'."
+    );
+  }
+
+  const parsed = parseRef(trimmed);
+  const sibling: DependencyRef = { kind: "sibling", namespace: parsed.namespace };
+  if (parsed.recipe !== undefined) sibling.recipe = parsed.recipe;
+  if (parsed.range !== undefined) sibling.range = parsed.range;
+  return sibling;
+}
+
+/**
+ * Parses the locator form, whose scheme is the provider's identifier.
+ *
+ * The path is read from the RIGHT: the last two segments are always the
+ * namespace and the recipe, because they are the recipe's published identity
+ * and never a filesystem path. Everything before them is the repository, whose
+ * first segment is the host when it carries a dot and otherwise the provider's
+ * own public host.
+ *
+ * @param input - The dependency as written, for error messages.
+ * @param scheme - The scheme, which names the provider.
+ * @param rest - Everything after the `://`.
+ */
+function parseRemoteDependency(
+  input: string,
+  scheme: string,
+  rest: string
+): DependencyRef {
+  const provider = scheme.toLowerCase();
+
+  if (provider === "local") {
+    throw dependencyError(
+      input,
+      "a local repository is a consumer's convenience, not a published location, so a " +
+        "manifest cannot depend on one. Publish the recipe and depend on it by its " +
+        "published location."
+    );
+  }
+
+  const defaultHost = DEPENDENCY_PROVIDER_HOSTS[provider];
+  if (defaultHost === undefined) {
+    const known = Object.keys(DEPENDENCY_PROVIDER_HOSTS).sort().join(", ");
+    throw dependencyError(
+      input,
+      `'${provider}' is not a provider sous can fetch from. The scheme of a locator URL ` +
+        `is the provider's own identifier; sous ships these: ${known}.`
+    );
+  }
+
+  let body = rest.trim();
+  let range: string | undefined;
+  const atIndex = body.indexOf("@");
+  if (atIndex !== -1) {
+    if (body.indexOf("@", atIndex + 1) !== -1) {
+      throw dependencyError(input, "a dependency may carry at most one '@' version range.");
+    }
+    range = body.slice(atIndex + 1).trim();
+    body = body.slice(0, atIndex);
+    if (range.length === 0) {
+      throw dependencyError(input, "the '@' is not followed by a version range.");
+    }
+    if (semver.validRange(range) === null) {
+      throw dependencyError(
+        input,
+        `'${range}' is not a version range. Ranges follow npm's rules, such as '^1.2.0', ` +
+          "'~2.1', '>=1.0.0 <2.0.0' or '*'."
+      );
+    }
+  }
+
+  const segments = body.split("/").filter((segment) => segment.length > 0);
+
+  // The recipe is two segments and a repository is at least an owner and a
+  // name, so four is the shortest locator that can mean anything.
+  if (segments.length < 4) {
+    throw dependencyError(
+      input,
+      "a locator URL names a repository and then the recipe inside it, as in " +
+        "'github://owner/repository/namespace/recipe'. The last two segments are always " +
+        "the namespace and the recipe."
+    );
+  }
+
+  const recipe = segments.pop()!;
+  const namespace = segments.pop()!;
+
+  if (!NAMESPACE_NAME_PATTERN.test(namespace)) {
+    throw dependencyError(
+      input,
+      `the namespace '${namespace}' must be lowercase kebab-case: a letter, then letters, ` +
+        "digits or hyphens."
+    );
+  }
+  if (!RECIPE_NAME_PATTERN.test(recipe)) {
+    throw dependencyError(
+      input,
+      `the recipe name '${recipe}' must be lowercase kebab-case: a letter, then letters, ` +
+        "digits or hyphens."
+    );
+  }
+
+  const first = segments[0]!;
+  const hasHost = first.includes(".");
+  const host = (hasHost ? first : defaultHost).toLowerCase();
+  const pathSegments = hasHost ? segments.slice(1) : segments;
+
+  if (pathSegments.length < 2) {
+    const what =
+      pathSegments.length === 0 ? "nothing" : `only '${pathSegments.join("/")}'`;
+    throw dependencyError(
+      input,
+      `the host '${host}' is followed by ${what}, and a repository is named by an owner ` +
+        "and a repository name, as in " +
+        "'gitlab://gitlab.example.com/group/subgroup/project/namespace/recipe'."
+    );
+  }
+
+  const repoPath = pathSegments.join("/").replace(/\.git$/i, "");
+
+  return {
+    kind: "remote",
+    provider,
+    host,
+    repoPath,
+    canonicalRepo: `${host}/${repoPath}`.toLowerCase(),
+    namespace,
+    recipe,
+    ...(range === undefined ? {} : { range }),
+  };
+}
+
+/**
+ * The recipe key a dependency names: `namespace/recipe`, or the bare namespace
+ * when a sibling ref named a whole namespace. This is what the index, the
+ * lockfile and the store all file a recipe under.
+ *
+ * @param parsed - The parsed dependency.
+ */
+export function dependencyRefKey(parsed: DependencyRef): string {
+  return parsed.recipe === undefined
+    ? parsed.namespace
+    : `${parsed.namespace}/${parsed.recipe}`;
+}
+
+/**
+ * Renders a parsed dependency back into the form a manifest writes. Round-trips
+ * with parseDependencyRef, apart from surrounding whitespace and a host that was
+ * left implicit.
+ *
+ * @param parsed - The parsed dependency.
+ */
+export function formatDependencyRef(parsed: DependencyRef): string {
+  const key = dependencyRefKey(parsed);
+  const range = parsed.range === undefined ? "" : `@${parsed.range}`;
+  if (parsed.kind === "sibling") return `${key}${range}`;
+  return `${parsed.provider}://${parsed.host}/${parsed.repoPath}/${key}${range}`;
+}
+
+/**
+ * Parses a dependency, returning undefined instead of throwing. Use this where
+ * a bad dependency is reported through another mechanism, such as a zod issue.
+ *
+ * @param input - The dependency as written.
+ */
+export function tryParseDependencyRef(input: string): DependencyRef | undefined {
+  try {
+    return parseDependencyRef(input);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The HTTPS location a remote dependency points at, which is what `sous repo
+ * add` would be given for it.
+ *
+ * @param parsed - A parsed remote dependency.
+ */
+export function dependencyRepoUrl(parsed: DependencyRef): string | undefined {
+  if (parsed.kind !== "remote") return undefined;
+  return `https://${parsed.host}/${parsed.repoPath}`;
+}

package/src/lib/repos/reference-report.ts

@@ -0,0 +1,122 @@
+/**
+ * Saying what a reference resolved to.
+ *
+ * A word on the command line can name a repository, a namespace, a recipe or a
+ * variable, and when sous settles which one it means it has to say so. What it
+ * resolved to is a set of facts, so it is written as the same key and value
+ * list every other set of facts in the CLI is written as, with one short
+ * sentence after it saying why that candidate won. One function builds it, so
+ * every command that resolves a reference reports it the same way; `pickReference`
+ * in `src/lib/refs/pick.ts` is the single caller, which is how every command gets it.
+ */
+
+import {
+  formatVariable,
+  indent,
+  wrapColumns,
+  wrapText,
+  type VariableEntry,
+} from "../../utils/formatting.js";
+import { SCOPE_LABELS, SousScope } from "../refs/scopes.js";
+import type { ReferenceMatch } from "../refs/find.js";
+
+/** What a resolved reference is, in the words the report shows. */
+export interface ResolvedReferenceFacts {
+  /** The reference exactly as the person wrote it. */
+  search: string;
+  /** The fully qualified spelling the run proceeds with. */
+  resolvedTo: string;
+  /** What kind of thing it turned out to be: "recipe", "namespace", "repository". */
+  kind: string;
+  /** The repository publishing it. */
+  repository?: string;
+  /** The namespace it lives in, when it has one. */
+  namespace?: string;
+  /** The recipe itself, when the reference named one. */
+  recipe?: string;
+  /** The variable itself, when the reference named one. */
+  variable?: string;
+  /** Where a repository lives, when the reference named a repository. */
+  location?: string;
+  /** The publisher's one-line summary, when there is one. */
+  description?: string;
+  /**
+   * Why this candidate won, as the closing sentence. The default says the
+   * reference named one thing and nothing else; a caller that settled it some
+   * other way (taking the first of several, say) supplies its own.
+   */
+  reason?: string;
+}
+
+/**
+ * The report as lines to write: the facts, a blank line, and the sentence.
+ *
+ * @param facts - What the reference resolved to.
+ * @returns The lines to write, ready for the console.
+ */
+export function formatResolvedReference(facts: ResolvedReferenceFacts): string[] {
+  const entries: VariableEntry[] = [
+    { label: "Resolved to", value: facts.resolvedTo },
+    ...(facts.variable === undefined ? [] : [{ label: "Variable", value: facts.variable }]),
+    ...(facts.recipe === undefined ? [] : [{ label: "Recipe", value: facts.recipe }]),
+    ...(facts.namespace === undefined ? [] : [{ label: "Namespace", value: facts.namespace }]),
+    ...(facts.repository === undefined
+      ? []
+      : [{ label: "Repository", value: facts.repository }]),
+    ...(facts.location === undefined ? [] : [{ label: "Location", value: facts.location }]),
+    ...(facts.description === undefined
+      ? []
+      : [{ label: "Description", value: facts.description }]),
+  ];
+
+  const labelWidth = Math.max(...entries.map((entry) => entry.label.length));
+  const lines = entries.flatMap((entry) => formatVariable(entry, { labelWidth }));
+
+  const reason =
+    facts.reason ??
+    `'${facts.search}' named one ${facts.kind}, and nothing else, so that is what ` +
+      `is being used.`;
+
+  lines.push("");
+  for (const line of wrapText(reason, wrapColumns() - 4)) {
+    lines.push(indent(line));
+  }
+
+  return lines;
+}
+
+/**
+ * The facts one match carries, ready for `formatResolvedReference`.
+ *
+ * The match knows what it is; this decides which of its fields are facts worth
+ * showing. A repository's detail is where it lives rather than a summary of it,
+ * and a repository's own name is already the resolved spelling, so neither is
+ * repeated as a line of its own. What a match resolves to is always its fully
+ * qualified key, including for an environment variable name, because the key is
+ * what the rest of the run proceeds with.
+ *
+ * @param match - The match the run proceeds with.
+ * @param search - The reference exactly as it was written.
+ * @param reason - The closing sentence, when the caller has one of its own.
+ */
+export function resolvedReferenceFacts(
+  match: ReferenceMatch,
+  search: string,
+  reason?: string
+): ResolvedReferenceFacts {
+  const isRepository = match.scope === SousScope.Repository;
+  const resolvedTo = match.key;
+
+  return {
+    search,
+    resolvedTo,
+    kind: SCOPE_LABELS[match.scope],
+    ...(match.variable === undefined ? {} : { variable: match.variable }),
+    ...(match.recipe === undefined ? {} : { recipe: match.recipe }),
+    ...(match.namespace === undefined ? {} : { namespace: match.namespace }),
+    ...(match.repo === undefined || match.repo === resolvedTo ? {} : { repository: match.repo }),
+    ...(isRepository && match.detail !== undefined ? { location: match.detail } : {}),
+    ...(!isRepository && match.detail !== undefined ? { description: match.detail } : {}),
+    ...(reason === undefined ? {} : { reason }),
+  };
+}