cotx-engine 0.1.0

package/dist/store/store.js

@@ -0,0 +1,254 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+const COTX_VERSION = '0.1';
+export class CotxStore {
+    root;
+    cotxDir;
+    constructor(projectRoot) {
+        this.root = projectRoot;
+        this.cotxDir = path.join(projectRoot, '.cotx');
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────────────
+    init(projectName) {
+        const dirs = [
+            this.cotxDir,
+            path.join(this.cotxDir, 'modules'),
+            path.join(this.cotxDir, 'concepts'),
+            path.join(this.cotxDir, 'contracts'),
+            path.join(this.cotxDir, 'flows'),
+            path.join(this.cotxDir, 'concerns'),
+            path.join(this.cotxDir, 'graph'),
+        ];
+        for (const dir of dirs) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        const meta = {
+            version: COTX_VERSION,
+            project: projectName,
+            compiled_at: new Date().toISOString(),
+            module_resolution: 'medium',
+            stats: { concepts: 0, modules: 0, contracts: 0, flows: 0, concerns: 0 },
+        };
+        this.writeMeta(meta);
+    }
+    exists() {
+        return fs.existsSync(this.cotxDir);
+    }
+    // ── Meta ───────────────────────────────────────────────────────────────────
+    readMeta() {
+        const file = path.join(this.cotxDir, 'meta.yaml');
+        const raw = fs.readFileSync(file, 'utf-8');
+        return yaml.load(raw);
+    }
+    writeMeta(meta) {
+        const file = path.join(this.cotxDir, 'meta.yaml');
+        fs.writeFileSync(file, yaml.dump(meta, { lineWidth: -1 }), 'utf-8');
+    }
+    updateMeta(updates) {
+        const existing = this.readMeta();
+        const merged = { ...existing, ...updates };
+        // Deep-merge stats if both sides have it
+        if (updates.stats && existing.stats) {
+            merged.stats = { ...existing.stats, ...updates.stats };
+        }
+        this.writeMeta(merged);
+    }
+    // ── Modules ────────────────────────────────────────────────────────────────
+    /** Convert a node ID to a safe filename stem using URL encoding. */
+    idToFilename(id) {
+        return encodeURIComponent(id);
+    }
+    /** Convert a safe filename stem back to a node ID. */
+    filenameToId(filename) {
+        return decodeURIComponent(filename);
+    }
+    /** Public access to filename encoding for index generation. */
+    safeFilename(id) {
+        return this.idToFilename(id);
+    }
+    decodeStoredId(filename) {
+        return this.filenameToId(filename.replace(/\.yaml$/, ''));
+    }
+    nodeFilePath(layer, id) {
+        return path.join(this.cotxDir, layer, `${this.idToFilename(id)}.yaml`);
+    }
+    writeModule(mod) {
+        const file = this.nodeFilePath('modules', mod.id);
+        const existing = this.safeReadYaml(file);
+        // Preserve annotations and enriched data from existing file
+        const annotations = mod.annotations ?? existing?.annotations;
+        const enriched = mod.enriched ?? existing?.enriched;
+        const toWrite = { ...mod, annotations, enriched };
+        if (!toWrite.annotations)
+            delete toWrite.annotations;
+        if (!toWrite.enriched)
+            delete toWrite.enriched;
+        fs.writeFileSync(file, yaml.dump(toWrite, { lineWidth: -1 }), 'utf-8');
+    }
+    readModule(id) {
+        const file = this.nodeFilePath('modules', id);
+        const raw = fs.readFileSync(file, 'utf-8');
+        return yaml.load(raw);
+    }
+    listModules() {
+        const dir = path.join(this.cotxDir, 'modules');
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.yaml'))
+            .map((f) => this.decodeStoredId(f));
+    }
+    // ── Concepts ───────────────────────────────────────────────────────────────
+    writeConcept(concept) {
+        const file = this.nodeFilePath('concepts', concept.id);
+        const existing = this.safeReadYaml(file);
+        const annotations = concept.annotations ?? existing?.annotations;
+        const enriched = concept.enriched ?? existing?.enriched;
+        const toWrite = { ...concept, annotations, enriched };
+        if (!toWrite.annotations)
+            delete toWrite.annotations;
+        if (!toWrite.enriched)
+            delete toWrite.enriched;
+        fs.writeFileSync(file, yaml.dump(toWrite, { lineWidth: -1 }), 'utf-8');
+    }
+    readConcept(id) {
+        const file = this.nodeFilePath('concepts', id);
+        const raw = fs.readFileSync(file, 'utf-8');
+        return yaml.load(raw);
+    }
+    listConcepts() {
+        const dir = path.join(this.cotxDir, 'concepts');
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.yaml'))
+            .map((f) => this.decodeStoredId(f));
+    }
+    // ── Contracts ──────────────────────────────────────────────────────────────
+    writeContract(contract) {
+        const file = this.nodeFilePath('contracts', contract.id);
+        const existing = this.safeReadYaml(file);
+        const annotations = contract.annotations ?? existing?.annotations;
+        const enriched = contract.enriched ?? existing?.enriched;
+        const toWrite = { ...contract, annotations, enriched };
+        if (!toWrite.annotations)
+            delete toWrite.annotations;
+        if (!toWrite.enriched)
+            delete toWrite.enriched;
+        fs.writeFileSync(file, yaml.dump(toWrite, { lineWidth: -1 }), 'utf-8');
+    }
+    readContract(id) {
+        const file = this.nodeFilePath('contracts', id);
+        const raw = fs.readFileSync(file, 'utf-8');
+        return yaml.load(raw);
+    }
+    listContracts() {
+        const dir = path.join(this.cotxDir, 'contracts');
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.yaml'))
+            .map((f) => this.decodeStoredId(f));
+    }
+    // ── Flows ──────────────────────────────────────────────────────────────────
+    writeFlow(flow) {
+        const file = this.nodeFilePath('flows', flow.id);
+        const existing = this.safeReadYaml(file);
+        const annotations = flow.annotations ?? existing?.annotations;
+        const enriched = flow.enriched ?? existing?.enriched;
+        const toWrite = { ...flow, annotations, enriched };
+        if (!toWrite.annotations)
+            delete toWrite.annotations;
+        if (!toWrite.enriched)
+            delete toWrite.enriched;
+        fs.writeFileSync(file, yaml.dump(toWrite, { lineWidth: -1 }), 'utf-8');
+    }
+    readFlow(id) {
+        const file = this.nodeFilePath('flows', id);
+        const raw = fs.readFileSync(file, 'utf-8');
+        return yaml.load(raw);
+    }
+    listFlows() {
+        const dir = path.join(this.cotxDir, 'flows');
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.yaml'))
+            .map((f) => this.decodeStoredId(f));
+    }
+    // ── Concerns ───────────────────────────────────────────────────────────────
+    writeConcern(concern) {
+        const file = this.nodeFilePath('concerns', concern.id);
+        fs.writeFileSync(file, yaml.dump(concern, { lineWidth: -1 }), 'utf-8');
+    }
+    readConcern(id) {
+        const file = this.nodeFilePath('concerns', id);
+        const raw = fs.readFileSync(file, 'utf-8');
+        return yaml.load(raw);
+    }
+    listConcerns() {
+        const dir = path.join(this.cotxDir, 'concerns');
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir)
+            .filter((f) => f.endsWith('.yaml'))
+            .map((f) => this.decodeStoredId(f));
+    }
+    // ── Garbage collection ────────────────────────────────────────────────────
+    /**
+     * Delete YAML files in a layer directory that are not in the valid ID set.
+     * Called after each compile phase to remove nodes that no longer exist.
+     */
+    pruneStale(layer, validIds) {
+        const dir = path.join(this.cotxDir, layer);
+        if (!fs.existsSync(dir))
+            return;
+        const validFilenames = new Set([...validIds].map((id) => `${this.idToFilename(id)}.yaml`));
+        for (const filename of fs.readdirSync(dir)) {
+            if (filename.endsWith('.yaml') && !validFilenames.has(filename)) {
+                fs.unlinkSync(path.join(dir, filename));
+            }
+        }
+    }
+    // ── Graph files ────────────────────────────────────────────────────────────
+    writeGraphFile(filename, lines) {
+        const file = path.join(this.cotxDir, 'graph', filename);
+        fs.writeFileSync(file, lines.join('\n') + '\n', 'utf-8');
+    }
+    // ── Index ──────────────────────────────────────────────────────────────────
+    writeIndex(index) {
+        const file = path.join(this.cotxDir, 'index.json');
+        fs.writeFileSync(file, JSON.stringify(index, null, 2), 'utf-8');
+    }
+    readIndex() {
+        const file = path.join(this.cotxDir, 'index.json');
+        const raw = fs.readFileSync(file, 'utf-8');
+        return JSON.parse(raw);
+    }
+    // ── Operation Log ──────────────────────────────────────────────────────────
+    appendLog(entry) {
+        const logPath = path.join(this.cotxDir, 'log.jsonl');
+        const record = {
+            timestamp: new Date().toISOString(),
+            ...entry,
+        };
+        fs.appendFileSync(logPath, JSON.stringify(record) + '\n');
+    }
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    safeReadYaml(filePath) {
+        try {
+            const raw = fs.readFileSync(filePath, 'utf-8');
+            return yaml.load(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/store/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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"}

package/dist/types/pipeline.d.ts

@@ -0,0 +1,12 @@
+import type { KnowledgeGraph } from '../core/graph/types.js';
+import { CommunityDetectionResult } from '../core/parser/community-processor.js';
+import { ProcessDetectionResult } from '../core/parser/process-processor.js';
+export interface PipelineResult {
+    graph: KnowledgeGraph;
+    /** Absolute path to the repo root — used for lazy file reads during LadybugDB loading */
+    repoPath: string;
+    /** Total files scanned (for stats) */
+    totalFileCount: number;
+    communityResult?: CommunityDetectionResult;
+    processResult?: ProcessDetectionResult;
+}

package/dist/types/pipeline.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeline.js.map

package/dist/types/pipeline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/types/pipeline.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "cotx-engine",
+  "version": "0.1.0",
+  "license": "BUSL-1.1",
+  "description": "Cognitive context engine — compiles codebases into persistent, queryable semantic maps",
+  "type": "module",
+  "files": [
+    "dist",
+    "vendor/leiden",
+    "skills/cotx-enrich/SKILL.md",
+    "README.md"
+  ],
+  "bin": {
+    "cotx": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc && tsc-alias",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "verify": "npm run build && npm run lint && npm test && npm run test:acceptance && npm run pack:check"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "change-case": "^5.4.4",
+    "commander": "^12.0.0",
+    "glob": "^11.0.0",
+    "graphology": "^0.25.4",
+    "graphology-communities-louvain": "^2.0.2",
+    "graphology-indices": "^0.17.0",
+    "graphology-utils": "^2.3.0",
+    "ignore": "^7.0.5",
+    "js-yaml": "^4.1.1",
+    "lru-cache": "^11.0.0",
+    "mnemonist": "^0.39.0",
+    "pandemonium": "^2.4.0",
+    "seedrandom": "^3.0.5",
+    "stopword": "^3.1.5",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-c": "0.23.2",
+    "tree-sitter-c-sharp": "^0.23.1",
+    "tree-sitter-cpp": "^0.23.4",
+    "tree-sitter-go": "^0.23.0",
+    "tree-sitter-java": "^0.23.5",
+    "tree-sitter-javascript": "^0.23.0",
+    "tree-sitter-php": "^0.23.0",
+    "tree-sitter-python": "0.23.4",
+    "tree-sitter-ruby": "^0.23.1",
+    "tree-sitter-rust": "0.23.1",
+    "tree-sitter-typescript": "^0.23.2",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "@types/seedrandom": "^3.0.8",
+    "@types/uuid": "^10.0.0",
+    "graphology-types": "^0.24.7",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/cotx-enrich/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: cotx-enrich
+description: Enrich stale nodes in the cognitive map with semantic descriptions. Run after cotx compile or cotx update when stale enrichments are reported.
+---
+
+## When to Use
+
+After `cotx compile` or `cotx update` reports stale enrichments, or when `cotx lint` shows STALE_ENRICHMENT warnings.
+
+## Workflow
+
+### Step 1: Find stale nodes
+
+Run: `cotx lint --json`
+
+This returns a JSON array of issues. Filter for `type: "STALE_ENRICHMENT"` entries.
+
+### Step 2: For each stale node
+
+1. **Read the node**: `cotx context <node_id>`
+   - Note the `layer` and `struct_hash`
+   - Note what fields are stale (enriched.source_hash ≠ struct_hash)
+
+2. **Read the source code**: Use Glob and Read tools to examine the files referenced by the node
+   - For modules: read the files listed in the module
+   - For concepts: read files in `appears_in`
+   - For contracts: read the interface functions in provider module
+   - For flows: read the functions in each step
+
+3. **Understand the change**: Compare what the old enrichment says vs what the code actually does now
+
+4. **Write updated enrichment**:
+   ```bash
+   cotx write <node_id> enriched.responsibility "new description based on code"
+   cotx write <node_id> enriched.key_patterns "observed patterns"
+   ```
+
+### Step 3: Verify
+
+Run: `cotx lint --json`
+Confirm the stale enrichment warnings are resolved (source_hash now matches struct_hash).
+
+## Field Guide
+
+| Layer | Enrichable Fields | What to Write |
+|-------|------------------|---------------|
+| Module | `enriched.responsibility` | One-sentence module purpose |
+| Module | `enriched.key_patterns` | Key design patterns used |
+| Concept | `enriched.definition` | Natural language definition |
+| Contract | `enriched.guarantees` | What the interface promises |
+| Contract | `enriched.invariants` | Rules that must hold |
+| Flow | `enriched.error_paths` | What happens when steps fail |
+
+## Important
+
+- Only enrich nodes you understand. Skip nodes where the code is unclear.
+- Do NOT modify deterministic fields (files, struct_hash, etc.) — only enriched.* fields.
+- Enrichment is optional — stale enrichments don't block any operation.
+- Focus on the most important nodes first (modules and contracts over individual concepts).