File Descriptors

File descriptors classify each file on its own, independently of the architectural element it belongs to. They answer the question "what kind of file is this?" — a test, a style, a story — regardless of where it lives.

This is the second classification layer. Element descriptors group files into architectural units (usually folders, such as components/Button/). File descriptors cut across those units: a test file is a test file whether it sits inside a component or a helper. The two layers are orthogonal, so the same file can be element type component and file category test at the same time.

Defining File Descriptors

File descriptors are configured in the boundaries/files setting as an array of objects. Each descriptor defines a pattern to match against file paths and the category to assign when it matches.

export default [{
  settings: {
    "boundaries/files": [
      { pattern: "**/*.spec.js", category: "test" },
      { pattern: "**/*.css", category: "style" }
    ]
  }
}]

This extends the running example used across the documentation. Test files get the test category and stylesheets get the style category, no matter which element contains them.

tip

Read the Selectors section to learn how to match categorized files in policies with the file selector, and see boundaries/files for the setting schema.

File Descriptor Properties

pattern (required)

Type: <string> | <array of strings>

A micromatch pattern matched against the file path. An array means OR — the file is categorized if any pattern matches.

Like element descriptors, patterns are matched relative to rootPath when the file is inside it.

{ pattern: "**/*.spec.js", category: "test" }

category (required)

Type: <string>

The category assigned to files matching the pattern. It is stored in the file's categories array.

{ pattern: "**/*.css", category: "style" }

capture (optional)

Type: <array of strings>

Captures named values from path fragments so you can reference them later in file selectors. It uses the micromatch capture feature, the same way element descriptors do.

Each captured fragment is stored under the key from the capture array at the same index, and appears at runtime as file.captured.

{ pattern: "**/*.stories.*", category: "story", capture: ["fileName"] }

When several matching descriptors capture values, those values are merged into a single file.captured object.

Category Accumulation

Unlike element descriptors by default, file descriptors do not stop at the first match. Every file descriptor whose pattern matches contributes its category, so a single file can carry several categories at once.

export default [{
  settings: {
    "boundaries/files": [
      { pattern: "**/*.spec.js", category: "test" },
      { pattern: "**/*.js", category: "source" }
    ]
  }
}]

With this configuration, src/components/atoms/atom-a/AtomA.spec.js matches both descriptors, so its file categories array is ["test", "source"] — in descriptor declaration order. A plain AtomA.js matches only the second descriptor, so its categories is ["source"].

This is the key difference from element types, which are single by default (you opt in to multi-type). File categories always accumulate.

	Element descriptors	File descriptors
Setting	boundaries/elements	boundaries/files
Answers	Which element does the file belong to?	What kind of file is it?
Result	element.types (array)	file.categories (array)
Accumulation	Single type by default; opt in to multi-type	Always accumulates all matching categories

File Description

During analysis, the plugin builds a runtime file description for each analyzed file as part of its entity. Access it as from.file / to.file in selectors and message templates (for example, {{to.file.categories}}).

Property	Type	Description
categories	<array of strings | null>	All file categories matched, or null when the file matches no file descriptor (unknown) or is ignored.
path	<string | null>	The file path. Relative to rootPath when inside it, absolute when outside. Kept even for unknown files.
captured	<object | null>	Captured values merged from all matching file descriptors, or null when there are none.
isIgnored	<boolean>	true when the file is excluded by include/ignore settings.
isUnknown	<boolean>	true when the file matches no file descriptor.

note

The file dimension is independent from the element dimension. A file can be a known element but an unknown file (no matching file descriptor), or an unknown element but a known file (it matched a file descriptor but no element descriptor). See Classification for how the three layers combine into one entity.

Matching Files using Selectors

To target a file, use the file sub-selector inside a policy's to:

// Match files with the "test" category
{ to: { file: { categories: ["test"] } } }

See File Selectors for the full file selector reference.

Interaction with no-unknown-files

The no-unknown-files rule reports files that the plugin does not recognize. A file is reported only when it belongs to no known element and matches no file descriptor.

This means defining a file descriptor makes the matching files known: a file that matches any boundaries/files pattern is no longer flagged, even if it belongs to no element.

This behavior also preserves backward compatibility: configurations that classified files such as tests or styles through element descriptors (the deprecated mode: "file" or element category) and have since moved them to file descriptors keep passing the rule, instead of being newly reported as unknown.

The default message reflects both layers:

File does not match any file pattern and does not belong to any known element

See no-unknown-files for the full rule reference.

Migrating from the Element category Property

File categories are the recommended replacement for the deprecated category property in element descriptors.

It keeps working without changes; you will see a deprecation warning in your console. File descriptors are a better fit because they categorize files independently of elements: one element can contain files in several categories, and a single file can have several categories at once — neither is possible with the single, element-wide category.

To migrate, move the category from the element descriptor to a file descriptor:

Legacy (element descriptor)	Recommended (file descriptor)
{ type: "helper", category: "helper", pattern: "helpers/*" }	{ type: "helper", pattern: "helpers/*" } plus boundaries/files: { pattern: "helpers/**", category: "helper" }

See the v6 to v7 migration guide for full details.

Next Steps

• Classification - how elements, files, and modules combine into one entity.
• Elements - classify files by the architectural element they belong to.
• Modules - classify dependencies by where they resolve from.
• Selectors - match files (and their categories) in your policies.
• Settings - the boundaries/files setting schema and every other global setting.