@sous-io/sous 0.2.37 → 1.0.2

package/src/lib/repos/declarations.ts

@@ -1,187 +0,0 @@
-/**
- * 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 {
-  RefSource,
-  isNamedRef,
-  locationOf,
-  namespaceOfKey,
-  settleDependency,
-  shortKey,
-  sharedRefResolver,
-  type RecordedDependencies,
-} from "../../services/ref-resolver/index.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 || !isNamedRef(reading)) continue;
-
-      const named = reading.kind === "recipe";
-      const covers = named
-        ? shortKey(reading) === key
-        : namespaceOfKey(key) === reading.name;
-      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 { refs } = sharedRefResolver().parse(declared, RefSource.Manifest);
-    const only = refs[0]!;
-    if (refs.length === 1 && only.kind === "namespace") {
-      const location = locationOf(only);
-      return location === undefined
-        ? `the whole '${only.name}' namespace`
-        : `the whole '${only.name}' namespace of ${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/defaults.ts

@@ -1,175 +0,0 @@
-/**
- * The repository and subscription every project gets without asking.
- *
- * Sous ships one namespace, `core`, holding the skills that teach an agent what
- * sous is and how it works. Every project is subscribed to it, because an agent
- * that does not know sous manages a file will happily hand-edit it. The wiring
- * is deliberately ordinary: sous adds the same two config entries a person could
- * have written by hand, so they can be inspected with `sous config show` and
- * overridden or switched off in the config like anything else.
- *
- *   - The repository `sous-recipes`, pointing at the official public repository.
- *     Trust is not a question here: sous itself ships the recipe, pins the
- *     version to its own, and seeds it from the package, so trusting it adds
- *     nothing a person did not already accept by installing sous.
- *   - The subscription `core`, a whole-namespace subscription whose range is
- *     exactly the running sous version. Core therefore always matches the CLI,
- *     and upgrading sous upgrades core with it.
- *
- * Two ways out, both plain config:
- *
- *     subscriptions: { core: { enabled: false } }      // keep the repo, drop the skills
- *     repos: { "sous-recipes": { enabled: false } }    // drop the repository entirely
- *
- * A user-written entry under either key REPLACES the default outright, because
- * the defaults are applied underneath whatever the config layers produced. That
- * is what lets a project pin core to a different range, point the repository at
- * a mirror, or turn either off.
- */
-
-import type { RepoEntry, Settings, SubscriptionEntry } from "../settings.js";
-import { SOUS_VERSION } from "../package-info.js";
-import {
-  CORE_NAMESPACE,
-  OFFICIAL_REPO_NAME,
-  OFFICIAL_REPO_PROVIDER,
-  OFFICIAL_REPO_URL,
-} from "./core-recipe.js";
-
-/**
- * The `addedBy` value on an entry sous provides itself. It is what tells
- * `sous repo list` to print "built in" rather than a date, and it is why these
- * entries are never written to a managed layer: they are recreated on every run
- * from the installed package.
- */
-export const BUILT_IN_ADDED_BY = "sous";
-
-/** The built-in repository entry, exactly as a person could have written it. */
-export function builtInRepoEntry(): RepoEntry {
-  return {
-    url: OFFICIAL_REPO_URL,
-    provider: OFFICIAL_REPO_PROVIDER,
-    addedBy: BUILT_IN_ADDED_BY,
-  };
-}
-
-/**
- * The built-in `core` subscription. Its range is the exact running version, not
- * a caret range: core is published in lockstep with the CLI and is meant to
- * match it exactly.
- *
- * @param version - The running sous version. Defaults to this installation's.
- */
-export function builtInCoreSubscription(version: string = SOUS_VERSION): SubscriptionEntry {
-  return { range: version, addedBy: BUILT_IN_ADDED_BY };
-}
-
-/**
- * Adds the built-in repository and subscription to a merged config, underneath
- * anything the config layers already said.
- *
- * The core subscription is added only when the built-in repository survives: a
- * project that switched the repository off would otherwise be left subscribed to
- * a namespace nothing can resolve.
- *
- * @param settings - The merged, validated config.
- * @param version - The running sous version. Defaults to this installation's.
- */
-export function applyRepoDefaults(
-  settings: Settings,
-  version: string = SOUS_VERSION
-): Settings {
-  // Anything that is not a map of entries is left exactly as written, so schema
-  // validation reports the real mistake rather than a symptom of this merge.
-  if (!isEntryMap(settings.repos) || !isEntryMap(settings.subscriptions)) return settings;
-
-  const repos: Record<string, RepoEntry> = {
-    ...settings.repos,
-    [OFFICIAL_REPO_NAME]: mergeOverDefault(
-      builtInRepoEntry(),
-      settings.repos?.[OFFICIAL_REPO_NAME]
-    ),
-  };
-
-  const withRepos: Settings = { ...settings, repos };
-  if (repos[OFFICIAL_REPO_NAME]?.enabled === false) return withRepos;
-
-  return {
-    ...withRepos,
-    subscriptions: {
-      ...settings.subscriptions,
-      [CORE_NAMESPACE]: mergeOverDefault(
-        builtInCoreSubscription(version),
-        settings.subscriptions?.[CORE_NAMESPACE]
-      ),
-    },
-  };
-}
-
-/**
- * Lays what a project wrote over the entry sous provides.
- *
- * The merge is per field, not per entry, which is the whole point: the shortest
- * possible opt-out, `{ enabled: false }`, is a complete entry once the built-in
- * URL and provider are underneath it. A project that wants to repoint the
- * repository writes a `url` and that field alone changes.
- *
- * @param fallback - The entry sous provides.
- * @param written - What the project's config layers produced, when anything did.
- */
-function mergeOverDefault<T extends object>(fallback: T, written: T | undefined): T {
-  if (written === undefined || typeof written !== "object" || Array.isArray(written)) {
-    return fallback;
-  }
-  return { ...fallback, ...written };
-}
-
-/** True when a config value is absent or is a plain map of entries. */
-function isEntryMap(value: unknown): boolean {
-  return value === undefined || (typeof value === "object" && value !== null && !Array.isArray(value));
-}
-
-/**
- * True when an entry is one sous provided rather than one the project wrote.
- *
- * @param entry - A repository or subscription entry.
- */
-export function isBuiltInEntry(entry: { addedBy?: string } | undefined): boolean {
-  return entry?.addedBy === BUILT_IN_ADDED_BY;
-}
-
-/**
- * The repositories a project actually uses: everything in the config except the
- * entries switched off with `enabled: false`. A switched-off entry stays in the
- * config, and stays visible to `sous config show`, so the opt-out is legible;
- * it simply takes no part in resolving, fetching or trusting anything.
- *
- * @param settings - The merged config.
- */
-export function enabledRepos(settings: Settings | undefined): Record<string, RepoEntry> {
-  return withoutDisabled(settings?.repos);
-}
-
-/**
- * The subscriptions a project actually has, on the same terms as
- * `enabledRepos`.
- *
- * @param settings - The merged config.
- */
-export function enabledSubscriptions(
-  settings: Settings | undefined
-): Record<string, SubscriptionEntry> {
-  return withoutDisabled(settings?.subscriptions);
-}
-
-/** Drops every entry whose `enabled` field says false. */
-function withoutDisabled<T extends { enabled?: boolean }>(
-  entries: Record<string, T> | undefined
-): Record<string, T> {
-  const kept: Record<string, T> = {};
-  for (const [key, entry] of Object.entries(entries ?? {})) {
-    if (entry?.enabled === false) continue;
-    kept[key] = entry;
-  }
-  return kept;
-}