Add function to test link definitions

Prerequisites

• Accepted Idea: Proposals in this project are created based on ideas that have been marked as Accepted in their Discussion. Before you file an issue for a feature or change, create a discussion. If you file an issue without a discussion, the team may convert it into one.
• Existing Issue: Search the existing issues and discussions for this repository. If there is an issue or discussion that fits your needs do not file a new one. Subscribe, react, or comment on that issue or discussion instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Add Get-Foo cmdlet to Documentarian module" instead of "New cmdlet."

Module

Documentarian

Summary

As a content author, I want to be able to test whether the links in an article are valid so I know whether they need to be updated.

Details

This functionality could be implemented with a Test-Link function that:

1. Inspects the links in a given document (by path or input) or array of links (returned by Get-DocumentLink, see #16).

2. Returns $true if every link reference and definition can be resolved, every reference definition is used, and every reference definition can be resolved.

   Link references are resolvable if their reference is defined.

   Absolute link and reference definitions are resolvable if they can be successfully reached with a web request.

   Relative link and reference definitions are resolvable if the path to the file can be resolved from the document's location.

3. If any link or definition fails validation, the function returns $false.

With parameters, the default behavior can be changed:

1. Use the Detailed parameter to return a result object for each tested link and reference definition.

2. Use the WarnOnFailure parameter to write descriptive messages to the warning stream for items that fail validation.

3. Use the ErrorOnFailure parameter to write errors for items that fail validation. Use this in conjunction with ErrorAction to stop execution.

4. Use the Ignore parameter to specify a regular expression and skip validating any links and references whose definition matches that regular expression.

5. Use the Handler parameter to specify one or more scriptblocks to use when attempting to validate an item. These scriptblocks have access to the item being validated.

   The Handler parameter enables users to specify custom handlers for links that can't be resolved normally, such as when a document uses site-relative links but not all pages are defined in the same project. The Handler scriptblocks are always executed before the default behavior.

Start by reviewing the proposed Test-Link entry point and the related Get-DocumentLink issue (#16), then inspect the accepted discussion linked in the prerequisites. Define how document paths, link arrays, reference definitions, handlers, and failure-reporting parameters should be represented. Done means validation returns the specified boolean or detailed results and handles warnings, errors, ignores, and custom handlers as described.