Sweep Flag Namespace

Sweep Flag Namespace

盡取二進制名空間中之每一旗候，分 gate 調用與 telemetry，與運行之已錄集校之，至未錄之餘歸零。probe-feature-flag-state 一旗一辨；此技則生其所據之錄，並驗其周備。

用時

• 旗探campaign行至中途，需可驗之停止條件，而非揣度旗已「足」否
• 二進制旗名空間甚大（候字數百），抽樣易漏要 gate
• 須將 DEFAULT-TRUE 與 DEFAULT-FALSE 分報——前者乃任名空間中信號最強之子集
• 多波文檔同行於一二進制，欲書之每波之周備度
• 疑前番campaign過早而止，欲以新掃確或駁之

入

• 必要：可讀之二進制或 bundle 文件
• 必要：名空間前綴（合成例：acme_*），辨識所究系統之旗
• 必要：運行之文檔集——campaign 已書之旗錄
• 可選：gate-reader 函數名（合成：gate(...)、flag(...)、isEnabled(...)），預備則速第二步
• 可選：telemetry/emit 函數名，同理而反向
• 可選：此二進制前版之掃出，以行差別析

法

Step 1: Harvest All Strings Matching the Namespace Prefix

取二進制中合於前綴之每一字面，不論調用點之角色。此步求覆，非求類。

BUNDLE=/path/to/cli/bundle.js
PREFIX=acme_                       # synthetic placeholder

# Pull every quoted string starting with the prefix
grep -oE "\"${PREFIX}[a-zA-Z0-9_]+\"" "$BUNDLE" | sort -u > /tmp/sweep-candidates.txt
wc -l /tmp/sweep-candidates.txt    # unique candidate count

# Per-string occurrence count (gives a first hint at gate-call density)
grep -oE "\"${PREFIX}[a-zA-Z0-9_]+\"" "$BUNDLE" | sort | uniq -c | sort -rn > /tmp/sweep-occurrences.txt
head /tmp/sweep-occurrences.txt

得：去重之候列，及按頻排之出現檔。次數甚高（≥10）者疑 gate 密；單次者多為 telemetry 事件名或靜態標籤。

敗則：若獨字數為零，前綴有誤（誤字、名空間界不合、調用約定異於所料）。若逾五千，前綴過寬——宜先收緊，否則簿冊不可治。

Step 2: Disambiguate Gate Calls from Telemetry from Static Labels

同字異役。於調用點辨其役，乃簿冊可施行之由。沿用 probe-feature-flag-state 第二步之辨法。

每候之每次出現，類之：

• gate-call——字為 gate-reader 函數之首參（gate("$FLAG", default)、flag("$FLAG", ...)、isEnabled("$FLAG") 等）
• telemetry-call——字為 emit/log/track 函數之首參
• env-var-check——字現於 process.env.X 查或同類
• static-label——字現於登錄表、map 或注釋中，無行為之繫

# Count gate-call occurrences for the candidate set, using a synthetic
# reader-name pattern. Adapt the regex to the actual reader names found.
GATE_PATTERN='(gate|flag|isEnabled)\(\s*"acme_'
grep -coE "$GATE_PATTERN" "$BUNDLE"

# Per-flag gate-call count
while read -r flag; do
  flag_no_quotes="${flag//\"/}"
  count=$(grep -coE "(gate|flag|isEnabled)\(\s*\"${flag_no_quotes}\"" "$BUNDLE")
  echo -e "${flag_no_quotes}\t${count}"
done < /tmp/sweep-candidates.txt > /tmp/sweep-gate-counts.tsv

得：每獨字一錄，形如 {flag, total_occurrences, gate_call_count, telemetry_count, static_label_count, env_var_count}。gate-call 計乃可施行之欄；餘為噪濾。

敗則：若每候之 gate-call 皆零，gate-reader 之式有誤。或二進制用此正則所漏之 reader 函數，或此名空間純為 telemetry（非旗名空間）。先以 decode-minified-js-gates 試數候，得實際 reader 名再重行此步。

Step 3: Build the Extraction Inventory

合每字之錄為一簿冊。CSV 或 JSONL——擇一而恆守，以利波次之差別。

# JSONL inventory
{
  while IFS=$'\t' read -r flag gate_count; do
    [ "$gate_count" -gt 0 ] || continue   # skip strings with no gate-call evidence
    total=$(grep -c "\"${flag}\"" "$BUNDLE")
    telem=$((total - gate_count))         # rough; refine if other call types matter
    printf '{"flag":"%s","total":%d,"gate_calls":%d,"telemetry":%d,"documented":false}\n' \
      "$flag" "$total" "$gate_count" "$telem"
  done < /tmp/sweep-gate-counts.tsv
} > /tmp/sweep-inventory.jsonl

wc -l /tmp/sweep-inventory.jsonl    # gate-bearing flag count

二導出之計要焉：

• total_unique：前綴所合之每字（gate 濾前）
• gate_calls：至少一次 gate-call 之子集——此為 campaign 之工作集

得：每獨之 gate-bearing 旗一錄之檔。gate 計常為 total_unique 之一分（多為 5–20%），二數宜顯異。

敗則：若簿冊空，或 gate_calls ≈ total_unique，第二步之 gate-vs-telemetry 辨產無意義之分。重審 reader-name 正則。

Step 4: Cross-Reference Against the Documented Set

周備之度賴於文檔集——campaign 於研究檔中已書之旗。校之而報其餘。

DOCUMENTED=/path/to/research/documented-flags.txt   # one flag name per line

# Extract gate-bearing flag names from the inventory
jq -r '.flag' /tmp/sweep-inventory.jsonl | sort -u > /tmp/sweep-extracted.txt

# Compute the documented and remaining sets
sort -u "$DOCUMENTED" > /tmp/sweep-documented.txt
comm -23 /tmp/sweep-extracted.txt /tmp/sweep-documented.txt > /tmp/sweep-remaining.txt

echo "Extracted (gate-bearing):  $(wc -l < /tmp/sweep-extracted.txt)"
echo "Documented:                $(wc -l < /tmp/sweep-documented.txt)"
echo "Remaining (undocumented):  $(wc -l < /tmp/sweep-remaining.txt)"

周備之度乃 remaining——歸零則文檔集已盡覆名空間中所有 gate-bearing 旗。

得：三計。campaign 初，remaining 宜為 extracted 之大分。每波削之至零。觀其軌跡以察停滯（一波反覆查已錄之旗）。

敗則：若 documented 逾 extracted，則文檔集含陳舊之條（此版已去之旗）。改用 comm -13 以顯廢名；下波檔中標為 REMOVED 而存之。

Step 5: Report the DEFAULT-TRUE Population

於 gate-bearing 旗集中，分二進制默認為 true 與默認為 false（或非 boolean）者。DEFAULT-TRUE 旗於所有用者皆開而無服務器側之蓋，乃最高信號之子集。

# Heuristic: gate-call shape `gate("flag_name", true)` indicates DEFAULT-TRUE
DEFAULT_TRUE_PATTERN='(gate|flag|isEnabled)\(\s*"acme_[a-zA-Z0-9_]+",\s*!?true\b'
grep -oE "$DEFAULT_TRUE_PATTERN" "$BUNDLE" | grep -oE '"acme_[a-zA-Z0-9_]+"' | sort -u > /tmp/sweep-default-true.txt

DEFAULT_FALSE_PATTERN='(gate|flag|isEnabled)\(\s*"acme_[a-zA-Z0-9_]+",\s*false\b'
grep -oE "$DEFAULT_FALSE_PATTERN" "$BUNDLE" | grep -oE '"acme_[a-zA-Z0-9_]+"' | sort -u > /tmp/sweep-default-false.txt

echo "DEFAULT-TRUE:  $(wc -l < /tmp/sweep-default-true.txt)"
echo "DEFAULT-FALSE: $(wc -l < /tmp/sweep-default-false.txt)"

旗之默認非 boolean 者（config 對象、TTL reader、async reader），以 decode-minified-js-gates 類其 reader 之變——其默認形異，宜別桶報之。

得：常分 10–20% DEFAULT-TRUE，80–90% DEFAULT-FALSE。極端者（≥90% TRUE 或 ≥90% FALSE）異常而宜察——或示某發布期之約（試驗皆默認開、分批推時皆默認關）。

敗則：若 DEFAULT-TRUE 與 DEFAULT-FALSE 之合不覆 gate-bearing 簿冊，餘者用非 boolean reader。以 decode-minified-js-gates 對其缺處類之。

Step 6: Confirm Completion

第四步 remaining = 0 時，行終掃：尋名空間相合之字之 gate-call 出現，而不在文檔集中者。此可獲第一步漏採之旗（如字串拼接藏其字面，逃簡易 grep）。

# Search for gate-call shapes containing the namespace prefix, not constrained
# to literal-string occurrences. Loosens Step 1's grep to catch dynamic forms.
DYNAMIC_PATTERN='(gate|flag|isEnabled)\(\s*[^"]*"acme_'
grep -nE "$DYNAMIC_PATTERN" "$BUNDLE" | head -50

# Alternative: ripgrep with multiline for split-string concatenation
rg -U "(gate|flag|isEnabled)\(\s*\"acme_(\\\\\"|[a-zA-Z0-9_])+\"" "$BUNDLE"

以 gate-call 之得校 /tmp/sweep-documented.txt。若有合於文檔集外之旗，回第一步以精提取（如治動態構造）。空則 campaign 周備矣。

得：終掃返空（campaign 周備）或返微餘（常 <5 旗，多為動態構造或別 reader）。

敗則：若第四步稱 remaining = 0 而終掃返大餘，則第一步系統性失採。察所漏之式（動態字、異引號、別 reader 函數），以更緊之正則自第一步重行之。

驗

• 第一步獨字數非零，且於預期之數量級內
• 第二步生有意義之 gate-vs-telemetry 分（gate-call 數為一分，非全有或全無）
• 第三步簿冊每 gate-bearing 旗一錄，CSV 或 JSONL
• 第四步報 total_unique、gate_calls、documented、remaining——其度於 campaign 終時歸零
• 第五步 DEFAULT-TRUE 與 DEFAULT-FALSE 別報之
• 第六步終掃返空乃稱 campaign 周備
• 一切例皆用合成之 placeholder（acme_*、gate(...) 等），無實旗名或 reader 名漏入檔
• sweep 之出可與前版之 sweep 相差（同形同欄）

陷

• 止於樣，非掃：campaign 至「已錄足旗」而止，未算 remaining，乃抽樣非掃。此技之要在可驗之終止條件
• 混 gate-bearing 與全提取：名空間中多字非 gate。以 total_unique 為 campaign 分母，膨其工而抑其表觀完成率。當以 gate_calls 為分母
• 跨版恃單一正則：gate-reader 函數名於主版間或變。掃新二進制始時宜重驗第二步之式
• 跳第六步：未行終動態掃即稱 remaining = 0 達周備，可漏字串拼接之旗。終掃廉而捕窘
• 漏實名：易誤將實旗名自簿冊貼入此技之例。acme_* placeholder 之律有由——法與所獲宜分
• 以陳舊文檔集行校：若文檔集建於舊二進制，已去之旗顯為「已錄」而非提取，真未錄者顯為餘。先以當前二進制刷新文檔集再校

參

• probe-feature-flag-state——一旗一類（此技簿冊之下游）
• decode-minified-js-gates——掃中需 reader-變類時用之
• monitor-binary-version-baselines——版間之長時跟蹤；每基線可重掃
• redact-for-public-disclosure——如何發掃法而不漏簿冊本身
• conduct-empirical-wire-capture——以實驗驗 sweep 所揭之旗