@bernierllc/validators-link-integrity

Link integrity validation primitive - broken links, anchor targets, redirects, and URL validation.

Installation

``bash
npm install @bernierllc/validators-link-integrity
`

Usage

$3

`typescript
import { validateLinkIntegrity } from '@bernierllc/validators-link-integrity';
import { createSharedUtils } from '@bernierllc/validators-utils';

const utils = createSharedUtils();

const input = {
links: [
{ url: 'https://example.com', context: 'Example link' },
{ url: '#section-1', context: 'Internal anchor' },
{ url: 'http://insecure.com', context: 'HTTP link' }
],
htmlContent: '

if (result.problems.length > 0) {
console.log('Link integrity issues found:');
result.problems.forEach(problem => {
console.log( - ${problem.message} (${problem.severity}));
});
}
`

$3

`typescript
import { createLinkIntegrityValidator } from '@bernierllc/validators-link-integrity';

const validator = createLinkIntegrityValidator({
checkBrokenLinks: true,
checkAnchorTargets: true,
checkRedirectChains: false, // Disable redirect checks
checkProtocolConsistency: true,
maxRedirects: 3,
timeout: 5000
});

const result = await validator.validate(input, utils);
`

API Reference

$3

Validates link integrity for the provided links.

Parameters:

- input (LinkIntegrityInput): The input containing links to validate
- links (LinkContext[]): Array of links to validate
- htmlContent? (string): Optional HTML content for anchor validation
- pageUrl? (string): Optional page URL for protocol validation
- options (LinkIntegrityOptions): Validation options
- utils (SharedUtils): Shared utility functions from validators-utils

Returns: Promise

$3

Creates a configured link integrity validator.

Parameters:

- options (LinkIntegrityOptions): Validation options

Returns: An object with:
- validate(input, utils): Validation function
- getMeta(): Returns validator metadata

LinkIntegrityOptions

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| checkBrokenLinks | boolean | true | Check for broken links (404s and other error statuses) |
| checkAnchorTargets | boolean | true | Check for anchor target existence (#fragment validation) |
| checkRedirectChains | boolean | true | Check for redirect chains |
| checkProtocolConsistency | boolean | true | Check for protocol consistency (http vs https) |
| maxRedirects | number | 5 | Maximum number of redirects to follow |
| timeout | number | 5000 | Timeout for HTTP requests (ms) |
| checkExternalLinks | boolean | true | Whether to check external links (outside current domain) |
| baseUrl | string | '' | Base URL for resolving relative links |
| userAgent | string | 'BernierLLC-Validators/1.0' | User agent string for HTTP requests |

Validation Rules

$3

Detects broken links that return 404 or other error status codes.

Reports:
- Error: 404 Not Found
- Warning: Other HTTP error statuses (500, 503, etc.)
- Warning: Network errors and timeouts

Skips:
- mailto:, tel:, javascript:, data: protocols
- Anchor-only links (#fragment)

$3

Validates that anchor links (#fragment) point to existing IDs in the document.

Reports:
- Error: Anchor target not found in HTML content
- Warning: Failed to parse HTML content
- Info: Cannot validate anchor (no HTML content provided)

Validates:
- Elements with matching id attributes
- Elements with matching name attributes (legacy HTML)

$3

Validates redirect chains and detects excessive or circular redirects.

Reports:
- Error: Excessive redirect chain (exceeds maxRedirects)
- Error: Circular redirect detected
- Warning: Long redirect chain (> 2 redirects)

Skips:
- Non-HTTP protocols

$3

Validates protocol consistency and recommends HTTPS usage.

Reports:
- Error: Mixed content (HTTPS page links to HTTP resource)
- Warning: Insecure protocol (HTTP instead of HTTPS)
- Info: Protocol-relative URL (//example.com)

Skips:
- Non-HTTP/HTTPS protocols

Examples

$3

`typescript
const validator = createLinkIntegrityValidator({
checkBrokenLinks: true,
checkAnchorTargets: false,
checkRedirectChains: false,
checkProtocolConsistency: false
});

const result = await validator.validate({
links: [
{ url: 'https://example.com/page' },
{ url: 'https://example.com/missing' }
]
}, utils);

// Result will contain problems for broken links
`

$3

`typescript
const htmlContent =

const result = await validateLinkIntegrity({
links: [
{ url: '#section-1' },
{ url: '#section-2' },
{ url: '#section-3' } // This will report an error
],
htmlContent
}, {}, utils);
`

$3

`typescript
const result = await validateLinkIntegrity({
links: [
{ url: 'http://example.com' }, // Warning: insecure
{ url: 'https://secure.com' } // OK
],
pageUrl: 'https://mysite.com' // Mixed content detection
}, {
checkProtocolConsistency: true,
checkBrokenLinks: false,
checkAnchorTargets: false,
checkRedirectChains: false
}, utils);
`

$3

`typescript
const validator = createLinkIntegrityValidator({
checkRedirectChains: true,
maxRedirects: 3 // Warn if more than 3 redirects
});

const result = await validator.validate({
links: [
{ url: 'http://example.com/redirect-chain' }
]
}, utils);
``

Integration Status

- Logger: not-applicable - Pure validation primitive with no internal state
- Docs-Suite: ready - Markdown documentation, TypeDoc API documentation
- NeverHub: not-applicable - Stateless primitive validator

Performance

- Sub-100ms validation per link for local checks (anchors, protocol)
- Network-bound for broken link and redirect checks (timeout: 5000ms)
- Parallel execution recommended for multiple links
- Rate limiting built-in for HTTP requests (10 requests per second)

Architecture

This is a primitive validator following BernierLLC validators architecture:

- Pure validation - Returns problems, never throws exceptions
- No policy enforcement - Implementors decide what constitutes "passing"
- Composable rules - Each rule focuses on a single aspect
- Evidence-rich - Provides actionable information for debugging
- Tool-agnostic - Works in CLI, web apps, CI/CD, IDE plugins

See Also

- @bernierllc/validators-core - Core types and interfaces
- @bernierllc/validators-utils - Shared utilities
- @bernierllc/validators-runner - Validation orchestration

License

Copyright (c) 2025 Bernier LLC. All rights reserved.