@sous-io/sous 0.2.31 → 0.2.33

package/src/lib/settings.ts

@@ -14,6 +14,7 @@ import {
   type DiscoveredConfig,
 } from "./config-discovery.js";
 import { ConfigError } from "./errors.js";
+import { sharedHashNames } from "../services/ref-resolver/index.js";
 import { resolveSousHome } from "./sous-home.js";
 import { validateSettings } from "./config-schema.js";
 import { applyRepoDefaults } from "./repos/defaults.js";
@@ -148,23 +149,25 @@ type StoreConfig = {
 };
 
 /**
- * Where the files a subscribed recipe contributes are written, one list of
- * destination directories per content kind. Each destination is `${var}`
- * substituted like any other config path, and a kind may name several so the
- * same recipe feeds more than one agent directory.
+ * What a project does with each content kind its subscribed recipes publish.
  *
- * Only `skills` has a default (`<project root>/.claude/skills`, the project root
- * being the parent of `.sous/`). A kind with no destination is skipped, with one
- * warning naming this config key, because sous cannot guess where a project
- * wants its memories or its prompts.
+ * `skills.outputs` lists the destination directories for recipe skills, each
+ * `${var}` substituted; the default is `<project root>/.claude/skills`, the
+ * project root being the parent of `.sous/`. `memories.first` and
+ * `memories.exclude` are lists of globs, or `/.../` regular expressions, over
+ * `namespace/recipe` keys.
  */
-type RecipeOutputs = {
-  /** Where recipe skill bundles are written. */
-  skills?: string[];
-  /** Where recipe memory files are written. */
-  memories?: string[];
-  /** Where recipe prompt files are written. */
-  prompts?: string[];
+type RecipesConfig = {
+  skills?: {
+    /** Where recipe skill bundles are written. */
+    outputs?: string[];
+  };
+  memories?: {
+    /** Recipes whose memories come first. */
+    first?: string[];
+    /** Recipes whose memories are left out. */
+    exclude?: string[];
+  };
 };
 
 /** Configuration for a launchable tool (e.g. claude, codex). */
@@ -204,9 +207,9 @@ export type Settings = {
   /** Knobs for the machine-wide recipe store. */
   store?: StoreConfig;
   /**
-   * Where the files subscribed recipes contribute are written, per content kind.
+   * What the project does with each content kind its subscribed recipes publish.
    */
-  recipeOutputs?: RecipeOutputs;
+  recipes?: RecipesConfig;
   /**
    * Variable mapping records, keyed by environment variable name, each bound to
    * one recipe variable written as `namespace/recipe/variableName` with an
@@ -820,30 +823,29 @@ function resolveAnswerLayer(
 }
 
 /**
- * Built-in `@include` aliases, always available and reserved (their names begin
- * with `~` so user `_aliases` can never shadow them). Add new entries here as
- * needed; keep names kebab-case.
+ * Built-in `@include` aliases: every `#` name the registry holds
+ * (`sharedHashNames`), each standing for its directories in this project. They
+ * are reserved (user `_aliases` may not start with `#`), so a user alias can
+ * never shadow one.
  *
- * - `~project` → the consuming project's root (`projectRoot`).
+ * - `#project` is the consuming project's root (`projectRoot`).
  *
- * There is exactly one, on purpose. Files that used to be reached through a
- * built-in alias pointing inside the sous package are published as recipes now,
- * and a recipe's files are addressed by its namespace (`@~workflow/task-files/
- * _partials/resume-task.md`), resolved against what the project has pinned. A
- * `~namespace` reference is NOT an alias: it is resolved separately, after the
- * alias map has been tried; see `locked-namespace-resolver.ts`.
+ * Files that used to be reached through a built-in alias pointing inside the
+ * sous package are published as recipes now, and a recipe's files are addressed
+ * by its namespace (`@~workflow/task-files/_partials/resume-task.md`),
+ * resolved against what the project has pinned. A `~` reference is NOT an
+ * alias: it is resolved separately, after the alias map has been tried; see
+ * `locked-namespace-resolver.ts`.
  */
 export function buildBuiltInAliases(scope: VarScope): AliasMap {
-  const builtIns: AliasMap = {};
-  if (scope.projectRoot) builtIns["~project"] = [scope.projectRoot];
-  return builtIns;
+  return sharedHashNames().aliasMap(scope as Record<string, string>);
 }
 
 /**
  * Resolve the full `@include` alias map: built-ins, then the config's
  * `_aliases` block (user entries prepend, so they are tried first and fall
  * through to built-in bases of the same name). User alias names starting
- * with `~` are rejected (reserved).
+ * with `~` or `#` are a ConfigError (reserved).
  *
  * @param settings - The loaded settings (for the `_aliases` block).
  * @param scope - The resolved settings scope (for ${var} substitution + projectRoot).
@@ -853,7 +855,9 @@ export function resolveAliases(settings: Settings, scope: VarScope): AliasMap {
     builtIns: buildBuiltInAliases(scope),
     userAliases: [settings._aliases],
     scope,
-    onError: warning,
+    onError: (message) => {
+      throw new ConfigError(message);
+    },
   });
 }
 
@@ -1002,7 +1006,7 @@ export function resolveCompilation(
 
       /* c8 ignore start */
       // Glob target: expand pattern into one CompilationTarget per matched file, skipping dirs.
-      // A leading alias (`~project/skills/**`) expands to one candidate pattern per alias
+      // A leading alias (`#project/skills/**`) expands to one candidate pattern per alias
       // base; the first base that matches any files wins, mirroring the first-existing-wins
       // rule of @include resolution.
       const rawPattern = substituteVarsStrict(target.entryGlob!, targetScope, `${where}.entryGlob`);

package/src/lib/vars/ask.ts

@@ -42,7 +42,7 @@ import { choicePrompt } from "../../utils/choice-prompt.js";
 import { confirmPrompt } from "../../utils/confirm-prompt.js";
 import { valuePrompt } from "../../utils/value-prompt.js";
 import { ENV_VAR_NAME_PATTERN } from "../repos/formats/patterns.js";
-import { variableReferenceKey } from "../refs/find.js";
+import { refKey, variableRefOf } from "../../services/ref-resolver/index.js";
 import type { VariableDefinition } from "../repos/formats/recipe-manifest.js";
 import {
   definedVariableKey,
@@ -152,7 +152,7 @@ export interface AskOptions {
    * Limit the run to these variables. Each entry is a variable's bare name, its
    * `namespace/recipe.name` key, or its fully qualified
    * `repository:namespace/recipe.name` reference. A command that resolved a
-   * reference through `src/lib/refs/` passes the fully qualified form, which is
+   * reference through `src/services/ref-resolver/` passes the fully qualified form, which is
    * the only spelling that cannot mean two variables at once.
    */
   only?: string[];
@@ -182,7 +182,7 @@ export function answerFileFor(definition: VariableDefinition): AnswerFile {
 function isNamed(defined: DefinedVariable, only: string[] | undefined): boolean {
   if (only === undefined) return false;
   const key = definedVariableKey(defined);
-  const qualified = variableReferenceKey(defined);
+  const qualified = refKey(variableRefOf(defined));
   return only.some(
     (name) => name === defined.definition.name || name === key || name === qualified
   );

package/src/lib/vars/mappings.ts

@@ -27,8 +27,14 @@ import {
   updateManagedLayer,
 } from "../repos/managed-layer.js";
 import { VARIABLE_NAME_PATTERN } from "../repos/formats/patterns.js";
-import { RefSource } from "../refs/scopes.js";
-import { formatRef, parseShortRef, type ParsedRef } from "../refs/parse.js";
+import {
+  RefSource,
+  formatRef,
+  namespaceOf,
+  parseNamedRef,
+  repoOf,
+  type NamedRef,
+} from "../../services/ref-resolver/index.js";
 import type { DefinedVariable } from "./definition-source.js";
 
 /** File name of the machine-written mapping record layer. */
@@ -85,18 +91,20 @@ export function parseMappingTarget(input: string): MappingTarget {
   // ref part is read by the one ref parser and held to the stored form.
   const slash = trimmed.lastIndexOf("/");
   const variable = slash === -1 ? "" : trimmed.slice(slash + 1);
-  let ref: ParsedRef = { namespace: "" };
+  let ref: NamedRef | undefined;
   try {
-    ref = parseShortRef(trimmed.slice(0, Math.max(slash, 0)), RefSource.CommandLine);
+    ref = parseNamedRef(trimmed.slice(0, Math.max(slash, 0)), RefSource.CommandLine);
   } catch (error) {
     fail((error as Error).message.split("\n")[0]!.replace(/^Invalid ref '[^']*': /, ""));
   }
-  const { repo, namespace, recipe } = ref;
-  if (recipe === undefined || ref.range !== undefined) {
+  if (ref?.kind !== "recipe" || ref.range !== undefined) {
     fail("a target names a namespace, a recipe and a variable, joined by slashes.");
   }
-  if (formatRef(ref) !== formatRef(ref).toLowerCase()) {
-    fail(`the repository, namespace and recipe in '${formatRef(ref)}' must be lowercase.`);
+  const repo = repoOf(ref!)?.name;
+  const namespace = namespaceOf(ref!)!.name;
+  const recipe = ref!.kind === "recipe" ? ref!.name : "";
+  if (formatRef(ref!) !== formatRef(ref!).toLowerCase()) {
+    fail(`the repository, namespace and recipe in '${formatRef(ref!)}' must be lowercase.`);
   }
   if (!VARIABLE_NAME_PATTERN.test(variable)) {
     fail(
@@ -105,7 +113,7 @@ export function parseMappingTarget(input: string): MappingTarget {
     );
   }
 
-  const parsed: MappingTarget = { namespace, recipe: recipe!, variable };
+  const parsed: MappingTarget = { namespace, recipe, variable };
   if (repo !== undefined) parsed.repo = repo;
   return parsed;
 }

package/src/services/ref-resolver/container.ts

@@ -0,0 +1,107 @@
+/**
+ * The Inversify container of the ref services.
+ *
+ * Every part is bound once and shared: the parser, every splitter, every
+ * pruner, the resolver and the picker. Splitters, pruners and providers are
+ * bound many times under one token each (`REF_TOKENS`), and the parser and the
+ * resolver receive them as lists, so a plugin adds a splitter, a pruner or a
+ * provider by binding one more under the same token on a container it builds
+ * with `createRefContainer()`:
+ *
+ *     const container = createRefContainer();
+ *     container.bind(REF_TOKENS.Splitter).to(MyNewFormSplitter);
+ *     const resolver = container.get<RefResolverService>(REF_TOKENS.Resolver);
+ *
+ * The `#` names are bound the same way: one more `HashName` under
+ * `REF_TOKENS.HashName` registers a view or a built-in, and a name bound twice
+ * is an error when the registry is first read.
+ *
+ * Callers that have no container of their own use `sharedRefResolver`,
+ * `sharedHashNames` and `sharedRefPicker`, which come from one container built the first time they
+ * are read.
+ */
+
+import { Container } from "inversify";
+import { builtInProviders } from "../../lib/repos/providers/index.js";
+import { EnvVarSplitter } from "./parser/env-var-splitter.js";
+import { LocationSplitter } from "./parser/location-splitter.js";
+import { NamePathSplitter } from "./parser/name-path-splitter.js";
+import { QuerySplitter } from "./parser/query-splitter.js";
+import { RangeSplitter } from "./parser/range-splitter.js";
+import { RefParser } from "./parser/ref-parser.js";
+import { RepoQualifierSplitter } from "./parser/repo-qualifier-splitter.js";
+import { CommandLinePruner } from "./pruners/command-line-pruner.js";
+import { IncludePruner } from "./pruners/include-pruner.js";
+import { ManifestPruner } from "./pruners/manifest-pruner.js";
+import { ConfigPruner, LockfilePruner } from "./pruners/stored-key-pruner.js";
+import { MemoriesHashName } from "../../lib/repos/memories-hash-name.js";
+import { HashNameRegistry, ProjectHashName } from "./hash-names.js";
+import { RefPickerService } from "./ref-picker-service.js";
+import { RefResolverService } from "./ref-resolver-service.js";
+import { REF_TOKENS } from "./tokens.js";
+
+/**
+ * Builds a container holding every ref service. Each call returns a fresh
+ * container, so a plugin or a test may bind more splitters or pruners without
+ * touching anyone else's.
+ */
+export function createRefContainer(): Container {
+  const container = new Container({ defaultScope: "Singleton" });
+
+  for (const provider of builtInProviders()) {
+    container.bind(REF_TOKENS.Provider).toConstantValue(provider);
+  }
+
+  for (const splitter of [
+    QuerySplitter,
+    RangeSplitter,
+    LocationSplitter,
+    RepoQualifierSplitter,
+    NamePathSplitter,
+    EnvVarSplitter,
+  ]) {
+    container.bind(REF_TOKENS.Splitter).to(splitter);
+  }
+
+  for (const pruner of [
+    CommandLinePruner,
+    ConfigPruner,
+    ManifestPruner,
+    LockfilePruner,
+    IncludePruner,
+  ]) {
+    container.bind(REF_TOKENS.Pruner).to(pruner);
+  }
+
+  container.bind(REF_TOKENS.HashName).to(ProjectHashName);
+  container.bind(REF_TOKENS.HashName).to(MemoriesHashName);
+  container.bind(REF_TOKENS.HashNames).to(HashNameRegistry);
+  container.bind(REF_TOKENS.Parser).to(RefParser);
+  container.bind(REF_TOKENS.Resolver).to(RefResolverService);
+  container.bind(REF_TOKENS.Picker).to(RefPickerService);
+  return container;
+}
+
+/** The container the shared instances come from, built on first use. */
+let sharedContainer: Container | undefined;
+
+/** The one container callers with no container of their own share. */
+export function getSharedRefContainer(): Container {
+  sharedContainer ??= createRefContainer();
+  return sharedContainer;
+}
+
+/** The shared resolver, for callers that have no container. */
+export function sharedRefResolver(): RefResolverService {
+  return getSharedRefContainer().get<RefResolverService>(REF_TOKENS.Resolver);
+}
+
+/** The shared registry of `#` names, for callers that have no container. */
+export function sharedHashNames(): HashNameRegistry {
+  return getSharedRefContainer().get<HashNameRegistry>(REF_TOKENS.HashNames);
+}
+
+/** The shared picker, for callers that have no container. */
+export function sharedRefPicker(): RefPickerService {
+  return getSharedRefContainer().get<RefPickerService>(REF_TOKENS.Picker);
+}

package/src/services/ref-resolver/dependency.ts

@@ -0,0 +1,60 @@
+/**
+ * Settling a manifest dependency that reads more than one way, from what is
+ * already at hand.
+ *
+ * A manifest entry usually says exactly what it means. A GitLab URL with nested
+ * groups does not say where the project path ends, and a browser URL names a
+ * folder, so the parser returns every reading. A release settles such an entry
+ * and records the repository it settled on beside each key it resolved
+ * (`RecordedDependencies`); a consumer reads that record and never probes.
+ */
+
+import { sharedRefResolver } from "./container.js";
+import {
+  isConfirmedByRecord,
+  type RecordedDependencies,
+} from "./lookups/recorded-dependency-lookup.js";
+import { RefSource } from "./source.js";
+import type { SousRef } from "./types.js";
+
+/** 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: SousRef) => 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");
+ * // -> the recipe workflow/alpha
+ *
+ * @param written - The dependency as the manifest wrote it.
+ * @param options - The index's record, and what is known locally.
+ * @throws A ConfigError when a manifest may not write the entry that way.
+ */
+export function settleDependency(
+  written: string,
+  options: SettleDependencyOptions = {}
+): SousRef | undefined {
+  const { refs } = sharedRefResolver().parse(written, RefSource.Manifest);
+  if (refs.length === 1) return refs[0];
+
+  const confirmed = refs.filter((ref) => isConfirmedByRecord(ref, options.recorded));
+  if (confirmed.length === 1) return confirmed[0];
+
+  if (options.known !== undefined) {
+    const known = refs.filter(options.known);
+    if (known.length === 1) return known[0];
+  }
+  return undefined;
+}

package/src/services/ref-resolver/format.ts

@@ -0,0 +1,197 @@
+/**
+ * Printing a ref: its key (what everything is stored and compared under) and
+ * its canonical written form (how sous prints it).
+ */
+
+import {
+  builtInProviders,
+  providerById,
+  type RepoProvider,
+} from "../../lib/repos/providers/index.js";
+import { repoOf } from "./parts.js";
+import { KIND_LABELS, type RepoRef, type SousRef } from "./types.js";
+
+/**
+ * The part of a key that names the repository: its short name, or its
+ * identity when it was named by location.
+ */
+function repoPart(repo: RepoRef | undefined): string | undefined {
+  if (repo === undefined) return undefined;
+  return repo.name ?? repo.location?.identity;
+}
+
+/**
+ * The path part of a key, without any repository.
+ *
+ * @param ref - Any ref.
+ */
+function pathPart(ref: SousRef): string {
+  switch (ref.kind) {
+    case "repo":
+      return ref.browsed === undefined ? "" : `tree/${ref.browsed}`;
+    case "namespace":
+      return ref.name;
+    case "recipe":
+      return ref.namespace === undefined ? ref.name : `${ref.namespace.name}/${ref.name}`;
+    case "recipeFile":
+      return `${pathPart(ref.recipe)}/${ref.path}`;
+    case "variable": {
+      const recipe = ref.recipe === undefined ? "" : `${pathPart(ref.recipe)}.`;
+      return `${recipe}${ref.name}`;
+    }
+    case "envVar":
+      return ref.name;
+  }
+}
+
+/**
+ * The canonical key of a ref, with its version range and query values left
+ * off, so the same thing is never keyed twice under two spellings. A
+ * repository qualifier is part of the key, because the same recipe name in two
+ * repositories is two things.
+ *
+ * refKey(namespace("workflow")); // -> "workflow"
+ * refKey(recipe("task-files", "workflow", "sous-recipes")); // -> "sous-recipes:workflow/task-files"
+ * refKey(variable("apiUrl", recipe)); // -> "workflow/task-files.apiUrl"
+ *
+ * @param ref - Any ref.
+ */
+export function refKey(ref: SousRef): string {
+  const repo = ref.kind === "envVar" ? undefined : repoPart(repoOf(ref));
+  const rest = pathPart(ref);
+  if (ref.kind === "repo") return repo === undefined ? rest : rest === "" ? repo : `${repo}:${rest}`;
+  return repo === undefined ? rest : `${repo}:${rest}`;
+}
+
+/**
+ * The key of a ref together with its kind, which is what tells a namespace
+ * `workflow` from a repository `workflow` apart.
+ *
+ * @param ref - Any ref.
+ */
+export function refIdentity(ref: SousRef): string {
+  return `${ref.kind} ${refKey(ref)}`;
+}
+
+/**
+ * Writes the repository qualifier in front of what is named inside it: `name:`
+ * for a repository this project knows by short name (whatever else it knows of
+ * it), and the provider's canonical locator for one known only by location.
+ */
+function qualified(
+  repo: RepoRef | undefined,
+  rest: string,
+  providers: RepoProvider[]
+): string {
+  if (repo === undefined) return rest;
+  if (repo.name !== undefined) return rest === "" ? repo.name : `${repo.name}:${rest}`;
+  if (repo.location !== undefined) {
+    const { host, repoPath } = repo.location;
+    const provider = providerById(repo.location.provider, providers);
+    if (provider !== undefined && provider.id !== "local") {
+      return provider.formatLocator(host, repoPath, rest);
+    }
+    return rest === "" ? repo.location.url : `${repo.location.url}/${rest}`;
+  }
+  return rest;
+}
+
+/**
+ * The canonical written form of a ref, which is how sous prints it: the short
+ * form for a short ref and each provider's own locator for a located one, then
+ * the version range, then the query values.
+ *
+ * formatRef(parse("https://github.com/o/r/w/a@^1")[0]); // -> "github://o/r/w/a@^1"
+ *
+ * @param ref - Any ref.
+ * @param providers - The providers that format locators. Defaults to the built-ins.
+ */
+export function formatRef(ref: SousRef, providers: RepoProvider[] = builtInProviders()): string {
+  const body = qualified(ref.kind === "envVar" ? undefined : repoOf(ref), pathPart(ref), providers);
+  const written =
+    ref.kind === "recipe" || ref.kind === "recipeFile" || ref.kind === "repo"
+      ? ref.range
+      : undefined;
+  const range = written === undefined ? "" : `@${written}`;
+  const pairs = Object.entries(ref.vars ?? {}).map(
+    ([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(value)}`
+  );
+  return `${body}${range}${pairs.length === 0 ? "" : `?${pairs.join("&")}`}`;
+}
+
+/**
+ * What kind of thing a ref names, in a sentence.
+ *
+ * @param ref - Any ref.
+ */
+export function refKindLabel(ref: SousRef): string {
+  return KIND_LABELS[ref.kind];
+}
+
+/**
+ * How a ref is written to a person, so they can type it back: its key when a
+ * repository's short name qualifies it, and its canonical locator when only a
+ * location does (a ref that has not been matched to a repository this project
+ * knows by name).
+ *
+ * refSpelling(recipe "task-files" in "sous-recipes") // -> "sous-recipes:workflow/task-files"
+ * refSpelling(a recipe at a located repository)      // -> its canonical locator
+ *
+ * @param ref - Any ref.
+ */
+export function refSpelling(ref: SousRef): string {
+  const repo = ref.kind === "envVar" ? undefined : repoOf(ref);
+  if (repo !== undefined && repo.name === undefined && repo.location !== undefined) {
+    return formatRef(ref);
+  }
+  return refKey(ref);
+}
+
+/** The repository a person is told a ref lives in: its short name, or where it lives. */
+function repoLabel(repo: RepoRef | undefined): string {
+  return repo?.name ?? repo?.location?.url ?? "unknown";
+}
+
+/**
+ * Describes one ref in the words a person choosing between several needs: the
+ * fully qualified name, and what it actually means.
+ *
+ * @param ref - A known ref, as a lookup returns it.
+ */
+export function describeRef(ref: SousRef): string {
+  const summary = ref.description === undefined ? "" : `: ${ref.description}`;
+  const key = refSpelling(ref);
+
+  switch (ref.kind) {
+    case "repo": {
+      const where = ref.location?.url;
+      return `${key}  (the repository '${ref.name ?? key}'${where === undefined ? "" : `, at ${where}`})`;
+    }
+    case "namespace":
+      return (
+        `${key}  (the whole namespace '${ref.name}' in the ` +
+        `repository '${repoLabel(ref.repo)}')`
+      );
+    case "recipe":
+      return (
+        `${key}  (the recipe '${ref.name}' in the namespace ` +
+        `'${ref.namespace?.name ?? "unknown"}' of the repository ` +
+        `'${repoLabel(repoOf(ref))}'${summary})`
+      );
+    case "recipeFile":
+      return `${key}  (the file '${ref.path}' of the recipe '${pathPart(ref.recipe)}'${summary})`;
+    case "variable":
+      return (
+        `${key}  (the variable '${ref.name}' of the recipe ` +
+        `'${ref.recipe === undefined ? "unknown" : pathPart(ref.recipe)}'${summary})`
+      );
+    case "envVar": {
+      const first = ref.variables?.[0];
+      const answers =
+        first === undefined
+          ? ""
+          : `answering '${first.name}' of the recipe '${first.recipe === undefined ? "unknown" : pathPart(first.recipe)}'`;
+      return `${ref.name}  (the environment variable${answers === "" ? "" : ` ${answers}`}${summary})`;
+    }
+  }
+}