GitHub

Structurelint

A standalone linter that validates an existing project's file/folder structure against rules you define — no scaffolding, no code generation. It only inspects what is already on disk and reports anything that does not match.

It was extracted from an ESLint structure rule so structure validation can run in parallel with the rest of your tooling instead of being sequenced inside the ESLint pipeline. It is not tied to React (or any framework) — the rules describe whatever layout your JS/TS project uses.

Rules are recursive — a rule can reference itself or other named rules to describe nested structures (e.g. components/Button/nested/Icon, where nested reuses the same PascalCase component rules as the root components).

Installation

npm install --save-dev @ladamczyk/structurelint

Or run it directly without installing:

npx @ladamczyk/structurelint

List all available options:

npx @ladamczyk/structurelint -h

Command

structurelint [options]

Option	Default	Description
-p, --path <path>	structureRoot	Root folder to validate (overrides structureRoot)
--json	—	Emit machine-readable JSON instead of text

Exits with code 0 when the structure is valid, 1 when there are violations, and 2 on a usage error (e.g. a missing config). Use --json for machine/AI consumption.

Config

Create a structure.config.ts (or .js/.mjs) at your project root that default-exports a config — it is auto-discovered, there is no way to point at a different path. .ts configs are loaded directly, no build step needed.

The config default-exports an object: an optional structureRoot (defaults to .), an optional ignorePatterns list, the structure array (allowed children of the root), and an optional rules map of reusable named rules referenced via { ruleId }.

A rule is a folder rule when it has children, otherwise it is a file rule — to allow an empty folder, give it children: []. The name is a literal or a template:

Token in name	Matches
{PascalCase}	Button, ButtonGroup
{camelCase}	useStore, fetch
{kebab-case}	my-feature
{snake_case}	my_module
{SCREAMING_SNAKE_CASE}	MAX_VALUE
{anyCase}	any single segment
(ts|tsx)	one of the listed alternatives
*	any run of characters in a segment

import type { IStructureConfig } from '@ladamczyk/structurelint';

const config = {
  structureRoot: 'src',
  ignorePatterns: ['*.d.ts', '*.stories.tsx'],
  rules: {
    // A single PascalCase component folder, recursive via `nested/`.
    component_folder: {
      name: '{PascalCase}',
      folderRecursionLimit: 5,
      children: [
        { name: 'index.ts' },
        { name: '{PascalCase}.(ts|tsx)' },
        { name: '{PascalCase}.spec.(ts|tsx)' },
        { ruleId: 'nested_folder' },
      ],
    },
    // `nested/` reuses the same component rules — this is the recursion.
    nested_folder: {
      name: 'nested',
      children: [{ ruleId: 'component_folder' }],
    },
  },
  structure: [
    {
      name: 'components',
      children: [{ ruleId: 'component_folder' }],
    },
  ],
} satisfies IStructureConfig;

export default config;

With the config above, components/Button/nested/Icon/Icon.tsx is valid, while components/Button/nested/icon (lowercase) is reported as an unexpected folder.

{ ruleId: 'name' } can reference a rule from rules — including itself, which is how nested/recursive structures are described. folderRecursionLimit caps how deep a self-referential rule keeps validating along a branch. required: true on a rule makes at least one matching entry mandatory in its parent folder.

Violations

Each violation is { path, type, message, expected }:

• type: 'unexpected' — a file/folder matched no rule at its level; expected lists the allowed name patterns there.
• type: 'missing' — a required rule had no matching entry; expected is that rule's name.

JavaScript API

The package also exports an ESM/CJS API. lint runs the same validation and returns structured results without printing or exiting:

import { lint, format } from '@ladamczyk/structurelint';

const result = await lint({ path: 'src' });

result.passed; // boolean — no violations
result.root; // the validated root folder
result.violations; // Array<{ path, type: 'unexpected' | 'missing', message, expected }>

process.stdout.write(format(result)); // or format(result, true) for JSON

Additional named exports: validate, loadConfig, templateToRegex, globToRegex, isIgnored, DEFAULT_PATH, DEFAULT_IGNORE, DEFAULT_CONFIG_FILES, and the TypeScript types (IStructureConfig, IStructureRule, IRuleRef, TStructureNode, IViolation, ILintOptions, ILintResult).