配布する PowerShell インストーラを CI で検査する

社内メンバーに「この1行を PowerShell に貼って」と配る形のインストーラ（irm <URL> | iex 型）を 運用しているチーム向け。JS/TS のテストが緑でも、配布している .ps1 は無検査のまま全PCへ届く という穴を塞ぐ。実際にこれで全メンバーPCのインストーラが起動直後に死んだ事例をもとにしている。

前提

• 配布物は Git リポジトリの tools/install.ps1 などに置き、raw URL（/main/ 参照）で取得させている
• CI は GitHub Actions
• メンバーPCの既定シェルは Windows PowerShell 5.1（PowerShell 7 ではない）

塞ぐ穴（2種類の実害）

1. PowerShell のエスケープはバックスラッシュではない

正規表現をダブルクォート文字列に書くと事故る。

# NG: PowerShell の "..." 内で \ はただの文字。続く " で文字列がそこで終わり、
#     残りがコードとして解釈されてパースエラーになる（JS/bash の癖がそのまま出る）
if ($line -match "^export\s+(\w+)\s*=\s*['\"]?(.+?)['\"]?$") { }

# OK: 引用符を含む正規表現はシングルクォート文字列で書く（内部の ' は '' で重ねる）
if ($line -match '^export\s+(\w+)\s*=\s*[''"]?(.+?)[''"]?$') { }

PowerShell のエスケープ文字はバッククォート。正規表現の \r\n \s \w は 「正規表現側のエスケープ」なのでシングルクォート文字列にそのまま書ける。 引用符を含む正規表現は常にシングルクォート文字列を定石にすると、この事故が構造的に消える。

2. 日本語（非ASCII）を含む .ps1 は UTF-8 BOM が必須

BOM が無いと Windows PowerShell 5.1 はシステムコードページ（日本語環境なら CP932）として読む。 非ASCII文字が化け、化けた結果がトークンとして解釈されてパースエラーになる。 エディタや Git 上では正常に見えるので、目視レビューでは絶対に見つからない。

検査スクリプト

tools/pscheck.ps1 として置く。パース検査と BOM 検査を両方行う。

param([string]$Root = (Split-Path -Parent $PSScriptRoot))

$sep = [IO.Path]::DirectorySeparatorChar
$gitDir = "$sep.git$sep"
$fail = 0

Get-ChildItem -Path $Root -Recurse -Filter *.ps1 |
  Where-Object { -not $_.FullName.Contains($gitDir) } |
  Sort-Object FullName |
  ForEach-Object {
    $path = $_.FullName
    $rel = $path.Substring($Root.Length).TrimStart($sep)
    $problems = @()

    # 1) 非ASCII を含む .ps1 は UTF-8 BOM 必須（5.1 の CP932 誤読を防ぐ）
    $bytes = [IO.File]::ReadAllBytes($path)
    $hasBom = $bytes.Length -ge 3 -and $bytes[0] -eq 0xEF -and $bytes[1] -eq 0xBB -and $bytes[2] -eq 0xBF
    $text = [Text.Encoding]::UTF8.GetString($bytes)
    if (($text -match '[^\x00-\x7F]') -and -not $hasBom) {
      $problems += 'UTF-8 BOM がない（非ASCIIを含む .ps1 は BOM 必須）'
    }

    # 2) 構文チェック
    $errs = $null
    [void][System.Management.Automation.Language.Parser]::ParseFile($path, [ref]$null, [ref]$errs)
    if ($errs -and $errs.Count -gt 0) {
      $problems += ("パースエラー {0}件 / 先頭 line {1}: {2}" -f $errs.Count, $errs[0].Extent.StartLineNumber, $errs[0].Message)
    }

    if ($problems.Count -gt 0) {
      $fail++
      Write-Output ("FAIL {0}" -f $rel)
      foreach ($p in $problems) { Write-Output ("       - {0}" -f $p) }
    } else {
      Write-Output ("ok   {0}" -f $rel)
    }
  }

Write-Output ("=== .ps1 検査: 失敗 {0} ファイル ===" -f $fail)
if ($fail -gt 0) { exit 1 }

このファイル自身に日本語コメントを書くなら、このファイルにも BOM を付けること（自分の検査に落ちる）。

// BOM をバイト単位で付ける（テキストとして読み書きすると環境依存で壊れる）
import fs from 'node:fs';
const b = fs.readFileSync(p);
if (!(b[0] === 0xEF && b[1] === 0xBB && b[2] === 0xBF)) {
  fs.writeFileSync(p, Buffer.concat([Buffer.from([0xEF, 0xBB, 0xBF]), b]));
}

CI への配線（ここが最重要）

jobs:
  test:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4

      # 既存のテストなど...

      - name: .ps1 構文/文字コード検査 (Windows PowerShell 5.1)
        if: ${{ !cancelled() }}
        shell: powershell        # ← pwsh(PS7) ではなく 5.1 を明示する
        run: .\tools\pscheck.ps1

shell: powershell の明示が要点。 windows-latest の既定シェルは pwsh（PowerShell 7）で、 PS7 は BOM なし UTF-8 を正しく読むため、PS7 で検査すると上記「穴2」を検出できない。 メンバーPCの実体は 5.1 なので、5.1 で検査しないと実機の事故がそのまますり抜ける。

if: ${{ !cancelled() }} は、前ステップが失敗したときに後続ステップが silent skip されるのを防ぐため（skip されると「検査した」と誤認する）。

受け入れ確認（ここをやらないと意味がない）

検査器を書いたら、故障注入して実際に落ちることを確認する。沈黙して緑になる検査器は無いのと同じ。

1. \" を含む壊れた .ps1 を置く → FAIL すること
2. 非ASCII を含み BOM なしの .ps1 を置く → FAIL すること
3. 正常な .ps1 → ok すること
4. 上記1,2がある状態で 終了コードが 1 になること（パイプ経由だと最後のコマンドの 終了コードを見てしまうので、cmd > /dev/null; echo $? のように単体で確認する）

CI に足したあとは、ジョブのログでそのステップが実際に実行されたかを目視する。 ログに検査対象ファイルが列挙されていれば本当に走っている。

配布物を直したあとの確認

修正を push したら、メンバーが実際に踏むその raw URL を取得して、その実物を検査する。 リポジトリ内が直っていることは、配布されているものが直っている証拠にならない （raw のキャッシュで数分間は旧版が返ることがある）。

curl -sS "https://raw.githubusercontent.com/<owner>/<repo>/main/tools/install.ps1" -o live.ps1
# live.ps1 を pscheck.ps1 に通してから「配布可」と言う

一般化できる教訓

「その言語のリンタが CI に無い」＝「その言語のファイルは無検査で配布されている」。 リポジトリに複数言語が同居しているとき、緑のテストはチェックしている言語についてしか何も言っていない。 .ps1 .sh .bat .sql .tf など、テストランナーの対象外になりがちな配布物を棚卸しして、 それぞれに構文チェックを1本ずつ足すだけで、この種の事故はまとめて消える。