【bug】Skipping invalid sub leaf node not found in components

[Adcbda]

Bug Report: Module Clustering Generates Warnings and Produces Incomplete Module Tree

Description

When running codewiki generate with the --no-cache flag, the Module Clustering phase generates multiple warnings about invalid sub leaf nodes not found in components. As a result, the final output only generates a single-level directory structure instead of the expected hierarchical module tree. Can not reproduce your online demo: https://fsoft-ai4code.github.io/codewiki-demo/viewer.html?project=FluentValidation--FluentValidation-docs

Steps to Reproduce

1. Install CodeWiki CLI tool and apply my config

codewiki config show

CodeWiki Configuration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Credentials
  API Key:          sk-F...6tOw (in encrypted file)

API Settings
  Base URL:         http://myip/v1
  Main Model:       glm-5
  Cluster Model:    glm-5
  Fallback Model:   glm-5
  Provider:         openai-compatible

Output Settings
  Default Output:   docs

Token Settings
  Max Tokens:              32768
  Max Token/Module:        36369
  Max Token/Leaf Module:   16000

Decomposition Settings
  Max Depth:               2

Agent Instructions
  Using defaults (no custom settings)

3. Clone a .NET repository (e.g., FluentValidation)

git clone https://github.com/FluentValidation/FluentValidation.git

5. Run the following command:

cd FluentValidation
codewiki generate -o ./documents --no-cache --verbose

Expected Behavior

• The Module Clustering phase should successfully cluster components into a hierarchical module tree
• All components identified by the LLM should be present in the components dictionary
• The generated documentation should contain multi-level module structure like your live demo: https://fsoft-ai4code.github.io/codewiki-demo/viewer.html?project=FluentValidation--FluentValidation-docs

Actual Behavior

• Multiple warnings are logged during the Module Clustering phase:

codewiki generate -o ./documents --no-cache --verbose
[1/4] Validating configuration...
✓ Configuration valid
[2/4] Validating repository...
✓ Repository valid: FluentValidation
[10:23:31] Detected languages: C# (217 files), Python (1 files)
✓ Output directory: /home/pc/project/CodeWiki-wsl/myrepo/FluentValidation/documents
[4/4] Generating documentation...

[10:23:31] Max tokens: 32768
[10:23:31] Max token/module: 36369
[10:23:31] Max token/leaf module: 16000
[10:23:31] Max depth: 2

[00:00] Phase 1/5: Dependency Analysis
[00:00]   Initializing dependency analyzer...
[00:00]   Parsing source files...
[10:23:32] INFO     📊 Parsing 218 source files (this may take a few minutes)...
[10:23:32] INFO       [1/218] docs/conf.py (0.0s elapsed, ~0.0s remaining)
[10:23:32] INFO       [2/218] src/CommonAssemblyInfo.cs (0.0s elapsed, ~0.3s remaining)
[10:23:32] INFO       [3/218] src/FluentValidation/AbstractValidator.cs (0.0s elapsed, ~0.7s remaining)    
[10:23:32] INFO       [4/218] src/FluentValidation/AssemblyInfo.FluentValidation.cs (0.0s elapsed, ~1.6s remaining)
[10:23:32] INFO       [5/218] src/FluentValidation/AssemblyScanner.cs (0.0s elapsed, ~1.3s remaining)      
[10:23:32] INFO       [21/218] src/FluentValidation/Internal/CollectionPropertyRule.cs (0.1s elapsed, ~1.2s remaining)
[10:23:32] INFO       [42/218] src/FluentValidation/Resources/ILanguageManager.cs (0.2s elapsed, ~0.9s remaining)
[10:23:32] INFO       [63/218] src/FluentValidation/Resources/Languages/GreekLanguage.cs (0.3s elapsed, ~0.6s remaining)
[10:23:32] INFO       [84/218] src/FluentValidation/Resources/Languages/RomanshLanguage.cs (0.3s elapsed, ~0.5s remaining)
[10:23:32] INFO       [105/218] src/FluentValidation/TestHelper/ITestValidationContinuation.cs (0.3s elapsed, ~0.4s remaining)
[10:23:32] INFO       [126/218] src/FluentValidation/Validators/IPropertyValidator.cs (0.4s elapsed, ~0.3s remaining)
[10:23:32] INFO       [147/218] src/FluentValidation.Tests/AssemblyScannerTester.cs (0.5s elapsed, ~0.2s remaining)
[10:23:32] INFO       [168/218] src/FluentValidation.Tests/ForEachRuleTests.cs (0.7s elapsed, ~0.2s remaining)
[10:23:32] INFO       [189/218] src/FluentValidation.Tests/Person.cs (0.9s elapsed, ~0.1s remaining)
[10:23:33] INFO       [210/218] src/FluentValidation.Tests/ValidatorSelectorTests.cs (1.1s elapsed, ~0.0s remaining)
[10:23:33] INFO     ✓ Analysis complete: 218/218 files analyzed, 0 failed, 398 functions, 999 relationships (1.2s)
[00:01]   Analyzed 398 files, found 355 leaf nodes
[00:01]     File: docs/conf.py::setup
[00:01]     File: src/FluentValidation.DependencyInjectionExtensions/ServiceCollectionExtensions.cs::ServiceCollectionExtensions
[00:01]     File: src/FluentValidation.DependencyInjectionExtensions/ServiceProviderValidatorFactory.cs::ServiceProviderValidatorFactory
[00:01]     File: src/FluentValidation.Tests.Benchmarks/AccessorCacheBenchmark.cs::AccessorCacheBenchmark  
[00:01]     File: src/FluentValidation.Tests.Benchmarks/EngineOnlyBenchmark.cs::EngineOnlyBenchmark
[00:01]     File: src/FluentValidation.Tests.Benchmarks/EngineOnlyBenchmark.cs::NoLogicModelSingleRuleValidator
[00:01]     File: src/FluentValidation.Tests.Benchmarks/EngineOnlyBenchmark.cs::NoLogicModelTenRulesValidator
[00:01]     File: src/FluentValidation.Tests.Benchmarks/EngineOnlyBenchmark.cs::VoidModel
[00:01]     File: src/FluentValidation.Tests.Benchmarks/InitializationBenchmark.cs::InitializationBenchmark
[00:01]     File: src/FluentValidation.Tests.Benchmarks/Models.cs::FullModel
[00:01]     File: src/FluentValidation.Tests.Benchmarks/Models.cs::FullModelValidator
[00:01]     File: src/FluentValidation.Tests.Benchmarks/Models.cs::NestedModel
[00:01]     File: src/FluentValidation.Tests.Benchmarks/Models.cs::NestedModelValidator
[00:01]     File: src/FluentValidation.Tests.Benchmarks/Program.cs::Program
[00:01]     File: src/FluentValidation.Tests.Benchmarks/ValidationBenchmark.cs::ValidationBenchmark
[00:01]     File: src/FluentValidation.Tests/AbstractValidatorTester.cs::AbstractValidatorTester
[00:01]     File: src/FluentValidation.Tests/AbstractValidatorTester.cs::DerivedPerson
[00:01]     File: src/FluentValidation.Tests/AccessorCacheTests.cs::AccessorCacheTests
[00:01]     ... and 378 more files
[00:01]   Dependency Analysis complete (1.4s)

[00:01] Phase 2/5: Module Clustering
[00:01]   Clustering modules with LLM...
[00:01]   Clustering 355 leaf nodes with LLM...
[10:25:25] WARNING  Skipping invalid sub leaf node 'IValidator' in module 'Core' - not found in components
[10:25:25] WARNING  Skipping invalid sub leaf node 'IValidatorFactory' in module 'Core' - not found in components
[10:25:25] WARNING  Skipping invalid sub leaf node 'IValidatorDescriptor' in module 'Core' - not found in components
[10:25:25] WARNING  Skipping invalid sub leaf node 'IValidationRule' in module 'Core' - not found in components
[10:25:25] WARNING  Skipping invalid sub leaf node 'IValidationRuleInternal' in module 'Core' - not found in components
[10:25:25] WARNING  Skipping invalid sub leaf node 'ICollectionRule' in module 'Core' - not found in components
[10:25:25] WARNING  Skipping invalid sub leaf node 'ValidationContext' in module 'Core' - not found in components
  ...

[01:53]   Created 6 modules
[01:53]     Module: Core (? files)
[01:53]     Module: DependencyInjection (? files)
[01:53]     Module: Localization (? files)
[01:53]     Module: Results (? files)
[01:53]     Module: TestHelper (? files)
[01:53]     Module: Validators (? files)
[01:53]   Module Clustering complete (111.8s)

• The generated documentation only contains a single-level directory

Output result

[3/5] Documentation Generation
Warning: IPython is not installed. Mermaidjs magic function is not available.

✓ Documentation generated successfully!

Output directory:
  /home/pc/project/CodeWiki-wsl/myrepo/FluentValidation/documents

Generated files:
  - Internal Engine.md
  - Test Helpers.md
  - overview.md
  - module_tree.json
  - Built-in Validators.md
  - Localization.md
  - Validation Results.md
  - Dependency Injection Extensions.md
  - first_module_tree.json
  - Core Abstractions.md
  ... and 1 more

Statistics:
  Total modules:     7
  Files analyzed:    398
  Generation time:   33 minutes 6 seconds

Next steps:

1. Review the generated documentation:
   cat /home/pc/project/CodeWiki-wsl/myrepo/FluentValidation/documents/overview.md

2. Commit the documentation:
   git add docs/
   git commit -m "Add generated documentation"

3. Push to GitHub:
   git push origin main

4. Enable GitHub Pages:
   - Go to repository Settings → Pages
   - Source: Deploy from a branch
   - Branch: main, folder: /docs

5. Your documentation will be available at:
   https://FluentValidation.github.io/FluentValidation/

dependency_graph.json

{
  "docs/conf.py::setup": {
    "id": "docs/conf.py::setup",
    "name": "setup",
    "component_type": "function",
    "file_path": "/home/pc/project/CodeWiki-wsl/myrepo/FluentValidation/docs/conf.py",
    "relative_path": "docs/conf.py",
    "depends_on": [],
    "source_code": "def setup(app):\n    app.add_config_value('recommonmark_config', {\n            'enable_eval_rst': True,\n            #'url_resolver': lambda url: github_doc_root + url,\n            #'auto_toc_tree_section': 'Contents',\n            }, True)\n    app.add_transform(AutoStructify)",
    "start_line": 180,
    "end_line": 186,
    "has_docstring": false,
    "docstring": "",
    "parameters": [
      "app"
    ],
    "node_type": "function",
    "base_classes": null,
    "class_name": null,
    "display_name": "function setup",
    "component_id": "docs/conf.py::setup"
  },
  "src/FluentValidation/AbstractValidator.cs::AbstractValidator": {
    "id": "src/FluentValidation/AbstractValidator.cs::AbstractValidator",
    "name": "AbstractValidator",
    "component_type": "abstract class",
    "file_path": "/home/pc/project/CodeWiki-wsl/myrepo/FluentValidation/src/FluentValidation/AbstractValidator.cs",
    "relative_path": "src/FluentValidation/AbstractValidator.cs",
    "depends_on": [
      "src/FluentValidation/Enums.cs::CascadeMode",
      "src/FluentValidation/IValidationContext.cs::IValidationContext",
      "src/FluentValidation/Results/ValidationResult.cs::ValidationResult"
    ],
    "source_code"
...

module_tree.json

{
    "Core Abstractions": {
        "path": "src/FluentValidation",
        "components": [
            "AssemblyScanner",
            "AssemblyScanResult",
            "ICollectionRule",
            "IValidationContext",
            "IHasFailures",
            "ValidationContext",
            "IValidationRule",
            "IValidationRuleInternal",
            "IValidator",
            "IValidatorDescriptor",
            "IValidatorFactory",
            "InlineValidator",
            "ValidatorDescriptor",
            "RulesetMetadata",
            "ValidatorConfiguration",
            "ValidatorSelectorOptions",
            "IRuleBuilderInitial",
            "IRuleBuilderOptions",
            "IRuleBuilderOptionsConditions",
            "IRuleBuilder",
            "IRuleBuilderInternal",
            "IRuleBuilderInitialCollection",
            "IConditionBuilder"
        ],
        "children": {}
    },
    "Internal Engine": {
        "path": "src/FluentValidation/Internal",
        "components": [
            "Key",
            "ChildRulesContainer",
            "CollectionPropertyRule",
            "CompositeValidatorSelector",
            "ConditionBuilder",
            "ConditionOtherwiseBuilder",
            "AsyncConditionBuilder",
            "AsyncConditionOtherwiseBuilder",
            "DefaultValidatorSelector",
            "IRuleComponent",
            "IValidatorSelector",
            "IIncludeRule",
            "IncludeRule",
            "MemberNameValidatorSelector",
            "IMessageBuilderContext",
            "MessageBuilderContext",
            "MessageFormatter",
            "PropertyChain",
            "PropertyRule",
            "RuleBuilder",
            "RuleComponent",
            "RuleComponentForNullableStruct",
            "RulesetValidatorSelector",
            "TrackingCollection",
            "CaptureDisposable",
            "EventDisposable",
            "ValidationStrategy"
        ],
        "children": {}
    },
...

Environment

• OS: Linux (WSL)
• Python: 3.12.3
• CodeWiki version: 1.0.1
• Target repository: https://github.com/FluentValidation/FluentValidation

[anhnh2002]

Hi @Adcbda, thanks for the detailed report.

What's happening

In CodeWiki, components are keyed internally by their full ID, e.g. src/FluentValidation/IValidator.cs::IValidator (path + :: + name). During the Module Clustering phase, the prompt feeds the cluster LLM these full IDs and expects them to be echoed back verbatim in the "components" arrays of the grouped output.

Looking at your module_tree.json, the cluster model returned bare class names instead:

"Core Abstractions": {
    "components": ["AssemblyScanner", "IValidator", "IValidatorFactory", ...]
}

These bare names don't match any key in our internal components dict, so they get filtered out with the Skipping invalid sub leaf node ... not found in components warning. With every component dropped, the recursive sub-clustering call receives an empty list and bails out → you end up with a single-level tree and no nested children. That fully explains the flat output you're seeing.

Why it works in our demo but not for you

The published FluentValidation demo was generated with a stronger cluster model that reliably preserves the full path::name format. From your config, you're using glm-5 for all three roles (main / cluster / fallback). Smaller/local models tend to "simplify" the IDs back to bare names, which breaks the clustering contract.

Recommendation

The clustering step is the most format-sensitive part of the pipeline — it only runs once per repo but its output shapes the entire documentation tree. We strongly recommend using a strong model for cluster_model (e.g. Claude Sonnet/Opus, GPT-4-class, or similar), and you can safely use cheaper models for main_model and fallback_model to keep costs down:

codewiki config set cluster-model <strong-model>
codewiki config set main-model <cheaper-model>
codewiki config set fallback-model <cheaper-model>

Once you switch the cluster model, please re-run with --no-cache and you should get the proper hierarchical tree like in the demo. We'll also look into making the clustering step more robust to bare-name responses on our side so weaker models degrade more gracefully. Thanks again for the report! 🚀