Dangerfile Rule Builder

Common errors

• Error: Cannot find module 'endanger' from '/path/to/project'

  cause The `endanger` package has not been installed or is not resolvable in the current environment.
  fix Run `npm install --save-dev endanger` or `yarn add --dev endanger` to add the package to your project dependencies.

• TypeError: (0, endanger_1.run) is not a function

  cause This error typically occurs when trying to `require` Endanger in a CommonJS context or when module resolution is incorrect for ESM imports, leading to `run` not being correctly imported.
  fix Ensure your `dangerfile.ts` (or `.js`) is treated as an ESM module. Add `"type": "module"` to your `package.json`, or rename your Dangerfile to `.mts` or `.mjs`. Always use `import { run } from 'endanger';`.

• Endanger requires `danger@10.5.3` and above

  cause The installed version of `danger` does not meet the peer dependency requirement of `endanger`.
  fix Update your `danger` package to a compatible version: `npm install danger@^10.5.3 --save-dev` or `yarn upgrade danger@^10.5.3`.

Warnings

• breaking Endanger v7.x requires Danger.js version `^10.5.3` or newer as a peer dependency. Using older versions of `danger` may lead to runtime errors or unexpected behavior due to API changes in Danger's core.
  Fix: Update your `danger` dependency to at least `10.5.3` (e.g., `npm install danger@^10.5.3`).
• gotcha The `run` method within an Endanger `Rule` is `async`. Forgetting to `await` calls to `file.contains()`, `file.before()`, or other asynchronous Git/Danger APIs can lead to unresolved Promises and incorrect rule evaluation.
  Fix: Always use `await` when interacting with asynchronous methods provided in the `files` or `context` objects within your `run` method, for example: `if (await file.contains('pattern'))`.
• gotcha When defining file matching patterns with `match.files`, ensure your glob patterns are correct and specific enough to avoid unintended rule execution or missed files. Debugging glob issues can be challenging.
  Fix: Test your glob patterns using online tools or a dedicated library like `minimatch` before deploying your rules. Use `console.log(files.created, files.modified)` in development to verify matched files.

Install

• npm install endanger npm
• yarn add endanger yarn
• pnpm add endanger pnpm

Imports

• run
  wrong:

  const { run } = require('endanger')

  correct:

  import { run } from 'endanger'

  Endanger is primarily designed for ESM. CommonJS `require` can lead to `TypeError` if not handled with interop.
• Rule
  wrong:

  import Rule from 'endanger'

  correct:

  import { Rule } from 'endanger'

  The `Rule` class is a named export, not a default export. Ensure curly braces are used for destructuring.
• RuleContext

  import type { RuleContext } from 'endanger'

  Import types separately for clarity and bundler optimization when not in TypeScript-only environments.

Quickstart

Demonstrates setting up a Dangerfile with `endanger` using a modular rule to warn about changes in critical system files and ensure corresponding security documentation exists.

import { run, Rule } from 'endanger';

// dangerfile.ts
// This file is typically located at the root of your repository.
import myFirstRule from './danger/myFirstRule';

// Execute the defined rules. You can pass multiple rule instances.
run(
  myFirstRule()
);

// danger/myFirstRule.ts
// Create this file inside a 'danger/' directory.
export default function myFirstRule() {
  return new Rule({
    match: {
      // This rule will only run if files matching this glob pattern are created or modified.
      files: ["src/critical-system/**", "docs/security/**"],
      // You can also match commits by regex: commit: [/^fix\(security\):/]
    },
    messages: {
      criticalFileChangeWarning: `
        🚨 Warning: Changes detected in critical system or security documentation files.
        Please ensure thorough review and necessary approvals.
      `,
      missingSecurityDocs: `
        🚫 A new file was added to 'src/critical-system/' without corresponding security documentation.
      `
    },
    async run({ files, context }) {
      // Iterate over newly created files that match the glob
      for (let file of files.created) {
        context.warn("criticalFileChangeWarning", { file });
        // Example: Check for companion security documentation
        const docPath = file.filePath.replace('src/critical-system/', 'docs/security/');
        if (!(await context.git.fileMatch(docPath).createdOrModified())) {
          context.fail("missingSecurityDocs", { file });
        }
      }
      // Iterate over modified files
      for (let file of files.modified) {
        context.message("criticalFileChangeWarning", { file });
      }
    }
  });
}

// To run this example:
// 1. Install dependencies: npm install --save-dev danger endanger typescript
// 2. Set up a simple git repository and make a commit.
// 3. Create or modify a file within 'src/critical-system/' (e.g., 'src/critical-system/new-feature.ts').
// 4. Run Danger locally: npx danger local --dangerfile dangerfile.ts
//    (Ensure your package.json has `"type": "module"` if you face module resolution issues.)