or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

browser-utilities.md configuration.md index.md instrumentation.md pattern-matching.md reporting.md test-integration.md

tile.json

Pattern Matching

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

Version

Tile

Files