tessl/npm-blanket

Seamless JavaScript code coverage library for both browser and Node.js environments

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Pattern Matching

Name: tessl/npm-blanket
Author: tessl

File pattern matching utilities for determining which files to instrument in Node.js environments.

Capabilities

Match Pattern Method

Core pattern matching function that determines if a filename matches a given pattern.

/**
 * Match filename against pattern
 * @param filename - File path to test
 * @param pattern - Pattern to match against (string, array, regex, or function)
 * @returns Whether filename matches the pattern
 */
function matchPattern(filename, pattern);

Usage Examples:

// String pattern (substring match)
blanket.matchPattern("src/utils.js", "src/");           // true
blanket.matchPattern("test/spec.js", "src/");           // false

// Array pattern (any match)
blanket.matchPattern("lib/helper.js", ["src/", "lib/"]); // true

// Regular expression pattern
blanket.matchPattern("src/utils.js", /^src\//);         // true

// Function pattern
blanket.matchPattern("src/utils.js", function(filename) {
  return filename.indexOf("utils") >= 0;
}); // true

Path Normalization

Utility for normalizing file paths across different operating systems.

/**
 * Normalize backslashes in file paths to forward slashes
 * @param str - File path string with potential backslashes
 * @returns Normalized path with forward slashes only
 */
function normalizeBackslashes(str);

Loader Management

Methods for managing Node.js require.extensions loaders in instrumentation workflows.

/**
 * Restore the original require.extensions['.js'] loader
 * Switches from blanket's instrumentation loader back to the original Node.js loader
 * No-op when engineOnly option is enabled
 */
function restoreNormalLoader();

/**
 * Restore blanket's instrumentation loader  
 * Switches from the original loader back to blanket's instrumentation loader
 * No-op when engineOnly option is enabled
 */
function restoreBlanketLoader();

Usage Examples:

// Temporarily disable blanket instrumentation
blanket.restoreNormalLoader();

// Load files without instrumentation
require('./non-instrumented-module.js');

// Re-enable blanket instrumentation
blanket.restoreBlanketLoader();

// Files loaded after this will be instrumented again
require('./instrumented-module.js');

Path Normalization Examples

// Windows path normalization
blanket.normalizeBackslashes("src\\utils\\helper.js");  // "src/utils/helper.js"
blanket.normalizeBackslashes("C:\\project\\src\\app.js"); // "C:/project/src/app.js"

// Unix paths remain unchanged
blanket.normalizeBackslashes("src/utils/helper.js");    // "src/utils/helper.js"

Pattern Types

String Patterns

Simple substring matching against the filename.

// Basic string pattern
blanket.matchPattern("src/app.js", "src/");      // true
blanket.matchPattern("test/spec.js", "src/");    // false

// Exact filename match
blanket.matchPattern("index.js", "index.js");    // true

Array Patterns

Test against multiple patterns - returns true if any pattern matches.

const patterns = ["src/", "lib/", ".js"];

blanket.matchPattern("src/app.js", patterns);    // true (matches "src/" and ".js")
blanket.matchPattern("lib/utils.js", patterns);  // true (matches "lib/" and ".js")
blanket.matchPattern("test/spec.js", patterns);  // true (matches ".js")
blanket.matchPattern("README.md", patterns);     // false (no matches)

Regular Expression Patterns

Advanced pattern matching using regular expressions.

// Match files starting with "src/"
blanket.matchPattern("src/app.js", /^src\//);         // true
blanket.matchPattern("lib/src/app.js", /^src\//);     // false

// Match JavaScript files
blanket.matchPattern("app.js", /\.js$/);              // true
blanket.matchPattern("app.coffee", /\.js$/);          // false

// Case-insensitive matching
blanket.matchPattern("SRC/APP.JS", /^src\//i);        // true

Function Patterns

Custom logic for complex matching scenarios.

// Custom function pattern
function customPattern(filename) {
  // Match .js files in src/ but exclude test files
  return filename.indexOf("src/") >= 0 && 
         filename.endsWith(".js") && 
         filename.indexOf("test") === -1;
}

blanket.matchPattern("src/app.js", customPattern);      // true
blanket.matchPattern("src/test/spec.js", customPattern); // false
blanket.matchPattern("lib/utils.js", customPattern);    // false

Regex String Patterns

Special string format for regex patterns: //pattern/flags

// Regex as string (starts and ends with //)
blanket.matchPattern("src/app.js", "//^src\\//");       // true
blanket.matchPattern("src/app.js", "//\\.js$/");        // true
blanket.matchPattern("APP.JS", "//\\.js$/i");           // true (case-insensitive)

Array String Patterns

Special string format for array patterns: ["pattern1","pattern2"]

// Array as string format
blanket.matchPattern("src/app.js", '["src/","lib/"]');  // true
blanket.matchPattern("test/spec.js", '["src/","lib/"]'); // false

Integration with Blanket.js

Filter Configuration

Pattern matching is used with the filter configuration option:

// String filter
blanket.options("filter", "src/");

// Array filter  
blanket.options("filter", ["src/", "lib/"]);

// Regex filter
blanket.options("filter", /^(src|lib)\//);

// Function filter
blanket.options("filter", function(filename) {
  return filename.indexOf("src/") >= 0 && !filename.includes("test");
});

Anti-filter Configuration

Pattern matching is also used with the antifilter option to exclude files:

// Exclude test files
blanket.options("antifilter", "test/");

// Exclude multiple patterns
blanket.options("antifilter", ["test/", "spec/", ".spec.js"]);

// Complex exclusion with regex
blanket.options("antifilter", /\.(test|spec)\.js$/);

Current Working Directory Filtering

When onlyCwd option is enabled, files are also matched against current working directory:

// Enable CWD filtering
blanket.options("onlyCwd", true);

// Only files within current working directory will be instrumented
// regardless of other filter settings

The cwdRegex is automatically created: new RegExp("^" + escapeRegExp(process.cwd()), "i")

Node.js Integration

require.extensions Integration

Pattern matching is automatically used in Node.js when files are loaded:

// Automatic integration with require.extensions
require.extensions['.js'] = function(localModule, filename) {
  filename = blanket.normalizeBackslashes(filename);
  
  // Check anti-filter first
  if (antipattern && blanket.matchPattern(filename, antipattern)) {
    // Don't instrument, use original loader
    oldLoader(localModule, filename);
    return;
  }
  
  // Check main filter
  if (blanket.matchPattern(filename, pattern)) {
    // Instrument the file
    var content = fs.readFileSync(filename, 'utf8');
    blanket.instrument({
      inputFile: content,
      inputFileName: filename
    }, function(instrumented) {
      localModule._compile(instrumented, filename);
    });
  } else {
    // Use original loader
    oldLoader(localModule, filename);
  }
};

Path Processing

All paths are normalized before pattern matching:

Backslash normalization: Convert \ to /
CWD checking: Validate against current working directory if enabled
Pattern matching: Apply filter and anti-filter patterns
Filename processing: Handle reporter options (shortnames, relativepath, basepath)

Advanced Usage

Debugging Pattern Matching

Enable debug mode to see pattern matching decisions:

blanket.options("debug", true);

// Will log messages like:
// "BLANKET-File will never be instrumented: test/spec.js"
// "BLANKET-Attempting instrument of: src/app.js"

Performance Considerations

String patterns: Fastest, use for simple substring matching
Array patterns: Moderate performance, stops at first match
Regex patterns: Good performance, compiled once
Function patterns: Slowest, custom logic executes each time

Common Patterns

// Source files only
blanket.options("filter", "src/");

// Multiple source directories
blanket.options("filter", ["src/", "lib/", "app/"]);

// JavaScript files only
blanket.options("filter", /\.js$/);

// Exclude test files
blanket.options("antifilter", /\.(test|spec)\.js$/);

// Complex inclusion/exclusion
blanket.options("filter", function(filename) {
  return filename.includes("src/") && 
         !filename.includes("test") &&
         (filename.endsWith(".js") || filename.endsWith(".ts"));
});