Skip to content

fix(compile): validate link paths independently of #fragment and ?query - #3713

Open
Sai krishna Bodapati (bodapatisaikrishna) wants to merge 1 commit into
microsoft:mainfrom
bodapatisaikrishna:fix/3255-link-validation-suffixes
Open

Sai krishna Bodapati (bodapatisaikrishna) wants to merge 1 commit into
microsoft:mainfrom
bodapatisaikrishna:fix/3255-link-validation-suffixes

Conversation

@bodapatisaikrishna

Copy link
Copy Markdown
Contributor

Description

apm compile reported Referenced file not found for a relative Markdown
link whose target exists but carries a #fragment, ?query, or both. For
example, [template](references/standards.md#template) was checked as a file
literally named standards.md#template.

validate_link_targets now splits the target with
UnifiedLinkResolver._split_link_target — the interpretation the rewrite path
already 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

  • Bug fix
  • New feature
  • Documentation
  • Maintenance / refactor

Testing

  • Tested locally
  • All existing tests pass
  • Added tests for new functionality

Local verification:

  • pytest tests/unit/compilation -q: 1514 passed, 1 skipped.
  • pytest tests/unit -q: 26,937 passed, 59 skipped. The 11 failures in this
    shell are unrelated environment checks in test_governance_evidence.py and
    test_helpers.py that require node and a python executable on PATH;
    they pass with node available, except the check for a literal python
    binary, which this environment does not provide.
  • ruff check and ruff format --check on the changed files: clean.
  • Manual apm compile --dry-run in a scratch project: existing targets with
    #fragment, ?query, and combined suffixes produced no missing-file
    warning; references/missing.md#template produced one warning naming
    references/missing.md. No preview files were written.

Spec conformance (OpenAPM v0.1)

  • N/A — this PR does not change OpenAPM-observable behaviour.

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 AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 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 branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] apm compile reports 'Referenced file not found' for links with a #fragment

2 participants