Shapelint

Enforce code architecture conventions so AI-generated code is predictable, not spaghetti.

Overview

Shapelint is a deterministic, AST-based linter for your codebase's shape — file structure, naming, placement, imports, body order, and member contracts.

It complements ESLint and tsc (it never duplicates what they already catch) and acts as an unyielding architectural gate that AI coding assistants and team members cannot slip past.

• 100% Framework Agnostic — Zero hardcoded framework assumptions. Enforce structural conventions across React, Next.js, Vue, Svelte, Angular, NestJS, Express, Node.js, or vanilla TypeScript.
• Deterministic Core — The default check is 100% static: reproducible, lightning fast, zero token cost, and safe to block CI builds.
• Declare Shape by Example — Describe expected file structure with intuitive pattern templates, not fragile regular expressions.
• Mechanical Autofix — shapelint fix renames symbols, rewrites import forms, moves misplaced files, and scaffolds conforming files.
• Optional Semantic (AI) Tier — A provider-agnostic judge for the few conventions that resist static encoding; strictly opt-in and non-blocking by default.

Installation

pnpm add -D shapelint
# or
npm install -D shapelint
# or
yarn add -D shapelint
# or
bun add -d shapelint

This installs the shapelint CLI (also aliased as shape) and typed defineConfig / defineRule helpers.

Quick Start

1. Initialize Configuration

Create shapelint.config.ts in your project root (or run shapelint init to scaffold one):

import { defineConfig } from 'shapelint';

export default defineConfig({
  root: 'src',
  rules: [
    // Frontend: Enforce component shape and naming
    {
      name: 'ui-component',
      files: 'components/ui/**/*.tsx',
      exclude: ['**/*.test.tsx', '**/*.stories.tsx'],
      pattern: `
        interface IProps {}

        const $Name: React.FC<IProps> = () => {}

        export default $Name
      `,
      filename: '$Name.tsx',
    },

    // Backend: Enforce controller naming & decorator contracts
    {
      name: 'api-controller',
      files: 'controllers/**/*.controller.ts',
      pattern: '@Controller($_) export class ${Name}Controller {}',
      filename: '$name.controller.ts',
    },
  ],
});

Note: The configuration is loaded with jiti, so TypeScript configs work instantly with zero precompilation step. .js and .mjs configs are also supported.

2. Run Shapelint

# Check repository against your architectural rules
shapelint check

# Apply mechanical autofixes (dry-run by default)
shapelint fix

# Run with optional semantic AI judge
shapelint check --semantic

CLI Reference

| Command | Description | | :--- | :--- | | shapelint check | Lint the repository against configured rules. | | shapelint fix | Apply mechanical autofixes (verify-and-rollback, dry-run by default). | | shapelint new <rule> <Name> | Scaffold a conforming file from a rule's pattern template. | | shapelint explain <file> | Display which rule governs a file and the underlying rationale. | | shapelint init | Generate a starter shapelint.config.ts. | | shapelint baseline | Grandfather existing violations for seamless incremental adoption. |

Suppressions

When an exception is genuinely required, suppress a finding inline (a reason is mandatory):

// shapelint-disable-next-line ui-component -- legacy component, TICKET-123

Semantic (AI) Tier

For subjective conventions that resist static analysis ("is this component purely presentational with no business logic?"), configure a provider-agnostic judge — either an async function or a CLI tool:

export default defineConfig({
  judge: { command: 'claude -p' }, // any CLI reading stdin and writing JSON to stdout
  rules: [
    {
      name: 'ui-primitive',
      files: 'components/ui/**/*.tsx',
      semantic: 'A UI primitive must be presentational only — no data fetching or side effects.',
    },
  ],
});

Verdicts are cached by content hash in .shapelint/semantic-cache.json so unchanged files never re-call the model.

Documentation

Comprehensive guides, configuration references, and concept deep-dives are available in the Documentation (or under docs/).

Contributing

Contributions are welcome! Please read the Contributing Guide for development setup and pull request instructions.

Security

To report security vulnerabilities, please refer to our Security Policy.

License

MIT © 2026 Tahir Saeed & Shapelint contributors