Skip to content

Improve raw-source inspector: file_tree should explain the directory layout #110

Description

@abegong

Context

The first command many users will run is katalyst inspect ., which runs the raw-source inspectors over the current directory. Today file_tree renders through the generic classes / outliers summarizer, which makes shallow directory evidence feel abstract and ungrounded.

For small directories especially, there is no reason to hide the actual tree. The output should help both humans and AI agents see that Katalyst has understood the directory layout.

Goal

Make file_tree answer, at a glance:

  • What files and directories are present?
  • What are the major regions of the tree?
  • Is this a very small tree where we should simply show the structure directly?
  • Which directory-level naming and extension conventions are visible?
  • Which directories/files break the obvious pattern, if any?

Possible shape

For short targets, render a compact tree before any summarization. For larger targets, render a concise directory overview: top-level directories, counts by extension, and representative paths.

Use outliers only when they tell a clear story about layout or naming, not as the primary structure.

Acceptance criteria

  • katalyst inspect . --inspector file_tree produces a coherent human-readable section for shallow filesystem structure.
  • Small directories show an actual tree or tree-like listing instead of only classes / outliers.
  • Larger directories summarize top-level regions and file type/name conventions without overwhelming the report.
  • The section includes enough concrete paths for an AI reader to ground follow-up reasoning.
  • Existing JSON output remains complete and parseable; any schema changes are intentional and covered by tests.
  • Snapshot tests cover at least one tiny directory and one directory large enough to require summarization.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions