threadlines 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# threadlines
+
+Threadline CLI - AI-powered linter based on your natural language documentation.
+
+## Installation
+
+```bash
+npm install -g threadlines
+```
+
+Or use with npx:
+
+```bash
+npx threadlines check
+```
+
+## Usage
+
+```bash
+threadlines check
+```
+
+## Configuration
+
+- `THREADLINE_API_URL` - Server URL (default: http://localhost:3000)
+- `OPENAI_API_KEY` - Your OpenAI API key (required)
+
+## Expert Files
+
+Create a `/threadlines` folder in your repository with markdown files. See [Threadline Format](../../docs/EXPERT_FORMAT.md) for details.
+

package/bin/threadline

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+require('../dist/index.js');
+

package/dist/api/client.js

@@ -0,0 +1,36 @@
+"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'
+            }
+        });
+    }
+    async review(request) {
+        try {
+            const response = await this.client.post('/api/threadline-check', request);
+            return response.data;
+        }
+        catch (error) {
+            if (error.response) {
+                throw new Error(`API error: ${error.response.status} - ${error.response.data?.message || error.message}`);
+            }
+            else if (error.request) {
+                throw new Error(`Network error: Could not reach Threadline server at ${this.client.defaults.baseURL}`);
+            }
+            else {
+                throw new Error(`Request error: ${error.message}`);
+            }
+        }
+    }
+}
+exports.ReviewAPIClient = ReviewAPIClient;

package/dist/commands/check.js

@@ -0,0 +1,157 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkCommand = checkCommand;
+const experts_1 = require("../validators/experts");
+const diff_1 = require("../git/diff");
+const client_1 = require("../api/client");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+async function checkCommand(options) {
+    const repoRoot = process.cwd();
+    console.log(chalk_1.default.blue('🔍 Threadline: Checking code against your threadlines...\n'));
+    try {
+        // 1. Find and validate threadlines
+        console.log(chalk_1.default.gray('📋 Finding threadlines...'));
+        const threadlines = await (0, experts_1.findThreadlines)(repoRoot);
+        console.log(chalk_1.default.green(`✓ Found ${threadlines.length} threadline(s)\n`));
+        if (threadlines.length === 0) {
+            console.log(chalk_1.default.yellow('⚠️  No valid threadlines found. Add threadline files to /threadlines folder.'));
+            process.exit(0);
+        }
+        // 2. Get git diff
+        console.log(chalk_1.default.gray('📝 Collecting git changes...'));
+        const gitDiff = await (0, diff_1.getGitDiff)(repoRoot);
+        if (gitDiff.changedFiles.length === 0) {
+            console.log(chalk_1.default.yellow('⚠️  No changes detected. Make some code changes and try again.'));
+            process.exit(0);
+        }
+        console.log(chalk_1.default.green(`✓ Found ${gitDiff.changedFiles.length} changed file(s)\n`));
+        // 3. Read context files for each threadline
+        const threadlinesWithContext = threadlines.map(threadline => {
+            const contextContent = {};
+            if (threadline.contextFiles) {
+                for (const contextFile of threadline.contextFiles) {
+                    const fullPath = path.join(repoRoot, contextFile);
+                    if (fs.existsSync(fullPath)) {
+                        contextContent[contextFile] = fs.readFileSync(fullPath, 'utf-8');
+                    }
+                }
+            }
+            return {
+                id: threadline.id,
+                version: threadline.version,
+                patterns: threadline.patterns,
+                content: threadline.content,
+                contextFiles: threadline.contextFiles,
+                contextContent
+            };
+        });
+        // 4. Get API URL and key
+        const apiUrl = options.apiUrl || process.env.THREADLINE_API_URL || 'http://localhost:3000';
+        const apiKey = options.apiKey || process.env.OPENAI_API_KEY;
+        if (!apiKey) {
+            throw new Error('OpenAI API key required. Set OPENAI_API_KEY environment variable.');
+        }
+        // 5. Call review API
+        console.log(chalk_1.default.gray('🤖 Running threadline checks...'));
+        const client = new client_1.ReviewAPIClient(apiUrl);
+        const response = await client.review({
+            threadlines: threadlinesWithContext,
+            diff: gitDiff.diff,
+            files: gitDiff.changedFiles,
+            apiKey
+        });
+        // 6. Display results
+        displayResults(response);
+        // Exit with appropriate code
+        const hasAttention = response.results.some(r => r.status === 'attention');
+        process.exit(hasAttention ? 1 : 0);
+    }
+    catch (error) {
+        console.error(chalk_1.default.red(`\n❌ Error: ${error.message}`));
+        process.exit(1);
+    }
+}
+function displayResults(response) {
+    const { results, metadata } = response;
+    console.log('\n' + chalk_1.default.bold('Results:\n'));
+    console.log(chalk_1.default.gray(`${metadata.totalThreadlines} threadlines checked`));
+    const notRelevant = results.filter((r) => r.status === 'not_relevant').length;
+    const compliant = results.filter((r) => r.status === 'compliant').length;
+    const attention = results.filter((r) => r.status === 'attention').length;
+    if (notRelevant > 0) {
+        console.log(chalk_1.default.gray(`  ${notRelevant} not relevant`));
+    }
+    if (compliant > 0) {
+        console.log(chalk_1.default.green(`  ${compliant} compliant`));
+    }
+    if (attention > 0) {
+        console.log(chalk_1.default.yellow(`  ${attention} attention`));
+    }
+    if (metadata.timedOut > 0) {
+        console.log(chalk_1.default.yellow(`  ${metadata.timedOut} timed out`));
+    }
+    if (metadata.errors > 0) {
+        console.log(chalk_1.default.red(`  ${metadata.errors} errors`));
+    }
+    console.log('');
+    // Show attention items
+    const attentionItems = results.filter((r) => r.status === 'attention');
+    if (attentionItems.length > 0) {
+        for (const item of attentionItems) {
+            console.log(chalk_1.default.yellow(`⚠️  ${item.expertId}`));
+            if (item.fileReferences && item.fileReferences.length > 0) {
+                for (const fileRef of item.fileReferences) {
+                    const lineRef = item.lineReferences?.[item.fileReferences.indexOf(fileRef)];
+                    const lineStr = lineRef ? `:${lineRef}` : '';
+                    console.log(chalk_1.default.gray(`   ${fileRef}${lineStr} - ${item.reasoning || 'Needs attention'}`));
+                }
+            }
+            else if (item.reasoning) {
+                console.log(chalk_1.default.gray(`   ${item.reasoning}`));
+            }
+        }
+        console.log('');
+    }
+    // Show compliant items (optional, can be verbose)
+    if (attentionItems.length === 0 && compliant > 0) {
+        console.log(chalk_1.default.green('✓ All threadlines passed!\n'));
+    }
+}

package/dist/git/diff.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getGitDiff = getGitDiff;
+const simple_git_1 = __importDefault(require("simple-git"));
+async function getGitDiff(repoRoot) {
+    const git = (0, simple_git_1.default)(repoRoot);
+    // Check if we're in a git repo
+    const isRepo = await git.checkIsRepo();
+    if (!isRepo) {
+        throw new Error('Not a git repository. Threadline requires a git repository.');
+    }
+    // Get diff (staged changes, or unstaged if no staged)
+    const status = await git.status();
+    let diff;
+    if (status.staged.length > 0) {
+        // Use staged changes
+        diff = await git.diff(['--cached']);
+    }
+    else if (status.files.length > 0) {
+        // Use unstaged changes
+        diff = await git.diff();
+    }
+    else {
+        // No changes
+        return {
+            diff: '',
+            changedFiles: []
+        };
+    }
+    // Get list of changed files
+    const changedFiles = status.files
+        .filter(f => f.working_dir !== ' ' || f.index !== ' ')
+        .map(f => f.path);
+    return {
+        diff: diff || '',
+        changedFiles
+    };
+}

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const check_1 = require("./commands/check");
+const program = new commander_1.Command();
+program
+    .name('threadline')
+    .description('AI-powered linter based on your natural language documentation')
+    .version('0.1.0');
+program
+    .command('check')
+    .description('Check code against your experts')
+    .option('--api-url <url>', 'Threadline server URL', process.env.THREADLINE_API_URL || 'http://localhost:3000')
+    .option('--api-key <key>', 'OpenAI API key', process.env.OPENAI_API_KEY)
+    .action(check_1.checkCommand);
+program.parse();

package/dist/types/expert.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/validators/experts.js

@@ -0,0 +1,133 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findThreadlines = findThreadlines;
+exports.validateThreadline = validateThreadline;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+const REQUIRED_FIELDS = ['id', 'version', 'patterns'];
+async function findThreadlines(repoRoot) {
+    const expertsDir = path.join(repoRoot, 'threadlines');
+    if (!fs.existsSync(expertsDir)) {
+        throw new Error('No /threadlines folder found. Create a /threadlines folder with your threadline markdown files.');
+    }
+    const files = fs.readdirSync(expertsDir);
+    const expertFiles = files.filter(f => f.endsWith('.md'));
+    if (expertFiles.length === 0) {
+        throw new Error('No threadline files found in /threadlines folder. Add .md files with threadline definitions.');
+    }
+    const threadlines = [];
+    for (const file of expertFiles) {
+        const result = await validateThreadline(path.join(expertsDir, file), repoRoot);
+        if (result.valid && result.threadline) {
+            threadlines.push(result.threadline);
+        }
+        else {
+            console.warn(`⚠️  Skipping ${file}: ${result.errors?.join(', ')}`);
+        }
+    }
+    return threadlines;
+}
+async function validateThreadline(filePath, repoRoot) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        // Parse YAML frontmatter
+        const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+        if (!frontmatterMatch) {
+            return {
+                valid: false,
+                errors: ['Missing YAML frontmatter. Threadline files must start with ---']
+            };
+        }
+        const frontmatter = yaml.load(frontmatterMatch[1]);
+        const body = frontmatterMatch[2].trim();
+        // Validate required fields
+        const errors = [];
+        for (const field of REQUIRED_FIELDS) {
+            if (!frontmatter[field]) {
+                errors.push(`Missing required field: ${field}`);
+            }
+        }
+        // Validate patterns
+        if (frontmatter.patterns && !Array.isArray(frontmatter.patterns)) {
+            errors.push('patterns must be an array');
+        }
+        if (frontmatter.patterns && frontmatter.patterns.length === 0) {
+            errors.push('patterns array cannot be empty');
+        }
+        // Validate context_files if present
+        if (frontmatter.context_files) {
+            if (!Array.isArray(frontmatter.context_files)) {
+                errors.push('context_files must be an array');
+            }
+            else {
+                // Check if context files exist
+                for (const contextFile of frontmatter.context_files) {
+                    const fullPath = path.join(repoRoot, contextFile);
+                    if (!fs.existsSync(fullPath)) {
+                        errors.push(`Context file not found: ${contextFile}`);
+                    }
+                }
+            }
+        }
+        // Validate body has content
+        if (!body || body.length === 0) {
+            errors.push('Threadline body cannot be empty');
+        }
+        // Validate version format (basic semver check)
+        if (frontmatter.version && !/^\d+\.\d+\.\d+/.test(frontmatter.version)) {
+            errors.push('version must be in semver format (e.g., 1.0.0)');
+        }
+        if (errors.length > 0) {
+            return { valid: false, errors };
+        }
+        const threadline = {
+            id: frontmatter.id,
+            version: frontmatter.version,
+            patterns: frontmatter.patterns,
+            contextFiles: frontmatter.context_files || [],
+            content: body,
+            filePath: path.relative(repoRoot, filePath)
+        };
+        return { valid: true, threadline };
+    }
+    catch (error) {
+        return {
+            valid: false,
+            errors: [`Failed to parse threadline file: ${error.message}`]
+        };
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "threadlines",
+  "version": "0.1.0",
+  "description": "Threadline CLI - AI-powered linter based on your natural language documentation",
+  "main": "dist/index.js",
+  "bin": {
+    "threadline": "./bin/threadline"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "keywords": [
+    "code-quality",
+    "linter",
+    "ai",
+    "code-review",
+    "threadline",
+    "code-standards"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ngrootscholten/threadline.git",
+    "directory": "packages/cli"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "simple-git": "^3.27.0",
+    "axios": "^1.7.9",
+    "chalk": "^4.1.2",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^5.7.2"
+  }
+}
+