@stackbilt/drift 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# @stackbilt/drift
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
> **Want the full toolkit?** Just install the CLI — it includes everything:
|
|
6
|
+
> ```bash
|
|
7
|
+
> npm install -g @stackbilt/cli
|
|
8
|
+
> ```
|
|
9
|
+
> Only install this package directly if you need drift scanning without the CLI.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @stackbilt/drift
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Usage
|
|
18
|
+
|
|
19
|
+
### Scan files for drift
|
|
20
|
+
|
|
21
|
+
```ts
|
|
22
|
+
import { scanForDrift } from '@stackbilt/drift';
|
|
23
|
+
|
|
24
|
+
const files = {
|
|
25
|
+
'src/app.ts': 'import { createApp } from "vue";\ncreateApp({});',
|
|
26
|
+
'src/utils.ts': 'export const add = (a: number, b: number) => a + b;',
|
|
27
|
+
};
|
|
28
|
+
|
|
29
|
+
const patterns = [
|
|
30
|
+
{ name: 'React Only', antiPatterns: 'Do not use `angular` or /vue\\.createApp/i' },
|
|
31
|
+
];
|
|
32
|
+
|
|
33
|
+
const report = scanForDrift(files, patterns);
|
|
34
|
+
|
|
35
|
+
console.log(report.score); // 0.0 - 1.0 (1.0 = no drift)
|
|
36
|
+
console.log(report.violations); // Array of DriftViolation
|
|
37
|
+
console.log(report.scannedFiles); // 2
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### Extract rules independently
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
import { extractRules } from '@stackbilt/drift';
|
|
44
|
+
|
|
45
|
+
const rules = extractRules('Avoid /console\\.log/g and `eval`');
|
|
46
|
+
// => [/console\.log/g, /eval/]
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## API Reference
|
|
50
|
+
|
|
51
|
+
### `scanForDrift(files, patterns): DriftReport`
|
|
52
|
+
|
|
53
|
+
Scan file contents against blessed-stack patterns.
|
|
54
|
+
|
|
55
|
+
| Field | Type | Description |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| `score` | `number` | 0.0 (high drift) to 1.0 (clean) |
|
|
58
|
+
| `violations` | `DriftViolation[]` | Anti-pattern matches found |
|
|
59
|
+
| `scannedFiles` | `number` | Total files scanned |
|
|
60
|
+
| `scannedPatterns` | `number` | Total patterns evaluated |
|
|
61
|
+
| `timestamp` | `string` | ISO 8601 scan timestamp |
|
|
62
|
+
|
|
63
|
+
### `extractRules(antiPatternText: string): RegExp[]`
|
|
64
|
+
|
|
65
|
+
Parse an anti-pattern definition into regex rules. Supports `/pattern/flags` and `` `keyword` `` syntax.
|
|
66
|
+
|
|
67
|
+
## Requirements
|
|
68
|
+
|
|
69
|
+
- Node >= 18
|
|
70
|
+
- Peer dependency: `@stackbilt/types`
|
|
71
|
+
|
|
72
|
+
## License
|
|
73
|
+
|
|
74
|
+
Apache-2.0
|
|
75
|
+
|
|
76
|
+
## Links
|
|
77
|
+
|
|
78
|
+
- [Repository](https://github.com/Stackbilt-dev/charter)
|
|
79
|
+
- [Issues](https://github.com/Stackbilt-dev/charter/issues)
|