@sous-io/sous 0.2.31 → 0.2.33

package/src/services/ref-resolver/parser/name-path-splitter.ts

@@ -0,0 +1,200 @@
+/**
+ * Reads the names and paths of a ref: the namespace, the recipe, the path of a
+ * file inside a recipe, and the name of a variable after a `.`.
+ */
+
+import { makeInjectable } from "../injectable.js";
+import {
+  ENV_VAR_NAME,
+  hasGlob,
+  isGlobName,
+  NAME_ANY_CASE,
+  splitSegments,
+  VARIABLE_NAME,
+} from "../glob.js";
+import type { NamespaceRef, RecipeRef, SousRef } from "../types.js";
+import { BaseRefSplitter, finishRef, type PartialRef } from "./partial-ref.js";
+
+/** The characters a path inside a recipe may use: anything but whitespace and a backslash. */
+const FILE_PATH = /^[^\s\\]+$/;
+
+/** True when a segment is a name (in any case) or a glob pattern standing for one. */
+function isName(segment: string): boolean {
+  return NAME_ANY_CASE.test(segment) || isGlobName(segment);
+}
+
+/** The sentence for a name that is not one. */
+function badName(what: string, name: string): string {
+  return `the ${what} '${name}' must be kebab-case: a letter, then letters, digits or hyphens.`;
+}
+
+/** The sentence for a range that has nothing to apply to. */
+const NAMESPACE_NOT_VERSIONED =
+  "a version range applies to a recipe, and namespaces are not versioned. Name a " +
+  "recipe, as in 'workflow/task-files@^1.2.0'.";
+
+/**
+ * Splits what is left of the text at `/` and reads it every way it can be
+ * read:
+ *
+ *     workflow                      a namespace, a recipe, a repository or a variable
+ *     workflow/alpha                a recipe
+ *     workflow/*                    a namespace spelled out, and every recipe in it
+ *     task-files.apiUrl             a variable of a recipe
+ *     workflow/alpha.apiUrl         a variable of a recipe in a namespace
+ *     workflow/alpha/SKILL.md       a file inside a recipe
+ *
+ * Any name or path may be a glob pattern. The text is also left unread, so the
+ * environment variable splitter may read the same word.
+ */
+export class NamePathSplitter extends BaseRefSplitter {
+  readonly order = 500;
+
+  protected read(state: PartialRef): PartialRef[] {
+    const segments = splitSegments(state.rest);
+    const out: PartialRef[] = [state];
+    const make = (ref: SousRef): void => {
+      out.push(finishRef(state, ref));
+    };
+
+    if (segments[0] === "") {
+      state.problems.push("the namespace is empty.");
+      return out;
+    }
+    const last = segments[segments.length - 1];
+    if (segments.length > 1 && segments.includes("")) {
+      state.problems.push(
+        last === ""
+          ? "the recipe name after '/' is empty."
+          : "a ref has an empty segment between two '/'."
+      );
+      return out;
+    }
+
+    const repo = state.repo;
+    const range = state.range;
+    const withGlob = (names: string[]) => (names.some(hasGlob) ? { glob: true as const } : {});
+    const ns = (name: string): NamespaceRef => ({
+      kind: "namespace",
+      name,
+      ...(repo === undefined ? {} : { repo }),
+    });
+
+    if (segments.length === 1) {
+      const text = segments[0]!;
+      const dot = text.indexOf(".");
+      // A location names a repository, so only a namespace can follow it here.
+      const located = repo?.location !== undefined;
+
+      if (!located && dot > 0 && dot < text.length - 1) {
+        const left = text.slice(0, dot);
+        const right = text.slice(dot + 1);
+        if (isName(left) && (VARIABLE_NAME.test(right) || isGlobName(right))) {
+          if (range === undefined) {
+            make({
+              kind: "variable",
+              name: right,
+              recipe: {
+                kind: "recipe",
+                name: left,
+                ...(repo === undefined ? {} : { repo }),
+              },
+              ...withGlob([left, right]),
+            });
+          }
+        }
+      }
+
+      if (isName(text)) {
+        if (range === undefined) {
+          make({ ...ns(text), ...withGlob([text]) });
+          if (repo === undefined) make({ kind: "repo", name: text, ...withGlob([text]) });
+        } else {
+          state.problems.push(NAMESPACE_NOT_VERSIONED);
+        }
+        if (!located) {
+          make({
+            kind: "recipe",
+            name: text,
+            ...(repo === undefined ? {} : { repo }),
+            ...(range === undefined ? {} : { range }),
+            ...withGlob([text]),
+          });
+        }
+      }
+      if (!located && range === undefined && (VARIABLE_NAME.test(text) || isGlobName(text))) {
+        make({
+          kind: "variable",
+          name: text,
+          ...(repo === undefined ? {} : { repo }),
+          ...withGlob([text]),
+        });
+      }
+      const readsAsOther =
+        repo === undefined && (VARIABLE_NAME.test(text) || ENV_VAR_NAME.test(text));
+      if (!isName(text) && !readsAsOther && dot <= 0) {
+        state.problems.push(badName("namespace", text));
+      }
+      return out;
+    }
+
+    const [namespace, second] = segments as [string, string, ...string[]];
+    if (!isName(namespace)) {
+      state.problems.push(badName("namespace", namespace));
+      return out;
+    }
+
+    if (segments.length === 2) {
+      const dot = second.indexOf(".");
+      if (second === "*") {
+        if (range === undefined) make({ ...ns(namespace), wildcard: true, ...withGlob([namespace]) });
+        else state.problems.push(NAMESPACE_NOT_VERSIONED);
+      }
+      if (dot > 0 && dot < second.length - 1 && range === undefined) {
+        const left = second.slice(0, dot);
+        const right = second.slice(dot + 1);
+        if (isName(left) && (VARIABLE_NAME.test(right) || isGlobName(right))) {
+          make({
+            kind: "variable",
+            name: right,
+            recipe: { kind: "recipe", name: left, namespace: ns(namespace) },
+            ...withGlob([namespace, left, right]),
+          });
+        }
+      }
+      if (isName(second)) {
+        make({
+          kind: "recipe",
+          name: second,
+          namespace: ns(namespace),
+          ...(range === undefined ? {} : { range }),
+          ...withGlob([namespace, second]),
+        });
+      } else if (dot <= 0) {
+        state.problems.push(badName("recipe name", second));
+      }
+      return out;
+    }
+
+    const path = segments.slice(2).join("/");
+    if (!isName(second)) {
+      state.problems.push(badName("recipe name", second));
+      return out;
+    }
+    if (!FILE_PATH.test(path)) {
+      state.problems.push(`the path '${path}' inside a recipe holds a space or a backslash.`);
+      return out;
+    }
+    const recipe: RecipeRef = { kind: "recipe", name: second, namespace: ns(namespace) };
+    make({
+      kind: "recipeFile",
+      path,
+      recipe,
+      ...(range === undefined ? {} : { range }),
+      ...withGlob([namespace, second, path]),
+    });
+    return out;
+  }
+}
+
+makeInjectable(NamePathSplitter);

package/src/services/ref-resolver/parser/partial-ref.ts

@@ -0,0 +1,84 @@
+/**
+ * The shapes the parser works with: a reading in progress, and the splitter
+ * that advances it.
+ */
+
+import type { RepoRef, SousRef } from "../types.js";
+
+/**
+ * A reading in progress. A splitter takes some of `rest` and records what it
+ * found beside it; a reading is finished when `ref` is set and `rest` is empty.
+ */
+export type PartialRef = {
+  /** The whole input, trimmed. Never changes. */
+  input: string;
+  /** The text no splitter has read yet. */
+  rest: string;
+  /** The `?name=value` pairs read so far. */
+  vars?: Record<string, string>;
+  /** The version range read so far. */
+  range?: string;
+  /** The repository qualifier read so far. */
+  repo?: RepoRef;
+  /** The finished ref, once a splitter has made one. */
+  ref?: SousRef;
+  /**
+   * Why a splitter turned the text down, shared by every reading of one input.
+   * The parser quotes these when nothing reads, and says nothing of them
+   * otherwise.
+   */
+  problems: string[];
+};
+
+/**
+ * One step of the parser. A splitter reads whatever part of `rest` it
+ * recognizes (the front or the end) and returns EVERY way to read it, as
+ * partial refs of its own. A splitter that does not recognize anything returns
+ * the state unchanged, and one that could also leave the text for a later
+ * splitter returns the state among its readings. A splitter never looks at
+ * where the ref was written.
+ */
+export interface RefSplitter {
+  /** Where this splitter runs among the others: lowest first. */
+  readonly order: number;
+  /**
+   * Advances one reading.
+   *
+   * @param state - The reading so far.
+   * @returns Every reading that can follow it.
+   */
+  split(state: PartialRef): PartialRef[];
+}
+
+/**
+ * A splitter that leaves a finished reading alone, so each subclass only says
+ * how it reads text that is still unread.
+ */
+export abstract class BaseRefSplitter implements RefSplitter {
+  abstract readonly order: number;
+
+  split(state: PartialRef): PartialRef[] {
+    if (state.ref !== undefined) return [state];
+    return this.read(state);
+  }
+
+  /**
+   * Reads an unfinished reading.
+   *
+   * @param state - A reading with no finished ref.
+   */
+  protected abstract read(state: PartialRef): PartialRef[];
+}
+
+/**
+ * The state with a finished ref in it, carrying the query values and, for the
+ * kinds that take one, the version range.
+ *
+ * @param state - The reading so far.
+ * @param ref - The finished ref.
+ */
+export function finishRef(state: PartialRef, ref: SousRef): PartialRef {
+  const withVars: SousRef =
+    state.vars === undefined ? ref : ({ ...ref, vars: state.vars } as SousRef);
+  return { ...state, rest: "", ref: withVars };
+}

package/src/services/ref-resolver/parser/query-splitter.ts

@@ -0,0 +1,61 @@
+/**
+ * Reads the `?name=value&name=value` at the end of a ref.
+ */
+
+import { makeInjectable } from "../injectable.js";
+import { BaseRefSplitter, type PartialRef } from "./partial-ref.js";
+
+/** A URL that names its scheme, such as `https://` or `github://`. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/** One pair of a query: a percent-encoded name, `=`, and a percent-encoded value. */
+const PAIR = /^([A-Za-z0-9\-._~%+!*'(),:@/$]+)=([A-Za-z0-9\-._~%+!*'(),:@/$]*)$/;
+
+/**
+ * The decoded pairs of a query, or undefined when it is not a valid
+ * percent-encoded query string.
+ *
+ * decodeQuery("a=1&b=two%20words"); // -> { a: "1", b: "two words" }
+ * decodeQuery("a=%zz"); // -> undefined
+ *
+ * @param query - The text after the `?`.
+ */
+export function decodeQuery(query: string): Record<string, string> | undefined {
+  if (query.length === 0) return undefined;
+  const vars: Record<string, string> = {};
+  for (const pair of query.split("&")) {
+    const match = PAIR.exec(pair);
+    if (match === null) return undefined;
+    try {
+      vars[decodeURIComponent(match[1]!.replace(/\+/g, " "))] = decodeURIComponent(
+        match[2]!.replace(/\+/g, " ")
+      );
+    } catch {
+      return undefined;
+    }
+  }
+  return vars;
+}
+
+/**
+ * Takes a valid, percent-encoded query off the end of the text and keeps its
+ * pairs. A string that starts with a URL scheme is left alone, because a URL's
+ * query belongs to the URL. When the text before the `?` could also be a glob
+ * path holding a `?` and an `=`, both readings are kept.
+ */
+export class QuerySplitter extends BaseRefSplitter {
+  readonly order = 100;
+
+  protected read(state: PartialRef): PartialRef[] {
+    if (SCHEME.test(state.rest)) return [state];
+    const mark = state.rest.lastIndexOf("?");
+    if (mark <= 0) return [state];
+
+    const vars = decodeQuery(state.rest.slice(mark + 1));
+    if (vars === undefined) return [state];
+
+    return [{ ...state, rest: state.rest.slice(0, mark), vars: { ...state.vars, ...vars } }, state];
+  }
+}
+
+makeInjectable(QuerySplitter);

package/src/services/ref-resolver/parser/range-splitter.ts

@@ -0,0 +1,52 @@
+/**
+ * Reads the `@^1.2` version range at the end of a ref.
+ */
+
+import { makeInjectable } from "../injectable.js";
+import semver from "semver";
+import { BaseRefSplitter, type PartialRef } from "./partial-ref.js";
+
+/** A URL that names its scheme, such as `https://` or `github://`. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/** The `scp`-style SSH form, as in `git@github.com:owner/name.git`. */
+const SCP = /^[^@\s/:]+@([^@\s/:]+):(.+)$/s;
+
+/**
+ * Takes a version range off the end of the text: whatever follows the last `@`
+ * that comes after the last `/`, so the `@` of an SSH remote
+ * (`git@host:owner/repo`) is never mistaken for one. A range that is not a
+ * semantic version range is left in the text, where a later splitter either
+ * accepts it as part of a path or turns it down.
+ */
+export class RangeSplitter extends BaseRefSplitter {
+  readonly order = 200;
+
+  protected read(state: PartialRef): PartialRef[] {
+    const text = state.rest;
+    const at = text.lastIndexOf("@");
+    if (at === -1 || at < text.lastIndexOf("/")) return [state];
+
+    const before = text.slice(0, at).trim();
+    const range = text.slice(at + 1).trim();
+
+    if (range.length === 0) {
+      state.problems.push("the '@' is not followed by a version range.");
+      return [];
+    }
+    if (before.includes("@") && !SCHEME.test(before) && !SCP.test(before)) {
+      state.problems.push("a ref may carry at most one '@' version range.");
+      return [];
+    }
+    if (semver.validRange(range) === null) {
+      state.problems.push(
+        `'${range}' is not a version range. Ranges follow npm's rules, such as '^1.2.0', ` +
+          "'~2.1', '>=1.0.0 <2.0.0' or '*'."
+      );
+      return [state];
+    }
+    return [{ ...state, rest: before, range }];
+  }
+}
+
+makeInjectable(RangeSplitter);

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

@@ -0,0 +1,115 @@
+/**
+ * The ref parser: the one place a written ref becomes the things it could mean.
+ *
+ * It is context free. It never asks where the ref was written (that is for a
+ * pruner) and never asks what exists (that is for a lookup); it returns EVERY
+ * way the text can be read, because some forms read more than one way: a bare
+ * `workflow` is a namespace, a recipe, a repository, a variable and an
+ * environment variable name, and a GitLab URL with nested groups does not say
+ * where the project path ends.
+ *
+ * The parser is a list of splitters, ordered by their `order`. Each reads
+ * whatever part of the remaining text it recognizes and returns every way to
+ * read it; the parser feeds every reading through every splitter with
+ * `flatMap`, and keeps the readings that ended with a finished ref and no text
+ * left over. A plugin adds a form by adding a splitter.
+ */
+
+import { makeInjectable } from "../injectable.js";
+import { REF_TOKENS } from "../tokens.js";
+import { ConfigError } from "../../../lib/errors.js";
+import type { RefSplitter, PartialRef } from "./partial-ref.js";
+import { REF_KINDS, type SousRef } from "../types.js";
+
+/** The forms a ref may take, for the reminder under a ref that does not parse. */
+const SYNTAX_HELP =
+  "A ref is written as 'namespace', 'namespace/recipe', 'repo:namespace/recipe', " +
+  "'namespace/recipe/path/to/file.md', 'namespace/recipe.variable', an environment variable " +
+  "name, any of those with '@<range>' or '?name=value', or a location such as " +
+  "'github://owner/repository/namespace/recipe' or a URL copied from the browser.";
+
+/** Parses written refs into every reading they have. */
+export class RefParser {
+  private readonly splitters: RefSplitter[];
+
+  /**
+   * @param splitters - The splitters, in any order; they run by their `order`.
+   */
+  constructor(splitters: RefSplitter[]) {
+    this.splitters = [...splitters].sort((left, right) => left.order - right.order);
+  }
+
+  /**
+   * Every reading of a written ref.
+   *
+   * parser.parse("workflow/alpha@^1.2");
+   * // -> [{ kind: "recipe", name: "alpha", namespace: { kind: "namespace", name: "workflow" },
+   * //       range: "^1.2" }]
+   *
+   * @param input - The ref exactly as it was written.
+   * @returns Every reading, never empty. Text that fits no form raises a ConfigError.
+   */
+  parse(input: string): SousRef[] {
+    if (typeof input !== "string") throw this.refError(String(input), "a ref must be a string.");
+
+    const trimmed = input.trim();
+    if (trimmed.length === 0) throw this.refError(input, "a ref must not be empty.");
+    if (trimmed.startsWith("@")) {
+      throw this.refError(
+        input,
+        "refs take no '@' prefix. The '@' character introduces a version range only, " +
+          "as in 'workflow/task-files@^1.2.0'."
+      );
+    }
+    if (trimmed.startsWith("~")) {
+      throw this.refError(
+        input,
+        "refs take no '~' prefix. The '~' sigil belongs to template include lines " +
+          "('@~workflow/file.md'); a ref itself is written without it."
+      );
+    }
+
+    const problems: string[] = [];
+    let states: PartialRef[] = [{ input: trimmed, rest: trimmed, problems }];
+    for (const splitter of this.splitters) {
+      states = states.flatMap((state) => splitter.split(state));
+      if (states.length === 0) break;
+    }
+
+    const seen = new Set<string>();
+    const refs: SousRef[] = [];
+    for (const state of states) {
+      if (state.ref === undefined || state.rest !== "") continue;
+      const key = JSON.stringify(state.ref);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      refs.push(state.ref);
+    }
+    // Kinds in their documented order, whatever order the splitters made them in.
+    if (refs.length > 0) {
+      return refs
+        .map((ref, position) => ({ ref, position }))
+        .sort(
+          (left, right) =>
+            REF_KINDS.indexOf(left.ref.kind) - REF_KINDS.indexOf(right.ref.kind) ||
+            left.position - right.position
+        )
+        .map((entry) => entry.ref);
+    }
+
+    const reasons = [...new Set(problems)];
+    if (reasons.length === 0) throw this.refError(input, "it does not fit any form of a ref.");
+    if (reasons.length === 1) throw this.refError(input, reasons[0]!);
+    throw this.refError(
+      input,
+      `it fits no form of a ref:\n${reasons.map((reason) => `    ${reason}`).join("\n")}`
+    );
+  }
+
+  /** A ConfigError for text that fits no form, quoting it and showing the forms. */
+  private refError(input: string, problem: string): ConfigError {
+    return new ConfigError(`Invalid ref '${input}': ${problem}\n  ${SYNTAX_HELP}`);
+  }
+}
+
+makeInjectable(RefParser, [{ multi: REF_TOKENS.Splitter }]);

package/src/services/ref-resolver/parser/repo-qualifier-splitter.ts

@@ -0,0 +1,51 @@
+/**
+ * Reads the `repo:` qualifier at the front of a ref.
+ */
+
+import { makeInjectable } from "../injectable.js";
+import { isGlobName, NAME_ANY_CASE } from "../glob.js";
+import { BaseRefSplitter, type PartialRef } from "./partial-ref.js";
+
+/** A URL that names its scheme, such as `https://` or `github://`. */
+const SCHEME = /^[a-z][a-z0-9+.-]*:\/\//i;
+
+/** The `scp`-style SSH form, as in `git@github.com:owner/name.git`. */
+const SCP = /^[^@\s/:]+@([^@\s/:]+):(.+)$/s;
+
+/**
+ * Takes `sous-recipes:` off the front of the text and records the repository
+ * short name it names. The name may be a glob. Text that is a location, or
+ * whose first `:` comes after a `/`, has no qualifier.
+ */
+export class RepoQualifierSplitter extends BaseRefSplitter {
+  readonly order = 400;
+
+  protected read(state: PartialRef): PartialRef[] {
+    const text = state.rest;
+    if (state.repo !== undefined || SCHEME.test(text) || SCP.test(text)) return [state];
+
+    const match = /^([^:/\s]*):(.*)$/s.exec(text);
+    if (match === null) return [state];
+    const name = match[1]!;
+    const rest = match[2]!;
+
+    if (name.length === 0) {
+      state.problems.push("the repo qualifier before ':' is empty.");
+      return [];
+    }
+    if (rest.includes(":")) {
+      state.problems.push("a ref may carry at most one 'repo:' qualifier.");
+      return [];
+    }
+    if (!NAME_ANY_CASE.test(name) && !isGlobName(name)) {
+      state.problems.push(
+        `the repo qualifier '${name}' must be kebab-case: a letter, then letters, digits ` +
+          "or hyphens."
+      );
+      return [];
+    }
+    return [{ ...state, rest, repo: { kind: "repo", name } }];
+  }
+}
+
+makeInjectable(RepoQualifierSplitter);

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

@@ -0,0 +1,115 @@
+/**
+ * Reading the parents out of a nested ref, wherever a kind keeps them.
+ */
+
+import type {
+  NamespaceRef,
+  RecipeRef,
+  RefLocation,
+  RepoRef,
+  SousRef,
+} from "./types.js";
+
+/**
+ * The repository qualifier a ref was written with, wherever it sits in the
+ * nesting. A repository ref is its own qualifier.
+ *
+ * repoOf(parse("sous-recipes:workflow/alpha")); // -> { kind: "repo", name: "sous-recipes" }
+ *
+ * @param ref - Any ref.
+ */
+export function repoOf(ref: SousRef): RepoRef | undefined {
+  switch (ref.kind) {
+    case "repo":
+      return ref;
+    case "namespace":
+      return ref.repo;
+    case "recipe":
+      return ref.namespace?.repo ?? ref.repo;
+    case "recipeFile":
+      return repoOf(ref.recipe);
+    case "variable":
+      return ref.recipe === undefined ? ref.repo : (repoOf(ref.recipe) ?? ref.repo);
+    case "envVar":
+      return undefined;
+  }
+}
+
+/**
+ * Where the ref says its repository lives, when it says.
+ *
+ * @param ref - Any ref.
+ */
+export function locationOf(ref: SousRef): RefLocation | undefined {
+  return repoOf(ref)?.location;
+}
+
+/**
+ * The namespace a ref names or sits in.
+ *
+ * @param ref - Any ref.
+ */
+export function namespaceOf(ref: SousRef): NamespaceRef | undefined {
+  switch (ref.kind) {
+    case "namespace":
+      return ref;
+    case "recipe":
+      return ref.namespace;
+    case "recipeFile":
+      return ref.recipe.namespace;
+    case "variable":
+      return ref.recipe?.namespace;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The recipe a ref names or sits in.
+ *
+ * @param ref - Any ref.
+ */
+export function recipeOf(ref: SousRef): RecipeRef | undefined {
+  switch (ref.kind) {
+    case "recipe":
+      return ref;
+    case "recipeFile":
+      return ref.recipe;
+    case "variable":
+      return ref.recipe;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * The version range a ref carries, when it carries one.
+ *
+ * @param ref - Any ref.
+ */
+export function rangeOf(ref: SousRef): string | undefined {
+  return ref.kind === "recipe" || ref.kind === "recipeFile" || ref.kind === "repo"
+    ? ref.range
+    : undefined;
+}
+
+/**
+ * Every name and path part of a ref and its parents, outermost parent first.
+ *
+ * namesOf(parse("sous-recipes:workflow/alpha")); // -> ["sous-recipes", "workflow", "alpha"]
+ *
+ * @param ref - Any ref.
+ */
+export function namesOf(ref: SousRef): string[] {
+  const names: string[] = [];
+  const repo = repoOf(ref);
+  if (repo?.name !== undefined) names.push(repo.name);
+  if (ref.kind === "repo") return names;
+  const namespace = namespaceOf(ref);
+  if (namespace !== undefined) names.push(namespace.name);
+  const recipe = recipeOf(ref);
+  if (recipe !== undefined) names.push(recipe.name);
+  if (ref.kind === "recipeFile") names.push(ref.path);
+  if (ref.kind === "variable" || ref.kind === "envVar") names.push(ref.name);
+  return names;
+}