チュートリアルの画像が欠けただけで、アプリごと立ち上がらなくなる設計でした。なくても動くはずの機能を、起動の必須の道から外します

// optional-step.ts — 「なくても本体は動く」処理を、失敗しても本体を巻き込まずに実行する
export type StepResult<T> =
  | { ok: true; value: T }
  | { ok: false; reason: 'error' | 'timeout'; error?: unknown };
 
type Options = {
  timeoutMs?: number; // 省略すると待ち時間に上限を付けない（人の操作を待つ処理用）
  onFail?: (name: string, reason: 'error' | 'timeout', error?: unknown) => void;
};
 
export async function optionalStep<T>(
  name: string,
  run: () => T | Promise<T>,
  { timeoutMs, onFail }: Options = {},
): Promise<StepResult<T>> {
  let timer: ReturnType<typeof setTimeout> | undefined;
  const racers: Promise<StepResult<T>>[] = [
    (async (): Promise<StepResult<T>> => {
      try {
        return { ok: true, value: await run() };
      } catch (error) {
        return { ok: false, reason: 'error', error }; // 例外は握りつぶさず、結果として返す
      }
    })(),
  ];
  if (timeoutMs !== undefined) {
    racers.push(
      new Promise<StepResult<T>>((resolve) => {
        timer = setTimeout(() => resolve({ ok: false, reason: 'timeout' }), timeoutMs);
      }),
    );
  }
  const result = await Promise.race(racers);
  if (timer !== undefined) clearTimeout(timer);
  if (!result.ok) {
    try {
      onFail?.(name, result.reason, result.error);
    } catch {
      // 記録の失敗で、さらに本体を止めない
    }
  }
  return result;
}

import { optionalStep } from './optional-step.ts';
 
export type Step = { id: string; title: string; image: string | null };
export type Deps = {
  version: string;
  storage: {
    get(key: string): Promise<string | null>;
    set(key: string, value: string): Promise<void>;
  };
  loadSteps(): Promise<Step[]>;
  checkAsset(uri: string): Promise<boolean>;
  show(steps: Step[]): Promise<void>;
  loadTimeoutMs?: number;
  onFail?: (name: string, reason: 'error' | 'timeout', error?: unknown) => void;
};
 
export async function maybeShowOnboarding(deps: Deps): Promise<'shown' | 'already' | 'skipped'> {
  const key = `onboarding:${deps.version}`;
  const opt = { onFail: deps.onFail };
 
  const flag = await optionalStep('read-flag', () => deps.storage.get(key), { ...opt, timeoutMs: 500 });
  if (!flag.ok) return 'skipped'; // 読めない端末では出さない。迷ったら出さない側に倒す
  if (flag.value !== null) return 'already';
 
  const loaded = await optionalStep('load-steps', () => deps.loadSteps(), {
    ...opt,
    timeoutMs: deps.loadTimeoutMs ?? 1500,
  });
  if (!loaded.ok || loaded.value.length === 0) {
    await optionalStep('write-flag', () => deps.storage.set(key, 'skipped'), opt); // 失敗したことも記録して、毎回の起動で同じ失敗を繰り返さない
    return 'skipped';
  }
 
  const steps: Step[] = [];
  for (const s of loaded.value) {
    let image = s.image;
    if (image !== null) {
      const check = await optionalStep(`asset:${s.id}`, () => deps.checkAsset(image as string), {
        ...opt,
        timeoutMs: 800,
      });
      if (!check.ok || check.value !== true) image = null; // 画像だけ諦める。説明文は出す
    }
    steps.push({ ...s, image });
  }
 
  const shown = await optionalStep('show', () => deps.show(steps), opt); // 人の操作を待つので、待ち時間の上限は付けない
  await optionalStep('write-flag', () => deps.storage.set(key, shown.ok ? 'done' : 'skipped'), opt);
  return shown.ok ? 'shown' : 'skipped';
}

// features/onboarding/load-steps.ts（開発ビルドだけで効く、欠落の再現用）
export async function loadSteps() {
  if (process.env.EXPO_PUBLIC_SIMULATE_MISSING === 'onboarding') {
    throw new Error('simulated: onboarding resource missing');
  }
  // 本来の読み込み
}

// 読み込みが返ってこなくても、起動が先へ進むこと
const t = mk({ loadSteps: () => new Promise(() => {}) });
assert.equal(await maybeShowOnboarding(t.deps), 'skipped');
assert.deepEqual(t.fails, ['load-steps:timeout']);

node test.ts

#!/usr/bin/env node
// audit-startup-path.mjs — 起動の入り口が、任意の機能を静的に読み込んでいないかを調べる
import { readFileSync } from 'node:fs';
 
const [, , configPath, ...entries] = process.argv;
if (!configPath || entries.length === 0) {
  console.error('usage: audit-startup-path.mjs <optional-patterns.json> <entry files...>');
  process.exit(2);
}
const patterns = JSON.parse(readFileSync(configPath, 'utf8')).optional.map((p) => new RegExp(p));
 
// 先頭が import か、行頭の require だけを見る（関数の中の遅延読み込みは対象外）
const staticLoad = /^(?:import\b[^'"]*['"]([^'"]+)['"]|(?:const|let|var)\s+[^=]+=\s*require\(\s*['"]([^'"]+)['"]\s*\))/;
 
let violations = 0;
for (const file of entries) {
  readFileSync(file, 'utf8').split('\n').forEach((line, i) => {
    const m = staticLoad.exec(line);
    const target = m && (m[1] ?? m[2]);
    if (target && patterns.some((re) => re.test(target))) {
      console.log(`${file}:${i + 1}: ${target}  任意機能が起動経路に直結しています`);
      violations += 1;
    }
  });
}
console.log(violations === 0 ? 'OK' : `${violations} violation(s)`);
process.exit(violations === 0 ? 0 : 1);

{ "optional": ["onboarding", "tutorial", "lottie"] }

node audit-startup-path.mjs optional-patterns.json app/_layout.tsx
# app/_layout.tsx:3: ../features/onboarding/Onboarding  任意機能が起動経路に直結しています
# 1 violation(s)