@bernierllc/validators-link-integrity

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

Installation

npm install @bernierllc/validators-link-integrity

Usage

Basic Usage

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: '<div id="section-1">Content</div>',
  pageUrl: 'https://mysite.com'
};

const result = await validateLinkIntegrity(input, {}, utils);

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

Create a Configured Validator

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

validateLinkIntegrity(input, options, utils): Promise<ValidationResult>

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<ValidationResult>

createLinkIntegrityValidator(options): Validator

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

Broken Links (link-integrity/broken-links)

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)

Anchor Targets (link-integrity/anchor-targets)

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)

Redirect Chains (link-integrity/redirect-chains)

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

Protocol Consistency (link-integrity/protocol-consistency)

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

Check Broken Links

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

Validate Anchor Targets

const htmlContent = `
  <div id="section-1">Section 1</div>
  <div id="section-2">Section 2</div>
`;

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

Check Protocol Consistency

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);

Validate Redirects

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.