threadlines 0.2.24 → 0.3.0

package/dist/commands/init.js

@@ -41,7 +41,6 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const chalk_1 = __importDefault(require("chalk"));
 const logger_1 = require("../utils/logger");
-const config_file_1 = require("../utils/config-file");
 const TEMPLATE = `---
 id: example-threadline
 version: 1.0.0
@@ -82,39 +81,49 @@ async function initCommand() {
         // Create threadlines directory if it doesn't exist
         if (!fs.existsSync(threadlinesDir)) {
             fs.mkdirSync(threadlinesDir, { recursive: true });
-            console.log(chalk_1.default.green(`✓ Created /threadlines directory`));
+            logger_1.logger.output(chalk_1.default.green(`✓ Created /threadlines directory`));
         }
         // Create .threadlinerc if it doesn't exist
         if (!fs.existsSync(configFile)) {
-            const configContent = JSON.stringify(config_file_1.DEFAULT_CONFIG, null, 2);
+            // Generate config with comment explaining mode
+            const configContent = `{
+  // mode: "online" syncs results to web app (requires THREADLINE_API_KEY and THREADLINE_ACCOUNT)
+  // mode: "offline" processes locally only, no sync
+  "mode": "online",
+  "api_url": "https://devthreadline.com",
+  "openai_model": "gpt-5.2",
+  "openai_service_tier": "Flex",
+  "diff_context_lines": 10
+}`;
             fs.writeFileSync(configFile, configContent, 'utf-8');
-            console.log(chalk_1.default.green(`✓ Created .threadlinerc`));
+            logger_1.logger.output(chalk_1.default.green(`✓ Created .threadlinerc`));
         }
         // Check if example file already exists
         if (fs.existsSync(exampleFile)) {
-            console.log(chalk_1.default.yellow(`⚠️  ${exampleFile} already exists`));
-            console.log(chalk_1.default.gray('   Edit it to create your threadline, or delete it and run init again.'));
+            logger_1.logger.warn(`${exampleFile} already exists`);
+            logger_1.logger.output(chalk_1.default.gray('   Edit it to create your threadline, or delete it and run init again.'));
             return;
         }
         // Write template file
         fs.writeFileSync(exampleFile, TEMPLATE, 'utf-8');
-        console.log(chalk_1.default.green(`✓ Created ${exampleFile}`));
-        console.log('');
-        console.log(chalk_1.default.blue('Next steps:'));
-        console.log(chalk_1.default.gray('  1. Edit threadlines/example.md with your coding standards'));
-        console.log(chalk_1.default.gray('  2. Rename it to something descriptive (e.g., error-handling.md)'));
-        console.log('');
-        console.log(chalk_1.default.yellow('⚠️  IMPORTANT: Configuration Required'));
-        console.log(chalk_1.default.white('   To use threadlines check, you need:'));
-        console.log('');
-        console.log(chalk_1.default.white('   Create a .env.local file in your project root with:'));
-        console.log(chalk_1.default.gray('     THREADLINE_API_KEY=your-api-key-here'));
-        console.log(chalk_1.default.gray('     THREADLINE_ACCOUNT=your-email@example.com'));
-        console.log('');
-        console.log(chalk_1.default.white('   Make sure .env.local is in your .gitignore file!'));
-        console.log('');
-        console.log(chalk_1.default.gray('  3. Run: npx threadlines check'));
-        console.log(chalk_1.default.gray('     (Use npx --yes threadlines check in non-interactive environments)'));
+        logger_1.logger.output(chalk_1.default.green(`✓ Created ${exampleFile}`));
+        logger_1.logger.output('');
+        logger_1.logger.output(chalk_1.default.blue('Next steps:'));
+        logger_1.logger.output(chalk_1.default.gray('  1. Edit threadlines/example.md with your coding standards'));
+        logger_1.logger.output(chalk_1.default.gray('  2. Rename it to something descriptive (e.g., error-handling.md)'));
+        logger_1.logger.output('');
+        logger_1.logger.output(chalk_1.default.yellow('⚠️  IMPORTANT: Configuration Required'));
+        logger_1.logger.output(chalk_1.default.white('   To use threadlines check, you need:'));
+        logger_1.logger.output('');
+        logger_1.logger.output(chalk_1.default.white('   Create a .env.local file in your project root with:'));
+        logger_1.logger.output(chalk_1.default.gray('     OPENAI_API_KEY=your-openai-api-key'));
+        logger_1.logger.output(chalk_1.default.gray('     THREADLINE_API_KEY=your-api-key-here'));
+        logger_1.logger.output(chalk_1.default.gray('     THREADLINE_ACCOUNT=your-email@example.com'));
+        logger_1.logger.output('');
+        logger_1.logger.output(chalk_1.default.white('   Make sure .env.local is in your .gitignore file!'));
+        logger_1.logger.output('');
+        logger_1.logger.output(chalk_1.default.gray('  3. Run: npx threadlines check'));
+        logger_1.logger.output(chalk_1.default.gray('     (Use npx --yes threadlines check in non-interactive environments)'));
     }
     catch (error) {
         const errorMessage = error instanceof Error ? error.message : 'Unknown error';

package/dist/git/diff.js

@@ -11,6 +11,7 @@ exports.getPRDiff = getPRDiff;
 exports.getCommitDiff = getCommitDiff;
 const simple_git_1 = __importDefault(require("simple-git"));
 const child_process_1 = require("child_process");
+const logger_1 = require("../utils/logger");
 // =============================================================================
 // CORE GIT OPERATIONS
 // These functions use raw git commands and work reliably across all CI environments.
@@ -146,13 +147,17 @@ async function getCommitAuthor(repoRoot, sha) {
  *
  * This is a shared implementation for CI environments that do shallow clones.
  * Uses three-dots logic (merge base) to show only the developer's changes,
- * avoiding drift from main moving forward.
+ * with graceful fallback to two dots for shallow clones.
  *
  * Strategy:
  * 1. Fetch target branch: origin/${targetBranch}:refs/remotes/origin/${targetBranch}
- * 2. Find merge base (common ancestor) using git merge-base (plumbing command)
- * 3. Fetch merge base commit (always fetch, assume not available)
- * 4. Diff: ${mergeBase}..HEAD (shows only developer's changes, not changes from main)
+ * 2. Try three dots: git diff origin/${targetBranch}...HEAD (merge base comparison)
+ *    - Shows only developer's changes (avoids drift from main moving forward)
+ *    - Works when we have enough history (full clones or GitHub's merge commits)
+ * 3. Fallback to two dots: git diff origin/${targetBranch}..HEAD (direct comparison)
+ *    - Used when shallow clone prevents merge base calculation
+ *    - May include drift from main, but provides working diff instead of crashing
+ *    - Warning is logged to inform user of potential drift
  *
  * Why three dots (merge base) instead of two dots (direct comparison)?
  * - Two dots: Shows all differences between target branch tip and HEAD
@@ -186,43 +191,34 @@ async function getPRDiff(repoRoot, targetBranch, logger) {
             `This is required for PR/MR diff comparison. ` +
             `Error: ${fetchError instanceof Error ? fetchError.message : 'Unknown error'}`);
     }
-    // Find merge base (common ancestor) using plumbing command
-    // Three dots logic: compare against merge base to show only developer's changes
-    // This avoids drift from main moving forward (two dots would include those changes)
-    let mergeBase;
+    // Try three dots (merge base) first - shows only developer's changes
+    // Falls back to two dots (direct comparison) if shallow clone prevents merge base calculation
+    let diff;
+    let changedFiles;
     try {
-        mergeBase = (0, child_process_1.execSync)(`git merge-base origin/${targetBranch} HEAD`, {
-            encoding: 'utf-8',
-            cwd: repoRoot
-        }).trim();
-        if (!mergeBase || mergeBase.length !== 40) {
-            throw new Error(`Invalid merge base SHA: "${mergeBase}"`);
-        }
+        // Step 1: Try the "Perfect" Diff (Three Dots)
+        // This isolates developer changes by comparing against merge base
+        // Works when we have enough history (full clones or GitHub's merge commits)
+        logger?.debug(`Attempting three-dots diff (merge base): origin/${targetBranch}...HEAD`);
+        diff = await git.diff([`origin/${targetBranch}...HEAD`, '-U200']);
+        const diffSummary = await git.diffSummary([`origin/${targetBranch}...HEAD`]);
+        changedFiles = diffSummary.files.map(f => f.file);
     }
     catch (error) {
+        // Step 2: Fallback to "Risky" Diff (Two Dots)
+        // If three dots fails, it means we're in a shallow clone without enough history
+        // We accept the "two dot" risk (may include drift from main) rather than crashing
         const errorMessage = error instanceof Error ? error.message : String(error);
-        throw new Error(`Failed to find merge base between origin/${targetBranch} and HEAD. ` +
-            `This is required to show only the developer's changes (avoids drift from main). ` +
-            `Error: ${errorMessage}`);
-    }
-    // Always fetch merge base (assume it's not available, fetch is fast/no-op if it is)
-    // This ensures we have the merge base available for diff comparison
-    logger?.debug(`Fetching merge base: ${mergeBase}`);
-    try {
-        await git.fetch(['origin', mergeBase, '--depth=1']);
-    }
-    catch (fetchError) {
-        throw new Error(`Failed to fetch merge base ${mergeBase} from origin. ` +
-            `This is required for PR/MR diff comparison in shallow clones. ` +
-            `Ensure 'origin' remote is configured and accessible. ` +
-            `Error: ${fetchError instanceof Error ? fetchError.message : 'Unknown error'}`);
+        logger_1.logger.warn(`Shallow clone detected: Cannot calculate merge base. ` +
+            `Diff may include unrelated changes from ${targetBranch} that occurred after branching. ` +
+            `Using direct comparison (two dots) as fallback.`);
+        logger?.debug(`Fallback error: ${errorMessage}`);
+        // Use two dots (direct comparison) - shows all differences between tips
+        logger?.debug(`Using two-dots diff (direct comparison): origin/${targetBranch}..HEAD`);
+        diff = await git.diff([`origin/${targetBranch}..HEAD`, '-U200']);
+        const diffSummary = await git.diffSummary([`origin/${targetBranch}..HEAD`]);
+        changedFiles = diffSummary.files.map(f => f.file);
     }
-    // Use merge base for diff (three dots logic: shows only developer's changes)
-    // git diff is plumbing command, ignores shallow boundaries
-    logger?.debug(`Comparing ${mergeBase}..HEAD (merge base vs PR branch)`);
-    const diff = await git.diff([`${mergeBase}..HEAD`, '-U200']);
-    const diffSummary = await git.diffSummary([`${mergeBase}..HEAD`]);
-    const changedFiles = diffSummary.files.map(f => f.file);
     return {
         diff: diff || '',
         changedFiles

package/dist/llm/prompt-builder.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Prompt Builder for LLM Threadline Checks
+ *
+ * Builds prompts for OpenAI API calls to check code changes against threadline guidelines.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPrompt = buildPrompt;
+function buildPrompt(threadline, diff, matchingFiles) {
+    // Build context files section if available
+    const contextFilesSection = threadline.contextContent && Object.keys(threadline.contextContent).length > 0
+        ? `Context Files:\n${Object.entries(threadline.contextContent)
+            .map(([file, content]) => `\n--- ${file} ---\n${content}`)
+            .join('\n')}\n\n`
+        : '';
+    return `You are a code quality checker focused EXCLUSIVELY on: ${threadline.id}
+
+CRITICAL: You must ONLY check for violations of THIS SPECIFIC threadline. Do NOT flag other code quality issues, style problems, or unrelated concerns. 
+If the code does not violate THIS threadline's specific rules, return "compliant" even if other issues exist.
+
+Threadline Guidelines:
+${threadline.content}
+
+${contextFilesSection}Code Changes (Git Diff Format):
+${diff}
+
+Changed Files:
+${matchingFiles.join('\n')}
+
+Review the code changes AGAINST ONLY THE THREADLINE GUIDELINES ABOVE.
+
+YOUR OBJECTIVES:
+1. Detect new violations being introduced in the code changes
+2. Review whether engineers have successfully addressed earlier violations
+
+This is why it's important to look very carefully at the diff structure. You'll come across diffs that introduce new violations. You will also come across some that address earlier violations. The diff structure should allow you to tell which is which, because lines starting with '-' are removed in favour of lines with '+'.
+
+CRITICAL CHECK BEFORE FLAGGING VIOLATIONS:
+Before commenting on or flagging a violation in any line, look at the FIRST CHARACTER of that line:
+* If it's a "-", the code is deleted.
+  → Only flag violations in lines starting with "+" (new code being added)
+* If the first character is "+", this is NEW code being added - flag violations here if they violate the threadline
+* If the line doesn't start with "+" or "-" (context lines), these are UNCHANGED - do NOT flag violations here
+* Some violations may not be line-specific (e.g., file-level patterns, overall structure) - include those in your reasoning as well
+
+
+IMPORTANT:
+- Only flag violations of the specific rules defined in this threadline
+- Ignore all other code quality issues, style problems, or unrelated concerns
+- Focus on understanding the diff structure to distinguish between new violations and fixes
+
+Return JSON only with this exact structure:
+{
+  "status": "compliant" | "attention" | "not_relevant",
+  "reasoning": "explanation with file paths and line numbers embedded in the text (e.g., 'app/api/checks/route.ts:8 - The addition of...')",
+  "file_references": [file paths where violations occur - MUST match files from the diff, include ONLY files with violations]
+}
+
+CRITICAL: For each violation, you MUST:
+1. Embed the file path and line number(s) directly in your reasoning text (e.g., "app/api/checks/route.ts:8 - The addition of 'c.files_changed_counts' violates...")
+2. For line-specific violations, include the line number (e.g., "file.ts:42")
+3. For file-level or pattern violations, just include the file path (e.g., "file.ts")
+4. Include ONLY files that actually contain violations in "file_references" array
+5. Do NOT include files that don't have violations, even if they appear in the diff
+6. The "file_references" array should be a simple list of file paths - no line numbers needed there since they're in the reasoning
+
+Status meanings:
+- "compliant": Code follows THIS threadline's guidelines, no violations found (even if other issues exist)
+- "attention": Code DIRECTLY violates THIS threadline's specific guidelines
+- "not_relevant": This threadline doesn't apply to these files/changes (e.g., wrong file type, no matching code patterns)
+`;
+}

package/dist/processors/expert.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processThreadlines = processThreadlines;
+const single_expert_1 = require("./single-expert");
+const logger_1 = require("../utils/logger");
+const EXPERT_TIMEOUT = 40000; // 40 seconds
+async function processThreadlines(request) {
+    const { threadlines, diff, files, apiKey, model, serviceTier, contextLinesForLLM } = request;
+    // Determine LLM model (same for all threadlines in this check)
+    const llmModel = `${model} ${serviceTier}`;
+    // Create promises with timeout
+    const promises = threadlines.map(threadline => {
+        let timeoutId = null;
+        let resolved = false;
+        const timeoutPromise = new Promise((resolve) => {
+            timeoutId = setTimeout(() => {
+                // Only log and resolve if we haven't already resolved
+                if (!resolved) {
+                    logger_1.logger.error(`Request timed out after ${EXPERT_TIMEOUT / 1000}s for threadline: ${threadline.id}`);
+                    resolved = true;
+                    resolve({
+                        expertId: threadline.id,
+                        status: 'error',
+                        reasoning: `Error: Request timed out after ${EXPERT_TIMEOUT / 1000}s`,
+                        error: {
+                            message: `Request timed out after ${EXPERT_TIMEOUT / 1000}s`,
+                            type: 'timeout'
+                        },
+                        fileReferences: [],
+                        relevantFiles: [],
+                        filteredDiff: '',
+                        filesInFilteredDiff: [],
+                        actualModel: undefined
+                    });
+                }
+            }, EXPERT_TIMEOUT);
+        });
+        const actualPromise = (0, single_expert_1.processThreadline)(threadline, diff, files, apiKey, model, serviceTier, contextLinesForLLM).then(result => {
+            // Mark as resolved and clear timeout if it hasn't fired yet
+            resolved = true;
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            return result;
+        });
+        return Promise.race([actualPromise, timeoutPromise]);
+    });
+    // Wait for all (some may timeout)
+    const results = await Promise.allSettled(promises);
+    // Process results
+    const expertResults = [];
+    let completed = 0;
+    let timedOut = 0;
+    let errors = 0;
+    let actualModelFromResponse;
+    for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        const threadline = threadlines[i];
+        if (result.status === 'fulfilled') {
+            const expertResult = result.value;
+            // Check status directly - errors and timeouts are now 'error' status
+            if (expertResult.status === 'error') {
+                // Check if it's a timeout (has error.type === 'timeout')
+                if ('error' in expertResult && expertResult.error?.type === 'timeout') {
+                    timedOut++;
+                }
+                else {
+                    errors++;
+                }
+            }
+            else {
+                completed++;
+            }
+            expertResults.push(expertResult);
+            // Capture actual model from first successful result (all threadlines use same model)
+            if (!actualModelFromResponse && 'actualModel' in expertResult && expertResult.actualModel) {
+                actualModelFromResponse = expertResult.actualModel;
+            }
+        }
+        else {
+            errors++;
+            expertResults.push({
+                expertId: threadline.id,
+                status: 'error',
+                reasoning: `Error: ${result.reason?.message || 'Unknown error'}`,
+                error: {
+                    message: result.reason?.message || 'Unknown error',
+                    rawResponse: result.reason
+                },
+                fileReferences: [],
+                relevantFiles: [],
+                filteredDiff: '',
+                filesInFilteredDiff: []
+            });
+        }
+    }
+    // Use actual model from OpenAI response, append service tier
+    let modelToStore;
+    if (actualModelFromResponse) {
+        modelToStore = `${actualModelFromResponse} ${serviceTier}`;
+    }
+    else {
+        // All calls failed - log prominently and preserve requested model for debugging
+        logger_1.logger.error(`No successful LLM responses received. Requested model: ${llmModel}`);
+        logger_1.logger.error(`Completed: ${completed}, Timed out: ${timedOut}, Errors: ${errors}`);
+        // Store requested model so we can debug what was attempted
+        modelToStore = `${llmModel} (no successful responses)`;
+    }
+    // Return all results - CLI will handle filtering/display
+    return {
+        results: expertResults,
+        metadata: {
+            totalThreadlines: threadlines.length,
+            completed,
+            timedOut,
+            errors,
+            llmModel: modelToStore
+        }
+    };
+}

package/dist/processors/single-expert.js

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.processThreadline = processThreadline;
+const openai_1 = __importDefault(require("openai"));
+const prompt_builder_1 = require("../llm/prompt-builder");
+const diff_filter_1 = require("../utils/diff-filter");
+const slim_diff_1 = require("../utils/slim-diff");
+const logger_1 = require("../utils/logger");
+async function processThreadline(threadline, diff, files, apiKey, model, serviceTier, contextLinesForLLM) {
+    const openai = new openai_1.default({ apiKey });
+    // Filter files that match threadline patterns
+    const relevantFiles = files.filter(file => threadline.patterns.some(pattern => matchesPattern(file, pattern)));
+    // If no files match, return not_relevant
+    if (relevantFiles.length === 0) {
+        logger_1.logger.debug(`   ⚠️  ${threadline.id}: No files matched patterns ${threadline.patterns.join(', ')}`);
+        logger_1.logger.debug(`      Files checked: ${files.slice(0, 5).join(', ')}${files.length > 5 ? '...' : ''}`);
+        return {
+            expertId: threadline.id,
+            status: 'not_relevant',
+            reasoning: `No files match threadline patterns: ${threadline.patterns.join(', ')}`,
+            fileReferences: [],
+            relevantFiles: [],
+            filteredDiff: '',
+            filesInFilteredDiff: []
+        };
+    }
+    // Filter diff to only include relevant files
+    const filteredDiff = (0, diff_filter_1.filterDiffByFiles)(diff, relevantFiles);
+    // Extract files actually present in the filtered diff
+    const filesInFilteredDiff = (0, diff_filter_1.extractFilesFromDiff)(filteredDiff);
+    // Trim diff for LLM to reduce token costs (keep full diff for storage/UI)
+    // The CLI sends diffs with -U200 (200 lines context), which can be expensive.
+    // This trims the diff to only N context lines before sending to LLM.
+    // Note: Full filtered diff is still stored in DB for UI viewing.
+    const trimmedDiffForLLM = (0, slim_diff_1.createSlimDiff)(filteredDiff, contextLinesForLLM);
+    // Log diff trimming if it occurred
+    const originalLines = filteredDiff.split('\n').length;
+    const trimmedLines = trimmedDiffForLLM.split('\n').length;
+    if (trimmedLines < originalLines) {
+        const reductionPercent = Math.round(((originalLines - trimmedLines) / originalLines) * 100);
+        logger_1.logger.debug(`   ✂️  Trimmed diff for LLM: ${originalLines} → ${trimmedLines} lines (${reductionPercent}% reduction, ${contextLinesForLLM} context lines)`);
+    }
+    // Build prompt with trimmed diff (full filtered diff is still stored for UI)
+    const prompt = (0, prompt_builder_1.buildPrompt)(threadline, trimmedDiffForLLM, filesInFilteredDiff);
+    logger_1.logger.debug(`   📝 Processing ${threadline.id}: ${relevantFiles.length} relevant files, ${filesInFilteredDiff.length} files in filtered diff`);
+    logger_1.logger.debug(`   🤖 Calling LLM (${model}) for ${threadline.id}...`);
+    // Capture timing for LLM call
+    const llmCallStartedAt = new Date().toISOString();
+    let llmCallFinishedAt;
+    let llmCallResponseTimeMs;
+    let llmCallTokens = null;
+    let llmCallStatus = 'success';
+    let llmCallErrorMessage = null;
+    try {
+        const requestParams = {
+            model,
+            messages: [
+                {
+                    role: 'system',
+                    content: 'You are a code quality checker. Analyze code changes against the threadline guidelines. Be precise - only flag actual violations. Return only valid JSON, no other text.'
+                },
+                {
+                    role: 'user',
+                    content: prompt
+                }
+            ],
+            response_format: { type: 'json_object' },
+            temperature: 0.1
+        };
+        // Add service_tier if not 'standard'
+        const normalizedServiceTier = serviceTier.toLowerCase();
+        if (normalizedServiceTier !== 'standard' && (normalizedServiceTier === 'auto' || normalizedServiceTier === 'default' || normalizedServiceTier === 'flex')) {
+            requestParams.service_tier = normalizedServiceTier;
+        }
+        const response = await openai.chat.completions.create(requestParams);
+        // Capture the actual model returned by OpenAI (may differ from requested)
+        const actualModel = response.model;
+        llmCallFinishedAt = new Date().toISOString();
+        llmCallResponseTimeMs = new Date(llmCallFinishedAt).getTime() - new Date(llmCallStartedAt).getTime();
+        // Capture token usage if available
+        if (response.usage) {
+            llmCallTokens = {
+                prompt_tokens: response.usage.prompt_tokens,
+                completion_tokens: response.usage.completion_tokens,
+                total_tokens: response.usage.total_tokens
+            };
+        }
+        const content = response.choices[0]?.message?.content;
+        if (!content) {
+            throw new Error('No response from LLM');
+        }
+        const parsed = JSON.parse(content);
+        logger_1.logger.debug(`   ✅ ${threadline.id}: ${parsed.status}`);
+        // Extract file references - rely entirely on LLM to provide them
+        let fileReferences = [];
+        if (parsed.file_references && Array.isArray(parsed.file_references) && parsed.file_references.length > 0) {
+            // LLM provided file references - validate they're in filesInFilteredDiff
+            fileReferences = parsed.file_references.filter((file) => filesInFilteredDiff.includes(file));
+            if (parsed.file_references.length !== fileReferences.length) {
+                logger_1.logger.debug(`   ⚠️  Warning: LLM provided ${parsed.file_references.length} file references, but only ${fileReferences.length} match the files sent to LLM`);
+            }
+        }
+        else {
+            // LLM did not provide file_references
+            const status = parsed.status || 'not_relevant';
+            if (status === 'attention') {
+                // This is a problem - we have violations but don't know which files
+                logger_1.logger.error(`   ❌ Error: LLM returned "attention" status but no file_references for threadline ${threadline.id}`);
+                logger_1.logger.error(`   Cannot accurately report violations without file references. This may indicate a prompt/LLM issue.`);
+                // Return empty file references - better than guessing
+                fileReferences = [];
+            }
+            // For "compliant" or "not_relevant" status, file references are optional
+        }
+        return {
+            expertId: threadline.id,
+            status: parsed.status || 'not_relevant',
+            reasoning: parsed.reasoning,
+            fileReferences: fileReferences,
+            relevantFiles: relevantFiles,
+            filteredDiff: filteredDiff,
+            filesInFilteredDiff: filesInFilteredDiff,
+            actualModel: actualModel,
+            llmCallMetrics: {
+                startedAt: llmCallStartedAt,
+                finishedAt: llmCallFinishedAt,
+                responseTimeMs: llmCallResponseTimeMs,
+                tokens: llmCallTokens,
+                status: llmCallStatus,
+                errorMessage: llmCallErrorMessage
+            }
+        };
+    }
+    catch (error) {
+        // Capture error timing
+        llmCallFinishedAt = new Date().toISOString();
+        llmCallResponseTimeMs = new Date(llmCallFinishedAt).getTime() - new Date(llmCallStartedAt).getTime();
+        llmCallStatus = 'error';
+        // Extract error details safely
+        const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+        llmCallErrorMessage = errorMessage;
+        // Log full error for debugging
+        logger_1.logger.error(`   ❌ OpenAI error: ${JSON.stringify(error, null, 2)}`);
+        // Extract OpenAI error details from the error object
+        const errorObj = error;
+        const openAIError = errorObj?.error || {};
+        const rawErrorResponse = {
+            status: errorObj?.status,
+            headers: errorObj?.headers,
+            request_id: errorObj?.request_id,
+            error: errorObj?.error,
+            code: errorObj?.code,
+            param: errorObj?.param,
+            type: errorObj?.type
+        };
+        // Return error result with metrics instead of throwing
+        // This allows metrics to be captured even when LLM call fails
+        // Use 'error' status - errors are errors, not attention items
+        return {
+            expertId: threadline.id,
+            status: 'error',
+            reasoning: `Error: ${errorMessage}`,
+            error: {
+                message: errorMessage,
+                type: openAIError?.type || errorObj?.type,
+                code: openAIError?.code || errorObj?.code,
+                rawResponse: rawErrorResponse
+            },
+            fileReferences: [],
+            relevantFiles: relevantFiles,
+            filteredDiff: filteredDiff,
+            filesInFilteredDiff: filesInFilteredDiff,
+            llmCallMetrics: {
+                startedAt: llmCallStartedAt,
+                finishedAt: llmCallFinishedAt,
+                responseTimeMs: llmCallResponseTimeMs,
+                tokens: llmCallTokens,
+                status: llmCallStatus,
+                errorMessage: llmCallErrorMessage
+            }
+        };
+    }
+}
+function matchesPattern(filePath, pattern) {
+    // Convert glob pattern to regex
+    // Handle ** first (before single *), escape it to avoid double replacement
+    let regexPattern = pattern
+        .replace(/\*\*/g, '__DOUBLE_STAR__')
+        .replace(/\*/g, '[^/]*')
+        .replace(/__DOUBLE_STAR__/g, '.*')
+        .replace(/\?/g, '.');
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(filePath);
+}

package/dist/utils/config-file.js

@@ -42,7 +42,7 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const simple_git_1 = __importDefault(require("simple-git"));
 exports.DEFAULT_CONFIG = {
-    mode: 'online',
+    mode: 'online', // Default: sync enabled. Set to "offline" for local-only processing.
     api_url: 'https://devthreadline.com',
     openai_model: 'gpt-5.2',
     openai_service_tier: 'Flex',
@@ -103,15 +103,24 @@ async function loadConfig(startDir) {
     }
     // If config file found, parse and merge
     if (configPath) {
+        let configContent = fs.readFileSync(configPath, 'utf-8');
+        // Strip single-line comments (// ...) before parsing JSON
+        // This allows comments in .threadlinerc for documentation
+        // Only match comments at the start of a line (after whitespace) to avoid matching // inside strings
+        // Also remove empty lines left after comment removal
+        configContent = configContent
+            .replace(/^\s*\/\/.*$/gm, '') // Remove comments (only at start of line after whitespace)
+            .replace(/^\s*[\r\n]/gm, ''); // Remove empty lines
         try {
-            const configContent = fs.readFileSync(configPath, 'utf-8');
             const fileConfig = JSON.parse(configContent);
             // Merge file config into defaults (file overrides defaults)
             Object.assign(config, fileConfig);
         }
         catch (error) {
-            // If file exists but can't be parsed, log warning but continue with defaults
-            console.warn(`Warning: Failed to parse .threadlinerc at ${configPath}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            // If file exists but can't be parsed, fail loudly - this is a user error that needs fixing
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new Error(`Failed to parse .threadlinerc at ${configPath}: ${errorMessage}\n` +
+                `Please fix the syntax error in your .threadlinerc file.`);
         }
     }
     return config;