@sous-io/sous 0.2.28 → 0.2.30

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,8 @@ import {
   semverVersionSchema,
   stableJsonStringify,
 } from "./common.js";
+import { publishedVariableDefinitionSchema } from "./variable-definition.js";
+import { namespaceOfKey } from "../../refs/parse.js";
 
 /**
  * One dependency of one published version, as the release resolved it.
@@ -54,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 " +
@@ -92,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. */
@@ -142,7 +182,7 @@ export const indexFileSchema = forwardCompatibleObject({
   // A recipe whose namespace is not declared could never be resolved, so a
   // release that produced one is broken; say which recipe and which namespace.
   for (const key of Object.keys(index.recipes)) {
-    const namespace = key.slice(0, key.indexOf("/"));
+    const namespace = namespaceOfKey(key);
     if (!Object.hasOwn(index.namespaces, namespace)) {
       ctx.addIssue({
         code: "custom",

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

package/src/lib/repos/formats/recipe-manifest.ts

@@ -15,18 +15,19 @@
  *   its files DO enter the output. A curated bundle is simply a recipe made
  *   mostly of `subscribes` entries.
  *
- * Both lists name their targets BY LOCATION, in one of two spellings:
+ * Both lists name their targets BY LOCATION:
  *
  *     workflow/sat                                  a sibling in this repository
  *     github://sous-io/sous-recipes/workflow/sat    a recipe in another one
  *
- * A short name such as `sous-recipes:` is a consuming project's own label, so
- * it never appears in a published manifest; see `parseDependencyRef`.
+ * Every other location form works too (an HTTPS or SSH URL, a browser URL); a
+ * short name such as `sous-recipes:` is a consuming project's own label, so it
+ * never appears in a published manifest. See `parseRef` with
+ * `RefSource.Manifest`.
  */
 
 import { z } from "zod";
 import {
-  envVarNameSchema,
   extensibleObject,
   formatVersionSchema,
   namespaceNameSchema,
@@ -35,22 +36,27 @@ import {
   relativePathSchema,
   semverVersionSchema,
   submissionsSchema,
-  variableNameSchema,
 } from "./common.js";
-import { parseDependencyRef } from "../ref.js";
+import { parseRef } from "../../refs/parse.js";
+import { RefSource } from "../../refs/scopes.js";
+import { variableDefinitionSchema } from "./variable-definition.js";
+
+// Variable definitions live in their own module, so the index can read them
+// without importing the ref parser this manifest needs; they are re-exported
+// here because a definition is part of the manifest.
+export * from "./variable-definition.js";
 
 // --- Dependency refs ----------------------------------------------------------------------------
 
 /**
- * A dependency in `depends` or `subscribes`, in either of the two spellings a
- * manifest may use: a bare ref naming a recipe in this same repository, or a
- * locator URL naming one in another repository. Parsed with the real parser so
+ * A dependency in `depends` or `subscribes`: a bare ref naming a recipe in this
+ * same repository, or a location naming one in another repository. Parsed with the real parser so
  * a manifest and the rest of sous never disagree about what a dependency means;
  * the parser's message is carried through as the zod issue message.
  */
 const dependencyRefSchema = z.string().superRefine((value, ctx) => {
   try {
-    parseDependencyRef(value);
+    parseRef(value, RefSource.Manifest);
   } catch (error) {
     ctx.addIssue({ code: "custom", message: (error as Error).message });
   }
@@ -95,196 +101,6 @@ export const recipeContentSchema = extensibleObject({
   exclude: z.array(relativePathSchema("an exclude pattern", true)).optional(),
 });
 
-// --- Variable definitions -----------------------------------------------------------------------
-
-/** The value types a recipe may declare for a variable. */
-export const VARIABLE_TYPES = [
-  "string",
-  "number",
-  "boolean",
-  "enum",
-  "path",
-  "url",
-] as const;
-
-/** Which env file an answer is written to. */
-export const VARIABLE_SCOPES = ["shared", "local"] as const;
-
-/** Constraints checked against an answer before it is accepted or stored. */
-export const variableValidationSchema = extensibleObject({
-  /** A regular expression the answer must match, as a string. */
-  pattern: z
-    .string()
-    .refine(
-      (value) => {
-        try {
-          new RegExp(value);
-          return true;
-        } catch {
-          return false;
-        }
-      },
-      { message: "must be a valid regular expression" }
-    )
-    .optional(),
-  /** Minimum length of a string answer. */
-  minLength: z.number().int().min(0).optional(),
-  /** Maximum length of a string answer. */
-  maxLength: z.number().int().min(0).optional(),
-  /** Minimum value of a numeric answer. */
-  min: z.number().optional(),
-  /** Maximum value of a numeric answer. */
-  max: z.number().optional(),
-  /** The allowed answers. Required when the variable's type is 'enum'. */
-  enum: z.array(z.string()).min(1, "must list at least one option").optional(),
-});
-
-/**
- * A published variable definition: a specification, not a value. Definitions
- * are inert; a question is asked only when a subscribed recipe needs the
- * variable and no valid answer is already in scope.
- */
-export const variableDefinitionSchema = extensibleObject({
-  /** The variable's camelCase name, as templates refer to it. */
-  name: variableNameSchema,
-  /**
-   * The environment variable an answer binds to. Authors may name an existing
-   * variable such as GITHUB_TOKEN to reuse a value already in the environment.
-   * When omitted, `sous repo release` derives an upper snake case default from
-   * the name; the runtime never derives one.
-   */
-  env: envVarNameSchema.optional(),
-  /** The answer's type, which decides how it is validated and prompted for. */
-  type: z.enum(VARIABLE_TYPES),
-  /** The one-line question shown when the variable is asked. */
-  prompt: z.string().min(1, "must not be empty"),
-  /**
-   * The paragraph that explains the variable: what it is for, what a good
-   * answer looks like, and what changes when it is set. Shown above the
-   * question when sous asks, and by `sous vars <name>`. Required, because a
-   * consumer reading the question has no other way to learn what a publisher
-   * meant by it.
-   */
-  description: z
-    .string({
-      error:
-        "is required: every published variable must explain itself in a sentence or " +
-        "two. The description is shown above the question when sous asks, and by " +
-        "'sous vars <name>'",
-    })
-    .min(1, "must not be empty"),
-  /**
-   * A realistic sample answer. It is documentation and prompt copy only; sous
-   * never stores it, never offers it as the answer, and never falls back to it.
-   * Use `default` for a value a project should actually start with.
-   */
-  example: z.union([z.string(), z.number(), z.boolean()], {
-    error:
-      "is required: every published variable must show what a real answer looks like. " +
-      "The example is shown with the question and by 'sous vars <name>'; it is " +
-      "documentation only and is never stored as the answer (use 'default' for that)",
-  }),
-  /** The value offered when the question is asked with nothing else in scope. */
-  default: z.union([z.string(), z.number(), z.boolean()]).optional(),
-  /** Whether an answer is needed for a build to run. Defaults to true. */
-  required: z.boolean().default(true),
-  /**
-   * Whether the answer is a secret. A secret is always written to the
-   * gitignored `.sous/.env.local`, never to the committed `.sous/.env`.
-   */
-  secret: z.boolean().default(false),
-  /**
-   * Which env file the answer is written to: 'shared' is `.sous/.env`, which is
-   * committed and shared with the team; 'local' is `.sous/.env.local`, which is
-   * gitignored and machine-specific. Defaults to 'shared'.
-   */
-  scope: z.enum(VARIABLE_SCOPES).default("shared"),
-  /** Constraints checked against an answer. */
-  validate: variableValidationSchema.optional(),
-})
-  .superRefine((definition, ctx) => {
-    const { type, validate } = definition;
-
-    if (type === "enum" && (validate?.enum === undefined || validate.enum.length === 0)) {
-      ctx.addIssue({
-        code: "custom",
-        path: ["validate", "enum"],
-        message:
-          "a variable of type 'enum' must list its options under 'validate.enum'",
-      });
-    }
-
-    if (validate !== undefined) {
-      const { minLength, maxLength, min, max } = validate;
-      if (minLength !== undefined && maxLength !== undefined && minLength > maxLength) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["validate", "maxLength"],
-          message: "must not be smaller than 'validate.minLength'",
-        });
-      }
-      if (min !== undefined && max !== undefined && min > max) {
-        ctx.addIssue({
-          code: "custom",
-          path: ["validate", "max"],
-          message: "must not be smaller than 'validate.min'",
-        });
-      }
-    }
-
-    // A secret written to the committed env file would leak, so the two fields
-    // are not allowed to contradict each other.
-    if (definition.secret && definition.scope === "shared") {
-      ctx.addIssue({
-        code: "custom",
-        path: ["scope"],
-        message:
-          "a secret variable is stored in the gitignored '.sous/.env.local', so its " +
-          "scope must be 'local' (or left unset)",
-      });
-    }
-
-    // `default` and `example` are both literal values written by the publisher,
-    // so both have to fit the variable they describe; an example that could
-    // never be a valid answer is worse than no example at all.
-    checkDeclaredValue(definition.default, "default");
-    checkDeclaredValue(definition.example, "example");
-
-    /**
-     * Checks one publisher-written literal against the declared type and the
-     * 'validate.enum' options.
-     *
-     * @param value - The literal to check, or undefined when it was omitted.
-     * @param field - The field name, used as the issue path.
-     */
-    function checkDeclaredValue(
-      value: string | number | boolean | undefined,
-      field: "default" | "example"
-    ): void {
-      if (value === undefined) return;
-
-      const expected =
-        type === "boolean" ? "boolean" : type === "number" ? "number" : "string";
-      if (typeof value !== expected) {
-        ctx.addIssue({
-          code: "custom",
-          path: [field],
-          message: `must be a ${expected}, to match the declared type '${type}'`,
-        });
-      } else if (
-        type === "enum" &&
-        validate?.enum !== undefined &&
-        !validate.enum.includes(String(value))
-      ) {
-        ctx.addIssue({
-          code: "custom",
-          path: [field],
-          message: "must be one of the options listed under 'validate.enum'",
-        });
-      }
-    }
-  });
-
 // --- The manifest -------------------------------------------------------------------------------
 
 /** The recipe manifest schema. */
@@ -362,21 +178,9 @@ export type RecipeManifest = z.infer<typeof recipeManifestSchema>;
 /** One validated content group from a recipe manifest. */
 export type RecipeContent = z.infer<typeof recipeContentSchema>;
 
-/** One validated variable definition from a recipe manifest. */
-export type VariableDefinition = z.infer<typeof variableDefinitionSchema>;
-
-/** The constraints attached to a variable definition. */
-export type VariableValidation = z.infer<typeof variableValidationSchema>;
-
 /** What a content group contributes. */
 export type ContentKind = (typeof CONTENT_KINDS)[number];
 
-/** The value type a variable definition declares. */
-export type VariableType = (typeof VARIABLE_TYPES)[number];
-
-/** Which env file an answer is written to. */
-export type VariableScope = (typeof VARIABLE_SCOPES)[number];
-
 /**
  * Validates a parsed recipe manifest, throwing a ConfigError that names the
  * file and the path of every bad field.