refactor(analyze-includes): revert toctree support

Author: cbullinger

audit-cli/README.md

@@ -59,7 +59,7 @@ audit-cli
 │   └── find-string
 ├── analyze          # Analyze RST file structures
 │   ├── includes
-│   └── references
+│   └── file-references
 └── compare          # Compare files across versions
     └── file-contents
 ```
@@ -223,9 +223,9 @@ With `-v` flag, also shows:
 
 #### `analyze includes`
 
-Analyze `include` directive and `toctree` relationships in RST files to understand file dependencies.
+Analyze `include` directive relationships in RST files to understand file dependencies.
 
-This command recursively follows both `.. include::` directives and `.. toctree::` entries to show all files that are referenced from a starting file. This provides a complete picture of file dependencies including both content includes and table of contents structure.
+This command recursively follows `.. include::` directives to show all files that are referenced from a starting file. This helps you understand which content is transcluded into a page.
 
 **Use Cases:**
 
@@ -234,7 +234,7 @@ This command helps writers:
 - Identify circular include dependencies (files included multiple times)
 - Document file relationships for maintenance
 - Plan refactoring of complex include structures
-- Understand table of contents structure and page hierarchies
+- See what content is actually pulled into a page
 
 **Basic Usage:**
 
@@ -286,6 +286,12 @@ times (e.g., file A includes file C, and file B also includes file C), the file
 However, the tree view will show it in all locations where it appears, with subsequent occurrences marked as circular
 includes in verbose mode.
 
+**Note on Toctree:**
+
+This command does **not** follow `.. toctree::` entries. Toctree entries are navigation links to other pages, not content
+that's transcluded into the page. If you need to find which files reference a target file through toctree entries, use
+the `analyze file-references` command with the `--include-toctree` flag.
+
 #### `analyze file-references`
 
 Find all files that reference a target file through RST directives. This performs reverse dependency analysis, showing which files reference the target file through `include`, `literalinclude`, `io-code-block`, or `toctree` directives.
@@ -382,8 +388,7 @@ With `--include-toctree`, also tracks:
       getting-started
    ```
 
-**Note:** Only file-based references are tracked. Inline content (e.g., `.. input::` with `:language:` but no file path) is not tracked.
-
+**Note:** Only file-based references are tracked. Inline content (e.g., `.. input::` with `:language:` but no file path) aly
 **Output Formats:**
 
 **Text** (default):
@@ -687,9 +692,9 @@ audit-cli/
 │   │   │   ├── analyzer.go         # Include tree building
 │   │   │   ├── output.go           # Output formatting
 │   │   │   └── types.go            # Type definitions
-│   │   └── references/             # References analysis subcommand
-│   │       ├── references.go       # Command logic
-│   │       ├── references_test.go  # Tests
+│   │   └── file-references/        # File-references analysis subcommand
+│   │       ├── file-references.go  # Command logic
+│   │       ├── file-references_test.go  # Tests
 │   │       ├── analyzer.go         # Reference finding logic
 │   │       ├── output.go           # Output formatting
 │   │       └── types.go            # Type definitions

audit-cli/commands/analyze/includes/analyzer.go

@@ -106,23 +106,13 @@ func buildIncludeTree(filePath string, visited map[string]bool, verbose bool, de
 		includeFiles = []string{}
 	}
 
-	// Find toctree entries in this file
-	toctreeFiles, err := rst.FindToctreeEntries(absPath)
-	if err != nil {
-		// Not a fatal error - file might not have toctree
-		toctreeFiles = []string{}
-	}
-
-	// Combine include and toctree files
-	allFiles := append(includeFiles, toctreeFiles...)
-
-	if verbose && len(allFiles) > 0 {
+	if verbose && len(includeFiles) > 0 {
 		indent := getIndent(depth)
-		fmt.Printf("%s📄 %s (%d includes, %d toctree entries)\n", indent, filepath.Base(absPath), len(includeFiles), len(toctreeFiles))
+		fmt.Printf("%s📄 %s (%d includes)\n", indent, filepath.Base(absPath), len(includeFiles))
 	}
 
-	// Recursively process each included/toctree file
-	for _, includeFile := range allFiles {
+	// Recursively process each included file
+	for _, includeFile := range includeFiles {
 		childNode, err := buildIncludeTree(includeFile, visited, verbose, depth+1)
 		if err != nil {
 			fmt.Fprintf(os.Stderr, "Warning: failed to process file %s: %v\n", includeFile, err)

audit-cli/commands/analyze/includes/includes.go

@@ -1,12 +1,12 @@
-// Package includes provides functionality for analyzing include and toctree relationships.
+// Package includes provides functionality for analyzing include relationships.
 //
 // This package implements the "analyze includes" subcommand, which analyzes RST files
-// to understand their include directive and toctree relationships. It can display results as:
-//   - A hierarchical tree structure showing include and toctree relationships
-//   - A flat list of all files referenced through includes and toctree entries
+// to understand their include directive relationships. It can display results as:
+//   - A hierarchical tree structure showing include relationships
+//   - A flat list of all files referenced through includes
 //
 // This helps writers understand the impact of changes to files that are widely included
-// or referenced in table of contents.
+// across the documentation.
 package includes
 
 import (
@@ -17,7 +17,7 @@ import (
 
 // NewIncludesCommand creates the includes subcommand.
 //
-// This command analyzes include directive and toctree relationships in RST files.
+// This command analyzes include directive relationships in RST files.
 // Supports flags for different output formats (tree or list).
 //
 // Flags:
@@ -33,17 +33,16 @@ func NewIncludesCommand() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "includes [filepath]",
-		Short: "Analyze include and toctree relationships in RST files",
-		Long: `Analyze include directive and toctree relationships to understand file dependencies.
+		Short: "Analyze include relationships in RST files",
+		Long: `Analyze include directive relationships to understand file dependencies.
 
-This command recursively follows .. include:: directives and .. toctree:: entries
-and shows all files that are referenced. This helps writers understand the impact
-of changes to files that are widely included or referenced in table of contents
-across the documentation.
+This command recursively follows .. include:: directives and shows all files
+that are referenced. This helps writers understand the impact of changes to
+files that are widely included across the documentation.
 
 Output formats:
-  --tree: Show hierarchical tree structure of includes and toctree entries
-  --list: Show flat list of all included and toctree files
+  --tree: Show hierarchical tree structure of includes
+  --list: Show flat list of all included files
 
 If neither flag is specified, shows a summary with basic statistics.`,
 		Args: cobra.ExactArgs(1),