Include enhancements: link adjustment and heading-level

[jeduden]

Summary

• Automatic relative link/image rewriting when including files across directories
• New heading-level: "absolute" parameter to shift included headings under the parent section
• findParentHeadingLevel walks the AST to detect enclosing heading level
• README examples for all configuration options (wrap, strip-frontmatter, heading-level, link rewriting)

Test plan

• go test ./... — all 44 packages pass
• go tool golangci-lint run — 0 issues
• mdsmith check . — 0 diagnostics
• Link adjustment edge cases: trailing slashes, fragments, query strings, images, nested brackets, mailto, absolute URLs
• Heading shift with setext headings and code fences (13 test cases)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR extends the MDS021 include directive to (1) rewrite relative link/image targets in included content when files live in different directories, and (2) optionally shift included heading levels under the parent section via heading-level: "absolute".

Changes:

• Add automatic relative link/image target rewriting for included content.
• Add heading-level: "absolute" parameter support, including parent-heading detection and heading shifting.
• Add/extend unit tests and update the MDS021 rule documentation.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
internal/rules/include/rule.go	Validates heading-level, calls link rewriting + heading shifting during include generation, adds parent-heading detection helper.
internal/rules/include/rule_test.go	Adds end-to-end tests for link adjustment, heading-level shifting, and combined behavior.
internal/rules/include/links.go	Implements adjustLinks to rewrite Markdown link/image targets across directories.
internal/rules/include/links_test.go	Adds unit tests covering link rewrite behavior (fragments, queries, images, skips).
internal/rules/include/headings.go	Implements adjustHeadings to shift ATX/setext headings while skipping fenced code blocks.
internal/rules/include/headings_test.go	Adds unit tests for heading shifting (ATX, setext, code fences, caps).
internal/rules/MDS021-include/README.md	Documents new heading-level param and automatic link adjustment behavior.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

internal/rules/include/rule.go:176

• generateIncludeContent applies link rewriting and (optionally) heading shifting before applying wrap. When wrap is set, the included content is meant to be shown verbatim inside a code fence; rewriting links/headings beforehand can unexpectedly change the literal content being displayed. Consider skipping these transformations when wrap is present, or adding an explicit parameter to control whether rewriting/heading shifting applies to wrapped includes.

	// Rewrite relative links so they resolve from the including file's
	// directory. The file param is relative to f.FS (the including file's
	// directory), so join with filePath's directory to get a repo-root-
	// relative path matching filePath's coordinate system.
	includedPath := path.Join(path.Dir(filePath), file)
	text = adjustLinks(text, includedPath, filePath)

	// Shift headings when heading-level: "absolute" is set.
	if params["heading-level"] == "absolute" {
		parentLevel := findParentHeadingLevel(f, line)
		text = adjustHeadings(text, parentLevel)
	}

	// Wrap in code fence if requested.
	if wrap, ok := params["wrap"]; ok {
		text = "```" + wrap + "\n" + text
		if !strings.HasSuffix(text, "\n") {
			text += "\n"
		}
		text += "```\n"
	}

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (2)

internal/rules/include/rule.go:184

• Link rewriting and heading shifting are applied before wrap handling, which means wrap: ... (code-fence includes) will still have its content mutated (links rewritten, headings shifted) even though the output is meant to be a literal code sample. That can break the intent of wrap (show the exact file contents). Consider skipping adjustLinks/adjustHeadings when wrap is set, or introducing an explicit opt-in/out parameter for these transformations.

	// Rewrite relative links so they resolve from the including file's
	// directory. The file param is relative to f.FS (the including file's
	// directory), so join with filePath's directory to get a repo-root-
	// relative path matching filePath's coordinate system.
	includedPath := path.Join(path.Dir(filePath), file)
	text = adjustLinks(text, includedPath, filePath)

	// Shift headings when heading-level: "absolute" is set.
	if params["heading-level"] == "absolute" {
		parentLevel := findParentHeadingLevel(f, line)
		text = adjustHeadings(text, parentLevel)
	}

	// Wrap in code fence if requested.
	if wrap, ok := params["wrap"]; ok {
		text = "```" + wrap + "\n" + text
		if !strings.HasSuffix(text, "\n") {
			text += "\n"
		}
		text += "```\n"
	}

internal/rules/include/rule.go:144

• With the removal of the explicit ".." validation, invalid/escaping paths now fall through to fs.ReadFile and surface as include file ... not found: ... invalid argument, which is misleading and makes traversal issues harder to diagnose. Before calling fs.ReadFile, consider validating readPath (and/or resolvedFile) with fs.ValidPath and returning a dedicated diagnostic when the resolved path is invalid or escapes the project root.

	// Resolve file relative to the including file's directory.
	// Use RootFS (project root) when available so that paths
	// with ".." segments work across directories.
	resolvedFile := path.Join(path.Dir(filePath), file)
	readFS := f.FS
	readPath := file
	if f.RootFS != nil {
		readFS = f.RootFS
		readPath = resolvedFile
	}
	data, err := fs.ReadFile(readFS, readPath)
	if err != nil {
		return "", []lint.Diagnostic{makeDiag(filePath, line,
			fmt.Sprintf("include file %q not found: %v", file, err))}
	}

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.