From a77eae95171eebc72f0bdee15358b3c155dca5dd Mon Sep 17 00:00:00 2001 From: Andreas Michael Fleckl <533481+oib@users.noreply.github.com> Date: Tue, 17 Feb 2026 15:50:54 +0100 Subject: [PATCH 1/2] docs: add codebase review task suggestions --- .../2026-02-17-codebase-task-vorschlaege.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/issues/2026-02-17-codebase-task-vorschlaege.md diff --git a/docs/issues/2026-02-17-codebase-task-vorschlaege.md b/docs/issues/2026-02-17-codebase-task-vorschlaege.md new file mode 100644 index 0000000..9174645 --- /dev/null +++ b/docs/issues/2026-02-17-codebase-task-vorschlaege.md @@ -0,0 +1,51 @@ +# Vorschläge für konkrete Korrekturaufgaben (Codebasis-Review) + +## 1) Aufgabe: Tippfehler in Dokumentations-Links korrigieren + +**Problem:** In der Datei `docs/8_development/1_overview.md` zeigen mehrere „Next Steps“-Links auf Dateinamen ohne den numerischen Präfix und laufen dadurch ins Leere (z. B. `setup.md`, `api-authentication.md`, `contributing.md`). + +**Vorschlag:** Alle betroffenen relativen Links auf die tatsächlichen Dateien mit Präfix umstellen (z. B. `2_setup.md`, `6_api-authentication.md`, `3_contributing.md`). + +**Akzeptanzkriterien:** +- Kein 404/Dead-Link mehr aus `1_overview.md` auf interne Entwicklungsdokumente. +- Link-Check (`markdown-link-check` oder vergleichbar) für `docs/8_development/1_overview.md` läuft ohne Fehler. + +--- + +## 2) Aufgabe: Programmierfehler in `config export` beheben + +**Problem:** In `cli/aitbc_cli/commands/config.py` wird bei `export` das YAML geladen und anschließend direkt `if 'api_key' in config_data:` geprüft. Ist die Datei leer, liefert `yaml.safe_load` den Wert `None`; die Membership-Prüfung wirft dann einen `TypeError`. + +**Vorschlag:** Nach dem Laden defensiv normalisieren, z. B. `config_data = yaml.safe_load(f) or {}`. + +**Akzeptanzkriterien:** +- `aitbc config export` mit leerer Config-Datei bricht nicht mit Exception ab. +- Rückgabe bleibt valide (leere Struktur in YAML/JSON statt Traceback). + +--- + +## 3) Aufgabe: Dokumentations-Unstimmigkeit zu Python-Version bereinigen + +**Problem:** `docs/1_project/3_infrastructure.md` nennt „Python 3.11+“ als Laufzeitannahme, während das Root-`pyproject.toml` `requires-python = ">=3.8"` definiert. Das ist widersprüchlich für Contributor und CI. + +**Vorschlag:** Versionsstrategie vereinheitlichen: +- Entweder Doku auf den tatsächlich unterstützten Bereich anpassen, +- oder Projektmetadaten/Tooling auf 3.11+ anheben (inkl. CI-Matrix). + +**Akzeptanzkriterien:** +- Doku und Projektmetadaten nennen dieselbe minimale Python-Version. +- CI/Tests dokumentieren und nutzen diese Zielversion konsistent. + +--- + +## 4) Aufgabe: Testabdeckung verbessern (doppelte Testfunktion in `test_config.py`) + +**Problem:** In `tests/cli/test_config.py` existiert die Testfunktion `test_environments` zweimal. In Python überschreibt die zweite Definition die erste, wodurch ein Testfall effektiv verloren geht. + +**Vorschlag:** +- Eindeutige Testnamen vergeben (z. B. `test_environments_table_output` und `test_environments_json_output`). +- Optional parametrisierte Tests nutzen, um Dopplungen robust abzudecken. + +**Akzeptanzkriterien:** +- Keine doppelten Testfunktionsnamen mehr in der Datei. +- Beide bislang beabsichtigten Szenarien werden tatsächlich ausgeführt und sind im Testreport sichtbar. From e2dfb0ea84052c5c4d39ad158eb5806ffbcd97ec Mon Sep 17 00:00:00 2001 From: Andreas Michael Fleckl <533481+oib@users.noreply.github.com> Date: Tue, 17 Feb 2026 16:00:11 +0100 Subject: [PATCH 2/2] fix: implement review follow-ups across docs, config, and tests --- cli/aitbc_cli/commands/config.py | 2 +- docs/1_project/3_infrastructure.md | 8 +- docs/8_development/1_overview.md | 12 +-- tests/cli/test_config.py | 117 ----------------------------- 4 files changed, 11 insertions(+), 128 deletions(-) diff --git a/cli/aitbc_cli/commands/config.py b/cli/aitbc_cli/commands/config.py index 41b2cf3..40c2567 100644 --- a/cli/aitbc_cli/commands/config.py +++ b/cli/aitbc_cli/commands/config.py @@ -174,7 +174,7 @@ def export(ctx, output_format: str, global_config: bool): ctx.exit(1) with open(config_file) as f: - config_data = yaml.safe_load(f) + config_data = yaml.safe_load(f) or {} # Redact sensitive data if 'api_key' in config_data: diff --git a/docs/1_project/3_infrastructure.md b/docs/1_project/3_infrastructure.md index a07861d..ec60f71 100644 --- a/docs/1_project/3_infrastructure.md +++ b/docs/1_project/3_infrastructure.md @@ -83,7 +83,7 @@ journalctl -u aitbc-mock-coordinator --no-pager -n 20 ### Python Environment (Host) -Development and testing services on localhost use **Python 3.11+**: +Development and testing services on localhost use **Python 3.8+**: ```bash # Localhost development workspace @@ -96,7 +96,7 @@ Development and testing services on localhost use **Python 3.11+**: **Verification Commands:** ```bash -python3 --version # Should show Python 3.11+ +python3 --version # Should show Python 3.8+ ls -la /home/oib/windsurf/aitbc/.venv/bin/python # Check venv ``` @@ -151,7 +151,7 @@ ssh aitbc-cascade # Direct SSH to container ### Python Environment Details -All Python services in the AITBC container run on **Python 3.11+** with isolated virtual environments: +All Python services in the AITBC container run on **Python 3.8+** with isolated virtual environments: ```bash # Container: aitbc (10.1.223.93) @@ -163,7 +163,7 @@ All Python services in the AITBC container run on **Python 3.11+** with isolated **Verification Commands:** ```bash -ssh aitbc-cascade "python3 --version" # Should show Python 3.11+ +ssh aitbc-cascade "python3 --version" # Should show Python 3.8+ ssh aitbc-cascade "ls -la /opt/*/.venv/bin/python" # Check venv symlinks ``` diff --git a/docs/8_development/1_overview.md b/docs/8_development/1_overview.md index dc71b13..cee13cd 100644 --- a/docs/8_development/1_overview.md +++ b/docs/8_development/1_overview.md @@ -142,7 +142,7 @@ Choose a tutorial based on your interest: ### Documentation - [API Reference](../api/) -- [SDK Guides](sdks/) +- [SDK Guides](4_examples.md) - [Examples](examples.md) - [Best Practices](best-practices.md) @@ -250,7 +250,7 @@ We welcome contributions! Areas where you can help: - Community support - Integration examples -See our [Contributing Guide](contributing.md) for details. +See our [Contributing Guide](3_contributing.md) for details. ## Support @@ -261,9 +261,9 @@ See our [Contributing Guide](contributing.md) for details. ## Next Steps -1. [Set up your environment](setup.md) -2. [Learn about authentication](api-authentication.md) -3. [Choose an SDK](sdks/) -4. [Build your first app](../../tutorials/) +1. [Set up your environment](2_setup.md) +2. [Learn about authentication](6_api-authentication.md) +3. [Choose an SDK](4_examples.md) +4. [Build your first app](4_examples.md) Happy building! 🚀 diff --git a/tests/cli/test_config.py b/tests/cli/test_config.py index 6a897b0..1949d63 100644 --- a/tests/cli/test_config.py +++ b/tests/cli/test_config.py @@ -422,123 +422,6 @@ def test_environments(self, runner, mock_config): assert result.exit_code == 0 assert 'CLIENT_API_KEY' in result.output - def test_profiles_save(self, runner, mock_config, tmp_path): - """Test saving a configuration profile""" - profiles_dir = tmp_path / ".config" / "aitbc" / "profiles" - - result = runner.invoke(config, [ - 'profiles', - 'save', - 'test_profile' - ], obj={'config': mock_config, 'output_format': 'table'}) - - assert result.exit_code == 0 - assert 'Profile test_profile saved' in result.output - - # Verify profile was created - profile_file = profiles_dir / "test_profile.yaml" - assert profile_file.exists() - with open(profile_file) as f: - profile_data = yaml.safe_load(f) - assert profile_data['coordinator_url'] == 'http://127.0.0.1:18000' - - def test_profiles_list(self, runner, mock_config, tmp_path): - """Test listing configuration profiles""" - # Create test profiles - profiles_dir = tmp_path / ".config" / "aitbc" / "profiles" - profiles_dir.mkdir(parents=True, exist_ok=True) - - profile1 = profiles_dir / "profile1.yaml" - profile1.write_text(yaml.dump({"coordinator_url": "http://test1:8000"})) - - profile2 = profiles_dir / "profile2.yaml" - profile2.write_text(yaml.dump({"coordinator_url": "http://test2:8000"})) - - # Patch Path.home to return tmp_path - with patch('pathlib.Path.home') as mock_home: - mock_home.return_value = tmp_path - - result = runner.invoke(config, [ - 'profiles', - 'list' - ], obj={'config': mock_config, 'output_format': 'table'}) - - assert result.exit_code == 0 - assert 'profile1' in result.output - assert 'profile2' in result.output - - def test_profiles_load(self, runner, mock_config, tmp_path): - """Test loading a configuration profile""" - # Create test profile - profiles_dir = tmp_path / ".config" / "aitbc" / "profiles" - profiles_dir.mkdir(parents=True, exist_ok=True) - - profile_file = profiles_dir / "test.yaml" - profile_data = { - "coordinator_url": "http://loaded:8000", - "timeout": 75 - } - profile_file.write_text(yaml.dump(profile_data)) - - config_file = tmp_path / ".aitbc.yaml" - - with runner.isolated_filesystem(temp_dir=tmp_path): - # Patch Path.home to return tmp_path - with patch('pathlib.Path.home') as mock_home: - mock_home.return_value = tmp_path - - result = runner.invoke(config, [ - 'profiles', - 'load', - 'test' - ], obj={'config': mock_config, 'output_format': 'table'}) - - assert result.exit_code == 0 - assert 'Profile test loaded' in result.output - - def test_validate_invalid_url(self, runner, mock_config): - """Test validating config with invalid URL""" - mock_config.coordinator_url = "invalid-url" - - result = runner.invoke(config, [ - 'validate' - ], obj={'config': mock_config, 'output_format': 'table'}) - - assert result.exit_code != 0 - assert 'validation failed' in result.output - - def test_validate_short_api_key(self, runner, mock_config): - """Test validating config with short API key""" - mock_config.api_key = "short" - - result = runner.invoke(config, [ - 'validate' - ], obj={'config': mock_config, 'output_format': 'table'}) - - assert result.exit_code != 0 - assert 'validation failed' in result.output - - def test_validate_no_api_key(self, runner, mock_config): - """Test validating config without API key (warning)""" - mock_config.api_key = None - - result = runner.invoke(config, [ - 'validate' - ], obj={'config': mock_config, 'output_format': 'table'}) - - assert result.exit_code == 0 - assert 'valid with warnings' in result.output - - @patch.dict(os.environ, {'CLIENT_API_KEY': 'env_key_123'}) - def test_environments(self, runner, mock_config): - """Test listing environment variables""" - result = runner.invoke(config, [ - 'environments' - ], obj={'config': mock_config, 'output_format': 'table'}) - - assert result.exit_code == 0 - assert 'CLIENT_API_KEY' in result.output - def test_profiles_save(self, runner, mock_config, tmp_path): """Test saving a configuration profile""" # Patch Path.home to return tmp_path