@compilr-dev/sdk 0.9.7 → 0.9.9

package/dist/detection/common.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Common Detection Utilities
+ *
+ * Shared by all type-specific strategies: git detection, README parsing,
+ * file counting, folder name parsing.
+ */
+import type { DetectionResult } from './types.js';
+/**
+ * Detect common project info (runs for ALL project types).
+ * Returns a base DetectionResult with name, git, README, file counts.
+ */
+export declare function detectCommon(projectPath: string): DetectionResult;
+/**
+ * List files matching a pattern in a directory (non-recursive or single level).
+ */
+export declare function findFiles(dir: string, predicate: (name: string, ext: string) => boolean, maxDepth?: number): string[];
+/**
+ * Check if a directory exists within the project.
+ */
+export declare function hasDirectory(projectPath: string, dirName: string): boolean;
+/**
+ * Read a file's content if it exists, or return undefined.
+ */
+export declare function readFileIfExists(filePath: string): string | undefined;

package/dist/detection/common.js

@@ -0,0 +1,247 @@
+/**
+ * Common Detection Utilities
+ *
+ * Shared by all type-specific strategies: git detection, README parsing,
+ * file counting, folder name parsing.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, basename, extname } from 'node:path';
+/** Directories to skip when scanning */
+const IGNORED_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.tox',
+    '.mypy_cache',
+    '.pytest_cache',
+    '.next',
+    '.nuxt',
+    'dist',
+    'build',
+    'target',
+    '.gradle',
+    '.idea',
+    '.vscode',
+    '.DS_Store',
+    'vendor',
+    '.compilr',
+    '.compilr-dev',
+]);
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg']);
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.markdown', '.mdx']);
+/**
+ * Detect common project info (runs for ALL project types).
+ * Returns a base DetectionResult with name, git, README, file counts.
+ */
+export function detectCommon(projectPath) {
+    const folderName = basename(projectPath);
+    const name = slugify(folderName);
+    const displayName = prettify(folderName);
+    // Git detection
+    const hasGit = existsSync(join(projectPath, '.git'));
+    let gitRemote;
+    if (hasGit) {
+        gitRemote = readGitRemote(projectPath);
+    }
+    // COMPILR.md
+    const hasCompilrMd = existsSync(join(projectPath, 'COMPILR.md'));
+    // Description from README
+    const description = readDescription(projectPath);
+    // File counting
+    const content = countFiles(projectPath);
+    return {
+        name,
+        displayName,
+        description,
+        gitRemote,
+        hasGit,
+        hasCompilrMd,
+        content,
+    };
+}
+/**
+ * Read the git remote URL from .git/config.
+ */
+function readGitRemote(projectPath) {
+    const configPath = join(projectPath, '.git', 'config');
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const config = readFileSync(configPath, 'utf-8');
+        const match = config.match(/\[remote "origin"\]\s*\n\s*url\s*=\s*(.+)/);
+        return match?.[1]?.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read description from README.md or COMPILR.md (first non-heading paragraph).
+ */
+function readDescription(projectPath) {
+    const candidates = ['README.md', 'readme.md', 'COMPILR.md'];
+    for (const file of candidates) {
+        const filePath = join(projectPath, file);
+        if (!existsSync(filePath))
+            continue;
+        try {
+            const content = readFileSync(filePath, 'utf-8');
+            const lines = content.split('\n');
+            // Find first non-empty, non-heading line
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                if (trimmed.startsWith('#'))
+                    continue;
+                if (trimmed.startsWith('!['))
+                    continue; // badge images
+                if (trimmed.startsWith('<!--'))
+                    continue;
+                // Found a content line — take up to 200 chars
+                return trimmed.length > 200 ? trimmed.slice(0, 200) + '...' : trimmed;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return undefined;
+}
+/**
+ * Count files in a project directory (non-recursive into ignored dirs).
+ */
+function countFiles(projectPath) {
+    let fileCount = 0;
+    let totalSizeBytes = 0;
+    let markdownFiles = 0;
+    let imageFiles = 0;
+    function walk(dir, depth) {
+        if (depth > 8)
+            return; // Don't go too deep
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            if (entry.startsWith('.') && entry !== '.git')
+                continue;
+            const fullPath = join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(fullPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                walk(fullPath, depth + 1);
+            }
+            else if (stat.isFile()) {
+                fileCount++;
+                totalSizeBytes += stat.size;
+                const ext = extname(entry).toLowerCase();
+                if (MARKDOWN_EXTENSIONS.has(ext))
+                    markdownFiles++;
+                if (IMAGE_EXTENSIONS.has(ext))
+                    imageFiles++;
+            }
+        }
+    }
+    walk(projectPath, 0);
+    return {
+        fileCount,
+        totalSizeKB: Math.round(totalSizeBytes / 1024),
+        markdownFiles,
+        imageFiles,
+    };
+}
+/**
+ * List files matching a pattern in a directory (non-recursive or single level).
+ */
+export function findFiles(dir, predicate, maxDepth = 2) {
+    const results = [];
+    function walk(currentDir, depth) {
+        if (depth > maxDepth)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(currentDir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (IGNORED_DIRS.has(entry))
+                continue;
+            const fullPath = join(currentDir, entry);
+            let stat;
+            try {
+                stat = statSync(fullPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                walk(fullPath, depth + 1);
+            }
+            else if (stat.isFile()) {
+                const ext = extname(entry).toLowerCase();
+                if (predicate(entry, ext)) {
+                    // Return relative path from root dir
+                    results.push(fullPath.slice(dir.length + 1));
+                }
+            }
+        }
+    }
+    walk(dir, 0);
+    return results;
+}
+/**
+ * Check if a directory exists within the project.
+ */
+export function hasDirectory(projectPath, dirName) {
+    const dirPath = join(projectPath, dirName);
+    try {
+        return existsSync(dirPath) && statSync(dirPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a file's content if it exists, or return undefined.
+ */
+export function readFileIfExists(filePath) {
+    try {
+        if (existsSync(filePath))
+            return readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        /* ignore */
+    }
+    return undefined;
+}
+/**
+ * Slugify a folder name for use as project name.
+ */
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9-]/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Prettify a folder name for display.
+ */
+function prettify(name) {
+    return name.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}

package/dist/detection/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Project Detection — Universal project content detection.
+ */
+export { detectProject, suggestProjectType } from './project-detector.js';
+export { detectCommon } from './common.js';
+export type { DetectProjectOptions, DetectionResult, ContentSummary, DetectionStrategy, } from './types.js';

package/dist/detection/index.js

@@ -0,0 +1,5 @@
+/**
+ * Project Detection — Universal project content detection.
+ */
+export { detectProject, suggestProjectType } from './project-detector.js';
+export { detectCommon } from './common.js';

package/dist/detection/project-detector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Project Detector — Universal project detection dispatcher.
+ *
+ * Runs common detection (git, README, file counts) for all types,
+ * then delegates to a type-specific strategy for additional scanning.
+ */
+import type { DetectProjectOptions, DetectionResult } from './types.js';
+/**
+ * Detect project contents based on the specified type.
+ *
+ * 1. Runs common detection (git, README, file counts) for all types
+ * 2. Delegates to type-specific strategy for additional scanning
+ *
+ * @example
+ * ```typescript
+ * const result = await detectProject({
+ *   path: '/Users/me/projects/my-app',
+ *   type: 'web',
+ * });
+ * console.log(result.content.language); // 'typescript'
+ * console.log(result.content.framework); // 'react + express'
+ * ```
+ */
+export declare function detectProject(options: DetectProjectOptions): DetectionResult;
+/**
+ * Quick check to suggest a project type based on folder contents.
+ * Returns the most likely type, or 'general' if uncertain.
+ */
+export declare function suggestProjectType(projectPath: string): string;

package/dist/detection/project-detector.js

@@ -0,0 +1,106 @@
+/**
+ * Project Detector — Universal project detection dispatcher.
+ *
+ * Runs common detection (git, README, file counts) for all types,
+ * then delegates to a type-specific strategy for additional scanning.
+ */
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { detectCommon } from './common.js';
+import { detectSoftware } from './strategies/software.js';
+import { detectResearch } from './strategies/research.js';
+import { detectBook } from './strategies/book.js';
+import { detectBusiness } from './strategies/business.js';
+import { detectContent } from './strategies/content.js';
+import { detectTechDocs } from './strategies/tech-docs.js';
+import { detectCourse } from './strategies/course.js';
+import { detectGeneral } from './strategies/general.js';
+/**
+ * Strategy map — maps project type IDs to detection functions.
+ * Software subtypes (web, cli, library, api) all use the software strategy.
+ */
+const STRATEGIES = {
+    // Software types
+    web: detectSoftware,
+    cli: detectSoftware,
+    library: detectSoftware,
+    api: detectSoftware,
+    // Non-software types
+    research: detectResearch,
+    book: detectBook,
+    'business-plan': detectBusiness,
+    content: detectContent,
+    'tech-docs': detectTechDocs,
+    course: detectCourse,
+    // Catch-all
+    general: detectGeneral,
+};
+/**
+ * Detect project contents based on the specified type.
+ *
+ * 1. Runs common detection (git, README, file counts) for all types
+ * 2. Delegates to type-specific strategy for additional scanning
+ *
+ * @example
+ * ```typescript
+ * const result = await detectProject({
+ *   path: '/Users/me/projects/my-app',
+ *   type: 'web',
+ * });
+ * console.log(result.content.language); // 'typescript'
+ * console.log(result.content.framework); // 'react + express'
+ * ```
+ */
+export function detectProject(options) {
+    // Step 1: Common detection (runs for ALL types)
+    const base = detectCommon(options.path);
+    // Step 2: Type-specific strategy
+    const strategy = STRATEGIES[options.type] ?? detectGeneral;
+    const enrichedContent = strategy(options.path, base.content);
+    return {
+        ...base,
+        content: enrichedContent,
+    };
+}
+/**
+ * Quick check to suggest a project type based on folder contents.
+ * Returns the most likely type, or 'general' if uncertain.
+ */
+export function suggestProjectType(projectPath) {
+    // Software indicators (strongest signals)
+    if (existsSync(join(projectPath, 'package.json')))
+        return 'web';
+    if (existsSync(join(projectPath, 'go.mod')))
+        return 'web';
+    if (existsSync(join(projectPath, 'Cargo.toml')))
+        return 'web';
+    if (existsSync(join(projectPath, 'pyproject.toml')) ||
+        existsSync(join(projectPath, 'requirements.txt'))) {
+        // Python could be software or research — check for research indicators
+        if (existsSync(join(projectPath, 'references.bib')) ||
+            existsSync(join(projectPath, 'main.tex'))) {
+            return 'research';
+        }
+        return 'web';
+    }
+    if (existsSync(join(projectPath, 'pom.xml')) || existsSync(join(projectPath, 'build.gradle')))
+        return 'web';
+    // Research indicators
+    try {
+        const entries = readdirSync(projectPath);
+        if (entries.some((f) => f.endsWith('.bib')))
+            return 'research';
+        if (entries.includes('main.tex'))
+            return 'research';
+        // Tech docs indicators
+        if (entries.includes('mkdocs.yml') || entries.includes('docusaurus.config.js'))
+            return 'tech-docs';
+        // Book indicators
+        if (entries.some((f) => /^(chapter|ch)[-_]?\d/i.test(f)))
+            return 'book';
+    }
+    catch {
+        /* unreadable directory */
+    }
+    return 'general';
+}

package/dist/detection/strategies/book.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Book Detection Strategy
+ *
+ * Detects: chapter files, outline, manuscript/draft folders.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectBook(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/book.js

@@ -0,0 +1,48 @@
+/**
+ * Book Detection Strategy
+ *
+ * Detects: chapter files, outline, manuscript/draft folders.
+ */
+import { join } from 'node:path';
+import { findFiles, hasDirectory } from '../common.js';
+export function detectBook(path, base) {
+    const result = { ...base };
+    // Chapter files (chapter-1.md, ch01.md, chapters/01-intro.md, etc.)
+    const chapterPattern = /^(chapter|ch)[-_]?\d/i;
+    const chapterFiles = findFiles(path, (name) => chapterPattern.test(name), 2);
+    // Also check chapters/ directory
+    if (hasDirectory(path, 'chapters')) {
+        const inDir = findFiles(join(path, 'chapters'), (_name, ext) => ext === '.md' || ext === '.txt', 1);
+        chapterFiles.push(...inDir.map((f) => `chapters/${f}`));
+    }
+    if (chapterFiles.length > 0) {
+        result.chapterCount = chapterFiles.length;
+    }
+    // Outline file
+    const outlineCandidates = [
+        'outline.md',
+        'outline.txt',
+        'OUTLINE.md',
+        'toc.md',
+        'table-of-contents.md',
+    ];
+    for (const candidate of outlineCandidates) {
+        const found = findFiles(path, (name) => name.toLowerCase() === candidate.toLowerCase(), 0);
+        if (found.length > 0) {
+            result.outlineFile = found[0];
+            break;
+        }
+    }
+    // Draft/manuscript files
+    const draftDirs = ['manuscript', 'drafts', 'draft', 'content'];
+    for (const dir of draftDirs) {
+        if (hasDirectory(path, dir)) {
+            const drafts = findFiles(join(path, dir), (_name, ext) => ext === '.md' || ext === '.txt', 1);
+            if (drafts.length > 0) {
+                result.draftFiles = drafts.map((f) => `${dir}/${f}`);
+                break;
+            }
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/business.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Business Plan Detection Strategy
+ *
+ * Detects: spreadsheets, presentations, analysis folders.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectBusiness(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/business.js

@@ -0,0 +1,22 @@
+/**
+ * Business Plan Detection Strategy
+ *
+ * Detects: spreadsheets, presentations, analysis folders.
+ */
+import { findFiles } from '../common.js';
+export function detectBusiness(path, base) {
+    const result = { ...base };
+    // Spreadsheet files
+    const spreadsheetExts = new Set(['.xlsx', '.xls', '.csv', '.tsv', '.ods']);
+    const spreadsheets = findFiles(path, (_name, ext) => spreadsheetExts.has(ext), 2);
+    if (spreadsheets.length > 0) {
+        result.spreadsheetFiles = spreadsheets.length;
+    }
+    // Presentation files
+    const presentationExts = new Set(['.pptx', '.ppt', '.pdf', '.key']);
+    const presentations = findFiles(path, (_name, ext) => presentationExts.has(ext), 2);
+    if (presentations.length > 0) {
+        result.presentationFiles = presentations.length;
+    }
+    return result;
+}

package/dist/detection/strategies/content.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Content & Marketing Detection Strategy
+ *
+ * Detects: article folders, editorial calendar, media assets.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectContent(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/content.js

@@ -0,0 +1,21 @@
+/**
+ * Content & Marketing Detection Strategy
+ *
+ * Detects: article folders, editorial calendar, media assets.
+ */
+import { findFiles, hasDirectory } from '../common.js';
+export function detectContent(path, base) {
+    const result = { ...base };
+    // Draft files in common content directories
+    const contentDirs = ['articles', 'posts', 'content', 'blog', 'drafts'];
+    for (const dir of contentDirs) {
+        if (hasDirectory(path, dir)) {
+            const drafts = findFiles(`${path}/${dir}`, (_name, ext) => ext === '.md' || ext === '.txt', 1);
+            if (drafts.length > 0) {
+                result.draftFiles = drafts.map((f) => `${dir}/${f}`);
+                break;
+            }
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/course.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Course / Training Detection Strategy
+ *
+ * Detects: lesson/module directories, exercise files, syllabus.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectCourse(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/course.js

@@ -0,0 +1,30 @@
+/**
+ * Course / Training Detection Strategy
+ *
+ * Detects: lesson/module directories, exercise files, syllabus.
+ */
+import { join } from 'node:path';
+import { findFiles, hasDirectory } from '../common.js';
+export function detectCourse(path, base) {
+    const result = { ...base };
+    // Lesson/module directories
+    const lessonDirs = ['modules', 'lessons', 'units', 'weeks', 'sessions'];
+    for (const dir of lessonDirs) {
+        if (hasDirectory(path, dir)) {
+            // Count subdirectories as lessons
+            const items = findFiles(join(path, dir), () => true, 0);
+            result.lessonCount = items.length;
+            break;
+        }
+    }
+    // Exercise files
+    const exerciseDirs = ['exercises', 'homework', 'labs', 'assignments'];
+    for (const dir of exerciseDirs) {
+        if (hasDirectory(path, dir)) {
+            const files = findFiles(join(path, dir), () => true, 1);
+            result.exerciseFiles = files.length;
+            break;
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/general.d.ts

@@ -0,0 +1,8 @@
+/**
+ * General Detection Strategy
+ *
+ * Minimal scan — just the common detection (git, README, file counts).
+ * No type-specific additions.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectGeneral(_path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/general.js

@@ -0,0 +1,10 @@
+/**
+ * General Detection Strategy
+ *
+ * Minimal scan — just the common detection (git, README, file counts).
+ * No type-specific additions.
+ */
+export function detectGeneral(_path, base) {
+    // Common detection already covers everything for general projects
+    return { ...base };
+}

package/dist/detection/strategies/research.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Research Detection Strategy
+ *
+ * Detects: bibliography files, LaTeX, data files, draft folders.
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectResearch(path: string, base: ContentSummary): ContentSummary;

package/dist/detection/strategies/research.js

@@ -0,0 +1,44 @@
+/**
+ * Research Detection Strategy
+ *
+ * Detects: bibliography files, LaTeX, data files, draft folders.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findFiles, hasDirectory } from '../common.js';
+export function detectResearch(path, base) {
+    const result = { ...base };
+    // Bibliography (.bib files)
+    const bibFiles = findFiles(path, (_name, ext) => ext === '.bib', 1);
+    if (bibFiles.length > 0) {
+        result.bibliographyFile = bibFiles[0];
+        try {
+            const content = readFileSync(join(path, bibFiles[0]), 'utf-8');
+            result.bibliographyEntries = (content.match(/@\w+\{/g) ?? []).length;
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    // LaTeX files
+    const texFiles = findFiles(path, (_name, ext) => ext === '.tex', 2);
+    if (texFiles.length > 0) {
+        result.latexFiles = texFiles;
+    }
+    // Data files (.csv, .xlsx, .json in data/ or root)
+    const dataExtensions = new Set(['.csv', '.xlsx', '.xls', '.json', '.tsv']);
+    const dataFiles = findFiles(path, (_name, ext) => dataExtensions.has(ext), 2);
+    if (dataFiles.length > 0) {
+        result.dataFiles = dataFiles.length;
+    }
+    // Check for common research folders
+    if (hasDirectory(path, 'drafts') || hasDirectory(path, 'papers')) {
+        // Count draft markdown files
+        const draftDir = hasDirectory(path, 'drafts') ? 'drafts' : 'papers';
+        const drafts = findFiles(join(path, draftDir), (_name, ext) => ext === '.md' || ext === '.tex', 1);
+        if (drafts.length > 0) {
+            result.draftFiles = drafts.map((f) => `${draftDir}/${f}`);
+        }
+    }
+    return result;
+}

package/dist/detection/strategies/software.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Software Detection Strategy
+ *
+ * Detects: language, framework, package manager, entry points, test framework.
+ * Uses file-based heuristics (package.json, go.mod, pyproject.toml, etc.).
+ */
+import type { ContentSummary } from '../types.js';
+export declare function detectSoftware(path: string, base: ContentSummary): ContentSummary;