feat(uko): add analyzer plugin framework and initial domain analyzers #597

2026-03-05T05:36:54Z

freemo commented

2026-03-05 05:36:54 +00:00

Summary

Implements the UKO analyzer plugin framework and two initial domain analyzers per issue #551.

Changes

New Files (9 created, 1 modified)

Core framework (src/cleveragents/domain/models/acms/):

analyzers.py (219 lines) — UKOTriple (frozen Pydantic v2 model), AnalyzerProtocol (@runtime_checkable Protocol), AnalyzerRegistry (extension-to-analyzer mapping with register/lookup/list)
python_analyzer.py (365 lines) — AST-based Python source analyzer extracting modules, classes, functions, methods, imports, docstrings, base-class inheritance into UKO triples
markdown_analyzer.py (275 lines) — Line-by-line regex parser extracting document declarations, sections (heading hierarchy), fenced code blocks (with language), and links into UKO triples
__init__.py — Updated with new exports

Tests:

features/uko_analyzers.feature (193 lines) — 39 Behave scenarios covering UKOTriple model, AnalyzerRegistry, PythonAnalyzer, MarkdownAnalyzer
features/steps/uko_analyzers_steps.py (468 lines) — Step definitions
robot/uko_analyzers.robot (65 lines) — 7 Robot Framework integration tests
robot/helper_uko_analyzers.py (241 lines) — Robot helper script

Benchmarks:

benchmarks/uko_analyzers_bench.py (157 lines) — ASV benchmarks for triple construction, registry ops, analyzer performance

Verification

nox -s lint — All checks passed
nox -s format — 1076 files unchanged
nox -s typecheck — 0 errors, 0 warnings (Pyright strict mode)
nox -s unit_tests -- features/uko_analyzers.feature — 1 feature, 39 scenarios, 103 steps passed
Robot integration tests — 7/7 passed

Design Decisions

Properties over methods: supported_extensions and domain are @property on AnalyzerProtocol, matching the project's protocol patterns
First-registered-wins: AnalyzerRegistry keeps the first analyzer registered for each extension rather than overwriting
Graceful degradation: PythonAnalyzer returns empty list on SyntaxError instead of raising
No external deps: MarkdownAnalyzer uses line-by-line regex (no markdown library), PythonAnalyzer uses stdlib ast
URI scheme: Follows uko:// hierarchy — uko://code/module/, uko://code/class/, uko://docs/document/, uko://docs/section/

ISSUES CLOSED: #551

## Summary Implements the UKO analyzer plugin framework and two initial domain analyzers per issue #551. ## Changes ### New Files (9 created, 1 modified) **Core framework** (`src/cleveragents/domain/models/acms/`): - `analyzers.py` (219 lines) — `UKOTriple` (frozen Pydantic v2 model), `AnalyzerProtocol` (`@runtime_checkable` Protocol), `AnalyzerRegistry` (extension-to-analyzer mapping with register/lookup/list) - `python_analyzer.py` (365 lines) — AST-based Python source analyzer extracting modules, classes, functions, methods, imports, docstrings, base-class inheritance into UKO triples - `markdown_analyzer.py` (275 lines) — Line-by-line regex parser extracting document declarations, sections (heading hierarchy), fenced code blocks (with language), and links into UKO triples - `__init__.py` — Updated with new exports **Tests**: - `features/uko_analyzers.feature` (193 lines) — 39 Behave scenarios covering UKOTriple model, AnalyzerRegistry, PythonAnalyzer, MarkdownAnalyzer - `features/steps/uko_analyzers_steps.py` (468 lines) — Step definitions - `robot/uko_analyzers.robot` (65 lines) — 7 Robot Framework integration tests - `robot/helper_uko_analyzers.py` (241 lines) — Robot helper script **Benchmarks**: - `benchmarks/uko_analyzers_bench.py` (157 lines) — ASV benchmarks for triple construction, registry ops, analyzer performance ## Verification - `nox -s lint` — All checks passed - `nox -s format` — 1076 files unchanged - `nox -s typecheck` — 0 errors, 0 warnings (Pyright strict mode) - `nox -s unit_tests -- features/uko_analyzers.feature` — 1 feature, 39 scenarios, 103 steps passed - Robot integration tests — 7/7 passed ## Design Decisions - **Properties over methods**: `supported_extensions` and `domain` are `@property` on `AnalyzerProtocol`, matching the project's protocol patterns - **First-registered-wins**: `AnalyzerRegistry` keeps the first analyzer registered for each extension rather than overwriting - **Graceful degradation**: `PythonAnalyzer` returns empty list on `SyntaxError` instead of raising - **No external deps**: `MarkdownAnalyzer` uses line-by-line regex (no markdown library), `PythonAnalyzer` uses stdlib `ast` - **URI scheme**: Follows `uko://` hierarchy — `uko://code/module/`, `uko://code/class/`, `uko://docs/document/`, `uko://docs/section/` ISSUES CLOSED: #551

freemo referenced this pull request

2026-03-05 06:50:13 +00:00

feat(uko): add analyzer plugin framework and initial domain analyzers (Python, Markdown) #551

freemo force-pushed feature/m6-uko-analyzers from 4039162cac to 7f02e571d4

2026-03-05 16:13:43 +00:00

Compare

freemo force-pushed feature/m6-uko-analyzers from 7f02e571d4 to 39aa737a82

2026-03-05 16:19:28 +00:00

Compare

freemo force-pushed feature/m6-uko-analyzers from 39aa737a82 to d990fc1b41

2026-03-05 19:20:41 +00:00

Compare

freemo scheduled this pull request to auto merge when all checks succeed 2026-03-05 19:20:50 +00:00

freemo merged commit d990fc1b41 into master

2026-03-05 19:25:45 +00:00

freemo deleted branch feature/m6-uko-analyzers

2026-03-05 19:25:46 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: cleveragents/cleveragents-core#597