@rasensio/aidlc 0.7.0 → 1.1.0

package/dist/knowledge/yaml-source.js

@@ -0,0 +1,195 @@
+/**
+ * YAML source layer — the knowledge graph's source of truth.
+ *
+ * One multi-document file per entity type plus `relationships.yaml`, each with
+ * a `_meta` header document. Writes are append-only by default (KG Req 2.5,
+ * 12.5): new entities go to the end of the file; only explicit updates rewrite
+ * an existing document. Only the affected file is ever touched (KG Req 2.3).
+ *
+ * Requirements: KG 2.1–2.5, 11.1, 12.5
+ *
+ * @module
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseAllDocuments, stringify } from 'yaml';
+import { KNOWLEDGE_SCHEMA_VERSION, RELATIONSHIPS_FILE, sourceFileForType, } from './types.js';
+export class YamlSourceStore {
+    knowledgeDir;
+    constructor(knowledgeDir) {
+        this.knowledgeDir = knowledgeDir;
+    }
+    /** Absolute path of the knowledge directory. */
+    get dir() {
+        return this.knowledgeDir;
+    }
+    /** True once any source file exists. */
+    exists() {
+        if (!existsSync(this.knowledgeDir))
+            return false;
+        return this.listSourceFiles().length > 0;
+    }
+    // -------------------------------------------------------------------------
+    // Writes
+    // -------------------------------------------------------------------------
+    /** Append a new entity document to its type file (KG Req 2.5). */
+    appendEntity(entity) {
+        const filePath = this.ensureFile(sourceFileForType(entity.type), entity.type);
+        const doc = stringify(entity, { lineWidth: 100 });
+        const content = readFileSync(filePath, 'utf8');
+        const sep = content.endsWith('\n') ? '---\n' : '\n---\n';
+        writeFileSync(filePath, content + sep + doc, 'utf8');
+    }
+    /** Rewrite an existing entity document in place (explicit update path). */
+    updateEntity(entity) {
+        const filePath = join(this.knowledgeDir, sourceFileForType(entity.type));
+        if (!existsSync(filePath)) {
+            throw new Error(`Source file not found for entity '${entity.id}'`);
+        }
+        const raw = readFileSync(filePath, 'utf8');
+        const docs = parseAllDocuments(raw);
+        let found = false;
+        const parts = [];
+        for (const doc of docs) {
+            const obj = doc.toJSON();
+            if (obj && obj.id === entity.id && !found) {
+                parts.push(stringify(entity, { lineWidth: 100 }));
+                found = true;
+            }
+            else if (obj !== null) {
+                parts.push(doc.toString());
+            }
+        }
+        if (!found) {
+            throw new Error(`Entity '${entity.id}' not found in ${sourceFileForType(entity.type)}`);
+        }
+        writeFileSync(filePath, parts.join('---\n'), 'utf8');
+    }
+    /** Append a relationship document to relationships.yaml (KG Req 2.5). */
+    appendRelationship(rel) {
+        const filePath = this.ensureFile(RELATIONSHIPS_FILE, 'relationship');
+        const doc = stringify(rel, { lineWidth: 100 });
+        const content = readFileSync(filePath, 'utf8');
+        const sep = content.endsWith('\n') ? '---\n' : '\n---\n';
+        writeFileSync(filePath, content + sep + doc, 'utf8');
+    }
+    /**
+     * Rewrite a whole source file from scratch (used only by `compact`,
+     * the sanctioned exception to append-only — KG Req 12.6).
+     */
+    rewriteFile(filename, entityType, docs) {
+        const filePath = join(this.knowledgeDir, filename);
+        const meta = this.metaHeader(entityType);
+        const body = docs.map((d) => stringify(d, { lineWidth: 100 })).join('---\n');
+        writeFileSync(filePath, meta + (body ? '---\n' + body : ''), 'utf8');
+    }
+    /** Update the `_meta.lastIndexed` timestamp of every source file. */
+    touchLastIndexed(timestamp) {
+        for (const file of this.listSourceFiles()) {
+            const filePath = join(this.knowledgeDir, file);
+            try {
+                const raw = readFileSync(filePath, 'utf8');
+                const docs = parseAllDocuments(raw);
+                const parts = [];
+                for (const doc of docs) {
+                    const obj = doc.toJSON();
+                    if (obj && typeof obj === 'object' && '_meta' in obj) {
+                        const meta = obj._meta;
+                        parts.push(stringify({ _meta: { ...meta, lastIndexed: timestamp } }));
+                    }
+                    else if (obj !== null) {
+                        parts.push(doc.toString());
+                    }
+                }
+                writeFileSync(filePath, parts.join('---\n'), 'utf8');
+            }
+            catch {
+                // Unreadable file — reported at load time, skip here.
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Reads
+    // -------------------------------------------------------------------------
+    /** Parse every source file into entities and relationships (KG Req 3.2). */
+    loadAll() {
+        const entities = [];
+        const relationships = [];
+        const warnings = [];
+        for (const file of this.listSourceFiles()) {
+            const filePath = join(this.knowledgeDir, file);
+            let raw;
+            try {
+                raw = readFileSync(filePath, 'utf8');
+            }
+            catch (err) {
+                warnings.push(`${file}: unreadable (${err.message})`);
+                continue;
+            }
+            let docs;
+            try {
+                docs = parseAllDocuments(raw);
+            }
+            catch (err) {
+                warnings.push(`${file}: YAML parse error (${err.message})`);
+                continue;
+            }
+            for (const doc of docs) {
+                if (doc.errors.length > 0) {
+                    warnings.push(`${file}: skipped corrupt document (${doc.errors[0].message})`);
+                    continue;
+                }
+                const obj = doc.toJSON();
+                if (!obj || typeof obj !== 'object')
+                    continue;
+                if ('_meta' in obj) {
+                    const meta = obj._meta;
+                    if (meta.schemaVersion > KNOWLEDGE_SCHEMA_VERSION) {
+                        warnings.push(`${file}: schema version ${meta.schemaVersion} is newer than supported ${KNOWLEDGE_SCHEMA_VERSION}`);
+                    }
+                    continue;
+                }
+                if (typeof obj.from === 'string' && typeof obj.to === 'string' && typeof obj.type === 'string') {
+                    relationships.push(obj);
+                }
+                else if (typeof obj.id === 'string' && typeof obj.type === 'string') {
+                    entities.push(obj);
+                }
+            }
+        }
+        return { entities, relationships, warnings };
+    }
+    /** List YAML source files (basenames), excluding the index db. */
+    listSourceFiles() {
+        if (!existsSync(this.knowledgeDir))
+            return [];
+        try {
+            return readdirSync(this.knowledgeDir)
+                .filter((f) => f.endsWith('.yaml') || f.endsWith('.yml'))
+                .sort();
+        }
+        catch {
+            return [];
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    ensureFile(filename, entityType) {
+        mkdirSync(this.knowledgeDir, { recursive: true });
+        const filePath = join(this.knowledgeDir, filename);
+        if (!existsSync(filePath)) {
+            writeFileSync(filePath, this.metaHeader(entityType), 'utf8');
+        }
+        return filePath;
+    }
+    metaHeader(entityType) {
+        const meta = {
+            schemaVersion: KNOWLEDGE_SCHEMA_VERSION,
+            lastIndexed: new Date().toISOString(),
+            entityType,
+        };
+        return stringify({ _meta: meta });
+    }
+}
+//# sourceMappingURL=yaml-source.js.map

package/dist/knowledge/yaml-source.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc",
-  "version": "0.7.0",
+  "version": "1.1.0",
   "description": "AI Development Lifecycle Framework — structured lifecycle guidance for AI coding agents across platforms",
   "type": "module",
   "main": "dist/cli.js",
@@ -8,7 +8,7 @@
     "aidlc": "dist/cli.js"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.13.0"
   },
   "keywords": [
     "ai",
@@ -24,7 +24,7 @@
     "commander": "15.0.0",
     "picomatch": "4.0.5",
     "yaml": "2.9.0",
-    "@rasensio/aidlc-content": "0.7.0"
+    "@rasensio/aidlc-content": "1.1.0"
   },
   "devDependencies": {
     "@types/node": "22.15.32",