Fitness Functions skill for Claude Code

# Fitness function tool configurations

Working starting points per ecosystem. Pin tool versions in the project's lockfile and
check option names against the installed version's docs.

## TypeScript / JavaScript: dependency-cruiser

```bash
npm i -D dependency-cruiser
npx depcruise --init                      # generates .dependency-cruiser.cjs
```

```js
// .dependency-cruiser.cjs
/** @type {import('dependency-cruiser').IConfiguration} */
module.exports = {
  forbidden: [
    { name: "no-circular", severity: "error", from: {}, to: { circular: true } },
    {
      name: "domain-is-pure",
      comment: "Domain code must not depend on infrastructure or delivery layers",
      severity: "error",
      from: { path: "^src/domain" },
      to: { path: "^src/(infra|web|jobs)" },
    },
    {
      name: "no-cross-feature-internals",
      comment: "Features talk through their index.ts only",
      severity: "error",
      from: { path: "^src/features/([^/]+)/" },
      to: { path: "^src/features/([^/]+)/(?!index\\.ts$)", pathNot: "^src/features/$1/" },
    },
    { name: "no-orphans", severity: "warn", from: { orphan: true, pathNot: "\\.(d\\.ts|test\\.ts)$" }, to: {} },
    { name: "no-dev-deps-in-src", severity: "error", from: { path: "^src" }, to: { dependencyTypes: ["npm-dev"] } },
  ],
  options: {
    doNotFollow: { path: "node_modules" },
    tsConfig: { fileName: "tsconfig.json" },
    tsPreCompilationDeps: true,
  },
};
```

```bash
npx depcruise src --config .dependency-cruiser.cjs                              # gate
npx depcruise src --config .dependency-cruiser.cjs --output-type baseline \
  > .dependency-cruiser-known-violations.json                                   # freeze existing
npx depcruise src --config .dependency-cruiser.cjs --ignore-known               # fail only on new
npx depcruise src --config .dependency-cruiser.cjs --output-type json \
  | jq '{dep_violations: .summary.error}' > arch-metrics.json                   # feed ratchet.py
npx depcruise src --include-only "^src" --output-type dot | dot -T svg > deps.svg
```

Alternatives: `eslint-plugin-boundaries` (element types and allowed relations as lint
rules, good editor feedback), ESLint core `no-restricted-imports` for a handful of bans,
Nx `@nx/enforce-module-boundaries` with project tags in Nx workspaces, `madge --circular src`
for a quick cycle check.

## Java / Kotlin: ArchUnit

```xml
<dependency>
  <groupId>com.tngtech.archunit</groupId>
  <artifactId>archunit-junit5</artifactId>
  <version>1.4.1</version>
  <scope>test</scope>
</dependency>
```

```java
@AnalyzeClasses(packages = "com.acme.shop", importOptions = ImportOption.DoNotIncludeTests.class)
class ArchitectureTest {

  @ArchTest
  static final ArchRule layers = layeredArchitecture().consideringAllDependencies()
      .layer("Web").definedBy("..web..")
      .layer("Application").definedBy("..application..")
      .layer("Domain").definedBy("..domain..")
      .layer("Infrastructure").definedBy("..infrastructure..")
      .whereLayer("Web").mayNotBeAccessedByAnyLayer()
      .whereLayer("Application").mayOnlyBeAccessedByLayers("Web")
      .whereLayer("Domain").mayOnlyBeAccessedByLayers("Application", "Infrastructure")
      .whereLayer("Infrastructure").mayNotBeAccessedByAnyLayer();

  @ArchTest
  static final ArchRule noCycles = slices().matching("com.acme.shop.(*)..").should().beFreeOfCycles();

  @ArchTest
  static final ArchRule domainHasNoSpring = noClasses().that().resideInAPackage("..domain..")
      .should().dependOnClassesThat().resideInAnyPackage("org.springframework..", "jakarta.persistence..");

  // Baseline existing violations; new ones fail. Store lives in archunit_store/ (commit it).
  @ArchTest
  static final ArchRule frozenLayers = FreezingArchRule.freeze(layers);
}
```

Enable the store to shrink automatically by setting `freeze.store.default.allowStoreUpdate=true`
locally and `false` in CI (in `archunit.properties`), so CI never writes new violations
into the baseline. Spring Modulith's `ApplicationModules.of(App.class).verify()` covers
module boundaries for Spring Boot apps. Kotlin projects can use Konsist for
declaration-level rules.

## .NET: NetArchTest or ArchUnitNET

```csharp
[Fact]
public void Domain_does_not_depend_on_infrastructure()
{
    var result = Types.InAssembly(typeof(Order).Assembly)
        .That().ResideInNamespace("Shop.Domain")
        .ShouldNot().HaveDependencyOnAny("Shop.Infrastructure", "Microsoft.EntityFrameworkCore")
        .GetResult();
    Assert.True(result.IsSuccessful, string.Join(", ", result.FailingTypeNames ?? []));
}
```

Separate projects per layer with restricted `ProjectReference`s are the cheapest .NET
fitness function: the compiler enforces direction.

## Python: import-linter

```ini
# .importlinter
[importlinter]
root_package = shop
include_external_packages = True

[importlinter:contract:layers]
name = Layered architecture
type = layers
layers =
    shop.api
    shop.services
    shop.domain

[importlinter:contract:domain-pure]
name = Domain has no framework imports
type = forbidden
source_modules =
    shop.domain
forbidden_modules =
    sqlalchemy
    fastapi
    shop.infra

[importlinter:contract:features-independent]
name = Feature packages are independent
type = independence
modules =
    shop.billing
    shop.catalog
    shop.shipping
```

```bash
pip install import-linter
lint-imports                              # exits non-zero on broken contracts
```

Use `ignore_imports` in a contract to list known violations explicitly, and shrink the
list over time. Complexity: `radon cc -s -a shop` to measure, `xenon --max-absolute B
--max-modules A --max-average A shop` to gate.

## Go

- Package direction: `depguard` via golangci-lint with rules per package path, or
  `go-arch-lint` for component-level rules.
- Cycles are compile errors in Go; the remaining risks are layering and `internal/` misuse.
  Put private packages under `internal/` so the toolchain blocks outside imports.

```yaml
# .golangci.yml (excerpt; v2 config format)
linters:
  enable: [depguard]
  settings:
    depguard:
      rules:
        domain:
          files: ["**/internal/domain/**"]
          deny:
            - pkg: "database/sql"
              desc: "domain must not touch the database"
            - pkg: "net/http"
              desc: "domain must not know about HTTP"
```

## Ruby

Packwerk (`bin/packwerk check`, `package.yml` per pack with `enforce_dependencies: true`)
with `package_todo.yml` as the baseline of existing violations.

## Non-structural fitness functions

| Characteristic | Tool | Gate example |
|---|---|---|
| Bundle size | size-limit | `"limit": "180 kB"` per entry, CI fails above |
| Page performance | Lighthouse CI | `assertions: { "categories:performance": ["error", {"minScore": 0.9}] }` |
| API latency | k6 thresholds | `http_req_duration: ["p(95)<300"]` in a nightly run |
| Function complexity | ESLint `complexity`, radon/xenon, gocyclo | max 15 per function for new code |
| File size | custom script (wc) + ratchet | no file over 800 lines unless baselined |
| Dependency policy | license checkers, `npm audit --audit-level=high`, osv-scanner | zero high or critical |
| Breaking API changes | oasdiff, buf breaking | no breaking changes without a version bump |

#!/usr/bin/env python3
"""Ratchet architecture metrics: fail when any metric gets worse than its baseline.

Usage:
    python3 scripts/ratchet.py current.json baseline.json [--update] [--tolerance 0]

Both files map metric names to numbers, or to objects with "value" and optional
"better" ("lower" is the default, or "higher"):

    {"dep_violations": 42, "circular_deps": 3,
     "coverage_pct": {"value": 81.5, "better": "higher"}}

The "better" direction is read from the baseline first, then from current.

Behavior:
  - A metric worse than baseline (beyond --tolerance) fails the run (exit 1).
  - A metric in the baseline but missing from current fails (exit 1).
  - New metrics in current are reported and, with --update, added.
  - With --update and no regressions, improved values are written back to the
    baseline so the bar only moves in the good direction.

Exit codes: 0 = no regressions, 1 = regression or missing metric, 2 = bad input.
"""
import json
import sys


def load(path):
    try:
        with open(path, encoding="utf-8") as fh:
            data = json.load(fh)
    except (OSError, json.JSONDecodeError) as exc:
        print(f"error: cannot read {path}: {exc}", file=sys.stderr)
        sys.exit(2)
    if not isinstance(data, dict):
        print(f"error: {path} must be a JSON object", file=sys.stderr)
        sys.exit(2)
    out = {}
    for name, raw in data.items():
        if isinstance(raw, dict):
            value, better = raw.get("value"), raw.get("better", "lower")
        else:
            value, better = raw, None
        if not isinstance(value, (int, float)) or isinstance(value, bool):
            print(f"error: {path}: metric '{name}' is not a number", file=sys.stderr)
            sys.exit(2)
        if better not in (None, "lower", "higher"):
            print(f"error: {path}: metric '{name}' has better='{better}' (use lower|higher)", file=sys.stderr)
            sys.exit(2)
        out[name] = (float(value), better)
    return out


def main(argv):
    args = [a for a in argv[1:] if not a.startswith("--")]
    update = "--update" in argv
    tolerance = 0.0
    if "--tolerance" in argv:
        try:
            tolerance = float(argv[argv.index("--tolerance") + 1])
            args = [a for a in args if a != argv[argv.index("--tolerance") + 1]]
        except (IndexError, ValueError):
            print("error: --tolerance needs a number", file=sys.stderr)
            return 2
    if len(args) != 2:
        print(__doc__)
        return 2
    current_path, baseline_path = args
    current, baseline = load(current_path), load(baseline_path)

    regressions, improved, rows = [], {}, []
    for name, (base_val, base_better) in sorted(baseline.items()):
        if name not in current:
            regressions.append(f"{name}: missing from current metrics")
            rows.append((name, base_val, None, "MISSING"))
            continue
        cur_val, cur_better = current[name]
        better = base_better or cur_better or "lower"
        delta = cur_val - base_val
        worse = delta > tolerance if better == "lower" else -delta > tolerance
        gained = delta < 0 if better == "lower" else delta > 0
        if worse:
            regressions.append(f"{name}: {base_val:g} -> {cur_val:g} ({better} is better)")
            status = "WORSE"
        elif gained:
            improved[name] = (cur_val, better)
            status = "better"
        else:
            status = "same"
        rows.append((name, base_val, cur_val, status))

    new = {k: v for k, v in current.items() if k not in baseline}
    for name, (val, _) in sorted(new.items()):
        rows.append((name, None, val, "new"))

    width = max([len(r[0]) for r in rows] + [6])
    print(f"{'metric':<{width}}  {'baseline':>10}  {'current':>10}  status")
    for name, b, c, s in rows:
        bs = "-" if b is None else f"{b:g}"
        cs = "-" if c is None else f"{c:g}"
        print(f"{name:<{width}}  {bs:>10}  {cs:>10}  {s}")

    if regressions:
        print("\nFAIL: architecture metrics regressed:")
        for r in regressions:
            print(f"  - {r}")
        print("Fix the regression, or get explicit approval and edit the baseline in a reviewed commit.")
        return 1

    if update and (improved or new):
        merged = {}
        for name, (val, better) in {**baseline, **new, **improved}.items():
            b = better or baseline.get(name, (None, None))[1] or "lower"
            merged[name] = {"value": val, "better": b}
        with open(baseline_path, "w", encoding="utf-8") as fh:
            json.dump(merged, fh, indent=2, sort_keys=True)
            fh.write("\n")
        print(f"\nBaseline tightened: {len(improved)} improved, {len(new)} added -> {baseline_path}")
    elif improved:
        print(f"\nOK: {len(improved)} metric(s) improved; run with --update to tighten the baseline.")
    else:
        print("\nOK: no regressions.")
    return 0


if __name__ == "__main__":
    sys.exit(main(sys.argv))