npm package: @furkanakinci/contract-unit-test-maintainer
Description: Contract-driven, LLM-assisted test maintenance CLI for Node/TS backends
Latest version: 0.2.8

[![npm version](https://img.shields.io/npm/v/%40furkanakinci%2Fcontract-unit-test-maintainer.svg)](https://www.npmjs.com/package/@furkanakinci/contract-unit-test-maintainer)

Status: In development (early preview)

This CLI is an academic/research prototype and intended for academic purposes. It is not production-ready; APIs and behavior may change, and results may vary. Use at your own risk.

Contract-driven, LLM-assisted test maintenance CLI.

---
# @furkanakinci/contract-unit-test-maintainer (cutm)

Minimal CLI that adapts existing Jest tests to function contract (signature / params / return shape / JSDoc) changes. It does NOT create new tests; it only patches existing tests.

## 1. Install
```bash
npm install --save-dev @furkanakinci/contract-unit-test-maintainer
export OPENAI_API_KEY=sk-...   # required for LLM patching
```

> Quick experiment run (uses default scripts/ outputs):
```bash
npx cutm experiment --out-dir scripts
```

## 2. Requirements
- Node 18+ (20+ recommended)
- Jest 29+ (tests already runnable)
- Git repository (clean working tree recommended for applying patches)

### 2.1 Unit-only Jest config (required)
cutm uses a dedicated Jest configuration for unit tests only.
- Default file name: `jest-unit.json` (repository root)
- Quick start:
  ```bash
  cp jest.config.json jest-unit.json   # start from your existing config
  # or create a minimal new jest-unit.json for unit scope only
  ```
- Alternative: if the file name differs, set via env:
  ```bash
  export CUTM_JEST_CONFIG=jest.config.json
  ```

## 3. Workflow
```bash
# 1) Initial extraction & baseline
npx cutm extract
cp scripts/function-signatures.json scripts/function-signatures-base.json

# 2) Make a function contract change (signature / param / return shape / JSDoc)

# 3) Detect changes
npx cutm check   # exit code 2 => contract change

# 4) Preview maintenance (dry)
npx cutm maintain

# 5) Apply patches + iterative repair
npx cutm maintain --apply

# 6) Accept new baseline if changes are intentional
cp scripts/function-signatures.json scripts/function-signatures-base.json
```
Commit: updated tests + new baseline together.

## 4. Common Commands
| Command | Purpose |
|---------|---------|
| `cutm extract` | Produce current function signatures |
| `cutm check` | Compare against baseline (exit 0 / 2) |
| `cutm maintain` | Generate patches (dry) |
| `cutm maintain --apply` | Apply patches + iterative failing test repair |

Exit codes: 0 = success / no change, 2 = contract change, other = error.

## 5. Output (default `scripts/`)
- `function-signatures.json` (current)
- `function-signatures-base.json` (baseline)
- `change-combined-report.json` (diff report)
- `llm-patches/*.patch` (saved diffs)

## 6. Simple CI Example
```bash
npx cutm extract
npx cutm check || STATUS=$?
if [ "$STATUS" = 2 ]; then
  echo "Contract changes detected" >&2
  npx cutm maintain --apply || true
  exit 2
fi
exit $STATUS
```
When exit 2 occurs in a PR, review changes and (if OK) accept baseline.

## 7. Key ENV Vars
| Var | Default | Note |
|-----|---------|------|
| OPENAI_API_KEY | (none) | Required |
| OPENAI_MODEL | gpt-5-mini | Model name (temperature auto-omitted if unsupported) |
| CUTM_OUTPUT_DIR | scripts | Output dir |
| CUTM_SOURCE_GLOB | src/app/**/*.ts | Source glob(s) |
| CUTM_TEST_GLOB | src/tests/**/*.test.ts | Test glob |
| LLM_MAX_FIX_ROUNDS | 3 | Repair rounds |
| LLM_IMMEDIATE_RETEST | 1 | Re-run each patched failing test immediately |
| LLM_ALLOW_SOURCE_EDITS | 1 | Set 0 to forbid source edits |

### Additional ENV Vars
- CUTM_JEST_CONFIG: Unit test Jest config path (default: `jest-unit.json`).
- OPENAI_BASE_URL, OPENAI_ORG, OPENAI_PROJECT: OpenAI client advanced settings.
- CTM_IMPORT_TEST_SCAN: 1 → optional advanced test scanning (default off).
- CTM_FAILING_TESTS_FALLBACK: 1 → target failing unit tests if no related test found.
- LLM_MAX_FILE_CHARS (default 8000), LLM_MAX_CONTEXT_CHARS (default 120000).
- LLM_MAX_RETRIES (default 3), LLM_RETRY_BASE_MS (default 2000), LLM_TEMPERATURE (default 0; gpt-5-* for automatic skipping).

Custom globs:
```bash
export CUTM_SOURCE_GLOB="src/core/**/*.ts,src/modules/**/*.ts"
export CUTM_TEST_GLOB="tests/**/*.spec.ts"
```

## 8. Accepting Changes
```bash
cp scripts/function-signatures.json scripts/function-signatures-base.json
```
Commit after tests are green.

## 9. Limitations
- Does NOT generate new test files.
- Jest focused.
- Return object key extraction is shallow (complex dynamic shapes may be missed).

## 10. Quick Troubleshooting
| Symptom | Quick Fix |
|---------|-----------|
| `No impacted files` | Change not on an exported function; verify export/globs |
| Patch not applied | Dirty working tree or git apply conflict |
| Still failing loops | Behavioral change → edit test manually |
| Missing `token` etc. | Return key renamed → update test + accept baseline |
| `[cutm:experiment] Required unit test config not found: .../jest-unit.json` | Create `jest-unit.json` at repo root or set `CUTM_JEST_CONFIG=jest.config.json` |

---
### Local development & link
```bash
# build + global link
npm run build
npm link
# in target project
npm link @furkanakinci/contract-unit-test-maintainer
```
Designed to stay small & direct. For deeper internals consult previous detailed docs.