@owlmeans/code-structure

Checker and codemods for the OwlMeans code-structure rules:

• types and interfaces live in types.ts (types.local.ts for the package-private ones);
• constants and enums live in consts.ts (consts.local.ts);
• code lives in every other file and declares no type, enum or constant of its own;
• helpers are factory-built objects, entity logic is a model over a plain record.

The rules and the reasons are in the owlmeans-code-structure skill (shipped with this package).

Install

bun add -d @owlmeans/code-structure@^0.1.18-rc.0

Add a root script and, for Claude Code, the hook:

{ "scripts": { "check:structure": "owlmeans-structure check" } }

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit",
  "hooks": [ { "type": "command", "command": "owlmeans-structure hook" } ] } ] } }

Configure

.owlmeans-structure.json at the repo root (all keys optional):

{
  "include": ["packages/*/src/**/*.{ts,tsx}"],
  "exclude": [],
  "relaxed": ["packages/library/src/skills/**"],
  "baseline": ".owlmeans-structure.baseline.json",
  "standaloneLimit": 3
}

relaxed paths may keep package-private types and constants beside their code and are not held to the standalone-function limit. Tests, build/, dist/, agent-meta/, fixtures/ and *.d.ts are always excluded.

Commands

| Command | Does | |---|---| | owlmeans-structure check [files…] [--strict] [--json] | reports violations; with a baseline file only those beyond it | | owlmeans-structure check --update-baseline | records today's violations as tolerated | | owlmeans-structure hook | PostToolUse hook: reads the event on stdin, reports the edited file | | owlmeans-structure split --slot <dir> --repos a,b [--apply] | moves types and constants out of code files, rewriting every importer | | owlmeans-structure convert --slot <dir> --repos a,b [--apply] | groups the standalone functions of non-public modules into factory-built helpers | | owlmeans-structure api --snapshot f.json / --diff f.json | public surface of every package before/after a change |

Rules reported: exported-type-in-code, exported-const-in-code, local-type-in-code, local-const-in-code, code-in-types, code-in-consts, type-in-consts, const-in-types, standalone-functions. A declaration is exempted with // owlmeans-structure: allow <reason> on the line above it, a file with /* owlmeans-structure: allow-file <reason> */.

How it reads code

The parser is the TypeScript syntax tree shipped inside ts-morph, so it works under TypeScript 7 (which has no JavaScript API) and needs no program or type information. See the skill's reference.md for what counts as a constant, as state and as code.