open-index/open-npm huggingface dataset:
npm package: @stackbilt/ci
Description: GitHub Actions adapter for Charter governance checks
Latest version: 0.10.0

# @stackbilt/ci

GitHub Actions integration helpers for [Charter Kit](https://github.com/Stackbilt-dev/charter) -- a local-first governance toolkit for software repos.

> **Want the full toolkit?** Just install the CLI — it includes everything:
> ```bash
> npm install -g @stackbilt/cli
> ```
> Only install this package directly if you need GitHub Actions helpers without the CLI.

## Install

```bash
npm install @stackbilt/ci
```

## Usage

### Write Actions outputs and summaries

```ts
import { setOutput, setSummary } from '@stackbilt/ci';

setOutput('governance-status', 'PASS');
setSummary('## Governance check passed\nNo violations detected.');
```

### Annotate drift violations

```ts
import { annotateDriftViolations } from '@stackbilt/ci';

// Emits ::warning:: or ::error:: annotations inline on PR diffs.
// BLOCKER/CRITICAL severity = error; others = warning.
annotateDriftViolations(violations);
```

### Annotate validation status

```ts
import { annotateValidationStatus } from '@stackbilt/ci';

annotateValidationStatus('FAIL', 'Missing required Governed-By trailer');
```

### Format a PR comment

```ts
import { formatPRComment } from '@stackbilt/ci';

const body = formatPRComment({
  status: 'WARN',
  summary: '2 drift violations detected',
  violations,
  suggestions: ['Pin axios to the blessed version'],
  score: 0.85,
});
```

## API Reference

### `setOutput(name, value): void`

Appends `name=value` to `$GITHUB_OUTPUT`. No-op outside Actions.

### `setSummary(markdown): void`

Appends markdown to `$GITHUB_STEP_SUMMARY`. No-op outside Actions.

### `annotateDriftViolations(violations: DriftViolation[]): void`

Emits `::error::` / `::warning::` for each violation with file and line number.

### `annotateValidationStatus(status, summary): void`

Emits `::error::` for FAIL, `::warning::` for WARN, nothing for PASS.

### `formatPRComment(result): string`

Formats governance results as a markdown PR comment with status, violations table (max 20), and suggestions.

## Requirements

- Node >= 18
- Peer dependency: `@stackbilt/types`

## License

Apache-2.0

## Links

- [Repository](https://github.com/Stackbilt-dev/charter)
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
npm package: @stackbilt/classify
Description: Heuristic change classification (SURFACE/LOCAL/CROSS_CUTTING)
Latest version: 0.10.0

# @stackbilt/classify

Heuristic change classification for [Charter Kit](https://github.com/Stackbilt-dev/charter) -- 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:
> ```bash
> npm install -g @stackbilt/cli
> ```
> Only install this package directly if you need change classification without the CLI.

## Install

```bash
npm install @stackbilt/classify
```

## Usage

```ts
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](https://github.com/Stackbilt-dev/charter)
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
npm package: @stackbilt/core
Description: Core schemas, sanitization, and error handling for Charter Kit
Latest version: 0.10.0

# @stackbilt/core

Zod schemas and sanitization helpers for [Charter Kit](https://github.com/Stackbilt-dev/charter) -- a local-first governance toolkit for software repos.

> **Want the full toolkit?** Just install the CLI — it includes everything:
> ```bash
> npm install -g @stackbilt/cli
> ```
> Only install this package directly if you need schemas and sanitizers without the CLI.

## Install

```bash
npm install @stackbilt/core
```

Requires Node >= 18. The only runtime dependency is [zod](https://github.com/colinhacks/zod).

## Usage

### Sanitize user input

```ts
import { sanitizeInput } from '@stackbilt/core';

const clean = sanitizeInput(rawUserInput);
```

### Safe error messages

`sanitizeErrorMessage` maps known error patterns (database, network, auth) to user-friendly messages and returns a generic fallback for anything unrecognized. Internal details are never exposed to callers.

```ts
import { sanitizeErrorMessage } from '@stackbilt/core';

try {
  await riskyOperation();
} catch (err) {
  const message = sanitizeErrorMessage(err);
  // "Database constraint violated", "Network error - please retry", etc.
}
```

### Validate governance data with Zod schemas

```ts
import { CreateLedgerEntrySchema, CreatePatternSchema } from '@stackbilt/core';

const result = CreateLedgerEntrySchema.safeParse(payload);
if (!result.success) {
  console.error(result.error.issues);
}
```

## API Reference

### Functions

| Export | Signature | Description |
|---|---|---|
| `sanitizeInput` | `(input: string) => string` | Strip control characters and enforce length limit |
| `sanitizeErrorMessage` | `(error: unknown) => string` | Return a safe, user-facing error message |

### Schemas

| Schema | Purpose |
|---|---|
| `CreateLedgerEntrySchema` | Validate new ledger entries (rulings, ADRs, policies, notary stamps) |
| `UpdateLedgerStatusSchema` | Validate status transitions (`ACTIVE`, `SUPERSEDED`, `ARCHIVED`) |
| `CreatePatternSchema` | Validate new blessed-stack patterns |
| `UpdatePatternSchema` | Validate pattern updates |
| `CreateProtocolSchema` | Validate governance protocols |
| `CreateGovernanceRequestSchema` | Validate governance requests |
| `ResolveGovernanceRequestSchema` | Validate request resolutions |
| `CreateProjectSchema` | Validate new project definitions |

Each schema also exports an inferred TypeScript type (e.g., `CreateLedgerEntryRequest`, `CreatePatternRequest`).

## License

Apache-2.0

## Links

- [Repository](https://github.com/Stackbilt-dev/charter)
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
npm package: @stackbilt/drift
Description: Drift scanner — detects codebase divergence from governance patterns
Latest version: 0.10.0

# @stackbilt/drift

Blessed-stack drift detection for [Charter Kit](https://github.com/Stackbilt-dev/charter) -- a local-first governance toolkit for software repos. Scans source files against anti-patterns defined in `.charter/patterns/*.json` and produces a drift score with per-line violation details.

> **Want the full toolkit?** Just install the CLI — it includes everything:
> ```bash
> npm install -g @stackbilt/cli
> ```
> Only install this package directly if you need drift scanning without the CLI.

## Install

```bash
npm install @stackbilt/drift
```

## Usage

### Scan files for drift

```ts
import { scanForDrift } from '@stackbilt/drift';

const files = {
  'src/app.ts': 'import { createApp } from "vue";\ncreateApp({});',
  'src/utils.ts': 'export const add = (a: number, b: number) => a + b;',
};

const patterns = [
  { name: 'React Only', antiPatterns: 'Do not use `angular` or /vue\\.createApp/i' },
];

const report = scanForDrift(files, patterns);

console.log(report.score);        // 0.0 - 1.0 (1.0 = no drift)
console.log(report.violations);   // Array of DriftViolation
console.log(report.scannedFiles); // 2
```

### Extract rules independently

```ts
import { extractRules } from '@stackbilt/drift';

const rules = extractRules('Avoid /console\\.log/g and `eval`');
// => [/console\.log/g, /eval/]
```

## API Reference

### `scanForDrift(files, patterns): DriftReport`

Scan file contents against blessed-stack patterns.

| Field | Type | Description |
|---|---|---|
| `score` | `number` | 0.0 (high drift) to 1.0 (clean) |
| `violations` | `DriftViolation[]` | Anti-pattern matches found |
| `scannedFiles` | `number` | Total files scanned |
| `scannedPatterns` | `number` | Total patterns evaluated |
| `timestamp` | `string` | ISO 8601 scan timestamp |

### `extractRules(antiPatternText: string): RegExp[]`

Parse an anti-pattern definition into regex rules. Supports `/pattern/flags` and `` `keyword` `` syntax.

## Requirements

- Node >= 18
- Peer dependency: `@stackbilt/types`

## License

Apache-2.0

## Links

- [Repository](https://github.com/Stackbilt-dev/charter)
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
npm package: @stackbilt/git
Description: Git trailer parsing, commit risk scoring, and PR validation
Latest version: 0.10.0

# @stackbilt/git

Git trailer parsing, commit risk scoring, and governance suggestion generation for [Charter Kit](https://github.com/Stackbilt-dev/charter) -- a local-first governance toolkit for software repos.

> **Want the full toolkit?** Just install the CLI — it includes everything:
> ```bash
> npm install -g @stackbilt/cli
> ```
> Only install this package directly if you need trailer parsing and risk scoring without the CLI.

## Install

```bash
npm install @stackbilt/git
```

## Usage

### Parse trailers from a commit message

```ts
import { parseTrailersFromMessage } from '@stackbilt/git';

const trailers = parseTrailersFromMessage('abc1234', `feat(api): add user endpoint

Governed-By: ADR-0012
Resolves-Request: REQ-0045
`);

console.log(trailers.governedBy);
// [{ commitSha: 'abc1234', reference: 'ADR-0012' }]
```

### Assess commit risk

```ts
import { assessCommitRisk } from '@stackbilt/git';

assessCommitRisk(['migrations/002_add_table.sql'], 'feat: add table');
// => 'HIGH'

assessCommitRisk(['lib/utils.ts'], 'refactor: extract helper');
// => 'MEDIUM'

assessCommitRisk(['README.md'], 'docs: update readme');
// => 'LOW'
```

**Risk classification:**

| Level  | File patterns |
| ------ | ------------- |
| HIGH   | `migrations/`, `*.sql`, `worker/handlers/`, `worker/services/` |
| MEDIUM | `lib/`, `components/`, `context/`, `worker/lib/` |
| LOW    | `*.md`, `*.json`, `*.yml`, `test/`, `*.test.*`, `.github/` |

### Generate governance suggestions

```ts
import { generateSuggestions } from '@stackbilt/git';

const suggestions = generateSuggestions(trailers, unlinkedCommits, totalCommits);
// ['No commits have governance trailers. Consider linking significant changes to ADRs.']
```

## API Reference

### `parseTrailersFromMessage(commitSha, message): ParsedTrailers`

Parse `Governed-By` and `Resolves-Request` trailers from a single commit message.
Parsing follows terminal git trailer block semantics (trailers must be contiguous at message end).

### `parseAllTrailers(commits: GitCommit[]): ParsedTrailers`

Parse trailers from an array of commits, returning combined results.

### `assessCommitRisk(filesChanged, commitMessage): CommitRiskLevel`

Score a commit as `HIGH`, `MEDIUM`, or `LOW`. Falls back to message keyword analysis when no files are provided.

### `generateSuggestions(trailers, unlinkedCommits, totalCommits): string[]`

Generate governance suggestions based on trailer coverage and unlinked high-risk commits.

## Requirements

- Node >= 18
- Peer dependency: `@stackbilt/types`

## License

Apache-2.0

## Links

- [Repository](https://github.com/Stackbilt-dev/charter)
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
npm package: @stackbilt/validate
Description: Citation validation, message classification, and governance checks
Latest version: 0.10.0

# @stackbilt/validate

Citation validation and commit message intent classification for [Charter Kit](https://github.com/Stackbilt-dev/charter) -- a local-first governance toolkit for software repos. Pure heuristics, no LLM calls.

> **Want the full toolkit?** Just install the CLI — it includes everything:
> ```bash
> npm install -g @stackbilt/cli
> ```
> Only install this package directly if you need citation validation or intent classification without the CLI.

## Install

```bash
npm install @stackbilt/validate
```

## Usage

### Extract and validate citations

```ts
import { extractCitations, validateCitations, enrichCitations } from '@stackbilt/validate';

const text = 'Per [Section 3.1] and [ADR-012], this approach is approved.';

const citations = extractCitations(text);
// => ['Section 3.1', 'ADR-012']

const result = validateCitations(text, bundle, 'WARN');
// => { valid: true, violations: [], totalCitations: 2, validCount: 2 }
```

### Classify commit message intent

```ts
import { classifyMessage } from '@stackbilt/validate';

const result = classifyMessage('Should we adopt GraphQL or stick with REST?');
// => {
//   intent: 'decision',
//   confidence: 1,
//   dudePhases: ['D', 'U', 'Di', 'E'],
//   suggestedMode: 'GOVERNANCE',
//   complexity: 'low',
//   domain: 'ARCHITECTURE'
// }
```

## API Reference

### `extractCitations(text: string): string[]`

Extract governance citation references from text. Recognized: `[Section X.Y]`, `[ADR-XXX]`, `[RFC-YYYY-XXX]`, `[Pattern: Name]`, `[POLICY-XXX]`.

### `validateCitations(text, bundle, strictness?): CitationValidationResult`

Validate citations against a `CitationBundle`. Unknown citations receive closest-match suggestions via Levenshtein distance.

### `enrichCitations(text, bundle): string`

Replace citation references with hyperlinked, titled versions.

### `classifyMessage(message, context?): Classification`

Classify a message by intent (`ideation`, `decision`, `doubt`, `synthesis`, `question`, `review`), DUDE phases, complexity, and suggested app mode. Runs in under 5 ms.

## Types

- `CitationViolation`, `CitationValidationResult`, `ValidationStrictness`, `CitationBundle`
- `Classification`, `MessageIntent`, `DudePhase`

## Requirements

- Node >= 18
- Peer dependency: `@stackbilt/types`

## License

Apache-2.0

## Links

- [Repository](https://github.com/Stackbilt-dev/charter)
- [Issues](https://github.com/Stackbilt-dev/charter/issues)