@stackbilt/classify

Heuristic change classification for Charter Kit -- a local-first governance toolkit for software repos. Classifies changes as SURFACE, LOCAL, or CROSS_CUTTING using pure pattern matching. No LLM calls, runs in under 5 ms.

Want the full toolkit? Just install the CLI — it includes everything:

npm install -g @stackbilt/cli

Only install this package directly if you need change classification without the CLI.

Install

npm install @stackbilt/classify

Usage

import { heuristicClassify, determineRecommendation } from '@stackbilt/classify';

const result = heuristicClassify('fix typo in readme');
// {
//   suggestedClass: 'SURFACE',
//   confidence: 'HIGH',
//   signals: ['Surface pattern: ...', 'Surface pattern: ...']
// }

const recommendation = determineRecommendation('CROSS_CUTTING', 'CLEAR', true);
// 'APPROVE_WITH_MITIGATIONS'

API Reference

heuristicClassify(subject: string)

Classifies a change description by matching against built-in pattern sets.

Returns { suggestedClass: ChangeClass, confidence: 'HIGH' | 'MEDIUM' | 'LOW', signals: string[] }

| ChangeClass | Meaning | Example triggers | |---|---|---| | SURFACE | Cosmetic or documentation-only | readme, doc, typo, spelling, rename, .md/.txt/.json | | CROSS_CUTTING | Multi-system or architectural | schema, API, migration, auth, infrastructure, integration | | LOCAL | Single-module (default) | No strong pattern match detected |

Confidence is HIGH when two or more patterns match, MEDIUM for one, LOW when defaulting to LOCAL.

determineRecommendation(changeClass, governanceStatus, mitigationsRequired)

Returns APPROVE, APPROVE_WITH_MITIGATIONS, REJECT, or ESCALATE based on classification context.

formatChangeClassification(classification: ChangeClassification)

Renders a full classification as human-readable Markdown.

Requirements

• Node >= 18
• Peer dependency: @stackbilt/types

License

Apache-2.0

Links

• Repository
• Issues