@sous-io/sous 0.2.32 → 0.2.34

package/src/services/ref-resolver/lookups/variable-lookup.ts

@@ -0,0 +1,123 @@
+import type { DefinedVariable } from "../../../lib/vars/definition-source.js";
+import { matchName, type NameMatch } from "../glob.js";
+import { refKey } from "../format.js";
+import type { RepoRef, SousRef, VariableRef } from "../types.js";
+import { CatalogMatcher, type CatalogRepo } from "./catalog-matcher.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/**
+ * The ref a defined variable is known as: its name, with the recipe that
+ * published it, that recipe's namespace and the repository's short name nested
+ * as parents.
+ *
+ * @param defined - The definition and the recipe that published it.
+ */
+export function variableRefOf(defined: DefinedVariable): VariableRef {
+  const { repo, namespace, name } = defined.recipe;
+  return {
+    kind: "variable",
+    name: defined.definition.name,
+    description: defined.definition.prompt,
+    recipe: {
+      kind: "recipe",
+      name,
+      namespace: { kind: "namespace", name: namespace, repo: { kind: "repo", name: repo } },
+    },
+  };
+}
+
+/** The weaker of two matches: one folded part makes the whole thing folded. */
+function both(left: NameMatch, right: NameMatch): NameMatch {
+  if (left === undefined || right === undefined) return undefined;
+  return left === "folded" || right === "folded" ? "folded" : "exact";
+}
+
+/**
+ * Answers from the variable definitions in play, which is what a variables
+ * command searches: variables themselves (by name, or qualified by recipe,
+ * namespace and repository, in any combination) and the repositories,
+ * namespaces and recipes that publish them. A namespace that publishes no
+ * variable this project holds has no questions to ask, so naming it would
+ * resolve to nothing rather than to an empty set of questions. Building the
+ * answer from the definitions also means `sous vars ask --file` resolves refs
+ * exactly as a subscribed project does.
+ */
+export class VariableLookup implements RefLookup {
+  private readonly matcher: CatalogMatcher;
+
+  /**
+   * @param variables - The variable definitions in play, with the recipe that published each.
+   * @param trusted - The trusted repositories, which lend each repository its location
+   *   and each recipe its folder, so a ref written as a location settles here too.
+   */
+  constructor(
+    private readonly variables: DefinedVariable[],
+    private readonly trusted: CatalogRepo[] = []
+  ) {
+    const repos = new Map<string, CatalogRepo>();
+
+    for (const defined of variables) {
+      const { repo: repoName, namespace, name: recipe } = defined.recipe;
+      const known = trusted.find((entry) => entry.name === repoName);
+
+      let repo = repos.get(repoName);
+      if (repo === undefined) {
+        repo = {
+          name: repoName,
+          namespaces: [],
+          recipes: [],
+          ...(known?.location === undefined ? {} : { location: known.location }),
+        };
+        repos.set(repoName, repo);
+      }
+      if (!repo.namespaces.some((entry) => entry.name === namespace)) {
+        repo.namespaces.push({ name: namespace });
+      }
+      if (!repo.recipes.some((entry) => entry.namespace === namespace && entry.name === recipe)) {
+        const path = known?.recipes.find(
+          (entry) => entry.namespace === namespace && entry.name === recipe
+        )?.path;
+        repo.recipes.push({ namespace, name: recipe, ...(path === undefined ? {} : { path }) });
+      }
+    }
+    this.matcher = new CatalogMatcher([...repos.values()]);
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    if (candidate.kind !== "variable") return this.matcher.match(candidate);
+
+    const qualifier: RepoRef | undefined =
+      candidate.recipe?.namespace?.repo ?? candidate.recipe?.repo ?? candidate.repo;
+    const matches: RefMatch[] = [];
+
+    for (const defined of this.variables) {
+      const { repo, namespace, name: recipe } = defined.recipe;
+      const location = this.trusted.find((entry) => entry.name === repo)?.location;
+
+      let spelling: NameMatch = "exact";
+      if (qualifier?.name !== undefined) spelling = matchName(qualifier.name, repo);
+      if (qualifier?.location !== undefined && location?.identity !== qualifier.location.identity) {
+        spelling = undefined;
+      }
+      if (candidate.recipe !== undefined) {
+        spelling = both(spelling, matchName(candidate.recipe.name, recipe));
+        if (candidate.recipe.namespace !== undefined) {
+          spelling = both(spelling, matchName(candidate.recipe.namespace.name, namespace));
+        }
+      }
+      spelling = both(spelling, matchName(candidate.name, defined.definition.name));
+      if (spelling === undefined) continue;
+
+      matches.push({
+        ref: {
+          ...variableRefOf(defined),
+          ...(candidate.vars === undefined ? {} : { vars: candidate.vars }),
+        },
+        exactSpelling: spelling === "exact",
+      });
+    }
+    return matches.sort((left, right) =>
+      refKey(left.ref) < refKey(right.ref) ? -1 : refKey(left.ref) > refKey(right.ref) ? 1 : 0
+    );
+  }
+}

package/src/services/ref-resolver/named-refs.ts

@@ -0,0 +1,144 @@
+/**
+ * Namespaces and recipes by their stored names: what a lockfile, an index, a
+ * config key and a manifest entry hold. A `NamedRef` is a namespace, or a
+ * recipe with its namespace, and `shortKey` (in `pruners/rule-helpers.ts`) is
+ * the `namespace` or `namespace/recipe` it is stored under.
+ *
+ * Callers with a stored key use `splitRecipeKey` and `namespaceOfKey`, which
+ * read it through the resolver with `RefSource.Lockfile`, so a key is read by
+ * the same code wherever it came from.
+ */
+
+import { ConfigError } from "../../lib/errors.js";
+import { sharedRefResolver } from "./container.js";
+import { locationOf } from "./parts.js";
+import { RefSource } from "./source.js";
+import type { NamespaceRef, RecipeRef, SousRef } from "./types.js";
+
+/** A namespace, or a recipe that names its namespace. */
+export type NamedRef = NamespaceRef | RecipeRef;
+
+/**
+ * True when a ref is a namespace or a recipe that names its namespace.
+ *
+ * @param ref - Any ref.
+ */
+export function isNamedRef(ref: SousRef): ref is NamedRef {
+  return ref.kind === "namespace" || (ref.kind === "recipe" && ref.namespace !== undefined);
+}
+
+/**
+ * A namespace ref, optionally inside a repository known by short name.
+ *
+ * @param name - The namespace.
+ * @param repo - The repository's short name, when the ref is qualified by one.
+ */
+export function namespaceRef(name: string, repo?: string): NamespaceRef {
+  return {
+    kind: "namespace",
+    name,
+    ...(repo === undefined ? {} : { repo: { kind: "repo", name: repo } }),
+  };
+}
+
+/**
+ * A recipe ref with its namespace, optionally inside a repository known by
+ * short name and with a version range.
+ *
+ * @param namespace - The recipe's namespace.
+ * @param name - The recipe.
+ * @param options - The repository's short name and the range, when there are any.
+ */
+export function recipeRef(
+  namespace: string,
+  name: string,
+  options: { repo?: string; range?: string } = {}
+): RecipeRef {
+  return {
+    kind: "recipe",
+    name,
+    namespace: namespaceRef(namespace, options.repo),
+    ...(options.range === undefined ? {} : { range: options.range }),
+  };
+}
+
+/**
+ * The same namespace or recipe, qualified by a repository's short name. A
+ * recipe holds its repository through its namespace.
+ *
+ * @param ref - A namespace or a recipe.
+ * @param repo - The repository's short name; left undefined, the ref comes back as it is.
+ */
+export function withRepoName(ref: NamedRef, repo: string | undefined): NamedRef {
+  if (repo === undefined) return ref;
+  if (ref.kind === "namespace") return { ...ref, repo: { kind: "repo", name: repo } };
+  return { ...ref, namespace: namespaceRef(ref.namespace?.name ?? "", repo) };
+}
+
+/**
+ * The one reading of a ref that must name a namespace or a recipe by its short
+ * form: a config key, a stored key, or a ref a caller has already settled.
+ *
+ * @param input - The ref as written.
+ * @param from - Where it was written.
+ * @throws A ConfigError when the place refuses it, or it names a location or reads several ways.
+ */
+export function parseNamedRef(input: string, from: RefSource = RefSource.CommandLine): NamedRef {
+  const { refs } = sharedRefResolver().parse(input, from);
+  const named = refs.filter((ref): ref is NamedRef => isNamedRef(ref) && locationOf(ref) === undefined);
+  if (named.length === 1 && !refs.some((ref) => locationOf(ref) !== undefined)) return named[0]!;
+  throw new ConfigError(
+    `Invalid ref '${input}': this needs a namespace or a recipe named by its short form, such ` +
+      `as 'workflow/alpha', and this ref names a location.`
+  );
+}
+
+/** What a stored key was read as, by key. A key's reading never changes, and listings read every key many times. */
+const storedKeys = new Map<string, { namespace: string; name?: string }>();
+
+/**
+ * Reads a stored key through the resolver, once per distinct key.
+ *
+ * @param key - A key sous stored.
+ */
+function readStoredKey(key: string): { namespace: string; name?: string } {
+  const known = storedKeys.get(key);
+  if (known !== undefined) return known;
+  const parsed = parseNamedRef(key, RefSource.Lockfile);
+  const read =
+    parsed.kind === "namespace"
+      ? { namespace: parsed.name }
+      : { namespace: parsed.namespace!.name, name: parsed.name };
+  storedKeys.set(key, read);
+  return read;
+}
+
+/**
+ * The namespace and name of a stored recipe key, `namespace/recipe`.
+ *
+ * splitRecipeKey("workflow/alpha"); // -> { namespace: "workflow", name: "alpha" }
+ *
+ * @param key - A key sous stored.
+ */
+export function splitRecipeKey(key: string): { namespace: string; name: string } {
+  const { namespace, name } = readStoredKey(key);
+  if (name === undefined) {
+    throw new ConfigError(
+      `Invalid ref '${key}': a recipe key names a namespace and a recipe.\n` +
+        `  A stored key is written as 'namespace' or 'namespace/recipe'.`
+    );
+  }
+  return { namespace, name };
+}
+
+/**
+ * The namespace a stored key belongs to: the key itself for a namespace, and
+ * its namespace for a recipe.
+ *
+ * namespaceOfKey("workflow/alpha"); // -> "workflow"
+ *
+ * @param key - A key sous stored.
+ */
+export function namespaceOfKey(key: string): string {
+  return readStoredKey(key).namespace;
+}

package/src/services/ref-resolver/parser/env-var-splitter.ts

@@ -0,0 +1,27 @@
+/**
+ * Reads an environment variable name.
+ */
+
+import { makeInjectable } from "../injectable.js";
+import { ENV_VAR_NAME } from "../glob.js";
+import { BaseRefSplitter, finishRef, type PartialRef } from "./partial-ref.js";
+
+/**
+ * Any text that is a legal environment variable name (a letter or underscore,
+ * then letters, digits or underscores) is also read as one, whole: `_` is both
+ * the delimiter and an identifier character, so a name is never split into the
+ * scopes that might have produced it. The text stays unread for the other
+ * splitters too, because `workflow` is a namespace as well.
+ */
+export class EnvVarSplitter extends BaseRefSplitter {
+  readonly order = 600;
+
+  protected read(state: PartialRef): PartialRef[] {
+    if (state.repo !== undefined || state.range !== undefined || !ENV_VAR_NAME.test(state.rest)) {
+      return [state];
+    }
+    return [state, finishRef(state, { kind: "envVar", name: state.rest })];
+  }
+}
+
+makeInjectable(EnvVarSplitter);

package/src/services/ref-resolver/parser/location-splitter.ts

@@ -0,0 +1,239 @@
+/**
+ * Reads a repository written as a location: a URL, an SSH remote, a
+ * provider-scheme locator or a host path.
+ *
+ * Nothing host-specific lives here. Where a repository path ends and what a
+ * browser path looks like are each provider's own rule, asked through
+ * `RepoProvider.readLocation`, which may answer more than one way (a GitLab
+ * nested group does not say where the project path ends).
+ */
+
+import { makeInjectable } from "../injectable.js";
+import { REF_TOKENS } from "../tokens.js";
+import {
+  detectProvider,
+  providerById,
+  type RepoProvider,
+} from "../../../lib/repos/providers/index.js";
+import { locationFor } from "../location.js";
+import type { RepoRef } from "../types.js";
+import { BaseRefSplitter, finishRef, type PartialRef } from "./partial-ref.js";
+
+/** A URL that names its scheme, such as `https://` or `github://`. */
+const SCHEME_PATTERN = /^([a-z][a-z0-9+.-]*):\/\/(.*)$/is;
+
+/** The `scp`-style SSH form, as in `git@github.com:owner/name.git`. */
+const SCP_PATTERN = /^[^@\s/:]+@([^@\s/:]+):(.+)$/s;
+
+/** Schemes that are ordinary URLs rather than a provider's own identifier. */
+const URL_SCHEMES = new Set(["http", "https", "ssh", "git", "git+ssh", "ssh+git"]);
+
+/** Schemes that name a repository on this machine. */
+const LOCAL_SCHEMES = new Set(["local", "file"]);
+
+/**
+ * True when a written ref names a location (a URL, an SSH remote, a
+ * provider-scheme locator or a host path) rather than a short name. A short
+ * name never carries `://`, an `@` before a `:`, or a dot in its first segment.
+ *
+ * @param ref - The ref as written.
+ */
+export function looksLikeLocation(ref: string): boolean {
+  const trimmed = ref.trim();
+  if (SCHEME_PATTERN.test(trimmed)) return true;
+  if (SCP_PATTERN.test(trimmed)) return true;
+  const first = trimmed.split("/")[0] ?? "";
+  return trimmed.includes("/") && first.includes(".") && !first.includes(":");
+}
+
+/** A location, taken apart only as far as every host agrees. */
+type Taken = { provider: RepoProvider; host: string; segments: string[] };
+
+/** A URL path's segments, decoded, with empty ones dropped. */
+function pathSegments(pathname: string): string[] {
+  return pathname
+    .split(/[?#]/)[0]!
+    .split("/")
+    .map((segment) => {
+      try {
+        return decodeURIComponent(segment);
+      } catch {
+        return segment;
+      }
+    })
+    .filter((segment) => segment.length > 0);
+}
+
+/**
+ * Reads a location into a repository, and whatever is named inside it. A
+ * repository that a short name does not already qualify gets the location; the
+ * names after it are left in `rest` for the name splitter, and a browser path
+ * becomes a finished repository ref of its own.
+ */
+export class LocationSplitter extends BaseRefSplitter {
+  readonly order = 300;
+
+  /**
+   * @param providers - The providers that read locations.
+   */
+  constructor(private readonly providers: RepoProvider[]) {
+    super();
+  }
+
+  protected read(state: PartialRef): PartialRef[] {
+    if (state.repo !== undefined || !looksLikeLocation(state.rest)) return [state];
+
+    const body = state.rest;
+    const scheme = SCHEME_PATTERN.exec(body);
+    if (scheme !== null && LOCAL_SCHEMES.has(scheme[1]!.toLowerCase())) {
+      return [this.local(state, scheme[2]!)];
+    }
+
+    const taken = this.take(state, body, scheme);
+    if (taken === undefined) return [];
+
+    const { provider, host, segments } = taken;
+    const specific: PartialRef[] = [];
+    const repositories: RepoRef[] = [];
+
+    for (const reading of provider.readLocation({ host, segments })) {
+      const location = locationFor(provider, host, reading.repoPath);
+      if (location === undefined) continue;
+
+      if (reading.browsed !== undefined) {
+        const browsed = reading.browsed.replace(/^\/+|\/+$/g, "");
+        if (browsed.length === 0) continue;
+        specific.push(
+          finishRef(state, {
+            kind: "repo",
+            location,
+            browsed,
+            ...(state.range === undefined ? {} : { range: state.range }),
+          })
+        );
+        continue;
+      }
+
+      const named = reading.named ?? [];
+      if (named.length === 0) {
+        repositories.push({ kind: "repo", location });
+        continue;
+      }
+      specific.push({ ...state, rest: named.join("/"), repo: { kind: "repo", location } });
+    }
+
+    // A reading of the whole repository is only kept when nothing more
+    // specific was read, because a namespace or a recipe is what a ref is for.
+    if (specific.length > 0) return specific;
+
+    if (repositories.length === 0) {
+      state.problems.push(
+        `the ${provider.id} provider cannot read a namespace or a recipe from this location. ` +
+          `After the repository, a location names a namespace and optionally a recipe, as in ` +
+          `'${provider.formatLocator(host, "owner/repository", "workflow/alpha")}'.`
+      );
+      return [];
+    }
+    if (state.range !== undefined) {
+      state.problems.push("a version range applies to a recipe, not to a repository.");
+      return [];
+    }
+    return repositories.map((repo) => finishRef(state, repo));
+  }
+
+  /** A repository on this machine: kept as a location the pruners can refuse. */
+  private local(state: PartialRef, path: string): PartialRef {
+    return finishRef(state, {
+      kind: "repo",
+      location: {
+        provider: "local",
+        host: "localhost",
+        repoPath: path,
+        identity: `localhost/${path.replace(/^\/+/, "")}`,
+        url: state.rest,
+      },
+    });
+  }
+
+  /**
+   * Takes the host-agnostic parts out of a location: which provider reads it,
+   * the host, and the path segments after the host. Records why not, and
+   * returns nothing, when the location cannot be read.
+   */
+  private take(
+    state: PartialRef,
+    body: string,
+    scheme: RegExpExecArray | null
+  ): Taken | undefined {
+    const providers = this.providers;
+    const known = providers
+      .filter((provider) => provider.defaultHost !== undefined)
+      .map((provider) => provider.id)
+      .sort()
+      .join(", ");
+
+    if (scheme !== null) {
+      const name = scheme[1]!.toLowerCase();
+
+      if (URL_SCHEMES.has(name)) {
+        let url: URL;
+        try {
+          url = new URL(body);
+        } catch {
+          state.problems.push("the URL could not be read.");
+          return undefined;
+        }
+        const host = url.host.toLowerCase();
+        const segments = pathSegments(url.pathname);
+        return this.forHost(state, host, segments);
+      }
+
+      const provider = providerById(name, providers);
+      if (provider === undefined || provider.defaultHost === undefined) {
+        state.problems.push(
+          `'${name}' is not a provider sous can read a location from. The scheme of a locator ` +
+            `is the provider's own identifier; sous ships these: ${known}. An ordinary ` +
+            "'https://' URL works too."
+        );
+        return undefined;
+      }
+      let segments = pathSegments(scheme[2]!);
+      let host = provider.defaultHost;
+      if (segments[0]?.includes(".") === true) {
+        host = segments[0].toLowerCase();
+        segments = segments.slice(1);
+      }
+      return { provider, host, segments };
+    }
+
+    const scp = SCP_PATTERN.exec(body);
+    if (scp !== null) {
+      return this.forHost(state, scp[1]!.toLowerCase(), pathSegments(scp[2]!));
+    }
+
+    const all = pathSegments(body);
+    return this.forHost(state, all[0]!.toLowerCase(), all.slice(1));
+  }
+
+  /** The provider that recognizes a host, asked with the URL the location would start with. */
+  private forHost(state: PartialRef, host: string, segments: string[]): Taken | undefined {
+    const probe = `https://${host}/${segments.slice(0, 2).join("/")}`;
+    const provider = detectProvider(probe, this.providers);
+    if (provider !== undefined && provider.defaultHost !== undefined) {
+      return { provider, host, segments };
+    }
+    const ids = this.providers
+      .filter((entry) => entry.defaultHost !== undefined)
+      .map((entry) => entry.id)
+      .sort();
+    state.problems.push(
+      `sous does not recognize the host '${host}'. For a self-hosted instance, write the ` +
+        `location with the provider's scheme and the host, as in ` +
+        `'${ids[0] ?? "gitlab"}://${host}/owner/repository/namespace/recipe' (sous ships these ` +
+        `providers: ${ids.join(", ")}).`
+    );
+    return undefined;
+  }
+}
+
+makeInjectable(LocationSplitter, [{ multi: REF_TOKENS.Provider }]);