github-settings-as-code 3.1.0 → 3.2.0

package/src/github/environments/backup.mts

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+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 { environmentsDir } from '../constants.mjs';
+import { getAllEnvironments } from './api/index.mjs';
+
+const backupDir = path.resolve(environmentsDir, './bk');
+
+/** Settings > Environments の現在値を `bk/` に保存する。 */
+export const backupEnvironments = async (
+  fmt: boolean = true,
+): Promise<void> => {
+  await makeEmptyDir(backupDir);
+
+  const environments = await getAllEnvironments();
+
+  for (const environment of environments) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(
+      path.resolve(backupDir, `${environment.name}.json`),
+      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,53 @@
+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);
+
+export const readEnvironmentBackupFiles = async (): Promise<
+  readonly EnvironmentSettings[]
+> => readFilesIn(path.resolve(environmentsDir, './bk'));
+
+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,9 @@
 export * from './actions-settings/index.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 './variables/index.mjs';
+export * from './vulnerability-alerts/index.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,77 @@
+#!/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);
+
+    // eslint-disable-next-line security/detect-non-literal-fs-filename
+    await fs.writeFile(
+      path.resolve(vulnerabilityAlertsDir, 'bk', settingsJsonName),
+      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,36 @@
+#!/usr/bin/env node
+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 { settingsJsonName, vulnerabilityAlertsDir } from '../constants.mjs';
+import { getVulnerabilityAlerts } from './api/index.mjs';
+
+const backupDir = path.resolve(vulnerabilityAlertsDir, './bk');
+
+/** Dependabot alerts の現在値を `bk/` に保存する。 */
+export const backupVulnerabilityAlerts = async (
+  fmt: boolean = true,
+): Promise<void> => {
+  await makeEmptyDir(backupDir);
+
+  const settings = await getVulnerabilityAlerts();
+
+  // eslint-disable-next-line security/detect-non-literal-fs-filename
+  await fs.writeFile(
+    path.resolve(backupDir, 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';