Skip to content

Add analyze references cmd #86

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 14 commits into from
Nov 20, 2025
Merged

Add analyze references cmd #86

merged 14 commits into from
Nov 20, 2025

Conversation

@cbullinger
Copy link
Collaborator

@cbullinger cbullinger commented Oct 24, 2025

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

dacharyc
dacharyc requested changes Oct 29, 2025
View reviewed changes
Copy link
Collaborator

@dacharyc dacharyc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@cbullinger cbullinger marked this pull request as ready for review October 29, 2025 14:56
@cbullinger cbullinger requested a review from dacharyc October 29, 2025 15:13
dacharyc
dacharyc requested changes Oct 29, 2025
View reviewed changes
Copy link
Collaborator

@dacharyc dacharyc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@cbullinger cbullinger requested a review from dacharyc November 14, 2025 15:13
dacharyc
dacharyc approved these changes Nov 18, 2025
View reviewed changes
Copy link
Collaborator

@dacharyc dacharyc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Overall, LGTM - just a couple of small comments/requests.

audit-cli/README.md Outdated

#### `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.
Copy link
Collaborator

@dacharyc dacharyc Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we note in here somewhere near the beginning that "file references" does not include :ref:s? I could see some writers interpreting "references" as including the "ref" role and I'm wondering if we should call out that it doesn't.

Copy link
Collaborator Author

@cbullinger cbullinger Nov 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Per Slack convo, renamed to analyze usages

@cbullinger
feat: add analyze-references cmd for finding all files that ref a tar…
9704b1a 
…get file
@cbullinger
apply Dachary feedback and update to support yaml and shared toctree …
8422c46 
…functionality
@cbullinger
docs(README): update for clarity re. orphaned files
a4761e0
@cbullinger
refactor(toctree matching): create new directive_regex.go and optiona…
dcef84e 
…l toctree flag
@cbullinger
refactor(analyze-includes): revert toctree support
8879195
@cbullinger
fix file name so tests pass
e42c4d5
@cbullinger
improve analyze references cmd and remove orphaned file usage
285170f
@cbullinger
Fix: Update flags comment to include all available flags
a7dd676 
Added missing flags to the NewFileReferencesCommand comment:
- --summary
- --include-toctree
- --exclude

These flags were added during improvements but the comment wasn't updated.
@cbullinger
chore(output): delete cli output
5782b7c
@cbullinger
Rename 'analyze file-references' command to 'analyze usage'
3378e0c 
- Rename directory from file-references/ to usage/
- Update package name from filereferences to usage
- Change command from 'file-references' to 'usage' (shorter, clearer)
- Update all documentation and help text
- Update README with new command examples
- All tests pass

The new 'analyze usage' command is shorter (13 vs 24 chars) and more
accurately describes what it does: finding where a file is used.
@cbullinger
Rename usage command files to match package name
8dcb061 
- Rename file_references.go to usage.go
- Rename file_references_test.go to usage_test.go
- Update README to reflect correct filenames
- All tests still pass
@cbullinger
Update output terminology from 'references' to 'usages'
321d967 
- Change 'REFERENCE ANALYSIS' to 'USAGE ANALYSIS' in output header
- Change 'Total References' to 'Total Usages' throughout output
- Update 'No files reference' to 'No files use' in messages
- Update README examples to show 'Total Usages' instead of 'Total References'
- Keep internal type names (ReferenceAnalysis, FileReference) unchanged for API stability
- Keep JSON field names unchanged for backward compatibility
@cbullinger
Update internal types and fields from 'reference' to 'usage' terminology
90d6775 
- Rename AnalyzeReferences() to AnalyzeUsage()
- Rename findReferencesInFile() to findUsagesInFile()
- Rename GroupReferencesByFile() to GroupUsagesByFile()
- Rename runReferences() to runUsage()
- Update all type names:
  - ReferenceAnalysis -> UsageAnalysis
  - FileReference -> FileUsage
  - ReferenceNode -> UsageNode
  - GroupedFileReference -> GroupedFileUsage
- Update all field names:
  - ReferencingFiles -> UsingFiles
  - ReferenceTree -> UsageTree
  - TotalReferences -> TotalUsages
  - ReferencePath -> UsagePath
  - References -> Usages
- Update JSON field names for consistency:
  - total_references -> total_usages
  - referencing_files -> using_files
  - reference_path -> usage_path
- Update all test functions and test data
- Update all comments and documentation

All tests pass. No backward compatibility concerns per user request.
@cbullinger
Update README example output to use 'usage' terminology
9f17c8b 
- Change 'REFERENCE ANALYSIS' header to 'USAGE ANALYSIS'
- Update '4 references' to '4 usages' in example output
- Update JSON field names in examples:
  - total_references -> total_usages
  - referencing_files -> using_files
  - reference_path -> usage_path
- Update command examples to use 'usages' instead of 'references'
- Update jq example to query '.total_usages' instead of '.total_references'
@cbullinger
Copy link
Collaborator Author

cbullinger commented Nov 20, 2025

@dacharyc not sure if you wanted to take another look, but I've renamed to analyze usages. So we're set up to add an analyze refs now. The next item was to add the orphaned files cmd.

dacharyc
dacharyc approved these changes Nov 20, 2025
View reviewed changes
Copy link
Collaborator

@dacharyc dacharyc left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I didn't check it out and run it, but with a cursory scan, it looks like the rename pass has caught everything, so I think this is good to merge!

@cbullinger cbullinger merged commit f2ab139 into mongodb:main Nov 20, 2025
1 check passed
@cbullinger cbullinger deleted the analyze-references branch November 20, 2025 14:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@dacharyc dacharyc dacharyc approved these changes

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

@cbullinger @dacharyc