#!/usr/bin/env bash # portability_lint.sh — 셸 이식성 · 조용한 즉사 · 레포전제 픽스처 린트 (advisory) # # 왜 이게 있나 (weekly_audit_2026-08-16 🟧-3): # 이 레포의 재발 클래스 중 BSD/GNU · zsh/bash 이식성이 윈도우 16일에 ~12건인데 # **전용 계기가 없었고**, 잡힌 경로는 **전부 CI ubuntu 에서 사후**였다. 즉 저자 머신 # (macOS)에서는 구조적으로 초록이고, 로컬 초록 / CI 적색이 2026-08-16 하루에 2회 났다. # 이 린트는 그 사각을 보라고 지어졌다. # # 🟥 배선 상태를 헤더가 정직하게 말한다 (적대검증 2026-08-16 이 초판 헤더를 «거짓말»로 지목): # 초판 헤더는 "저자 머신에서 **커밋 전에** 한 번 본다" 고 적었는데, 실제 호출부는 # `selfcheck.sh` 의 `--self-test` **하나뿐**이다. 즉 **계기의 계기는 도는데 계기 자체는 안 돈다.** # 제자리는 pre-commit 의 staged `*.sh` 한정 advisory 인데 아직 안 붙였다(별도 커밋 · 인계됨). # 그때까지 본 실행은 **손으로 돌려야 한다**: `bash scripts/portability_lint.sh`. # 이 문장을 «커밋 전에 본다»로 되돌리려면 **먼저 pre-commit 에 붙여라.** 헤더가 배선보다 # 앞서 나가는 것이 이 커밋이 고치고 있는 바로 그 결함이다. # # 무엇이 아닌가: # · shellcheck 대체가 아니다. shellcheck 는 「성공하는 첫 명령」 패턴(P1)을 못 잡는다 — # 문법이 아니라 **플랫폼별 의미 차이**라서다. 둘은 상보적이다. # · 게이트가 아니다. **advisory** 다(exit 0 유지, `--strict` 로만 1). 이유는 # degrade_direction_scan 과 같다 — FP 를 감수하는 사전 선별기이고, 과차단은 # `--no-verify` 를 근육기억으로 만들어 같은 훅의 비가역 게이트까지 무장해제시킨다. # # Exit: 0 = 소견 없음 또는 advisory 모드 · 1 = --strict 에서 소견 有 · 10 = 하네스 오류 # Usage: bash scripts/portability_lint.sh [PATHS...] [--strict] [--quiet] # bash scripts/portability_lint.sh --self-test set -uo pipefail STRICT=0; QUIET=0; SELFTEST=0; TARGETS=() for a in "$@"; do case "$a" in --strict) STRICT=1 ;; --quiet) QUIET=1 ;; --self-test) SELFTEST=1 ;; -*) echo "unknown flag: $a" >&2; exit 10 ;; *) TARGETS+=("$a") ;; esac done # ── 규칙표 ──────────────────────────────────────────────────────────────────── # 각 규칙 = ID§정규식§한 줄 사유§처방 # # 🟥 구분자가 `|` 가 아니라 `§` 인 이유 — 이 린트의 self-test 가 초판에서 잡은 결함이다: # `|` 를 필드 구분자로 쓰면 정규식 안의 **교대(alternation) `|`** 에서 잘린다. # P1 이 `…=\$\((cat` 까지만 남아 known-positive 를 놓쳤다. 계기가 자기 문법에 걸린 것이고, # known-pair 가 없었으면 «소견 0건»이 그냥 초록으로 보였을 것이다. # 전부 **오늘 실물에서 나온 것**이거나 이 레포의 기록된 재발이다. 추측 규칙은 넣지 않는다 — # FP 가 늘면 이 린트가 무시되고, 무시되는 린트는 없는 린트보다 나쁘다(경고 하나가 0건보다 # 나쁠 수 있다: 0건은 «아무도 안 봤다»로 남지만 1건은 «봤고 이것만 나왔다»로 접힌다). RULES=( 'P1§^[[:space:]]*[A-Za-z_][A-Za-z0-9_]*=\$\((cat|sed|awk|grep|head|tail|python3?|node|jq)[^)]*\)§[후보] set -e 아래 명령치환 ASSIGNMENT — 파일 부재 시 그 줄에서 즉사. set -e 판별이 파일 스코프라 확정 아님§`|| true` 를 붙여라. 2>/dev/null 도 ${VAR:-기본값} 도 이걸 못 막는다(할당문 자체가 죽으므로). [ -f ] 가드도 present-but-unreadable arm 을 못 막는다 — 2026-08-16 4방 매트릭스가 반증' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 'P2§stat -f §`stat -f` 가 먼저 오면 GNU 에서 **성공한다** — 파일시스템 정보를 내고 폴백이 영영 안 돈다§stat -c %Y … 2>/dev/null || stat -f %m … 2>/dev/null || echo 0 순서로. GNU-first 가 맞다' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 'P3§sed -i[[:space:]]+[^-.]§`sed -i` 는 BSD 가 백업 접미사를 요구한다 — GNU 폼은 macOS 에서 다음 토큰을 파일명으로 먹는다§sed -i.bak 후 삭제, 또는 sed … > tmp && mv tmp f' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 'P4§grep -P§`grep -P` 는 BSD/macOS 기본 grep 에 없다§grep -E 로 낮추거나 perl -ne 로' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 'P5§\$\{PIPESTATUS§`${PIPESTATUS[…]}` 는 zsh 에서 빈 문자열이다 — 판정이 "" 로 접힌다§bash 전용이면 shebang 확인. 더 나은 형태: 파이프를 빼고 out=$(cmd); rc=$?' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 'P6§readlink -f§`readlink -f` 는 구형 BSD 에 없다§cd "$(dirname "$f")" && pwd -P 조합으로' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 'P7§date -d §`date -d` 는 GNU 전용 — BSD 는 date -v§epoch 로 계산하거나 두 폼을 || 로 잇되 GNU-first' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 'P9§"(package\.json|bin/)§테스트가 **레포 고유 파일**을 픽스처로 참조한다 — 이식된 자산에서 전량 FAIL 한다§자기 픽스처를 mktemp 로 만들어 써라. 2026-08-16 PMH 이식에서 selfcheck 35 FAIL 의 원인' # portability-noqa: 규칙표 데이터이지 실행 코드가 아니다 ) _hits=0 _emit() { [ "$QUIET" = 1 ] || printf '%s\n' "$*"; } lint_file() { local f="$1" rule id re why fix line n # 🟥 끊어진 심링크는 «소견 없음»이 아니라 **미측정**이다 (cross-family 2026-08-16). if [ -L "$f" ] && [ ! -e "$f" ]; then _emit " [UNMEASURED] $f — 끊어진 심링크. 읽지 못했다(초록이 아니다)." return 0 fi # 🟥 **로케일 fail-open — cross-family 가 양쪽 로케일을 실제로 돌려서 잡았다.** # UTF-8 로케일에서 대상 줄에 비-UTF8 바이트가 있으면 `grep -nE` 가 **매치하지 않고**, 그 # 실패가 삼켜져 최종 「소견 없음」으로 접힌다. 같은 입력이 `LC_ALL=C` 에서는 검출됐다. # 즉 «무매치»와 «해석 실패»가 구분되지 않는 fail-open 이고, 이 린트가 잡으라고 만들어진 # 클래스 그 자체다. 이 함수의 모든 매칭을 **바이트 기반으로 고정**한다. local LC_ALL=C LANG=C # P1 은 «set -e 계열이 켜져 있는 파일»에서만 의미가 있다. 아니면 FP 폭발. # ⚠️ 이 판별은 **파일 스코프**라 정확하지 않다 (cross-family 실측): 호출되지 않는 함수 안의 # `set -e` 로도 켜지고, 뒤따르는 `set +e` 로 꺼지지 않으며, 부모가 `set -e` 상태로 source 하는 # 파일은 **놓친다**. 그래서 P1 은 «확정 결함»이 아니라 **후보**다 — 출력 문구도 그렇게 낮춘다. local has_sete=0 grep -qE '^[[:space:]]*set -[a-z]*e' "$f" 2>/dev/null && has_sete=1 for rule in "${RULES[@]}"; do id="${rule%%§*}"; rest="${rule#*§}" re="${rest%%§*}"; rest="${rest#*§}" why="${rest%%§*}"; fix="${rest#*§}" case "$id" in P1) [ "$has_sete" = 1 ] || continue ;; esac while IFS= read -r line; do n="${line%%:*}"; body="${line#*:}" # noqa 이탈구: 알고 쓴 경우를 위한 문서화된 억제(전부 차단하면 우회를 훈련시킨다) # noqa 는 **사유가 있어야** 억제한다. 초판은 문자열 존재만 봐서 사유 없이도, 심지어 # 문자열 리터럴 안에서도 억제됐다 — advisory 인 지금은 경미하나 `--strict` 를 게이트로 # 승격하는 순간 무료 우회로가 된다. printf '%s' "$body" | grep -qE '#[[:space:]]*portability-noqa:[[:space:]]*[^[:space:]]' && continue # 주석 전용 줄은 소견이 아니다. 이 레포는 결함을 **주석으로 길게 설명하는** 관습이 있어서 # (그 설명이 문제 패턴을 그대로 인용한다) 이걸 안 빼면 FP 가 구조적으로 쌓인다. # 손검증 2026-08-16: 초판 50건 중 8건이 정확히 이 형태였다. case "$(printf '%s' "$body" | sed 's/^[[:space:]]*//')" in '#'*) continue ;; esac # P2 는 **순서**가 결함이지 `stat -f` 의 존재가 아니다. GNU-first(`stat -c … || stat -f …`)는 # 이 레포의 올바른 관용구이고, 초판은 그걸 12건 중 대다수로 지적했다 — 즉 규칙이 처방을 # 위반으로 렌더했다. 손검증 한 건이 이걸 잡았다(`_mtime()` 두 곳). case "$id" in P2) case "$body" in *'stat -c'*'stat -f'*) continue ;; esac ;; # P7 도 같은 형태다 — `date -d … || date -v…` 는 GNU-first 폴백이라 **올바른 관용구**다. # P2 에서 한 번 겪고도 새 규칙에 같은 오류를 심었다(손검증이 두 번째로 잡음). P7) case "$body" in *'date -d'*'date -v'*) continue ;; esac ;; esac # P1 의 처방이 이미 적용된 줄은 소견이 아니다. 이 이탈구가 없으면 린트가 **자기 처방을 # 따른 코드를 계속 지적**하고, 그러면 사람이 린트를 끄게 된다 — self-test 가 잡았다. # ⚠️ `2>/dev/null` 이나 `${VAR:-기본값}` 은 이탈 사유가 **아니다**: 둘 다 할당문의 # 즉사를 막지 못한다(2026-08-16 4방 매트릭스). 여기서 인정하는 건 `|| true` 뿐이다. case "$id" in P1) case "$body" in *'|| true'*|*'||true'*) continue ;; esac ;; esac _emit " [$id] $f:$n" _emit " $why" _emit " → $fix" _hits=$((_hits+1)) done < <(grep -nE "$re" "$f" 2>/dev/null) done # P8 — 가드 없는 glob 루프. 규칙표에 못 넣는다: **판정이 다음 줄에 있기 때문**이다. # 줄 단위 정규식은 `for f in *.sh; do` 만 보고 바로 아래의 `[ -e "$f" ] || continue` 를 # 볼 수 없어서, 초판 self-test 가 known-negative 에서 오탐을 냈다(hits=1, expected 0). # 계기의 시야가 한 줄이면 두 줄짜리 관용구를 영영 오판한다 — 그래서 여기만 창을 넓힌다. while IFS= read -r line; do n="${line%%:*}"; body="${line#*:}" printf '%s' "$body" | grep -qE '#[[:space:]]*portability-noqa:[[:space:]]*[^[:space:]]' && continue # 주석 전용 줄 제외 — RULES 루프엔 넣고 여기엔 안 넣어서, 이 블록이 **자기 자신을 설명하는 # 주석**을 소견으로 냈다(손검증이 잡음). 같은 이탈구는 두 루프에 **같이** 있어야 한다. case "$(printf '%s' "$body" | sed 's/^[[:space:]]*//')" in '#'*) continue ;; esac # 다음 2줄 안에 가드가 있으면 관용구를 지킨 것이다 if sed -n "$((n+1)),$((n+2))p" "$f" 2>/dev/null \ | grep -qE '\[ *-[efd] |\|\| *continue|nullglob'; then continue; fi # 파일 어딘가에 nullglob 이 켜져 있으면 전역적으로 해결된 것이다 grep -qE '^[[:space:]]*shopt -s [a-z ]*nullglob' "$f" 2>/dev/null && continue _emit " [P8] $f:$n" _emit " glob 이 하나도 안 맞으면 **리터럴 문자열 자체**가 루프에 들어온다" _emit " → 루프 첫 줄에 \`[ -e \"\$f\" ] || continue\`, 또는 shopt -s nullglob" _hits=$((_hits+1)) done < <(grep -nE 'for [A-Za-z_][A-Za-z0-9_]* in [^;]*\*[^;)]*; *do' "$f" 2>/dev/null) # ── [P10] `tr` 집합 안의 «범위로 읽힐 수 있는» 하이픈 ──────────────────────────── # 🟥 2026-08-30 실측, N=3 로 기계화. (번호: 초판이 이미 쓰인 P9 를 재사용해 충돌했다 — 실행해서 잡았다.) `tr -d '[:space:].·—-]'` 의 `—-]` 를 **범위**로 읽는 # 구현이 있다(GNU tr). 그러면 그 범위에 든 바이트가 전부 삭제되고 — 한글 코퍼스에서는 # 낱말 자체가 사라진다. macOS 는 리터럴로 읽어 통과하므로 **로컬만 초록이고 CI 에서 적색**이다. # 실제 피해: `defeater: 없음` 이 「1 낱말 공허」로 차단됐다(D6 레인, CI 전용 실패). # 판별: `tr` 인자 안에서 **양쪽에 문자가 있는 `-`**. 맨 앞/맨 뒤 하이픈은 리터럴이라 안전하고, # `a-z`·`0-9` 같은 **의도된 범위**는 오탐이므로 뺀다. while IFS= read -r line; do n="${line%%:*}"; body="${line#*:}" printf '%s' "$body" | grep -qE '#[[:space:]]*portability-noqa:[[:space:]]*[^[:space:]]' && continue case "$(printf '%s' "$body" | sed 's/^[[:space:]]*//')" in '#'*) continue ;; esac # 의도된 ASCII 범위만 쓰는 줄은 통과 printf '%s' "$body" | grep -qE "tr[^|]*'[^']*[a-zA-Z0-9]-[a-zA-Z0-9][^']*'" && continue _emit " [P10] $f:$n" _emit " \`tr\` 집합 안의 하이픈이 **범위**로 읽힐 수 있다(구현마다 다르다)." _emit " 비-ASCII 가 섞인 집합에서는 낱말이 통째로 지워진다 — 로컬만 초록이 된다." _emit " → 하이픈을 **맨 뒤**로 옮기거나, \`tr\` 대신 셸 파라미터 확장을 써라." _hits=$((_hits+1)) done < <(grep -nE "tr +-[a-z]* *'[^']*[^-'][-][^-'][^']*'" "$f" 2>/dev/null) # ── [P11] 비인용 heredoc 본문의 백틱 = 조용한 명령치환 ────────────────────────── # 🟥 2026-09-01, N=3 로 기계화(하루에 두 세션이 각각 겪었다). # `cat </dev/null || mktemp) || _p11py="" if [ -n "$_p11py" ]; then cat > "$_p11py" <<'P11PY' import re, sys try: lines = open(sys.argv[1], encoding='utf-8', errors='replace').read().split('\n') except OSError: sys.exit(0) # 진짜 heredoc 여는 줄은 구분자 «뒤»에 줄끝이나 리다이렉션이 온다. # 이 꼬리 조건이 없으면 `sed 's/.*<['\"])?(?P[A-Za-z_][A-Za-z0-9_]*)(?(q)(?P=q))\s*(?:[|>&;)]|$)") delim = None for i, l in enumerate(lines): if delim is None: m = open_re.search(l) if m and not m.group('q'): delim = m.group('w') continue if l.strip() == delim: delim = None else: # \U0001f7e5 이스케이프된 백틱(\\`)은 리터럴이라 명령치환이 아니다 — 첫 실사용에서 # 유일하게 남은 소견이 정확히 그 형태였다(의도된 셸 shim 문자열). # ⇒ 규칙 진술도 정정된다: 「비인용 heredoc 의 백틱은 언제나 명령치환」이 아니라 # **「이스케이프되지 않은 백틱은 언제나 명령치환」**이다. stripped = re.sub(r'\\.', '', l) # 이스케이프 시퀀스(백슬래시+1문자)를 먼저 지운다 if '\x60' in stripped: print(i + 1) P11PY _p11out=$(python3 "$_p11py" "$f" 2>&1); _p11rc=$? rm -f "$_p11py" if [ "$_p11rc" != 0 ]; then _emit " [UNMEASURED] $f — P11 검사기가 죽었다(rc=$_p11rc). 초록이 아니다." _emit " $(printf '%s' "$_p11out" | head -1)" else for n in $_p11out; do body=$(sed -n "${n}p" "$f" 2>/dev/null) printf '%s' "$body" | grep -qE '#[[:space:]]*portability-noqa:[[:space:]]*[^[:space:]]' && continue _emit " [P11] $f:$n" _emit " 비인용 heredoc 본문의 백틱은 **명령치환**이다 — 없으면 그 자리가 삭제된다." _emit " → 값을 미리 계산해 변수에 담고 본문엔 변수만 넣어라." _hits=$((_hits+1)) done fi else _emit " [UNMEASURED] $f — P11 임시파일 생성 실패. 초록이 아니다." fi } # ── self-test (known-pair) ──────────────────────────────────────────────────── # 이 린트가 «무엇을 못 잡는지»까지 고정한다. 컨트롤이 없으면 초록의 이유를 모른다. if [ "$SELFTEST" = 1 ]; then t=$(mktemp -d) || { echo "harness-error: mktemp"; exit 10; } trap 'rm -rf "$t"' EXIT pass=0; failn=0 _ck(){ # _ck