or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

examples

edge-cases.md real-world-scenarios.md

guides

quick-start.md

reference

parsing.md validate-host.md validate-https.md validate-integrity.md validate-package-names.md validate-scheme.md validate-url.md

index.md

tile.json

Quick Start Guide

This guide walks you through using lockfile-lint-api to validate your lockfiles for security issues.

Installation

npm install lockfile-lint-api

Requirements: Node.js >= 16.0.0

Basic Workflow

The library follows a simple pattern:

Parse the lockfile
Create a validator
Validate and check results

Step 1: Parse a Lockfile

const { ParseLockfile } = require('lockfile-lint-api');

// Parse from file path
const parser = new ParseLockfile({
  lockfilePath: './package-lock.json'
});

const lockfile = parser.parseSync();
// Returns: { type: 'success', object: { ... } }

Alternative: Parse from string content

const fs = require('fs');
const content = fs.readFileSync('./yarn.lock', 'utf-8');

const parser = new ParseLockfile({
  lockfileText: content
});

const lockfile = parser.parseSync();

Step 2: Create a Validator

All validators follow the same pattern - they accept the parsed packages object:

const { ValidateHost, ValidateHttps } = require('lockfile-lint-api');

// Host validation
const hostValidator = new ValidateHost({ 
  packages: lockfile.object 
});

// HTTPS validation
const httpsValidator = new ValidateHttps({ 
  packages: lockfile.object 
});

Step 3: Validate and Handle Results

All validators return a consistent result structure:

const result = hostValidator.validate(['npm']);

if (result.type === 'success') {
  console.log('Validation passed');
} else {
  console.error('Validation failed:');
  result.errors.forEach(error => {
    console.error(`  ${error.package}: ${error.message}`);
  });
}

Common Validations

Validate Hosts

Ensure all packages come from trusted registries:

const { ValidateHost, ParseLockfile } = require('lockfile-lint-api');

const parser = new ParseLockfile({ lockfilePath: './package-lock.json' });
const lockfile = parser.parseSync();

const validator = new ValidateHost({ packages: lockfile.object });

// Use registry shortcuts
const result = validator.validate(['npm']);  // Only npm registry
// or
const result = validator.validate(['npm', 'yarn']);  // npm or yarn

// Use custom registries
const result = validator.validate(['registry.mycompany.com']);

Validate HTTPS Protocol

Ensure all packages use secure HTTPS:

const { ValidateHttps, ParseLockfile } = require('lockfile-lint-api');

const parser = new ParseLockfile({ lockfilePath: './package-lock.json' });
const lockfile = parser.parseSync();

const validator = new ValidateHttps({ packages: lockfile.object });
const result = validator.validate();

if (result.type === 'error') {
  console.error('Insecure packages detected:', result.errors);
}

Validate Integrity Hashes

Ensure all packages use strong SHA-512 hashes:

const { ValidateIntegrity, ParseLockfile } = require('lockfile-lint-api');

const parser = new ParseLockfile({ lockfilePath: './package-lock.json' });
const lockfile = parser.parseSync();

const validator = new ValidateIntegrity({ packages: lockfile.object });

// Validate all packages
const result = validator.validate();

// Or exclude specific packages
const result = validator.validate({
  integrityExclude: ['legacy-package', '@company/old-lib']
});

Error Handling

Parsing Errors

Parsing errors throw exceptions:

try {
  const parser = new ParseLockfile({ lockfilePath: './package-lock.json' });
  const lockfile = parser.parseSync();
} catch (error) {
  if (error.name === 'ParsingError') {
    console.error('Failed to parse lockfile:', error.message);
  }
}

Validation Errors

Validation errors are returned in result objects:

const result = validator.validate(['npm']);

if (result.type === 'error') {
  // Handle validation failures
  result.errors.forEach(error => {
    console.error(`${error.package}: ${error.message}`);
  });
}

Complete Example

const {
  ParseLockfile,
  ValidateHost,
  ValidateHttps
} = require('lockfile-lint-api');

function validateLockfile(lockfilePath) {
  try {
    // Parse
    const parser = new ParseLockfile({ lockfilePath });
    const lockfile = parser.parseSync();

    // Validate hosts
    const hostValidator = new ValidateHost({ packages: lockfile.object });
    const hostResult = hostValidator.validate(['npm']);

    if (hostResult.type === 'error') {
      console.error('Host validation failed:');
      hostResult.errors.forEach(e => console.error(e.message));
      return false;
    }

    // Validate HTTPS
    const httpsValidator = new ValidateHttps({ packages: lockfile.object });
    const httpsResult = httpsValidator.validate();

    if (httpsResult.type === 'error') {
      console.error('HTTPS validation failed:');
      httpsResult.errors.forEach(e => console.error(e.message));
      return false;
    }

    console.log('✓ All validations passed');
    return true;
  } catch (error) {
    console.error('Error:', error.message);
    return false;
  }
}

validateLockfile('./package-lock.json');

Next Steps

See Real-World Scenarios for advanced usage
Check Edge Cases for special scenarios
Browse API Reference for complete documentation