feat: add analyze function

Author: TeaCoder52

README.md

@@ -7,12 +7,12 @@ Perfect for **OTP**, **SMS verification**, **2FA**, **PIN codes**, onboarding st
 
 ## Features
 
-- Generates **4-digit** and **6-digit** human-friendly codes  
-- Pattern-based generation: **AABB**, **ABAB**, **ABBA**, **AAAB**, **ABBB**, **AABC**, **ABBC**,  
-  plus **ABABAB**, **AABBCC**, **AAABBB**, **ABBABB**, **ABCABC**, **ABCCBA**
-- Filters out simple sequences (`1234`, `9876`) and repeated digits (`0000`)
-- Fully customizable strategies (your own generator logic)
-- Optional custom RNG (for cryptographic random or deterministic tests)
+-   Generates **4-digit** and **6-digit** human-friendly codes
+-   Pattern-based generation: **AABB**, **ABAB**, **ABBA**, **AAAB**, **ABBB**, **AABC**, **ABBC**,  
+    plus **ABABAB**, **AABBCC**, **AAABBB**, **ABBABB**, **ABCABC**, **ABCCBA**
+-   Filters out simple sequences (`1234`, `9876`) and repeated digits (`0000`)
+-   Fully customizable strategies (your own generator logic)
+-   Optional custom RNG (for cryptographic random or deterministic tests)
 
 ---
 
@@ -33,31 +33,31 @@ pnpm add patcode
 ### Basic
 
 ```ts
-import { generateCode } from "patcode";
+import { generateCode } from 'patcode'
 
-generateCode(); // "535353" (6-digit, mixed patterns)
+generateCode() // "535353" (6-digit, mixed patterns)
 ```
 
 ### 4-digit code
 
 ```ts
-generateCode({ length: 4 }); // "5566"
+generateCode({ length: 4 }) // "5566"
 ```
 
 ## Custom Strategy
 
 ```ts
 generateCode({
-  length: 6,
-  strategy: "custom",
-  customStrategy(ctx) {
-    // example: code starting with 9, then ABAB
-    const [A, B] = ctx.pickTwoDifferentDigits();
-    return ctx.fromDigits(["9", A, B, A, B, A]);
-  }
-});
+	length: 6,
+	strategy: 'custom',
+	customStrategy(ctx) {
+		// example: code starting with 9, then ABAB
+		const [A, B] = ctx.pickTwoDifferentDigits()
+		return ctx.fromDigits(['9', A, B, A, B, A])
+	},
+})
 ```
 
-## 📝 License
+## License
 
 This project is licensed under the [**MIT License**](./LICENSE).

src/analyze.ts

@@ -0,0 +1,104 @@
+import { isAllSame, isTooSimpleSequence } from './utils'
+import type { CodeLength, CodeAnalysis } from './types'
+
+function isSequentialAsc(code: string): boolean {
+	for (let i = 1; i < code.length; i++) {
+		const prev = Number(code[i - 1])
+		const curr = Number(code[i])
+		if (curr !== (prev + 1) % 10) return false
+	}
+	return true
+}
+
+function isSequentialDesc(code: string): boolean {
+	for (let i = 1; i < code.length; i++) {
+		const prev = Number(code[i - 1])
+		const curr = Number(code[i])
+		if (curr !== (prev + 9) % 10) return false
+	}
+	return true
+}
+
+function countGroups(code: string): number {
+	let groups = 1
+	for (let i = 1; i < code.length; i++) {
+		if (code[i] !== code[i - 1]) groups++
+	}
+	return groups
+}
+
+function estimateEntropy(code: string): number {
+	const freq: Record<string, number> = {}
+
+	for (const d of code) freq[d] = (freq[d] || 0) + 1
+
+	let entropy = 0
+	for (const k in freq) {
+		const p = freq[k] / code.length
+		entropy -= p * Math.log2(p)
+	}
+
+	return entropy * code.length
+}
+
+function collisionRisk(
+	code: string,
+	entropy: number
+): 'low' | 'medium' | 'high' {
+	if (code.length === 4) {
+		// Max entropy ~8 bits
+		if (entropy > 6.5) return 'low'
+		if (entropy > 3.5) return 'medium'
+		return 'high'
+	}
+
+	if (code.length === 6) {
+		// Max entropy ~12 bits
+		if (entropy > 10) return 'low'
+		if (entropy > 6) return 'medium'
+		return 'high'
+	}
+
+	return 'high'
+}
+
+function memorabilityScore(
+	code: string,
+	groups: number
+): 'low' | 'medium' | 'high' {
+	if (isAllSame(code)) return 'low'
+	if (isTooSimpleSequence(code)) return 'low'
+
+	if (groups <= 2) return 'high'
+
+	if (groups === 3) return 'medium'
+
+	return 'low'
+}
+
+export function analyze(code: string): CodeAnalysis {
+	const length = code.length as CodeLength
+
+	const allSame = isAllSame(code)
+	const tooSimple = isTooSimpleSequence(code)
+	const asc = isSequentialAsc(code)
+	const desc = isSequentialDesc(code)
+	const groups = countGroups(code)
+
+	const entropy = estimateEntropy(code)
+	const collision = collisionRisk(code, entropy)
+	const memory = memorabilityScore(code, groups)
+
+	return {
+		length,
+		isAllSame: allSame,
+		isTooSimple: tooSimple,
+		isSequentialAsc: asc,
+		isSequentialDesc: desc,
+		repeatedGroups: groups,
+
+		entropy,
+		collisionRisk: collision,
+		memorability: memory,
+	}
+}

src/index.ts

@@ -1,8 +1,9 @@
-import type {
+import {
 	GenerateOptions,
 	CodeLength,
-	StrategyName,
+	Strategy,
 	CustomStrategyContext,
+	CodeAnalysis,
 } from './types'
 import { getStrategyImpl } from './strategy'
 import { isCodeAllowed } from './validator'
@@ -17,11 +18,19 @@ import {
 	pickThreeDifferentDigits,
 } from './utils'
 
-export type { GenerateOptions, CodeLength, StrategyName, CustomStrategyContext }
+export { analyze } from './analyze'
+
+export {
+	GenerateOptions,
+	CodeLength,
+	Strategy,
+	CustomStrategyContext,
+	CodeAnalysis,
+}
 
 export function generateCode(options: GenerateOptions = {}): string {
 	const length: CodeLength = options.length === 4 ? 4 : 6
-	const strategy: StrategyName = options.strategy ?? 'mixed'
+	const strategy: Strategy = options.strategy ?? Strategy.Mixed
 
 	const impl = getStrategyImpl(length, strategy, options)
 

src/strategy.ts

@@ -1,6 +1,6 @@
 import type {
 	CodeLength,
-	StrategyName,
+	Strategy,
 	GenerateOptions,
 	CustomStrategyContext,
 } from './types'
@@ -10,7 +10,7 @@ import * as s6 from './patterns6'
 
 export function getStrategyImpl(
 	length: CodeLength,
-	strategy: StrategyName,
+	strategy: Strategy,
 	options: GenerateOptions
 ): () => string {
 	const digits = utils.getAllowedDigits(options)

src/types.ts

@@ -1,14 +1,15 @@
 export type CodeLength = 4 | 6
 
-export type StrategyName =
-	| 'mixed'
-	| 'pairs'
-	| 'triples'
-	| 'mirror'
-	| 'wave'
-	| 'escalator'
-	| 'pairWave'
-	| 'custom'
+export enum Strategy {
+	Mixed = 'mixed',
+	Pairs = 'pairs',
+	Triples = 'triples',
+	Mirror = 'mirror',
+	Wave = 'wave',
+	Escalator = 'escalator',
+	PairWave = 'pairWave',
+	Custom = 'custom',
+}
 
 export interface CustomStrategyContext {
 	length: CodeLength
@@ -22,7 +23,7 @@ export interface CustomStrategyContext {
 
 export interface GenerateOptions {
 	length?: CodeLength
-	strategy?: StrategyName
+	strategy?: Strategy
 	avoidSimpleSequences?: boolean
 	avoidSameDigits?: boolean
 	blackList?: string[]
@@ -31,3 +32,16 @@ export interface GenerateOptions {
 	rng?: () => number
 	customStrategy?: (ctx: CustomStrategyContext) => string
 }
+
+export interface CodeAnalysis {
+	length: CodeLength
+	isAllSame: boolean
+	isTooSimple: boolean
+	isSequentialAsc: boolean
+	isSequentialDesc: boolean
+	repeatedGroups: number
+	pattern?: string
+	entropy: number
+	memorability: 'low' | 'medium' | 'high'
+	collisionRisk: 'low' | 'medium' | 'high'
+}

test/random.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { generateCode } from '../src/index'
+import { generateCode, Strategy } from '../src/index'
 
 function fakeRngGenerator(values: number[]) {
 	let i = 0
@@ -12,7 +12,7 @@ describe('deterministic RNG', () => {
 
 		const code1 = generateCode({
 			length: 6,
-			strategy: 'custom',
+			strategy: Strategy.Custom,
 			rng,
 			customStrategy(ctx) {
 				const d1 = ctx.pickDigit()
@@ -30,7 +30,7 @@ describe('deterministic RNG', () => {
 
 		const code2 = generateCode({
 			length: 6,
-			strategy: 'custom',
+			strategy: Strategy.Custom,
 			rng: rng2,
 			customStrategy(ctx) {
 				const d1 = ctx.pickDigit()

test/strategy.test.ts

@@ -1,15 +1,16 @@
 import { describe, it, expect } from 'vitest'
 import { getStrategyImpl } from '../src/strategy'
+import { Strategy } from '../src'
 
 describe('strategy system', () => {
 	it('creates a implementation function', () => {
-		const impl = getStrategyImpl(6, 'mixed', {})
+		const impl = getStrategyImpl(6, Strategy.Mixed, {})
 		const code = impl()
 		expect(code.length).toBe(6)
 	})
 
 	it('custom strategy works', () => {
-		const impl = getStrategyImpl(4, 'custom', {
+		const impl = getStrategyImpl(4, Strategy.Custom, {
 			customStrategy: () => '1234',
 		})
 		expect(impl()).toBe('1234')