@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/ds-canonical/fork/consumer/managed-files/68bfcddff9c4a16388c248cd34fb66163e9e64b3d809a48ef3984f6ae4ff6d12.blob

@@ -0,0 +1,211 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// 凍結受測建置:把 storybook-static 複製成本次執行獨佔的快照
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// **為什麼有這個**(2026-09-24,本機誤紅一次):
+// `data-table-invariants.mjs` 在 :156 `waitForSelector` 逾時 30 秒,重跑就綠。實際經過:
+// 另一個 agent 在**同一份工作樹**跑 `npm run build-storybook`(10:24:00 起,10:26:13 建完),
+// Storybook 8 的 build 第一步就是把輸出目錄整個刪掉再重寫
+// (node_modules/@storybook/core/dist/core-server/index.js「Cleaning outputDir」→ rm recursive),
+// 前 ~70 秒 iframe.html 與 assets/ 都不存在。閘的第一次導覽用的是舊檔、成功;第二次導覽時目錄
+// 已被清空 → 資源 404 → story 永遠不渲染 → 30 秒後被當成「表格沒有列」。重跑之所以綠,只是因為
+// 那時對方剛好建完了。
+//
+// 這是 M37:閘開頭的 stale-build 守衛驗的是「那一刻的那份建置」,之後每次導覽讀的卻是
+// 「路徑 storybook-static 底下當下剛好有的東西」—— 把「路徑」當成「建置身分」。
+//
+// 正解:守衛通過之後,把那份建置複製到只有本次執行讀得到的暫存目錄,後續一律從快照供檔。
+// 身分標記用既有的 build-info.json(scripts/gen-build-info.mjs):它是 `npm run build-storybook`
+// **最後**寫的檔、內含 builtAt 毫秒時間戳,而重建的第一步會把它刪掉 —— 所以
+//   「複製前後都存在且逐位元組相同」⇔「複製期間沒有任何重建開始或結束」。
+// 不存在 = 目前沒有完整的建置(正在重建或從沒建完),以**儀器失效**的名義紅,不指控被測物。
+//
+// **第二道:建置完整性(2026-09-25)**。上面那道只證明「複製期間沒人重建」,證明不了「建完之後檔還是
+// 當時那些檔」—— 同一天本機的 storybook-static 被雲端同步弄壞:一批 chunk 變成 0 位元組、另外冒出
+// `<name> 2.js` 衝突副本,而 build-info.json 完好如初。標記「存在且沒變」被當成「建置完整」(M37 同一種代理)。
+// 所以 gen-build-info.mjs 在建置最後把**每個檔的相對路徑與位元組數**寫進 build-info.json 的 `manifest`
+// (再加整份清單的 sha256),這裡對**複製出來的快照**逐檔核對:
+//   清單裡的檔不見了 / 大小不同 → 以儀器失效拒絕,點名前幾個檔(「這不是被測元件的失敗」);
+//   清單外多出來的檔(衝突副本、部署時另寫的 deployment.json)→ 不影響量測,只記一筆說明;
+//   舊建置沒有 manifest → 印一行警告照常放行(CI 每次都重建,這個分支只會出現在本機舊產物上)。
+// 注意:本檔會交付給 consumer(scripts/build-fork-governance.mjs),不得 import 本 repo 限定的模組;
+// 「儀器失效」的標記字 INSTRUMENT-FAIL 與 scripts/lib/launch-browser.mjs 相同(test-storybook-static-snapshot 斷言)。
+
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+export class StorybookBuildNotStableError extends Error {}
+
+const MARKER = 'build-info.json'
+const SNAPSHOT_PREFIX = 'storybook-static-snapshot-'
+const INSTRUMENT_FAIL = 'INSTRUMENT-FAIL'
+// 建置不完整時訊息裡最多點名幾個檔(其餘只給數量)
+const MAX_NAMED_FILES = 8
+// 正常結束、丟例外都會在 exit 時刪快照;只有被 SIGKILL / 逾時強制中止的那一次會留下(每份約 16MB)。
+// 下一次建快照時順手清掉「超過這個年紀」的殘留 —— 年紀取得夠長,不會刪到別人正在用的那份
+// (最慢的全 story 掃描約 6 分鐘,這裡給 6 小時)。清不掉就算了,不影響本次量測。
+const STALE_SNAPSHOT_AGE_MS = 6 * 60 * 60 * 1000
+
+export function sweepStaleSnapshots({ root = tmpdir(), now = Date.now(), maxAgeMs = STALE_SNAPSHOT_AGE_MS } = {}) {
+  const removed = []
+  let entries = []
+  try { entries = readdirSync(root) } catch { return removed }
+  for (const name of entries) {
+    if (!name.startsWith(SNAPSHOT_PREFIX)) continue
+    const dir = join(root, name)
+    try {
+      if (now - statSync(dir).mtimeMs <= maxAgeMs) continue
+      rmSync(dir, { recursive: true, force: true })
+      removed.push(dir)
+    } catch { /* 別人剛好在刪,或沒權限 —— 不影響本次 */ }
+  }
+  return removed
+}
+
+// ─── 檔案清單(寫:gen-build-info.mjs;讀:snapshotStorybookStatic)──────────────
+
+/** 建置目錄裡每個一般檔的 [相對路徑('/' 分隔), 位元組數],依路徑排序;不含根目錄的 build-info.json 本身。 */
+function listBuildFiles(dir) {
+  const out = []
+  const walk = (rel) => {
+    for (const name of readdirSync(join(dir, rel))) {
+      const relPath = rel ? `${rel}/${name}` : name
+      if (relPath === MARKER) continue
+      const info = lstatSync(join(dir, relPath))
+      if (info.isDirectory()) walk(relPath)
+      else if (info.isFile()) out.push([relPath, info.size])
+    }
+  }
+  walk('')
+  return out.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+}
+
+const manifestDigest = (files) => createHash('sha256').update(JSON.stringify(files)).digest('hex')
+
+/**
+ * 算出建置目錄的檔案清單:`{ version, algorithm, fileCount, totalBytes, sha256, files: { 相對路徑: 位元組數 } }`。
+ * sha256 = 整份 files(依路徑排序後的 JSON)的雜湊 —— 同一份建置恆得同一個值,可直接比較兩份建置是否逐檔同大小。
+ */
+export function buildFileManifest(dir) {
+  const entries = listBuildFiles(dir)
+  const files = Object.fromEntries(entries)
+  return {
+    version: 1,
+    algorithm: 'sha256',
+    fileCount: entries.length,
+    totalBytes: entries.reduce((sum, [, size]) => sum + size, 0),
+    sha256: manifestDigest(files),
+    files,
+  }
+}
+
+/**
+ * **刻意**改動建置之後(例:meta-test 往建好的 CSS 注入違規)重簽 build-info.json 的檔案清單,
+ * 否則快照的完整性核對會先以儀器失效拒絕 —— 那個紅不是「偵測到違規」。回傳原本的 build-info.json 原文,
+ * 呼叫端還原建置時一併寫回。
+ */
+export function resignBuildManifest(dir) {
+  const markerPath = join(dir, MARKER)
+  const original = readFileSync(markerPath, 'utf8')
+  writeFileSync(markerPath, JSON.stringify({ ...JSON.parse(original), manifest: buildFileManifest(dir) }, null, 2))
+  return original
+}
+
+/**
+ * 用 build-info.json 的 manifest 核對一個目錄(snapshotStorybookStatic 對快照呼叫;也可單獨用)。
+ * @returns {{ status: 'verified', fileCount: number, extras: string[] } | { status: 'no-manifest' }}
+ * @throws {StorybookBuildNotStableError} 清單本身不一致、或有檔缺少 / 大小不符
+ */
+export function verifyBuildManifest(dir, manifest) {
+  if (manifest == null) return { status: 'no-manifest' }
+  const files = manifest.files
+  if (!files || typeof files !== 'object' || Array.isArray(files) || manifestDigest(files) !== manifest.sha256) {
+    throw new StorybookBuildNotStableError(
+      `${INSTRUMENT_FAIL}: build-info.json 的檔案清單本身不一致(sha256 對不上或格式錯)—— 無法證明這是一份完整的建置。` +
+      '這不是被測元件的失敗;重新跑 `npm run build-storybook`。',
+    )
+  }
+  const bad = []
+  for (const [relPath, size] of Object.entries(files)) {
+    let actual = null
+    try { const info = lstatSync(join(dir, relPath)); if (info.isFile()) actual = info.size } catch { /* 不存在 */ }
+    if (actual === null) bad.push(`${relPath}(不見了)`)
+    else if (actual !== size) bad.push(`${relPath}(${actual} 位元組,建置時 ${size})`)
+  }
+  if (bad.length) {
+    const named = bad.slice(0, MAX_NAMED_FILES).join('、')
+    throw new StorybookBuildNotStableError(
+      `${INSTRUMENT_FAIL}: 建置不完整:${bad.length} / ${Object.keys(files).length} 個檔缺少或大小與建置時不同 —— ${named}` +
+      `${bad.length > MAX_NAMED_FILES ? ` …另 ${bad.length - MAX_NAMED_FILES} 個` : ''}。` +
+      '建完之後有東西截斷或刪了檔(雲端同步衝突、別人清目錄)。這不是被測元件的失敗;重新跑 `npm run build-storybook`。',
+    )
+  }
+  const listed = new Set(Object.keys(files))
+  const extras = listBuildFiles(dir).map(([relPath]) => relPath).filter((relPath) => !listed.has(relPath))
+  return { status: 'verified', fileCount: listed.size, extras }
+}
+
+// ─── 快照 ───────────────────────────────────────────────────────────────────
+
+// `copy` 只給測試注入(在複製途中改動標記,確定性地走到「複製期間被重建」那一枝);正式呼叫一律用預設。
+// `log` 只給測試注入(收集警告 / 說明);正式呼叫印到 stderr。
+export function snapshotStorybookStatic(staticDir, {
+  copy = (from, to) => cpSync(from, to, { recursive: true }),
+  log = (line) => console.error(line),
+} = {}) {
+  const markerPath = join(staticDir, MARKER)
+  const readMarker = () => (existsSync(markerPath) ? readFileSync(markerPath, 'utf8') : null)
+  const before = readMarker()
+  if (before === null) {
+    throw new StorybookBuildNotStableError(
+      `${INSTRUMENT_FAIL}: ${markerPath} 不存在 —— storybook-static 不是一份完整的建置(正在重建,或上次沒建完)。` +
+      '這不是被測元件的失敗;等建置完成(或跑 `npm run build-storybook`)再執行。',
+    )
+  }
+  sweepStaleSnapshots()
+  const dir = mkdtempSync(join(tmpdir(), SNAPSHOT_PREFIX))
+  try {
+    copy(staticDir, dir)
+  } catch (error) {
+    rmSync(dir, { recursive: true, force: true })
+    throw new StorybookBuildNotStableError(`${INSTRUMENT_FAIL}: 複製 storybook-static 失敗(複製期間目錄被改動?):${error.message}`)
+  }
+  const after = readMarker()
+  const copied = existsSync(join(dir, MARKER)) ? readFileSync(join(dir, MARKER), 'utf8') : null
+  if (after !== before || copied !== before) {
+    rmSync(dir, { recursive: true, force: true })
+    throw new StorybookBuildNotStableError(
+      `${INSTRUMENT_FAIL}: 複製期間 storybook-static 被重建(build-info.json 前後不一致)—— 快照不是單一建置。這不是被測元件的失敗。`,
+    )
+  }
+  let buildInfo
+  let integrity
+  try {
+    buildInfo = JSON.parse(before)
+    // 核對的是**快照**(之後供檔的就是它),不是活目錄
+    integrity = verifyBuildManifest(dir, buildInfo.manifest)
+  } catch (error) {
+    rmSync(dir, { recursive: true, force: true })
+    if (error instanceof StorybookBuildNotStableError) throw error
+    throw new StorybookBuildNotStableError(`${INSTRUMENT_FAIL}: 讀不懂 ${markerPath}(${error.message})—— 無法確認建置身分。這不是被測元件的失敗。`)
+  }
+  if (integrity.status === 'no-manifest') {
+    log(`⚠️  ${markerPath} 沒有檔案清單(舊版建置):這次不核對建置完整性;重新 npm run build-storybook 即會補上。`)
+  } else if (integrity.extras.length) {
+    log(`· 建置快照:${integrity.fileCount} 個檔逐一核對大小相符;另有 ${integrity.extras.length} 個檔不在清單裡(例:${integrity.extras.slice(0, 3).join('、')})—— 不是這次建置的產物(雲端同步衝突副本等),已忽略。`)
+  }
+  let disposed = false
+  return Object.freeze({
+    dir,
+    buildInfo,
+    /** { status: 'verified', fileCount, extras } 或 { status: 'no-manifest' } */
+    integrity: Object.freeze(integrity),
+    dispose() {
+      if (disposed) return
+      disposed = true
+      rmSync(dir, { recursive: true, force: true })
+    },
+  })
+}

package/ds-canonical/fork/consumer/managed-files/7eb6cc60abfdabaf6617c336058fad1454ccde08889295767bfd9b7fd153cc6e.blob

@@ -291,20 +291,59 @@ async function downloadCanonicalRegistryTarball(url, {
   })
 }
 
-export async function downloadCanonicalNpmTarball(url, { timeoutMs = 30_000 } = {}) {
-  return downloadCanonicalRegistryTarball(url, {
+// 2026-09-29(ab9a4e1a 那一輪:governance control plane job 在任何閘之前死在「canonical npm download timed out」,
+// PAT 沒有 actions:write 不能重跑;與 09-24 `npm audit` 的 ECONNRESET 同一族)。只對**暫時性傳輸失敗**重試 ——
+// 逾時、連線被重設／拒絕、DNS 暫時失敗、socket hang up、上游 502/503/504 —— 上限 3 次、退避 2s/4s;
+// 契約失敗(非 canonical origin / 重導向 / 內容編碼 / 超出封閉預算 / 長度不符 / 空檔)一律不重試,用盡仍 fail closed、
+// 訊息帶 attempts。下載回來的位元組仍走原本的 SHA-512 / lock digest 驗證,重試不放寬任何完整性檢查。
+// 判定抽成純函式 `isTransientRegistryDownloadFailure`,測試兩面對照(該重試的、不該重試的)。
+export const NPM_RUNTIME_DOWNLOAD_RETRY_LIMIT = 3
+export const NPM_RUNTIME_DOWNLOAD_BACKOFF_MS = 2_000
+const TRANSIENT_DOWNLOAD_REASON = /download timed out|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|EPIPE|socket hang up|download returned HTTP 50[234]\b/i
+const CONTRACT_DOWNLOAD_REASON = /outside the canonical registry contract|unexpected content encoding|closed archive budget|differs from Content-Length|download is empty/i
+export function isTransientRegistryDownloadFailure(error) {
+  const text = String(error?.message || '')
+  return TRANSIENT_DOWNLOAD_REASON.test(text) && !CONTRACT_DOWNLOAD_REASON.test(text)
+}
+
+export async function downloadWithTransientRetry(attempt, {
+  label = 'canonical registry',
+  retryLimit = NPM_RUNTIME_DOWNLOAD_RETRY_LIMIT,
+  backoffMs = NPM_RUNTIME_DOWNLOAD_BACKOFF_MS,
+  sleep = (ms) => new Promise((resolvePromise) => setTimeout(resolvePromise, ms)),
+  report = (line) => console.error(line),
+} = {}) {
+  invariant(typeof attempt === 'function', `${label} download attempt must be a function`)
+  invariant(Number.isInteger(retryLimit) && retryLimit >= 1, `${label} download retry limit must be a positive integer`)
+  for (let attemptNumber = 1; ; attemptNumber += 1) {
+    try {
+      return await attempt(attemptNumber)
+    } catch (error) {
+      if (!isTransientRegistryDownloadFailure(error)) throw error
+      if (attemptNumber >= retryLimit) {
+        throw new Error(`${String(error?.message || error)}(after ${attemptNumber} attempts)`)
+      }
+      const wait = backoffMs * attemptNumber
+      report(`⚠️  GOV-NPM-RUNTIME-001:${label} download transient failure(attempt ${attemptNumber}/${retryLimit}),retrying in ${wait}ms:${String(error?.message || error).slice(0, 240)}`)
+      await sleep(wait)
+    }
+  }
+}
+
+export async function downloadCanonicalNpmTarball(url, { timeoutMs = 30_000, retryLimit, backoffMs, sleep, report } = {}) {
+  return downloadWithTransientRetry(() => downloadCanonicalRegistryTarball(url, {
     label: 'canonical npm',
     pathPattern: /^\/npm\/-\/npm-\d+\.\d+\.\d+\.tgz$/,
     timeoutMs,
-  })
+  }), { label: 'canonical npm', retryLimit, backoffMs, sleep, report })
 }
 
-export async function downloadCanonicalNpmSecurityOverlayTarball(url, { timeoutMs = 30_000 } = {}) {
-  return downloadCanonicalRegistryTarball(url, {
+export async function downloadCanonicalNpmSecurityOverlayTarball(url, { timeoutMs = 30_000, retryLimit, backoffMs, sleep, report } = {}) {
+  return downloadWithTransientRetry(() => downloadCanonicalRegistryTarball(url, {
     label: 'canonical npm security overlay',
     pathPattern: /^\/(?:brace-expansion\/-\/brace-expansion-5\.0\.9|tar\/-\/tar-7\.5\.22)\.tgz$/,
     timeoutMs,
-  })
+  }), { label: 'canonical npm security overlay', retryLimit, backoffMs, sleep, report })
 }
 
 function decodeTarField(header, offset, length, label) {

package/ds-canonical/fork/consumer/managed-files/92e4828cdcb96ff0d01daa16f6885f24045a8e72820665650f2a1890dc3a446c.blob

@@ -2,6 +2,7 @@ import fs from 'node:fs'
 import { createServer } from 'node:http'
 import path from 'node:path'
 import { isContainedPath } from './canonical-path-containment.mjs'
+import { snapshotStorybookStatic } from './storybook-static-snapshot.mjs'
 
 const LOOPBACK_HOST = '127.0.0.1'
 const CONTENT_TYPES = new Map([
@@ -64,9 +65,26 @@ export function resolveA11yStaticFile(rootDirectory, requestUrl, { defaultFile =
 }
 
 /** Start one owned ephemeral loopback server and return its unforgeable origin + awaited stop. */
-export async function startA11yStaticServer({ rootDirectory, defaultFile = 'index.html' } = {}) {
-  const root = canonicalStaticRoot(rootDirectory)
+// **Storybook 建置一律從本次獨佔的快照供檔**(2026-09-24):根目錄裡有 build-info.json(= 一份完整的
+// `npm run build-storybook` 產物)時,先凍結成快照再服務,不再每次請求讀活目錄。錨例:
+// data-table-invariants.mjs 本機誤紅 —— 另一個 agent 同時 build-storybook,第一步就清空輸出目錄,
+// 後續導覽全部 404,被判成「表格沒有列」(M37:把「路徑」當成「建置身分」)。沒有 build-info.json 的
+// 根目錄(consumer dist 等)照舊直接服務;建置不完整或複製期間被重建 → 以「儀器失效」的名義丟出。
+// `notFound` 是同源 404 帳本:快照不會再變,任何 404 都是「建置缺檔」或「story 要了不存在的檔」,
+// 呼叫端失敗時應一併印出,不讓「儀器沒拿到檔」被讀成「元件沒渲染」。
+export async function startA11yStaticServer({ rootDirectory, defaultFile = 'index.html', snapshot = 'auto' } = {}) {
+  const liveRoot = canonicalStaticRoot(rootDirectory)
   safeDefaultFile(defaultFile)
+  // 「這是一份 Storybook 建置」的判定:有完成標記,或目錄就叫 storybook-static。後者沒有標記 = 別人正在重建
+  // (重建第一步就刪標記、最後才寫回)或從沒建完 —— 這時 snapshotStorybookStatic 會以「儀器失效」丟出,
+  // 不再退回讀活目錄(那正是 2026-09-24 誤紅的路徑)。其他根目錄(consumer dist、暫存頁)照舊直接服務。
+  const isStorybookBuild = fs.existsSync(path.join(liveRoot, 'build-info.json')) || path.basename(liveRoot) === 'storybook-static'
+  const frozen = (snapshot === 'auto' && isStorybookBuild) || snapshot === true
+    ? snapshotStorybookStatic(liveRoot)
+    : null
+  const root = frozen ? canonicalStaticRoot(frozen.dir) : liveRoot
+  const notFound = []
+  if (frozen) process.once('exit', () => frozen.dispose())
   const server = createServer((request, response) => {
     if (!['GET', 'HEAD'].includes(request.method || '')) {
       response.statusCode = 405
@@ -76,6 +94,7 @@ export async function startA11yStaticServer({ rootDirectory, defaultFile = 'inde
     }
     const file = resolveA11yStaticFile(root, request.url || '/', { defaultFile })
     if (!file) {
+      notFound.push((request.url || '/').split(/[?#]/, 1)[0])
       response.statusCode = 404
       response.end()
       return
@@ -121,6 +140,7 @@ export async function startA11yStaticServer({ rootDirectory, defaultFile = 'inde
     await new Promise((resolveClosed, rejectClosed) => {
       server.close(error => error ? rejectClosed(error) : resolveClosed())
     })
+    frozen?.dispose()
   }
   return Object.freeze({
     host: LOOPBACK_HOST,
@@ -130,5 +150,25 @@ export async function startA11yStaticServer({ rootDirectory, defaultFile = 'inde
     // `close` 是 Node server 的習慣名字,呼叫端很自然會伸手去拿;沒有它的時候
     // `server.close?.()` 會靜靜地什麼都不做(2026-09-18 實測四支閘都是這樣寫的)。給同一個實作,別再有人踩。
     close: stop,
+    /** 同源 404 帳本(路徑,不含 query);呼叫端失敗時印出 `[...new Set(server.notFound)]`。 */
+    notFound,
+    /** 本次服務的建置快照(沒有 build-info.json 的根目錄為 null)。 */
+    snapshot: frozen ? Object.freeze({ dir: frozen.dir, buildInfo: frozen.buildInfo }) : null,
+    /** 正在服務的根目錄(有快照 = 快照目錄;沒有 = 原根目錄)。讀清單一律從這裡讀,見 readServedStorybookIndex。 */
+    servedRoot: root,
   })
 }
+
+/**
+ * 讀**正在服務的那一份**建置的 Storybook index.json(2026-09-25,待辦總帳 C5)。
+ * story 清單必須跟頁面出自同一份建置:伺服器從快照供檔、清單卻讀活目錄的閘,在別人同時 build-storybook 時
+ * 會拿到「清單有、快照沒有」(或反過來)的 story,把「清單與頁面不是同一份」讀成「story 載入失敗」(假的儀器紅),
+ * 或把新增的 story 漏量。有快照 → 讀快照;沒有快照(非 Storybook 根目錄)→ 讀服務中的根目錄 —— 兩者都是「正在服務的那一份」。
+ * 缺檔 / 壞檔照常丟例外(呼叫端先用 requireStorybookBuild 擋「根本沒有建置」)。
+ * @param {{ servedRoot: string }} server startA11yStaticServer 的回傳
+ * @returns {any} 解析後的 index.json
+ */
+export function readServedStorybookIndex(server) {
+  if (!server || typeof server.servedRoot !== 'string') throw new TypeError('readServedStorybookIndex:要傳 startA11yStaticServer 的回傳(需有 servedRoot)')
+  return JSON.parse(fs.readFileSync(path.join(server.servedRoot, 'index.json'), 'utf8'))
+}

package/ds-canonical/fork/consumer/managed-files/ab072e7f2eca51f0e18a5e18c4b333260ee5d219a12cc6df5bb2d683f0b2734d.blob

@@ -2558,10 +2558,31 @@ try {
     'live upgraded transaction authority',
   )
   assertClosedGitLocalConfiguration(repoRoot)
+  // 2026-09-27(M37:「未暫存的 diff ≡ 這次改了什麼」只在沒有新檔的版本成立):重建端的 patch 是
+  // `git add -A` 之後的 --cached diff(新增檔以 new file 出現),而這裡原本拿「未暫存的 git diff」比
+  // bytes —— untracked 的新增受管檔案根本不會出現在未暫存 diff。這道比對 2026-07-28 上線後,
+  // beta.146 是第一個新增受管檔案的 release(scripts/lib/launch-browser / storybook-render-health /
+  // storybook-static-snapshot),WM run 36303338183 第 6 步因此少三個檔而被判「與重建不符」。
+  // 修法:live 端用**同一條**指令暫存(add -A -- .)、比同樣的 --cached diff,比完用 `git reset -- .`
+  // 把 index 還原(只動 index、不動工作樹),下游契約不變:index 乾淨、HEAD 不動、新檔留在工作樹
+  // 當 untracked 交給 PR 步驟的 `git add --all` 收。對照組:scripts/test-sync-all-transaction.mjs
+  // 「新增受管檔案」情境(修法前紅、修法後綠)。
+  const liveStage = runClosedGit(['add', '-A', '--', '.'], { cwd: repoRoot, output: 'ignore' })
+  if (liveStage.error || liveStage.signal !== null || liveStage.status !== 0) {
+    throw new Error('live upgrade result could not be staged for the protected-base comparison')
+  }
   const livePatch = runClosedGit(
-    ['diff', '--binary', '--full-index', '--no-ext-diff', '--no-textconv', '--no-renames'],
+    ['diff', '--cached', '--binary', '--full-index', '--no-ext-diff', '--no-textconv', '--no-renames'],
     { cwd: repoRoot, output: 'buffer', maxOutputBytes: 64 * 1024 * 1024 },
   )
+  const unstagedDiff = runClosedGit(
+    ['diff', '--name-only', '-z', '--no-ext-diff', '--no-textconv'],
+    { cwd: repoRoot, output: 'buffer' },
+  )
+  const liveUnstage = runClosedGit(['reset', '-q', '--', '.'], { cwd: repoRoot, output: 'ignore' })
+  if (liveUnstage.error || liveUnstage.signal !== null || liveUnstage.status !== 0) {
+    throw new Error('live upgrade index could not be restored after the protected-base comparison')
+  }
   const stagedDiff = runClosedGit(
     ['diff', '--cached', '--name-only', '-z', '--no-ext-diff', '--no-textconv'],
     { cwd: repoRoot, output: 'buffer' },
@@ -2574,6 +2595,11 @@ try {
     || livePatch.status !== 0
     || !Buffer.isBuffer(livePatch.stdout)
     || !livePatch.stdout.equals(reconstructedUpgrade.patchBytes)
+    || unstagedDiff.error
+    || unstagedDiff.signal !== null
+    || unstagedDiff.status !== 0
+    || !Buffer.isBuffer(unstagedDiff.stdout)
+    || unstagedDiff.stdout.length !== 0
     || stagedDiff.error
     || stagedDiff.signal !== null
     || stagedDiff.status !== 0

package/ds-canonical/fork/consumer/managed-files/e71c65f45c6af7ce12b6b3c0d8028f185da5b719e2050c9b2a6b243d41ae4878.blob

@@ -8,21 +8,30 @@
 //   4. fail = block PR
 //
 // 對齊 DS repo `npm run a11y:check`(scripts/audit-a11y.mjs)的 consumer-side equivalent。
+//
+// **「頁面真的渲染出來了」由共用的 openStory(document 模式)證明,不再用固定睡眠代替**(2026-09-25,M37)。
+// 錨例:app 的 bundle 404(dist/assets 缺檔)或 bundle 載入後什麼都沒掛上時,`#root` 是空的,axe 對一個
+// 空白頁當然找不到任何違規 —— 舊版(`networkidle` + 固定睡 1000ms、沒有任何渲染檢查)於是印出
+// 「✅ All apps pass WCAG 2 A + AA」、exit 0。要保證的性質是「axe 量的是 app 真正渲染出來的畫面」,
+// 量的卻是「網路靜了、又過了一秒」。現在:根節點沒有內容 / 關鍵資源(document/script/stylesheet)缺檔 /
+// 頁面例外 → 以 INSTRUMENT-FAIL(儀器失效:沒量到,不是產品裁決)的名義紅,並點名 app 與缺的檔。
+//
+// 交付面:這支腳本隨 fork 治理套件與 published template 交付給 consumer,所以它 import 的
+// `lib/launch-browser.mjs` 與其依賴 `lib/storybook-render-health.mjs` 一併登記進四個發送清單:
+// build-fork-governance.mjs 的 MANAGED_FILE_SOURCES / infra/governance/inventory/managed-repos.json /
+// published-template-mirror-policy.json / build-published-template-mirror.mjs 的 ALLOWLIST;另外
+// consumer-source-harness.mjs 的 TRUSTED_PRODUCT_CHECK_FILES(staged 的受保護檢查器)也必須是完整閉包。
+// fork 產生器、mirror 產生器、test-consumer-source-harness 各有相依閉包檢查,test-setup-governance 由本檔的
+// import 閉包推導清單並比對四個發送清單 —— 漏登記的相對 import 會當場擋下(2026-09-25 兩面實跑)。
+// 先前為了不擴張交付面而就地抄一份 SANDBOX_ARGS;現在 launch-browser 本來就要交付,單一住所改回直接 import(M17)。
 
 import { existsSync, lstatSync, readdirSync, realpathSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import { chromium } from 'playwright'
-
-// 受限沙箱起 Chromium 需要的兩個參數。**刻意就地寫,不 import 共用 helper**:
-// 這支腳本會被交付到 consumer repo,而 import `lib/launch-browser.mjs` 會讓那支也必須進
-// 四個交付／白名單清單(2026-09-21 實測:fork delivery / 檔案所有權 / published-template 鏡像 /
-// 鏡像路徑白名單),為兩個旗標擴張消費端交付面不值得 —— M17 的門檻是同值 **3+** 個消費者才抽共用,
-// 這裡是第 2 個。DS 內部閘的單一住所仍是 `scripts/lib/launch-browser.mjs` 的 `SANDBOX_ARGS`,
-// 兩邊若要改必須一起改(值相同:單行程 + 關沙箱)。
-const SANDBOX_ARGS = ['--single-process', '--no-sandbox']
 import { createRequire } from 'node:module'
 import { fileURLToPath } from 'node:url'
 import { resolveA11yStaticFile, startA11yStaticServer } from './lib/a11y-static-server.mjs'
+import { INSTRUMENT_FAIL_MARKER, SANDBOX_ARGS, StoryRenderInstrumentError, openStory } from './lib/launch-browser.mjs'
 
 const require = createRequire(import.meta.url)
 const axeBundle = require.resolve('axe-core/axe.min.js')
@@ -89,11 +98,32 @@ export async function startStaticServer({ distPath } = {}) {
   return startA11yStaticServer({ rootDirectory: distPath, defaultFile: 'index.html' })
 }
 
+/**
+ * 「這個 app 的頁面沒有渲染出來」的儀器失效(沒量到,不是產品裁決)。訊息以 INSTRUMENT-FAIL 開頭、點名 app,
+ * 附缺的檔(同源 404)與失敗原因 —— 絕不被讀成「0 個違規」。
+ */
+export class ConsumerAppRenderError extends Error {
+  constructor({ app, cause }) {
+    const detail = cause instanceof StoryRenderInstrumentError ? cause.detail : String(cause?.message ?? cause).split('\n')[0]
+    super(`${INSTRUMENT_FAIL_MARKER} app「${app}」的頁面沒有渲染出來 —— ${detail}。`
+      + '這是儀器失效(沒量到),不是產品裁決:axe 沒有對一個空白 / 半載入的頁面下結論,這次不能算通過', { cause })
+    this.name = 'ConsumerAppRenderError'
+    this.app = app
+    this.kind = cause instanceof StoryRenderInstrumentError ? cause.kind : 'unknown'
+    this.failedRequests = cause instanceof StoryRenderInstrumentError ? cause.failedRequests : []
+  }
+}
+
 export async function auditUrlWithAxe({
   url,
+  app = url,
+  notFound = null,
   browserType = chromium,
   axeBundlePath = axeBundle,
-  settleMs = 1000,
+  // 版面連續靜止幾個影格才開始量(影格不是毫秒:慢的機器只會等久一點,不會提早取樣)。0 = 不等靜止。
+  settleFrames = 10,
+  // 「根節點出現內容」的等待上限(不是「已渲染」的代理 —— 成功一律由根節點真的有內容決定)。
+  healthTimeoutMs = 15_000,
 } = {}) {
   let browser
   try {
@@ -102,9 +132,20 @@ export async function auditUrlWithAxe({
     // 差別就只在這組參數。同一份程式在不同環境給不同答案,本身就是量具問題。
     browser = await browserType.launch({ headless: true, args: [...SANDBOX_ARGS] })
     const page = await (await browser.newContext()).newPage()
-    const response = await page.goto(url, { waitUntil: 'networkidle' })
-    if (!response || !response.ok()) throw new Error(`owned app server returned ${response?.status() ?? 'no response'}`)
-    if (settleMs > 0) await page.waitForTimeout(settleMs)
+    // 共用的「真的渲染完成了」:document 模式 = 根節點(#root / main / body)有內容、document/script/stylesheet
+    // 沒有缺檔、沒有頁面例外、渲染期間發出的請求全部結束、版面靜止 —— 任何一項不成立就丟,不量。
+    try {
+      await openStory(page, url, {
+        storybook: false,
+        label: app,
+        notFound,
+        requestsSettled: true,
+        settleFrames,
+        healthTimeoutMs,
+      })
+    } catch (error) {
+      throw new ConsumerAppRenderError({ app, cause: error })
+    }
 
     // Exact lockfile dependency: no mutable CDN code enters the protected audit.
     await page.addScriptTag({ path: axeBundlePath })
@@ -153,6 +194,9 @@ export async function runConsumerA11yAudit({
       const violations = validateAxeViolations(await auditUrl({
         ...auditOptions,
         url: server.origin,
+        app,
+        // 伺服器端的同源 404 帳本:缺檔時點名是哪個檔(瀏覽器事件可能晚到,伺服器記的不會)
+        notFound: Array.isArray(server.notFound) ? server.notFound : null,
       }))
 
       if (violations.length > 0) {
@@ -165,7 +209,11 @@ export async function runConsumerA11yAudit({
         logger.log('  ✅ 0 WCAG violations')
       }
     } catch (error) {
-      logger.error(`  ❌ a11y audit infrastructure error:${error.message}`)
+      if (error instanceof ConsumerAppRenderError) {
+        logger.error(`  ❌ ${error.message}`)
+      } else {
+        logger.error(`  ❌ ${INSTRUMENT_FAIL_MARKER} a11y audit infrastructure error:${error.message}`)
+      }
       errors.push({ app, auditError: error.message })
     } finally {
       await server?.stop()
@@ -183,7 +231,7 @@ export async function runConsumerA11yAudit({
     const product = errors.filter((item) => !item.auditError)
     if (product.length > 0) logger.error(`❌ ${product.length} app(s) have a11y issues`)
     if (infrastructure.length > 0) {
-      logger.error(`❌ ${infrastructure.length} app(s) 量不到(儀器失效,不是產品有問題):`)
+      logger.error(`❌ ${INSTRUMENT_FAIL_MARKER}:${infrastructure.length} app(s) 量不到(儀器失效,不是產品有問題;沒量到不等於 0 個違規):`)
       for (const item of infrastructure) logger.error(`   - ${item.app}:${String(item.auditError).split('\n')[0]}`)
     }
     return 1