Skip to content

feat: gitignore filtering for rule context and respectGitignore frontmatter opt-out #321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhuanbarreto merged 7 commits into from
May 18, 2026
Merged

feat: gitignore filtering for rule context and respectGitignore frontmatter opt-out #321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
1d9f34d
feat: add `respectGitignore` frontmatter field and gitignore filterin…
rhuanbarreto May 18, 2026
6a1bd98
docs: regenerate llms-full.txt
rhuanbarreto May 18, 2026
94c7d2a
fix: treat empty files array same as omitted in resolveScopedFiles
rhuanbarreto May 18, 2026
a7f6dfa
feat: warn when respectGitignore is false without files scope
rhuanbarreto May 18, 2026
ad6d92b
feat: warn when file patterns match only gitignored files
rhuanbarreto May 18, 2026
030c2ff
test: add coverage for gitignore warnings, extract to separate file
rhuanbarreto May 18, 2026
f0d6f3c
refactor: move gitignore warnings from runner into resolveScopedFiles
rhuanbarreto May 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 48 additions & 18 deletions docs/public/llms-full.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -461,16 +461,19 @@ The prefix comes from the ADR's domain (see [Domains](/concepts/domains/)). The

Every ADR document starts with a YAML frontmatter block between `---` delimiters. The frontmatter is the machine-readable metadata that Archgate uses to load, filter, and scope rules.

| Field | Type | Required | Description |
| -------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | Unique identifier like `ARCH-001` or `BE-003` |
| `title` | string | Yes | Human-readable title of the decision |
| `domain` | string | Yes | Registered domain name. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. [Custom domains](/concepts/domains/#custom-domains) can be added via `archgate adr domain add`. |
| `rules` | boolean | Yes | Whether this ADR has a companion `.rules.ts` file |
| `files` | string array | No | Glob patterns that scope which files the rules check |
| Field | Type | Required | Description |
| ------------------ | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | Unique identifier like `ARCH-001` or `BE-003` |
| `title` | string | Yes | Human-readable title of the decision |
| `domain` | string | Yes | Registered domain name. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. [Custom domains](/concepts/domains/#custom-domains) can be added via `archgate adr domain add`. |
| `rules` | boolean | Yes | Whether this ADR has a companion `.rules.ts` file |
| `files` | string array | No | Glob patterns that scope which files the rules check |
| `respectGitignore` | boolean | No | Whether to filter out `.gitignore`d files. Defaults to `true`. |

The `files` field is optional. When present, it restricts rule execution to only the files matching the given globs. When absent, rules run against all project files. For example, `files: ["src/commands/**/*.ts"]` limits checks to command files only.

The `respectGitignore` field is also optional. By default, files listed in `.gitignore` are excluded from all file-scanning operations (`ctx.scopedFiles`, `ctx.glob()`, `ctx.grepFiles()`). Set `respectGitignore: false` to include gitignored files -- useful for rules that need to inspect build output or generated files.

## ADR Body Sections

After the frontmatter, the ADR body follows a standard section structure:
Expand Down Expand Up @@ -2540,6 +2543,19 @@ files: ["src/commands/**/*.ts"]

If `files` is omitted, `ctx.scopedFiles` includes all project files. This is appropriate for project-wide rules like dependency policies.

By default, files listed in `.gitignore` (e.g., `node_modules/`, `dist/`) are automatically excluded from `ctx.scopedFiles`, `ctx.glob()`, and `ctx.grepFiles()`. To include gitignored files, set `respectGitignore: false`:

```yaml
---
id: BUILD-001
title: Build Output Structure
domain: architecture
rules: true
respectGitignore: false
files: ["dist/**/*.js"]
---
```

Common patterns:

| Pattern | Matches |
Expand Down Expand Up @@ -2749,7 +2765,7 @@ for (const match of matches) {

### ctx.grepFiles(pattern, fileGlob)

Search across multiple files matching a glob pattern. Returns a flat array of `GrepMatch` objects from all matching files.
Search across multiple files matching a glob pattern. Returns a flat array of `GrepMatch` objects from all matching files. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const matches = await ctx.grepFiles(/TODO:/, "src/**/*.ts");
Expand All @@ -2764,7 +2780,7 @@ for (const match of matches) {

### ctx.glob(pattern)

Find files by glob pattern. Returns an array of file paths relative to the project root.
Find files by glob pattern. Returns an array of file paths relative to the project root. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const testFiles = await ctx.glob("tests/**/*.test.ts");
Expand Down Expand Up @@ -2927,13 +2943,14 @@ files: ["src/commands/**/*.ts"]

### Fields

| Field | Type | Required | Description |
| -------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | Yes | Unique identifier. Must be non-empty. Convention: `PREFIX-NNN` (e.g., `ARCH-001`). |
| `title` | `string` | Yes | Human-readable title of the decision. Must be non-empty. |
| `domain` | `string` | Yes | A registered domain name in lowercase kebab-case. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. Custom domains are those registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). |
| `rules` | `boolean` | Yes | Whether this ADR has a companion `.rules.ts` file with automated checks. |
| `files` | `string[]` | No | Glob patterns that scope which files the rules apply to. |
| Field | Type | Required | Description |
| ------------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id` | `string` | Yes | Unique identifier. Must be non-empty. Convention: `PREFIX-NNN` (e.g., `ARCH-001`). |
| `title` | `string` | Yes | Human-readable title of the decision. Must be non-empty. |
| `domain` | `string` | Yes | A registered domain name in lowercase kebab-case. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. Custom domains are those registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). |
| `rules` | `boolean` | Yes | Whether this ADR has a companion `.rules.ts` file with automated checks. |
| `files` | `string[]` | No | Glob patterns that scope which files the rules apply to. |
| `respectGitignore` | `boolean` | No | Whether to filter out `.gitignore`d files. Defaults to `true`. |

### id

Expand Down Expand Up @@ -2969,6 +2986,19 @@ Multiple patterns can be specified:
files: ["src/api/**/*.ts", "src/middleware/**/*.ts"]
```

### respectGitignore

Controls whether `.gitignore`d files are excluded from `ctx.scopedFiles`, `ctx.glob()`, and `ctx.grepFiles()`. Defaults to `true` when omitted -- gitignored files (e.g., `node_modules/`, `dist/`) are automatically filtered out.

Set to `false` when a rule intentionally needs to inspect ignored files, such as checking build output structure:

```yaml
respectGitignore: false
files: ["dist/**/*.js"]
```

When `respectGitignore` is `false`, all files matched by the `files` globs are included regardless of `.gitignore` rules. When not inside a git repository, this field has no effect -- all matched files are included.

---

## Domain Prefixes
Expand Down Expand Up @@ -4554,7 +4584,7 @@ The reporting interface for recording violations, warnings, and informational me
glob(pattern: string): Promise<string[]>;
```

Find files matching a glob pattern relative to the project root. Returns an array of absolute file paths.
Find files matching a glob pattern relative to the project root. Returns an array of file paths. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const testFiles = await ctx.glob("tests/**/*.test.ts");
Expand All @@ -4578,7 +4608,7 @@ const matches = await ctx.grep(file, /console\.error\(/);
grepFiles(pattern: RegExp, fileGlob: string): Promise;
```

Search multiple files matching a glob pattern for lines matching a regular expression. Combines `glob` and `grep` into a single call.
Search multiple files matching a glob pattern for lines matching a regular expression. Combines `glob` and `grep` into a single call. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const matches = await ctx.grepFiles(/TODO:/i, "src/**/*.ts");
Expand Down
17 changes: 10 additions & 7 deletions docs/src/content/docs/concepts/adrs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,16 +47,19 @@ The prefix comes from the ADR's domain (see [Domains](/concepts/domains/)). The

Every ADR document starts with a YAML frontmatter block between `---` delimiters. The frontmatter is the machine-readable metadata that Archgate uses to load, filter, and scope rules.

| Field | Type | Required | Description |
| -------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | Unique identifier like `ARCH-001` or `BE-003` |
| `title` | string | Yes | Human-readable title of the decision |
| `domain` | string | Yes | Registered domain name. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. [Custom domains](/concepts/domains/#custom-domains) can be added via `archgate adr domain add`. |
| `rules` | boolean | Yes | Whether this ADR has a companion `.rules.ts` file |
| `files` | string array | No | Glob patterns that scope which files the rules check |
| Field | Type | Required | Description |
| ------------------ | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | string | Yes | Unique identifier like `ARCH-001` or `BE-003` |
| `title` | string | Yes | Human-readable title of the decision |
| `domain` | string | Yes | Registered domain name. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. [Custom domains](/concepts/domains/#custom-domains) can be added via `archgate adr domain add`. |
| `rules` | boolean | Yes | Whether this ADR has a companion `.rules.ts` file |
| `files` | string array | No | Glob patterns that scope which files the rules check |
| `respectGitignore` | boolean | No | Whether to filter out `.gitignore`d files. Defaults to `true`. |

The `files` field is optional. When present, it restricts rule execution to only the files matching the given globs. When absent, rules run against all project files. For example, `files: ["src/commands/**/*.ts"]` limits checks to command files only.

The `respectGitignore` field is also optional. By default, files listed in `.gitignore` are excluded from all file-scanning operations (`ctx.scopedFiles`, `ctx.glob()`, `ctx.grepFiles()`). Set `respectGitignore: false` to include gitignored files -- useful for rules that need to inspect build output or generated files.

## ADR Body Sections

After the frontmatter, the ADR body follows a standard section structure:
Expand Down
13 changes: 13 additions & 0 deletions docs/src/content/docs/guides/writing-adrs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -244,6 +244,19 @@ files: ["src/commands/**/*.ts"]

If `files` is omitted, `ctx.scopedFiles` includes all project files. This is appropriate for project-wide rules like dependency policies.

By default, files listed in `.gitignore` (e.g., `node_modules/`, `dist/`) are automatically excluded from `ctx.scopedFiles`, `ctx.glob()`, and `ctx.grepFiles()`. To include gitignored files, set `respectGitignore: false`:

```yaml
---
id: BUILD-001
title: Build Output Structure
domain: architecture
rules: true
respectGitignore: false
files: ["dist/**/*.js"]
---
```

Common patterns:

| Pattern | Matches |
Expand Down
4 changes: 2 additions & 2 deletions docs/src/content/docs/guides/writing-rules.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -145,7 +145,7 @@ for (const match of matches) {

### ctx.grepFiles(pattern, fileGlob)

Search across multiple files matching a glob pattern. Returns a flat array of `GrepMatch` objects from all matching files.
Search across multiple files matching a glob pattern. Returns a flat array of `GrepMatch` objects from all matching files. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const matches = await ctx.grepFiles(/TODO:/, "src/**/*.ts");
Expand All @@ -160,7 +160,7 @@ for (const match of matches) {

### ctx.glob(pattern)

Find files by glob pattern. Returns an array of file paths relative to the project root.
Find files by glob pattern. Returns an array of file paths relative to the project root. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const testFiles = await ctx.glob("tests/**/*.test.ts");
Expand Down
Loading
Loading