fix(docs-links): name a present-but-untracked link target - #29
Conversation
A doc linking to a file that exists on disk but is not yet tracked was reported as a broken link, which reads as if the file were missing. The rule stays (targets must be tracked); the message now says the target is untracked and that staging it resolves the link. Missing targets still report as broken.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![slopzapper[bot]](https://avatars.githubusercontent.com/in/4527847?s=60&v=4){kind=small}
There was a problem hiding this comment.
⚡ SLOPS ZAPPED: 1
Verdict: Non-blocking slop
The untracked diagnostic is correct for a stageable file. Gitignored-present targets get the same stage-it text, which git add will refuse.
Findings
- 🧹 SMOLSLOP · P2 — Gitignored link targets told to stage — bogus fix git will refuse (
src/checks/docsLinks.ts:351)
There was a problem hiding this comment.
🟢 Approval recommended
The change is narrowly scoped, preserves the existing tracked-target rule, and includes targeted unit test coverage for the new behavior.
Pull request overview
This PR improves the docs links validator’s diagnostics when a Markdown link points to a file that exists in the working tree but isn’t tracked by git yet, so contributors see a clear “stage it” action instead of an ambiguous “broken link”.
Changes:
- Detect link targets that exist on disk but are untracked, and report them as
untracked link target (...)with an explicit staging hint. - Add a unit test covering both the “present-but-untracked” and “missing” target branches.
- Document the clarified behavior in the conventions guide.
File summaries
| File | Description |
|---|---|
| test/docs-links.test.ts | Adds coverage for the new “untracked link target” diagnostic and ensures missing targets still report as broken. |
| src/checks/docsLinks.ts | Introduces a filesystem existence check for untracked targets and emits a more specific error message. |
| docs/convention.md | Updates documentation to explain the new diagnostic for present-but-untracked link targets. |
Review details
- Files reviewed: 3/3 changed files
- Comments generated: 0
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 68b6f2913e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Use git ls-files --others --exclude-standard as the source of stageable paths instead of an lstat existence check. A gitignored-but-present target and a case-mismatched spelling of a tracked file both stay broken links, so the remediation is only offered when git add would actually resolve it.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2333851069
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Ask git about the single link target instead of listing every untracked path, so a large untracked tree cannot overflow the spawn buffer and turn into an empty set. Reject case-folded collisions with tracked paths and embedded repositories (listed as dir/), since git add would not produce a tree that checks out everywhere.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fa8cb0998b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Pass the target under --literal-pathspecs so metacharacters in a link are not expanded as a git pattern. List with --directory --no-empty-directory so a large untracked directory collapses to one entry instead of every descendant, and reject it only when it is an embedded repository. Compare against tracked paths with portablePathIdentity so Unicode case aliases collide the same way the registry check treats them.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 176c9be6ce
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Replace the untracked-listing prediction with git add --dry-run under --literal-pathspecs, which refuses ignored paths, missing paths, and embedded repositories at any depth without touching the index. Guard the two cases git accepts but a portable tree cannot hold: components that alias the .git directory, and portable-identity collisions with tracked paths in either direction. Reject NUL bytes before spawning.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ab8dccf593
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
git add --dry-run runs configured clean filters, so validation could execute commands. Go back to a literal, filter-free ls-files --others listing collapsed to one entry per directory, and stop promising that staging will succeed: the message now says the target is untracked and resolves only once tracked. Empty and ignored-only directories, .git aliases, embedded repositories, and portable-identity collisions with tracked paths stay broken links.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: be96c716b3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
The untracked diagnostic is a classification, not a promise that git add will succeed, so stop re-deriving git's path rules in the check: a .git marker inside an untracked directory is that directory's business, and .git aliases (case, HFS-ignorable characters) are enforced by git at add time. Cache the classification per distinct target so a file with many links spawns git once per target rather than once per occurrence.
Problem
docs linksresolves link targets againstgit ls-files. Adding a file and a Markdown link to it in the same change reportsbroken link (path)until the file is staged, which reads as if the file were missing.Solution
Keep the rule (targets must be tracked so a gitignored-but-present file never passes). When the target exists in the working tree but is untracked, report
untracked link target (path); stage it so the link resolves for others. Missing targets and../escapes still reportbroken link.No golden covers the broken-link message, so parity is unaffected. Adds a unit test for both branches and a sentence in
docs/convention.md.