diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index a5e7146..086aa1b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -562,6 +562,11 @@ jobs: - name: Check input-form documentation coverage run: bash scripts/check-doc-coverage.sh + # Code->docs gate: every user-facing env var in scan-sbom.sh --help must be + # documented in the reference pages (the reverse of check-docs-drift.sh). + - name: Check environment-variable documentation coverage + run: bash scripts/check-doc-env-coverage.sh + # Deterministic internal-link gate for the getting-started pages. - name: Check onboarding internal links run: bash scripts/check-doc-links.sh diff --git a/docs/reference/cli.ko.md b/docs/reference/cli.ko.md index 97e81c9..7886a22 100644 --- a/docs/reference/cli.ko.md +++ b/docs/reference/cli.ko.md @@ -54,6 +54,7 @@ BomLens의 전체 옵션과 분석 모드, CI/CD 통합 방법, 트러블슈팅 |----------|--------|------| | `SBOM_SCANNER_IMAGE` | `ghcr.io/sktelecom/bomlens:latest` | 스캐너 이미지를 다른 태그로 재정의 | | `SBOM_FIRMWARE_IMAGE` | `ghcr.io/sktelecom/bomlens-firmware:latest` | 펌웨어 분석용 이미지 지정 | +| `SBOM_AIBOM_IMAGE` | `ghcr.io/sktelecom/bomlens-aibom:latest` | AI 모델(ML-BOM) 생성용 이미지 지정 | | `SBOM_OUTPUT_FLAT` | — | `1`로 두면 실행별 하위 폴더 없이 산출물을 베이스에 평면으로 저장(격리 이전 배치, 옛 경로를 기대하는 CI용) | | `SBOM_OUTPUT_DIR` | `~/sbom-output` | 데스크톱 앱과 웹 UI의 산출물 베이스(CLI는 대신 `--output-dir` 사용). 스캔마다 그 아래 `{Project}_{Version}/` 하위 폴더에 저장 | | `SBOM_UI_MOUNT_DIR` | — | CLI 인자를 받지 않는 Windows 실행 파일 `sbom-ui.bat`용: 웹 UI의 디렉터리 경로 입력에 읽기 전용 대상으로 추가할 폴더 하나(`--ui --mount`의 더블클릭 대응) | diff --git a/docs/reference/cli.md b/docs/reference/cli.md index ef5738d..b66dda2 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -54,6 +54,7 @@ Environment variables adjust the behavior. |----------|---------|-------------| | `SBOM_SCANNER_IMAGE` | `ghcr.io/sktelecom/bomlens:latest` | Override the scanner image | | `SBOM_FIRMWARE_IMAGE` | `ghcr.io/sktelecom/bomlens-firmware:latest` | Image used for firmware analysis | +| `SBOM_AIBOM_IMAGE` | `ghcr.io/sktelecom/bomlens-aibom:latest` | Image used for AI model (ML-BOM) generation | | `SBOM_OUTPUT_FLAT` | — | Set to `1` to write artifacts flat in the output base, with no per-run subfolder (the pre-isolation layout, for CI that expects the old paths) | | `SBOM_OUTPUT_DIR` | `~/sbom-output` | Output base for the desktop app and web UI (the CLI uses `--output-dir` instead). Each scan still lands in a `{Project}_{Version}/` subfolder under it | | `SBOM_UI_MOUNT_DIR` | — | For the Windows launcher `sbom-ui.bat`, which takes no CLI arguments: one extra folder to expose to the web UI as a read-only Directory path target (the double-click counterpart of `--ui --mount`) | diff --git a/scripts/check-doc-env-coverage.sh b/scripts/check-doc-env-coverage.sh new file mode 100755 index 0000000..ae91740 --- /dev/null +++ b/scripts/check-doc-env-coverage.sh @@ -0,0 +1,66 @@ +#!/bin/bash +# Copyright 2026 SK Telecom Co., Ltd. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# See the License for the specific language governing permissions and +# limitations under the License. +# +# check-doc-env-coverage.sh — guard against adding a user-facing environment +# variable to the tool without documenting it. +# +# The authoritative list of user-facing env vars is the "Environment:" block of +# scripts/scan-sbom.sh --help. Every name there must appear in one of the user +# reference pages (docs/reference/cli.md or docs/reference/docker-image.md). +# Adding a var to the help text but forgetting the docs therefore fails CI. +# +# This is the code->docs direction. check-docs-drift.sh checks the reverse +# (docs referencing an env var that no longer exists in code), so the two gates +# together keep the environment documentation and the tool in sync both ways. + +set -euo pipefail + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +HELP_SRC="$ROOT/scripts/scan-sbom.sh" +DOCS=("$ROOT/docs/reference/cli.md" "$ROOT/docs/reference/docker-image.md") +bt='`' +fail=0 + +# 1) Pull the user-facing env names from the "Environment:" help block. Entries +# start at a two-space indent (VAR then its description); continuation lines +# are indented further and are skipped. +envs="$(awk ' + /^Environment:/ { inblock=1; next } + /^[A-Za-z]/ { inblock=0 } + inblock && /^ [A-Z][A-Z0-9_]+/ { print $1 } +' "$HELP_SRC")" + +[ -n "$envs" ] || { echo "ERROR: could not read the Environment block from $HELP_SRC"; exit 2; } + +# 2) Each must be documented (as `VAR`) in at least one reference page. +while IFS= read -r v; do + [ -z "$v" ] && continue + found=0 + for d in "${DOCS[@]}"; do + [ -f "$d" ] || continue + if grep -qF "${bt}${v}${bt}" "$d"; then found=1; break; fi + done + if [ "$found" -eq 0 ]; then + echo "FAIL: env var '$v' is advertised in scan-sbom.sh --help but is documented in neither" + echo " docs/reference/cli.md nor docs/reference/docker-image.md." + echo " Add a row/mention for ${bt}${v}${bt} to one of them (and its .ko.md mirror)." + fail=1 + fi +done <