docs(topic13): peephole optimizer docs and tests

.github/workflows/ci.yml

@@ -73,20 +73,31 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python3.12 -m pip install --upgrade pip
-          python3.12 -m pip install -e ".[all]"
-          python3.12 -m pip install "pytest>=7,<10"
+          set -euo pipefail
+          if python -c 'import sys; sys.exit(0 if sys.version_info[:2] == (3, 12) else 1)'; then
+            PY=python
+          elif command -v python3.12 >/dev/null 2>&1; then
+            PY=python3.12
+          else
+            echo "Python 3.12 not found" >&2
+            exit 1
+          fi
+          echo "PY=$PY" >> "$GITHUB_ENV"
+          echo "Using python: $($PY -c 'import sys; print(sys.executable, sys.version)')"
+          $PY -m pip install --upgrade pip setuptools wheel
+          $PY -m pip install -e ".[all]"
+          $PY -m pip install "pytest>=7,<10"
 
       - name: Run all topic tests
         run: |
           mkdir -p benchmark_reports
-          python3.12 -m pytest tests/ -v --tb=short \
+          $PY -m pytest tests/ -v --tb=short \
             --junit-xml=benchmark_reports/test_results.xml \
             --ignore=tests/test_simulator.py
 
       - name: Run assembly-beautifier regressions
         run: |
-          python3.12 -m pytest \
+          $PY -m pytest \
             tests/test_parser_for_beautifier.py \
             tests/test_asm_beautifier_comments.py \
             tests/test_asm_beautifier_formatting.py \
@@ -96,20 +107,38 @@ jobs:
 
       - name: Run constant-merge regressions
         run: |
-          python3.12 -m pytest \
+          $PY -m pytest \
             tests/test_const_merge.py \
             tests/test_backend.py::TestConstMergeIntegration \
             tests/test_simulator.py::TestStubProfiledMachine \
             -v --tb=short
 
       - name: Run PR #37 register-allocation regressions
         run: |
-          python3.12 -m pytest tests/test_pr37_regression.py -v --tb=short
+          $PY -m pytest tests/test_pr37_regression.py -v --tb=short
+
+      - name: Run topic13 peephole regressions
+        run: |
+          $PY -m pytest tests/test_asm_peephole*.py -v --tb=short
+
+      - name: Run topic13 peephole CLI smoke
+        run: |
+          $PY -m scratchv.backend.asm_peephole --list-rules | tee /tmp/peephole_rules.txt
+          grep -q "addi+addi fusion" /tmp/peephole_rules.txt
+          if grep -q "redundant mv pair elimination" /tmp/peephole_rules.txt; then
+            echo "unsound rule must not be listed" >&2
+            exit 1
+          fi
+          $PY -m scratchv.backend.asm_peephole \
+            tests/fixtures/asm_peephole/input_addi_fusion.s \
+            -o /tmp/peephole_out.s --report --json | tee /tmp/peephole_report.json
+          $PY -c "import json; d=json.load(open('/tmp/peephole_report.json')); assert d['instructions_saved']>=1"
+          grep -q "8" /tmp/peephole_out.s
 
       - name: Generate test visualization page
         if: github.ref == 'refs/heads/main'
         run: |
-          python3.12 scratchv/ci/test_page.py \
+          $PY scratchv/ci/test_page.py \
             --junit benchmark_reports/test_results.xml \
             -o benchmark_reports/tests.html
 
@@ -183,27 +212,46 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python3.12 -m pip install --upgrade pip
-          python3.12 -m pip install -e ".[all]"
-          python3.12 -m pip install markdown "pytest>=7,<10"
+          set -euo pipefail
+          if python -c 'import sys; sys.exit(0 if sys.version_info[:2] == (3, 12) else 1)'; then
+            PY=python
+          elif command -v python3.12 >/dev/null 2>&1; then
+            PY=python3.12
+          else
+            echo "Python 3.12 not found" >&2
+            exit 1
+          fi
+          echo "PY=$PY" >> "$GITHUB_ENV"
+          echo "Using python: $($PY -c 'import sys; print(sys.executable, sys.version)')"
+          $PY -m pip install --upgrade pip setuptools wheel
+          $PY -m pip install -e ".[all]"
+          $PY -m pip install markdown "pytest>=7,<10"
 
       # ── 3.1 ONNX 模型管线基准测试 ──────────────────────────────────────
       - name: ONNX model pipeline benchmarks
-        run: python3.12 -m pytest benchmarks/test_benchmark.py -v --tb=short
+        run: $PY -m pytest benchmarks/test_benchmark.py -v --tb=short
 
       # ── 3.1.1 课题14：固定 case + 真实 TinyFive A/B 报告 ─────────────
       - name: Topic 14 constant-merge case report
         run: |
-          python3.12 benchmarks/run_const_merge_case.py \
+          $PY benchmarks/run_const_merge_case.py \
             benchmarks/cases/const_merge_feature.asm \
             --json benchmark_reports/const_merge_report.json \
             --markdown benchmark_reports/const_merge_report.md
 
+      # ── 3.1.2 课题13：窥孔前后对比报告 ─────────────────────────────
+      - name: Topic 13 peephole compare report
+        run: |
+          mkdir -p benchmark_reports
+          $PY benchmarks/compare_peephole.py \
+            --json benchmark_reports/peephole_compare.json \
+            --markdown benchmark_reports/peephole_compare.md
+
       # ── 3.2 DSL 用例编译 + 模拟基准 ────────────────────────────────────
       - name: DSL case compilation benchmarks
         run: |
           mkdir -p benchmark_reports
-          python3.12 benchmarks/bench_runner.py benchmarks/cases \
+          $PY benchmarks/bench_runner.py benchmarks/cases \
             --output-json benchmark_reports/dsl_bench.json \
             --output-html benchmark_reports/dsl_bench.html \
             --output-md benchmark_reports/dsl_bench.md
@@ -215,17 +263,17 @@ jobs:
           MODEL=models/graph/cnn.onnx
           if [ ! -f "$MODEL" ]; then
             echo "::warning::cnn.onnx not found, generating minimal CNN test model"
-            python3.12 scripts/gen_minimal_cnn.py 2>&1
+            $PY scripts/gen_minimal_cnn.py 2>&1
           fi
-          python3.12 scratchv/standalone/onnx_to_riscv_standalone.py \
+          $PY scratchv/standalone/onnx_to_riscv_standalone.py \
             "$MODEL" -o /tmp/cnn_riscv.bin \
             --asm benchmark_reports/cnn_scratchv.s \
             --estimate --report --const-merge
 
       # ── 3.3.1 汇编美化器：真实 CNN 输出 + Actions Summary ───────────
       - name: CNN assembly beautifier benchmark
         run: |
-          python3.12 -m benchmarks.bench_asm_beautifier \
+          $PY -m benchmarks.bench_asm_beautifier \
             --input benchmark_reports/cnn_scratchv.s \
             --output-asm benchmark_reports/cnn_pretty.s \
             --markdown benchmark_reports/asm_beautifier_summary.md \
@@ -238,16 +286,16 @@ jobs:
           mkdir -p benchmark_reports
           # Generate ScratchV assembly if not already present
           if [ ! -f benchmark_reports/cnn_scratchv.s ] && [ -f models/graph/cnn.onnx ]; then
-            python3.12 scratchv/standalone/onnx_to_riscv_standalone.py \
+            $PY scratchv/standalone/onnx_to_riscv_standalone.py \
               models/graph/cnn.onnx -o /tmp/cnn_riscv.bin \
               --asm benchmark_reports/cnn_scratchv.s --estimate \
               --const-merge 2>&1 | tail -3
           fi
-          python3.12 scratchv/standalone/llvm_cache_compare.py \
+          $PY scratchv/standalone/llvm_cache_compare.py \
             --json-output benchmark_reports/llvm_vs_scratchv.json \
             --markdown benchmark_reports/llvm_vs_scratchv.md \
             || echo "WARNING: llvm_cache_compare failed"
-          python3.12 scratchv/standalone/tinyfive_compare.py \
+          $PY scratchv/standalone/tinyfive_compare.py \
             --json benchmark_reports/tinyfive_compare.json \
             --markdown benchmark_reports/tinyfive_compare.md \
             --scratchv-asm benchmark_reports/cnn_scratchv.s \
@@ -256,19 +304,19 @@ jobs:
       # ── 3.5 ONNX 模型拆分为单算子 ────────────────────────────────────
       - name: Split CNN model into single operators
         run: |
-          python3.12 scripts/split_cnn_to_single_ops.py \
+          $PY scripts/split_cnn_to_single_ops.py \
             || echo "WARNING: split_cnn_to_single_ops failed"
 
       # ── 3.6 单算子 benchmark ────────────────────────────────────────
       - name: Single-operator benchmarks
         run: |
-          python3.12 scripts/bench_single_ops.py \
+          $PY scripts/bench_single_ops.py \
             || echo "WARNING: bench_single_ops failed"
 
       # ── 3.7 生成仪表盘 HTML (版本vsLLVM + 指令分类 + 算子对比) ─────
       - name: Generate dashboard
         run: |
-          python3.12 scratchv/ci/dashboard.py \
+          $PY scratchv/ci/dashboard.py \
             --llvm-json benchmark_reports/llvm_vs_scratchv.json \
             --history-json benchmark_reports/optimization_history.json \
             -o benchmark_reports/dashboard.html \
@@ -277,7 +325,7 @@ jobs:
       # ── 3.8 寄存器分配 benchmark(线性扫描:simple/dense/cnn + LLVM对比) ──
       - name: Register allocation benchmarks
         run: |
-          python3.12 -m benchmarks.test_regalloc.bench_regalloc_linear \
+          $PY -m benchmarks.test_regalloc.bench_regalloc_linear \
             --repeats 30 \
             --output-json benchmark_reports/regalloc_bench.json \
             --output-html benchmark_reports/regalloc_bench.html \
@@ -301,20 +349,20 @@ jobs:
       - name: Build docs HTML course site
         if: github.ref == 'refs/heads/main'
         run: |
-          python3.12 -m pip install markdown
-          python3.12 scripts/build_docs_html.py --output-dir benchmark_reports/docs
+          $PY -m pip install markdown
+          $PY scripts/build_docs_html.py --output-dir benchmark_reports/docs
           echo "Docs site built: benchmark_reports/docs/index.html"
 
       # ── 优化历史页面 ──────────────────────────────────────────────────
       - name: Generate optimization history page
         if: github.ref == 'refs/heads/main'
-        run: python3.12 scratchv/ci/history_page.py -o benchmark_reports/history.html
+        run: $PY scratchv/ci/history_page.py -o benchmark_reports/history.html
 
       # ── 测试可视化页面 ────────────────────────────────────────────────
       - name: Generate test visualization page
         if: github.ref == 'refs/heads/main'
         run: |
-          python3.12 scratchv/ci/test_page.py \
+          $PY scratchv/ci/test_page.py \
             --junit benchmark_reports/test_results.xml \
             -o benchmark_reports/tests.html
 
@@ -342,6 +390,11 @@ jobs:
             cat benchmark_reports/const_merge_report.md >> $GITHUB_STEP_SUMMARY
           fi
           echo "" >> $GITHUB_STEP_SUMMARY
+          if [ -f benchmark_reports/peephole_compare.md ]; then
+            echo "### Topic 13 Peephole Compare" >> $GITHUB_STEP_SUMMARY
+            head -40 benchmark_reports/peephole_compare.md >> $GITHUB_STEP_SUMMARY
+          fi
+          echo "" >> $GITHUB_STEP_SUMMARY
           if [ -f benchmark_reports/github_summary.md ]; then
             cat benchmark_reports/github_summary.md >> $GITHUB_STEP_SUMMARY
           fi

Makefile

@@ -1,7 +1,7 @@
 # ScratchV developer makefile
 .POSIX:
 
-.PHONY: quick-start install test bench bench-cnn clean lint
+.PHONY: quick-start install test test-peephole ci-peephole bench bench-cnn clean lint
 
 # ── Beginner quick-start ─────────────────────────────────────────────────────
 
@@ -40,6 +40,22 @@ install:
 test:
 	python3 -m pytest tests/ -v --tb=short
 
+# ── Topic 13 窥孔优化器（本地 / CI 对齐） ─────────────────────────────────
+
+test-peephole:
+	python3 -m pytest tests/test_asm_peephole*.py -v --tb=short
+	python3 -m scratchv.backend.asm_peephole --list-rules
+	python3 -m scratchv.backend.asm_peephole \
+		tests/fixtures/asm_peephole/input_addi_fusion.s \
+		-o /tmp/peephole_out.s --report --json
+
+ci-peephole: test-peephole
+	@mkdir -p benchmark_reports
+	python3 benchmarks/compare_peephole.py \
+		--json benchmark_reports/peephole_compare.json \
+		--markdown benchmark_reports/peephole_compare.md
+	@echo "Peephole CI checks done."
+
 # ── 模型性能基准 ──────────────────────────────────────────────────────────
 
 bench: