@sous-io/sous 0.2.36 → 1.0.1

package/src/services/ref-resolver/lookups/recorded-dependency-lookup.ts

@@ -1,62 +0,0 @@
-import { locationOf } from "../parts.js";
-import type { SousRef } from "../types.js";
-import type { RefLookup, RefMatch } from "./ref-lookup.js";
-
-/** What a repository's index recorded about one dependency, as far as settling needs. */
-export type RecordedDependencies = Record<string, { repo?: string } | undefined>;
-
-/**
- * Whether what a version's index entry recorded confirms a candidate reading
- * of one of its dependencies. This is the rule `RecordedDependencyLookup`
- * answers with, for callers that settle a dependency without waiting.
- *
- * @param candidate - One reading of the dependency as the manifest wrote it.
- * @param recorded - What the declaring version's index entry records, keyed `namespace/recipe`.
- */
-export function isConfirmedByRecord(
-  candidate: SousRef,
-  recorded: RecordedDependencies | undefined
-): boolean {
-  const identity = locationOf(candidate)?.identity;
-  const records = Object.entries(recorded ?? {}).filter(([, record]) =>
-    identity === undefined ? record?.repo === undefined : record?.repo === identity
-  );
-
-  switch (candidate.kind) {
-    case "repo":
-      return candidate.browsed !== undefined && identity !== undefined && records.length > 0;
-    case "namespace":
-      return records.some(([key]) => key.startsWith(`${candidate.name}/`));
-    case "recipe":
-      return (
-        candidate.namespace !== undefined &&
-        records.some(([key]) => key === `${candidate.namespace!.name}/${candidate.name}`)
-      );
-    default:
-      return false;
-  }
-}
-
-/**
- * Answers from what a published version's index entry recorded about its
- * dependencies, and never searches.
- *
- * A release settles a dependency that reads more than one way (a GitLab URL
- * with nested groups, a browser URL) and records the repository it settled on
- * beside each key it resolved; a consumer reads that record and never probes.
- * A candidate is confirmed when a record says so: a namespace by a record
- * under a key inside it, a recipe by a record under its own key, a browser
- * path by any record carrying its repository. A candidate that names no
- * location is confirmed by a record that names none, which is a sibling in the
- * declaring recipe's own repository.
- */
-export class RecordedDependencyLookup implements RefLookup {
-  /**
-   * @param recorded - What the declaring version's index entry records, keyed `namespace/recipe`.
-   */
-  constructor(private readonly recorded: RecordedDependencies | undefined) {}
-
-  async find(candidate: SousRef): Promise<RefMatch[]> {
-    return isConfirmedByRecord(candidate, this.recorded) ? [{ ref: candidate, exactSpelling: true }] : [];
-  }
-}

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

@@ -1,54 +0,0 @@
-/**
- * Lookups: what exists, as a queryable object rather than a list.
- *
- * A caller that knows what exists (the cached indexes, a release's recorded
- * dependencies, the variable definitions in play) hands the resolver a lookup,
- * and the candidate readings narrow to the ones that are actually available.
- */
-
-import type { SousRef } from "../types.js";
-
-/** One thing a candidate reading turned out to name. */
-export type RefMatch = {
-  /**
-   * The known ref, spelled the way it is published (not the way it was
-   * typed), with every parent it has.
-   */
-  ref: SousRef;
-  /**
-   * True when every part of the candidate matched in exactly the case it was
-   * written. A lookup returns case-insensitive matches too; the resolver keeps
-   * them only when nothing matched exactly.
-   */
-  exactSpelling: boolean;
-};
-
-/**
- * Answers what a candidate reading names.
- *
- * `find` returns an empty array when nothing known matches the candidate, and
- * throws when the lookup could not find out (an index that could not be
- * fetched): not finding an answer and failing to look are different things.
- */
-export interface RefLookup {
-  /**
-   * Every known ref a candidate names.
-   *
-   * @param candidate - One reading of a written ref.
-   */
-  find(candidate: SousRef): Promise<RefMatch[]>;
-}
-
-/**
- * A lookup that can also answer without waiting, for a caller whose own
- * interface is synchronous (a template engine resolving a path). It answers
- * exactly what `find` answers.
- */
-export interface SyncRefLookup extends RefLookup {
-  /**
-   * Every known ref a candidate names, at once.
-   *
-   * @param candidate - One reading of a written ref.
-   */
-  findSync(candidate: SousRef): RefMatch[];
-}

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

@@ -1,123 +0,0 @@
-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

@@ -1,144 +0,0 @@
-/**
- * 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

@@ -1,27 +0,0 @@
-/**
- * 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

@@ -1,239 +0,0 @@
-/**
- * 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 }]);