Merged
Conversation
…odebase and to addition of utility error handling and missing type hints.
…dme_for_comparison(), normalize_dry_run_output() to fix errors in test_quick_comparison.py
…on for smart cli detection enabled by default - Implement tests for DependenciesDecisionRule, GraphDecisionRule, and MinimalModeRule to ensure correct decision-making based on role complexity and dependencies. - Create CLI integration tests to verify smart defaults behavior for different role types, including user overrides and environment variable impacts. - Develop integration tests for SmartDefaultsEngine to validate the complete pipeline from role detection to configuration generation, ensuring user overrides are respected. - Enhance structure detection tests to cover various role structures, including detection of handlers, meta, defaults, templates, and files directories, as well as accurate counting of task files. - Ensure all tests validate the expected outcomes and decision rationales, contributing to a robust testing framework for the decision-making logic in the application.
…tion
Implements the complete severity-based output system
with CRITICAL/WARNING/INFO levels for prioritized role analysis.
Core Models:
- Add Severity enum with icons, labels, and priority ordering
- Enhance Recommendation model with severity field and location property
- Add confidence scoring and auto-fixable metadata
Recommendation Generators:
- SecurityRecommendationGenerator (CRITICAL): vault encryption, exposed secrets, unsafe permissions
- QualityRecommendationGenerator (WARNING): complex roles, undocumented variables
- EnhancementRecommendationGenerator (INFO): missing examples, missing tests
- Aggregate function sorts by severity priority (critical first)
Output Formatting:
- RecommendationFormatter groups by severity with emoji icons (🔴🟡💡)
- Shows location (file:line) and remediation steps when available
- Sorts within severity by confidence score
- Summary section with counts per severity level
CLI Integration:
- Add --show-info flag to display INFO-level recommendations (hidden by default)
- Add --recommendations-only flag to analyze without generating documentation
- Integrate with RoleOrchestrator for seamless workflow
- Parameters flow through core.py → orchestrated.py → context models
Testing:
- 11 comprehensive formatter tests with realistic pytest fixtures
- 2 end-to-end CLI tests for critical output and INFO filtering
- Fixtures match actual security/quality/enhancement generator outputs
- All 13 tests passing with 100% coverage of severity logic
Fixes:
- Vault encryption check now examines first line only (no false positives)
- Secret detection checks both var and msg fields with detailed output
- Proper type safety with ComplexityCategory enum usage
- Fixed line_number to use None for non-specific locations
Files Modified:
- docsible/models/severity.py (new)
- docsible/models/recommendation.py (enhanced)
- docsible/analyzers/recommendations/{__init__,security,quality,enhancement}.py
- docsible/formatters/recommendation_formatter.py (new)
- docsible/commands/document_role/{__init__,core,core_orchestrated,options/recommendations}.py
- docsible/commands/document_role/models/role_command_context.py
- docsible/commands/document_role/orchestrators/role_orchestrator.py
- tests/formatters/test_recommendation_formatter.py (11 tests)
- tests/end_to_end/test_severity_output.py (2 tests)
…ent branch for now focus on UX improvements. Next step is Progressive help UI implementation.
…paring for phase3 intent-based-cli
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This branch transforms Docsible from a parameter-driven CLI into an intent-based, user-friendly tool. It delivers 5 major UX improvements across the full stack, from CLI surface to output formatting, along with a complete suppression system and a preset/wizard onboarding flow.
What Was Built
1. Severity-Based Output
Recommendations are now grouped and prioritized as
CRITICAL,WARNING, orINFOinstead of a flat undifferentiated list. Each recommendation includes a remediation step. Low-severity items are hidden by default (--show-infoto reveal).2. Positive Output Framing
Success output leads with what went well before surfacing issues. Missing items are reframed as "enhancement opportunities" with time estimates and difficulty tags. A
MessageTransformerconverts negative phrasing to constructive language.3. Progressive Help
docsible role --helpnow shows a concise brief view (essential options only).--help-fullreveals all options. An interactive guide system (docsible guide getting-started) was added for new users.4. Suppression System
Users can silence known false positives with persistent rules stored in
.docsible/suppress.yml:docsible suppress add "pattern" --reason "..." --expires 90docsible suppress list / remove <id> / clean5. Intent-Based CLI + Presets (Phase 3)
The CLI is restructured around user intent rather than implementation flags:
New Command | Purpose -- | -- docsible init | Interactive 3-step wizard (use case → smart defaults → CI/CD setup for GitHub Actions, GitLab CI, Azure DevOps) docsible document role [--role PATH] [--preset ...] | Generate documentation docsible analyze role | Analysis-only mode with complexity report docsible validate role | Dry-run validation with strict modeFour built-in presets:
personal,team,enterprise,consultant. Preset settings resolve with 3-level priority: preset defaults <.docsible/config.ymloverrides < explicit CLI flags.The legacy
docsible role --role PATHstill works with a deprecation warning — fully backward compatible.Quality
UX_IMPROVEMENTS_ROADMAP.md— all phases marked completeFOLDER_REORGANIZATION_REPORT.md— written as input for the next branch