Skip to content

Add --help-full flag for complete recursive CLI documentation#756

Draft
kitlangton wants to merge 1 commit intomainfrom
feat/cli-help-full-flag
Draft

Add --help-full flag for complete recursive CLI documentation#756
kitlangton wants to merge 1 commit intomainfrom
feat/cli-help-full-flag

Conversation

@kitlangton
Copy link
Contributor

@kitlangton kitlangton commented Nov 25, 2025

Summary

  • Add --help-full flag that generates complete recursive help for LLM/agent consumption
  • Output shows compact tree overview with box-drawing characters followed by flat command reference
  • Commands included if they have: own flags, args, description, or are leaf commands

Example Output

mycli - A comprehensive CLI tool

Tree:
  mycli
  ├─■ admin
  │   ├─■ users
  │   │   ├─■ list
  │   │   └─■ create
  │   └─■ config
  └─■ copy

Commands
--------

mycli
  A comprehensive CLI tool
  Flags:
    -d, --debug          [boolean]  Enable debug logging

mycli admin users list
  List all users
  Flags:
    --format             [string] (required)  Output format

Test plan

  • Added inline snapshot tests for root and subcommand --help-full
  • All 106 CLI tests pass
  • Type checks pass

@kitlangton
Add --help-full flag for complete recursive CLI documentation
53b2c32 
- Add helpFullFlag to built-in flags
- Wire up extraction in parser
- Generate compact tree overview + flat command reference
- Include commands with flags, args, description, or leaf status
- Skip pure namespace commands without content
@github-actions
Copy link
Contributor

github-actions bot commented Nov 25, 2025

Bundle Size Analysis

File Name Current Size Previous Size Difference
bundle/basic.ts 6.12 KB 6.12 KB 0.00 KB (0.00%)
bundle/batching.ts 8.37 KB 8.37 KB 0.00 KB (0.00%)
bundle/brand.ts 6.32 KB 6.32 KB 0.00 KB (0.00%)
bundle/cache.ts 9.44 KB 9.44 KB 0.00 KB (0.00%)
bundle/config.ts 16.18 KB 16.18 KB 0.00 KB (0.00%)
bundle/differ.ts 14.03 KB 14.03 KB 0.00 KB (0.00%)
bundle/http-client.ts 18.42 KB 18.42 KB 0.00 KB (0.00%)
bundle/logger.ts 8.57 KB 8.57 KB 0.00 KB (0.00%)
bundle/metric.ts 8.60 KB 8.60 KB 0.00 KB (0.00%)
bundle/optic.ts 7.58 KB 7.58 KB 0.00 KB (0.00%)
bundle/pubsub.ts 12.94 KB 12.94 KB 0.00 KB (0.00%)
bundle/queue.ts 10.85 KB 10.85 KB 0.00 KB (0.00%)
bundle/schedule.ts 9.29 KB 9.29 KB 0.00 KB (0.00%)
bundle/schema-arbitrary.ts 16.17 KB 16.17 KB 0.00 KB (0.00%)
bundle/schema-equivalence.ts 15.30 KB 15.30 KB 0.00 KB (0.00%)
bundle/schema-formatter.ts 15.25 KB 15.25 KB 0.00 KB (0.00%)
bundle/schema-json-schema.ts 16.50 KB 16.50 KB 0.00 KB (0.00%)
bundle/schema-record-literals-key.ts 13.65 KB 13.65 KB 0.00 KB (0.00%)
bundle/schema-string-async.ts 11.17 KB 11.17 KB 0.00 KB (0.00%)
bundle/schema-string-check.ts 9.94 KB 9.94 KB 0.00 KB (0.00%)
bundle/schema-string.ts 9.52 KB 9.52 KB 0.00 KB (0.00%)
bundle/schema-template-literal.ts 12.07 KB 12.07 KB 0.00 KB (0.00%)
bundle/schema-toSerializerStringTree.ts 15.06 KB 15.06 KB 0.00 KB (0.00%)
bundle/schema.ts 14.78 KB 14.78 KB 0.00 KB (0.00%)
bundle/stm.ts 11.68 KB 11.68 KB 0.00 KB (0.00%)
bundle/stream.ts 8.30 KB 8.30 KB 0.00 KB (0.00%)

@github-actions
Copy link
Contributor

github-actions bot commented Nov 25, 2025

📊 JSDoc Documentation Analysis

📈 Current Analysis Results 
Analyzing 64 TypeScript files in packages/effect/src/ (including schema and config subdirectories)...

============================================================
         EFFECT JSDOC ANALYSIS REPORT
============================================================

📊 SUMMARY STATISTICS
------------------------------
Total files analyzed: 64
Total exported members: 2146
Missing @example: 1021 (47.6%)
Missing @category: 344 (16.0%)

🎯 TOP FILES NEEDING ATTENTION
----------------------------------------
1. schema/Schema.ts
   📝 421 missing examples, 🏷️  241 missing categories
   📦 421 total exports
2. schema/AST.ts
   📝 71 missing examples, 🏷️  13 missing categories
   📦 71 total exports
3. schema/Annotations.ts
   📝 38 missing examples, 🏷️  26 missing categories
   📦 38 total exports
4. schema/Getter.ts
   📝 52 missing examples, 🏷️  1 missing categories
   📦 52 total exports
5. schema/Transformation.ts
   📝 28 missing examples, 🏷️  17 missing categories
   📦 28 total exports
6. PubSub.ts
   📝 25 missing examples, 🏷️  16 missing categories
   📦 37 total exports
7. Config.ts
   📝 33 missing examples, 🏷️  5 missing categories
   📦 33 total exports
8. Cause.ts
   📝 28 missing examples, 🏷️  2 missing categories
   📦 69 total exports
9. Effect.ts
   📝 24 missing examples, 🏷️  1 missing categories
   📦 227 total exports
10. SynchronizedRef.ts
   📝 24 missing examples, 🏷️  0 missing categories
   📦 24 total exports
11. schema/Issue.ts
   📝 22 missing examples, 🏷️  2 missing categories
   📦 22 total exports
12. schema/Parser.ts
   📝 24 missing examples, 🏷️  0 missing categories
   📦 24 total exports
13. ConfigProvider.ts
   📝 21 missing examples, 🏷️  1 missing categories
   📦 21 total exports
14. DateTime.ts
   📝 20 missing examples, 🏷️  0 missing categories
   📦 108 total exports
15. Optic.ts
   📝 18 missing examples, 🏷️  0 missing categories
   📦 18 total exports

✅ PERFECTLY DOCUMENTED FILES
-----------------------------------
   Clock.ts (5 exports)
   Console.ts (21 exports)
   FiberHandle.ts (15 exports)
   FiberMap.ts (19 exports)
   FiberSet.ts (14 exports)
   Match.ts (57 exports)
   MutableRef.ts (17 exports)
   Random.ts (7 exports)
   RcRef.ts (5 exports)
   RegExp.ts (3 exports)
   Runtime.ts (3 exports)
   Schedule.ts (49 exports)
   Symbol.ts (1 exports)
   index.ts (0 exports)
   schema/index.ts (0 exports)

🔍 SAMPLE MISSING ITEMS FROM schema/Schema.ts
-----------------------------------
   Optionality (type, line 53): missing example, category
   Mutability (type, line 60): missing example, category
   ConstructorDefault (type, line 67): missing example, category
   MakeOptions (interface, line 75): missing example, category
   Bottom (interface, line 99): missing example, category
   declareConstructor (interface, line 179): missing example, category
   declareConstructor (function, line 203): missing example
   declare (interface, line 227): missing example
   declare (function, line 236): missing example, category
   revealBottom (function, line 256): missing example, category

📋 BREAKDOWN BY EXPORT TYPE
-----------------------------------
type: 112 missing examples, 58 missing categories
const: 388 missing examples, 100 missing categories
interface: 191 missing examples, 122 missing categories
class: 54 missing examples, 3 missing categories
function: 248 missing examples, 46 missing categories
namespace: 28 missing examples, 15 missing categories

📈 DOCUMENTATION PROGRESS
------------------------------
Examples: 1125/2146 (52.4% complete)
Categories: 1802/2146 (84.0% complete)

============================================================
Analysis complete! 1365 items need attention.
============================================================

📄 Detailed results saved to: jsdoc-analysis-results.json

This comment is automatically updated on each push. View the analysis script for details.

@AMar4enko
Copy link

AMar4enko commented Dec 5, 2025 •
edited
Loading

This is sLick!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@kitlangton @AMar4enko