@nielspeter/eess-ts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Niels Peter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,364 @@
+# @nielspeter/eess-ts
+
+[![npm version](https://img.shields.io/npm/v/@nielspeter/eess-ts)](https://www.npmjs.com/package/@nielspeter/eess-ts)
+[![CI](https://github.com/nielspeter/ts-archunit/actions/workflows/ci.yml/badge.svg)](https://github.com/nielspeter/ts-archunit/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org/)
+
+**Architecture guardrails for AI coding agents.** Executable rules that catch structural violations in CI — before they reach your codebase.
+
+Inspired by Java's [ArchUnit](https://www.archunit.org/). Powered by [ts-morph](https://ts-morph.com/).
+
+> **The TypeScript dialect of the [eess](../../README.md) family.** Formerly published as `@nielspeter/ts-archunit` — that name still works as an alias, so existing installs are unaffected. New projects should prefer `@nielspeter/eess-ts`.
+
+[Documentation](https://nielspeter.github.io/ts-archunit/) · [Getting Started](https://nielspeter.github.io/ts-archunit/getting-started) · [What Can It Check?](https://nielspeter.github.io/ts-archunit/what-to-check)
+
+## The Problem
+
+AI coding agents don't know your architecture. They generate code that compiles, passes type checks, and looks correct in isolation — but violates the structural decisions your team spent months establishing.
+
+An agent will:
+
+- Call `parseInt` instead of the shared `extractCount()` helper
+- Throw `new Error()` instead of your typed `NotFoundError`
+- Import the database driver directly from a service instead of going through the repository
+- Copy-paste a parser function instead of using the shared utility
+- Skip validation in a route handler
+
+Code review catches some of this. But at scale — with multiple agents generating PRs across a large codebase — review becomes the bottleneck. You need automated enforcement.
+
+## The Solution
+
+ts-archunit turns your architecture decisions into executable tests. They run in CI. Violations show up inline on the PR with clear messages explaining **what's wrong, why it matters, and how to fix it** — exactly the context an agent needs to self-correct.
+
+```typescript
+classes(p)
+  .that()
+  .extend('BaseRepository')
+  .should()
+  .notContain(newExpr('Error'))
+  .rule({
+    id: 'repo/typed-errors',
+    because: 'Generic Error loses context and prevents consistent error handling',
+    suggestion: 'Use NotFoundError, ValidationError, or DomainError instead',
+  })
+  .check()
+```
+
+When an agent violates this rule, it sees:
+
+```
+Architecture Violation [repo/typed-errors]
+
+  WebhookRepository.findById contains new 'Error' at line 42
+  at src/repositories/webhook.repository.ts:42
+
+      41 |     if (!result) {
+    > 42 |       throw new Error(`Webhook '${id}' not found`)
+      43 |     }
+
+  Why: Generic Error loses context and prevents consistent error handling
+  Fix: Use NotFoundError, ValidationError, or DomainError instead
+```
+
+The `because` and `suggestion` fields give the agent everything it needs to fix the violation without human intervention.
+
+## Why Not Just Import Rules?
+
+Every other tool (dependency-cruiser, eslint-plugin-boundaries, ts-arch) only checks which files import which. That's necessary but insufficient.
+
+AI agents don't violate architecture by importing wrong files. They violate it by **writing the wrong code in the right place** — inlining logic instead of delegating, using raw APIs instead of abstractions, skipping validation, throwing generic errors.
+
+ts-archunit checks what happens **inside** your functions:
+
+```typescript
+// "Services must delegate to repositories, not hardcode data"
+functions(p)
+  .that()
+  .resideInFolder('**/services/**')
+  .should()
+  .satisfy(mustCall(/Repository/))
+  .check()
+
+// "No eval anywhere in production code"
+modules(p).that().resideInFolder('src/**').should().satisfy(moduleNoEval()).check()
+
+// "Route handlers must validate input"
+functions(p)
+  .that()
+  .resideInFolder('**/handlers/**')
+  .should()
+  .satisfy(mustCall(/validate|parse/))
+  .check()
+```
+
+| Capability                                         | ts-archunit | [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) | [eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries) | [Biome](https://biomejs.dev) | [ts-arch](https://github.com/ts-arch/ts-arch) |
+| -------------------------------------------------- | ----------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------- |
+| Import path rules                                  | Yes         | Yes                                                                  | Yes                                                                                | Yes                          | Yes                                           |
+| **Body analysis** (what's called inside functions) | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| **Type checking** (string vs typed union)          | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| JSX element rules                                  | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| Cross-layer rules                                  | Yes         | No                                                                   | No                                                                                 | No                           | Partial                                       |
+| Cycle detection                                    | Yes         | Yes                                                                  | No                                                                                 | No                           | Yes                                           |
+| Code smell detection (duplicate bodies)            | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| Code metrics (cyclomatic, LOC)                     | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| Pattern matching (reusable rule templates)         | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| Baseline (gradual adoption)                        | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| Diff-aware / PR-only checking                      | Yes         | No                                                                   | No                                                                                 | No                           | No                                            |
+| Watch mode                                         | Yes         | No                                                                   | No                                                                                 | Yes                          | No                                            |
+| Inline exclusion comments                          | Yes         | No                                                                   | Via ESLint                                                                         | Yes                          | No                                            |
+| GitHub PR annotations                              | Yes         | No                                                                   | Via ESLint                                                                         | No                           | No                                            |
+
+## Quick Start with Presets
+
+One function call enforces an entire architecture pattern — layer ordering, cycles, import direction, package restrictions:
+
+```typescript
+import { project } from '@nielspeter/eess-ts'
+import { layeredArchitecture } from '@nielspeter/eess-ts/presets'
+
+const p = project('tsconfig.json')
+
+layeredArchitecture(p, {
+  layers: {
+    routes: 'src/routes/**',
+    services: 'src/services/**',
+    repositories: 'src/repositories/**',
+  },
+  shared: ['src/shared/**'],
+  strict: true,
+})
+```
+
+This generates 5 coordinated rules. Override individual rules without disabling the preset:
+
+```typescript
+layeredArchitecture(p, {
+  layers: { ... },
+  overrides: {
+    'preset/layered/type-imports-only': 'off',
+  },
+})
+```
+
+Three presets available: [`layeredArchitecture`](https://nielspeter.github.io/ts-archunit/presets), [`dataLayerIsolation`](https://nielspeter.github.io/ts-archunit/presets#datalayerisolation), [`strictBoundaries`](https://nielspeter.github.io/ts-archunit/presets#strictboundaries).
+
+## Feed Your Architecture to the Agent
+
+The `explain` command dumps all active rules as structured JSON — pipe it into your agent's system prompt so it knows the constraints before writing code:
+
+```bash
+npx ts-archunit explain arch.rules.ts
+```
+
+```json
+{
+  "rules": [
+    {
+      "id": "repo/typed-errors",
+      "rule": "that extend 'BaseRepository' should not contain new 'Error'",
+      "because": "Generic Error loses context and prevents consistent error handling",
+      "suggestion": "Use NotFoundError, ValidationError, or DomainError instead"
+    }
+  ]
+}
+```
+
+The agent reads the rules, understands the constraints, and generates compliant code from the start. When it doesn't, CI catches it with actionable violation messages.
+
+## Custom Rules
+
+The fluent API reads like English:
+
+```typescript
+// Select → Filter → Assert → Execute
+classes(p).that().extend('BaseRepository').should().notContain(call('parseInt')).check()
+```
+
+### Body Analysis
+
+Inspect what happens inside functions — the differentiator:
+
+```typescript
+// Ban inline parseInt — use the shared helper
+classes(p)
+  .that()
+  .extend('BaseRepository')
+  .should()
+  .useInsteadOf(call('parseInt'), call('this.extractCount'))
+  .check()
+
+// Services must delegate to repositories
+functions(p)
+  .that()
+  .resideInFolder('**/services/**')
+  .should()
+  .satisfy(mustCall(/Repository/))
+  .check()
+
+// No process.env in domain — use dependency injection
+functions(p).that().resideInFolder('**/domain/**').should().satisfy(functionNoProcessEnv()).check()
+```
+
+### Layer Enforcement
+
+```typescript
+slices(p)
+  .assignedFrom({
+    controllers: 'src/controllers/**',
+    services: 'src/services/**',
+    repositories: 'src/repositories/**',
+  })
+  .should()
+  .respectLayerOrder('controllers', 'services', 'repositories')
+  .check()
+
+slices(p).matching('src/features/*/').should().beFreeOfCycles().check()
+```
+
+### Type-Level Rules
+
+Check property types using the TypeScript type checker:
+
+```typescript
+types(p)
+  .that()
+  .haveProperty('orderBy')
+  .should()
+  .havePropertyType('orderBy', not(isString()))
+  .rule({
+    because: 'Bare string orderBy is a SQL injection surface',
+    suggestion: "Use a union type: orderBy?: 'created_at' | 'updated_at'",
+  })
+  .check()
+```
+
+### Standard Rules Library
+
+25+ ready-to-use rules across 8 categories:
+
+```typescript
+import {
+  functionNoEval,
+  functionNoConsole,
+  functionNoJsonParse,
+} from '@nielspeter/eess-ts/rules/security'
+import { functionNoGenericErrors } from '@nielspeter/eess-ts/rules/errors'
+import { mustCall } from '@nielspeter/eess-ts/rules/architecture'
+import { noDeadModules, noStubComments, noEmptyBodies } from '@nielspeter/eess-ts/rules/hygiene'
+
+functions(p).that().resideInFolder('src/**').should().satisfy(functionNoEval()).check()
+functions(p).that().resideInFolder('src/**').should().satisfy(noEmptyBodies()).check()
+functions(p).that().resideInFolder('src/**').should().satisfy(noStubComments()).check()
+```
+
+Categories: `rules/typescript`, `rules/security`, `rules/errors`, `rules/naming`, `rules/dependencies`, `rules/code-quality`, `rules/metrics`, `rules/architecture`, `rules/hygiene`.
+
+### Baseline Mode
+
+Adopt rules in existing codebases without fixing every pre-existing violation:
+
+```typescript
+const baseline = withBaseline('arch-baseline.json')
+
+// Only NEW violations fail — existing ones are recorded
+classes(p).should().notContain(call('parseInt')).check({ baseline })
+```
+
+### GitHub Actions Annotations
+
+Violations appear inline on PR diffs — automatically detected in GitHub Actions:
+
+```typescript
+classes(p).should().notContain(call('eval')).check({ format: detectFormat() })
+```
+
+### Smell Detection
+
+Find code drift — duplicate function bodies and inconsistent patterns:
+
+```typescript
+smells.duplicateBodies(p).inFolder('src/routes/**').withMinSimilarity(0.9).warn()
+
+smells
+  .inconsistentSiblings(p)
+  .inFolder('src/repositories/**')
+  .forPattern(call('this.extractCount'))
+  .warn()
+```
+
+### More Features
+
+- **[Call matching](https://nielspeter.github.io/ts-archunit/calls)** — framework-agnostic route/handler inspection (Express, Fastify, Hono)
+- **[Scoped rules](https://nielspeter.github.io/ts-archunit/body-analysis)** — `within(routes).functions()` for callback-level rules
+- **[Pattern templates](https://nielspeter.github.io/ts-archunit/patterns)** — enforce return type shapes (`{ items, total, skip, limit }`)
+- **[GraphQL rules](https://nielspeter.github.io/ts-archunit/graphql)** — schema and resolver conventions
+- **[Cross-layer validation](https://nielspeter.github.io/ts-archunit/cross-layer)** — route/schema/SDK consistency
+- **[Custom predicates and conditions](https://nielspeter.github.io/ts-archunit/custom-rules)** — `definePredicate()`, `defineCondition()`, `and`/`or`/`not` combinators
+- **[Metrics](https://nielspeter.github.io/ts-archunit/metrics)** — cyclomatic complexity, lines of code, method count limits
+- **[CLI](https://nielspeter.github.io/ts-archunit/cli)** — `check`, `baseline`, `explain`, `--watch` mode
+
+## Entry Points
+
+| Function       | Operates on                               | Use case                                        |
+| -------------- | ----------------------------------------- | ----------------------------------------------- |
+| `modules(p)`   | Source files                              | Import/dependency rules                         |
+| `classes(p)`   | Class declarations                        | Inheritance, decorators, methods, body analysis |
+| `functions(p)` | Functions, arrow functions, class methods | Naming, parameters, body analysis               |
+| `types(p)`     | Interfaces + type aliases                 | Property types, type safety                     |
+| `slices(p)`    | Groups of files                           | Cycles, layer ordering                          |
+| `calls(p)`     | Call expressions                          | Framework-agnostic route/handler matching       |
+| `within(sel)`  | Scoped callbacks                          | Rules inside matched call callbacks             |
+
+## Compared to Other Tools
+
+| Capability                                        | ts-archunit     | [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) | [ArchUnitTS](https://github.com/LukasNiessen/ArchUnitTS) | [Biome](https://biomejs.dev) | [ts-arch](https://github.com/ts-arch/ts-arch) |
+| ------------------------------------------------- | --------------- | -------------------------------------------------------------------- | -------------------------------------------------------- | ---------------------------- | --------------------------------------------- |
+| Import path rules                                 | Yes             | Yes                                                                  | Yes                                                      | Yes (`noRestrictedImports`)  | Yes                                           |
+| **Body analysis** (calls, access, constructors)   | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| **Type checking** (resolved types via ts-morph)   | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Class rules (inheritance, decorators, members)    | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Function rules (params, return types, async)      | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| JSX element rules                                 | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Cross-layer rules (pair-condition per layer)      | Yes             | No                                                                   | No                                                       | No                           | Partial (layered slices)                      |
+| Cycle detection                                   | Yes             | Yes                                                                  | Yes                                                      | No                           | Yes                                           |
+| Parameterized presets                             | Yes             | Flat config                                                          | No                                                       | No                           | No                                            |
+| Pattern matching (reusable rule templates)        | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Code smell detection (duplicate bodies, siblings) | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Code metrics                                      | Cyclomatic, LOC | No                                                                   | LCOM, coupling, instability                              | No                           | No                                            |
+| Baseline / gradual adoption                       | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Diff-aware / PR-only checking                     | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Watch mode                                        | Yes             | No                                                                   | No                                                       | Yes                          | No                                            |
+| Inline exclusion comments                         | Yes             | No                                                                   | No                                                       | Yes (`biome-ignore`)         | No                                            |
+| JSON output format                                | Yes             | Yes                                                                  | Via vitest                                               | Yes                          | Via test runner                               |
+| GitHub PR annotations                             | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| Violation messages with fix suggestions           | Yes             | No                                                                   | No                                                       | Partial (autofixes)          | No                                            |
+| `explain` command (dump rules as JSON for agents) | Yes             | No                                                                   | No                                                       | No                           | No                                            |
+| PlantUML diagram compliance                       | No              | No                                                                   | Yes                                                      | No                           | No                                            |
+| Dependency graph visualization                    | No              | Yes (dot, HTML)                                                      | No                                                       | No                           | No                                            |
+| License checking                                  | No              | Yes                                                                  | No                                                       | No                           | No                                            |
+| Nx monorepo support                               | No              | No                                                                   | Yes                                                      | No                           | No                                            |
+
+**Use ts-archunit** when you need to enforce what happens _inside_ functions — call patterns, error types, missing delegation, stub comments — and when AI agents are generating code that needs architectural guardrails. This is the only tool that catches "service calls parseInt instead of extractCount()", flags duplicate function bodies as smells, and can restrict checking to only the files changed in a PR.
+
+**Use dependency-cruiser** when you only need import direction rules and want fast graph visualization, license compliance checking, or stability metrics. It's faster (no ts-morph project load) and has mature HTML/dot reporting.
+
+**Use ArchUnitTS** when you need OO metrics (LCOM cohesion, coupling factor, distance from main sequence), PlantUML diagram validation, or Nx monorepo project-graph awareness.
+
+**Use Biome** when you want a fast Rust-based lint + format toolchain and only need lint-level import restrictions (`noRestrictedImports`) — not architecture rules over class hierarchies, function bodies, or slice cycles. Pair it with ts-archunit if you want both.
+
+**Use ts-arch** when you want the classic ArchUnit-style fluent API scoped to file/folder dependency rules and layered slices, and don't need body analysis, type-checker rules, or CI integrations like baselines, diff-aware runs, or GitHub annotations.
+
+**Use ts-archunit + dependency-cruiser together** if you want both body-level enforcement and dependency graph visualization.
+
+## Install
+
+```bash
+npm install -D @nielspeter/eess-ts
+```
+
+Requires Node.js >= 24 and a `tsconfig.json`. Works with vitest (recommended) or jest.
+
+## License
+
+MIT

package/dist/builders/call-rule-builder.d.ts

@@ -0,0 +1,199 @@
+import type { ArchProject } from '../core/project.js';
+import { RuleBuilder } from '@nielspeter/eess';
+import type { ConditionContext } from '@nielspeter/eess';
+import type { ExpressionMatcher } from '../helpers/matchers.js';
+import type { ArchCall } from '../models/arch-call.js';
+/**
+ * Rule builder for call-expression-level architecture rules.
+ *
+ * Operates on CallExpression nodes across all source files,
+ * wrapped in the ArchCall model for uniform predicate access.
+ *
+ * @example
+ * ```typescript
+ * // All Express route handlers must call handleError()
+ * calls(project)
+ *   .that().onObject('app')
+ *   .and().withMethod(/^(get|post|put|delete|patch)$/)
+ *   .should().haveCallbackContaining(call('handleError'))
+ *   .because('unhandled errors crash the server')
+ *   .check()
+ *
+ * // No route may call db.query() directly
+ * calls(project)
+ *   .that().onObject('app')
+ *   .and().withMethod(/^(get|post|put|delete|patch)$/)
+ *   .should().notHaveCallbackContaining(call('db.query'))
+ *   .because('use repository methods instead')
+ *   .check()
+ *
+ * // Select specific routes by path pattern
+ * calls(project)
+ *   .that().onObject('router')
+ *   .and().withMethod('get')
+ *   .and().withStringArg(0, '/api/users/**')
+ *   .should().haveCallbackContaining(call('authenticate'))
+ *   .check()
+ * ```
+ */
+export declare class CallRuleBuilder extends RuleBuilder<ArchCall, ArchProject> {
+    /**
+     * Argument index to fold into the violation element/message. Set by
+     * `.identifiedByArg(index)`. Threaded into `ConditionContext.identifyByArgument`
+     * so the eight `archCall.getName()` sites in `src/conditions/call.ts`
+     * can build identity-keyed violation strings.
+     *
+     * Survives `fork()` via `Object.assign(fork, this)` in the base class
+     * (primitive field; no explicit copy needed). See plan 0057.
+     */
+    protected _identifyByArgument?: number;
+    protected getElements(): ArchCall[];
+    protected buildConditionContext(): ConditionContext;
+    /**
+     * Filter to calls whose callee name matches the pattern.
+     * A string is compiled to a RegExp. For `app.get(...)` the name is `app.get`.
+     */
+    haveNameMatching(pattern: RegExp | string): this;
+    /** Filter to calls whose callee name starts with the given prefix. */
+    haveNameStartingWith(prefix: string): this;
+    /** Filter to calls whose callee name ends with the given suffix. */
+    haveNameEndingWith(suffix: string): this;
+    /** Filter to calls in a file whose absolute path matches the glob. */
+    resideInFile(glob: string): this;
+    /** Filter to calls in a folder whose path matches the glob. */
+    resideInFolder(glob: string): this;
+    /**
+     * Filter to method calls on the object with the exact given name.
+     * For `app.get(...)` use `onObject('app')`; for `router.route.get(...)`
+     * use `onObject('router.route')`. Optional chaining is normalized.
+     */
+    onObject(name: string): this;
+    /**
+     * Filter to calls whose method name matches. Accepts an exact string
+     * or a regex; also matches bare function calls (`handleError(...)`).
+     */
+    withMethod(nameOrRegex: string | RegExp): this;
+    /**
+     * Filter to calls whose argument at `index` matches the pattern, tested
+     * against the argument's source text (so it matches identifiers and
+     * expressions, not just string literals).
+     */
+    withArgMatching(index: number, pattern: string | RegExp): this;
+    /**
+     * Filter to calls whose argument at `index` is a string literal whose
+     * value matches the glob. Non-literal arguments (variables, expressions)
+     * never match.
+     */
+    withStringArg(index: number, glob: string): this;
+    /**
+     * Fold the indexed argument's source text into the violation
+     * `element` and `message`, so identity-keyed registrations (HTTP
+     * routes, event handlers, registry entries, etc.) can be excluded
+     * individually rather than only by file.
+     *
+     * When the indexed argument is a `StringLiteral` or
+     * `NoSubstitutionTemplateLiteral`, the violation reads
+     * `` `${callee}(${rawText})` `` (e.g. `app.post("/auth/token")`).
+     * Otherwise (template with substitutions, `as const`, parenthesized,
+     * identifier, spread, out-of-bounds, non-string literal) it degrades
+     * gracefully to the bare `${callee}` form.
+     *
+     * **Identity scope — predicates see the bare callee.** This method
+     * affects violation output and `.excluding()` matching only;
+     * predicates that read `archCall.getName()` (e.g. `haveNameMatching`,
+     * `haveNameStartingWith`) continue to see the bare `app.post`. To
+     * filter by argument value, use `.withStringArg(i, glob)` or
+     * `.withArgMatching(i, pattern)`.
+     *
+     * @example Filtering by path AND naming each violation by path:
+     * ```ts
+     * calls(p).that()
+     *   .onObject('app').withMethod(/^(get|post)$/)
+     *   .withStringArg(0, '/auth/**')     // filter: only /auth routes
+     *   .identifiedByArg(0)                // identity: name violations by path
+     *   .should().haveArgumentWithProperty('preHandler')
+     *   .excluding(/"\/auth\/(login|register)"/)
+     *   .check()
+     * ```
+     *
+     * @example Footgun — predicates do NOT see the enriched name:
+     * ```ts
+     * // This produces ZERO violations regardless of source — the
+     * // predicate sees bare "app.post", which never matches the regex.
+     * calls(p).that()
+     *   .haveNameMatching(/app\.post\("\/auth/)   // <-- never matches
+     *   .identifiedByArg(0)
+     *   .should()...
+     * ```
+     *
+     * See proposal 011 / plan 0057 for the full design, the 8-case
+     * generic-pattern table, and the edge-case behavior matrix.
+     *
+     * @param index — zero-based argument index to fold into the identity.
+     */
+    identifiedByArg(index: number): this;
+    /**
+     * Assert that the call's callback argument(s) contain a match.
+     */
+    haveCallbackContaining(matcher: ExpressionMatcher): this;
+    /**
+     * Assert that the call's callback argument(s) do NOT contain a match.
+     */
+    notHaveCallbackContaining(matcher: ExpressionMatcher): this;
+    /**
+     * The filtered call set must be empty.
+     */
+    notExist(): this;
+    /**
+     * Assert that at least one object literal argument has ALL named properties.
+     */
+    haveArgumentWithProperty(...names: string[]): this;
+    /**
+     * Assert that NO object literal argument has ANY of the named properties.
+     */
+    notHaveArgumentWithProperty(...names: string[]): this;
+    /**
+     * Assert that at least one argument subtree contains a match.
+     *
+     * Searches ALL arguments recursively — a superset of `haveCallbackContaining`.
+     * Use `haveCallbackContaining` when you only want to search callback bodies.
+     */
+    haveArgumentContaining(matcher: ExpressionMatcher): this;
+    /**
+     * Assert that NO argument subtree contains a match.
+     *
+     * Searches ALL arguments recursively — a superset of `notHaveCallbackContaining`.
+     * Use `notHaveCallbackContaining` when you only want to search callback bodies.
+     */
+    notHaveArgumentContaining(matcher: ExpressionMatcher): this;
+    /**
+     * Get the underlying ArchProject.
+     * Used by within() to create scoped builders.
+     */
+    getProject(): ArchProject;
+    /**
+     * Get the ArchCall elements that match the current predicate chain.
+     * Used by within() to extract callbacks from matched calls.
+     */
+    getMatchedCalls(): ArchCall[];
+}
+/**
+ * Entry point for call-expression architecture rules.
+ *
+ * Scans all source files in the project for CallExpression nodes
+ * and wraps them in ArchCall for predicate/condition evaluation.
+ *
+ * @example
+ * ```typescript
+ * import { project, calls, call } from '@nielspeter/eess-ts'
+ *
+ * const p = project('tsconfig.json')
+ *
+ * calls(p)
+ *   .that().onObject('app').and().withMethod('get')
+ *   .should().haveCallbackContaining(call('authenticate'))
+ *   .check()
+ * ```
+ */
+export declare function calls(p: ArchProject): CallRuleBuilder;
+//# sourceMappingURL=call-rule-builder.d.ts.map

package/dist/builders/call-rule-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-rule-builder.d.ts","sourceRoot":"","sources":["../../src/builders/call-rule-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAA;AAyBtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,eAAgB,SAAQ,WAAW,CAAC,QAAQ,EAAE,WAAW,CAAC;IACrE;;;;;;;;OAQG;IACH,SAAS,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAEtC,SAAS,CAAC,WAAW,IAAI,QAAQ,EAAE;cAIhB,qBAAqB,IAAI,gBAAgB;IAS5D;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIhD,sEAAsE;IACtE,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI1C,oEAAoE;IACpE,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIxC,sEAAsE;IACtE,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIhC,+DAA+D;IAC/D,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IASlC;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5B;;;OAGG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI9C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAI9D;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAOpC;;OAEG;IACH,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAIxD;;OAEG;IACH,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAI3D;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;OAEG;IACH,wBAAwB,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIlD;;OAEG;IACH,2BAA2B,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI;IAIrD;;;;;OAKG;IACH,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAIxD;;;;;OAKG;IACH,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAM3D;;;OAGG;IACH,UAAU,IAAI,WAAW;IAIzB;;;OAGG;IACH,eAAe,IAAI,QAAQ,EAAE;CAG9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,eAAe,CAErD"}