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

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):

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:

  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:

  export CUTM_JEST_CONFIG=jest.config.json

3. Workflow

# 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

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:

export CUTM_SOURCE_GLOB="src/core/**/*.ts,src/modules/**/*.ts"
export CUTM_TEST_GLOB="tests/**/*.spec.ts"

8. Accepting Changes

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

# 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.