> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iriscode.co/llms.txt
> Use this file to discover all available pages before exploring further.

# File naming conventions

> Configure Free path-aware file naming checks with ordered role overrides, baseline-aware rollout, ignore globs, suggestions, and built-in exemptions.

Most projects use more than one naming convention: components in `PascalCase`, hooks in `camelCase`, and everything else in `kebab-case`.

A rule keyed on language cannot express that, since a component and a composable are both TypeScript. Naming rules are therefore keyed on **where a file lives**. Set a fallback for the workspace, then add path rules for the directories that differ.

File naming checks are Free.

```jsonc theme={null}
{
  "fileNaming": {
    "convention": "kebab-case",
    "ignore": ["src/generated/**"],
    "overrides": [
      { "files": ["**/components/**"], "convention": "PascalCase" },
      { "files": ["**/hooks/**", "**/composables/**"], "convention": "camelCase" }
    ]
  },
  "fileNamingScope": "new-files",
  "languages": {
    "python": {
      "fileNaming": { "convention": "snake_case", "scope": "all", "ignore": [] }
    }
  }
}
```

Valid conventions are `snake_case`, `kebab-case`, `camelCase`, and `PascalCase`. Iris checks the file stem, preserves known suffixes such as `.test` and `.spec`, and suggests a replacement name.

## How Iris chooses a policy

For every file, Iris applies one deterministic precedence order:

1. Built-in framework/generated-file exemptions and top-level `fileNaming.ignore` globs exclude the file.
2. Every matching `fileNaming.overrides` rule is considered in declaration order; the **last matching rule wins**.
3. If no path rule matches, an existing `languages.<language>.fileNaming` policy is used as a backward-compatible fallback.
4. Otherwise the top-level `fileNaming.convention` applies.

An override requires a non-empty `files` glob array and a `convention`. It may also set `scope`. Override lists are valid only in the top-level `fileNaming` object, so there is one ordered rule list rather than nested precedence systems.

## Roll out without legacy noise

`fileNamingScope` defaults to `"new-files"`.

* With `.iris-baseline.json`, Iris checks paths not present in the baseline. A renamed path counts as new.
* Without a baseline, Iris checks the whole scan. It shows the first 50 violations governed by `new-files` and discloses the full count; findings from a matching rule with `scope: "all"` are never hidden by that rollout cap.
* Set `"all"` to check every file explicitly.

Top-level `fileNaming` supplies the workspace default, absolute ignores, and ordered path rules. `fileNamingScope` is the rollout default. A matching path rule can set `scope`; otherwise a legacy language fallback may set it; when neither does, `fileNamingScope` applies.

## Built-in exemptions

Iris always exempts:

* Next.js reserved files under `app/` or `pages/`: `page`, `layout`, `route`, `loading`, `error`, `global-error`, `not-found`, `template`, `default`, `middleware`, `instrumentation`, `opengraph-image`, `sitemap`, `robots`, `manifest`, `_app`, `_document`, and `_error`.
* Files whose own name is a route construct or a private file: `[id].tsx`, `[...slug].tsx`, `(group).tsx`, and `_`/`@`-prefixed files. These apply to the **file's own name only** - ordinary files inside a route-group `(app)`, private `_modals`, parallel `@slot`, or dynamic `[slug]` **folder** are still checked against the convention.
* Python conventions: `__init__.py`, `__main__.py`, `conftest.py`, `setup.py`, `manage.py`, and other `__dunder__.py` files.
* Go conventions: `main.go`, `*_test.go`, and generated `*.pb.go`. Platform suffixes such as `_windows`, `_linux`, `_darwin`, `_amd64`, and `_arm64` are preserved but removed before checking the stem.
* Type declarations, universal entry files, and hidden paths: `*.d.ts`, `index.*`, dotfiles, and dotfolders.
* Generated or vendored paths: `vendor/`, `node_modules/`, `dist/`, `build/`, `.next/`, `__pycache__/`, and `*.generated.*`.
* Config-by-convention files such as `next.config.*`, `tailwind.config.*`, `postcss.config.*`, `jest.config.*`, `vitest.config.*`, `vite.config.*`, `webpack.config.*`, `rollup.config.*`, and `esbuild.*`.

The top-level `ignore` array adds absolute workspace-relative exclusions to this list, even when a language fallback applies. A legacy language policy's ignore globs are additive. Windows separators are normalized before matching.

## Diagnostics and enforcement

Violations receive a yellow decoration in the VS Code Explorer and a rename hint at the top of an open file. Naming diagnostics are on by default once a policy is configured so the Problems decoration can take precedence over Git's green untracked-file color. Set `inlineDiagnostics.fileNaming` to `false` to opt out. Suppress an intentional exception with `iris-ignore-file: file-naming -- <reason>`.

Pro users can set `gateMaxNamingViolations` to cap the scan-total count in hooks and CI.

## Fixing names

Iris Code renames files to the suggested convention for you:

* **One file (Free).** The naming CodeLens, the Quick Fix on the naming diagnostic, and the Explorer right-click menu all rename a file through an editable prompt. Iris Code updates TypeScript and JavaScript imports across the workspace, and every rename can be undone from the toast or the **Iris Code: Undo Last Rename** command. Renaming Python files does not rewrite `import` statements, renaming Ruby files does not rewrite `require_relative` paths or the constant names Rails derives from a filename, and renaming C# files does not rewrite type names, namespaces, or project references. Iris Code warns you in each case.
* **Every file (Pro).** The **File Naming** panel (from the sidebar's File Naming section) lists every violation with an editable target name. Rename selected files, or all of them, in one import-updating pass; name collisions are skipped and disclosed. Committing before a large batch is recommended.

## Adopting your existing convention

You do not have to configure naming by hand. After a workspace scan, if no policy is set, Iris Code detects the convention your files already follow and offers to adopt it:

* A persistent **Naming Insight** card in the sidebar shows the dominant convention (for example, "78% of your files use kebab-case") and recomputes on every scan, so it stays accurate as files change.
* A one-time toast per workspace surfaces the same suggestion without nagging.

Either one writes the `fileNaming` block into `.irisconfig.json` for you; the card clears once a policy exists. Iris Code only suggests a convention when your codebase clearly follows one.