@prata.ma/anvil-eslint

Anvil-owned ESLint plugin for governed markdown and template-schema enforcement.

Overview

@prata.ma/anvil-eslint owns the custom ESLint plugin rules and generated config presets that enforce Anvil's governed markdown conventions. It now covers both markdown structure checks and AI rule-budget enforcement, including max chars, max lines, approximate max tokens, banned heavy constructs such as fenced code blocks and tables, and a split package CHANGELOG.md rule bundle for H1, H2, H3, and change-list validation.

Within the workspace and for external consumers, this package is the home for Anvil-specific lint behavior that does not belong in the general shared config package. Consumers should use @prata.ma/anvil-eslint when they need the documented plugin and config surface instead of duplicating markdown-rule logic in package-local lint setup.

Installation

Install the package from npm when using the documented plugin surface outside this monorepo.

npm

{
  "devDependencies": {
    "@prata.ma/anvil-eslint": "^0.0.0"
  }
}

Usage

The package is used as an ESLint plugin surface. The main consumption paths are the plugin itself and the generated config groups built from catalog template schemas.

Library

import anvilEslint from '@prata.ma/anvil-eslint'

export default [
  {
    plugins: {
      anvil: anvilEslint,
    },
    rules: {
      'anvil/md-required-frontmatter': ['error', { keys: ['title'] }],
      'anvil/md-heading-starts-at': ['error', { depth: 2 }],
    },
  },
]

Patterns

Typical usage patterns include:

• applying markdown structure rules to governed docs such as rules, briefs, skills, state, and product artifacts
• using generated config groups built from authored schema definitions under @prata.ma/anvil-schema
• regenerating src/configs/generated.ts after schema changes so plugin configs stay aligned with the package-owned schema source

API

@prata.ma/anvil-eslint exposes a plugin default export with rules, metadata, and generated config groups.

Exports

• @prata.ma/anvil-eslint - default ESLint plugin export
• plugin meta with package name and version
• anvil/md-heading-starts-at
• anvil/md-max-chars
• anvil/md-max-lines
• anvil/md-max-tokens
• anvil/md-no-fenced-code-blocks
• anvil/md-no-heading-beyond
• anvil/md-no-tables
• anvil/md-changelog-h1
• anvil/md-changelog-h2
• anvil/md-changelog-h3
• anvil/md-changelog-changes
• anvil/md-required-frontmatter
• anvil/md-required-headings
• generated config groups from createConfigs(plugin), including catalogRules, briefs, changelogs, skills, state, system, product, skillAssets, and templateSchemas

Configuration

• scripts/generate-configs.ts scans @packages/anvil-schema/src/schemas/** for *.schema.yaml files.
• Template schemas are parsed through parseTemplateSchema() from @prata.ma/anvil-schema.
• catalogRules also consumes the shared harnessRuleBudget export from @prata.ma/anvil-schema so hard limits are not duplicated in lint config.
• changelogs applies the changelog H1, H2, H3, and changes rules to workspace package and versioned block-package CHANGELOG.md files.
• anvil/md-changelog-h1 resolves the expected H1 from the sibling package.json name for each CHANGELOG.md.
• anvil/md-changelog-changes validates each H3 body as a whole bullet-list block and flattens ambiguous malformed bullets into sibling top-level items by default.
• Generated configs are written to src/configs/generated.ts and consumed during build.
• build runs generate:configs before tsdown.

Development

Use the package-local scripts while working in @packages/anvil-eslint, and keep new Anvil-specific lint behavior inside this package instead of pushing it into the shared @repo/lint config package.

This package now participates in the repo's Changesets, npm publish, and GitHub Release automation as a package-scoped public surface. The package-local release:check script remains the focused validation contract for this package.

Commands

pnpm --filter @prata.ma/anvil-eslint release:check
pnpm --filter @prata.ma/anvil-eslint generate:configs
pnpm --filter @prata.ma/anvil-eslint build
pnpm --filter @prata.ma/anvil-eslint lint
pnpm --filter @prata.ma/anvil-eslint test
pnpm --filter @prata.ma/anvil-eslint test:type

Testing

The current Vitest coverage focuses on markdown-rule helper behavior, split package changelog enforcement, template-schema parsing, shared config wiring, and the AI rule-budget rule set.

Conventions

• Keep plugin rules deterministic and based on observable markdown structure rather than repo-specific heuristics.
• Keep changelog autofixes deterministic and structure-aware: H1s resolve from sibling package.json files and H3 change blocks normalize malformed list indentation without rewriting valid release prose.
• Regenerate src/configs/generated.ts whenever template-schema inputs change.
• Keep custom Anvil-owned rules here; keep general ESLint baseline concerns in @repo/lint.
• Keep shared rule-budget limits sourced from @prata.ma/anvil-schema rather than duplicating them across config groups.

Status

This package is active and currently focused on Anvil-specific markdown and template linting.

Maturity

@prata.ma/anvil-eslint is active and publish-prepared as a reusable package.

Scope

The package currently supports custom markdown rules, generated config sets for governed repo surfaces including workspace package changelogs, and template-schema parsing used to synthesize those config sets. It does not replace the shared flat-config baseline owned by @repo/lint.

Notes

• @prata.ma/anvil-eslint now ships a package CHANGELOG.md and participates in the repo's multi-package release workflow.
• The generated config file src/configs/generated.ts is build input owned by generate:configs, not a hand-maintained source of truth.
• Changes to rule behavior or schema parsing can affect governed docs across @catalog/, @product/, @system/, and @state/.