docs: spec traceability for the locale/template/lint domain by JarbasAl · Pull Request #33 · OpenVoiceOS/ovos-spec-tools

JarbasAl · 2026-06-26T16:11:54Z

Makes the locale / template / dialog / prompt / language-matching / lint
domain of ovos-spec-tools exemplary for spec traceability: deepened docstrings,
complete type hints, and inline comments connecting every non-obvious decision
to a specific OVOS-INTENT clause.

Docs / typing / comments only — no runtime behaviour change. python -m pytest test/ stays green (327 passed).

What changed

expansion.py (OVOS-INTENT-1): cite §4.1 step 1 / §3.7 on
inline_keywords; flag its max_values cap and lenient unknown-reference
handling as deliberately non-spec.
resources.py (OVOS-INTENT-2): Args/Returns + § citations on the common
reader (§3), locale-dir discovery (§5/§2), keyword_form (§4.3) and the match
helpers (§4.3 whole-word occurrence); add the Iterator[...] return hint to
iter_locale_dirs.
dialog.py / prompt.py (§4.2 / §4.4): cite the three substitution
conditions and the fence heuristic.
language.py: module docstring traces the BCP-47 rules to INTENT-2 §2
(case-insensitive comparison) and §2.2 (fallback, threshold 10) and the
SESSION-1 lang family; the dialect-fallback ladder is documented precisely.
lint.py: clause map in the module docstring; per-finding § citations in
messages and comments, so a red lint points at the exact MUST.
docs: spec-coverage header per page; worked §4.1 expansion example;
dialect-fallback table; union-slot-set section.

Findings surfaced (documented, not changed)

.prompt HTML-comment stripping (OVOS-INTENT-2 §4.4) is unimplemented.
§4.4 requires  author comments be stripped before a prompt
reaches a model (a MUST), and an unterminated <!-- be reported.
read_prompt_file / render_prompt pass them through verbatim. Documented as
a known conformance gap in both modules and docs/dialog.md.
.intent union-slot relaxation. INTENT-1 §5.5 ("MUST reject" differing
slot sets) is relaxed to a warning for .intent to reconcile with the
multi-slot template-intent example in INTENT-3 §5.3. This is intentional; the
reasoning is now documented inline in lint.py and in docs/linting.md.

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Clarified and expanded spec guidance for dialogs, templates, prompts, language matching, locale resources, linting, and resource loading.
- Added more precise examples of slot handling, fallback behavior, and template expansion rules.
- Documented known conformance gaps and stricter validation expectations for locale files and prompts.
- Improved reference material for language detection, matching thresholds, and dialect fallback behavior.

Deepen docstrings, type hints and inline comments across the locale, template, dialog, prompt, language-matching and lint modules so every non-obvious decision cites the OVOS spec clause it implements. Docs, typing and comments only — no runtime behaviour change. - expansion.py (OVOS-INTENT-1): cite §4.1 step 1 / §3.7 on inline_keywords; flag its max_values cap and lenient unknown-ref handling as non-spec. - resources.py (OVOS-INTENT-2): Args/Returns + § citations on the common reader, locale-dir discovery, keyword_form and match helpers; add the Iterator return hint to iter_locale_dirs; note the §4.4 HTML-comment gap on read_prompt_file. - dialog.py / prompt.py (§4.2 / §4.4): cite the three substitution conditions and the fence heuristic; document the unimplemented §4.4 author-comment stripping as a known conformance gap, not a silent workaround. - language.py: module docstring now traces the BCP-47 rules to INTENT-2 §2 (case-insensitive) and §2.2 (fallback, threshold 10) and the SESSION-1 lang family; document the dialect-fallback ladder precisely. - lint.py: clause map in the module docstring; per-finding § citations in messages and comments; document the .intent union-slot relaxation that reconciles INTENT-1 §5.5 with INTENT-3 §5.3 (kept a warning by design). - docs: spec-coverage headers per page; worked §4.1 expansion example; dialect-fallback table; union-slot-set section; §4.4 prompt-comment gap. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

coderabbitai · 2026-06-26T16:12:02Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 32bc8323-cfa8-4a18-9a9d-957c861ea97c

📥 Commits

Reviewing files that changed from the base of the PR and between b0b2ab1 and 45bd1f4.

📒 Files selected for processing (10)

docs/dialog.md
docs/language-matching.md
docs/linting.md
docs/locale-resources.md
docs/templates.md
ovos_spec_tools/expansion.py
ovos_spec_tools/language.py
ovos_spec_tools/lint.py
ovos_spec_tools/prompt.py
ovos_spec_tools/resources.py

📝 Walkthrough

Walkthrough

The PR expands spec-facing documentation and docstrings across template rendering, language matching, locale resources, linting, and prompt handling. It clarifies rule coverage, fallback behavior, slot substitution, and documented conformance gaps.

Changes

Spec documentation alignment

Layer / File(s)	Summary
Template and prompt rules `docs/templates.md`, `docs/dialog.md`, `ovos_spec_tools/expansion.py`, `ovos_spec_tools/prompt.py`	Template grammar and prompt-rendering references add spec coverage, expansion steps, substitution conditions, and HTML-comment handling notes.
Language matching semantics `docs/language-matching.md`, `ovos_spec_tools/language.py`	Language-matching references add spec coverage, distance-threshold fallback rules, and docstrings for standardization, distance, matching, and closest-language selection.
Locale resource loading `docs/locale-resources.md`, `ovos_spec_tools/resources.py`	Locale-resource references add spec coverage for file parsing, locale discovery, override precedence, fallback, and helper normalization and matching behavior.
Lint rule references `docs/linting.md`, `ovos_spec_tools/lint.py`	Linting references map checks to OVOS clauses and expand documented handling of slot-set consistency, warnings, and CLI output.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

OpenVoiceOS/ovos-spec-tools#19: Updates the linting/spec docs around .intent union slot sets and .dialog slot-set consistency, which overlaps with the linting changes here.

Poem

I hop through docs with a carrot grin,
Where slots and tags all tuck right in.
The moonlight says, "Be clear, be kind!"
And tidy specs are easy to find. 🐇

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/spec-traceability-locale

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

github-actions · 2026-06-26T16:12:32Z

Greetings! I've analyzed your changes and have some results to share. 🖖

I've aggregated the results of the automated checks for this PR below.

📋 Repo Health

Scanning for any signs of 'large file' weight gain. ⚖️

✅ All required files present.

Latest Version: 0.12.0a1

✅ ovos_spec_tools/version.py — Version file
✅ README.md — README
✅ LICENSE.md — License file (consider renaming to LICENSE)
✅ pyproject.toml — pyproject.toml
⚠️ setup.py — setup.py
✅ CHANGELOG.md — Changelog
✅ ovos_spec_tools/version.py has valid version block markers

🔨 Build Tests

The build report has been filed and is ready. 📁

✅ All versions pass

Python	Build	Install	Tests
3.10	✅	✅	✅
3.11	✅	✅	✅
3.12	✅	✅	✅
3.13	✅	✅	✅
3.14	✅	✅	✅

🔒 Security (pip-audit)

I've audited the packages. Safety first! 🦺

✅ No known vulnerabilities found (32 packages scanned).

⚖️ License Check

Ensuring our legal documentation is accessible. 📖

✅ No license violations found.

Policy: Apache 2.0 (universal donor). StrongCopyleft / NetworkCopyleft / WeakCopyleft / Other / Error categories fail. MPL allowed.

📊 Coverage

Mapping out the 'known' vs 'unknown' in your code. 🗺️

✅ 96.9% total coverage

Full report: download the coverage-report artifact.

🏷️ Release Preview

I've checked the 'Performance Improvements' metrics. 📈

Current: 0.12.0a1 → Next: 0.12.0a2

Signal	Value
Label	(none)
PR title	`docs: spec traceability for the locale/template/lint domain`
Bump	alpha

✅ PR title follows conventional commit format.

🚀 Release Channel Compatibility

Predicted next version: 0.12.0a2

Channel	Status	Note	Current Constraint
Stable	⚪	Not in channel	-
Testing	⚪	Not in channel	-
Alpha	✅	Compatible	`ovos-spec-tools>=0.11.0a1`

🔍 Lint

I've performed a routine sweep of your changes. 🧹

❌ ruff: issues found — see job log

Built by scripts, maintained by community 🤝

JarbasAl marked this pull request as ready for review June 26, 2026 16:16

JarbasAl merged commit 403c48e into dev Jun 26, 2026
14 checks passed

JarbasAl deleted the docs/spec-traceability-locale branch June 27, 2026 20:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: spec traceability for the locale/template/lint domain#33

docs: spec traceability for the locale/template/lint domain#33
JarbasAl merged 1 commit into
devfrom
docs/spec-traceability-locale

JarbasAl commented Jun 26, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 26, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

github-actions Bot commented Jun 26, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

JarbasAl commented Jun 26, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changed

Findings surfaced (documented, not changed)

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Poem

Uh oh!

github-actions Bot commented Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greetings! I've analyzed your changes and have some results to share. 🖖

📋 Repo Health

🔨 Build Tests

🔒 Security (pip-audit)

⚖️ License Check

📊 Coverage

🏷️ Release Preview

🔍 Lint

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

JarbasAl commented Jun 26, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 26, 2026 •

edited

Loading

github-actions Bot commented Jun 26, 2026 •

edited

Loading