@codewalla_india/openspec 1.3.0 → 1.3.2

package/dist/comprehension-quiz/index.js

@@ -0,0 +1,47 @@
+/**
+ * Comprehension quiz system main entry point
+ *
+ * This module provides the main entry point for the comprehension quiz system,
+ * which enforces that developers read and understand change artifacts before
+ * implementation. The quiz blocks the `/opsx:apply` command until passed with a score
+ * of 80% or higher.
+ *
+ * @module comprehension-quiz
+ *
+ * @example
+ * ```ts
+ * import { QuizExecutor } from './comprehension-quiz/quiz-executor.js';
+ * import { generateQuizQuestions } from './comprehension-quiz/question-generator.js';
+ * import { createProviderWithFallback } from './comprehension-quiz/providers/factory.js';
+ *
+ * // Generate questions
+ * const questions = await generateQuizQuestions(artifactPaths, 10);
+ *
+ * // Execute quiz
+ * const executor = new QuizExecutor();
+ * const result = await executor.executeQuiz(questions);
+ *
+ * if (result.passed) {
+ *   console.log('Quiz passed! Proceeding with implementation.');
+ * } else {
+ *   console.log('Quiz failed. Please review the artifacts and try again.');
+ * }
+ * ```
+ */
+// Types
+export * from './types.js';
+// Providers
+export * from './providers/interface.js';
+export * from './providers/factory.js';
+export { OpenAIProvider } from './providers/openai.js';
+export { AnthropicProvider } from './providers/anthropic.js';
+export { OllamaProvider } from './providers/ollama.js';
+export { LocalProvider } from './providers/local.js';
+// Core utilities
+export { fingerprintFile, fingerprintDirectory, fingerprintArtifacts, isPassRecordValid } from './fingerprint.js';
+export * from './pass-record.js';
+// Quiz execution
+export { QuizExecutor } from './quiz-executor.js';
+// Question generation
+export { generateQuizQuestions, generateQuestionsForArtifact, getQuestionCount, calculateQuestionAllocation, } from './question-generator.js';
+//# sourceMappingURL=index.js.map

package/dist/comprehension-quiz/pass-record.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pass record storage and validation
+ *
+ * This module handles the storage and retrieval of quiz pass records. Pass records
+ * are stored in `.openspec/comprehension-quiz-passes.json` and include fingerprint
+ * information to detect when artifacts have changed since the quiz was passed.
+ *
+ * @module comprehension-quiz/pass-record
+ */
+import type { PassRecord } from './types.js';
+/**
+ * Get pass record for a specific change
+ *
+ * @param changeName - Name of the change
+ * @returns Pass record or undefined if not found
+ */
+export declare function getPassRecord(changeName: string): Promise<PassRecord | undefined>;
+/**
+ * Save pass record for a change
+ *
+ * @param record - Pass record to save
+ */
+export declare function savePassRecord(record: PassRecord): Promise<void>;
+/**
+ * Increment failure count for a change
+ *
+ * @param changeName - Name of the change
+ */
+export declare function incrementFailureCount(changeName: string): Promise<void>;
+/**
+ * Delete pass record for a change
+ *
+ * @param changeName - Name of the change
+ */
+export declare function deletePassRecord(changeName: string): Promise<void>;
+/**
+ * Check if a pass record is valid for current artifact fingerprint
+ *
+ * @param changeName - Name of the change
+ * @param currentFingerprint - Current fingerprint of artifacts
+ * @returns True if pass record exists and fingerprint matches
+ */
+export declare function isPassRecordValid(changeName: string, currentFingerprint: string): Promise<boolean>;
+//# sourceMappingURL=pass-record.d.ts.map

package/dist/comprehension-quiz/pass-record.js

@@ -0,0 +1,98 @@
+/**
+ * Pass record storage and validation
+ *
+ * This module handles the storage and retrieval of quiz pass records. Pass records
+ * are stored in `.openspec/comprehension-quiz-passes.json` and include fingerprint
+ * information to detect when artifacts have changed since the quiz was passed.
+ *
+ * @module comprehension-quiz/pass-record
+ */
+import { promises as fs } from 'fs';
+import path from 'path';
+/**
+ * Path to the pass records file
+ */
+const PASS_RECORDS_FILE = '.openspec/comprehension-quiz-passes.json';
+/**
+ * Read all pass records from storage
+ *
+ * @returns Pass records object
+ */
+async function readPassRecords() {
+    try {
+        const content = await fs.readFile(PASS_RECORDS_FILE, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        // File doesn't exist or is invalid, return empty object
+        return {};
+    }
+}
+/**
+ * Write pass records to storage
+ *
+ * @param records - Pass records to write
+ */
+async function writePassRecords(records) {
+    const dir = path.dirname(PASS_RECORDS_FILE);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(PASS_RECORDS_FILE, JSON.stringify(records, null, 2), 'utf-8');
+}
+/**
+ * Get pass record for a specific change
+ *
+ * @param changeName - Name of the change
+ * @returns Pass record or undefined if not found
+ */
+export async function getPassRecord(changeName) {
+    const records = await readPassRecords();
+    return records[changeName];
+}
+/**
+ * Save pass record for a change
+ *
+ * @param record - Pass record to save
+ */
+export async function savePassRecord(record) {
+    const records = await readPassRecords();
+    records[record.changeName] = record;
+    await writePassRecords(records);
+}
+/**
+ * Increment failure count for a change
+ *
+ * @param changeName - Name of the change
+ */
+export async function incrementFailureCount(changeName) {
+    const records = await readPassRecords();
+    const record = records[changeName];
+    if (record) {
+        record.failureCount = (record.failureCount || 0) + 1;
+        await writePassRecords(records);
+    }
+}
+/**
+ * Delete pass record for a change
+ *
+ * @param changeName - Name of the change
+ */
+export async function deletePassRecord(changeName) {
+    const records = await readPassRecords();
+    delete records[changeName];
+    await writePassRecords(records);
+}
+/**
+ * Check if a pass record is valid for current artifact fingerprint
+ *
+ * @param changeName - Name of the change
+ * @param currentFingerprint - Current fingerprint of artifacts
+ * @returns True if pass record exists and fingerprint matches
+ */
+export async function isPassRecordValid(changeName, currentFingerprint) {
+    const record = await getPassRecord(changeName);
+    if (!record) {
+        return false;
+    }
+    return record.fingerprint === currentFingerprint;
+}
+//# sourceMappingURL=pass-record.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * Anthropic provider implementation
+ *
+ * This module implements the Anthropic LLM provider for question generation.
+ * It uses the Anthropic API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/anthropic
+ */
+import { BaseProvider } from './interface.js';
+import type { ProviderConfig, Question } from '../types.js';
+/**
+ * Anthropic provider for question generation
+ *
+ * Requires ANTHROPIC_API_KEY environment variable to be set.
+ */
+export declare class AnthropicProvider extends BaseProvider {
+    constructor(config: ProviderConfig);
+    /**
+     * Validate Anthropic configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig(): void;
+    /**
+     * Generate quiz questions using Anthropic 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[]>;
+}
+//# sourceMappingURL=anthropic.d.ts.map

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

@@ -0,0 +1,53 @@
+/**
+ * Anthropic provider implementation
+ *
+ * This module implements the Anthropic LLM provider for question generation.
+ * It uses the Anthropic API to generate quiz questions from artifact content.
+ *
+ * @module comprehension-quiz/providers/anthropic
+ */
+import { BaseProvider } from './interface.js';
+/**
+ * Anthropic provider for question generation
+ *
+ * Requires ANTHROPIC_API_KEY environment variable to be set.
+ */
+export class AnthropicProvider extends BaseProvider {
+    constructor(config) {
+        super(config);
+    }
+    /**
+     * Validate Anthropic configuration
+     *
+     * @throws Error if API key is missing
+     */
+    validateConfig() {
+        if (!this.config.apiKey) {
+            throw new Error('ANTHROPIC_API_KEY environment variable is required for Anthropic provider');
+        }
+    }
+    /**
+     * Generate quiz questions using Anthropic 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) {
+        // TODO: Implement Anthropic API call
+        // For now, return placeholder questions
+        const questions = [];
+        for (let i = 0; i < questionCount; i++) {
+            questions.push({
+                text: `Sample question ${i + 1} for ${artifactType}`,
+                options: ['Option A', 'Option B', 'Option C'],
+                correctOption: 0,
+                artifactSource: artifactType,
+            });
+        }
+        this.validateQuestions(questions);
+        return questions;
+    }
+}
+//# sourceMappingURL=anthropic.js.map

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

@@ -0,0 +1,44 @@
+/**
+ * Provider factory for creating LLM provider instances
+ *
+ * This module handles provider selection via environment variables, configuration
+ * loading, and fallback chain management. It supports OpenAI, Anthropic, Ollama, and
+ * local model providers with automatic fallback on failure.
+ *
+ * @module comprehension-quiz/providers/factory
+ */
+import type { LLMProvider } from '../types.js';
+/**
+ * Supported provider types
+ */
+export type ProviderType = 'openai' | 'anthropic' | 'ollama' | 'local';
+/**
+ * Create a provider instance
+ *
+ * @param providerType - Type of provider to create
+ * @returns Provider instance
+ * @throws Error if provider cannot be loaded
+ */
+export declare function createProvider(providerType: ProviderType): Promise<LLMProvider>;
+/**
+ * Create a provider with fallback chain
+ *
+ * Tries each provider in the fallback chain until one succeeds.
+ *
+ * @returns Provider instance from first available provider in fallback chain
+ * @throws Error if all providers fail
+ */
+export declare function createProviderWithFallback(): Promise<LLMProvider>;
+/**
+ * Get the primary provider type
+ *
+ * @returns Provider type
+ */
+export declare function getPrimaryProviderType(): ProviderType;
+/**
+ * Get the fallback chain
+ *
+ * @returns Array of provider types in fallback order
+ */
+export declare function getFallbackChainTypes(): ProviderType[];
+//# sourceMappingURL=factory.d.ts.map

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

@@ -0,0 +1,174 @@
+/**
+ * Provider factory for creating LLM provider instances
+ *
+ * This module handles provider selection via environment variables, configuration
+ * loading, and fallback chain management. It supports OpenAI, Anthropic, Ollama, and
+ * local model providers with automatic fallback on failure.
+ *
+ * @module comprehension-quiz/providers/factory
+ */
+/**
+ * Default fallback chain for providers
+ *
+ * The system will try providers in this order until one succeeds.
+ */
+const DEFAULT_FALLBACK_CHAIN = ['openai', 'anthropic', 'ollama', 'local'];
+/**
+ * Environment variable names for provider selection
+ */
+const ENV_PROVIDER = 'OPENSPEC_LLM_PROVIDER';
+const ENV_FALLBACK = 'OPENSPEC_LLM_FALLBACK';
+/**
+ * Provider-specific environment variables
+ *
+ * Maps each provider to its configuration environment variables.
+ */
+const PROVIDER_ENV_VARS = {
+    openai: {
+        apiKey: 'OPENAI_API_KEY',
+        model: 'OPENAI_MODEL',
+    },
+    anthropic: {
+        apiKey: 'ANTHROPIC_API_KEY',
+        model: 'ANTHROPIC_MODEL',
+    },
+    ollama: {
+        endpoint: 'OLLAMA_BASE_URL',
+        model: 'OLLAMA_MODEL',
+    },
+    local: {
+        modelType: 'LOCAL_MODEL_TYPE',
+        model: 'LOCAL_MODEL_PATH',
+    },
+};
+/**
+ * Default model names for each provider
+ *
+ * These are used if no specific model is configured via environment variables.
+ */
+const DEFAULT_MODELS = {
+    openai: 'gpt-4',
+    anthropic: 'claude-3-opus',
+    ollama: 'llama2',
+    local: 'local-model',
+};
+/**
+ * Get provider type from environment variable
+ *
+ * @returns Provider type or default
+ */
+function getProviderType() {
+    const envValue = process.env[ENV_PROVIDER];
+    if (envValue && ['openai', 'anthropic', 'ollama', 'local'].includes(envValue)) {
+        return envValue;
+    }
+    return 'openai'; // Default
+}
+/**
+ * Get fallback chain from environment variable
+ *
+ * @returns Array of provider types in fallback order
+ */
+function getFallbackChain() {
+    const envValue = process.env[ENV_FALLBACK];
+    if (envValue) {
+        const providers = envValue.split(',').map((p) => p.trim().toLowerCase());
+        const validProviders = providers.filter((p) => ['openai', 'anthropic', 'ollama', 'local'].includes(p));
+        if (validProviders.length > 0) {
+            return validProviders;
+        }
+    }
+    return DEFAULT_FALLBACK_CHAIN;
+}
+/**
+ * Get configuration for a provider type from environment variables
+ *
+ * @param providerType - Type of provider
+ * @returns Provider configuration
+ */
+function getProviderConfig(providerType) {
+    const envVars = PROVIDER_ENV_VARS[providerType];
+    const config = {};
+    if (envVars.apiKey && process.env[envVars.apiKey]) {
+        config.apiKey = process.env[envVars.apiKey];
+    }
+    if (envVars.model && process.env[envVars.model]) {
+        config.model = process.env[envVars.model];
+    }
+    else {
+        config.model = DEFAULT_MODELS[providerType];
+    }
+    if (envVars.endpoint && process.env[envVars.endpoint]) {
+        config.endpoint = process.env[envVars.endpoint];
+    }
+    if (envVars.modelType && process.env[envVars.modelType]) {
+        config.modelType = process.env[envVars.modelType];
+    }
+    return config;
+}
+/**
+ * Create a provider instance
+ *
+ * @param providerType - Type of provider to create
+ * @returns Provider instance
+ * @throws Error if provider cannot be loaded
+ */
+export async function createProvider(providerType) {
+    const config = getProviderConfig(providerType);
+    switch (providerType) {
+        case 'openai':
+            const { OpenAIProvider } = await import('./openai.js');
+            return new OpenAIProvider(config);
+        case 'anthropic':
+            const { AnthropicProvider } = await import('./anthropic.js');
+            return new AnthropicProvider(config);
+        case 'ollama':
+            const { OllamaProvider } = await import('./ollama.js');
+            return new OllamaProvider(config);
+        case 'local':
+            const { LocalProvider } = await import('./local.js');
+            return new LocalProvider(config);
+        default:
+            throw new Error(`Unknown provider type: ${providerType}`);
+    }
+}
+/**
+ * Create a provider with fallback chain
+ *
+ * Tries each provider in the fallback chain until one succeeds.
+ *
+ * @returns Provider instance from first available provider in fallback chain
+ * @throws Error if all providers fail
+ */
+export async function createProviderWithFallback() {
+    const fallbackChain = getFallbackChain();
+    const errors = [];
+    for (const providerType of fallbackChain) {
+        try {
+            const provider = await createProvider(providerType);
+            return provider;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            errors.push(`${providerType}: ${errorMessage}`);
+        }
+    }
+    throw new Error(`All LLM providers failed. Attempted: ${fallbackChain.join(', ')}. Errors: ${errors.join('; ')}`);
+}
+/**
+ * Get the primary provider type
+ *
+ * @returns Provider type
+ */
+export function getPrimaryProviderType() {
+    return getProviderType();
+}
+/**
+ * Get the fallback chain
+ *
+ * @returns Array of provider types in fallback order
+ */
+export function getFallbackChainTypes() {
+    return getFallbackChain();
+}
+//# sourceMappingURL=factory.js.map

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

@@ -0,0 +1,59 @@
+/**
+ * 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
+ */
+import type { LLMProvider, ProviderConfig, Question } from '../types.js';
+/**
+ * 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 declare abstract class BaseProvider implements LLMProvider {
+    protected config: ProviderConfig;
+    constructor(config: ProviderConfig);
+    /**
+     * Generate quiz questions from artifact content
+     * @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
+     */
+    abstract generateQuestions(artifactContent: string, questionCount: number, artifactType: 'proposal' | 'design' | 'specs' | 'plan' | 'tasks'): Promise<Question[]>;
+    /**
+     * Validate provider configuration
+     * @throws Error if configuration is invalid
+     */
+    abstract validateConfig(): void;
+    /**
+     * 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
+     */
+    protected validateQuestions(questions: Question[]): void;
+}
+//# sourceMappingURL=interface.d.ts.map

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

@@ -0,0 +1,63 @@
+/**
+ * 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();
+    }
+    /**
+     * 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) {
+            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,34 @@
+/**
+ * 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[]>;
+}
+//# sourceMappingURL=local.d.ts.map