@10kdevs/matha 0.1.0

package/dist/analysis/git-analyser.js

@@ -0,0 +1,261 @@
+import { simpleGit } from 'simple-git';
+import * as fs from 'fs/promises';
+import * as path from 'path';
+// ──────────────────────────────────────────────────────────────
+// CONSTANTS
+// ──────────────────────────────────────────────────────────────
+const DEFAULT_MAX_COMMITS = 500;
+const DEFAULT_MAX_CO_CHANGE_PAIRS = 50;
+const DEFAULT_EXCLUDE_PATHS = ['node_modules', '.git', 'dist', '.matha', 'coverage'];
+const CO_CHANGE_FILES_PER_COMMIT_CAP = 20;
+const BINARY_EXTENSIONS = new Set([
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.svg',
+    '.woff', '.woff2', '.ttf', '.eot',
+    '.pdf', '.zip', '.tar', '.gz',
+]);
+// ──────────────────────────────────────────────────────────────
+// HELPERS
+// ──────────────────────────────────────────────────────────────
+function normalisePath(filepath) {
+    return filepath.replace(/\\/g, '/');
+}
+function isBinaryFile(filepath) {
+    const ext = path.extname(filepath).toLowerCase();
+    return BINARY_EXTENSIONS.has(ext);
+}
+function isExcluded(filepath, excludePaths) {
+    const normalised = normalisePath(filepath);
+    for (const exclude of excludePaths) {
+        if (normalised.startsWith(exclude + '/') || normalised === exclude) {
+            return true;
+        }
+        // Also check path segments
+        const segments = normalised.split('/');
+        if (segments.includes(exclude)) {
+            return true;
+        }
+    }
+    return false;
+}
+function shouldIncludeFile(filepath, excludePaths) {
+    if (!filepath || filepath.trim() === '')
+        return false;
+    if (isBinaryFile(filepath))
+        return false;
+    if (isExcluded(filepath, excludePaths))
+        return false;
+    return true;
+}
+function makeCoChangeKey(a, b) {
+    return a < b ? `${a}|${b}` : `${b}|${a}`;
+}
+function toISO(dateStr) {
+    try {
+        return new Date(dateStr).toISOString();
+    }
+    catch {
+        return new Date().toISOString();
+    }
+}
+function emptyResult() {
+    return {
+        analysedAt: new Date().toISOString(),
+        commitCount: 0,
+        fileCount: 0,
+        files: [],
+        coChanges: [],
+        oldestCommit: '',
+        newestCommit: '',
+    };
+}
+// ──────────────────────────────────────────────────────────────
+// MAIN FUNCTION
+// ──────────────────────────────────────────────────────────────
+/**
+ * Analyse a git repository and produce structured change data.
+ *
+ * **Never throws** — returns an empty result for non-git directories,
+ * empty repos, or any other error condition.
+ */
+export async function analyseRepository(repoPath, options) {
+    try {
+        // Check if .git exists
+        try {
+            await fs.access(path.join(repoPath, '.git'));
+        }
+        catch {
+            return emptyResult();
+        }
+        const git = simpleGit(repoPath);
+        const maxCommits = options?.maxCommits ?? DEFAULT_MAX_COMMITS;
+        const excludePaths = options?.excludePaths ?? DEFAULT_EXCLUDE_PATHS;
+        const maxCoChangePairs = options?.maxCoChangePairs ?? DEFAULT_MAX_CO_CHANGE_PAIRS;
+        // Build log options
+        const logOptions = {
+            maxCount: maxCommits,
+            '--name-only': null,
+        };
+        if (options?.since) {
+            logOptions['--after'] = options.since;
+        }
+        // Get commit log
+        let logResult;
+        try {
+            logResult = await git.log(logOptions);
+        }
+        catch {
+            // Empty repo or other git error
+            return emptyResult();
+        }
+        const commits = logResult.all;
+        if (commits.length === 0) {
+            return emptyResult();
+        }
+        // ────────────────────────────────────────────────────────────
+        // SCAN COMMITS
+        // ────────────────────────────────────────────────────────────
+        // Per-file tracking
+        const fileData = new Map();
+        // Co-change pair tracking
+        const coChangeMap = new Map();
+        let oldestDate = '';
+        let newestDate = '';
+        for (const commit of commits) {
+            const commitDate = toISO(commit.date);
+            const author = commit.author_name || 'unknown';
+            // Track oldest/newest
+            if (!oldestDate || commitDate < oldestDate)
+                oldestDate = commitDate;
+            if (!newestDate || commitDate > newestDate)
+                newestDate = commitDate;
+            // Get files from this commit
+            // simple-git log with --name-only puts files in diff.files or body
+            const rawFiles = extractFilesFromCommit(commit);
+            const filteredFiles = rawFiles
+                .map(normalisePath)
+                .filter(f => shouldIncludeFile(f, excludePaths));
+            // Update per-file data
+            for (const filepath of filteredFiles) {
+                const existing = fileData.get(filepath);
+                if (existing) {
+                    existing.changeCount++;
+                    if (commitDate > existing.lastChanged)
+                        existing.lastChanged = commitDate;
+                    if (commitDate < existing.firstSeen)
+                        existing.firstSeen = commitDate;
+                    existing.authors.add(author);
+                }
+                else {
+                    fileData.set(filepath, {
+                        changeCount: 1,
+                        lastChanged: commitDate,
+                        firstSeen: commitDate,
+                        authors: new Set([author]),
+                    });
+                }
+            }
+            // Co-change pairs (skip if too many files in this commit)
+            if (filteredFiles.length >= 2 && filteredFiles.length <= CO_CHANGE_FILES_PER_COMMIT_CAP) {
+                for (let i = 0; i < filteredFiles.length; i++) {
+                    for (let j = i + 1; j < filteredFiles.length; j++) {
+                        const key = makeCoChangeKey(filteredFiles[i], filteredFiles[j]);
+                        coChangeMap.set(key, (coChangeMap.get(key) ?? 0) + 1);
+                    }
+                }
+            }
+        }
+        // ────────────────────────────────────────────────────────────
+        // BUILD CO-CHANGE RECORDS
+        // ────────────────────────────────────────────────────────────
+        // Filter out pairs with count < 2, sort descending, take top N
+        const coChangePairs = [];
+        for (const [key, count] of coChangeMap) {
+            if (count >= 2) {
+                const [fileA, fileB] = key.split('|');
+                coChangePairs.push({ fileA, fileB, coChangeCount: count });
+            }
+        }
+        coChangePairs.sort((a, b) => b.coChangeCount - a.coChangeCount);
+        const topCoChanges = coChangePairs.slice(0, maxCoChangePairs);
+        // ────────────────────────────────────────────────────────────
+        // BUILD FILE RECORDS with coChangedWith
+        // ────────────────────────────────────────────────────────────
+        // Build per-file co-change index for top 5
+        const perFileCoChange = new Map();
+        for (const [key, count] of coChangeMap) {
+            if (count < 2)
+                continue;
+            const [a, b] = key.split('|');
+            if (!perFileCoChange.has(a))
+                perFileCoChange.set(a, new Map());
+            if (!perFileCoChange.has(b))
+                perFileCoChange.set(b, new Map());
+            perFileCoChange.get(a).set(b, count);
+            perFileCoChange.get(b).set(a, count);
+        }
+        const files = [];
+        for (const [filepath, data] of fileData) {
+            // Top 5 co-changed files
+            const coMap = perFileCoChange.get(filepath);
+            let coChangedWith = [];
+            if (coMap) {
+                coChangedWith = Array.from(coMap.entries())
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 5)
+                    .map(([f]) => f);
+            }
+            files.push({
+                filepath,
+                changeCount: data.changeCount,
+                lastChanged: data.lastChanged,
+                firstSeen: data.firstSeen,
+                authors: Array.from(data.authors),
+                coChangedWith,
+            });
+        }
+        // Sort files by changeCount descending
+        files.sort((a, b) => b.changeCount - a.changeCount);
+        return {
+            analysedAt: new Date().toISOString(),
+            commitCount: commits.length,
+            fileCount: files.length,
+            files,
+            coChanges: topCoChanges,
+            oldestCommit: oldestDate,
+            newestCommit: newestDate,
+        };
+    }
+    catch {
+        // Catch-all: never throw
+        return emptyResult();
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// EXTRACT FILES FROM COMMIT
+// ──────────────────────────────────────────────────────────────
+/**
+ * Extract file paths from a simple-git log entry.
+ * simple-git puts the file list in `diff.files` when --name-only is used,
+ * or sometimes in the `body` field as newline-separated paths.
+ */
+function extractFilesFromCommit(commit) {
+    const files = [];
+    // Try diff.files first (simple-git standard format)
+    if (commit.diff && commit.diff.files && commit.diff.files.length > 0) {
+        for (const f of commit.diff.files) {
+            if (f.file)
+                files.push(f.file);
+        }
+    }
+    // Fallback: parse body for file paths (--name-only output)
+    if (files.length === 0 && commit.body) {
+        const bodyLines = commit.body.split('\n');
+        for (const line of bodyLines) {
+            const trimmed = line.trim();
+            if (trimmed && !trimmed.startsWith('commit ') && !trimmed.startsWith('Author:') && !trimmed.startsWith('Date:')) {
+                files.push(trimmed);
+            }
+        }
+    }
+    return files.filter(f => f.length > 0);
+}

package/dist/analysis/stability-classifier.js

@@ -0,0 +1,122 @@
+// ──────────────────────────────────────────────────────────────
+// CONSTANTS
+// ──────────────────────────────────────────────────────────────
+const DEFAULT_FROZEN_THRESHOLD = 2; // max changes/month
+const DEFAULT_VOLATILE_THRESHOLD = 8; // min changes/month
+const DEFAULT_MIN_AGE_FOR_FROZEN = 30; // days
+// ──────────────────────────────────────────────────────────────
+// MAIN FUNCTION
+// ──────────────────────────────────────────────────────────────
+/**
+ * Classify stability for every file in a GitAnalysisResult.
+ *
+ * **Never throws** — returns an empty ClassificationResult on any error.
+ */
+export function classifyStability(analysis, options) {
+    try {
+        const frozenThreshold = options?.frozenThreshold ?? DEFAULT_FROZEN_THRESHOLD;
+        const volatileThreshold = options?.volatileThreshold ?? DEFAULT_VOLATILE_THRESHOLD;
+        const minAgeForFrozen = options?.minAgeForFrozen ?? DEFAULT_MIN_AGE_FOR_FROZEN;
+        const now = new Date(analysis.analysedAt || new Date().toISOString());
+        const classifications = [];
+        for (const file of analysis.files) {
+            const classification = classifyFile(file, now, frozenThreshold, volatileThreshold, minAgeForFrozen);
+            classifications.push(classification);
+        }
+        // Build summary
+        const summary = { frozen: 0, stable: 0, volatile: 0, disposable: 0 };
+        for (const c of classifications) {
+            summary[c.stability]++;
+        }
+        return {
+            classifiedAt: new Date().toISOString(),
+            fileCount: classifications.length,
+            classifications,
+            summary,
+        };
+    }
+    catch {
+        return {
+            classifiedAt: new Date().toISOString(),
+            fileCount: 0,
+            classifications: [],
+            summary: { frozen: 0, stable: 0, volatile: 0, disposable: 0 },
+        };
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// PER-FILE CLASSIFICATION
+// ──────────────────────────────────────────────────────────────
+function classifyFile(file, now, frozenThreshold, volatileThreshold, minAgeForFrozen) {
+    const { filepath, changeCount, coChangedWith } = file;
+    // Calculate age metrics
+    const firstSeenDate = new Date(file.firstSeen);
+    const lastChangedDate = new Date(file.lastChanged);
+    let ageInDays = Math.floor((now.getTime() - firstSeenDate.getTime()) / (1000 * 60 * 60 * 24));
+    if (ageInDays < 1)
+        ageInDays = 1; // guard against division by zero
+    const daysSinceLastChange = Math.floor((now.getTime() - lastChangedDate.getTime()) / (1000 * 60 * 60 * 24));
+    // Calculate churn rate
+    const changesPerMonth = (changeCount / ageInDays) * 30;
+    const changesPerMonthRounded = Math.round(changesPerMonth * 100) / 100;
+    // Co-change count
+    const coChangeCount = coChangedWith.length;
+    // ──────────────────────────────────────────────────────────
+    // CLASSIFICATION RULES (first match wins)
+    // ──────────────────────────────────────────────────────────
+    let stability;
+    let reason;
+    if (changesPerMonth <= frozenThreshold &&
+        ageInDays >= minAgeForFrozen &&
+        coChangeCount >= 3) {
+        // FROZEN
+        stability = 'frozen';
+        reason =
+            `Low churn (${changesPerMonthRounded} changes/month), ` +
+                `high connectivity (${coChangeCount} co-changed files), ` +
+                `aged ${ageInDays} days`;
+    }
+    else if (changesPerMonth >= volatileThreshold) {
+        // VOLATILE
+        stability = 'volatile';
+        reason = `High churn (${changesPerMonthRounded} changes/month)`;
+    }
+    else if (changesPerMonth <= frozenThreshold &&
+        coChangeCount <= 1 &&
+        ageInDays >= minAgeForFrozen) {
+        // DISPOSABLE
+        stability = 'disposable';
+        reason =
+            `Low churn (${changesPerMonthRounded} changes/month), ` +
+                `low connectivity, aged ${ageInDays} days`;
+    }
+    else {
+        // STABLE (catch-all)
+        stability = 'stable';
+        reason = `Moderate churn (${changesPerMonthRounded} changes/month)`;
+    }
+    // ──────────────────────────────────────────────────────────
+    // CONFIDENCE
+    // ──────────────────────────────────────────────────────────
+    let confidence;
+    if (ageInDays >= 90 && changeCount >= 5) {
+        confidence = 'high';
+    }
+    else if (ageInDays >= 30 && changeCount >= 2) {
+        confidence = 'medium';
+    }
+    else {
+        confidence = 'low';
+    }
+    return {
+        filepath,
+        stability,
+        confidence,
+        reason,
+        changeCount,
+        coChangeCount,
+        ageInDays,
+        daysSinceLastChange,
+        classificationSource: 'derived',
+    };
+}

package/dist/brain/cortex.js

@@ -0,0 +1,258 @@
+import * as path from 'path';
+import { readJsonOrNull } from '../storage/reader.js';
+import { writeAtomic } from '../storage/writer.js';
+import { analyseRepository } from '../analysis/git-analyser.js';
+import { classifyStability } from '../analysis/stability-classifier.js';
+// ──────────────────────────────────────────────────────────────
+// PATHS
+// ──────────────────────────────────────────────────────────────
+function stabilityPath(mathaDir) {
+    return path.join(mathaDir, 'cortex', 'stability.json');
+}
+function coChangesPath(mathaDir) {
+    return path.join(mathaDir, 'cortex', 'co-changes.json');
+}
+// ──────────────────────────────────────────────────────────────
+// HELPERS
+// ──────────────────────────────────────────────────────────────
+function normalisePath(filepath) {
+    return filepath.replace(/\\/g, '/');
+}
+function buildSummary(records) {
+    const summary = { frozen: 0, stable: 0, volatile: 0, disposable: 0, declared: 0 };
+    for (const r of records) {
+        if (r.stability === 'frozen')
+            summary.frozen++;
+        else if (r.stability === 'stable')
+            summary.stable++;
+        else if (r.stability === 'volatile')
+            summary.volatile++;
+        else if (r.stability === 'disposable')
+            summary.disposable++;
+        if (r.classificationSource === 'declared')
+            summary.declared++;
+    }
+    return summary;
+}
+// ──────────────────────────────────────────────────────────────
+// refreshFromGit
+// ──────────────────────────────────────────────────────────────
+/**
+ * Run git analysis + stability classification and persist results.
+ * Preserves any existing `declared` records (declared-wins invariant).
+ *
+ * **Never throws** — empty repo produces empty cortex.
+ */
+export async function refreshFromGit(repoPath, mathaDir, options) {
+    try {
+        const now = new Date().toISOString();
+        // Run analysis pipeline
+        const analysis = await analyseRepository(repoPath, options);
+        const classification = classifyStability(analysis);
+        // Load existing stability records (to preserve declared)
+        const existing = await readJsonOrNull(stabilityPath(mathaDir));
+        const declaredMap = new Map();
+        if (existing && Array.isArray(existing)) {
+            for (const r of existing) {
+                if (r.classificationSource === 'declared') {
+                    declaredMap.set(normalisePath(r.filepath), r);
+                }
+            }
+        }
+        // Build new stability records
+        const records = [];
+        for (const c of classification.classifications) {
+            const fp = normalisePath(c.filepath);
+            const declared = declaredMap.get(fp);
+            if (declared) {
+                // Preserve declared, only update lastDerivedAt
+                records.push({
+                    ...declared,
+                    filepath: fp,
+                    lastDerivedAt: now,
+                });
+                declaredMap.delete(fp); // mark as handled
+            }
+            else {
+                records.push({
+                    filepath: fp,
+                    stability: c.stability,
+                    confidence: c.confidence,
+                    reason: c.reason,
+                    classificationSource: 'derived',
+                    changeCount: c.changeCount,
+                    coChangeCount: c.coChangeCount,
+                    ageInDays: c.ageInDays,
+                    daysSinceLastChange: c.daysSinceLastChange,
+                    lastDerivedAt: now,
+                });
+            }
+        }
+        // Keep any declared records for files not in current git analysis
+        for (const declared of declaredMap.values()) {
+            records.push({
+                ...declared,
+                filepath: normalisePath(declared.filepath),
+                lastDerivedAt: now,
+            });
+        }
+        // Write stability.json
+        await writeAtomic(stabilityPath(mathaDir), records, { overwrite: true });
+        // Write co-changes.json
+        await writeAtomic(coChangesPath(mathaDir), analysis.coChanges, { overwrite: true });
+        const snapshot = {
+            updatedAt: now,
+            repoPath,
+            commitCount: analysis.commitCount,
+            fileCount: records.length,
+            stability: records,
+            coChanges: analysis.coChanges,
+            summary: buildSummary(records),
+        };
+        return snapshot;
+    }
+    catch {
+        const empty = {
+            updatedAt: new Date().toISOString(),
+            repoPath,
+            commitCount: 0,
+            fileCount: 0,
+            stability: [],
+            coChanges: [],
+            summary: { frozen: 0, stable: 0, volatile: 0, disposable: 0, declared: 0 },
+        };
+        return empty;
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// getStability
+// ──────────────────────────────────────────────────────────────
+/**
+ * Look up stability records for specific files.
+ * Returns null for any filepath not found in stability.json.
+ *
+ * **Never throws.**
+ */
+export async function getStability(mathaDir, filepaths) {
+    try {
+        const records = await readJsonOrNull(stabilityPath(mathaDir));
+        const result = {};
+        const recordMap = new Map();
+        if (records && Array.isArray(records)) {
+            for (const r of records) {
+                recordMap.set(normalisePath(r.filepath), r);
+            }
+        }
+        for (const fp of filepaths) {
+            const normalised = normalisePath(fp);
+            result[normalised] = recordMap.get(normalised) ?? null;
+        }
+        return result;
+    }
+    catch {
+        const result = {};
+        for (const fp of filepaths) {
+            result[normalisePath(fp)] = null;
+        }
+        return result;
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// overrideStability
+// ──────────────────────────────────────────────────────────────
+/**
+ * Set a human override for a file's stability classification.
+ * Creates the record if the file is not already in stability.json.
+ *
+ * **Never throws.**
+ */
+export async function overrideStability(mathaDir, filepath, stability, reason, declaredBy) {
+    try {
+        const fp = normalisePath(filepath);
+        const now = new Date().toISOString();
+        let records = await readJsonOrNull(stabilityPath(mathaDir));
+        if (!records || !Array.isArray(records)) {
+            records = [];
+        }
+        const idx = records.findIndex(r => normalisePath(r.filepath) === fp);
+        const declaredRecord = {
+            filepath: fp,
+            stability,
+            confidence: idx >= 0 ? records[idx].confidence : 'low',
+            reason,
+            classificationSource: 'declared',
+            declaredBy,
+            declaredAt: now,
+            changeCount: idx >= 0 ? records[idx].changeCount : 0,
+            coChangeCount: idx >= 0 ? records[idx].coChangeCount : 0,
+            ageInDays: idx >= 0 ? records[idx].ageInDays : 0,
+            daysSinceLastChange: idx >= 0 ? records[idx].daysSinceLastChange : 0,
+            lastDerivedAt: idx >= 0 ? records[idx].lastDerivedAt : undefined,
+        };
+        if (idx >= 0) {
+            records[idx] = declaredRecord;
+        }
+        else {
+            records.push(declaredRecord);
+        }
+        await writeAtomic(stabilityPath(mathaDir), records, { overwrite: true });
+    }
+    catch {
+        // Never throw
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// getCoChanges
+// ──────────────────────────────────────────────────────────────
+/**
+ * Read co-change pairs, optionally filtered to a specific file.
+ *
+ * **Never throws** — returns empty array if file missing.
+ */
+export async function getCoChanges(mathaDir, filepath) {
+    try {
+        const pairs = await readJsonOrNull(coChangesPath(mathaDir));
+        if (!pairs || !Array.isArray(pairs))
+            return [];
+        if (!filepath)
+            return pairs;
+        const fp = normalisePath(filepath);
+        return pairs.filter(p => normalisePath(p.fileA) === fp || normalisePath(p.fileB) === fp);
+    }
+    catch {
+        return [];
+    }
+}
+// ──────────────────────────────────────────────────────────────
+// getSnapshot
+// ──────────────────────────────────────────────────────────────
+/**
+ * Read persisted cortex data and assemble a CortexSnapshot.
+ * Returns null if stability.json does not exist.
+ *
+ * **Never throws.**
+ */
+export async function getSnapshot(mathaDir) {
+    try {
+        const records = await readJsonOrNull(stabilityPath(mathaDir));
+        if (!records || !Array.isArray(records))
+            return null;
+        const pairs = await readJsonOrNull(coChangesPath(mathaDir));
+        const coChanges = pairs && Array.isArray(pairs) ? pairs : [];
+        // Try to read shape.json for metadata
+        const shapePath = path.join(mathaDir, 'cortex', 'shape.json');
+        const shape = await readJsonOrNull(shapePath);
+        return {
+            updatedAt: new Date().toISOString(),
+            repoPath: shape?.project_root ?? '',
+            commitCount: 0, // Not stored in stability.json — would need separate metadata
+            fileCount: records.length,
+            stability: records,
+            coChanges,
+            summary: buildSummary(records),
+        };
+    }
+    catch {
+        return null;
+    }
+}