@sous-io/sous 0.2.28 → 0.2.30

package/src/lib/refs/scopes.ts

@@ -23,6 +23,40 @@ export enum SousScope {
   EnvVarName = "envVarName",
 }
 
+/**
+ * Where a ref was written. `parseRef` reads every form wherever a ref comes
+ * from, and the place decides which of those forms it allows: a refused form
+ * is an error saying what to write there instead.
+ */
+export enum RefSource {
+  /**
+   * A ref typed on the command line. Every form is allowed: a bare name, a
+   * namespace and recipe, a `repo:` qualifier, a version range, a
+   * provider-scheme locator, an HTTPS, SSH or scheme-less URL, and a browser
+   * URL copied from a host's file view. Names may be written in any case.
+   */
+  CommandLine = "commandLine",
+  /**
+   * A subscription key in a config layer. Only the stored form is allowed:
+   * `namespace` or `namespace/recipe`, lowercase. The repository a
+   * subscription resolves into is recorded in the lockfile, and its range in
+   * the entry's own `range` field.
+   */
+  Config = "config",
+  /**
+   * An entry of a recipe manifest's `depends` or `subscribes` list. A bare ref
+   * names a recipe in the same repository; every locator and URL form names
+   * one in another repository. A `repo:` qualifier is refused, because it is
+   * one project's private name for a repository, and so is a local path.
+   */
+  Manifest = "manifest",
+  /**
+   * A key sous wrote itself: the lockfile, the index and the store. Only the
+   * canonical `namespace` or `namespace/recipe` is allowed.
+   */
+  Lockfile = "lockfile",
+}
+
 /**
  * Every scope, in the order matches of equal specificity are listed in. It is
  * the order the one-word ref search has always used (a whole namespace before

package/src/lib/refs/settle.ts

@@ -0,0 +1,219 @@
+/**
+ * Settling what a ref means, once the index that can say is at hand.
+ *
+ * `parseRef` returns every reading of a written ref. Some readings are settled
+ * the moment they are read (`workflow/alpha`), and some need the index of the
+ * repository they point at: a browser URL names a folder, and only the `path`
+ * each recipe's index entry records says which recipe that folder is; a GitLab
+ * URL with nested groups can be read as several repositories, and only their
+ * indexes say which one publishes what was named.
+ *
+ * Names are matched the same way everywhere: the exact spelling first, then
+ * ignoring case. A name that still matches several things is a question for
+ * `pickReference`.
+ */
+
+import {
+  isBrowsedReading,
+  isNamedReading,
+  namespaceOfKey,
+  parseRef,
+  refKey,
+  splitRecipeKey,
+  type ParsedRef,
+  type RefReading,
+} from "./parse.js";
+import { RefSource } from "./scopes.js";
+
+/**
+ * The names that match a written one: those spelled exactly as written, or,
+ * when there is none, those that differ only in case.
+ *
+ * matchNames("Workflow", ["workflow", "tooling"]); // -> ["workflow"]
+ * matchNames("workflow", ["workflow", "Workflow"]); // -> ["workflow"]
+ *
+ * @param written - The name as written.
+ * @param names - The names it could mean.
+ */
+export function matchNames(written: string, names: Iterable<string>): string[] {
+  const all = [...names];
+  const exact = all.filter((name) => name === written);
+  if (exact.length > 0) return exact;
+  const folded = written.toLowerCase();
+  return all.filter((name) => name.toLowerCase() === folded);
+}
+
+/** What settling needs to know about one repository's index. */
+export type SettleIndex = {
+  /** Every namespace the index publishes. */
+  namespaces: Iterable<string>;
+  /** Every recipe it publishes, keyed `namespace/recipe`, with the folder it lives in. */
+  recipes: Record<string, { path: string }>;
+};
+
+/**
+ * What a reading names in one repository's index, spelled the way the index
+ * spells it. A named reading that the index does not publish settles to
+ * nothing; a browsed path settles through the recipe paths.
+ *
+ * settleInIndex({ namespace: "Workflow", recipe: "alpha" }, index);
+ * // -> [{ namespace: "workflow", recipe: "alpha" }]
+ *
+ * @param reading - One reading of a written ref.
+ * @param index - The index of the repository the reading points at.
+ */
+export function settleInIndex(reading: RefReading, index: SettleIndex): ParsedRef[] {
+  const carried = {
+    ...(reading.location === undefined ? {} : { location: reading.location }),
+    ...("range" in reading && reading.range !== undefined ? { range: reading.range } : {}),
+    ...("repo" in reading && reading.repo !== undefined ? { repo: reading.repo } : {}),
+  };
+
+  if (isBrowsedReading(reading)) {
+    return settleBrowsed(reading.browsed, index).map((settled) => ({ ...settled, ...carried }));
+  }
+  if (!isNamedReading(reading)) return [];
+
+  if (reading.recipe === undefined) {
+    return matchNames(reading.namespace, index.namespaces).map((namespace) => ({
+      namespace,
+      ...carried,
+    }));
+  }
+
+  return matchNames(refKey(reading), Object.keys(index.recipes)).map((key) => {
+    const { namespace, name } = splitRecipeKey(key);
+    return { namespace, recipe: name, ...carried };
+  });
+}
+
+/**
+ * What a browser path names, through the folder each recipe's index entry
+ * records. The path still carries the branch in front (which may itself hold
+ * slashes), so every split is tried: the folder of a recipe, or anything inside
+ * it, names that recipe; a folder holding recipes of exactly one namespace
+ * names that namespace.
+ *
+ * settleBrowsed("main/recipes/workflow/alpha/SKILL.md", index);
+ * // -> [{ namespace: "workflow", recipe: "alpha" }]
+ *
+ * @param browsed - The path after `tree/` or `blob/`, branch included.
+ * @param index - The repository's index.
+ */
+export function settleBrowsed(browsed: string, index: SettleIndex): ParsedRef[] {
+  const segments = browsed.split("/").filter((segment) => segment.length > 0);
+  const recipes = Object.entries(index.recipes).map(([key, entry]) => ({
+    key,
+    path: entry.path.replace(/^\.?\/+|\/+$/g, ""),
+  }));
+
+  const found = new Map<string, ParsedRef>();
+
+  // A recipe's folder, or a file inside it. The deepest recipe wins, so a
+  // recipe nested inside another's folder is named by its own path.
+  for (let start = 1; start < segments.length; start++) {
+    const folder = segments.slice(start).join("/");
+    const holding = recipes
+      .filter((recipe) => folder === recipe.path || folder.startsWith(`${recipe.path}/`))
+      .sort((left, right) => right.path.length - left.path.length);
+    const deepest = holding[0];
+    if (deepest !== undefined) {
+      const { namespace, name } = splitRecipeKey(deepest.key);
+      found.set(deepest.key, { namespace, recipe: name });
+    }
+  }
+  if (found.size > 0) return [...found.values()];
+
+  // A folder above recipes: a namespace, when everything under it is one.
+  for (let start = 1; start < segments.length; start++) {
+    const folder = segments.slice(start).join("/");
+    const under = recipes.filter((recipe) => recipe.path.startsWith(`${folder}/`));
+    const namespaces = new Set(under.map((recipe) => namespaceOfKey(recipe.key)));
+    if (namespaces.size === 1) {
+      const namespace = [...namespaces][0]!;
+      found.set(namespace, { namespace });
+    }
+  }
+  return [...found.values()];
+}
+
+/** What a repository's index recorded about one dependency, as far as settling needs. */
+export type RecordedDependencies = Record<string, { repo?: string } | undefined>;
+
+/**
+ * The readings of a manifest dependency that the declaring recipe's index
+ * confirms. 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 dependency that reads one way needs no record and comes back as it
+ * is.
+ *
+ * A named reading is confirmed by a record under its own key (or, for a whole
+ * namespace, under a key inside it) carrying its repository; a browsed reading
+ * by any record carrying its repository.
+ *
+ * @param readings - Every reading of the dependency, from `parseRef`.
+ * @param recorded - What the declaring version's index entry records, keyed `namespace/recipe`.
+ * @returns The confirmed readings: one is the answer; none or several leave it unsettled.
+ */
+export function confirmedReadings(
+  readings: RefReading[],
+  recorded: RecordedDependencies | undefined
+): RefReading[] {
+  if (readings.length === 1) return readings;
+  const records = Object.entries(recorded ?? {});
+
+  return readings.filter((reading) => {
+    const identity = reading.location?.identity;
+    if (identity === undefined) return false;
+    return records.some(([key, record]) => {
+      if (record?.repo !== identity) return false;
+      if (isBrowsedReading(reading)) return true;
+      if (!isNamedReading(reading)) return false;
+      return reading.recipe === undefined
+        ? key.startsWith(`${reading.namespace}/`)
+        : key === refKey(reading);
+    });
+  });
+}
+
+/** What `settleDependency` may consult, beyond the dependency itself. */
+export type SettleDependencyOptions = {
+  /** What the declaring version's index entry records about its dependencies. */
+  recorded?: RecordedDependencies;
+  /**
+   * Whether a reading is already known to be right from what is on this
+   * machine: its repository is trusted and its cached index publishes what it
+   * names. Used only when the index recorded nothing, and it never fetches.
+   */
+  known?: (reading: RefReading) => boolean;
+};
+
+/**
+ * The one reading a manifest dependency settles on, or undefined when it reads
+ * more than one way and nothing at hand says which: the declaring recipe's
+ * index recorded no answer, and what this machine already knows does not pick
+ * exactly one.
+ *
+ * settleDependency("workflow/alpha");
+ * // -> { namespace: "workflow", recipe: "alpha" }
+ *
+ * @param written - The dependency as the manifest wrote it.
+ * @param options - The index's record, and what is known locally.
+ */
+export function settleDependency(
+  written: string,
+  options: SettleDependencyOptions = {}
+): RefReading | undefined {
+  const readings = parseRef(written, RefSource.Manifest);
+  if (readings.length === 1) return readings[0];
+
+  const confirmed = confirmedReadings(readings, options.recorded);
+  if (confirmed.length === 1) return confirmed[0];
+
+  if (options.known !== undefined) {
+    const known = readings.filter(options.known);
+    if (known.length === 1) return known[0];
+  }
+  return undefined;
+}

package/src/lib/repos/catalog.ts

@@ -8,11 +8,12 @@
  * This module answers all four.
  *
  * Everything here is a pure function over data the caller hands it: the cached
- * indexes, the lockfile, and the subscription keys the project declares. A
- * recipe's own manifest (its variables, its declared dependencies and the
- * content it contributes) lives inside the recipe's files rather than in the
- * index, so the caller supplies a reader for it; a recipe whose files are not on
- * this machine is described from its index alone rather than being an error.
+ * indexes, the lockfile, and the subscription keys the project declares. The
+ * content a recipe contributes is known only from its own manifest, inside the
+ * recipe's files, so the caller supplies a reader for it; a recipe whose files
+ * are not on this machine is described from its index alone rather than being
+ * an error, and an index recorded by a current release says how each of its
+ * dependencies was declared.
  *
  * Refs resolve the way `sous subscribe` resolves them: `namespace`,
  * `namespace/recipe`, and either of those qualified with `repo:`. A one-word ref
@@ -24,13 +25,17 @@ import semver from "semver";
 import { ConfigError } from "../errors.js";
 import type { IndexDependency, IndexFile } from "./formats/index-file.js";
 import type { Lockfile } from "./formats/lockfile.js";
-import type {
-  ContentKind,
-  RecipeManifest,
-  VariableDefinition,
-} from "./formats/recipe-manifest.js";
-import { dependencyRefKey, parseDependencyRef, parseRef, type ParsedRef } from "./ref.js";
-import { bareName } from "../vars/names.js";
+import type { ContentKind, RecipeManifest } from "./formats/recipe-manifest.js";
+import {
+  isNamedReading,
+  namespaceOfKey,
+  parseRef,
+  refKey,
+  splitRecipeKey,
+  type ParsedRef,
+} from "../refs/parse.js";
+import { settleDependency } from "../refs/settle.js";
+import { declarationFor, type DependencyLists } from "./declarations.js";
 import {
   describeReference,
   findNamespace,
@@ -166,9 +171,13 @@ export type RecipeVersionListing = {
 export type RecipeDependencyListing = {
   /** The recipe key the dependency names, `namespace/recipe`. */
   key: string;
-  /** The dependency exactly as the recipe's manifest wrote it, when it could be read. */
+  /**
+   * The manifest entry that brings it in, exactly as written (a recipe, a whole
+   * namespace, or a locator), from the index when it records one and from the
+   * manifest otherwise.
+   */
   declared?: string;
-  /** Whether the manifest declared it a build dependency or a co-subscription. */
+  /** Whether that entry makes it a build dependency or a co-subscription. */
   kind?: "depends" | "subscribes";
   /** The exact version the release resolved it to, when the index records one. */
   resolvedVersion?: string;
@@ -178,22 +187,6 @@ export type RecipeDependencyListing = {
   repo?: string;
 };
 
-/** One variable a recipe asks about. */
-export type RecipeVariableListing = {
-  /** The variable's name, as the manifest declares it. */
-  name: string;
-  /** The type of answer it takes. */
-  type: string;
-  /** The environment variable an answer is stored under. */
-  env: string;
-  /** True when an answer is required before the recipe is usable. */
-  required: boolean;
-  /** True when the answer is a secret, which sous never prints. */
-  secret: boolean;
-  /** The one-line question it asks. */
-  prompt: string;
-};
-
 /** One content kind a recipe contributes, and where its files would land. */
 export type RecipeContentListing = {
   /** The content kind, as the manifest declares it. */
@@ -238,14 +231,18 @@ export type RecipeDetail = {
   versions: RecipeVersionListing[];
   /** What the described version depends on, by key. */
   dependencies: RecipeDependencyListing[];
-  /** The variables the recipe declares, in manifest order. */
-  variables: RecipeVariableListing[];
+  /**
+   * True when the index records the described version's dependencies, even as
+   * none at all, so an empty list means "depends on nothing" rather than "not
+   * recorded".
+   */
+  dependenciesRecorded: boolean;
   /** What the recipe contributes, and where each kind's files land. */
   contents: RecipeContentListing[];
   /**
    * True when the recipe's own manifest could be read. When it is false, the
-   * variables, the declared dependencies and the contents are unknown rather
-   * than empty, because the recipe's files are not on this machine.
+   * contents are unknown rather than empty, because the recipe's files are not
+   * on this machine.
    */
   manifestRead: boolean;
 };
@@ -360,7 +357,7 @@ export function describeRecipe(inputs: CatalogInputs, ref: string): RecipeDetail
     ...(describing === undefined ? {} : { describing }),
     versions: versionListings(entry.versions, listing.latest, listing.pinned),
     dependencies: dependencyListings(published?.dependencies, manifest),
-    variables: (manifest?.variables ?? []).map(variableListing),
+    dependenciesRecorded: published?.dependencies !== undefined,
     contents: (manifest?.contents ?? []).map((content) => ({
       kind: content.kind,
       include: [...content.include],
@@ -390,7 +387,7 @@ export function narrowToInstalled(inputs: CatalogInputs): CatalogInputs {
         ([key]) => inputs.lock.recipes[key]?.repo === repo.name
       )
     );
-    const held = new Set(Object.keys(recipes).map((key) => key.slice(0, key.indexOf("/"))));
+    const held = new Set(Object.keys(recipes).map(namespaceOfKey));
     const namespaces = Object.fromEntries(
       Object.entries(repo.index.namespaces).filter(([namespace]) => held.has(namespace))
     );
@@ -468,16 +465,16 @@ export type ResolvedRecipeRef = {
  * @param ref - The namespace, optionally qualified with `repo:`.
  */
 export function resolveNamespaceRef(inputs: CatalogInputs, ref: string): ResolvedNamespace {
-  const parsed = parseRef(ref);
+  const { parsed, search } = readCommandLineRef(ref);
 
-  if (parsed.recipe !== undefined) {
+  if (parsed?.recipe !== undefined) {
     throw new ConfigError(
       `'${ref}' names the recipe '${parsed.recipe}', not a namespace.\n` +
         `  The namespace it belongs to is '${parsed.namespace}'.`
     );
   }
 
-  const matches = findNamespace(refSearchString(parsed), referenceContext(inputs));
+  const matches = findNamespace(search, referenceContext(inputs));
 
   if (matches.length === 1) {
     return { repo: repoNamed(inputs, matches[0]!.repo!), namespace: matches[0]!.namespace! };
@@ -485,8 +482,8 @@ export function resolveNamespaceRef(inputs: CatalogInputs, ref: string): Resolve
 
   if (matches.length > 1) throw ambiguousError(ref, "namespace", matches);
 
-  const asRecipe = findRecipe(refSearchString(parsed), referenceContext(inputs));
-  if (parsed.repo === undefined && asRecipe.length > 0) {
+  const asRecipe = findRecipe(search, referenceContext(inputs));
+  if (parsed !== undefined && parsed.repo === undefined && asRecipe.length > 0) {
     throw new ConfigError(
       `No repository this project trusts publishes a namespace called ` +
         `'${parsed.namespace}'.\n` +
@@ -495,7 +492,7 @@ export function resolveNamespaceRef(inputs: CatalogInputs, ref: string): Resolve
     );
   }
 
-  throw unknownError(inputs, ref, "namespace", parsed.repo);
+  throw unknownError(inputs, ref, "namespace", parsed?.repo);
 }
 
 /**
@@ -507,8 +504,7 @@ export function resolveNamespaceRef(inputs: CatalogInputs, ref: string): Resolve
  * @param ref - The recipe, as `namespace/recipe`, a bare recipe name, or either qualified with `repo:`.
  */
 export function resolveRecipeRef(inputs: CatalogInputs, ref: string): ResolvedRecipeRef {
-  const parsed = parseRef(ref);
-  const search = refSearchString(parsed);
+  const { parsed, search } = readCommandLineRef(ref);
   const context = referenceContext(inputs);
 
   const matches = findRecipe(search, context);
@@ -529,13 +525,13 @@ export function resolveRecipeRef(inputs: CatalogInputs, ref: string): ResolvedRe
   if (asNamespace.length > 0) {
     throw new ConfigError(
       `No repository this project trusts publishes a recipe called ` +
-        `'${parsed.namespace}'.\n` +
+        `'${parsed?.namespace ?? ref}'.\n` +
         `  It is the name of a namespace:\n` +
         asNamespace.map((candidate) => `    ${describeReference(candidate)}`).join("\n")
     );
   }
 
-  throw unknownError(inputs, ref, "recipe", parsed.repo);
+  throw unknownError(inputs, ref, "recipe", parsed?.repo);
 }
 
 // --- The pieces ---------------------------------------------------------------------------------
@@ -543,7 +539,7 @@ export function resolveRecipeRef(inputs: CatalogInputs, ref: string): ResolvedRe
 /** Every recipe key one index publishes in one namespace, sorted. */
 function recipeKeysIn(index: IndexFile, namespace: string): string[] {
   return Object.keys(index.recipes)
-    .filter((key) => key.slice(0, key.indexOf("/")) === namespace)
+    .filter((key) => namespaceOfKey(key) === namespace)
     .sort();
 }
 
@@ -583,8 +579,7 @@ function recipeListing(
 ): RecipeListing {
   const lock = inputs.lock;
   const entry = repo.index.recipes[key]!;
-  const namespace = key.slice(0, key.indexOf("/"));
-  const name = key.slice(namespace.length + 1);
+  const { namespace, name } = splitRecipeKey(key);
   const latest = latestVersion(Object.keys(entry.versions), entry.versions);
 
   // A locked entry pins one recipe from one repository. Two repositories can
@@ -674,27 +669,50 @@ function dependencyListings(
   manifest: RecipeManifest | undefined
 ): RecipeDependencyListing[] {
   const rows = new Map<string, RecipeDependencyListing>();
+  const lists: DependencyLists | undefined =
+    manifest === undefined
+      ? undefined
+      : { depends: manifest.depends ?? [], subscribes: manifest.subscribes ?? [] };
 
   for (const [key, entry] of Object.entries(resolved ?? {})) {
+    // The index says how the release that published the version saw it. An
+    // entry recorded before the index said so is answered from the manifest,
+    // by the same rule the release applies.
+    const declaration =
+      entry.declared !== undefined && entry.kind !== undefined
+        ? { declared: entry.declared, kind: entry.kind }
+        : lists === undefined
+          ? undefined
+          : declarationFor(lists, key, resolved);
     rows.set(key, {
       key,
       ...(entry.version === undefined ? {} : { resolvedVersion: entry.version }),
       ...(entry.range === undefined ? {} : { resolvedRange: entry.range }),
       ...(entry.repo === undefined ? {} : { repo: entry.repo }),
+      ...(declaration ?? {}),
     });
   }
 
+  // A manifest entry that covers no row the index recorded is still shown, so a
+  // reader sees everything the manifest declares.
+  const covered = new Set([...rows.values()].map((row) => row.declared));
   for (const [kind, declared] of [
-    ["depends", manifest?.depends ?? []],
-    ["subscribes", manifest?.subscribes ?? []],
+    ["depends", lists?.depends ?? []],
+    ["subscribes", lists?.subscribes ?? []],
   ] as Array<["depends" | "subscribes", string[]]>) {
     for (const written of declared) {
-      let key: string;
+      if (covered.has(written.trim())) continue;
+      // A dependency that reads more than one way is listed under the key the
+      // index recorded for it. One sous cannot parse or settle is still worth
+      // showing; it is listed under what it was written as, so the reader sees
+      // the entry as it stands.
+      let key = written;
       try {
-        key = dependencyRefKey(parseDependencyRef(written));
+        const reading = settleDependency(written, {
+          ...(resolved === undefined ? {} : { recorded: resolved }),
+        });
+        if (reading !== undefined && isNamedReading(reading)) key = refKey(reading);
       } catch {
-        // A manifest sous cannot parse is still worth showing; it is listed
-        // under what it was written as, so the reader sees the bad entry.
         key = written;
       }
       rows.set(key, { ...(rows.get(key) ?? { key }), declared: written, kind });
@@ -704,25 +722,6 @@ function dependencyListings(
   return [...rows.values()].sort((left, right) => compare(left.key, right.key));
 }
 
-/**
- * One variable row: what it is called, what kind of answer it takes, and the
- * environment variable an answer is stored under.
- *
- * @param definition - The variable definition from the recipe's manifest.
- */
-function variableListing(definition: VariableDefinition): RecipeVariableListing {
-  return {
-    name: definition.name,
-    type: definition.type,
-    // The manifest may bind an existing environment variable; otherwise the
-    // answer is stored under the name sous derives from the variable's own.
-    env: bareName(definition),
-    required: definition.required,
-    secret: definition.secret,
-    prompt: definition.prompt,
-  };
-}
-
 /**
  * The repository a match named. Every match comes from this catalog's own
  * repositories, so the lookup always finds one.
@@ -746,14 +745,22 @@ function referenceContext(inputs: CatalogInputs): ReferenceContext {
 }
 
 /**
- * A parsed ref written back out as a reference, without its version range: the
- * range says which version to use, never which thing is meant.
+ * A ref from the command line, checked by the one parser, and the spelling to
+ * search for: a short ref written back without its version range (the range
+ * says which version to use, never which thing is meant), or a location
+ * exactly as written, which the search settles through the repository's index.
  *
- * @param parsed - The parsed ref.
+ * @param ref - The ref as typed.
+ * @returns The short reading, when the ref was short, and the search term.
  */
-function refSearchString(parsed: ParsedRef): string {
-  const path = parsed.recipe === undefined ? parsed.namespace : `${parsed.namespace}/${parsed.recipe}`;
-  return parsed.repo === undefined ? path : `${parsed.repo}:${path}`;
+function readCommandLineRef(ref: string): { parsed?: ParsedRef; search: string } {
+  const readings = parseRef(ref);
+  const first = readings[0]!;
+  if (first.location !== undefined || !isNamedReading(first)) return { search: ref.trim() };
+  return {
+    parsed: first,
+    search: first.repo === undefined ? refKey(first) : `${first.repo}:${refKey(first)}`,
+  };
 }
 
 /** The error a ref that could have meant several things raises. */