@sous-io/sous 0.1.0 → 0.2.0

package/src/lib/repos/providers/provider.ts

@@ -0,0 +1,401 @@
+/**
+ * The provider interface.
+ *
+ * A provider knows how to talk to one kind of repository host. Version one
+ * ships exactly two, GitHub and GitLab, and the interface stays INTERNAL: it is
+ * not a published plugin API yet, so it can still change shape while the rest
+ * of the Repositories system settles.
+ *
+ * A provider does only two things on the read path, and both are deliberately
+ * small: hand back a repo's index file, and fetch one recipe's subtree at one
+ * tag. Anything larger (a full clone) belongs to the authoring workflow, not to
+ * installing recipes.
+ *
+ * The write path is just as small, and it is the ONLY place a host's own
+ * mechanics are allowed to live. Everything host-specific (which command line
+ * tool is driven, how a fork is made, what a proposal is called, how one is
+ * opened) belongs to a provider; the services above it ask in order and report
+ * what came back. A provider declares `submit` in its features once it answers
+ * the write side; one that does not may leave those methods out entirely, and
+ * `ProviderBase` answers them with a clear refusal naming the provider and the
+ * feature.
+ */
+
+import { ConfigError } from "../../errors.js";
+import type { CommandRunner } from "./git.js";
+import type { FetchLike } from "./http.js";
+
+/**
+ * What a provider can do. `fetch` is the read path every provider implements;
+ * `submit` is the propose-a-change path, which arrives in a later phase. A
+ * provider declares the feature only once it genuinely supports it.
+ */
+export type ProviderFeature = "fetch" | "submit";
+
+/**
+ * The identifier a repo entry uses to name its provider explicitly. `local` is a
+ * repository on this machine, for local development and for tests; its trust
+ * semantics are identical to a hosted one.
+ */
+export type ProviderId = "github" | "gitlab" | "local";
+
+/** A repository URL, taken apart into the pieces every provider needs. */
+export type CanonicalRepo = {
+  /** The host the repository lives on, such as `github.com`. */
+  host: string;
+  /** The owning user, organization or group path. */
+  owner: string;
+  /** The repository's own name, with any `.git` suffix removed. */
+  name: string;
+  /** The canonical HTTPS clone URL. */
+  httpsUrl: string;
+  /** The canonical SSH clone URL. */
+  sshUrl: string;
+};
+
+/** Options every provider call accepts, all of them for testing seams. */
+export type ProviderOptions = {
+  /**
+   * The directory subprocesses run in. A write-path call is made from inside
+   * the contributor's checkout, so the host's own command line tool reads the
+   * repository the contributor is standing in.
+   */
+  cwd?: string;
+  /** The environment to read tokens from. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** The fetch implementation to use. Defaults to the global `fetch`. */
+  fetchImpl?: FetchLike;
+  /** How subprocesses are run. Defaults to spawning a real process. */
+  run?: CommandRunner;
+};
+
+/** What an index fetch returns. */
+export type FetchedIndex = {
+  /** The raw text of the index file, still to be parsed and validated. */
+  text: string;
+  /** The git ref the file was read at, for the record. */
+  ref: string;
+  /** The entity tag the host sent, when it sent one. */
+  etag?: string;
+};
+
+/** What a provider's command line tool is called, and where to get it. */
+export type ProviderCli = {
+  /** The executable, spelled the way it is typed. */
+  command: string;
+  /** The plain-language name used in messages, such as `the GitHub CLI`. */
+  label: string;
+  /** Where the tool is installed from, for the message that says it is missing. */
+  install: string;
+};
+
+/** What an authentication check found. */
+export type AuthStatus = {
+  /** True when sous can act on the contributor's behalf here. */
+  ok: boolean;
+  /**
+   * One plain-language explanation, ready to print: what is signed in when the
+   * check passed, and what to install or run when it did not.
+   */
+  detail: string;
+};
+
+/** Where a fork of a repository ended up. */
+export type ForkedRepo = {
+  /** The account the fork lives under. */
+  owner: string;
+  /** The fork's repository name. */
+  name: string;
+  /** The fork's HTTPS clone URL. */
+  httpsUrl: string;
+  /** The fork's SSH clone URL. */
+  sshUrl: string;
+};
+
+/** One change, described the way every provider needs to hear about it. */
+export type ChangeProposal = {
+  /** The branch the change is on. */
+  branch: string;
+  /** The branch the proposal targets, when the caller knows it. */
+  base?: string;
+  /** The proposal's title. */
+  title: string;
+  /** The proposal's body. */
+  body: string;
+  /** True when the proposal should be opened as a draft. */
+  draft: boolean;
+  /**
+   * The account the branch was pushed to, when that is not the repository
+   * itself. Only a provider knows how a cross-repository proposal is spelled,
+   * so it is handed the owner and composes the rest.
+   */
+  head?: { owner: string };
+};
+
+/** What proposing a change produced. */
+export type ProposedChange = {
+  /** The proposal's address, when the provider gave one. */
+  url?: string;
+  /** One plain-language line about what happened, ready to print. */
+  detail: string;
+};
+
+/** One repository host sous knows how to read from. */
+export interface RepoProvider {
+  /** The provider's stable identifier, as written in a repo config entry. */
+  readonly id: ProviderId;
+  /** What this provider can do; see ProviderFeature. */
+  readonly features: ProviderFeature[];
+  /** True when this provider handles the given repository URL. */
+  matches(url: string): boolean;
+  /** Takes a repository URL apart, raising a ConfigError when it does not fit. */
+  canonicalize(url: string): CanonicalRepo;
+  /** Fetches the repo's `sous.index.json` at its default branch. */
+  fetchIndex(repo: CanonicalRepo, options?: ProviderOptions): Promise<FetchedIndex>;
+  /**
+   * Fetches ONE recipe's subtree at one tag into `destDir`, never the whole
+   * repository.
+   *
+   * @param repo - The canonicalized repository.
+   * @param recipePath - The recipe folder's path, relative to the repo root.
+   * @param tag - The git tag carrying the version to fetch.
+   * @param destDir - Where the recipe's files should end up.
+   * @param options - Testing seams.
+   */
+  fetchRecipeTree(
+    repo: CanonicalRepo,
+    recipePath: string,
+    tag: string,
+    destDir: string,
+    options?: ProviderOptions
+  ): Promise<void>;
+
+  // --- The write path, answered by a provider that declares `submit` --------
+
+  /** The command line tool this provider drives, when it has one. */
+  readonly cli?: ProviderCli;
+  /**
+   * What this provider calls a proposal, such as `pull request` or `merge
+   * request`. It is what the submission prints as it goes.
+   */
+  readonly proposalNoun?: string;
+  /** Whether sous can act on the contributor's behalf here, and why not. */
+  authStatus?(options?: ProviderOptions): Promise<AuthStatus>;
+  /**
+   * Whether the contributor may push to the repository itself. Undefined means
+   * the provider genuinely cannot tell, which is not the same as `false`.
+   */
+  canPush?(repo: CanonicalRepo, options?: ProviderOptions): Promise<boolean | undefined>;
+  /** Forks the repository onto the contributor's own account. */
+  fork?(repo: CanonicalRepo, options?: ProviderOptions): Promise<ForkedRepo>;
+  /** Opens a proposal for a branch that has already been pushed. */
+  proposeChange?(
+    repo: CanonicalRepo,
+    proposal: ChangeProposal,
+    options?: ProviderOptions
+  ): Promise<ProposedChange>;
+}
+
+/**
+ * A provider that answers the whole write path. This is what declaring the
+ * `submit` feature promises, and `supportsSubmit` is how a caller gets from the
+ * one to the other without ever naming a provider.
+ */
+export type SubmitCapableProvider = RepoProvider &
+  Required<Pick<RepoProvider, "authStatus" | "canPush" | "fork" | "proposeChange">>;
+
+/**
+ * True when a provider declares the `submit` feature and really does answer
+ * every write-path call. It narrows the type, so a caller that has asked once
+ * never has to test a method for existence again.
+ *
+ * @param provider - The provider to test.
+ */
+export function supportsSubmit(provider: RepoProvider): provider is SubmitCapableProvider {
+  return (
+    provider.features.includes("submit") &&
+    typeof provider.authStatus === "function" &&
+    typeof provider.canPush === "function" &&
+    typeof provider.fork === "function" &&
+    typeof provider.proposeChange === "function"
+  );
+}
+
+/**
+ * Normalizes a repository URL for matching: trims it, drops a trailing slash
+ * and a trailing `.git`, and lowercases the scheme and host only.
+ *
+ * @param url - The URL as configured.
+ */
+export function normalizeRepoUrl(url: string): string {
+  let value = url.trim();
+  while (value.endsWith("/")) value = value.slice(0, -1);
+  if (value.endsWith(".git")) value = value.slice(0, -4);
+  return value;
+}
+
+/**
+ * Takes a repository URL apart into host, owner and name. Accepts the HTTPS
+ * form, the `scp`-style SSH form (`git@host:owner/name.git`) and the
+ * `ssh://host/owner/name` form, because all three are what people paste.
+ *
+ * Returns undefined rather than throwing, so a provider's `matches` can use it.
+ *
+ * @param url - The URL as configured.
+ */
+export function splitRepoUrl(
+  url: string
+): { host: string; owner: string; name: string } | undefined {
+  const normalized = normalizeRepoUrl(url);
+  if (normalized.length === 0) return undefined;
+
+  let host: string;
+  let repoPath: string;
+
+  const scpMatch = /^(?:([^@\s/]+)@)?([^@\s/:]+):(.+)$/.exec(normalized);
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(normalized)) {
+    let parsed: URL;
+    try {
+      parsed = new URL(normalized);
+    } catch {
+      return undefined;
+    }
+    host = parsed.host.toLowerCase();
+    repoPath = parsed.pathname.replace(/^\/+/, "");
+  } else if (scpMatch !== null) {
+    host = scpMatch[2]!.toLowerCase();
+    repoPath = scpMatch[3]!.replace(/^\/+/, "");
+  } else {
+    return undefined;
+  }
+
+  const segments = repoPath.split("/").filter((segment) => segment.length > 0);
+  if (segments.length < 2 || host.length === 0) return undefined;
+
+  const name = segments[segments.length - 1]!;
+  const owner = segments.slice(0, -1).join("/");
+  return { host, owner, name };
+}
+
+/**
+ * Builds the canonical form of a repository URL for a given host style.
+ *
+ * @param host - The repository host.
+ * @param owner - The owning user, organization or group path.
+ * @param name - The repository name.
+ */
+export function buildCanonicalRepo(
+  host: string,
+  owner: string,
+  name: string
+): CanonicalRepo {
+  return {
+    host,
+    owner,
+    name,
+    httpsUrl: `https://${host}/${owner}/${name}.git`,
+    sshUrl: `git@${host}:${owner}/${name}.git`,
+  };
+}
+
+/**
+ * Raises the standard ConfigError for a URL a provider cannot take apart.
+ *
+ * @param providerId - Which provider rejected it.
+ * @param url - The offending URL.
+ */
+export function invalidRepoUrl(providerId: ProviderId, url: string): ConfigError {
+  return new ConfigError(
+    `'${url}' is not a ${providerId} repository URL that sous can read.\n` +
+      `  A repository URL names an owner and a repository, as in ` +
+      `'https://${providerId}.com/owner/repository'.`
+  );
+}
+
+/**
+ * Finds the provider that handles a repository URL among the ones given, or
+ * undefined when none does. `providers/index.ts` wraps this with the built-in
+ * provider list, which is what callers normally use.
+ *
+ * @param url - The repository URL.
+ * @param providers - The providers to consider.
+ */
+export function detectProviderIn(
+  url: string,
+  providers: RepoProvider[]
+): RepoProvider | undefined {
+  return providers.find((provider) => provider.matches(url));
+}
+
+/**
+ * Looks a provider up by its identifier among the ones given, or undefined when
+ * there is none.
+ *
+ * @param id - The provider identifier from a repo config entry.
+ * @param providers - The providers to consider.
+ */
+export function providerByIdIn(
+  id: string,
+  providers: RepoProvider[]
+): RepoProvider | undefined {
+  return providers.find((provider) => provider.id === id);
+}
+
+/**
+ * Finds the provider for a repo entry: the one it names, otherwise the one that
+ * recognizes its URL. Raises a ConfigError naming the URL and listing the
+ * providers sous knows when neither works, and another when the named provider
+ * contradicts a URL a different provider plainly owns.
+ *
+ * @param url - The repository URL.
+ * @param providerId - The provider named by the repo entry, when it named one.
+ * @param providers - The providers to consider.
+ */
+export function requireProviderIn(
+  url: string,
+  providerId: string | undefined,
+  providers: RepoProvider[]
+): RepoProvider {
+  const known = providers.map((entry) => entry.id).join(", ");
+
+  if (providerId !== undefined) {
+    const named = providerByIdIn(providerId, providers);
+    if (named === undefined) {
+      throw new ConfigError(
+        `The repository at ${url} names the provider '${providerId}', which sous does not ` +
+          `have.\n  Sous ships these providers: ${known}.`
+      );
+    }
+
+    // A named provider is honoured for a host nobody recognizes, which is what a
+    // self-hosted instance needs. It is refused only when a DIFFERENT provider
+    // plainly owns the URL, because that is a contradiction rather than a hint.
+    if (!named.matches(url)) {
+      const owner = detectProviderIn(url, providers);
+      if (owner !== undefined) {
+        throw new ConfigError(
+          `The ${named.id} provider does not handle ${url}; that is ` +
+            `${describeRepoUrl(owner.id)}, which the ${owner.id} provider handles.\n` +
+            `  Drop '--provider' and let sous work it out, or name '${owner.id}'.`
+        );
+      }
+    }
+
+    return named;
+  }
+
+  const detected = detectProviderIn(url, providers);
+  if (detected !== undefined) return detected;
+
+  throw new ConfigError(
+    `Sous does not recognize the host in the repository URL ${url}.\n` +
+      `  Sous ships these providers: ${known}. For a self-hosted instance, name the ` +
+      `provider that host runs on the repository entry, as in ` +
+      `'sous repo add ${url} --provider <provider>'.`
+  );
+}
+
+/** How a URL a provider recognizes is described in a mismatch message. */
+function describeRepoUrl(providerId: ProviderId): string {
+  return providerId === "local" ? "a local path" : `a ${providerId} URL`;
+}

package/src/lib/repos/recipe-config-layers.ts

@@ -0,0 +1,287 @@
+/**
+ * Config layers that come from subscribed recipes.
+ *
+ * A recipe may contribute `config` content: files that are merged into the
+ * subscribing project's configuration rather than written anywhere in it. They
+ * are loaded AFTER the primary config and BEFORE the `conf.d/` drop-ins, so a
+ * recipe can supply defaults and the project always wins over them.
+ *
+ * This has to work before variable resolution, and before the settings even
+ * exist, because these layers are part of what the settings are built from. It
+ * therefore reads nothing but the lockfile, the links map and the store, all of
+ * which are locatable from the `.sous/` directory and the environment alone.
+ *
+ * A recipe layer is JSON (`.json`, or `.jsonc` for JSON with comments) or YAML
+ * only. The config kernel would happily import a
+ * `.js` layer, and a repository's whole trust story rests on sous being able to
+ * read what it publishes without running any of it, so an executable layer from
+ * a recipe is refused rather than loaded.
+ *
+ * A recipe layer is also read HERE rather than by the config kernel, and only
+ * the keys on the allowlist below survive the reading. A recipe is content you
+ * subscribed to; it does not get to decide what sous trusts or what sous runs.
+ * See RECIPE_CONFIG_ALLOWED_KEYS.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { globSync } from "glob";
+import { parse as parseYaml } from "yaml";
+import { parseJsoncText } from "./load-manifest.js";
+import { listLockedRecipes, readRecipeManifestIn } from "./locked-recipes.js";
+
+/** The layer extensions a recipe may contribute; the executable ones are refused. */
+export const RECIPE_LAYER_EXTENSIONS = [".json", ".jsonc", ".yaml", ".yml"] as const;
+
+/** Extensions sous can load as a config layer but deliberately will not take from a recipe. */
+export const RECIPE_LAYER_EXECUTABLE_EXTENSIONS = [".js", ".mjs", ".cjs", ".ts"] as const;
+
+/**
+ * The only top-level config keys a recipe's config layer may set.
+ *
+ * A recipe layer is merged into the project's configuration, so without this
+ * allowlist a recipe could add a repository to `repos:` (granting itself, and
+ * anything published beside it, trust the person never gave), add a
+ * subscription, or point a `tools.<name>.command` at a program that `sous
+ * launch` then spawns. Every key here is inert with respect to trust and to
+ * what sous executes: a recipe can supply variables, aliases, compilation
+ * targets, runtime context, where recipe output lands, store knobs and variable
+ * mappings, and nothing else.
+ *
+ * Anything not on this list is dropped with a warning naming the recipe and the
+ * key, including keys sous does not recognise at all.
+ */
+export const RECIPE_CONFIG_ALLOWED_KEYS = [
+  "_aliases",
+  "_vars",
+  "compilation",
+  "recipeOutputs",
+  "runtimeContext",
+  "store",
+  "varMappings",
+] as const;
+
+/**
+ * Plain-language reasons for the refused keys a recipe is most likely to try,
+ * so the warning says why rather than only that.
+ */
+const REFUSAL_REASONS: Record<string, string> = {
+  repos:
+    "only you decide which repositories this project trusts, so a recipe may not add one",
+  subscriptions:
+    "only you decide what this project subscribes to, so a recipe may not subscribe on your behalf",
+  tools:
+    "a tool entry names a program sous launches, so a recipe may not add one or change one",
+  _env: "an _env mapping decides which environment variables reach the build",
+  version: "the config version is the project's own to declare",
+  name: "the project's display name is the project's own to declare",
+  $schema: "the schema binding is the project's own editor setting",
+};
+
+/** One recipe config layer, already read and already filtered. */
+export type RecipeConfigLayer = {
+  /** Absolute path of the file it was read from, used for reporting and tracing. */
+  path: string;
+  /** The `namespace/recipe` key of the recipe that contributed it. */
+  recipeKey: string;
+  /** The layer's content, with every key outside the allowlist removed. */
+  config: Record<string, unknown>;
+};
+
+/** What a recipe's config contents came to. */
+export type RecipeConfigLayers = {
+  /** The layers, in the order they should be merged. */
+  layers: RecipeConfigLayer[];
+  /** Absolute paths of those layers, in the same order. */
+  paths: string[];
+  /** Complete, plain-language sentences about anything that was skipped. */
+  warnings: string[];
+};
+
+/**
+ * Removes every top-level key a recipe is not allowed to set.
+ *
+ * Pure, so the rule can be tested on its own: give it whatever a layer file
+ * parsed to and it returns what may be merged, plus a sentence for everything
+ * it took out.
+ *
+ * @param recipeKey - The `namespace/recipe` key, named in every warning.
+ * @param layerPath - The layer file, named in every warning.
+ * @param raw - Whatever the layer file parsed to.
+ */
+export function filterRecipeConfigLayer(
+  recipeKey: string,
+  layerPath: string,
+  raw: unknown
+): { config: Record<string, unknown>; warnings: string[] } {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    return {
+      config: {},
+      warnings: [
+        `The recipe ${recipeKey} contributes a config layer that is not a set of ` +
+          `configuration keys, so none of it was merged:\n  ${layerPath}\n` +
+          `A config layer has to be an object with configuration keys at its top level.`,
+      ],
+    };
+  }
+
+  const warnings: string[] = [];
+  const allowed = new Set<string>(RECIPE_CONFIG_ALLOWED_KEYS);
+  const config: Record<string, unknown> = {};
+
+  for (const key of Object.keys(raw)) {
+    if (allowed.has(key)) {
+      config[key] = (raw as Record<string, unknown>)[key];
+      continue;
+    }
+    const reason =
+      REFUSAL_REASONS[key] ?? "sous does not recognise it as a key a recipe may set";
+    warnings.push(
+      `The recipe ${recipeKey} tried to set '${key}' in a config layer, and sous ` +
+        `removed it before merging anything:\n  ${layerPath}\n` +
+        `That key is not one a recipe may set (${reason}). A recipe's config layer may ` +
+        `set only: ${RECIPE_CONFIG_ALLOWED_KEYS.join(", ")}.`
+    );
+  }
+
+  return { config, warnings };
+}
+
+/**
+ * Every config layer the recipes this project subscribes to contribute, read
+ * and filtered, ordered by recipe key and then by path so the merge order is
+ * the same on every machine.
+ *
+ * Only recipes held through `subscribes` contribute; a build dependency is
+ * addressable from the recipe that declared it and changes nothing about the
+ * project, its configuration included.
+ *
+ * @param sousDir - The project's `.sous/` directory.
+ * @param env - The environment to read; decides where the store is.
+ */
+export function listRecipeConfigLayers(
+  sousDir: string,
+  env: NodeJS.ProcessEnv = process.env
+): RecipeConfigLayers {
+  const result: RecipeConfigLayers = { layers: [], paths: [], warnings: [] };
+
+  let locked;
+  try {
+    locked = listLockedRecipes({ sousDir, env });
+  } catch {
+    // Config discovery runs before anything can report a problem nicely. A
+    // lockfile that does not parse is reported by every other reader of it, so
+    // contributing no layers here is the quiet, correct answer.
+    return result;
+  }
+
+  const executable: string[] = [];
+  const unsupported: string[] = [];
+
+  for (const recipe of locked) {
+    if (recipe.kind !== "subscribes") continue;
+    if (!recipe.present) continue;
+
+    let manifest;
+    try {
+      manifest = readRecipeManifestIn(recipe.dir);
+    } catch {
+      continue;
+    }
+    if (manifest === undefined) continue;
+
+    const found: string[] = [];
+
+    for (const content of manifest.contents) {
+      if (content.kind !== "config") continue;
+
+      const ignore = (content.exclude ?? []).map((pattern) =>
+        path.join(recipe.dir, pattern)
+      );
+
+      for (const include of content.include) {
+        for (const filePath of globSync(path.join(recipe.dir, include), {
+          absolute: true,
+          ignore,
+        })) {
+          if (!isFile(filePath)) continue;
+          const extension = path.extname(filePath).toLowerCase();
+          if (
+            (RECIPE_LAYER_EXECUTABLE_EXTENSIONS as readonly string[]).includes(extension)
+          ) {
+            executable.push(filePath);
+            continue;
+          }
+          if (!(RECIPE_LAYER_EXTENSIONS as readonly string[]).includes(extension)) {
+            unsupported.push(filePath);
+            continue;
+          }
+          found.push(path.normalize(filePath));
+        }
+      }
+    }
+
+    for (const layerPath of [...new Set(found)].sort()) {
+      let raw: unknown;
+      try {
+        raw = readLayerFile(layerPath);
+      } catch (error) {
+        result.warnings.push(
+          `The recipe ${recipe.key} contributes a config layer sous could not read, so ` +
+            `none of it was merged:\n  ${layerPath}\n` +
+            `${error instanceof Error ? error.message : String(error)}`
+        );
+        continue;
+      }
+
+      const filtered = filterRecipeConfigLayer(recipe.key, layerPath, raw);
+      result.warnings.push(...filtered.warnings);
+      result.layers.push({
+        path: layerPath,
+        recipeKey: recipe.key,
+        config: filtered.config,
+      });
+      result.paths.push(layerPath);
+    }
+  }
+
+  if (executable.length > 0) {
+    result.warnings.push(
+      `Some subscribed recipes contribute config layers that are program code, and sous ` +
+        `refused to load them:\n` +
+        executable.map((entry) => `  ${entry}`).join("\n") +
+        `\nSous must be able to read everything a repository publishes without running ` +
+        `any of it, so an executable layer from a recipe is never loaded. Publish the ` +
+        `same settings as ${RECIPE_LAYER_EXTENSIONS.join(", ")} instead.`
+    );
+  }
+
+  if (unsupported.length > 0) {
+    result.warnings.push(
+      `Some subscribed recipes contribute config layers written in a format sous does ` +
+        `not read, and they were skipped:\n` +
+        unsupported.map((entry) => `  ${entry}`).join("\n") +
+        `\nA recipe's config layer is written as ${RECIPE_LAYER_EXTENSIONS.join(", ")}.`
+    );
+  }
+
+  return result;
+}
+
+/** Reads and parses one recipe config layer according to its extension. */
+function readLayerFile(layerPath: string): unknown {
+  const text = fs.readFileSync(layerPath, "utf8");
+  const extension = path.extname(layerPath).toLowerCase();
+  if (extension === ".jsonc") return parseJsoncText(text, layerPath);
+  if (extension === ".json") return JSON.parse(text);
+  return parseYaml(text);
+}
+
+/** True when the path is a regular file. */
+function isFile(candidate: string): boolean {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}