ifttt-lint

0.11.1 verified Fri May 01 auth: no javascript

An open-source implementation of Google's internal IFTTT (IfThisThenThat) linter tool for enforcing atomic pull requests. It analyzes diffs and source files to ensure that when certain files or code regions change, specified dependent files or regions also change. Current stable version is v0.11.1, released periodically. Key differentiators include high-concurrency parallel linting using Node.js worker threads, support for labeled regions, and both CLI and programmatic APIs. It is typed with TypeScript, supports Node.js >=18.18, and integrates with GitHub Actions.

Common errors

error SyntaxError: Cannot use import statement outside a module ↓

cause Using ESM import in a CommonJS project without proper configuration.

fix

Add "type": "module" to your package.json or use dynamic import.

error Error: Binary file 'image.png' is not supported ↓

cause Diff contains binary file with changes that cannot be parsed as text.

fix

Ignore binary files via -i '*.png' or upgrade to v0.11.0+.

error Error: LINT.EndLabel without matching LINT.Label ↓

cause Unmatched `LINT.EndLabel` annotation in source file.

fix

Check that each LINT.EndLabel is preceded by a LINT.Label with the same name.

error TypeError: IfThenElse is not a constructor ↓

cause Incorrect import: using default import instead of named import.

fix

Use import { IfThenElse } from 'ifttt-lint'.

Warnings

breaking Node.js >=18.18 required since v0.11.0; older Node.js versions cause import failures. ↓

fix Upgrade Node.js to v18.18 or later.

deprecated The CLI option `--scan` is deprecated and will be removed in v1.0. Use `ifttt-lint path/to/file.diff` instead. ↓

fix Use direct file argument instead of --scan.

gotcha Binary files in diffs cause lint failures with 'Binary file not supported' error. ↓

fix Upgrade to v0.11.0 or later which handles binary diffs gracefully.

breaking API functions previously exported as CommonJS are now ESM-only since v0.11.0. ↓

fix Use `import` syntax; switch to dynamic import if required from CJS modules.

gotcha Missing `LINT.EndLabel` for an open `LINT.Label` causes parser errors without clear error message. ↓

fix Ensure every `LINT.Label('name')` has a matching `LINT.EndLabel`.

gotcha Glob patterns for `-i` (ignore) must be wrapped in quotes in shell to prevent expansion. ↓

fix Use single quotes: `-i '**/*.bak'`.

Install

npm install ifttt-lint

yarn add ifttt-lint

pnpm add ifttt-lint

Imports

IfThenElse

wrong

import IfThenElse from 'ifttt-lint'

correct

import { IfThenElse } from 'ifttt-lint'

Default export does not exist; must use named import.

lintFile

wrong

const { lintFile } = require('ifttt-lint')

correct

import { lintFile } from 'ifttt-lint'

Use ESM import for TypeScript or modern Node.js.

LintContext
wrong
```
import { LintContext } from 'ifttt-lint'
```
correct
```
import type { LintContext } from 'ifttt-lint'
```
If only using type, import with `type` keyword to avoid runtime overhead.

Quickstart

Demonstrates programmatic usage: reading a git diff, linting with ignore patterns, and checking errors.

// Install: npm install --save-dev ifttt-lint
// Example: lint a diff from stdin
import { execSync } from 'child_process';
const diff = execSync('git diff HEAD~1').toString();
const result = await lintFromString(diff, { ignore: ['**/*.bak'] });
if (result.errors.length > 0) {
  console.error('IFTTT lint errors:', result.errors);
  process.exit(1);
}
console.log('No IFTTT issues found.');