How the Ignore Filter Works in Egonex-AI to Exclude Files from Analysis

TLDR: The ignore filter in Egonex-AI uses a three-layer pattern system based on the npm ignore package to decide which files the static-analysis pipeline should skip, checking hard-coded defaults first, then project-local configurations, with later layers able to override earlier ones via negation rules.

The Understand Anything repository implements a robust ignore filter to ensure its static-analysis pipeline processes only relevant source code. Located in packages/core/src/ignore-filter.ts, this filter leverages the standard ignore npm package to provide Git-compatible glob pattern matching. By excluding dependency folders, build artifacts, and binary assets, the system keeps the generated knowledge graph lightweight and focused on actual code.

The Three-Layer Pattern Architecture

The createIgnoreFilter() function constructs rules through three ordered layers. Later layers can override earlier patterns using the ! negation syntax supported by the underlying ignore library.

Layer 1: Hard-Coded Default Patterns

The foundation consists of DEFAULT_IGNORE_PATTERNS, a static array defined at the top of ignore-filter.ts. This list includes common directories like node_modules/, .git/, vendor/, and __pycache__/, along with build outputs (dist/, build/, .next/), lock files (package-lock.json, yarn.lock), binary assets (*.png, *.mp4), and IDE configurations (.idea/, .vscode/).

// packages/core/src/ignore-filter.ts
export const DEFAULT_IGNORE_PATTERNS: string[] = [
  "node_modules/", ".git/", "vendor/", "venv/", "__pycache__/",
  "dist/", "build/", "out/", "coverage/", ".next/", ".cache/",
  ".turbo/", "target/", "obj/",
  "*.lock", "package-lock.json", "yarn.lock", "pnpm-lock.yaml",
  "*.png", "*.jpg", "*.jpeg", "*.gif", "*.svg", "*.ico",
  "*.woff", "*.woff2", "*.ttf", "*.eot", "*.mp3", "*.mp4",
  "*.pdf", "*.zip", "*.tar", "*.gz",
  "*.min.js", "*.min.css", "*.map", "*.generated.*",
  ".idea/", ".vscode/",
  "LICENSE", ".gitignore", ".editorconfig", ".prettierrc",
  ".eslintrc*", "*.log",
];

Layer 2: Project-Local .understandignore

The function checks for .understand-anything/.understandignore relative to the project root. If present, the file's raw contents are read and passed to ig.add(), allowing repository-specific exclusions that travel with the project.

Layer 3: Root-Level .understandignore

Finally, the filter reads .understandignore directly from the project root. This provides a convenient top-level location for user-defined patterns without requiring the .understand-anything/ directory structure.

Filter Construction and API

The createIgnoreFilter() function in packages/core/src/ignore-filter.ts orchestrates the compilation process. It instantiates the ignore object, adds the default patterns, then conditionally adds contents from the two possible user configuration files.

// packages/core/src/ignore-filter.ts
export function createIgnoreFilter(projectRoot: string): IgnoreFilter {
  const ig: Ignore = ignore();

  // 1. Hard-coded defaults
  ig.add(DEFAULT_IGNORE_PATTERNS);

  // 2. .understand-anything/.understandignore
  const projectIgnorePath = join(projectRoot, ".understand-anything", ".understandignore");
  if (existsSync(projectIgnorePath)) {
    ig.add(readFileSync(projectIgnorePath, "utf-8"));
  }

  // 3. .understandignore at repository root
  const rootIgnorePath = join(projectRoot, ".understandignore");
  if (existsSync(rootIgnorePath)) {
    ig.add(readFileSync(rootIgnorePath, "utf-8"));
  }

  return {
    isIgnored(relativePath: string): boolean {
      return ig.ignores(relativePath);
    },
  };
}

Integration with the Analysis Pipeline

When the project-scanner agent walks the filesystem, each file path is passed to the isIgnored method. If the method returns true, the file is skipped and never fed into the parser or graph builder.

This early exclusion prevents unnecessary work on large dependency folders, generated artefacts, and binary assets. The check happens before any parsing occurs, ensuring the knowledge graph remains concise and focused strictly on relevant source code.

Overriding Default Patterns

Users can re-include specific paths that match default patterns by utilizing the ! negation syntax in their .understandignore files.

Create a .understandignore file in your project root:

# Re-include a specific package from node_modules

!node_modules/keep-me/

After loading this configuration, filter.isIgnored("node_modules/keep-me/util.js") returns false, allowing that specific directory to be analyzed despite the default node_modules/ exclusion.

Practical Implementation Examples

To use the filter programmatically:

import { createIgnoreFilter } from "@understand-anything/core/ignore-filter";

const projectRoot = "/path/to/my/project";
const filter = createIgnoreFilter(projectRoot);

console.log(filter.isIgnored("src/index.ts"));           // false
console.log(filter.isIgnored("node_modules/lodash.js"));  // true

Integrating with a file walker:

import { walk } from "some-walk-lib";
import { createIgnoreFilter } from "@understand-anything/core/ignore-filter";

const filter = createIgnoreFilter(projectRoot);
for await (const file of walk(projectRoot)) {
  const rel = file.path.slice(projectRoot.length + 1);
  if (filter.isIgnored(rel)) continue;   // Excluded here
  // Process file...
}

Summary

• The ignore filter uses the npm ignore package to implement Git-compatible glob pattern matching in packages/core/src/ignore-filter.ts.
• Three ordered layers construct the filter: hard-coded defaults, .understand-anything/.understandignore, and root-level .understandignore.
• The createIgnoreFilter() function compiles these patterns and returns an isIgnored() method for runtime checks.
• Later layers override earlier ones using ! negation syntax, allowing fine-grained control over exclusions.
• The filter prevents build artifacts, dependencies, and binary assets from entering the static-analysis pipeline, keeping the knowledge graph focused on source code.

Frequently Asked Questions

What configuration files does the Egonex-AI ignore filter recognize?

The filter checks for two configuration files: .understand-anything/.understandignore for project-local settings, and .understandignore at the repository root for global overrides. Both files use standard Git-ignore syntax and are processed after the hard-coded defaults but before analysis begins.

Can I override the default ignore patterns in Understand Anything?

Yes. Create a .understandignore file in your project root and use the ! negation prefix to re-include specific paths. For example, !node_modules/special-package/ overrides the default node_modules/ exclusion and includes that specific directory in the analysis.

How do I programmatically check if a file is ignored?

Import createIgnoreFilter from @understand-anything/core/ignore-filter and instantiate it with your project root. The returned object provides isIgnored(relativePath), which returns true if the file should be excluded based on the compiled three-layer rule set.

Does the ignore filter affect analysis performance?

Yes, significantly. By excluding directories like node_modules/ and build outputs before they reach the parser, the filter reduces memory usage and processing time. The boolean check happens early in the pipeline, ensuring irrelevant files never trigger parse operations or graph node creation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}