@sous-io/sous 0.2.37 → 1.0.2

package/src/services/ref-resolver/pruners/command-line-pruner.ts

@@ -1,47 +0,0 @@
-import { RefSource, SOURCE_LABELS } from "../source.js";
-import { makeInjectable } from "../injectable.js";
-import { isLocal } from "./rule-helpers.js";
-import { RuleRefPruner, type RefPruneRule } from "./ref-pruner.js";
-
-/**
- * The command line allows every form a ref has: a bare name, a namespace and
- * recipe, a `repo:` qualifier, a range, a location, a browser URL, a variable
- * and an environment variable name. It refuses a repository on this machine
- * written as a location (it is added by its path), a file inside a recipe (a
- * folder in a repository is a URL copied from the browser) and a glob.
- */
-export class CommandLinePruner extends RuleRefPruner {
-  readonly source = RefSource.CommandLine;
-  readonly place = SOURCE_LABELS[RefSource.CommandLine];
-
-  protected rules(): RefPruneRule[] {
-    return [
-      {
-        matches: isLocal,
-        action: "drop",
-        message:
-          "a repository on this machine is added by its path, and its recipes are then named " +
-          "by their short form.",
-        instead: "'sous repo add <path>', then 'namespace/recipe'",
-      },
-      {
-        matches: (ref) => ref.kind === "recipeFile",
-        action: "drop",
-        message:
-          "a short ref has at most two path segments, a namespace and a recipe. A folder path " +
-          "inside a repository is written as a URL copied from the browser instead.",
-        instead: "'namespace/recipe', or the URL copied from the browser",
-      },
-      {
-        matches: (ref) => ref.glob === true,
-        action: "drop",
-        message:
-          "a name here must be kebab-case (a letter, then letters, digits or hyphens), so a " +
-          "glob pattern is not accepted.",
-        instead: "the name itself",
-      },
-    ];
-  }
-}
-
-makeInjectable(CommandLinePruner);

package/src/services/ref-resolver/pruners/include-pruner.ts

@@ -1,66 +0,0 @@
-import { splitSegments } from "../glob.js";
-import { makeInjectable } from "../injectable.js";
-import { rangeOf } from "../parts.js";
-import { RefSource, SOURCE_LABELS } from "../source.js";
-import type { SousRef } from "../types.js";
-import { RuleRefPruner, type RefPruneRule } from "./ref-pruner.js";
-import { hasLocation } from "./rule-helpers.js";
-
-/** The path of a recipe file ref, or an empty string for any other ref. */
-function pathOf(ref: SousRef): string {
-  return ref.kind === "recipeFile" ? ref.path : "";
-}
-
-/** The spelling a refused include is told to use: `namespace/recipe/path`. */
-function instead(ref: SousRef): string {
-  if (ref.kind !== "recipeFile") return "'namespace/recipe/path/to/file.md'";
-  const namespace = ref.recipe.namespace?.name ?? "namespace";
-  return `'${namespace}/${ref.recipe.name}/${ref.path}'`;
-}
-
-/**
- * The path of a template include line, once its sigil is taken off. Only a
- * file inside a recipe is allowed, and its path, namespace and recipe name may
- * be globs. A `repo:` qualifier may name the repository by the short name this
- * project gave it. A location never counts, and neither does a version range
- * (the version is the one the project pins).
- */
-export class IncludePruner extends RuleRefPruner {
-  readonly source = RefSource.Include;
-  readonly place = SOURCE_LABELS[RefSource.Include];
-
-  protected rules(): RefPruneRule[] {
-    return [
-      {
-        matches: (ref) => ref.kind !== "recipeFile",
-        action: "drop",
-        message:
-          "an include line names a file inside a recipe: its namespace, its recipe and the " +
-          "path inside it.",
-        instead,
-      },
-      {
-        matches: hasLocation,
-        action: "drop",
-        message: "an include line never names a location; it reads the recipes this project pins.",
-        instead,
-      },
-      {
-        matches: (ref) => rangeOf(ref) !== undefined,
-        action: "drop",
-        message:
-          "an include line takes no version range; the version of a recipe is the one this " +
-          "project pins.",
-        instead,
-      },
-      {
-        matches: (ref) => splitSegments(pathOf(ref)).some((part) => part === "." || part === ".."),
-        action: "drop",
-        message: "the path inside a recipe may not contain '.' or '..' segments.",
-        instead,
-      },
-    ];
-  }
-}
-
-makeInjectable(IncludePruner);

package/src/services/ref-resolver/pruners/manifest-pruner.ts

@@ -1,130 +0,0 @@
-import type { RepoProvider } from "../../../lib/repos/providers/index.js";
-import { makeInjectable } from "../injectable.js";
-import { REF_TOKENS } from "../tokens.js";
-import { providerById } from "../../../lib/repos/providers/index.js";
-import { rangeOf } from "../parts.js";
-import { RefSource, SOURCE_LABELS } from "../source.js";
-import type { SousRef } from "../types.js";
-import { RuleRefPruner, type RefPruneRule } from "./ref-pruner.js";
-import { hasRepoName, isLocal, isStoredKind, KEBAB_REASON, shortKey } from "./rule-helpers.js";
-
-/**
- * An entry of a recipe manifest's `depends` or `subscribes` list. A bare ref
- * names a namespace or a recipe in the same repository, and a location names
- * one in another. A manifest is published, so its names are stored lowercase.
- * It refuses a `repo:` qualifier (one project's private name for a repository),
- * a repository on this machine, a whole repository with nothing inside it, and
- * everything that is not a namespace or a recipe.
- */
-export class ManifestPruner extends RuleRefPruner {
-  readonly source = RefSource.Manifest;
-  readonly place = SOURCE_LABELS[RefSource.Manifest];
-
-  /**
-   * @param providers - The providers that format a locator, for what to write instead.
-   */
-  constructor(private readonly providers: RepoProvider[]) {
-    super();
-  }
-
-  protected rules(): RefPruneRule[] {
-    return [
-      {
-        matches: hasRepoName,
-        action: "drop",
-        message:
-          "a 'repo:' qualifier names a short name that only the consuming project knows, so it " +
-          "cannot appear in a published manifest.",
-        instead: (ref) =>
-          `'${shortKey(ref).toLowerCase()}' for a recipe in this same repository, or name the ` +
-          `other repository by its location, as in ` +
-          `'github://owner/repository/${shortKey(ref).toLowerCase()}'`,
-      },
-      {
-        matches: isLocal,
-        action: "drop",
-        message:
-          "a local repository is a consumer's convenience, not a published location, so a " +
-          "manifest cannot depend on one.",
-        instead:
-          "the recipe's published location, such as 'github://owner/repository/namespace/recipe'",
-      },
-      {
-        matches: (ref) => ref.kind === "recipeFile",
-        action: "drop",
-        message:
-          "a short ref has at most two path segments, a namespace and a recipe. A folder path " +
-          "inside a repository is written as a URL copied from the browser instead.",
-        instead: "'namespace/recipe', or the URL copied from the browser",
-      },
-      {
-        matches: (ref) => ref.glob === true,
-        action: "drop",
-        message: KEBAB_REASON,
-        instead: "'namespace/recipe'",
-      },
-      {
-        matches: (ref) => ref.kind === "repo" && ref.browsed === undefined && ref.location !== undefined,
-        action: "drop",
-        message: (ref) =>
-          `it names the repository at ${locationUrl(ref)} and nothing inside it, and a ` +
-          "dependency is a namespace or a recipe.",
-        instead: (ref) => `'${this.locator(ref)}'`,
-      },
-      {
-        matches: (ref) => ref.kind === "recipe" && ref.namespace === undefined,
-        action: "drop",
-        message: (ref) =>
-          rangeOf(ref) === undefined
-            ? "a recipe is named with its namespace here, and a bare name is read as a " +
-              "namespace."
-            : "a version range applies to a recipe, and namespaces are not versioned. Name " +
-              "the recipe with its namespace.",
-        instead: "'namespace/recipe', optionally with a range such as '@^1.1'",
-      },
-      {
-        matches: (ref) => !isStoredKind(ref) && !(ref.kind === "repo" && ref.browsed !== undefined),
-        action: "drop",
-        message: KEBAB_REASON,
-        instead: "'namespace/recipe'",
-      },
-      {
-        matches: (ref) => ref.vars !== undefined,
-        action: "drop",
-        message: "a manifest's dependency carries no query values.",
-        instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-      },
-    ];
-  }
-
-  protected normalize(ref: SousRef): SousRef {
-    if (ref.kind === "namespace") return { ...ref, name: ref.name.toLowerCase() };
-    if (ref.kind === "recipe") {
-      return {
-        ...ref,
-        name: ref.name.toLowerCase(),
-        ...(ref.namespace === undefined
-          ? {}
-          : { namespace: { ...ref.namespace, name: ref.namespace.name.toLowerCase() } }),
-      };
-    }
-    return ref;
-  }
-
-  /** The canonical locator for something inside the ref's repository, as an example. */
-  private locator(ref: SousRef): string {
-    if (ref.kind !== "repo" || ref.location === undefined) return "github://owner/repository";
-    const { host, repoPath } = ref.location;
-    const provider = providerById(ref.location.provider, this.providers);
-    return provider === undefined
-      ? `${ref.location.url}/namespace/recipe`
-      : provider.formatLocator(host, repoPath, "namespace/recipe");
-  }
-}
-
-/** Where a located ref says its repository is. */
-function locationUrl(ref: SousRef): string {
-  return ref.kind === "repo" && ref.location !== undefined ? ref.location.url : "that location";
-}
-
-makeInjectable(ManifestPruner, [{ multi: REF_TOKENS.Provider }]);

package/src/services/ref-resolver/pruners/ref-pruner.ts

@@ -1,135 +0,0 @@
-/**
- * Pruners: the place a ref was written decides which readings of it count.
- *
- * The parser returns every reading. One pruner per `RefSource` then drops the
- * readings that place does not allow, each with the reason and what to write
- * there instead, so a refused ref is an error that tells the writer how to fix
- * it rather than a puzzle.
- */
-
-import { ConfigError } from "../../../lib/errors.js";
-import type { RefSource } from "../source.js";
-import type { SousRef } from "../types.js";
-
-/** One reading a pruner refused. */
-export class DroppedRef {
-  /**
-   * @param ref - The reading.
-   * @param reason - Why this place does not allow it, as a sentence.
-   * @param instead - What to write there instead, as it would appear after "Write".
-   */
-  constructor(
-    readonly ref: SousRef,
-    readonly reason: string,
-    readonly instead?: string
-  ) {}
-
-  /** The reason, with what to write instead on a line of its own. */
-  describe(): string {
-    return this.instead === undefined
-      ? this.reason
-      : `${this.reason}\n    Write ${this.instead} instead.`;
-  }
-}
-
-/** What a pruner decided about a list of readings. */
-export class RefPruneResult {
-  /**
-   * @param kept - The readings this place allows, in the order they came.
-   * @param dropped - The readings it refuses, each with its reason.
-   * @param warnings - Sentences about readings that were kept all the same.
-   */
-  constructor(
-    readonly kept: SousRef[] = [],
-    readonly dropped: DroppedRef[] = [],
-    readonly warnings: string[] = []
-  ) {}
-}
-
-/** Decides which readings of a ref count in one place. */
-export interface RefPruner {
-  /** The place this pruner speaks for. */
-  readonly source: RefSource;
-  /** What the place is called in a sentence, for the error. */
-  readonly place: string;
-  /**
-   * Splits the readings into those the place allows and those it refuses.
-   *
-   * @param candidates - Every reading the parser returned.
-   * @param input - The ref exactly as it was written, for messages.
-   */
-  prune(candidates: SousRef[], input: string): RefPruneResult;
-}
-
-/** What a rule does with a reading it matches. */
-export type RefPruneAction = "drop" | "warn" | "throw";
-
-/** The text of a rule's message: fixed, or made from the reading and what was written. */
-export type RefRuleText = string | ((ref: SousRef, input: string) => string);
-
-/** One rule of a pruner: when it matches a reading, what it does and why. */
-export type RefPruneRule = {
-  /** True when the rule applies to this reading. */
-  matches: (ref: SousRef, input: string) => boolean;
-  /** `drop` removes the reading, `warn` keeps it with a warning, `throw` fails at once. */
-  action: RefPruneAction;
-  /** The reason: why the place refuses the reading, or what is wrong with it. */
-  message: RefRuleText;
-  /** What to write instead, which makes the error say how to fix it. */
-  instead?: RefRuleText;
-};
-
-/** Resolves a rule's text for one reading. */
-function textOf(text: RefRuleText, ref: SousRef, input: string): string {
-  return typeof text === "function" ? text(ref, input) : text;
-}
-
-/**
- * A pruner that applies an ordered list of rules. The first rule that matches
- * a reading decides; a reading no rule matches is kept. A subclass lists its
- * rules, and may rewrite a kept reading (a manifest stores lowercase names).
- */
-export abstract class RuleRefPruner implements RefPruner {
-  abstract readonly source: RefSource;
-  abstract readonly place: string;
-
-  /** The rules, in the order they are tried. */
-  protected abstract rules(): RefPruneRule[];
-
-  /**
-   * Rewrites a reading this place keeps. Most places keep it as it is.
-   *
-   * @param ref - A kept reading.
-   */
-  protected normalize(ref: SousRef): SousRef {
-    return ref;
-  }
-
-  prune(candidates: SousRef[], input: string): RefPruneResult {
-    const rules = this.rules();
-    const result = new RefPruneResult();
-
-    for (const ref of candidates) {
-      const rule = rules.find((entry) => entry.matches(ref, input));
-      if (rule === undefined) {
-        result.kept.push(this.normalize(ref));
-        continue;
-      }
-      const message = textOf(rule.message, ref, input);
-      if (rule.action === "throw") throw new ConfigError(message);
-      if (rule.action === "warn") {
-        result.kept.push(this.normalize(ref));
-        result.warnings.push(message);
-        continue;
-      }
-      result.dropped.push(
-        new DroppedRef(
-          ref,
-          message,
-          rule.instead === undefined ? undefined : textOf(rule.instead, ref, input)
-        )
-      );
-    }
-    return result;
-  }
-}

package/src/services/ref-resolver/pruners/rule-helpers.ts

@@ -1,44 +0,0 @@
-/**
- * Predicates and wording the per-place pruners share.
- */
-
-import { locationOf, namespaceOf, recipeOf, repoOf } from "../parts.js";
-import type { SousRef } from "../types.js";
-
-/** True when the ref names a repository that lives on this machine. */
-export function isLocal(ref: SousRef): boolean {
-  return locationOf(ref)?.provider === "local";
-}
-
-/** True when the ref names where its repository lives. */
-export function hasLocation(ref: SousRef): boolean {
-  return locationOf(ref) !== undefined;
-}
-
-/** True when the ref is qualified by a repository short name (`repo:`). */
-export function hasRepoName(ref: SousRef): boolean {
-  return ref.kind !== "repo" && repoOf(ref)?.name !== undefined;
-}
-
-/** True when the ref is a namespace, or a recipe that names its namespace. */
-export function isStoredKind(ref: SousRef): boolean {
-  return ref.kind === "namespace" || (ref.kind === "recipe" && ref.namespace !== undefined);
-}
-
-/**
- * The short key of a namespace or a recipe: `namespace` or `namespace/recipe`,
- * as the lockfile and the index store it, in the case it was written.
- *
- * @param ref - A namespace or a recipe.
- */
-export function shortKey(ref: SousRef): string {
-  const namespace = namespaceOf(ref)?.name;
-  const recipe = ref.kind === "namespace" ? undefined : recipeOf(ref)?.name;
-  if (namespace === undefined) return recipe ?? "";
-  return recipe === undefined ? namespace : `${namespace}/${recipe}`;
-}
-
-/** The sentence for a reading that is not a name a place can hold. */
-export const KEBAB_REASON =
-  "only a namespace or a recipe can be named here, and their names must be kebab-case: " +
-  "a letter, then letters, digits or hyphens.";

package/src/services/ref-resolver/pruners/stored-key-pruner.ts

@@ -1,136 +0,0 @@
-/**
- * What a config file and a stored key have in common: only `namespace` or
- * `namespace/recipe`, lowercase, with nothing else attached. They differ in
- * what they tell a writer to do instead.
- */
-
-import { makeInjectable } from "../injectable.js";
-import { rangeOf, repoOf } from "../parts.js";
-import { RefSource, SOURCE_LABELS } from "../source.js";
-import { RuleRefPruner, type RefPruneRule } from "./ref-pruner.js";
-import {
-  hasLocation,
-  hasRepoName,
-  isStoredKind,
-  KEBAB_REASON,
-  shortKey,
-} from "./rule-helpers.js";
-
-/** A subscription key in a config layer. */
-export class ConfigPruner extends RuleRefPruner {
-  readonly source = RefSource.Config;
-  readonly place = SOURCE_LABELS[RefSource.Config];
-
-  protected rules(): RefPruneRule[] {
-    return [
-      {
-        matches: hasLocation,
-        action: "drop",
-        message:
-          "a config file names a subscription by its short form; the repository it lives in is " +
-          "a separate entry under 'repos'.",
-        instead: (_ref, input) =>
-          `'namespace/recipe', or run 'sous subscribe ${input.trim()}', which adds the ` +
-          "repository and writes the subscription in its short form",
-      },
-      {
-        matches: (ref) => !isStoredKind(ref),
-        action: "drop",
-        message: KEBAB_REASON,
-        instead: "'namespace/recipe'",
-      },
-      {
-        matches: hasRepoName,
-        action: "drop",
-        message: (ref) =>
-          "the repository a subscription resolves into is recorded in the lockfile, not in the " +
-          "key. To choose between repositories, run " +
-          `'sous subscribe ${repoOf(ref)?.name}:${shortKey(ref).toLowerCase()}', which records the choice.`,
-        instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-      },
-      {
-        matches: (ref) => ref.glob === true,
-        action: "drop",
-        message: "a glob pattern is not a stored key; names here must be kebab-case.",
-        instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-      },
-      {
-        matches: (ref) => rangeOf(ref) !== undefined,
-        action: "drop",
-        message: "a subscription's version range belongs in the entry's own 'range' field.",
-        instead: (ref) => `'${shortKey(ref).toLowerCase()}': { range: '${rangeOf(ref)}' }`,
-      },
-      ...sharedStoredRules(),
-    ];
-  }
-}
-
-/** A key sous stored: the lockfile, the index and the store. */
-export class LockfilePruner extends RuleRefPruner {
-  readonly source = RefSource.Lockfile;
-  readonly place = SOURCE_LABELS[RefSource.Lockfile];
-
-  protected rules(): RefPruneRule[] {
-    return [
-      {
-        matches: hasLocation,
-        action: "drop",
-        message: "a stored key never names a location.",
-        instead: "'namespace/recipe'",
-      },
-      {
-        matches: (ref) => !isStoredKind(ref),
-        action: "drop",
-        message: KEBAB_REASON,
-        instead: "'namespace/recipe'",
-      },
-      {
-        matches: hasRepoName,
-        action: "drop",
-        message: "a stored key never names a repository.",
-        instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-      },
-      {
-        matches: (ref) => ref.glob === true,
-        action: "drop",
-        message: "a glob pattern is not a stored key; names here must be kebab-case.",
-        instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-      },
-      {
-        matches: (ref) => rangeOf(ref) !== undefined,
-        action: "drop",
-        message: "a stored key carries no version range.",
-        instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-      },
-      ...sharedStoredRules(),
-    ];
-  }
-}
-
-/** The rules a config key and a stored key share, after their own. */
-function sharedStoredRules(): RefPruneRule[] {
-  return [
-    {
-      matches: (ref) => ref.kind === "namespace" && ref.wildcard === true,
-      action: "drop",
-      message: "a whole namespace is stored as its name alone.",
-      instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-    },
-    {
-      matches: (ref) => ref.vars !== undefined,
-      action: "drop",
-      message: "a stored key carries no query values.",
-      instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-    },
-    {
-      matches: (ref) => shortKey(ref) !== shortKey(ref).toLowerCase(),
-      action: "drop",
-      message: "stored names are lowercase.",
-      instead: (ref) => `'${shortKey(ref).toLowerCase()}'`,
-    },
-  ];
-}
-
-makeInjectable(ConfigPruner);
-
-makeInjectable(LockfilePruner);

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

@@ -1,62 +0,0 @@
-/**
- * Helpers around the resolver, for callers that have no container: the ones
- * that need a resolver use the shared one, and the ones that only work on refs
- * need none.
- */
-
-import { sharedRefResolver } from "./container.js";
-import { RefResolveResult } from "./ref-resolve-result.js";
-import type { RefInString } from "./ref-resolver-service.js";
-import { RefSource } from "./source.js";
-import type { RefKind, SousRef } from "./types.js";
-
-/**
- * True when the text is a ref the place allows. A caller that finds text that
- * looks like a ref but is not (an include line, say) treats it as an error.
- *
- * @param input - The ref exactly as it was written.
- * @param from - Where it was written.
- */
-export function isValidRef(input: string, from: RefSource = RefSource.CommandLine): boolean {
-  return sharedRefResolver().isValidRef(input, from);
-}
-
-/**
- * Every valid ref in a longer text, with the punctuation around each word taken off.
- *
- * @param text - The text to search.
- * @param from - Where the text was written.
- */
-export function getRefsInString(text: string, from: RefSource = RefSource.CommandLine): RefInString[] {
-  return sharedRefResolver().getRefsInString(text, from);
-}
-
-/**
- * The best ref of a result, or the first reading of a string the place allows.
- *
- * @param source - A resolve result, or a written ref.
- * @param from - Where a written ref was written.
- * @returns The ref, or undefined when a result holds none.
- */
-export function getFirstRef(
-  source: RefResolveResult | string,
-  from: RefSource = RefSource.CommandLine
-): SousRef | undefined {
-  return typeof source === "string" ? sharedRefResolver().parse(source, from).first() : source.first();
-}
-
-/**
- * Keeps the refs a caller can use: those of the given kinds, or those a
- * predicate accepts.
- *
- * pruneRefs(result.refs, ["namespace", "recipe"]);
- *
- * @param refs - The refs to narrow.
- * @param keep - The kinds to keep, or a test.
- */
-export function pruneRefs(
-  refs: readonly SousRef[],
-  keep: readonly RefKind[] | ((ref: SousRef) => boolean)
-): SousRef[] {
-  return refs.filter((ref) => (typeof keep === "function" ? keep(ref) : keep.includes(ref.kind)));
-}