@sous-io/sous 0.1.1 → 0.2.0

package/src/commands/lock/rebuild.ts

@@ -0,0 +1,241 @@
+/**
+ * `sous lock rebuild`.
+ *
+ * Recomputes the lockfile from scratch: every subscription this project
+ * declares is resolved against the cached repository indexes, the whole
+ * dependency closure beneath them is walked, and the result replaces the
+ * lockfile outright. An entry nothing holds any more is dropped, which is what
+ * makes this the repair for a lockfile that has drifted from the config: a
+ * hand-edited file, a bad merge, or a subscription removed from the config by
+ * hand rather than with `sous subscription remove`.
+ *
+ * It is an edge-case utility, so it is deliberately blunt. It never asks a
+ * question and never grants trust: a subscription whose repository this project
+ * has not added is an error naming the repository. It downloads nothing; a
+ * repository whose index has not been fetched is named, and nothing in it can
+ * be resolved.
+ */
+
+import { Flags } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import { ConfigError } from "../../lib/errors.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { recipeFilesDirectory } from "../../lib/repos/catalog-inputs.js";
+import { readRecipeManifestIn } from "../../lib/repos/locked-recipes.js";
+import { createEmptyLockfile } from "../../lib/repos/formats/lockfile.js";
+import type { LockRepoInput } from "../../lib/repos/lock-service.js";
+import { parseRef } from "../../lib/repos/ref.js";
+import {
+  PROJECT_REQUESTER,
+  resolveRefs,
+  type RefRequest,
+  type ResolverRepo,
+} from "../../lib/repos/resolver.js";
+import type { IndexFile } from "../../lib/repos/formats/index-file.js";
+import {
+  blankLine,
+  dryRunNotice,
+  footer,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showCommandVars,
+} from "../../utils/formatting.js";
+
+/** How far every line of this command's output is indented. */
+const INDENT = 2;
+
+export default class LockRebuild extends BaseCommand {
+  static description =
+    "Rebuild this project's lockfile from its subscriptions and the cached repository indexes";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["locks:rebuild"];
+
+  static examples = [
+    "<%= config.bin %> lock rebuild",
+    "<%= config.bin %> lock rebuild --dry-run",
+  ];
+
+  static flags = {
+    ...BaseCommand.baseFlags,
+    "dry-run": Flags.boolean({
+      description: "Print what would change without writing the lockfile",
+      default: false,
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(LockRebuild);
+    const dryRun = flags["dry-run"];
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+      "Dry Run": dryRun,
+    });
+
+    heading("Rebuilding the lockfile");
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const sousDir = this.configContext.sousDir;
+    const trusted = service.currentRepos();
+
+    const repos: Record<string, ResolverRepo> = {};
+    const lockRepos: Record<string, LockRepoInput> = {};
+    const indexes = new Map<string, IndexFile>();
+    const notFetched: string[] = [];
+
+    const before = service.lockService.read();
+
+    for (const name of Object.keys(trusted).sort()) {
+      const entry = trusted[name]!;
+      const identity = service.identityForRepo(name);
+      if (identity === undefined) continue;
+
+      repos[name] = {
+        url: entry.url,
+        identity,
+        ...(entry.provider === undefined ? {} : { provider: entry.provider }),
+        ...(entry.alwaysPull === undefined ? {} : { alwaysPull: entry.alwaysPull }),
+      };
+      lockRepos[name] = {
+        url: entry.url,
+        identity,
+        ...(entry.provider === undefined ? {} : { provider: entry.provider }),
+        // The index a resolution was made against is recorded per repository.
+        // A rebuild resolves against the same cached index the last one did, so
+        // whatever the lockfile already recorded still holds.
+        ...(before.repos[name]?.indexHash === undefined
+          ? {}
+          : { indexHash: before.repos[name]!.indexHash! }),
+      };
+
+      const index = service.cachedIndex(name);
+      if (index === undefined) {
+        notFetched.push(name);
+        continue;
+      }
+      indexes.set(name, index);
+    }
+
+    const subscriptions = service.allSubscriptions();
+    const requests: RefRequest[] = Object.keys(subscriptions)
+      .sort()
+      .map((key) => {
+        const entry = subscriptions[key]!;
+        const parsed = parseRef(key);
+        return {
+          ref: {
+            ...parsed,
+            ...(entry.range === undefined ? {} : { range: entry.range }),
+          },
+          requestedBy: PROJECT_REQUESTER,
+          kind: "subscribes" as const,
+          ...(entry.prerelease === true ? { prerelease: true } : {}),
+        };
+      });
+
+    const result = await resolveRefs(requests, {
+      indexes,
+      repos,
+      // A recipe's own manifest is what names its dependencies, and it is read
+      // from the files this machine already holds. Nothing is fetched here, so a
+      // recipe that is not in the store yet comes back under `missingManifests`.
+      loadManifest: (recipe) => {
+        const directory = recipeFilesDirectory({
+          service,
+          sousDir,
+          repo: recipe.repo,
+          key: recipe.key,
+          namespace: recipe.namespace,
+          name: recipe.name,
+          version: recipe.version,
+        });
+        return directory === undefined ? undefined : readRecipeManifestIn(directory);
+      },
+    });
+
+    if (result.missingRepos.length > 0) {
+      throw new ConfigError(
+        `This project's subscriptions need ${
+          result.missingRepos.length === 1 ? "a repository" : "repositories"
+        } it does not trust, so the lockfile cannot be rebuilt:\n` +
+          result.missingRepos
+            .map(
+              (missing) =>
+                `  ${missing.name}${missing.url === undefined ? "" : ` (${missing.url})`}, ` +
+                `needed by ${missing.requiredBy.map((entry) => entry.ref).join(", ")}`
+            )
+            .join("\n") +
+          `\n  Add ${
+            result.missingRepos.length === 1 ? "it" : "them"
+          } with 'sous repo add <url>', which is how a repository is trusted, then run ` +
+          `this command again.`
+      );
+    }
+
+    // The rebuild starts from an empty lockfile rather than the one on disk, so
+    // an entry nothing in the resolution holds any more is gone rather than
+    // carried through.
+    const after = service.lockService.applyResolution(
+      createEmptyLockfile(),
+      result.resolved,
+      lockRepos
+    );
+    const diff = service.lockService.diff(before, after);
+
+    blankLine();
+    for (const line of diff.lines) log(indent(line, INDENT));
+
+    if (notFetched.length > 0) {
+      blankLine();
+      paragraph(
+        `These repositories are trusted and their index has not been fetched yet, so ` +
+          `nothing in them could be resolved: ${notFetched.join(", ")}.`
+      );
+    }
+
+    if (result.missingManifests.length > 0) {
+      blankLine();
+      paragraph(
+        `The files of these recipes are not on this machine, so their own ` +
+          `dependencies could not be read and are not in the rebuilt lockfile: ` +
+          `${result.missingManifests.join(", ")}.`
+      );
+    }
+
+    for (const cycle of result.cycles) {
+      blankLine();
+      paragraph(`These recipes depend on each other in a circle: ${cycle.join(" -> ")}.`);
+    }
+
+    blankLine();
+
+    if (dryRun) {
+      dryRunNotice(`Nothing was written. The lockfile is ${service.lockService.filePath}.`);
+      footer();
+      return;
+    }
+
+    const written = service.lockService.write(after);
+    paragraph(
+      `The lockfile was rebuilt from ${requests.length} ${
+        requests.length === 1 ? "subscription" : "subscriptions"
+      } and now pins ${Object.keys(after.recipes).length} ${
+        Object.keys(after.recipes).length === 1 ? "recipe" : "recipes"
+      }: ${written}.`
+    );
+
+    footer();
+  }
+}

package/src/commands/lock/show.ts

@@ -0,0 +1,115 @@
+/**
+ * `sous lock show`.
+ *
+ * Prints the lockfile: every recipe this project pins, the version and the
+ * repository it is pinned to, and who holds it. It reads the file and nothing
+ * else, so it works offline and never writes.
+ */
+
+import { BaseCommand } from "../../base-command.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { PROJECT_HOLDER } from "../../lib/repos/formats/lockfile.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  blankLine,
+  footer,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showCommandVars,
+} from "../../utils/formatting.js";
+
+/** How far every line of this command's output is indented. */
+const INDENT = 2;
+
+/**
+ * The columns the listing shows. The recipe and the version it is pinned at are
+ * what a lockfile is for, so they stay whatever the terminal's width; the list
+ * of holders takes the room that is left and wraps rather than being cut.
+ */
+const COLUMNS: TableColumn[] = [
+  { key: "key", header: "Recipe", kind: "path", overflow: "truncate", minWidth: 12 },
+  { key: "version", header: "Version", overflow: "truncate", minWidth: 7 },
+  { key: "repo", header: "Repository", overflow: "truncate", priority: "medium" },
+  {
+    key: "heldBy",
+    header: "Held by",
+    overflow: "wrap",
+    flex: 1,
+    priority: "low",
+    minWidth: 16,
+  },
+];
+
+export default class LockShow extends BaseCommand {
+  static description = "Show every recipe version this project's lockfile pins";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["locks:show"];
+
+  static examples = ["<%= config.bin %> lock show"];
+
+  static flags = { ...BaseCommand.baseFlags };
+
+  async run(): Promise<void> {
+    await this.parse(LockShow);
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+    });
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const lock = service.lockService.read();
+    const keys = Object.keys(lock.recipes).sort();
+
+    heading("Recipe versions this project pins");
+    blankLine();
+
+    if (keys.length === 0) {
+      paragraph(
+        `This project pins nothing yet. Its lockfile is ${service.lockService.filePath}.`
+      );
+      footer();
+      return;
+    }
+
+    const rows = keys.map((key) => {
+      const entry = lock.recipes[key]!;
+      return {
+        key,
+        version: entry.version,
+        repo: entry.repo,
+        heldBy: entry.requestedBy.map(describeHolder).join(", "),
+      };
+    });
+
+    for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+      log(indent(line, INDENT));
+    }
+
+    blankLine();
+    paragraph(`This project's lockfile is ${service.lockService.filePath}.`);
+
+    footer();
+  }
+}
+
+/**
+ * Plain-language wording for one holder of a locked recipe: the project itself,
+ * or the recipe that requires it.
+ *
+ * @param holder - What the lockfile recorded.
+ */
+function describeHolder(holder: string): string {
+  return holder === PROJECT_HOLDER ? "this project" : holder;
+}

package/src/commands/namespace/list.ts

@@ -0,0 +1,117 @@
+/**
+ * `sous namespace list`.
+ *
+ * Shows every namespace published by the repositories this project trusts, how
+ * many recipes each one holds, and how much of it the project subscribes to. It
+ * reads only the indexes sous already has on disk, so it works offline; a
+ * repository whose index has never been fetched is named at the end rather than
+ * being silently left out.
+ */
+
+import { BaseCommand } from "../../base-command.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { catalogContextFor } from "../../lib/repos/catalog-inputs.js";
+import { listNamespaces } from "../../lib/repos/catalog.js";
+import { INDENT, describeCoverage } from "../../lib/repos/catalog-display.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  blankLine,
+  footer,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showCommandVars,
+} from "../../utils/formatting.js";
+
+/**
+ * The columns the listing shows. The namespace and what a project has of it are
+ * the point of the command, so they stay whatever the terminal's width; the
+ * description takes the room that is left and wraps rather than being cut.
+ */
+const COLUMNS: TableColumn[] = [
+  { key: "namespace", header: "Namespace", overflow: "truncate", minWidth: 10 },
+  { key: "repo", header: "Repository", overflow: "truncate", priority: "medium" },
+  { key: "recipes", header: "Recipes", kind: "number", priority: "medium" },
+  { key: "subscribed", header: "Subscribed", priority: "medium" },
+  {
+    key: "description",
+    header: "What it is",
+    overflow: "wrap",
+    flex: 1,
+    priority: "low",
+    minWidth: 16,
+  },
+];
+
+export default class NamespaceList extends BaseCommand {
+  static description = "List the namespaces the repositories this project trusts publish";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["namespaces:list"];
+
+  static examples = ["<%= config.bin %> namespace list"];
+
+  static flags = { ...BaseCommand.baseFlags };
+
+  async run(): Promise<void> {
+    await this.parse(NamespaceList);
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+    });
+
+    heading("Namespaces in the repositories this project trusts");
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const { inputs, notFetched } = catalogContextFor({
+      service,
+      sousDir: this.configContext.sousDir,
+      settings: this.settings,
+    });
+
+    const listings = listNamespaces(inputs);
+
+    blankLine();
+
+    if (listings.length === 0) {
+      paragraph(
+        inputs.repos.length === 0
+          ? "Sous has read no repository index for this project, so there are no " +
+            "namespaces to show."
+          : "The repositories this project trusts publish no namespaces."
+      );
+    } else {
+      const rows = listings.map((entry) => ({
+        namespace: entry.namespace,
+        repo: entry.repo,
+        recipes: String(entry.recipeCount),
+        subscribed: describeCoverage(entry.subscribed),
+        description: entry.description ?? "no description published",
+      }));
+
+      for (const line of renderTable(COLUMNS, rows, { indent: INDENT })) {
+        log(indent(line, INDENT));
+      }
+    }
+
+    if (notFetched.length > 0) {
+      blankLine();
+      paragraph(
+        `These repositories are trusted and their index has not been fetched yet, so ` +
+          `nothing in them is listed: ${notFetched.join(", ")}.`
+      );
+    }
+
+    footer();
+  }
+}

package/src/commands/namespace/show.ts

@@ -0,0 +1,110 @@
+/**
+ * `sous namespace show <ref>`.
+ *
+ * Shows one namespace in full: the repository publishing it, what that
+ * repository says it is for, how much of it this project subscribes to, and
+ * every recipe in it with its latest version, its pinned version and its own
+ * subscription state. It reads only the indexes sous already has on disk.
+ */
+
+import { Args } from "@oclif/core";
+import { BaseCommand } from "../../base-command.js";
+import { subscriptionServiceFor } from "../../lib/repos/subscription-service.js";
+import { catalogContextFor } from "../../lib/repos/catalog-inputs.js";
+import { describeNamespace } from "../../lib/repos/catalog.js";
+import {
+  INDENT,
+  RECIPE_COLUMNS,
+  describeCoverage,
+  factIf,
+  printFacts,
+  recipeRows,
+} from "../../lib/repos/catalog-display.js";
+import { renderTable } from "../../utils/table.js";
+import {
+  blankLine,
+  footer,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showCommandVars,
+  subheading,
+} from "../../utils/formatting.js";
+
+export default class NamespaceShow extends BaseCommand {
+  static description = "Show one namespace and every recipe the repository publishes in it";
+
+  /**
+   * The other spelling of the topic. It lives under a hidden topic, so it is
+   * typable everywhere without ever reaching the top-level listing.
+   */
+  static aliases = ["namespaces:show"];
+
+  static examples = [
+    "<%= config.bin %> namespace show workflow",
+    "<%= config.bin %> namespace show sous-recipes:core",
+  ];
+
+  static args = {
+    ref: Args.string({
+      description: "A namespace, optionally written as 'repository:namespace'",
+      required: true,
+    }),
+  };
+
+  static flags = { ...BaseCommand.baseFlags };
+
+  async run(): Promise<void> {
+    const { args } = await this.parse(NamespaceShow);
+
+    showCommandVars({
+      Project: this.projectLabel,
+      Config: this.configContext.configPath,
+      Namespace: args.ref,
+    });
+
+    const service = subscriptionServiceFor({
+      configContext: this.configContext,
+      settings: this.settings,
+      shellEnv: this.shellEnv,
+    });
+
+    const { inputs } = catalogContextFor({
+      service,
+      sousDir: this.configContext.sousDir,
+      settings: this.settings,
+    });
+
+    const detail = describeNamespace(inputs, args.ref);
+
+    heading(`The namespace ${detail.namespace}`);
+    blankLine();
+
+    printFacts([
+      { label: "Repository", lines: [detail.repo] },
+      ...factIf("Location", detail.repoUrl),
+      ...factIf("About", detail.description),
+      { label: "Recipes", lines: [String(detail.recipes.length)] },
+      { label: "Subscribed", lines: [describeCoverage(detail.subscribed)] },
+    ]);
+
+    blankLine();
+    subheading(`Recipes in ${detail.namespace}`);
+    blankLine();
+
+    if (detail.recipes.length === 0) {
+      paragraph(`The repository ${detail.repo} publishes no recipes in this namespace.`);
+      footer();
+      return;
+    }
+
+    for (const line of renderTable(RECIPE_COLUMNS, recipeRows(detail.recipes), {
+      indent: INDENT,
+    })) {
+      log(indent(line, INDENT));
+    }
+
+    footer();
+  }
+}

package/src/commands/prune.ts

@@ -9,7 +9,6 @@ export default class Prune extends BaseCommand {
   static examples = [
     "<%= config.bin %> prune",
     "<%= config.bin %> prune --dry-run",
-    "<%= config.bin %> prune --project myproject",
   ];
 
   static flags = {
@@ -23,11 +22,10 @@ export default class Prune extends BaseCommand {
   async run(): Promise<void> {
     const { flags } = await this.parse(Prune);
 
-    const project = this.resolveProject(flags.project);
-    const stateFilePath = resolveStateFilePath(project.key, this.settings, this.configContext);
+    const stateFilePath = resolveStateFilePath(this.settings, this.configContext);
 
     showCommandVars({
-      Project: project.name,
+      Project: this.projectLabel,
       Config: this.configContext.configPath,
       "Dry Run": flags["dry-run"],
     });
@@ -35,13 +33,7 @@ export default class Prune extends BaseCommand {
     heading("Pruning");
 
     const buildService = new BuildService();
-    await buildService.prune(
-      project.key,
-      this.settings,
-      stateFilePath,
-      flags["dry-run"],
-      this.configContext
-    );
+    await buildService.prune(this.settings, stateFilePath, flags["dry-run"], this.configContext);
 
     footer();
   }