pyplcopen 0.20.0__tar.gz

pyplcopen-0.20.0/.clang-tidy

@@ -0,0 +1,22 @@
+Checks: >
+  -*,
+  bugprone-*,
+  clang-analyzer-*,
+  performance-*,
+  readability-*,
+  -bugprone-easily-swappable-parameters,
+  -performance-enum-size,
+  -readability-magic-numbers,
+  -readability-identifier-length,
+  -readability-function-cognitive-complexity,
+  -readability-braces-around-statements
+
+WarningsAsErrors: >
+  bugprone-*,
+  clang-analyzer-*,
+  performance-*,
+  -bugprone-easily-swappable-parameters,
+  -performance-enum-size
+
+HeaderFilterRegex: 'core/.*\.h$'
+FormatStyle: none

pyplcopen-0.20.0/.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,63 @@
+name: AI executable task
+description: A bounded task with acceptance criteria and verification evidence.
+title: "[Task] "
+labels:
+  - task
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: What should be true when this task is complete?
+      placeholder: "Example: Add a regression test for KB-001 and make it pass."
+    validations:
+      required: true
+
+  - type: dropdown
+    id: risk
+    attributes:
+      label: Risk level
+      description: Use the project T0-T3 change policy from CLAUDE.md.
+      options:
+        - T0 - docs, comments, demos, tests, formatting, CI scripts
+        - T1 - non-RT implementation, tooling, pyplcopen, build config
+        - T2 - RT path, OTG/planner algorithms, state semantics, public API
+        - T3 - license, provenance, release tags, external safety claims
+    validations:
+      required: true
+
+  - type: input
+    id: scope
+    attributes:
+      label: Affected layers or KB ids
+      description: Name the core layer(s), compliance rows, or known-boundary ids.
+      placeholder: "Example: L0 rt, KB-001, Part 1 MC_MoveAbsolute"
+    validations:
+      required: true
+
+  - type: textarea
+    id: done
+    attributes:
+      label: Definition of done
+      description: List the observable acceptance criteria.
+      placeholder: "- Failing test added first\n- Implementation passes the test\n- Docs updated if public behavior changes"
+    validations:
+      required: true
+
+  - type: textarea
+    id: verification
+    attributes:
+      label: Verification commands
+      description: Commands that must pass before the task is done.
+      placeholder: ".\\build.ps1 -Test"
+    validations:
+      required: true
+
+  - type: textarea
+    id: docs
+    attributes:
+      label: Documentation impact
+      description: State which docs change, or why no docs change is needed.
+      placeholder: "Example: Update doc/compliance/...; no docs change for test-only task."
+    validations:
+      required: true

pyplcopen-0.20.0/.github/pull_request_template.md

@@ -0,0 +1,17 @@
+# Summary
+
+-
+
+# Scope
+
+- Affected layers / KB ids:
+- Semantic matrix: approved / not touched
+- Declared change (replay baseline re-recorded): yes / no
+
+# Evidence
+
+- Gates (build / tests / replay / RT-safety / benchmarks):
+
+# AI statement
+
+- AI-assisted: yes / no

pyplcopen-0.20.0/.github/workflows/core-nightly.yml

@@ -0,0 +1,173 @@
+name: Core Nightly
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '23 2 * * *'
+
+jobs:
+  fuzz-smoke-suite:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Configure CMake
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+
+      - name: Build fuzz smoke suite
+        run: >
+          cmake --build build --parallel --target
+          plcopen_core_otg_fuzz
+          plcopen_core_st_fuzz
+          plcopen_core_feetech_fuzz
+          plcopen_core_part4_p4b1_fuzz
+          plcopen_core_part4_p4b2_fuzz
+          plcopen_core_part4_p4b3_fuzz
+          plcopen_core_part4_c3_fuzz
+
+      - name: Run fuzz smoke suite
+        run: ctest --test-dir build --output-on-failure -L fuzz
+
+  deterministic-otg-fuzz:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Configure CMake
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+
+      - name: Build deterministic OTG fuzz
+        run: cmake --build build --target plcopen_core_otg_fuzz --parallel
+
+      - name: Run deterministic OTG fuzz
+        run: ./build/core/plcopen_core_otg_fuzz --iterations 1000000
+
+  a2-allocation-soak:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Configure CMake
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+
+      - name: Build allocation guard
+        run: cmake --build build --target plcopen_core_a2_alloc_guard --parallel
+
+      - name: Run allocation-guard soak (A2)
+        run: ./build/core/plcopen_core_a2_alloc_guard --cycles 50000000
+
+  time-optimal-otg-fuzz:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Configure CMake
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+
+      - name: Build time-optimal OTG fuzz
+        run: cmake --build build --target plcopen_core_otg_time_optimal_tests --parallel
+
+      - name: Run time-optimal OTG fuzz
+        run: ./build/core/plcopen_core_otg_time_optimal_tests --iterations 1000000
+
+  executor-tsan:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Configure CMake (TSan)
+        run: >
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
+          -DCMAKE_CXX_FLAGS="-fsanitize=thread -g"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
+
+      - name: Build dual-domain executor demo
+        run: cmake --build build --target plcopen_core_rt_executor_demo --parallel
+
+      - name: Build ST L3 process-image concurrency tests
+        run: cmake --build build --target plcopen_core_st_l3_tests --parallel
+
+      - name: Build ST L5 task and motion isolation tests
+        run: cmake --build build --target plcopen_core_st_l5_tests --parallel
+
+      # setarch -R: TSan is incompatible with the high ASLR entropy of
+      # ubuntu-24.04 kernels (unexpected memory mapping otherwise).
+      - name: Run executor under ThreadSanitizer (ADR-0007)
+        run: >
+          setarch $(uname -m) -R
+          ./build/core/plcopen_core_rt_executor_demo
+          --cycles 20000 --period-ns 250000 --trace /tmp/tsan_trace.bin
+
+      - name: Run ST L3 process image under ThreadSanitizer
+        run: >
+          setarch $(uname -m) -R
+          ./build/core/plcopen_core_st_l3_tests
+
+      - name: Run ST L5 task and motion isolation under ThreadSanitizer
+        run: >
+          setarch $(uname -m) -R
+          ./build/core/plcopen_core_st_l5_tests
+
+  st-frontend-fuzz-sanitized:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Configure CMake (ASan/UBSan)
+        run: >
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
+          -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined
+          -fno-sanitize-recover=all"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
+
+      - name: Build ST fuzz
+        run: cmake --build build --target plcopen_core_st_fuzz --parallel
+
+      - name: Run ST front-end fuzz (metric 5.2)
+        run: ./build/core/plcopen_core_st_fuzz --iterations 100000
+
+      - name: Run ST multi-POU fuzz (L2b-A07)
+        run: ./build/core/plcopen_core_st_fuzz --iterations 100000 --l2b
+
+      - name: Run ST configuration graph fuzz (L5-A08)
+        run: ./build/core/plcopen_core_st_fuzz --iterations 100000 --l5
+
+      - name: Run ST textual SFC fuzz (L6-A08)
+        run: ./build/core/plcopen_core_st_fuzz --iterations 100000 --l6
+
+      - name: Run ST debugger state-machine fuzz (L7-A08)
+        run: ./build/core/plcopen_core_st_fuzz --iterations 100000 --l7
+
+  st-l7-debug-tsan:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Configure CMake (TSan)
+        run: >
+          cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo
+          -DCMAKE_CXX_FLAGS="-fsanitize=thread -g"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=thread"
+
+      - name: Build ST L7 debugger concurrency tests
+        run: cmake --build build --target plcopen_core_st_l7_tests --parallel
+
+      # setarch -R avoids the high-ASLR mapping conflict on ubuntu-24.04.
+      - name: Run ST L7 debugger under ThreadSanitizer
+        run: >
+          setarch $(uname -m) -R
+          ./build/core/plcopen_core_st_l7_tests

pyplcopen-0.20.0/.github/workflows/coverage.yml

@@ -0,0 +1,29 @@
+name: Coverage Gate
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '47 3 * * 1'
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install gcovr
+        run: python -m pip install gcovr==8.6
+
+      - name: Run coverage gate (E4)
+        run: cmake -P cmake/coverage_gate.cmake
+
+      - name: Upload coverage summaries
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: linux-coverage-summaries
+          path: out/coverage-linux
+          retention-days: 30

pyplcopen-0.20.0/.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.x'
+
+      - name: Install mkdocs
+        run: pip install mkdocs mkdocs-material
+
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

pyplcopen-0.20.0/.github/workflows/linux-ci.yml

@@ -0,0 +1,148 @@
+name: Linux CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        compiler: [gcc, clang]
+        include:
+          - compiler: gcc
+            cc: gcc
+            cxx: g++
+          - compiler: clang
+            cc: clang
+            cxx: clang++
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Run RT-safety static scan
+        run: cmake -P cmake/rt_safety_scan.cmake
+
+      - name: Verify generated compliance matrix
+        run: |
+          cmake -P cmake/generate_part1_part2_matrix.cmake
+          cmake -P cmake/generate_part1_io_matrix.cmake
+          cmake -P cmake/generate_part5_io_matrix.cmake
+
+      - name: Verify replay fixtures
+        run: cmake -P cmake/verify_replay_fixtures.cmake
+
+      - name: Set up Python
+        if: matrix.compiler == 'gcc'
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Configure CMake
+        run: >
+          cmake -S . -B build
+          -DCMAKE_BUILD_TYPE=Release
+          -DCMAKE_C_COMPILER=${{ matrix.cc }}
+          -DCMAKE_CXX_COMPILER=${{ matrix.cxx }}
+          -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+
+      - name: Build
+        run: cmake --build build --parallel
+
+      - name: Test
+        run: ctest --test-dir build --output-on-failure -LE fuzz
+
+      - name: Print core benchmark baseline
+        run: ctest --test-dir build --output-on-failure -R plcopen_core_benchmark -V
+
+      - name: clang-tidy gate (E2)
+        if: matrix.compiler == 'clang'
+        run: cmake -P cmake/clang_tidy_gate.cmake
+
+      - name: Core cross-compile smoke (legacy)
+        if: matrix.compiler == 'gcc'
+        run: cmake -P cmake/core_cross_compile_smoke.cmake
+
+      - name: Verify installed find_package consumer
+        if: matrix.compiler == 'gcc'
+        run: |
+          install_prefix="$PWD/build/ci-install"
+          cmake --install build --prefix "$install_prefix"
+          cmake -S test_package/find_package -B build/ci-find -DCMAKE_PREFIX_PATH="$install_prefix"
+          cmake --build build/ci-find --parallel
+          ./build/ci-find/plcopen_find_package_smoke
+
+      - name: Verify FetchContent consumer
+        if: matrix.compiler == 'gcc'
+        run: |
+          cmake -S test_package/fetchcontent -B build/ci-fetch -DPLCOPEN_SOURCE_DIR="$PWD"
+          cmake --build build/ci-fetch --parallel
+          consumer="$(find build/ci-fetch -name 'plcopen_fetchcontent_smoke' -type f -print -quit)"
+          test -n "$consumer"
+          "$consumer"
+
+      - name: Build and test Python bindings
+        if: matrix.compiler == 'gcc'
+        run: |
+          cmake -S . -B build-python \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_CXX_COMPILER=${{ matrix.cxx }} \
+            -DPLCOPEN_BUILD_DEMOS=OFF \
+            -DPLCOPEN_BUILD_TESTS=OFF \
+            -DPLCOPEN_BUILD_PYTHON_BINDINGS=ON
+          cmake --build build-python --parallel
+          ctest --test-dir build-python -R pyplcopen_smoke --output-on-failure
+
+      - name: Install Doxygen
+        if: matrix.compiler == 'gcc'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y doxygen graphviz
+          dot -V
+
+      - name: Generate API documentation
+        if: matrix.compiler == 'gcc'
+        run: |
+          cmake -S . -B build-docs \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_CXX_COMPILER=${{ matrix.cxx }} \
+            -DBUILD_TESTING=OFF \
+            -DPLCOPEN_BUILD_DEMOS=OFF \
+            -DPLCOPEN_BUILD_TESTS=OFF \
+            -DPLCOPEN_BUILD_DOCS=ON
+          cmake --build build-docs --target docs
+          test -s build-docs/docs/api/html/index.html
+          find build-docs/docs/api/html -name '*.png' -type f -print -quit | grep -q .
+          find build-docs/docs/api/html -name '*.map' -type f -print -quit | grep -q .
+
+  arm64-cross:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Install ARM64 toolchain and QEMU
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y g++-aarch64-linux-gnu qemu-user-static
+
+      - name: Configure (ARM64 cross-compile)
+        run: >
+          cmake -S . -B build-arm64
+          -DCMAKE_BUILD_TYPE=Release
+          -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-aarch64-linux-gnu.cmake
+          -DPLCOPEN_BUILD_DEMOS=OFF
+
+      - name: Build
+        run: cmake --build build-arm64 --parallel
+
+      - name: Test (via QEMU user-mode)
+        run: >
+          ctest --test-dir build-arm64 --output-on-failure
+          -E "(benchmark|jitter_harness)" -LE fuzz

pyplcopen-0.20.0/.github/workflows/mutation-score.yml

@@ -0,0 +1,18 @@
+name: Mutation Score Gate
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: '17 3 * * 1'
+
+jobs:
+  mutation-score:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Run mutation score gate (E3)
+        run: cmake -P cmake/mutation_score_gate.cmake

pyplcopen-0.20.0/.github/workflows/wheels.yml

@@ -0,0 +1,72 @@
+name: Wheels
+
+on:
+  workflow_dispatch:
+  push:
+    tags: ['v*']
+
+jobs:
+  build_wheels:
+    name: Wheels · ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: pypa/cibuildwheel@v4.1.0
+        env:
+          CIBW_BUILD: "cp310-* cp311-* cp312-* cp313-*"
+          CIBW_SKIP: "*-musllinux_*"
+          CIBW_TEST_COMMAND: "python {project}/ci/smoke_test.py"
+          CIBW_ARCHS_MACOS: "x86_64 arm64"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  # PyPI 发布（Trusted Publishing / OIDC，无 token secret）。
+  # 首次发布的人专属前置（未完成前本作业必然失败）：维护者在 PyPI 注册
+  # trusted publisher（project: pyplcopen, owner: lusipad, repo: plcopen,
+  # workflow: wheels.yml, environment: pypi）并在仓库建 pypi environment。
+  # 仅 tag 推送触发；维护者明确授权版本与目标提交后，AI 可代为推送 tag。
+  publish_pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

pyplcopen-0.20.0/.github/workflows/windows-ci.yml

@@ -0,0 +1,74 @@
+name: Windows CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build-test:
+    runs-on: windows-latest
+
+    defaults:
+      run:
+        shell: pwsh
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Run RT-safety static scan
+        run: cmake -P cmake/rt_safety_scan.cmake
+
+      - name: Verify generated compliance matrix
+        run: |
+          cmake -P cmake/generate_part1_part2_matrix.cmake
+          cmake -P cmake/generate_part1_io_matrix.cmake
+          cmake -P cmake/generate_part5_io_matrix.cmake
+
+      - name: Verify replay fixtures
+        run: cmake -P cmake/verify_replay_fixtures.cmake
+
+      - name: Clean build and run regular CTest suite
+        run: .\build.ps1 -Clean -Test -ExcludeFuzz
+
+      - name: Collect coverage
+        run: .\coverage.ps1 -ExcludeFuzz
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v7
+        with:
+          name: windows-coverage
+          path: out/coverage
+          retention-days: 14
+
+      - name: Verify installed find_package consumer
+        run: |
+          $InstallPrefix = Join-Path $env:GITHUB_WORKSPACE "build/ci-install"
+          cmake --install build --config Release --prefix $InstallPrefix
+          cmake -S test_package/find_package -B build/ci-find "-DCMAKE_PREFIX_PATH=$InstallPrefix"
+          cmake --build build/ci-find --config Release --parallel -- /p:TrackFileAccess=false /nodeReuse:false
+
+          $Consumer = Get-ChildItem build/ci-find -Recurse -File -Filter plcopen_find_package_smoke.exe | Select-Object -First 1
+          if (-not $Consumer) {
+            throw "find_package consumer executable was not produced"
+          }
+          & $Consumer.FullName
+          if ($LASTEXITCODE -ne 0) {
+            throw "find_package consumer failed"
+          }
+
+      - name: Verify FetchContent consumer with Windows path
+        run: |
+          cmake -S test_package/fetchcontent -B build/ci-fetch "-DPLCOPEN_SOURCE_DIR=$env:GITHUB_WORKSPACE"
+          cmake --build build/ci-fetch --config Release --parallel -- /p:TrackFileAccess=false /nodeReuse:false
+
+          $Consumer = Get-ChildItem build/ci-fetch -Recurse -File -Filter plcopen_fetchcontent_smoke.exe | Select-Object -First 1
+          if (-not $Consumer) {
+            throw "FetchContent consumer artifacts were not produced"
+          }
+          & $Consumer.FullName
+          if ($LASTEXITCODE -ne 0) {
+            throw "FetchContent consumer failed"
+          }

pyplcopen-0.20.0/.gitignore

@@ -0,0 +1,51 @@
+# Prerequisites
+*.d
+
+# Compiled Object files
+*.slo
+*.lo
+*.o
+*.obj
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Compiled Dynamic libraries
+*.so
+*.dylib
+*.dll
+
+# Fortran module files
+*.mod
+*.smod
+
+# Compiled Static libraries
+*.lai
+*.la
+*.a
+*.lib
+
+# Executables
+*.exe
+*.out
+*.app
+
+.vs
+build
+build-*/
+out
+.cache
+.playwright-cli/
+.omx/
+site/
+
+# Local AI session state stays ignored, but the versioned harness
+# (.claude/skills/) is part of the repository.
+.claude/*
+!.claude/skills/
+
+# PLCopen 规格文档本地缓存（版权文档，不再分发——见
+# doc/compliance/plcopen-specs-manifest.md；用 tools/fetch-plcopen-specs.sh 取回）
+refs/plcopen-specs/
+refs/zeroth-01/