Add analyze references cmd #86

cbullinger · 2025-10-24T12:24:04Z

Adds a new analyze references command that finds all files that reference a target file.

Path resolution logic is centralized in internal/pathresolver
All existing commands continue to work with refactored path resolution
Command supports multiple directive types: include, literalinclude, io-code-block
Command shows directive type in output (e.g., "referenced by literalinclude in page.rst")
Command works with both versioned and non-versioned projects
Command is limited to single version (no cross-version search)
All tests pass
Documentation is complete and accurate
Code follows existing patterns and conventions

…get file

dacharyc

At a high level, this seems like useful functionality, but is missing some considerations that would make it function as-advertised. It's currently going to miss references via a few different avenues.

dacharyc · 2025-10-29T12:58:40Z

audit-cli/README.md

 However, the tree view will show it in all locations where it appears, with subsequent occurrences marked as circular
 includes in verbose mode.

+#### `analyze references`


One high-level request: can we rename this to analyze file-references or something like that? I want to distinguish it from ref references... JW wrote a script recently to analyze refs and we might want to add that to the CLI, so I'd like to disambiguate.

dacharyc · 2025-10-29T13:00:33Z

audit-cli/README.md

+- Understand the impact of changes to a file (what pages will be affected)
+- Find all usages of an include file across the documentation
+- Track where code examples are referenced
+- Identify orphaned files (files with no references)


If we're trying to find orphaned files, I think we also need to check ToC entries. Many .txt files may have no references through include, literalinclude, or io-code-block directives - they may only be referenced through ToC entries, but that doesn't make them "unused."

added the toctree resolution as shared functionality

dacharyc · 2025-10-29T13:03:14Z

audit-cli/README.md

+│   │   │   ├── analyzer.go         # Include tree building
+│   │   │   ├── output.go           # Output formatting
+│   │   │   └── types.go            # Type definitions
+│   │   └── references/             # References analysis subcommand


If we do rename this command, presumably we'd also need to rename this dir.

dacharyc · 2025-10-29T13:08:04Z

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

+			return nil
+		}
+
+		// Only process RST files (.rst and .txt extensions)


Ah, this is an issue - there are yaml files that may also include references to files, so we probably need to process those, too. i.e. the extracts files, like here - are .yaml files that contain include, literalinclude, or io-code-block directives - but we're not seeing them here if we're not processing those files.

dacharyc · 2025-10-29T13:09:10Z

audit-cli/commands/analyze/file-references/analyzer.go

+
+// findReferencesInFile searches a single file for references to the target file.
+//
+// This function scans through the file line by line looking for include,


Yeah, given this implementation, we will definitely be missing ToC references and therefore some pages will falsely show as orphaned when they're in fact included via ToC.

…functionality

dacharyc

Back to you for some fixups - mainly related to the changes to the analyze includes command.

audit-cli/README.md

dacharyc · 2025-10-29T16:18:14Z

audit-cli/README.md

 #### `analyze includes`

-Analyze `include` directive relationships in RST files to understand file dependencies.
+Analyze `include` directive and `toctree` relationships in RST files to understand file dependencies.


Oh, this is an interesting interpretation.

I would prefer this did not include toctree relationships by default. Can we make this an optional flag? I was specifically trying to inspect all the content that goes into creating this file or page. The toctree references are links to other pages, but they are not pulled into the page content (transcluded) the same way that includes are.

dacharyc · 2025-10-29T16:19:52Z

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

Can we revert this functionality or at least gate it behind an optional flag (for toctrees)?

dacharyc · 2025-10-29T16:22:21Z

audit-cli/README.md

+- `-v, --verbose` - Show detailed information including line numbers and reference paths
+- `-c, --count-only` - Only show the count of references (useful for quick checks and scripting)
+- `--paths-only` - Only show the file paths, one per line (useful for piping to other commands)
+- `-t, --directive-type <type>` - Filter by directive type: `include`, `literalinclude`, or `io-code-block`


Should we add toctree as a filter here since we're now checking those?

(Ahh, I see in the implementation it's supported - so I guess this README section just needs some updates?)

dacharyc · 2025-10-29T16:22:38Z

audit-cli/README.md

+
+This helps identify both the impact scope (how many files) and duplicate includes (when references > files).
+
+**Supported Directive Types:**


Same here - I presume we should add toctree to this list.

audit-cli/README.md

dacharyc · 2025-10-29T16:28:33Z

audit-cli/commands/analyze/file-references/analyzer.go

+		trimmedLine := strings.TrimSpace(line)
+
+		// Check for toctree start (use shared regex from rst package)
+		if rst.ToctreeDirectiveRegex.MatchString(trimmedLine) {


Hmm, this inconsistency is bugging me. It looks like we're defining the toctree matching regex in the rst package, but all the other regex is defined as vars at the top of this file. Could we move all of these to rst, maybe as a directive_regex.go file or something?

…l toctree flag

feat: add analyze-references cmd for finding all files that ref a tar…

1c6c715

…get file

dacharyc requested changes Oct 29, 2025

View reviewed changes

apply Dachary feedback and update to support yaml and shared toctree …

7b61530

…functionality

cbullinger marked this pull request as ready for review October 29, 2025 14:56

docs(README): update for clarity re. orphaned files

d82630b

cbullinger requested a review from dacharyc October 29, 2025 15:13

dacharyc requested changes Oct 29, 2025

View reviewed changes

cbullinger added 2 commits October 29, 2025 13:20

refactor(toctree matching): create new directive_regex.go and optiona…

f2a787f

…l toctree flag

refactor(analyze-includes): revert toctree support

1f63808

cbullinger force-pushed the analyze-references branch from e92aaa5 to 1f63808 Compare October 29, 2025 17:30

fix file name so tests pass

27e91a5


		This helps identify both the impact scope (how many files) and duplicate includes (when references > files).

		Supported Directive Types:

Add analyze references cmd #86

Are you sure you want to change the base?

Add analyze references cmd #86

Uh oh!

Conversation

cbullinger commented Oct 24, 2025

Uh oh!

dacharyc left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dacharyc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants