Repository navigation
fix(compile): validate link paths independently of #fragment and ?query - #3713
Open
Sai krishna Bodapati (bodapatisaikrishna) wants to merge 1 commit into
Conversation
A markdown target such as references/standards.md#template names a file plus a section address. validate_link_targets passed the whole target to the filesystem check, so an existing file produced a false 'Referenced file not found' warning whenever the link carried a #fragment, ?query, or both. Split the target with UnifiedLinkResolver._split_link_target, the same interpretation the rewrite path already uses, and validate only the path component. Missing-file diagnostics now name that path without the suffix. Suffix values are not validated, and link emission, inlining, install-time rewriting and dry-run write semantics are unchanged. Fixes microsoft#3255
Copilot started reviewing on behalf of
Sai krishna Bodapati (bodapatisaikrishna)
November 13, 2026 06:16
Contributor
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues are reported for the change separating filesystem-path validation from link fragments and queries.
No open issues 🎉
What changed in this PR
Fixes #3255 by making apm compile validate the filesystem path separately from Markdown link fragments and queries, avoiding false missing-file warnings.
Changes:
- Reuses the existing link-target splitter for path validation and diagnostics, without changing link rewriting or inlining.
- Adds regression tests for existing and missing targets with suffixes, plus CLI dry-run coverage.
- Documents that heading and query values are not validated.
| File | Description |
|---|---|
tests/unit/compilation/test_link_resolver_phase3.py |
Adds parameterized tests for fragment, query, and combined suffixes. |
tests/unit/compilation/test_compile_link_validation.py |
Adds CLI coverage for warnings and dry-run output-file behavior. |
src/apm_cli/compilation/link_resolver.py |
Validates and reports only the path component of link targets. |
docs/src/content/docs/producer/package-relative-links.md |
Clarifies path-only validation and its limits. |
CHANGELOG.md |
Records the fix and unchanged surrounding behavior. |
Review effort: Balanced
This was referenced Nov 17, 2026
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
apm compilereportedReferenced file not foundfor a relative Markdownlink whose target exists but carries a
#fragment,?query, or both. Forexample,
[template](references/standards.md#template)was checked as a fileliterally named
standards.md#template.validate_link_targetsnow splits the target withUnifiedLinkResolver._split_link_target— the interpretation the rewrite pathalready uses — and validates only the path component. Missing-file diagnostics
name that path without the suffix. Suffix values themselves are not validated:
the heading or query is not checked against the target document.
Emitted links, suffix preservation, inlining, install-time rewriting,
containment and invalid-path checks, and dry-run versus write semantics are
unchanged.
Issue and approved scope
Issue: Fixes #3255
Human scope-approval comment:
#3255 (comment)
This PR completes the issue as scoped. It does not add heading-ID validation,
section extraction, a new Markdown parser, or any new flag or target.
Type of change
Testing
Local verification:
pytest tests/unit/compilation -q: 1514 passed, 1 skipped.pytest tests/unit -q: 26,937 passed, 59 skipped. The 11 failures in thisshell are unrelated environment checks in
test_governance_evidence.pyandtest_helpers.pythat requirenodeand apythonexecutable onPATH;they pass with
nodeavailable, except the check for a literalpythonbinary, which this environment does not provide.
ruff checkandruff format --checkon the changed files: clean.apm compile --dry-runin a scratch project: existing targets with#fragment,?query, and combined suffixes produced no missing-filewarning;
references/missing.md#templateproduced one warning namingreferences/missing.md. No preview files were written.Spec conformance (OpenAPM v0.1)