github-settings-as-code 3.1.0 → 4.0.0

package/src/github/environments/apply.mts

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import { Arr } from 'ts-data-forge';
+import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
+import { environmentsDir } from '../constants.mjs';
+import { settingsFilePath } from '../settings-file-path.mjs';
+import { getAllEnvironments, setEnvironment } from './api/index.mjs';
+import { type EnvironmentSettings } from './constants.mjs';
+import { readEnvironmentFiles } from './read-environment-contents.mjs';
+
+/**
+ * `repo-settings/environments/*.json` を Settings > Environments に反映する。
+ *
+ * ruleset と同じく、宣言に無い環境は消さない。 GUI で作られたものは drift
+ * 検査が報せるのであって、 apply が黙って片付けてしまうと「いつ誰が何を
+ * 作ったか」を見る機会がなくなる。
+ */
+export const applyEnvironments = async (): Promise<void> => {
+  const environments = await readEnvironmentFiles();
+
+  for (const environment of environments) {
+    assertConsistent(environment);
+  }
+
+  for (const environment of environments) {
+    await setEnvironment(environment);
+  }
+
+  // 反映後の実際の値でローカルのファイルを更新する
+  {
+    const applied = await getAllEnvironments();
+
+    for (const environment of applied) {
+      const str = JSON.stringify(environment, undefined, 2);
+
+      // `settingsFilePath` が `environmentsDir` の直下であることを確かめている。
+      // eslint-disable-next-line security/detect-non-literal-fs-filename
+      await fs.writeFile(
+        settingsFilePath(environmentsDir, environment.name),
+        str,
+      );
+    }
+
+    await formatUncommittedFiles();
+  }
+};
+
+/**
+ * GitHub 側が黙って無視する組み合わせを、送る前に落とす。
+ *
+ * `custom_branch_policies` が立っていないのに pattern が書いてあるファイルは、
+ * 読む側には「この ref だけに制限されている」と読めて、実際には何の制限にも
+ * なっていない — 一番危ない種類の嘘なので、エラーにする。
+ */
+const assertConsistent = (environment: EnvironmentSettings): void => {
+  const custom =
+    environment.deployment_branch_policy?.custom_branch_policies === true;
+
+  if (!custom && Arr.isNonEmpty(environment.deployment_branch_policies)) {
+    throw new Error(
+      [
+        `環境 "${environment.name}": deployment_branch_policies が書かれていますが、`,
+        'deployment_branch_policy.custom_branch_policies が true ではありません。',
+        'pattern は "Selected branches and tags" を選んだときにしか効きません。',
+      ].join('\n'),
+    );
+  }
+
+  // `custom` が立っている時点で TypeScript は `deployment_branch_policy` を
+  // record 側に絞り込んでいる。両方 true は JSON としては書けてしまうので、
+  // この組み合わせは送る前に落とす。
+  if (custom && environment.deployment_branch_policy.protected_branches) {
+    throw new Error(
+      `環境 "${environment.name}": protected_branches と custom_branch_policies は同時に true にできません。`,
+    );
+  }
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await applyEnvironments();
+}

package/src/github/environments/backup.mts

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
+import { clearJsonFilesIn } from '../clear-json-files.mjs';
+import { environmentsDir } from '../constants.mjs';
+import { settingsFilePath } from '../settings-file-path.mjs';
+import { getAllEnvironments } from './api/index.mjs';
+
+/**
+ * Settings > Environments の現在値を宣言ファイルへ撮り直す。
+ *
+ * ruleset と同じく、先に直下の `*.json` を消してから書く。理由は
+ * {@link clearJsonFilesIn} を参照。
+ */
+export const backupEnvironments = async (
+  fmt: boolean = true,
+): Promise<void> => {
+  const environments = await getAllEnvironments();
+
+  await clearJsonFilesIn(environmentsDir);
+
+  for (const environment of environments) {
+    // `settingsFilePath` が `environmentsDir` の直下であることを確かめている。
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(
+      settingsFilePath(environmentsDir, environment.name),
+      JSON.stringify(environment, undefined, 2),
+    );
+  }
+
+  if (fmt) {
+    await formatUncommittedFiles();
+  }
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await backupEnvironments();
+}

package/src/github/environments/constants.mts

@@ -0,0 +1,78 @@
+import * as t from 'ts-fortress';
+
+/**
+ * `repo-settings/environments/*.json` の型。
+ *
+ * Settings > Environments の 1 件に対応する。ファイルは「その環境の望ましい
+ * 状態」を丸ごと表しており、 GitHub 側で 2 つに分かれている次の API をまとめて
+ * 1 ファイルで管理する:
+ *
+ * - `PUT /repos/{owner}/{repo}/environments/{environment_name}`
+ * - `GET|POST|DELETE /repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies`
+ *
+ * GET が返す `protection_rules` は「有効な保護ルールだけが並ぶ配列」だが、この
+ * 型は書き込み側（ PUT の body ）に合わせた平らな形にしている。往復させる側の
+ * 形を正とするほうが、ファイルを読んで何が起きるか分かりやすいため。
+ */
+export const EnvironmentSettings = t.record({
+  name: t.string(''),
+
+  /** 「 Wait timer 」。分。 0 なら待たない。 */
+  wait_timer: t.number(0),
+
+  /** 「 Prevent self-review 」。 */
+  prevent_self_review: t.boolean(false),
+
+  /** 「 Required reviewers 」。空配列なら承認は要らない。 */
+  reviewers: t.array(
+    t.record({
+      type: t.enumType(['User', 'Team'], {
+        typeName: 'EnvironmentReviewerType',
+        defaultValue: 'User',
+      }),
+      id: t.number(0),
+    }),
+    { typeName: 'EnvironmentReviewers' },
+  ),
+
+  /**
+   * 「 Deployment branches and tags 」の選択。
+   *
+   * - `null` … 「 No restriction 」（ どの ref からでも deploy できる ）
+   * - `protected_branches: true` … 「 Protected branches only 」
+   * - `custom_branch_policies: true` … 「 Selected branches and tags 」。
+   *   具体的な pattern は下の `deployment_branch_policies` 。
+   *
+   * 2 つを同時に `true` にはできない。
+   */
+  deployment_branch_policy: t.union(
+    [
+      t.record({
+        protected_branches: t.boolean(false),
+        custom_branch_policies: t.boolean(true),
+      }),
+      t.nullType,
+    ],
+    { typeName: 'DeploymentBranchPolicySelection' },
+  ),
+
+  /**
+   * `custom_branch_policies` が `true` のときの pattern 一覧。
+   *
+   * それ以外のときは空配列でなければならない（`applyEnvironments` が拒否する）。
+   * GitHub 側は別エンドポイントだが、「どの ref から deploy できるか」を
+   * 決めているのは選択と pattern の組で、片方だけ見ても意味を成さない。
+   */
+  deployment_branch_policies: t.array(
+    t.record({
+      name: t.string(''),
+      type: t.enumType(['branch', 'tag'], {
+        typeName: 'DeploymentBranchPolicyType',
+        defaultValue: 'branch',
+      }),
+    }),
+    { typeName: 'DeploymentBranchPolicies' },
+  ),
+});
+
+export type EnvironmentSettings = t.TypeOf<typeof EnvironmentSettings>;

package/src/github/environments/index.mts

@@ -0,0 +1,5 @@
+export * from './api/index.mjs';
+export * from './apply.mjs';
+export * from './backup.mjs';
+export * from './constants.mjs';
+export * from './read-environment-contents.mjs';

package/src/github/environments/read-environment-contents.mts

@@ -0,0 +1,49 @@
+import { type Dirent } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as t from 'ts-fortress';
+import { isDirectlyExecuted, Result } from 'ts-repo-utils';
+import { environmentsDir } from '../constants.mjs';
+import { EnvironmentSettings } from './constants.mjs';
+
+export const readEnvironmentFiles = async (): Promise<
+  readonly EnvironmentSettings[]
+> => readFilesIn(environmentsDir);
+
+const readFilesIn = async (
+  dir: string,
+): Promise<readonly EnvironmentSettings[]> => {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const files: readonly Dirent<string>[] = await fs.readdir(dir, {
+    withFileTypes: true,
+  });
+
+  const fileContents: readonly string[] = await Promise.all(
+    files
+      .filter((d) => d.isFile())
+      .map((d) =>
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        fs.readFile(path.resolve(dir, d.name), { encoding: 'utf8' }),
+      ),
+  );
+
+  const validationResults = fileContents.map((content) =>
+    EnvironmentSettings.validate(JSON.parse(content)),
+  );
+
+  const mut_values: EnvironmentSettings[] = [];
+
+  for (const r of validationResults) {
+    if (Result.isErr(r)) {
+      throw new Error(t.validationErrorsToMessages(r.value).join('\n'));
+    }
+
+    mut_values.push(r.value);
+  }
+
+  return mut_values;
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await readEnvironmentFiles();
+}

package/src/github/index.mts

@@ -1,7 +1,11 @@
 export * from './actions-settings/index.mjs';
+export * from './clear-json-files.mjs';
 export * from './constants.mjs';
+export * from './environments/index.mjs';
 export * from './pages/index.mjs';
 export * from './repository/index.mjs';
 export * from './resolve-target-repo.mjs';
 export * from './ruleset/index.mjs';
+export * from './settings-file-path.mjs';
 export * from './variables/index.mjs';
+export * from './vulnerability-alerts/index.mjs';

package/src/github/pages/apply.mts

@@ -43,12 +43,6 @@ export const applyPagesSettings = async (): Promise<void> => {
     // eslint-disable-next-line security/detect-non-literal-fs-filename
     await fs.writeFile(settingsPath, str);
 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename
-    await fs.writeFile(
-      path.resolve(pagesSettingsDir, 'bk', settingsJsonName),
-      str,
-    );
-
     await formatUncommittedFiles();
   }
 };

package/src/github/pages/backup.mts

@@ -2,35 +2,44 @@
 import 'dotenv/config';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import {
-  formatUncommittedFiles,
-  isDirectlyExecuted,
-  makeEmptyDir,
-} from 'ts-repo-utils';
+import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
+import { clearJsonFilesIn } from '../clear-json-files.mjs';
 import { pagesSettingsDir, settingsJsonName } from '../constants.mjs';
 import { getPagesSettings } from './api/index.mjs';
 
-const backupDir = path.resolve(pagesSettingsDir, './bk');
-
-/** Settings > Pages の現在値を `bk/` に保存する。 */
+/**
+ * Settings > Pages の現在値を宣言ファイルへ撮り直す。
+ *
+ * **Pages が無効なら宣言も消える。** 他のターゲットと同じ規則にしてある — 撮り
+ * 直したあとに在るものが live から取れたものそのもの、という性質を、ここだけ
+ * 崩さない。無効になったことが `git status` に削除として出る。
+ *
+ * 無効化と読み取り失敗を区別できないという弱点は残るが、`getPagesSettings` が
+ * `undefined` を返すのは 404 のときだけで、それ以外の失敗は例外になる。消えた
+ * 宣言はコミットしなければ失われない。
+ */
 export const backupPagesSettings = async (
   fmt: boolean = true,
 ): Promise<void> => {
-  await makeEmptyDir(backupDir);
-
   const settings = await getPagesSettings();
 
+  await clearJsonFilesIn(pagesSettingsDir);
+
   if (settings === undefined) {
     console.warn(
-      'GitHub Pages is not enabled for this repository; skipping backup.',
+      'GitHub Pages is not enabled for this repository; the declaration was removed.',
     );
 
+    if (fmt) {
+      await formatUncommittedFiles();
+    }
+
     return;
   }
 
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   await fs.writeFile(
-    path.resolve(backupDir, settingsJsonName),
+    path.resolve(pagesSettingsDir, settingsJsonName),
     JSON.stringify(settings, undefined, 2),
   );
 

package/src/github/repository/apply.mts

@@ -13,7 +13,6 @@ import {
 import { type StrictPick } from 'ts-type-forge';
 import { repositorySettingsDir, settingsJsonName } from '../constants.mjs';
 import { getRepositorySettings, updateRepository } from './api/index.mjs';
-import { backupRepositorySettings } from './backup.mjs';
 import {
   type RepositoryKeysToPick,
   repositoryKeysToPick,
@@ -21,8 +20,6 @@ import {
 } from './constants.mjs';
 
 export const applyRepositorySettings = async (): Promise<void> => {
-  await backupRepositorySettings(false);
-
   const settings = await readSettings();
 
   await updateRepository({
@@ -72,12 +69,6 @@ export const applyRepositorySettings = async (): Promise<void> => {
       str,
     );
 
-    // eslint-disable-next-line security/detect-non-literal-fs-filename
-    await fs.writeFile(
-      path.resolve(repositorySettingsDir, 'bk', settingsJsonName),
-      str,
-    );
-
     await formatUncommittedFiles();
   }
 };

package/src/github/repository/backup.mts

@@ -3,27 +3,22 @@ import 'dotenv/config';
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { Obj } from 'ts-data-forge';
-import {
-  formatUncommittedFiles,
-  isDirectlyExecuted,
-  makeEmptyDir,
-} from 'ts-repo-utils';
+import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
+import { clearJsonFilesIn } from '../clear-json-files.mjs';
 import { repositorySettingsDir, settingsJsonName } from '../constants.mjs';
 import { getRepositorySettings } from './api/index.mjs';
 import { repositoryKeysToPick } from './constants.mjs';
 
-const backupDir = path.resolve(repositorySettingsDir, './bk');
-
 export const backupRepositorySettings = async (
   fmt: boolean = true,
 ): Promise<void> => {
-  await makeEmptyDir(backupDir);
-
   const repositorySettings = await getRepositorySettings();
 
+  await clearJsonFilesIn(repositorySettingsDir);
+
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   await fs.writeFile(
-    path.resolve(backupDir, settingsJsonName),
+    path.resolve(repositorySettingsDir, settingsJsonName),
     JSON.stringify(
       Obj.pick(repositorySettings, repositoryKeysToPick),
       undefined,

package/src/github/ruleset/apply.mts

@@ -1,35 +1,32 @@
 #!/usr/bin/env node
 import 'dotenv/config';
 import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
 import { Obj } from 'ts-data-forge';
 import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
 import { rulesetsDir } from '../constants.mjs';
+import { settingsFilePath } from '../settings-file-path.mjs';
 import {
   createRuleset,
   getAllRulesets,
   getRuleset,
   updateRuleset,
 } from './api/index.mjs';
-import { backupRulesets } from './backup.mjs';
 import { rulesetKeysToPick } from './constants.mjs';
-import {
-  readRulesetBackupFiles,
-  readRulesetFiles,
-} from './read-rule-set-contents.mjs';
+import { readRulesetFiles } from './read-rule-set-contents.mjs';
 
 export const applyRulesets = async (): Promise<void> => {
-  await backupRulesets(false);
-
   const rulesets = await readRulesetFiles();
 
-  const backupIds: ReadonlySet<number> = await readRulesetBackupFiles().then(
+  // 既にあるかどうかは live に訊く。以前はこの直前に走らせた backup の出力を
+  // 読んでいたが、それは live の写しでしかなく、写した時点と送る時点のあいだに
+  // 消えた ruleset を「更新できる」と誤らせる余地があった。
+  const existingIds: ReadonlySet<number> = await getAllRulesets().then(
     (rs) => new Set(rs.map((r) => r.id)),
   );
 
-  const rulesetsToUpdate = rulesets.filter((r) => backupIds.has(r.id));
+  const rulesetsToUpdate = rulesets.filter((r) => existingIds.has(r.id));
 
-  const rulesetsToCreate = rulesets.filter((r) => !backupIds.has(r.id));
+  const rulesetsToCreate = rulesets.filter((r) => !existingIds.has(r.id));
 
   for (const ruleset of rulesetsToUpdate) {
     await updateRuleset({
@@ -71,14 +68,9 @@ export const applyRulesets = async (): Promise<void> => {
         2,
       );
 
+      // `settingsFilePath` が `rulesetsDir` の直下であることを確かめている。
       // eslint-disable-next-line security/detect-non-literal-fs-filename
-      await fs.writeFile(path.resolve(rulesetsDir, `${rule.name}.json`), str);
-
-      // eslint-disable-next-line security/detect-non-literal-fs-filename
-      await fs.writeFile(
-        path.resolve(rulesetsDir, `./bk/${rule.name}.json`),
-        str,
-      );
+      await fs.writeFile(settingsFilePath(rulesetsDir, rule.name), str);
     }
 
     await formatUncommittedFiles();

package/src/github/ruleset/backup.mts

@@ -1,30 +1,40 @@
 #!/usr/bin/env node
 import 'dotenv/config';
 import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
 import { Obj } from 'ts-data-forge';
-import {
-  formatUncommittedFiles,
-  isDirectlyExecuted,
-  makeEmptyDir,
-} from 'ts-repo-utils';
+import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
+import { clearJsonFilesIn } from '../clear-json-files.mjs';
 import { rulesetsDir } from '../constants.mjs';
+import { settingsFilePath } from '../settings-file-path.mjs';
 import { getAllRulesets, getRuleset } from './api/index.mjs';
 import { rulesetKeysToPick } from './constants.mjs';
 
-const backupDir = path.resolve(rulesetsDir, './bk');
-
+/**
+ * ruleset の現在値を宣言ファイルへ撮り直す。
+ *
+ * 先に直下の `*.json` を消してから書くので、撮り直したあとにそこに在るものが
+ * live から取れたものそのものになる。取れなかった ruleset は `git status` に
+ * 削除として現れる。理由は {@link clearJsonFilesIn} を参照。
+ */
 export const backupRulesets = async (fmt: boolean = true): Promise<void> => {
-  await makeEmptyDir(backupDir);
-
   const rulesetsResult = await getAllRulesets();
 
-  for (const rule of rulesetsResult) {
-    const content = await getRuleset(rule.id);
+  // 取得がすべて終わってから消す。途中で失敗したときに、宣言だけ消えて何も
+  // 書かれていない状態にしないため。
+  const contents = await Promise.all(
+    rulesetsResult.map(async (rule) => ({
+      name: rule.name,
+      content: await getRuleset(rule.id),
+    })),
+  );
+
+  await clearJsonFilesIn(rulesetsDir);
 
+  for (const { name, content } of contents) {
+    // `settingsFilePath` が `rulesetsDir` の直下であることを確かめている。
     // eslint-disable-next-line security/detect-non-literal-fs-filename
     await fs.writeFile(
-      path.resolve(backupDir, `${rule.name}.json`),
+      settingsFilePath(rulesetsDir, name),
       JSON.stringify(Obj.pick(content, rulesetKeysToPick), undefined, 2),
     );
   }

package/src/github/ruleset/read-rule-set-contents.mts

@@ -9,10 +9,6 @@ import { RulesetPicked } from './constants.mjs';
 export const readRulesetFiles = async (): Promise<readonly RulesetPicked[]> =>
   readFilesIn(rulesetsDir);
 
-export const readRulesetBackupFiles = async (): Promise<
-  readonly RulesetPicked[]
-> => readFilesIn(path.resolve(rulesetsDir, './bk'));
-
 const readFilesIn = async (dir: string): Promise<readonly RulesetPicked[]> => {
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   const files: readonly Dirent<string>[] = await fs.readdir(dir, {

package/src/github/ruleset/schema.test.mts

@@ -77,19 +77,6 @@ describe('the ruleset schema', () => {
     }
   });
 
-  test('accepts every backed-up ruleset', async () => {
-    const files = await readJsonFilesIn(path.resolve(rulesetsDir, './bk'));
-
-    assert.isTrue(Arr.isNonEmpty(files));
-
-    for (const [name, content] of files) {
-      assert.deepStrictEqual(
-        outcomeOf(name, RulesetPicked.validate(content)),
-        name,
-      );
-    }
-  });
-
   test('accepts the fields GitHub adds to what apply sends back', async () => {
     const files = await readJsonFilesIn(rulesetsDir);
 

package/src/github/settings-file-path.mts

@@ -0,0 +1,51 @@
+import * as path from 'node:path';
+
+/**
+ * `dir` の直下の `<name>.json` を指すパスを返す。ファイル名にできない名前は
+ * 拒否する。
+ *
+ * environment 名と ruleset 名は GitHub API が返す素の文字列で、パス片として
+ * 使えることは何も保証していない。区切りを含む名前をそのまま結合すると、
+ * 書き込み先が `dir` の外 — GitHub の現在値と突き合わせる宣言ファイルが
+ * 置いてある場所 — へ出てしまう。
+ *
+ * 正規化ではなく拒否にしてあるのは、そういう名前が来たこと自体が異常の証拠だ
+ * からで、黙って書き換えると何が起きていたのかが分からなくなる。
+ */
+export const settingsFilePath = (dir: string, name: string): string => {
+  if (!isUsableAsFileName(name)) {
+    throw new Error(
+      [
+        `ファイル名にできない名前です: ${JSON.stringify(name)}。`,
+        `${dir} の外へ書き込もうとしている可能性があります。`,
+      ].join('\n'),
+    );
+  }
+
+  const resolvedDir = path.resolve(dir);
+
+  const resolved = path.resolve(resolvedDir, `${name}.json`);
+
+  // 二重の歯止め。上の判定が漏れても、`dir` の外には出さない。
+  if (!resolved.startsWith(resolvedDir + path.sep)) {
+    throw new Error(
+      `書き込み先が ${resolvedDir} の外を指しています: ${resolved}`,
+    );
+  }
+
+  return resolved;
+};
+
+/**
+ * パス片ひとつとして読める名前か。
+ *
+ * `path.sep` ではなく両方の区切りを見るのは、Windows で書かれた名前が POSIX
+ * 上で素通りしないようにするため。
+ */
+const isUsableAsFileName = (name: string): boolean =>
+  name !== '' &&
+  name !== '.' &&
+  name !== '..' &&
+  !name.includes('/') &&
+  !name.includes('\\') &&
+  !name.includes('\u{0}');

package/src/github/settings-file-path.test.mts

@@ -0,0 +1,70 @@
+import * as path from 'node:path';
+import { Result } from 'ts-data-forge';
+import { settingsFilePath } from './settings-file-path.mjs';
+
+const dir = path.resolve('/tmp/repo-settings/environments');
+
+/** `'rejected'` when the name was refused, the resolved path when it was not. */
+const outcomeOf = (name: string): string => {
+  const result = Result.fromThrowable(() => settingsFilePath(dir, name));
+
+  return Result.isErr(result) ? 'rejected' : result.value;
+};
+
+describe(settingsFilePath, () => {
+  test('names a file directly under the directory it was given', () => {
+    assert.deepStrictEqual(
+      settingsFilePath(dir, 'release'),
+      path.join(dir, 'release.json'),
+    );
+  });
+
+  test('keeps the characters a name is allowed to carry', () => {
+    assert.deepStrictEqual(
+      settingsFilePath(dir, 'main-no-bypass'),
+      path.join(dir, 'main-no-bypass.json'),
+    );
+
+    assert.deepStrictEqual(
+      settingsFilePath(dir, 'Production (US East)'),
+      path.join(dir, 'Production (US East).json'),
+    );
+  });
+
+  test('rejects a name that would resolve above the directory', () => {
+    assert.deepStrictEqual(outcomeOf('../release'), 'rejected');
+
+    assert.deepStrictEqual(outcomeOf('../../../../tmp/elsewhere'), 'rejected');
+  });
+
+  test('rejects a name carrying a separator, rather than nesting it', () => {
+    assert.deepStrictEqual(outcomeOf('production/us-east'), 'rejected');
+
+    assert.deepStrictEqual(
+      outcomeOf(String.raw`production\us-east`),
+      'rejected',
+    );
+  });
+
+  test('rejects the names that are not file names at all', () => {
+    assert.deepStrictEqual(outcomeOf(''), 'rejected');
+
+    assert.deepStrictEqual(outcomeOf('.'), 'rejected');
+
+    assert.deepStrictEqual(outcomeOf('..'), 'rejected');
+
+    assert.deepStrictEqual(outcomeOf('release\u{0}'), 'rejected');
+  });
+
+  test('says which name it refused', () => {
+    const result = Result.fromThrowable(() =>
+      settingsFilePath(dir, '../release'),
+    );
+
+    assert.isTrue(Result.isErr(result));
+
+    if (Result.isErr(result)) {
+      assert.isTrue(result.value.message.includes('../release'));
+    }
+  });
+});