ros_checker 0.1.0__tar.gz

ros_checker-0.1.0/.gitignore

@@ -0,0 +1,126 @@
+# Created by expert developer assistant
+# Optimized for ROS-based Python project
+
+### Project Specific ###
+# ROS home and logs
+.ros-home/
+*.log
+
+# Local uv cache (CI에서 UV_CACHE_DIR=.uv-cache 사용)
+.uv-cache/
+
+# Binary and Data files
+*.msgpack
+*.rkyv
+*.so
+*.pem
+# *.lock
+*.tag
+*.rev
+
+# Environment variables
+.env
+!.env.example
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Environments
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Mypy / Ruff / Pyright
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.ruff_cache/
+pyrightconfig.json
+
+### IDEs ###
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+.history/
+
+# PyCharm / JetBrains
+.idea/
+
+### OS Specific ###
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+._*
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Windows
+Thumbs.db
+Thumbs.db:encryptable
+ehthumbs.db
+ehthumbs_vista.db
+*.stackdump
+[Dd]esktop.ini
+$RECYCLE.BIN/
+*.lnk
+
+# Linux
+*~
+.fuse_hidden*
+.directory
+.Trash-*
+.nfs*

ros_checker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ros_checker contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ros_checker-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.5
+Name: ros_checker
+Version: 0.1.0
+Summary: ROS2 토픽/노드/서비스/액션을 분석하고 Nav2 구동 여부를 LLM으로 진단하는 CLI 앱
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: numpy
+Requires-Dist: wpycli
+Requires-Dist: wpyconf
+Requires-Dist: wpylog
+Description-Content-Type: text/markdown
+
+# ros_checker
+
+ROS2 토픽/노드/서비스/액션을 분석해 **신호 수신 여부**와 **Nav2 구동 가능성**을 체크하고, **LLM(ollama / Azure OpenAI)**으로 자연어 진단을 제공하는 CLI 앱입니다.
+
+로컬(호스트 ROS2)과 Docker(컨테이너 ROS2) 환경 모두에서 동작합니다.
+
+## 기능
+
+| 커맨드 | 설명 |
+|---|---|
+| `ros-checker scan` | ROS2 그래프 스캔 — 토픽/노드/서비스/액션, 토픽별 hz·대역폭 |
+| `ros-checker health` | 토픽 신호 수신, 노드 존재, 서비스 호출 헬스 체크 |
+| `ros-checker nav2` | Nav2 구동 가능성 체크 (라이프사이클, costmap, cmd_vel, 액션) |
+| `ros-checker analyze` | 수집 데이터를 LLM으로 자연어 진단 |
+| `ros-checker config` | 설정 출력 (`config init`/`set`으로 생성·수정) |
+
+## 문서
+
+- [AGENTS.md](AGENTS.md) — 에이전트/개발자용 개발 가이드 (TDD, 스타일, 명령어)
+- [CONTRIBUTING.md](CONTRIBUTING.md) — 기여 가이드
+- [SECURITY.md](SECURITY.md) — 보안 취약점 보고 절차
+- [docs/PLAN.md](docs/PLAN.md) — 초기 구현 계획
+
+## 요구사항
+
+- Python 3.12
+- ROS2 (Jazzy 등) — `rclpy` 필요. `source /opt/ros/<distro>/setup.bash` 후 실행
+- LLM: ollama(로컬) 또는 Azure OpenAI(클라우드)
+
+## 설치 및 실행 (로컬)
+
+```bash
+uv sync --group dev
+source /opt/ros/<distro>/setup.bash
+
+# 그래프 스캔
+uv run ros-checker scan
+
+# 헬스 체크
+uv run ros-checker health
+
+# Nav2 구동 가능성
+uv run ros-checker nav2
+
+# LLM 진단 (ollama 기본)
+uv run ros-checker analyze
+```
+
+> ROS2가 없는 환경에서도 `--mock` 플래그로 Mock 그래프를 사용해 기능을 확인할 수 있습니다.
+> `uv run ros-checker nav2 --mock`
+
+## 설정
+
+설정은 **플랫폼 표준 설정 디렉터리**의 `config.toml`에서 읽습니다.
+
+| 플랫폼 | 기본 경로 |
+|---|---|
+| Linux | `$XDG_CONFIG_HOME/ros-checker/config.toml` (기본 `~/.config/ros-checker/config.toml`) |
+| macOS | `~/Library/Application Support/ros-checker/config.toml` |
+| Windows | `%APPDATA%\ros-checker\config.toml` |
+
+`config` 커맨드로 관리합니다.
+
+```bash
+# 기본 config.toml 생성
+ros-checker config init
+
+# 항목 수정·저장 (점 표기 키)
+ros-checker config set llm.provider azure
+ros-checker config set llm.model gpt-4o
+ros-checker config set llm.timeout 30
+
+# 현재 유효 설정 출력
+ros-checker config
+```
+
+설정 파일이나 `.env`가 없어도 **내장 기본값으로 동작**하므로, uvx 등에서 별도 파일 없이 바로 실행할 수 있습니다. 파일을 지정하려면 `-c/--config`와 `--dotenv` 플래그를 사용합니다.
+
+## LLM 설정
+
+`config init`/`config set`으로 생성한 설정 파일이나 `.env`로 프로바이더를 선택합니다.
+
+**ollama (기본)**
+```toml
+[llm]
+provider = "ollama"
+base_url = "http://localhost:11434"
+model = "llama3.2"
+```
+
+**Azure OpenAI**
+```toml
+[llm]
+provider = "azure"
+base_url = "https://<resource>.openai.azure.com"
+model = "<deployment-name>"
+api_key = "<your-api-key>"
+```
+
+환경 변수로도 설정 가능합니다 (`ROS_CHECKER_LLM__PROVIDER` 등, `.env.example` 참고).
+
+## uvx로 실행 (로봇에서)
+
+패키지를 PyPI에 배포하면 로봇에서 `uvx`로 설치 없이 실행할 수 있습니다.
+
+```bash
+# ROS2 환경 source 후
+source /opt/ros/<distro>/setup.bash
+
+# 그래프 스캔 (rclpy 없으면 자동으로 ros2 CLI 사용)
+uvx ros-checker scan
+
+# CLI 소스 명시 (ros2 CLI만 필요, 가장 견고)
+uvx ros-checker scan --source cli
+
+# Nav2 체크 / LLM 진단
+uvx ros-checker nav2 --source cli
+uvx ros-checker analyze --source cli
+```
+
+> **동작 원리**: `uvx`는 격리 환경을 만들지만 시스템 파이썬을 사용하므로 rclpy가 import 가능한 경우 rclpy 소스가 동작합니다. rclpy가 없거나 `~/.ros` 로그 문제가 있으면 `--source cli`로 `ros2` CLI만 사용해 동작합니다. 로봇에는 `ros2` CLI가 항상 있으므로 `--source cli`가 가장 안정적입니다.
+>
+> 설정은 cwd가 아닌 **플랫폼 기본 경로**에서 읽으므로, 설정 파일이 없어도 기본값으로 동작합니다. 사용자 설정이 필요하면 `uvx ros-checker config init`로 기본 config를 만든 뒤 `config set`으로 수정하세요.
+
+## Docker 사용
+
+체커는 ROS2 그래프의 **노드로 참여**하므로, ROS2 컨테이너와 **같은 네트워크 + 동일 `ROS_DOMAIN_ID`**로 실행해야 합니다.
+
+```bash
+docker compose build
+docker compose up -d ros2-system   # ROS2 시스템(예: talker) 기동
+docker compose run --rm checker scan
+docker compose run --rm checker nav2
+docker compose run --rm checker analyze
+```
+
+실제 Nav2/로봇 시스템을 사용한다면 `docker-compose.yml`의 `ros2-system` 서비스를 해당 이미지로 교체하세요.
+
+## 개발
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+> rclpy 통합 테스트는 `~/.ros`에 로그를 쓰므로, 읽기 전용 환경에서는
+> `ROS_LOG_DIR`을 임시 경로로 지정하세요. 통합 테스트는 자체적으로 임시
+> 디렉터리를 사용합니다.
+
+## 아키텍처
+
+```
+┌─────────────────────────────────────────────────────┐
+│  ros-checker CLI (wpycli 기반)                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
+│  │ Graph        │  │ Health       │  │ LLM       │  │
+│  │ Introspection│→ │ Check Engine │→ │ Analyzer  │  │
+│  │ (rclpy)      │  │ (rules)      │  │ (provider)│  │
+│  └──────────────┘  └──────────────┘  └───────────┘  │
+│        │                 │                │         │
+│  ┌─────▼─────┐     ┌─────▼─────┐    ┌─────▼─────┐   │
+│  │ ROS2 Graph│     │ Nav2      │    │ ollama /  │   │
+│  │ (DDS)     │     │ Checker   │    │ AzureOpenAI│  │
+│  └───────────┘     └───────────┘    └───────────┘   │
+└─────────────────────────────────────────────────────┘
+```
+
+- `src/ros_checker/graph/` — ROS2 그래프 인트로스펙션 (rclpy + Mock)
+- `src/ros_checker/health/` — 헬스 체크 엔진 + Nav2 규칙
+- `src/ros_checker/llm/` — LLM 프로바이더 추상화 (ollama/Azure OpenAI)
+- `src/ros_checker/report/` — 테이블/JSON 리포트 렌더링
+
+## 라이선스
+
+[MIT](LICENSE) 라이선스로 배포됩니다.

ros_checker-0.1.0/README.md

@@ -0,0 +1,177 @@
+# ros_checker
+
+ROS2 토픽/노드/서비스/액션을 분석해 **신호 수신 여부**와 **Nav2 구동 가능성**을 체크하고, **LLM(ollama / Azure OpenAI)**으로 자연어 진단을 제공하는 CLI 앱입니다.
+
+로컬(호스트 ROS2)과 Docker(컨테이너 ROS2) 환경 모두에서 동작합니다.
+
+## 기능
+
+| 커맨드 | 설명 |
+|---|---|
+| `ros-checker scan` | ROS2 그래프 스캔 — 토픽/노드/서비스/액션, 토픽별 hz·대역폭 |
+| `ros-checker health` | 토픽 신호 수신, 노드 존재, 서비스 호출 헬스 체크 |
+| `ros-checker nav2` | Nav2 구동 가능성 체크 (라이프사이클, costmap, cmd_vel, 액션) |
+| `ros-checker analyze` | 수집 데이터를 LLM으로 자연어 진단 |
+| `ros-checker config` | 설정 출력 (`config init`/`set`으로 생성·수정) |
+
+## 문서
+
+- [AGENTS.md](AGENTS.md) — 에이전트/개발자용 개발 가이드 (TDD, 스타일, 명령어)
+- [CONTRIBUTING.md](CONTRIBUTING.md) — 기여 가이드
+- [SECURITY.md](SECURITY.md) — 보안 취약점 보고 절차
+- [docs/PLAN.md](docs/PLAN.md) — 초기 구현 계획
+
+## 요구사항
+
+- Python 3.12
+- ROS2 (Jazzy 등) — `rclpy` 필요. `source /opt/ros/<distro>/setup.bash` 후 실행
+- LLM: ollama(로컬) 또는 Azure OpenAI(클라우드)
+
+## 설치 및 실행 (로컬)
+
+```bash
+uv sync --group dev
+source /opt/ros/<distro>/setup.bash
+
+# 그래프 스캔
+uv run ros-checker scan
+
+# 헬스 체크
+uv run ros-checker health
+
+# Nav2 구동 가능성
+uv run ros-checker nav2
+
+# LLM 진단 (ollama 기본)
+uv run ros-checker analyze
+```
+
+> ROS2가 없는 환경에서도 `--mock` 플래그로 Mock 그래프를 사용해 기능을 확인할 수 있습니다.
+> `uv run ros-checker nav2 --mock`
+
+## 설정
+
+설정은 **플랫폼 표준 설정 디렉터리**의 `config.toml`에서 읽습니다.
+
+| 플랫폼 | 기본 경로 |
+|---|---|
+| Linux | `$XDG_CONFIG_HOME/ros-checker/config.toml` (기본 `~/.config/ros-checker/config.toml`) |
+| macOS | `~/Library/Application Support/ros-checker/config.toml` |
+| Windows | `%APPDATA%\ros-checker\config.toml` |
+
+`config` 커맨드로 관리합니다.
+
+```bash
+# 기본 config.toml 생성
+ros-checker config init
+
+# 항목 수정·저장 (점 표기 키)
+ros-checker config set llm.provider azure
+ros-checker config set llm.model gpt-4o
+ros-checker config set llm.timeout 30
+
+# 현재 유효 설정 출력
+ros-checker config
+```
+
+설정 파일이나 `.env`가 없어도 **내장 기본값으로 동작**하므로, uvx 등에서 별도 파일 없이 바로 실행할 수 있습니다. 파일을 지정하려면 `-c/--config`와 `--dotenv` 플래그를 사용합니다.
+
+## LLM 설정
+
+`config init`/`config set`으로 생성한 설정 파일이나 `.env`로 프로바이더를 선택합니다.
+
+**ollama (기본)**
+```toml
+[llm]
+provider = "ollama"
+base_url = "http://localhost:11434"
+model = "llama3.2"
+```
+
+**Azure OpenAI**
+```toml
+[llm]
+provider = "azure"
+base_url = "https://<resource>.openai.azure.com"
+model = "<deployment-name>"
+api_key = "<your-api-key>"
+```
+
+환경 변수로도 설정 가능합니다 (`ROS_CHECKER_LLM__PROVIDER` 등, `.env.example` 참고).
+
+## uvx로 실행 (로봇에서)
+
+패키지를 PyPI에 배포하면 로봇에서 `uvx`로 설치 없이 실행할 수 있습니다.
+
+```bash
+# ROS2 환경 source 후
+source /opt/ros/<distro>/setup.bash
+
+# 그래프 스캔 (rclpy 없으면 자동으로 ros2 CLI 사용)
+uvx ros-checker scan
+
+# CLI 소스 명시 (ros2 CLI만 필요, 가장 견고)
+uvx ros-checker scan --source cli
+
+# Nav2 체크 / LLM 진단
+uvx ros-checker nav2 --source cli
+uvx ros-checker analyze --source cli
+```
+
+> **동작 원리**: `uvx`는 격리 환경을 만들지만 시스템 파이썬을 사용하므로 rclpy가 import 가능한 경우 rclpy 소스가 동작합니다. rclpy가 없거나 `~/.ros` 로그 문제가 있으면 `--source cli`로 `ros2` CLI만 사용해 동작합니다. 로봇에는 `ros2` CLI가 항상 있으므로 `--source cli`가 가장 안정적입니다.
+>
+> 설정은 cwd가 아닌 **플랫폼 기본 경로**에서 읽으므로, 설정 파일이 없어도 기본값으로 동작합니다. 사용자 설정이 필요하면 `uvx ros-checker config init`로 기본 config를 만든 뒤 `config set`으로 수정하세요.
+
+## Docker 사용
+
+체커는 ROS2 그래프의 **노드로 참여**하므로, ROS2 컨테이너와 **같은 네트워크 + 동일 `ROS_DOMAIN_ID`**로 실행해야 합니다.
+
+```bash
+docker compose build
+docker compose up -d ros2-system   # ROS2 시스템(예: talker) 기동
+docker compose run --rm checker scan
+docker compose run --rm checker nav2
+docker compose run --rm checker analyze
+```
+
+실제 Nav2/로봇 시스템을 사용한다면 `docker-compose.yml`의 `ros2-system` 서비스를 해당 이미지로 교체하세요.
+
+## 개발
+
+```bash
+uv sync --group dev
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest
+```
+
+> rclpy 통합 테스트는 `~/.ros`에 로그를 쓰므로, 읽기 전용 환경에서는
+> `ROS_LOG_DIR`을 임시 경로로 지정하세요. 통합 테스트는 자체적으로 임시
+> 디렉터리를 사용합니다.
+
+## 아키텍처
+
+```
+┌─────────────────────────────────────────────────────┐
+│  ros-checker CLI (wpycli 기반)                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐  │
+│  │ Graph        │  │ Health       │  │ LLM       │  │
+│  │ Introspection│→ │ Check Engine │→ │ Analyzer  │  │
+│  │ (rclpy)      │  │ (rules)      │  │ (provider)│  │
+│  └──────────────┘  └──────────────┘  └───────────┘  │
+│        │                 │                │         │
+│  ┌─────▼─────┐     ┌─────▼─────┐    ┌─────▼─────┐   │
+│  │ ROS2 Graph│     │ Nav2      │    │ ollama /  │   │
+│  │ (DDS)     │     │ Checker   │    │ AzureOpenAI│  │
+│  └───────────┘     └───────────┘    └───────────┘   │
+└─────────────────────────────────────────────────────┘
+```
+
+- `src/ros_checker/graph/` — ROS2 그래프 인트로스펙션 (rclpy + Mock)
+- `src/ros_checker/health/` — 헬스 체크 엔진 + Nav2 규칙
+- `src/ros_checker/llm/` — LLM 프로바이더 추상화 (ollama/Azure OpenAI)
+- `src/ros_checker/report/` — 테이블/JSON 리포트 렌더링
+
+## 라이선스
+
+[MIT](LICENSE) 라이선스로 배포됩니다.

ros_checker-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "ros_checker"
+version = "0.1.0"
+description = "ROS2 토픽/노드/서비스/액션을 분석하고 Nav2 구동 여부를 LLM으로 진단하는 CLI 앱"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "wpyconf",
+    "wpylog",
+    "wpycli",
+    "httpx>=0.27",
+    "numpy"
+]
+
+[project.scripts]
+ros-checker = "ros_checker.main:main"
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build]
+exclude = [
+  "/.git",
+  "/.venv",
+  "/.uv-cache",
+  "/.ros-home",
+  "/.pytest_cache",
+  "/.ruff_cache",
+  "/build",
+  "/dist",
+  "*.egg-info",
+]
+
+# PyPI 소스 배포는 필요한 파일만 화이트리스트로 포함
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+  "/README.md",
+  "/LICENSE",
+]
+
+[tool.uv]
+package = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F", "I"]
+
+[dependency-groups]
+dev = ["ruff", "pytest"]
+
+[tool.pytest.ini_options]
+# ROS2 환경이 source된 셸에서 launch_testing 등 ROS2 pytest 플러그인이
+# 자동 로드되어 실패하는 것을 방지한다.
+addopts = "-p no:launch_testing -p no:launch_ros"

ros_checker-0.1.0/src/ros_checker/__init__.py

@@ -0,0 +1,5 @@
+"""ros_checker — ROS2 토픽/노드/서비스/액션 분석 및 Nav2 구동 진단 CLI."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

ros_checker-0.1.0/src/ros_checker/graph/__init__.py

@@ -0,0 +1,34 @@
+"""ROS2 그래프 인트로스펙션 패키지."""
+
+from .cli import Ros2CliGraphSource
+from .mock import MockGraphSource, build_mock_snapshot
+from .models import (
+    ActionInfo,
+    GraphSnapshot,
+    NodeInfo,
+    ServiceInfo,
+    TopicInfo,
+)
+from .source import (
+    GraphSource,
+    RclpyGraphSource,
+    detect_domain_id,
+    detect_ros_distro,
+    rclpy_available,
+)
+
+__all__ = [
+    "ActionInfo",
+    "GraphSnapshot",
+    "GraphSource",
+    "MockGraphSource",
+    "NodeInfo",
+    "RclpyGraphSource",
+    "Ros2CliGraphSource",
+    "ServiceInfo",
+    "TopicInfo",
+    "build_mock_snapshot",
+    "detect_domain_id",
+    "detect_ros_distro",
+    "rclpy_available",
+]