k9guard 1.0.0

package/src/utils/riddleBank.ts

@@ -0,0 +1,18 @@
+import { randomBytes } from 'crypto';
+import enData from '../locale/en.json';
+import trData from '../locale/tr.json';
+
+export class RiddleBank {
+  private static data: Record<'en' | 'tr', { question: string; answer: string }[]> = {
+    en: enData.riddles,
+    tr: trData.riddles
+  };
+
+  static getRandom(locale: 'en' | 'tr' = 'en', difficulty: 'easy' | 'medium' | 'hard' = 'easy'): { question: string; answer: string } {
+    const riddles = this.data[locale];
+    // use crypto random to select a riddle securely
+    const buffer = randomBytes(4);
+    const index = buffer.readUInt32LE(0) % riddles.length;
+    return riddles[index]!;
+  }
+}

package/src/utils/scrambleGenerator.ts

@@ -0,0 +1,37 @@
+import { randomBytes } from 'crypto';
+
+export class ScrambleGenerator {
+  private static words: string[] = [
+    'apple', 'cat', 'dog', 'house', 'sun', 'moon', 'car', 'tree', 'book', 'water',
+    'bread', 'milk', 'fish', 'bird', 'flower', 'star', 'hand', 'eye', 'nose', 'mouth'
+  ];
+
+  static generate(difficulty: 'easy' | 'medium' | 'hard'): { question: string; answer: string } {
+    let word: string;
+    const buffer = randomBytes(4);
+    // convert crypto bytes to a float between 0 and 1
+    const rand = buffer.readUInt32LE(0) / 0xFFFFFFFF;
+    
+    if (difficulty === 'easy') {
+      word = this.words[Math.floor(rand * 10)]!;
+    } else if (difficulty === 'medium') {
+      word = this.words[Math.floor(rand * this.words.length)]!;
+    } else {
+      word = 'typescript';
+    }
+    
+    const scrambled = this.scramble(word);
+    return { question: scrambled, answer: word };
+  }
+
+  private static scramble(word: string): string {
+    const arr = word.split('');
+    // NOTE: fisher yates shuffle using crypto random for each swap
+    for (let i = arr.length - 1; i > 0; i--) {
+      const buffer = randomBytes(4);
+      const j = buffer.readUInt32LE(0) % (i + 1);
+      [arr[i]!, arr[j]!] = [arr[j]!, arr[i]!];
+    }
+    return arr.join('');
+  }
+}

package/src/utils/sequenceGenerator.ts

@@ -0,0 +1,33 @@
+import { randomBytes } from 'crypto';
+
+export class SequenceGenerator {
+  static generate(difficulty: 'easy' | 'medium' | 'hard'): { question: string; answer: number | string } {
+    if (difficulty === 'easy') {
+      const buffer = randomBytes(4);
+      // NOTE: generate random starting number and step size for arithmetic sequence
+      const start = (buffer.readUInt32LE(0) % 5) + 1;
+      const step = ((buffer.readUInt32LE(0) >> 8) % 3) + 1;
+      const sequence = [start, start + step, start + 2 * step];
+      const answer = start + 3 * step;
+      return { question: `${sequence.join(', ')}, ?`, answer };
+    }
+    if (difficulty === 'medium') {
+      const letters = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J'];
+      const buffer = randomBytes(4);
+      const start = buffer.readUInt32LE(0) % 4;
+      const step = 2;
+      const sequence = [letters[start], letters[start + step], letters[start + 2 * step]];
+      const nextIndex = start + 3 * step;
+      // check if next letter goes out of bounds
+      if (nextIndex >= letters.length) {
+        return { question: `${sequence.join(', ')}, ?`, answer: '?' };
+      }
+      const answer = letters[nextIndex]!;
+      return { question: `${sequence.join(', ')}, ?`, answer };
+    }
+    // hard mode uses fibonacci sequence
+    const sequence = [1, 1, 2, 3];
+    const answer = 5;
+    return { question: `${sequence.join(', ')}, ?`, answer };
+  }
+}

package/src/validators/customQuestionValidator.ts

@@ -0,0 +1,88 @@
+import type { CustomQuestion } from '../types';
+
+export class CustomQuestionValidator {
+  private static readonly MAX_QUESTIONS = 100;
+  private static readonly MAX_QUESTION_LENGTH = 500;
+  private static readonly MAX_ANSWER_LENGTH = 200;
+  private static readonly MIN_QUESTION_LENGTH = 5;
+  private static readonly MIN_ANSWER_LENGTH = 1;
+  private static readonly VALID_DIFFICULTY = ['easy', 'medium', 'hard'];
+
+  // validates the entire questions array structure and content
+  static validate(questions: unknown): { valid: boolean; error?: string } {
+    if (!Array.isArray(questions)) {
+      return { valid: false, error: 'Questions must be an array' };
+    }
+
+    if (questions.length === 0) {
+      return { valid: false, error: 'At least one question is required' };
+    }
+
+    if (questions.length > this.MAX_QUESTIONS) {
+      return { valid: false, error: `Maximum ${this.MAX_QUESTIONS} questions allowed` };
+    }
+
+    // NOTE: validate each question individually and return detailed error if any fail
+    for (let i = 0; i < questions.length; i++) {
+      const questionItem = questions[i];
+      const singleValidation = this.validateSingle(questionItem);
+      
+      if (!singleValidation.valid) {
+        return { valid: false, error: `Question ${i + 1}: ${singleValidation.error}` };
+      }
+    }
+
+    return { valid: true };
+  }
+
+  private static validateSingle(question: unknown): { valid: boolean; error?: string } {
+    if (typeof question !== 'object' || question === null) {
+      return { valid: false, error: 'Each question must be an object' };
+    }
+
+    const q = question as Record<string, unknown>;
+
+    if (typeof q.question !== 'string') {
+      return { valid: false, error: 'Question text must be a string' };
+    }
+
+    if (typeof q.answer !== 'string') {
+      return { valid: false, error: 'Answer must be a string' };
+    }
+
+    if (typeof q.difficulty !== 'string') {
+      return { valid: false, error: 'Difficulty must be specified' };
+    }
+
+    if (!this.VALID_DIFFICULTY.includes(q.difficulty)) {
+      return { valid: false, error: `Difficulty must be one of: ${this.VALID_DIFFICULTY.join(', ')}` };
+    }
+
+    if (q.question.length < this.MIN_QUESTION_LENGTH) {
+      return { valid: false, error: `Question must be at least ${this.MIN_QUESTION_LENGTH} characters` };
+    }
+
+    if (q.question.length > this.MAX_QUESTION_LENGTH) {
+      return { valid: false, error: `Question must not exceed ${this.MAX_QUESTION_LENGTH} characters` };
+    }
+
+    if (q.answer.length < this.MIN_ANSWER_LENGTH) {
+      return { valid: false, error: 'Answer cannot be empty' };
+    }
+
+    if (q.answer.length > this.MAX_ANSWER_LENGTH) {
+      return { valid: false, error: `Answer must not exceed ${this.MAX_ANSWER_LENGTH} characters` };
+    }
+
+    return { valid: true };
+  }
+
+  // clean up whitespace from questions and answers
+  static sanitize(questions: CustomQuestion[]): CustomQuestion[] {
+    return questions.map(q => ({
+      question: q.question.trim(),
+      answer: q.answer.trim(),
+      difficulty: q.difficulty
+    }));
+  }
+}

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}