Semantic Change Tracker (SCT)

Version 0.x (Experimental)

An experimental CLI tool that analyzes Git code changes to help engineers quickly understand potential risks in TypeScript/JavaScript codebases.

⚠️ This is an early-stage experimental tool. Output requires human interpretation and should not replace engineering judgment.

What This Tool Is

SCT reads git diff, parses TypeScript/JavaScript AST structures, and applies rule-based heuristics to identify:

• Changes to exported functions (potential API surface changes)
• Changes to control flow or return logic (potential behavior changes)
• Functions modified without corresponding test updates

What This Tool Is NOT

• Not a linter — Does not enforce code style or quality standards
• Not a gatekeeper — Should not be used to block commits or deployments
• Not a CI blocker — Output is advisory, not prescriptive
• Not guaranteed correct — Heuristic-based analysis may produce false positives or miss changes
• Not a replacement for code review — Human engineering judgment is required

Version Status

This tool is version 0.x and is under active development:

• APIs, output format, and behavior may change without notice
• Backward compatibility is not guaranteed
• Configuration schema may evolve

Installation

npm install
npm run build
npm link  # Optional: to use `sct` globally

Requirements:

• Node.js ≥ 18
• Git repository
• TypeScript/JavaScript codebase

Usage

Initialize Configuration

sct init

This creates a basic sct.config.json file.

Analyze Changes

sct analyze

Outputs a JSON object to stdout with detected changes and estimated risk level.

Output Structure (Example)

{
  "changeType": "ApiChange",
  "behaviorChanged": true,
  "riskLevel": "High",
  "reasons": [
    "Return behavior of HTTP methods 'get', 'post' changed",
    "No test changes detected for 'get', 'post'"
  ],
  "touchedFunctions": ["get", "post"],
  "suggestedTests": [
    "No test updates detected for API surface changes ('get', 'post')"
  ]
}

Fields:

• changeType — Detected change category (ApiChange, BehaviorChange, Refactor)
• behaviorChanged — Boolean indicating potential behavior modification
• riskLevel — Heuristic risk assessment (Low, Medium, High)
• reasons — List of detected change patterns
• touchedFunctions — Functions modified in the diff
• suggestedTests — Advisory test suggestions (may be empty)

Configuration (Optional)

Basic sct.config.json:

{
  "languages": ["ts", "js"],
  "exclude": ["**/*.spec.ts", "**/*.test.ts"],
  "domains": {
    "Order": ["order", "checkout"]
  }
}

How It Works

1. Reads git diff HEAD to find changed files
2. Parses TypeScript AST for function signatures, control flow, and export status
3. Compares before/after AST structures
4. Applies rule-based heuristics to classify changes
5. Aggregates similar changes and assigns risk scores

Detection rules are deterministic and AST-based. No AI or network calls are made.

Limitations

• Only supports TypeScript and JavaScript
• Only analyzes function-level changes (does not track variable usage, call graphs, etc.)
• Export detection may be incomplete for complex module patterns
• Risk scoring is heuristic-based and may not align with actual project risk
• No analysis of runtime behavior or type-checking correctness

License

MIT