@sous-io/sous 0.2.31 → 0.2.33

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

@@ -0,0 +1,115 @@
+/**
+ * Names, glob patterns and how a written name is compared with a known one.
+ *
+ * Every name or path part of a ref may be a glob pattern (`*`, `**`, `?`,
+ * `[..]`, `{a,b}`), matched with minimatch. Plain names are compared as
+ * strings. Either way the exact spelling is tried first and ignoring case is
+ * the fallback, so the caller can tell which one matched.
+ */
+
+import { minimatch } from "minimatch";
+
+/** A name as the parser accepts it: kebab-case, in any case. */
+export const NAME_ANY_CASE = /^[a-z][a-z0-9-]*$/i;
+
+/** A name as it is stored: lowercase kebab-case. */
+export const NAME_STORED = /^[a-z][a-z0-9-]*$/;
+
+/** A variable name, as a recipe's author writes it: camelCase. */
+export const VARIABLE_NAME = /^[a-z][a-zA-Z0-9]*$/;
+
+/** An environment variable name: whatever a shell accepts. */
+export const ENV_VAR_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** The characters a glob pattern is made of. */
+const GLOB_CHARS = /[*?[\]{}]/;
+
+/** The characters a glob pattern standing for a name may use. */
+const GLOB_NAME = /^[A-Za-z0-9_\-.*?[\]{},!^]+$/;
+
+/** True when a string holds glob syntax. */
+export function hasGlob(text: string): boolean {
+  return GLOB_CHARS.test(text);
+}
+
+/** True when a string is a glob pattern that could stand for a name. */
+export function isGlobName(text: string): boolean {
+  return hasGlob(text) && GLOB_NAME.test(text);
+}
+
+/**
+ * Splits text at `/`, except inside braces, so `{a/b,c}` stays whole.
+ *
+ * splitSegments("a/{b/c,d}/e"); // -> ["a", "{b/c,d}", "e"]
+ *
+ * @param text - The text to split.
+ */
+export function splitSegments(text: string): string[] {
+  const segments: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const character of text) {
+    if (character === "{") depth += 1;
+    if (character === "}" && depth > 0) depth -= 1;
+    if (character === "/" && depth === 0) {
+      segments.push(current);
+      current = "";
+      continue;
+    }
+    current += character;
+  }
+  segments.push(current);
+  return segments;
+}
+
+/** How a written name matched a known one. */
+export type NameMatch = "exact" | "folded" | undefined;
+
+/**
+ * Whether a written name (or glob pattern) matches a known one: exactly, only
+ * ignoring case, or not at all.
+ *
+ * matchName("Workflow", "workflow"); // -> "folded"
+ * matchName("work*", "workflow"); // -> "exact"
+ *
+ * @param written - The name or pattern as written.
+ * @param known - The name as it is spelled where it is published.
+ */
+export function matchName(written: string, known: string): NameMatch {
+  if (hasGlob(written)) {
+    if (minimatch(known, written, { dot: true })) return "exact";
+    return minimatch(known, written, { dot: true, nocase: true }) ? "folded" : undefined;
+  }
+  if (written === known) return "exact";
+  return written.toLowerCase() === known.toLowerCase() ? "folded" : undefined;
+}
+
+/**
+ * The names that match a written one: those spelled exactly as written, or,
+ * when there is none, those that differ only in case.
+ *
+ * matchNames("Workflow", ["workflow", "tooling"]); // -> ["workflow"]
+ * matchNames("workflow", ["workflow", "Workflow"]); // -> ["workflow"]
+ *
+ * @param written - The name as written.
+ * @param names - The names it could mean.
+ */
+export function matchNames(written: string, names: Iterable<string>): string[] {
+  const all = [...names];
+  const exact = all.filter((name) => matchName(written, name) === "exact");
+  if (exact.length > 0) return exact;
+  return all.filter((name) => matchName(written, name) === "folded");
+}
+
+/**
+ * Orders two strings by their UTF-8 bytes, so the order is the same on every
+ * machine whatever its locale.
+ *
+ * ["b", "B", "a"].sort(compareBytewise); // -> ["B", "a", "b"]
+ *
+ * @param left - The first string.
+ * @param right - The second string.
+ */
+export function compareBytewise(left: string, right: string): number {
+  return Buffer.compare(Buffer.from(left), Buffer.from(right));
+}

package/src/services/ref-resolver/hash-names.ts

@@ -0,0 +1,155 @@
+/**
+ * The `#` names: the built-in names an include line, a `{% render %}` path or
+ * an `entryGlob` may start with, such as `#project`.
+ *
+ * `~` keeps meaning the home directory and recipe namespaces; `#` is for names
+ * sous or a plugin provides. Each name is registered once, with the directories
+ * it stands for, and a registration that repeats a name is an error naming both
+ * registrants. A later layer registers a view the same way.
+ *
+ * A plugin adds a name by binding one more `HashName` under
+ * `REF_TOKENS.HashName` on a container it builds with `createRefContainer()`.
+ */
+
+import { ConfigError } from "../../lib/errors.js";
+import { compareBytewise } from "./glob.js";
+import { makeInjectable } from "./injectable.js";
+import { REF_TOKENS } from "./tokens.js";
+
+/** One file a view lists: where it sits in the view, and the real file behind it. */
+export interface ViewFile {
+  /** The path inside the view, without the `#name/` prefix, with `/` separators. */
+  readonly path: string;
+  /** The real file's absolute path. */
+  readonly file: string;
+}
+
+/** What a view needs to know about the project to list its files. */
+export interface HashViewContext {
+  /** The project's `.sous/` directory. */
+  sousDir: string;
+  /** The environment to read; decides where the recipe store is. */
+  env?: NodeJS.ProcessEnv;
+  /** The merged project config, read for the `recipes` key. */
+  settings: {
+    recipes?: { memories?: { first?: string[] | undefined; exclude?: string[] | undefined } };
+  };
+}
+
+/** One `#` name and what it stands for. */
+export interface HashName {
+  /** The name without its `#`: lowercase kebab-case, such as `project`. */
+  readonly name: string;
+  /** Who registers it, for the error a duplicate raises (`sous`, or a plugin's name). */
+  readonly registeredBy: string;
+  /** What the name is, in one sentence. */
+  readonly description: string;
+  /**
+   * The directories the name stands for, in the order they are tried. A path
+   * after the name is looked up under each in turn, the first that exists
+   * wins. Empty when the name has nothing to stand for in this project.
+   *
+   * @param scope - The settings scope the project's paths come from.
+   */
+  bases(scope: Record<string, string>): string[];
+  /**
+   * A view lists virtual files instead of standing for directories: an include
+   * of `#name/<glob>` selects among the listed paths and includes the real
+   * files behind them, in the listed order. A view has no bases.
+   *
+   * @param context - The project the files are listed for.
+   */
+  view?(context: HashViewContext): ViewFile[];
+}
+
+/** The characters a registered name may hold. */
+const VALID_NAME = /^[a-z][a-z0-9-]*$/;
+
+/** The built-in `#project`: the consuming project's root. */
+export class ProjectHashName implements HashName {
+  readonly name = "project";
+  readonly registeredBy = "sous";
+  readonly description = "the root directory of the project being built.";
+
+  bases(scope: Record<string, string>): string[] {
+    return scope.projectRoot ? [scope.projectRoot] : [];
+  }
+}
+
+makeInjectable(ProjectHashName);
+
+/** Every registered `#` name. */
+export class HashNameRegistry {
+  private readonly entries = new Map<string, HashName>();
+
+  /**
+   * @param names - The names to register, each once.
+   * @throws A ConfigError when a name is invalid or registered twice.
+   */
+  constructor(names: HashName[] = []) {
+    for (const entry of names) this.register(entry);
+  }
+
+  /**
+   * Adds a name.
+   *
+   * @param entry - The name to add.
+   * @throws A ConfigError naming both registrants when the name is already taken.
+   */
+  register(entry: HashName): void {
+    if (!VALID_NAME.test(entry.name)) {
+      throw new ConfigError(
+        `The name '#${entry.name}' registered by '${entry.registeredBy}' is invalid: a name is ` +
+          "lowercase kebab-case, a letter then letters, digits or hyphens."
+      );
+    }
+    const existing = this.entries.get(entry.name);
+    if (existing !== undefined) {
+      throw new ConfigError(
+        `The name '#${entry.name}' is registered twice: by '${existing.registeredBy}' and by ` +
+          `'${entry.registeredBy}'.`
+      );
+    }
+    this.entries.set(entry.name, entry);
+  }
+
+  /** The registered name, or undefined. */
+  get(name: string): HashName | undefined {
+    return this.entries.get(name);
+  }
+
+  /** Every registered name, sorted. */
+  list(): HashName[] {
+    return [...this.entries.values()].sort((left, right) => compareBytewise(left.name, right.name));
+  }
+
+  /**
+   * Every view's listed files, keyed by the name with its `#`.
+   *
+   * @param context - The project the files are listed for.
+   */
+  viewMap(context: HashViewContext): Record<string, ViewFile[]> {
+    const map: Record<string, ViewFile[]> = {};
+    for (const entry of this.list()) {
+      if (entry.view !== undefined) map[`#${entry.name}`] = entry.view(context);
+    }
+    return map;
+  }
+
+  /**
+   * The alias map the registered names make for a project: `#name` to its
+   * directories, leaving out a name with none.
+   *
+   * @param scope - The settings scope the project's paths come from.
+   */
+  aliasMap(scope: Record<string, string>): Record<string, string[]> {
+    const map: Record<string, string[]> = {};
+    for (const entry of this.list()) {
+      const bases = entry.bases(scope);
+      if (bases.length > 0) map[`#${entry.name}`] = bases;
+    }
+    return map;
+  }
+}
+
+makeInjectable(HashNameRegistry, [{ multi: REF_TOKENS.HashName }]);

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

@@ -0,0 +1,55 @@
+/**
+ * The ref resolver service: how every sous command and template turns a
+ * written ref into the thing it names.
+ *
+ * Import from here. `types.ts` says what a ref is, the parser reads every way a
+ * text can be one, a pruner per place says which readings count there, a
+ * lookup says which exist, `RefResolverService` runs the three in order, and
+ * `RefPickerService` settles which meaning a run proceeds with.
+ *
+ * `EnvVarLookup` is not exported here. It reads the variable ladder, which
+ * reaches config discovery, and config discovery reaches this module through
+ * the recipe formats, so exporting it from the barrel would make an import
+ * cycle that fails at load time. Import it from `lookups/env-var-lookup.js`.
+ */
+
+export * from "./source.js";
+export * from "./types.js";
+export * from "./parts.js";
+export * from "./glob.js";
+export * from "./location.js";
+export * from "./format.js";
+export * from "./tokens.js";
+export * from "./hash-names.js";
+export * from "./injectable.js";
+export * from "./parser/partial-ref.js";
+export * from "./parser/ref-parser.js";
+export * from "./parser/query-splitter.js";
+export * from "./parser/range-splitter.js";
+export * from "./parser/location-splitter.js";
+export * from "./parser/repo-qualifier-splitter.js";
+export * from "./parser/name-path-splitter.js";
+export * from "./parser/env-var-splitter.js";
+export * from "./pruners/ref-pruner.js";
+export * from "./pruners/rule-helpers.js";
+export * from "./pruners/command-line-pruner.js";
+export * from "./pruners/stored-key-pruner.js";
+export * from "./pruners/manifest-pruner.js";
+export * from "./pruners/include-pruner.js";
+export * from "./lookups/ref-lookup.js";
+export * from "./lookups/chained-lookup.js";
+export * from "./lookups/catalog-matcher.js";
+export * from "./lookups/catalog-lookup.js";
+export * from "./lookups/cached-index-lookup.js";
+export * from "./lookups/recorded-dependency-lookup.js";
+export * from "./lookups/fetched-index-lookup.js";
+export * from "./lookups/variable-lookup.js";
+export * from "./ref-resolve-arguments.js";
+export * from "./ref-resolve-result.js";
+export * from "./ref-resolver-service.js";
+export * from "./ref-picker-service.js";
+export * from "./ref-report.js";
+export * from "./named-refs.js";
+export * from "./dependency.js";
+export * from "./ref-helpers.js";
+export * from "./container.js";

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

@@ -0,0 +1,36 @@
+/**
+ * Marking a class as injectable without decorator syntax.
+ *
+ * sous runs TypeScript through tsx, and the published `bin/run.js` registers
+ * tsx from the directory a command runs in, so the `experimentalDecorators`
+ * flag in this repository's tsconfig does not reach it; esbuild also emits no
+ * decorator metadata. Inversify's decorators are plain functions, though, so
+ * calling them here marks every constructor parameter with its token
+ * explicitly and needs neither a compiler flag nor `reflect-metadata`.
+ */
+
+import { decorate, inject, injectable, multiInject } from "inversify";
+
+/** One constructor parameter: a token bound once, or a token bound many times. */
+export type ConstructorParameter = symbol | { multi: symbol };
+
+/**
+ * Marks a class injectable and names the token of every constructor parameter,
+ * in order.
+ *
+ * makeInjectable(RefParser, [{ multi: REF_TOKENS.Splitter }]);
+ *
+ * @param target - The class.
+ * @param parameters - The token of each constructor parameter, in order.
+ */
+export function makeInjectable(
+  target: new (...args: never[]) => unknown,
+  parameters: ConstructorParameter[] = []
+): void {
+  decorate(injectable(), target);
+  parameters.forEach((parameter, index) => {
+    const decorator =
+      typeof parameter === "symbol" ? inject(parameter) : multiInject(parameter.multi);
+    decorate(decorator, target, index);
+  });
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Building a `RefLocation`: where a repository lives, in the form every ref
+ * and every machine-wide key agrees on.
+ */
+
+import { repoIdentity } from "../../lib/repos/identity.js";
+import {
+  requireProvider,
+  type RepoProvider,
+} from "../../lib/repos/providers/index.js";
+import type { RefLocation } from "./types.js";
+
+/**
+ * Where one repository lives, or undefined when its provider cannot take the
+ * path apart (a path of one segment, say).
+ *
+ * @param provider - The provider that reads the location.
+ * @param host - The repository's host.
+ * @param repoPath - The repository's path on that host.
+ */
+export function locationFor(
+  provider: RepoProvider,
+  host: string,
+  repoPath: string
+): RefLocation | undefined {
+  const url = `https://${host}/${repoPath}`;
+  try {
+    return {
+      provider: provider.id,
+      host,
+      repoPath,
+      identity: repoIdentity(provider.canonicalize(url)),
+      url,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Where the repository at a configured URL lives, or undefined when no
+ * provider recognizes it. The location's `url` is the URL as the project
+ * configured it, which is what a person is shown.
+ *
+ * @param url - The repository's URL, as a project's config records it.
+ * @param providers - The providers to ask. Defaults to the built-ins.
+ */
+export function locationFromUrl(url: string, providers?: RepoProvider[]): RefLocation | undefined {
+  try {
+    const provider = requireProvider(url, undefined, providers);
+    const canonical = provider.canonicalize(url);
+    return {
+      provider: provider.id,
+      host: canonical.host,
+      repoPath: `${canonical.owner}/${canonical.name}`,
+      identity: repoIdentity(canonical),
+      url,
+    };
+  } catch {
+    return undefined;
+  }
+}

package/src/services/ref-resolver/lookups/cached-index-lookup.ts

@@ -0,0 +1,53 @@
+import type { IndexFile } from "../../../lib/repos/formats/index-file.js";
+import { locationFromUrl } from "../location.js";
+import type { SousRef } from "../types.js";
+import { CatalogMatcher, catalogRepoOfIndex, type CatalogRepo } from "./catalog-matcher.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/** What a `CachedIndexLookup` needs to know beyond the indexes themselves. */
+export type CachedIndexLookupOptions = {
+  /**
+   * The repositories' short names, in the order their matches should be
+   * listed: the built-in repository first, then the ones the config names.
+   * Defaults to the order the indexes were added to the map.
+   */
+  order?: readonly string[];
+  /**
+   * Where each repository lives, by short name. It is how a ref written as a
+   * location (a URL, a locator, a URL copied from the browser) finds the
+   * repository whatever short name this project gave it.
+   */
+  urls?: Record<string, string | undefined>;
+};
+
+/**
+ * Answers repositories, namespaces and recipes from the repository indexes
+ * already on this machine. It reads nothing, fetches nothing and never fails:
+ * a candidate no index publishes simply has no match.
+ */
+export class CachedIndexLookup implements RefLookup {
+  private readonly matcher: CatalogMatcher;
+
+  /**
+   * @param indexes - Each repository's cached index, keyed by short name.
+   * @param options - The listing order, and where each repository lives.
+   */
+  constructor(indexes: Map<string, IndexFile>, options: CachedIndexLookupOptions = {}) {
+    const order = options.order ?? [...indexes.keys()];
+    const repos: CatalogRepo[] = [];
+
+    for (const name of order) {
+      const index = indexes.get(name);
+      if (index === undefined) continue;
+      const url = options.urls?.[name];
+      const location = url === undefined ? undefined : locationFromUrl(url);
+
+      repos.push(catalogRepoOfIndex(index, { name, ...(location === undefined ? {} : { location }) }));
+    }
+    this.matcher = new CatalogMatcher(repos);
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    return this.matcher.match(candidate);
+  }
+}

package/src/services/ref-resolver/lookups/catalog-lookup.ts

@@ -0,0 +1,23 @@
+import type { SousRef } from "../types.js";
+import { CatalogMatcher, type CatalogRepo } from "./catalog-matcher.js";
+import type { RefLookup, RefMatch } from "./ref-lookup.js";
+
+/**
+ * Answers repositories, namespaces and recipes from a catalog a caller has
+ * already built (which repositories it knows, and what each publishes). It
+ * reads nothing, fetches nothing and never fails.
+ */
+export class CatalogLookup implements RefLookup {
+  private readonly matcher: CatalogMatcher;
+
+  /**
+   * @param repos - The repositories to search, in the order their matches are listed.
+   */
+  constructor(repos: CatalogRepo[]) {
+    this.matcher = new CatalogMatcher(repos);
+  }
+
+  async find(candidate: SousRef): Promise<RefMatch[]> {
+    return this.matcher.match(candidate);
+  }
+}