@codewalla_india/openspec 1.3.1 → 1.3.3

package/dist/comprehension-quiz/providers/interface.js

@@ -0,0 +1,150 @@
+/**
+ * LLM provider interface for question generation
+ *
+ * This module defines the abstract base class that all LLM providers must implement.
+ * The interface ensures consistent question generation across different backends (OpenAI,
+ * Anthropic, Ollama, local models) with validation of generated questions.
+ *
+ * @module comprehension-quiz/providers/interface
+ */
+/**
+ * Abstract base class for LLM providers
+ *
+ * All providers must extend this class and implement the abstract methods.
+ * Provides common validation logic for generated questions.
+ *
+ * @example
+ * ```ts
+ * class MyProvider extends BaseProvider {
+ *   async generateQuestions(content, count, type) {
+ *     // Generate questions using your LLM
+ *   }
+ *   validateConfig() {
+ *     // Check your configuration
+ *   }
+ * }
+ * ```
+ */
+export class BaseProvider {
+    config;
+    constructor(config) {
+        this.config = config;
+        this.validateConfig();
+    }
+    /**
+     * Build the system + user messages for single-question generation.
+     *
+     * Contract:
+     *   - System message explicitly forbids listing multiple questions.
+     *   - User message asks for exactly one question (question N of total).
+     *   - Response format is strict JSON only — no prose, no explanation, no answer label.
+     *   - The correct answer index (correctOption) is returned as a number 0-2; its
+     *     meaning is never explained in the response so the LLM cannot read it back.
+     *
+     * @returns { system, user } message pair ready to send to the LLM API
+     */
+    buildSingleQuestionPrompt(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts) {
+        const previousBlock = previousQuestionTexts.length > 0
+            ? `\n\nAlready asked questions (do NOT repeat these):\n${previousQuestionTexts.map((t, i) => `${i + 1}. ${t}`).join('\n')}`
+            : '';
+        const system = [
+            'You are a quiz question generator for a software change review system.',
+            'STRICT RULES — violating any rule causes system failure:',
+            '  1. Output EXACTLY ONE question. Never output a list, array, or multiple questions.',
+            '  2. Output ONLY valid JSON matching the schema below. No prose before or after.',
+            '  3. Do NOT include the word "Answer", "Correct", or any hint about which option is right.',
+            '  4. Do NOT explain the options. Do NOT add notes, caveats, or additional text.',
+            '  5. The "correctOption" field is an opaque integer (0, 1, or 2). Do not label it.',
+            '',
+            'Response schema (output this JSON and nothing else):',
+            '{',
+            '  "text": "<question text>",',
+            '  "options": ["<option 1>", "<option 2>", "<option 3>"],',
+            '  "correctOption": <0|1|2>,',
+            '  "artifactSource": "<proposal|design|specs|plan|tasks>"',
+            '}',
+        ].join('\n');
+        const user = [
+            `Generate question ${questionIndex + 1} of ${totalQuestions} for the "${artifactType}" artifact.`,
+            'The question must require reading the artifact to answer correctly.',
+            'Distractors must be plausible but wrong based on artifact content.',
+            previousBlock,
+            '',
+            `Artifact content:\n---\n${artifactContent}\n---`,
+        ].join('\n');
+        return { system, user };
+    }
+    /**
+     * Parse the raw LLM text response into a Question object.
+     * Strips markdown fences if present, then JSON-parses and validates.
+     *
+     * @param rawResponse - Raw text returned by the LLM API
+     * @param artifactType - Expected artifact source (used as fallback)
+     * @returns Validated Question object
+     * @throws Error if the response cannot be parsed or fails validation
+     */
+    parseSingleQuestionResponse(rawResponse, artifactType) {
+        let text = rawResponse.trim();
+        // Strip markdown code fences if present
+        text = text.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '').trim();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`LLM returned invalid JSON for single question: ${rawResponse.slice(0, 200)}`);
+        }
+        const q = parsed;
+        if (typeof q['text'] !== 'string' ||
+            !Array.isArray(q['options']) ||
+            typeof q['correctOption'] !== 'number' ||
+            typeof q['artifactSource'] !== 'string') {
+            throw new Error(`LLM response missing required fields: ${JSON.stringify(q)}`);
+        }
+        const question = {
+            text: q['text'],
+            options: q['options'],
+            correctOption: q['correctOption'],
+            artifactSource: q['artifactSource'] ?? artifactType,
+        };
+        this.validateQuestion(question);
+        return question;
+    }
+    /**
+     * Validate generated questions before returning
+     *
+     * Ensures all questions have:
+     * - Non-empty text
+     * - Exactly 3 options
+     * - Valid correct option index (0-2)
+     * - Valid artifact source
+     *
+     * @param questions - Questions to validate
+     * @throws Error if any question is invalid
+     */
+    validateQuestions(questions) {
+        for (const question of questions) {
+            this.validateQuestion(question);
+        }
+    }
+    /**
+     * Validate a single question object.
+     * @param question - Question to validate
+     * @throws Error if invalid
+     */
+    validateQuestion(question) {
+        if (!question.text || question.text.trim().length === 0) {
+            throw new Error('Question text cannot be empty');
+        }
+        if (question.options.length !== 3) {
+            throw new Error('Each question must have exactly 3 options');
+        }
+        if (question.correctOption < 0 || question.correctOption > 2) {
+            throw new Error('Correct option index must be 0, 1, or 2');
+        }
+        if (!['proposal', 'design', 'specs', 'plan', 'tasks'].includes(question.artifactSource)) {
+            throw new Error('Invalid artifact source');
+        }
+    }
+}
+//# sourceMappingURL=interface.js.map

package/dist/comprehension-quiz/providers/local.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Local model provider implementation
+ *
+ * This module implements the local model LLM provider for question generation.
+ * It supports running local models for offline or private question generation.
+ *
+ * @module comprehension-quiz/providers/local
+ */
+import { BaseProvider } from './interface.js';
+import type { ProviderConfig, Question } from '../types.js';
+/**
+ * Local model provider for question generation
+ *
+ * Requires LOCAL_MODEL_PATH environment variable to be set.
+ */
+export declare class LocalProvider extends BaseProvider {
+    constructor(config: ProviderConfig);
+    /**
+     * Validate local model configuration
+     *
+     * @throws Error if model path is missing
+     */
+    validateConfig(): void;
+    /**
+     * Generate quiz questions using local model
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    generateQuestions(artifactContent: string, questionCount: number, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Promise<Question[]>;
+    generateSingleQuestion(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionIndex: number, totalQuestions: number, previousQuestionTexts: string[]): Promise<Question>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/comprehension-quiz/providers/local.js

@@ -0,0 +1,69 @@
+/**
+ * Local model provider implementation
+ *
+ * This module implements the local model LLM provider for question generation.
+ * It supports running local models for offline or private question generation.
+ *
+ * @module comprehension-quiz/providers/local
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * Local model provider for question generation
+ *
+ * Requires LOCAL_MODEL_PATH environment variable to be set.
+ */
+export class LocalProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate local model configuration
+     *
+     * @throws Error if model path is missing
+     */
+    validateConfig() {
+        if (!this.config.model) {
+            throw new Error('LOCAL_MODEL_PATH environment variable is required for local provider');
+        }
+    }
+    /**
+     * Generate quiz questions using local model
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    async generateQuestions(artifactContent, questionCount, artifactType) {
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            const q = await this.generateSingleQuestion(artifactContent, artifactType, i, questionCount, questions.map((q) => q.text));
+            questions.push(q);
+        }
+        return questions;
+    }
+    async generateSingleQuestion(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts) {
+        const { system, user } = this.buildSingleQuestionPrompt(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts);
+        const endpoint = this.config.endpoint ?? 'http://localhost:11434';
+        const response = await fetch(`${endpoint}/api/chat`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                model: this.config.model,
+                stream: false,
+                format: 'json',
+                messages: [
+                    { role: 'system', content: system },
+                    { role: 'user', content: user },
+                ],
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Local model API error ${response.status}: ${await response.text()}`);
+        }
+        const data = (await response.json());
+        const raw = data.message?.content ?? '';
+        return this.parseSingleQuestionResponse(raw, artifactType);
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/comprehension-quiz/providers/ollama.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Ollama provider implementation
+ *
+ * This module implements the Ollama LLM provider for question generation.
+ * It uses the Ollama API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/ollama
+ */
+import { BaseProvider } from './interface.js';
+import type { ProviderConfig, Question } from '../types.js';
+/**
+ * Ollama provider for question generation
+ *
+ * Requires OLLAMA_BASE_URL environment variable to be set.
+ */
+export declare class OllamaProvider extends BaseProvider {
+    constructor(config: ProviderConfig);
+    /**
+     * Validate Ollama configuration
+     *
+     * @throws Error if endpoint is missing
+     */
+    validateConfig(): void;
+    /**
+     * Generate quiz questions using Ollama API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    generateQuestions(artifactContent: string, questionCount: number, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Promise<Question[]>;
+    generateSingleQuestion(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionIndex: number, totalQuestions: number, previousQuestionTexts: string[]): Promise<Question>;
+}
+//# sourceMappingURL=ollama.d.ts.map

package/dist/comprehension-quiz/providers/ollama.js

@@ -0,0 +1,69 @@
+/**
+ * Ollama provider implementation
+ *
+ * This module implements the Ollama LLM provider for question generation.
+ * It uses the Ollama API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/ollama
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * Ollama provider for question generation
+ *
+ * Requires OLLAMA_BASE_URL environment variable to be set.
+ */
+export class OllamaProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate Ollama configuration
+     *
+     * @throws Error if endpoint is missing
+     */
+    validateConfig() {
+        if (!this.config.endpoint) {
+            throw new Error('OLLAMA_BASE_URL environment variable is required for Ollama provider');
+        }
+    }
+    /**
+     * Generate quiz questions using Ollama API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    async generateQuestions(artifactContent, questionCount, artifactType) {
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            const q = await this.generateSingleQuestion(artifactContent, artifactType, i, questionCount, questions.map((q) => q.text));
+            questions.push(q);
+        }
+        return questions;
+    }
+    async generateSingleQuestion(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts) {
+        const { system, user } = this.buildSingleQuestionPrompt(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts);
+        const baseUrl = this.config.endpoint ?? 'http://localhost:11434';
+        const response = await fetch(`${baseUrl}/api/chat`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                model: this.config.model ?? 'llama2',
+                stream: false,
+                format: 'json',
+                messages: [
+                    { role: 'system', content: system },
+                    { role: 'user', content: user },
+                ],
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`Ollama API error ${response.status}: ${await response.text()}`);
+        }
+        const data = (await response.json());
+        const raw = data.message?.content ?? '';
+        return this.parseSingleQuestionResponse(raw, artifactType);
+    }
+}
+//# sourceMappingURL=ollama.js.map

package/dist/comprehension-quiz/providers/openai.d.ts

@@ -0,0 +1,35 @@
+/**
+ * OpenAI provider implementation
+ *
+ * This module implements the OpenAI LLM provider for question generation.
+ * It uses the OpenAI API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/openai
+ */
+import { BaseProvider } from './interface.js';
+import type { ProviderConfig, Question } from '../types.js';
+/**
+ * OpenAI provider for question generation
+ *
+ * Requires OPENAI_API_KEY environment variable to be set.
+ */
+export declare class OpenAIProvider extends BaseProvider {
+    constructor(config: ProviderConfig);
+    /**
+     * Validate OpenAI configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig(): void;
+    /**
+     * Generate quiz questions using OpenAI API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    generateQuestions(artifactContent: string, questionCount: number, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Promise<Question[]>;
+    generateSingleQuestion(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionIndex: number, totalQuestions: number, previousQuestionTexts: string[]): Promise<Question>;
+}
+//# sourceMappingURL=openai.d.ts.map

package/dist/comprehension-quiz/providers/openai.js

@@ -0,0 +1,72 @@
+/**
+ * OpenAI provider implementation
+ *
+ * This module implements the OpenAI LLM provider for question generation.
+ * It uses the OpenAI API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/openai
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * OpenAI provider for question generation
+ *
+ * Requires OPENAI_API_KEY environment variable to be set.
+ */
+export class OpenAIProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate OpenAI configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig() {
+        if (!this.config.apiKey) {
+            throw new Error('OPENAI_API_KEY environment variable is required for OpenAI provider');
+        }
+    }
+    /**
+     * Generate quiz questions using OpenAI API
+     *
+     * @param artifactContent - The content of the artifact to generate questions from
+     * @param questionCount - Number of questions to generate
+     * @param artifactType - Type of artifact (proposal, design, specs, plan, tasks)
+     * @returns Array of generated questions
+     */
+    async generateQuestions(artifactContent, questionCount, artifactType) {
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            const q = await this.generateSingleQuestion(artifactContent, artifactType, i, questionCount, questions.map((q) => q.text));
+            questions.push(q);
+        }
+        return questions;
+    }
+    async generateSingleQuestion(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts) {
+        const { system, user } = this.buildSingleQuestionPrompt(artifactContent, artifactType, questionIndex, totalQuestions, previousQuestionTexts);
+        const response = await fetch('https://api.openai.com/v1/chat/completions', {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${this.config.apiKey}`,
+                'content-type': 'application/json',
+            },
+            body: JSON.stringify({
+                model: this.config.model ?? 'gpt-4',
+                max_tokens: 512,
+                temperature: 0.7,
+                response_format: { type: 'json_object' },
+                messages: [
+                    { role: 'system', content: system },
+                    { role: 'user', content: user },
+                ],
+            }),
+        });
+        if (!response.ok) {
+            throw new Error(`OpenAI API error ${response.status}: ${await response.text()}`);
+        }
+        const data = (await response.json());
+        const raw = data.choices[0]?.message?.content ?? '';
+        return this.parseSingleQuestionResponse(raw, artifactType);
+    }
+}
+//# sourceMappingURL=openai.js.map

package/dist/comprehension-quiz/question-generator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Question generator for quiz questions
+ *
+ * This module handles reading artifact content and generating quiz questions
+ * using LLM providers. It includes logic for question count scaling based on
+ * artifact size and proportional question allocation across artifact types.
+ *
+ * @module comprehension-quiz/question-generator
+ */
+import type { Question, LLMProvider } from './types.js';
+/**
+ * Determine question count based on artifact size
+ *
+ * @param totalSize - Total size of all artifacts in bytes
+ * @returns Number of questions to generate (5, 7, or 10)
+ */
+export declare function getQuestionCount(totalSize: number): number;
+/**
+ * Calculate question allocation per artifact type
+ *
+ * Distributes questions proportionally to artifact size, ensuring at least
+ * one question per artifact type if it has content.
+ *
+ * @param totalQuestions - Total number of questions to generate
+ * @param artifactSizes - Size of each artifact type in bytes
+ * @returns Object with question count per artifact type
+ */
+export declare function calculateQuestionAllocation(totalQuestions: number, artifactSizes: {
+    proposal: number;
+    design: number;
+    specs: number;
+    plan: number;
+    tasks: number;
+}): {
+    proposal: number;
+    design: number;
+    specs: number;
+    plan: number;
+    tasks: number;
+};
+/**
+ * Generate questions for a specific artifact type
+ *
+ * @param artifactContent - Content of the artifact
+ * @param artifactType - Type of artifact
+ * @param questionCount - Number of questions to generate
+ * @param provider - LLM provider to use
+ * @returns Array of generated questions
+ */
+export declare function generateQuestionsForArtifact(artifactContent: string, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks', questionCount: number, provider: LLMProvider): Promise<Question[]>;
+/**
+ * On-demand question stream for the quiz executor.
+ *
+ * This class resolves the artifact contents and allocation plan upfront, but
+ * NEVER pre-generates questions. Each call to `next()` fetches exactly ONE
+ * question from the LLM — only after the previous question has been answered.
+ *
+ * This enforces FR-10: questions are fetched on-demand, never pre-generated.
+ * The correct answer (correctOption) is held in process memory; it is never
+ * written to stdout, disk, or any external surface.
+ */
+export declare class QuizQuestionStream {
+    private provider;
+    private plan;
+    private totalQuestions;
+    private fetchedCount;
+    private askedTexts;
+    private constructor();
+    /**
+     * Create and initialise a QuizQuestionStream.
+     * Reads artifact files and builds the question plan, but does NOT generate any questions.
+     *
+     * @param artifactPaths - Object mapping artifact types to file paths
+     * @param totalQuestions - Total number of questions the quiz will ask
+     * @param provider - LLM provider (optional, uses fallback if not provided)
+     */
+    static create(artifactPaths: {
+        proposal?: string;
+        design?: string;
+        specs?: string;
+        plan?: string;
+        tasks?: string;
+    }, totalQuestions: number, provider?: LLMProvider): Promise<QuizQuestionStream>;
+    /** Total number of questions this quiz will ask. */
+    get total(): number;
+    /** Whether there are more questions to fetch. */
+    get hasNext(): boolean;
+    /**
+     * Fetch the next question from the LLM.
+     * MUST only be called after the user has answered the current question.
+     * Only one question is held in memory at a time; this method discards the
+     * previous question before fetching the next.
+     *
+     * @returns The next Question, or null if all questions have been asked.
+     */
+    next(): Promise<Question | null>;
+}
+/**
+ * Generate complete quiz question set for all artifacts.
+ *
+ * NOTE: This function pre-generates all questions and should only be used for
+ * non-interactive contexts (e.g. testing, pass recording). During live quiz
+ * execution use QuizQuestionStream.create() instead.
+ *
+ * @param artifactPaths - Object mapping artifact types to file paths
+ * @param totalQuestions - Total number of questions to generate
+ * @param provider - LLM provider to use (optional, uses fallback if not provided)
+ * @returns Array of all generated questions
+ */
+export declare function generateQuizQuestions(artifactPaths: {
+    proposal?: string;
+    design?: string;
+    specs?: string;
+    plan?: string;
+    tasks?: string;
+}, totalQuestions: number, provider?: LLMProvider): Promise<Question[]>;
+//# sourceMappingURL=question-generator.d.ts.map