github-settings-as-code 3.1.0 → 4.0.0

package/src/github/variables/api/list-repo-variables.mts

@@ -23,5 +23,7 @@ export const listRepoVariables = async (): Promise<
     },
   );
 
-  return result.data.variables;
+  // `getAllEnvironments` と同じく名前順に整えて返す。宣言ファイルの中身が API
+  // の返す順に左右されると、値が変わっていない日にも diff が出る。
+  return result.data.variables.toSorted((a, b) => a.name.localeCompare(b.name));
 };

package/src/github/variables/apply.mts

@@ -1,43 +1,70 @@
 #!/usr/bin/env node
-
-// cspell:ignore lilpi
 import 'dotenv/config';
-import { isDirectlyExecuted } from 'ts-repo-utils';
+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 { settingsJsonName, variablesDir } from '../constants.mjs';
 import {
   createRepoVariable,
   listRepoVariables,
   updateRepoVariable,
 } from './api/index.mjs';
+import {
+  assertVariableNamesAreValid,
+  RepositoryVariables,
+} from './constants.mjs';
 
+/**
+ * `repo-settings/variables/settings.json` を Settings > Secrets and variables >
+ * Actions > Variables に反映する。
+ *
+ * ruleset や environment と同じく、**宣言に無い変数は消さない。** 消したい
+ * ときは宣言から外したうえで GitHub 側でも消す。 apply が片付けてしまうと、
+ * 誰かが GUI で足したものが「いつの間にか無くなる」ことになり、drift 検査が
+ * 報せるという見え方が働かなくなる。
+ */
 export const applyVariables = async (): Promise<void> => {
-  const variables = [
-    {
-      // noshiro-repo-settings-bot (App ID: 4476573)
-      // Administration を含む強い権限を持つ。設定の backup / apply 専用。
-      name: 'REPO_SETTINGS_BOT_CLIENT_ID',
-      value: 'Iv23ctr4Lq9H3wOYRQrD',
-    },
-    {
-      // noshiro-repo-automation-bot (App ID: 4478721)
-      // Contents / Pull requests / Issues 権限。PR を作る自動化（ pnpm-update ）と
-      // release で共用する。実際に使う権限は各ワークフローの permission-* 入力で
-      // 絞る。
-      name: 'REPO_AUTOMATION_BOT_CLIENT_ID',
-      value: 'Iv23lilpiDh0twq2PErv',
-    },
-  ] as const;
-
-  const variableListSaved = await listRepoVariables();
-
-  const variablesSaved: ReadonlySet<string> = new Set(
-    variableListSaved.map((v) => v.name),
+  const variables = await readSettings();
+
+  // 1 本目を送る前に、全部の名前を見る。
+  assertVariableNamesAreValid(variables);
+
+  const existing: ReadonlySet<string> = await listRepoVariables().then(
+    (vs) => new Set(vs.map((v) => v.name)),
+  );
+
+  for (const [name, value] of Object.entries(variables)) {
+    await (existing.has(name)
+      ? updateRepoVariable({ name, value })
+      : createRepoVariable({ name, value }));
+  }
+
+  // ここで live を読み直して書き戻すことはしない。 backup は live をそのまま
+  // 宣言に写す操作で、 live は宣言の上位集合になりうる — apply の締めに呼ぶと、
+  // 宣言していない変数まで黙って宣言に入る。送った値は宣言そのものなので、
+  // 書き戻して得られるものも無い。現在値を取り込みたいときは backup を明示的に
+  // 実行する。
+};
+
+const readSettings = async (): Promise<RepositoryVariables> => {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const settingsText = await fs.readFile(
+    path.resolve(variablesDir, settingsJsonName),
+    { encoding: 'utf8' },
   );
 
-  for (const variable of variables) {
-    const found = variablesSaved.has(variable.name);
+  const validationResult = RepositoryVariables.validate(
+    JSON.parse(settingsText),
+  );
 
-    await (found ? updateRepoVariable(variable) : createRepoVariable(variable));
+  if (Result.isErr(validationResult)) {
+    throw new Error(
+      t.validationErrorsToMessages(validationResult.value).join('\n'),
+    );
   }
+
+  return validationResult.value;
 };
 
 if (isDirectlyExecuted(import.meta.url)) {

package/src/github/variables/backup.mts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
+import { clearJsonFilesIn } from '../clear-json-files.mjs';
+import { settingsJsonName, variablesDir } from '../constants.mjs';
+import { listRepoVariables } from './api/index.mjs';
+import { type RepositoryVariables } from './constants.mjs';
+
+/**
+ * repository variable の現在値を宣言ファイルへ撮り直す。
+ *
+ * 宣言していないものも含めて live にあるものを全部書く。 backup は「いま何が
+ * あるか」を写す操作なので、 GUI で足された変数もここで宣言に入る。要らない
+ * ものは撮り直したあとに宣言から外し、 GitHub 側でも消す。
+ */
+export const backupVariables = async (fmt: boolean = true): Promise<void> => {
+  const variables = await listRepoVariables();
+
+  await clearJsonFilesIn(variablesDir);
+
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  await fs.writeFile(
+    path.resolve(variablesDir, settingsJsonName),
+    JSON.stringify(toDeclaration(variables), undefined, 2),
+  );
+
+  if (fmt) {
+    await formatUncommittedFiles();
+  }
+};
+
+/**
+ * API の配列を `settings.json` と同じ record に畳む。
+ *
+ * `created_at` / `updated_at` はここで落ちる。値が変わっていなくても動くので、
+ * 残すと宣言ファイルが毎日変わり、ドリフト検査が本当の変更を報せなくなる。
+ */
+export const toDeclaration = (
+  variables: Awaited<ReturnType<typeof listRepoVariables>>,
+): RepositoryVariables =>
+  Object.fromEntries(variables.map(({ name, value }) => [name, value]));
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await backupVariables();
+}

package/src/github/variables/constants.mts

@@ -0,0 +1,61 @@
+import { Arr } from 'ts-data-forge';
+import * as t from 'ts-fortress';
+
+/**
+ * `repo-settings/variables/settings.json` の型。
+ *
+ * Settings > Secrets and variables > Actions > Variables に対応する
+ * (`GET|POST /repos/{owner}/{repo}/actions/variables`,
+ * `PATCH /repos/{owner}/{repo}/actions/variables/{name}`)。
+ *
+ * 変数名をキー、値を値にした素の record にしてある。 API が返す配列
+ * (`{ name, value, created_at, updated_at }[]`) をそのまま写さないのは、
+ * `created_at` / `updated_at` が値の変化なしに動くためで、宣言に入れると
+ * 毎日ドリフトとして出てしまう。ここで持つのは宣言できるものだけ。
+ *
+ * **ここに秘密を書かないこと。** repository variable は API でも Actions の
+ * ログでも平文で読める。秘密は secret 側で、そちらはこのツールの管理外にある。
+ */
+export const RepositoryVariables = t.keyValueRecord(t.string(), t.string(), {
+  typeName: 'RepositoryVariables',
+});
+
+export type RepositoryVariables = t.TypeOf<typeof RepositoryVariables>;
+
+/**
+ * GitHub が受け付けない変数名を、送る前にすべて挙げて落とす。
+ *
+ * 名前は `PATCH .../actions/variables/{name}` のパスに入る。 octokit が URL
+ * エンコードするので注入にはならないが、弾かれる名前は 422 になり、それが
+ * 起きるのは**何本か書き込んだ後**である。 environments の `assertConsistent`
+ * と同じ理由でここに置いてある — 1 本目を送る前に全部の名前を見ておけば、
+ * この種の間違いで中途半端に適用された状態にはならない。
+ *
+ * 規則は GitHub の documentation のとおり: 英数字と `_` のみ、先頭に数字は
+ * 不可、`GITHUB_` 始まりは予約。名前の大文字小文字は区別されないので、
+ * 予約接頭辞の判定も区別しない。
+ */
+export const assertVariableNamesAreValid = (
+  variables: RepositoryVariables,
+): void => {
+  const offenders = Object.keys(variables).filter(
+    (name) => !isValidVariableName(name),
+  );
+
+  if (Arr.isNonEmpty(offenders)) {
+    throw new Error(
+      [
+        `repository variable の名前として使えないものがあります: ${offenders
+          .map((name) => JSON.stringify(name))
+          .join(', ')}。`,
+        '英数字と "_" のみが使え、先頭に数字は置けず、"GITHUB_" 始まりは予約されています。',
+      ].join('\n'),
+    );
+  }
+};
+
+/** 先頭は英字か `_`、以降は英数字か `_`。入れ子の量化子は無いので線形。 */
+const variableNamePattern = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+
+const isValidVariableName = (name: string): boolean =>
+  variableNamePattern.test(name) && !name.toUpperCase().startsWith('GITHUB_');

package/src/github/variables/constants.test.mts

@@ -0,0 +1,110 @@
+import { Result } from 'ts-data-forge';
+import {
+  assertVariableNamesAreValid,
+  RepositoryVariables,
+} from './constants.mjs';
+
+/** `'rejected'` when the names were refused, `'accepted'` when they were not. */
+const outcomeOf = (variables: RepositoryVariables): string =>
+  Result.isErr(
+    Result.fromThrowable(() => {
+      assertVariableNamesAreValid(variables);
+    }),
+  )
+    ? 'rejected'
+    : 'accepted';
+
+describe('the repository-variables schema', () => {
+  test('accepts a declaration of names to values', () => {
+    const result = RepositoryVariables.validate({
+      REPO_AUTOMATION_BOT_CLIENT_ID: 'Iv1example0client0id',
+    });
+
+    assert.isTrue(Result.isOk(result));
+
+    if (Result.isOk(result)) {
+      assert.deepStrictEqual(result.value, {
+        REPO_AUTOMATION_BOT_CLIENT_ID: 'Iv1example0client0id',
+      });
+    }
+  });
+
+  test('accepts an empty declaration', () => {
+    assert.isTrue(Result.isOk(RepositoryVariables.validate({})));
+  });
+
+  test('rejects a value that is not a string', () => {
+    // A variable's value is always a string on GitHub's side. A number here
+    // would be sent as one and read back as `"4476573"`, which reads as drift
+    // on the next backup.
+    assert.isTrue(
+      Result.isErr(RepositoryVariables.validate({ A_NUMBER: 123 })),
+    );
+
+    assert.isTrue(Result.isErr(RepositoryVariables.validate({ A_NULL: null })));
+  });
+
+  test('rejects a declaration that is not a record', () => {
+    assert.isTrue(Result.isErr(RepositoryVariables.validate([])));
+
+    assert.isTrue(Result.isErr(RepositoryVariables.validate('')));
+
+    assert.isTrue(Result.isErr(RepositoryVariables.validate(null)));
+  });
+});
+
+describe(assertVariableNamesAreValid, () => {
+  test('accepts the names GitHub accepts', () => {
+    assert.deepStrictEqual(
+      outcomeOf({
+        REPO_AUTOMATION_BOT_CLIENT_ID: 'x',
+        lowercase_is_allowed: 'x',
+        _LEADING_UNDERSCORE: 'x',
+        MIXED_Case_9: 'x',
+      }),
+      'accepted',
+    );
+  });
+
+  test('rejects a name starting with a digit', () => {
+    assert.deepStrictEqual(outcomeOf({ '1ST_PLACE': 'x' }), 'rejected');
+  });
+
+  test('rejects a name carrying a character GitHub does not allow', () => {
+    assert.deepStrictEqual(outcomeOf({ 'WITH-HYPHEN': 'x' }), 'rejected');
+
+    assert.deepStrictEqual(outcomeOf({ 'WITH SPACE': 'x' }), 'rejected');
+
+    assert.deepStrictEqual(outcomeOf({ 'WITH.DOT': 'x' }), 'rejected');
+  });
+
+  test('rejects the reserved GITHUB_ prefix, in any case', () => {
+    assert.deepStrictEqual(outcomeOf({ GITHUB_TOKEN: 'x' }), 'rejected');
+
+    assert.deepStrictEqual(outcomeOf({ github_token: 'x' }), 'rejected');
+  });
+
+  test('rejects an empty name', () => {
+    assert.deepStrictEqual(outcomeOf({ '': 'x' }), 'rejected');
+  });
+
+  test('names every offender, so one run fixes the file', () => {
+    const result = Result.fromThrowable(() => {
+      assertVariableNamesAreValid({
+        'WITH-HYPHEN': 'x',
+        GITHUB_TOKEN: 'x',
+        FINE: 'x',
+      });
+    });
+
+    assert.isTrue(Result.isErr(result));
+
+    if (Result.isErr(result)) {
+      assert.isTrue(result.value.message.includes('WITH-HYPHEN'));
+
+      assert.isTrue(result.value.message.includes('GITHUB_TOKEN'));
+
+      assert.isFalse(result.value.message.includes('FINE'));
+    }
+  });
+});

package/src/github/variables/index.mts

@@ -1,2 +1,4 @@
 export * from './api/index.mjs';
 export * from './apply.mjs';
+export * from './backup.mjs';
+export * from './constants.mjs';

package/src/github/vulnerability-alerts/api/get-vulnerability-alerts.mts

@@ -0,0 +1,31 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { hasKey, isRecord } from 'ts-data-forge';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { VulnerabilityAlertsSettings } from '../constants.mjs';
+
+/**
+ * Dependabot alerts が有効かどうかを取得する。
+ *
+ * このエンドポイントは body を返さない: 有効なら 204、無効なら 404。
+ * octokit は 404 を例外にするので、それを `enabled: false` として扱う。
+ * 「無効」と「読めなかった」は区別する必要があるため、 404 以外は投げ直す。
+ */
+export const getVulnerabilityAlerts =
+  async (): Promise<VulnerabilityAlertsSettings> => {
+    try {
+      // https://docs.github.com/rest/repos/repos#check-if-vulnerability-alerts-are-enabled-for-a-repository
+      await octokit.request(
+        'GET /repos/{owner}/{repo}/vulnerability-alerts' satisfies EndpointKeys,
+        { owner: OWNER, repo: REPO, headers: octokitHeaders },
+      );
+
+      return VulnerabilityAlertsSettings.fill({ enabled: true });
+    } catch (error) {
+      if (isRecord(error) && hasKey(error, 'status') && error.status === 404) {
+        return VulnerabilityAlertsSettings.fill({ enabled: false });
+      }
+
+      throw error;
+    }
+  };

package/src/github/vulnerability-alerts/api/index.mts

@@ -0,0 +1,2 @@
+export * from './get-vulnerability-alerts.mjs';
+export * from './set-vulnerability-alerts.mjs';

package/src/github/vulnerability-alerts/api/set-vulnerability-alerts.mts

@@ -0,0 +1,31 @@
+import { type EndpointKeys } from 'octokit-safe-types';
+import { octokitHeaders, OWNER, REPO } from '../../constants.mjs';
+import { octokit } from '../../octokit.mjs';
+import { type VulnerabilityAlertsSettings } from '../constants.mjs';
+
+/**
+ * Dependabot alerts を JSON の内容に合わせる。
+ *
+ * 有効化と無効化で別メソッドなので、書き込みは 1 回で済むように分岐する。
+ * `enabled: false` はきちんと無効化する — 宣言が現状に合わせて黙るなら、
+ * ファイルを読んでも何が有効なのか分からなくなる。
+ */
+export const setVulnerabilityAlerts = async (
+  settings: VulnerabilityAlertsSettings,
+): Promise<void> => {
+  if (settings.enabled) {
+    // https://docs.github.com/rest/repos/repos#enable-vulnerability-alerts
+    await octokit.request(
+      'PUT /repos/{owner}/{repo}/vulnerability-alerts' satisfies EndpointKeys,
+      { owner: OWNER, repo: REPO, headers: octokitHeaders },
+    );
+
+    return;
+  }
+
+  // https://docs.github.com/rest/repos/repos#disable-vulnerability-alerts
+  await octokit.request(
+    'DELETE /repos/{owner}/{repo}/vulnerability-alerts' satisfies EndpointKeys,
+    { owner: OWNER, repo: REPO, headers: octokitHeaders },
+  );
+};

package/src/github/vulnerability-alerts/apply.mts

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as t from 'ts-fortress';
+import {
+  formatUncommittedFiles,
+  isDirectlyExecuted,
+  pathExists,
+  Result,
+} from 'ts-repo-utils';
+import { settingsJsonName, vulnerabilityAlertsDir } from '../constants.mjs';
+import {
+  getVulnerabilityAlerts,
+  setVulnerabilityAlerts,
+} from './api/index.mjs';
+import { VulnerabilityAlertsSettings } from './constants.mjs';
+
+/**
+ * `repo-settings/vulnerability-alerts/settings.json` を Dependabot alerts に反映する。
+ *
+ * 設定ファイルを置いていない repository では何もしない。 pages と同じ理由 —
+ * この package は他の repository からも使われるので、ファイルの不在を
+ * 「無効にせよ」と読むと、宣言していない設定を勝手に落としてしまう。
+ */
+export const applyVulnerabilityAlerts = async (): Promise<void> => {
+  const settingsPath = path.resolve(vulnerabilityAlertsDir, settingsJsonName);
+
+  if (!(await pathExists(settingsPath))) {
+    return;
+  }
+
+  const settings = await readSettings(settingsPath);
+
+  await setVulnerabilityAlerts(settings);
+
+  // 反映後の実際の値でローカルのファイルを更新する
+  {
+    const applied = await getVulnerabilityAlerts();
+
+    const str = JSON.stringify(applied, undefined, 2);
+
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(settingsPath, str);
+
+    await formatUncommittedFiles();
+  }
+};
+
+const readSettings = async (
+  settingsPath: string,
+): Promise<VulnerabilityAlertsSettings> => {
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  const settingsText = await fs.readFile(settingsPath, { encoding: 'utf8' });
+
+  const validationResult = VulnerabilityAlertsSettings.validate(
+    JSON.parse(settingsText),
+  );
+
+  if (Result.isErr(validationResult)) {
+    throw new Error(
+      t.validationErrorsToMessages(validationResult.value).join('\n'),
+    );
+  }
+
+  return validationResult.value;
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await applyVulnerabilityAlerts();
+}

package/src/github/vulnerability-alerts/backup.mts

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { formatUncommittedFiles, isDirectlyExecuted } from 'ts-repo-utils';
+import { clearJsonFilesIn } from '../clear-json-files.mjs';
+import { settingsJsonName, vulnerabilityAlertsDir } from '../constants.mjs';
+import { getVulnerabilityAlerts } from './api/index.mjs';
+
+/** Dependabot alerts の現在値を宣言ファイルへ撮り直す。 */
+export const backupVulnerabilityAlerts = async (
+  fmt: boolean = true,
+): Promise<void> => {
+  const settings = await getVulnerabilityAlerts();
+
+  await clearJsonFilesIn(vulnerabilityAlertsDir);
+
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  await fs.writeFile(
+    path.resolve(vulnerabilityAlertsDir, settingsJsonName),
+    JSON.stringify(settings, undefined, 2),
+  );
+
+  if (fmt) {
+    await formatUncommittedFiles();
+  }
+};
+
+if (isDirectlyExecuted(import.meta.url)) {
+  await backupVulnerabilityAlerts();
+}

package/src/github/vulnerability-alerts/constants.mts

@@ -0,0 +1,25 @@
+import * as t from 'ts-fortress';
+
+/**
+ * `repo-settings/vulnerability-alerts/settings.json` の型。
+ *
+ * Settings > Advanced Security > Dependabot alerts に対応する。
+ *
+ * `security_and_analysis` とは別の API
+ * (`GET|PUT|DELETE /repos/{owner}/{repo}/vulnerability-alerts`) で、
+ * 値も JSON body ではなく 204 / 404 で返ってくる。そのため
+ * `repository-settings/settings.json` には載せられず、 pages と同じく
+ * 独立した設定ファイルにしている。
+ *
+ * `repository-settings/settings.json` の `dependabot_security_updates` は
+ * これとは別物 — あちらは「脆弱な依存を直す PR を自動で作るか」で、
+ * この repository では `pnpm-update` が lockfile を持っているため無効のまま。
+ * ここで管理するのは「既知の脆弱性を知らせるか」だけ。
+ */
+export const VulnerabilityAlertsSettings = t.record({
+  enabled: t.boolean(false),
+});
+
+export type VulnerabilityAlertsSettings = t.TypeOf<
+  typeof VulnerabilityAlertsSettings
+>;

package/src/github/vulnerability-alerts/index.mts

@@ -0,0 +1,4 @@
+export * from './api/index.mjs';
+export * from './apply.mjs';
+export * from './backup.mjs';
+export * from './constants.mjs';