threadlines 0.2.25 → 0.4.0

package/README.md

@@ -4,17 +4,17 @@ Threadline CLI - AI-powered linter based on your natural language documentation.
 
 ## Why Threadline?
 
-Getting teams to follow consistent quality standards is **hard**. Really hard.
+Getting teams to consistently follow coding patterns and quality standards is **hard**. Really hard.
 
 - **Documentation** → Nobody reads it. Or it's outdated before you finish writing it.
 - **Linting** → Catches syntax errors, but misses nuanced stuff.
 - **AI Code Reviewers** → Powerful, but you can't trust them. Did they actually check what you care about? Can you customize them with your team's specific rules?
 
-**Threadline solves this** by running **separate, parallel, highly focused AI-powered reviews** - each focused on a single, specific concern. Your coding standards live in your repository as markdown files, version-controlled and always in sync with your codebase. Each threadline gets its own dedicated AI check, ensuring focused attention on what matters to your team.
+**Threadline solves this** by running **separate, parallel, highly focused AI-powered reviews** - each focused on a single, specific concern or pattern: the stuff that takes engineers months to internalise - and they keep forgetting. Your coding patterns live in your repository as 'Threadline' markdown files, version-controlled and always in sync with your codebase. Each threadline is its own AI agent, ensuring focused attention on what matters to your team.
 
 ### What Makes Threadline Different?
 
-- **Focused Reviews** - Instead of one AI trying to check everything, Threadline runs multiple specialized AI reviewers in parallel. Each threadline focuses on one thing and does it well.
+- **Focused Reviews** - Instead of one AI agent checking everything, Threadline runs multiple specialized AI reviewers in parallel. Each threadline focuses on one thing and does it well.
 
 - **Documentation That Lives With Your Code** - Your coding standards live in your repo, in a `/threadlines` folder. They're version-controlled, reviewable, and always in sync with your codebase.
 
@@ -24,18 +24,7 @@ Getting teams to follow consistent quality standards is **hard**. Really hard.
 
 ## Installation
 
-### Option 1: Global Installation (Recommended for Regular Use)
-
-```bash
-npm install -g threadlines
-```
-
-Then use directly:
-```bash
-threadlines check
-```
-
-### Option 2: Use with npx (No Installation)
+### Option 1: Use with npx (No Installation)
 
 ```bash
 npx threadlines check
@@ -82,8 +71,17 @@ Edit `threadlines/example.md` with your coding standards, then rename it to some
 ```bash
 npx threadlines check
 ```
+
 By default, analyzes your staged/unstaged git changes against all threadlines in the `/threadlines` directory.
 
+**Review Context Types:**
+- `local` - Staged/unstaged changes (default for local development)
+- `commit` - Specific commit (when using `--commit` flag)
+- `pr` - Pull Request/Merge Request (auto-detected in CI)
+- `file` - Single file (when using `--file` flag)
+- `folder` - Folder contents (when using `--folder` flag)
+- `files` - Multiple files (when using `--files` flag)
+
 **Common Use Cases:**
 
 **Check latest commit locally:**
@@ -96,11 +94,6 @@ threadlines check --commit HEAD
 threadlines check --commit abc123def
 ```
 
-**Check all commits in a branch:**
-```bash
-threadlines check --branch feature/new-feature
-```
-
 **Check entire file(s):**
 ```bash
 threadlines check --file src/api/users.ts
@@ -108,24 +101,35 @@ threadlines check --files src/api/users.ts src/api/posts.ts
 threadlines check --folder src/api
 ```
 
+**Debug mode (verbose output):**
+```bash
+threadlines check --debug
+```
+
 **Show all results (not just violations):**
 ```bash
 threadlines check --full
 ```
 
+**Enable debug logging:**
+```bash
+threadlines check --debug
+```
+
 **Options:**
-- `--api-url <url>` - Override the server URL (default: http://localhost:3000)
-- `--commit <ref>` - Review specific commit. Accepts commit SHA or git reference (e.g., `HEAD`, `HEAD~1`, `abc123`)
-- `--branch <name>` - Review all commits in branch vs base
-- `--file <path>` - Review entire file (all lines as additions)
-- `--folder <path>` - Review all files in folder recursively
-- `--files <paths...>` - Review multiple specified files
+- `--commit <ref>` - Review specific commit. Accepts commit SHA or git reference (e.g., `HEAD`, `HEAD~1`, `abc123`). Sets review context to `commit`.
+- `--file <path>` - Review entire file (all lines as additions). Sets review context to `file`.
+- `--folder <path>` - Review all files in folder recursively. Sets review context to `folder`.
+- `--files <paths...>` - Review multiple specified files. Sets review context to `files`.
 - `--full` - Show all results (compliant, attention, not_relevant). Default: only attention items
+- `--debug` - Enable debug logging (verbose output for troubleshooting)
+
+**Note:** Flags (`--commit`, `--file`, `--folder`, `--files`) are for local development only. In CI/CD environments, these flags are ignored and the CLI auto-detects the appropriate context.
 
 **Auto-detection in CI:**
-- CI with branch detected → reviews all commits in branch vs base
-- CI with commit SHA detected → reviews specific commit
-- Local development → reviews staged/unstaged changes
+- **Pull Request/Merge Request context** → Reviews all changes in the PR/MR (review context: `pr`)
+- **Push to any branch** → Reviews the commit being pushed (review context: `commit`)
+- **Local development** → Reviews staged/unstaged changes (review context: `local`)
 
 ## Configuration
 
@@ -135,11 +139,40 @@ threadlines check --full
 |----------|---------|----------|
 | `THREADLINE_API_KEY` | Authentication with Threadlines API | Yes |
 | `THREADLINE_ACCOUNT` | Your Threadlines account email | Yes |
-| `THREADLINE_API_URL` | Custom API endpoint (default: https://devthreadline.com) | No |
 
 Both required variables can be set in a `.env.local` file (recommended for local development) or as environment variables (required for CI/CD).
 
-The optional `THREADLINE_API_URL` allows you to point to a custom server if you want to intercept telemetry with your own endpoint. It can also be set with the `--api-url` flag.
+**Local Development:**
+Create a `.env.local` file in your project root:
+```bash
+THREADLINE_API_KEY=your-api-key-here
+THREADLINE_ACCOUNT=your-email@example.com
+```
+
+**CI/CD:**
+Set these as environment variables in your platform:
+- **GitHub Actions**: Settings → Secrets → Add variables
+- **GitLab CI**: Settings → CI/CD → Variables
+- **Bitbucket Pipelines**: Repository settings → Repository variables
+- **Vercel**: Settings → Environment Variables
+
+Get your credentials at: https://devthreadline.com/settings
+
+### Configuration File (`.threadlinerc`)
+
+You can customize the API endpoint and other settings by creating a `.threadlinerc` file in your project root:
+
+```json
+{
+  "mode": "online",
+  "api_url": "https://devthreadline.com",
+  "openai_model": "gpt-5.2",
+  "openai_service_tier": "Flex",
+  "diff_context_lines": 10
+}
+```
+
+The `api_url` field allows you to point to a custom server if needed. Default is `https://devthreadline.com`.
 
 ## Threadline Files
 
@@ -176,26 +209,38 @@ Your guidelines and standards here...
 
 - **`context_files`**: Array of file paths that provide context (always included, even if unchanged)
 
-### Example: SQL Queries with Schema Context
+### Example: Feature Flagging Standards
 
 ```markdown
 ---
-id: sql-queries
+id: feature-flags
 version: 1.0.0
 patterns:
-  - "**/queries/**"
-  - "**/*.sql"
+  - "**/features/**"
+  - "**/components/**"
+  - "**/*.tsx"
+  - "**/*.ts"
 context_files:
-  - "schema.sql"
+  - "config/feature-flags.ts"
 ---
 
-# SQL Query Standards
+# Feature Flag Standards
+
+All feature flag usage must:
+- Check flags using the centralized `isFeatureEnabled()` function from `config/feature-flags.ts`
+- Never hardcode feature flag names as strings (use constants from the config)
+- Include proper cleanup: remove feature flag checks when features are fully rolled out
+- Document rollout plan in PR description (target percentage, timeline)
+- Use feature flags for gradual rollouts, not as permanent configuration
 
-All SQL queries must:
-- Reference tables and columns that exist in schema.sql
-- Use parameterized queries (no string concatenation)
-- Include proper indexes for WHERE clauses
+**Violations:**
+- ❌ `if (process.env.NEW_FEATURE === 'true')` (hardcoded, not using registry)
+- ❌ `if (flags['new-feature'])` (string literal instead of constant)
+- ✅ `if (isFeatureEnabled(FeatureFlags.NEW_DASHBOARD))` (using centralized function)
 ```
 
-The `schema.sql` file will always be included as context, even if you're only changing query files.
+The `config/feature-flags.ts` file will always be included as context, ensuring the AI reviewer can verify that:
+- Feature flag names match the registry
+- The correct flag checking function is used
+- Flags are properly typed and documented
 

package/dist/api/client.js

@@ -1,23 +1,60 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReviewAPIClient = void 0;
-const axios_1 = __importDefault(require("axios"));
 class ReviewAPIClient {
     constructor(baseURL) {
-        this.client = axios_1.default.create({
-            baseURL,
-            timeout: 60000, // 60s timeout for entire request
-            headers: {
-                'Content-Type': 'application/json'
+        this.timeout = 60000; // 60s timeout for entire request
+        this.baseURL = baseURL;
+    }
+    async fetchWithTimeout(url, options) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            return response;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            // Handle AbortError from timeout
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`Request timeout after ${this.timeout}ms`);
             }
-        });
+            throw error;
+        }
     }
     async review(request) {
-        const response = await this.client.post('/api/threadline-check', request);
-        return response.data;
+        const url = `${this.baseURL}/api/threadline-check`;
+        const response = await this.fetchWithTimeout(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+        return await response.json();
+    }
+    async syncResults(request) {
+        const url = `${this.baseURL}/api/threadline-check-results`;
+        const response = await this.fetchWithTimeout(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+        return await response.json();
     }
 }
 exports.ReviewAPIClient = ReviewAPIClient;