@sous-io/sous 0.2.29 → 0.2.31

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,11 +25,7 @@ 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 type { ContentKind, RecipeManifest } from "./formats/recipe-manifest.js";
 import {
   isNamedReading,
   namespaceOfKey,
@@ -38,7 +35,7 @@ import {
   type ParsedRef,
 } from "../refs/parse.js";
 import { settleDependency } from "../refs/settle.js";
-import { bareName } from "../vars/names.js";
+import { declarationFor, type DependencyLists } from "./declarations.js";
 import {
   describeReference,
   findNamespace,
@@ -174,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;
@@ -186,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. */
@@ -246,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;
 };
@@ -368,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],
@@ -680,21 +669,39 @@ 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) {
+      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
@@ -715,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.

package/src/lib/repos/declarations.ts

@@ -0,0 +1,177 @@
+/**
+ * How one recipe brings in another: which entry of its manifest names it, and
+ * whether that entry is a co-subscription or a build dependency.
+ *
+ * A manifest lists what it brings in under `depends` and `subscribes`, and one
+ * recipe can be covered by more than one entry: `subscribes: [workflow]` covers
+ * every recipe of the `workflow` namespace, and `depends: [workflow/task-files]`
+ * names one of them again. Three places need one answer per recipe, and they
+ * must agree: a release recording the answer in the index, `sous recipe show`
+ * describing a recipe whose manifest it can read, and the resolver walking a
+ * recipe whose manifest it cannot. This module is that one answer, and its
+ * reverse.
+ */
+
+import type { DependencyKind } from "./formats/common.js";
+import type { IndexVersion } from "./formats/index-file.js";
+import { isNamedReading, namespaceOfKey, parseRef, refKey } from "../refs/parse.js";
+import { RefSource } from "../refs/scopes.js";
+import { settleDependency, type RecordedDependencies } from "../refs/settle.js";
+
+/** A manifest's two dependency lists, each entry exactly as it was written. */
+export type DependencyLists = {
+  /** Build dependencies: fetched and addressable, never in the project's output. */
+  depends: string[];
+  /** Co-subscriptions: their files land and their questions are asked. */
+  subscribes: string[];
+};
+
+/** How one recipe is brought in by the manifest that declares it. */
+export type DependencyDeclaration = {
+  /**
+   * The manifest entry that brings it in, as written. An entry naming the
+   * recipe wins over a namespace entry that also covers it; between two
+   * entries naming it, the later one (in `depends`, then `subscribes` order)
+   * wins, and between two namespace entries, the first.
+   */
+  declared: string;
+  /** `subscribes` when any entry covering the recipe is a co-subscription. */
+  kind: DependencyKind;
+};
+
+/** A declaration being gathered, entry by entry. */
+export type GatheredDeclaration = DependencyDeclaration & {
+  /** True when an entry named the recipe itself rather than its namespace. */
+  named: boolean;
+};
+
+/** One manifest entry covering a recipe. */
+export type CoveringEntry = {
+  /** The entry as written. */
+  written: string;
+  /** The list it sits in. */
+  kind: DependencyKind;
+  /** True when it names the recipe itself rather than a namespace holding it. */
+  named: boolean;
+};
+
+/**
+ * Folds one more manifest entry covering a recipe into what is known about the
+ * recipe's declaration, by the rule `DependencyDeclaration` states. Every
+ * reader applies this one function, entry by entry in manifest order
+ * (`depends` first, then `subscribes`).
+ *
+ * foldDeclaration(undefined, { written: "workflow", kind: "subscribes", named: false })
+ * // -> { declared: "workflow", kind: "subscribes", named: false }
+ *
+ * @param before - What the earlier entries said, when any covered the recipe.
+ * @param entry - The next entry covering it.
+ */
+export function foldDeclaration(
+  before: GatheredDeclaration | undefined,
+  entry: CoveringEntry
+): GatheredDeclaration {
+  const keepBefore = before !== undefined && !entry.named;
+  return {
+    declared: keepBefore ? before.declared : entry.written.trim(),
+    kind: before?.kind === "subscribes" || entry.kind === "subscribes" ? "subscribes" : "depends",
+    named: entry.named || before?.named === true,
+  };
+}
+
+/**
+ * The declaration that brings one recipe in, or undefined when no entry of the
+ * lists covers it. An entry that reads more than one way is settled from what
+ * the version's index entry recorded, and one that cannot be settled, or does
+ * not parse, covers nothing.
+ *
+ * declarationFor({ depends: ["workflow/a"], subscribes: ["workflow"] }, "workflow/a")
+ * // -> { declared: "workflow/a", kind: "subscribes" }
+ *
+ * @param lists - The declaring recipe's `depends` and `subscribes` lists.
+ * @param key - The recipe being asked about, `namespace/recipe`.
+ * @param recorded - What the declaring version's index entry records, for settling.
+ */
+export function declarationFor(
+  lists: Partial<DependencyLists>,
+  key: string,
+  recorded?: RecordedDependencies
+): DependencyDeclaration | undefined {
+  let gathered: GatheredDeclaration | undefined;
+
+  for (const [kind, entries] of [
+    ["depends", lists.depends ?? []],
+    ["subscribes", lists.subscribes ?? []],
+  ] as Array<[DependencyKind, string[]]>) {
+    for (const written of entries) {
+      let reading;
+      try {
+        reading = settleDependency(written, recorded === undefined ? {} : { recorded });
+      } catch {
+        // An entry that does not parse is reported wherever the manifest is
+        // validated; here it simply covers nothing.
+        continue;
+      }
+      if (reading === undefined || !isNamedReading(reading)) continue;
+
+      const named = reading.recipe !== undefined;
+      const covers = named ? refKey(reading) === key : namespaceOfKey(key) === reading.namespace;
+      if (covers) gathered = foldDeclaration(gathered, { written, kind, named });
+    }
+  }
+
+  return gathered === undefined ? undefined : { declared: gathered.declared, kind: gathered.kind };
+}
+
+/**
+ * The manifest lists a version's index entry records, or undefined when it
+ * records neither (a version recorded before the index described recipes).
+ * That is what lets the resolver walk a recipe whose files are not on this
+ * machine exactly as it would walk its manifest.
+ *
+ * indexDependencyLists({ subscribes: ["workflow"], depends: [] , ... })
+ * // -> { depends: [], subscribes: ["workflow"] }
+ *
+ * @param version - The version's index entry.
+ */
+export function indexDependencyLists(
+  version: Pick<IndexVersion, "depends" | "subscribes">
+): DependencyLists | undefined {
+  if (version.depends === undefined && version.subscribes === undefined) return undefined;
+  return { depends: [...(version.depends ?? [])], subscribes: [...(version.subscribes ?? [])] };
+}
+
+/**
+ * Says how a declaration brings a recipe in, the way a person would: a whole
+ * namespace is named as one, and anything else is shown as it was written.
+ *
+ * describeDeclaration("workflow")             // -> "the whole 'workflow' namespace"
+ * describeDeclaration("workflow/task-files")  // -> "workflow/task-files"
+ *
+ * @param declared - The manifest entry, as written.
+ */
+export function describeDeclaration(declared: string): string {
+  try {
+    const readings = parseRef(declared, RefSource.Manifest);
+    const only = readings[0]!;
+    if (readings.length === 1 && isNamedReading(only) && only.recipe === undefined) {
+      return only.location === undefined
+        ? `the whole '${only.namespace}' namespace`
+        : `the whole '${only.namespace}' namespace of ${only.location.identity}`;
+    }
+  } catch {
+    // Shown as it was written; the reader sees the bad entry.
+  }
+  return declared;
+}
+
+/**
+ * Plain-language wording for a dependency kind.
+ *
+ * @param kind - The kind, when it is known.
+ */
+export function describeDependencyKind(kind: DependencyKind | undefined): string {
+  if (kind === "depends") return "build dependency";
+  if (kind === "subscribes") return "co-subscription";
+  return "not recorded";
+}

package/src/lib/repos/formats/common.ts

@@ -161,6 +161,20 @@ export const recipeKeySchema = z
       "(for example 'workflow/task-files')"
   );
 
+/**
+ * The two ways one recipe can bring in another, named after the manifest lists
+ * that declare them: `subscribes` is a co-subscription, whose files land in the
+ * project and whose questions are asked; `depends` is a build dependency, a
+ * library whose files never reach the project's output.
+ */
+export const DEPENDENCY_KINDS = ["subscribes", "depends"] as const;
+
+/** A co-subscription or a build dependency. */
+export const dependencyKindSchema = z.enum(DEPENDENCY_KINDS);
+
+/** A co-subscription or a build dependency. */
+export type DependencyKind = (typeof DEPENDENCY_KINDS)[number];
+
 // --- Value primitives ---------------------------------------------------------------------------
 
 /** An exact semantic version, as published by a recipe. */

package/src/lib/repos/formats/index-file.ts

@@ -18,6 +18,7 @@
 import { z } from "zod";
 import {
   contentHashSchema,
+  dependencyKindSchema,
   formatVersionSchema,
   forwardCompatibleObject,
   isoTimestampSchema,
@@ -31,6 +32,7 @@ import {
   semverVersionSchema,
   stableJsonStringify,
 } from "./common.js";
+import { publishedVariableDefinitionSchema } from "./variable-definition.js";
 import { namespaceOfKey } from "../../refs/parse.js";
 
 /**
@@ -55,6 +57,22 @@ export const indexDependencySchema = forwardCompatibleObject({
    * this same repository.
    */
   repo: repoIdentitySchema.optional(),
+  /**
+   * The entry of the version's manifest that brings this dependency in, exactly
+   * as it was written: a recipe (`workflow/task-files`, with its range when it
+   * has one), a whole namespace of this repository (`workflow`), or a locator
+   * naming a recipe in another repository. When several entries cover the same
+   * recipe, the one naming it wins over a namespace. Absent on an entry recorded
+   * before sous described recipes in the index (ADR 0010).
+   */
+  declared: z.string().min(1, "must not be empty").optional(),
+  /**
+   * Whether that brings it in as a co-subscription (`subscribes`: its files
+   * land in the project and its questions are asked) or as a build dependency
+   * (`depends`: a library only); `subscribes` when any entry covering it is a
+   * co-subscription. Recorded alongside `declared`.
+   */
+  kind: dependencyKindSchema.optional(),
 }).refine((entry) => entry.version !== undefined || entry.range !== undefined, {
   message:
     "must record either the exact version this dependency resolved to or the range " +
@@ -93,9 +111,30 @@ export const indexVersionSchema = forwardCompatibleObject({
    * published version means one thing forever.
    *
    * The field is additive: an index written before it existed still parses, and
-   * a consumer that finds no entry falls back to the manifest's ranges.
+   * a consumer that finds no entry falls back to the manifest's ranges. A
+   * version described in full (ADR 0010) carries this field even when it is
+   * empty, so "depends on nothing" and "not recorded" read differently.
    */
   dependencies: z.record(recipeKeySchema, indexDependencySchema).optional(),
+  /**
+   * The variable definitions this version's manifest publishes, in manifest
+   * order: the questions subscribing to it asks. An empty list means it asks
+   * none; an absent field means the release that recorded the version did not
+   * record them (a release made before ADR 0010), and only the recipe's own
+   * files can say.
+   */
+  variables: z.array(publishedVariableDefinitionSchema).optional(),
+  /**
+   * The version's manifest `depends` and `subscribes` lists, exactly as
+   * written, so a consumer walks a recipe whose files it has not fetched the
+   * same way it walks its manifest: a namespace still expands to what the
+   * namespace holds, including a namespace of another repository, which no
+   * key of `dependencies` can record. Written, even when empty, beside
+   * `variables`; absent on a version recorded before ADR 0010. Kept as plain
+   * strings, so a ref form a later sous accepts never breaks this reader.
+   */
+  depends: z.array(z.string().min(1, "must not be empty")).optional(),
+  subscribes: z.array(z.string().min(1, "must not be empty")).optional(),
 });
 
 /** One recipe, with every version the repo publishes of it. */

package/src/lib/repos/formats/lockfile.ts

@@ -30,13 +30,15 @@ import {
   repoUrlSchema,
   semverVersionSchema,
   stableJsonStringify,
+  DEPENDENCY_KINDS,
+  type DependencyKind,
 } from "./common.js";
 
 /** The literal `requestedBy` holder meaning "the project subscribed to this directly". */
 export const PROJECT_HOLDER = "project";
 
-/** How a locked recipe entered the project. */
-export const LOCK_KINDS = ["subscribes", "depends"] as const;
+/** How a locked recipe entered the project: the dependency kinds every format shares. */
+export const LOCK_KINDS = DEPENDENCY_KINDS;
 
 /** One repo the project resolves against. */
 export const lockedRepoSchema = z
@@ -138,7 +140,7 @@ export type LockedRepo = z.infer<typeof lockedRepoSchema>;
 export type LockedRecipe = z.infer<typeof lockedRecipeSchema>;
 
 /** How a locked recipe entered the project. */
-export type LockKind = (typeof LOCK_KINDS)[number];
+export type LockKind = DependencyKind;
 
 /**
  * Validates a parsed lockfile, throwing a ConfigError that names the file and