@grafema/util 0.3.0-beta

package/dist/knowledge/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Knowledge Base — persistent knowledge layer for Grafema
+ */
+export { KnowledgeBase } from './KnowledgeBase.js';
+export { SemanticAddressResolver, parseSemanticAddress } from './SemanticAddressResolver.js';
+export type { ResolverBackend } from './SemanticAddressResolver.js';
+export { parseFrontmatter, parseKBNode, serializeKBNode, parseEdgesFile, appendEdge } from './parser.js';
+export type { KBNodeType, KBLifecycle, KBScope, KBNodeBase, KBDecision, KBFact, KBSession, KBNode, KBEdge, KBStats, KBQueryFilter, ParsedSemanticAddress, ResolvedAddress, DanglingCodeRef, } from './types.js';
+export { parseYamlArrayFile } from './parser.js';
+export { GitIngest, parseGitLog, normalizeAuthors } from './git-ingest.js';
+export type { RawCommit, FileChange, AuthorEntry, CommitEntry, IngestResult, Meta } from './git-ingest.js';
+export { getChurn, getCoChanges, getOwnership, getArchaeology } from './git-queries.js';
+export type { ChurnEntry, CoChangeEntry, OwnershipEntry, ArchaeologyEntry } from './git-queries.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAC7F,YAAY,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzG,YAAY,EACV,UAAU,EACV,WAAW,EACX,OAAO,EACP,UAAU,EACV,UAAU,EACV,MAAM,EACN,SAAS,EACT,MAAM,EACN,MAAM,EACN,OAAO,EACP,aAAa,EACb,qBAAqB,EACrB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC3G,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACxF,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/knowledge/index.js

@@ -0,0 +1,10 @@
+/**
+ * Knowledge Base — persistent knowledge layer for Grafema
+ */
+export { KnowledgeBase } from './KnowledgeBase.js';
+export { SemanticAddressResolver, parseSemanticAddress } from './SemanticAddressResolver.js';
+export { parseFrontmatter, parseKBNode, serializeKBNode, parseEdgesFile, appendEdge } from './parser.js';
+export { parseYamlArrayFile } from './parser.js';
+export { GitIngest, parseGitLog, normalizeAuthors } from './git-ingest.js';
+export { getChurn, getCoChanges, getOwnership, getArchaeology } from './git-queries.js';
+//# sourceMappingURL=index.js.map

package/dist/knowledge/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/knowledge/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAE7F,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAiBzG,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAE3E,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/knowledge/parser.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Knowledge Base Parser
+ *
+ * Parses markdown files with YAML frontmatter into KBNode objects.
+ * Serializes KBNode objects back to markdown format.
+ */
+import type { KBNode, KBEdge } from './types.js';
+/**
+ * Split markdown content into YAML frontmatter and body.
+ */
+export declare function parseFrontmatter(content: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/**
+ * Validate and construct a typed KBNode from parsed frontmatter and body.
+ */
+export declare function parseKBNode(frontmatter: Record<string, unknown>, body: string, filePath: string): KBNode;
+/**
+ * Serialize a KBNode back to markdown with YAML frontmatter.
+ */
+export declare function serializeKBNode(node: KBNode): string;
+/**
+ * Parse edges.yaml file into KBEdge array.
+ */
+export declare function parseEdgesFile(filePath: string): KBEdge[];
+/**
+ * Parse a YAML file containing an array of node objects (e.g., commits/2026-03.yaml, authors.yaml).
+ * Each entry must have at least a `type` field. ID is generated based on type:
+ * - COMMIT → kb:commit:<short-hash>
+ * - AUTHOR → kb:author:<slug>
+ * - Others → kb:<type>:<index>
+ */
+export declare function parseYamlArrayFile(filePath: string): KBNode[];
+/**
+ * Append an edge to the edges.yaml file.
+ */
+export declare function appendEdge(filePath: string, edge: KBEdge): void;
+//# sourceMappingURL=parser.d.ts.map

package/dist/knowledge/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/knowledge/parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,EAAuD,MAAM,YAAY,CAAC;AAKlH;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwBxG;AAYD;;GAEG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8DxG;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA4CpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BzD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAwD7D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAuB/D"}

package/dist/knowledge/parser.js

@@ -0,0 +1,292 @@
+/**
+ * Knowledge Base Parser
+ *
+ * Parses markdown files with YAML frontmatter into KBNode objects.
+ * Serializes KBNode objects back to markdown format.
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { readFileSync, appendFileSync, mkdirSync, existsSync } from 'fs';
+import { dirname } from 'path';
+const VALID_TYPES = ['DECISION', 'FACT', 'SESSION', 'COMMIT', 'FILE_CHANGE', 'AUTHOR', 'TICKET', 'INCIDENT'];
+const ID_PATTERN = /^kb:[a-z_]+:[a-z0-9_-]+$/;
+/**
+ * Split markdown content into YAML frontmatter and body.
+ */
+export function parseFrontmatter(content) {
+    const trimmed = content.trimStart();
+    if (!trimmed.startsWith('---\n') && !trimmed.startsWith('---\r\n')) {
+        throw new Error('Missing frontmatter: file must start with ---');
+    }
+    // Find closing --- delimiter
+    const firstNewline = trimmed.indexOf('\n');
+    const rest = trimmed.slice(firstNewline + 1);
+    const closingIndex = rest.indexOf('\n---');
+    if (closingIndex === -1) {
+        throw new Error('Missing frontmatter: no closing --- delimiter found');
+    }
+    const yamlContent = rest.slice(0, closingIndex);
+    const body = rest.slice(closingIndex + 4).replace(/^\r?\n/, ''); // skip \n--- and leading newline
+    const frontmatter = parseYaml(yamlContent);
+    if (!frontmatter || typeof frontmatter !== 'object') {
+        throw new Error('Invalid frontmatter: YAML must be an object');
+    }
+    return { frontmatter, body };
+}
+/**
+ * Derive lifecycle from file path.
+ * declared/ → declared, derived/ → derived, synced/ → synced
+ */
+function deriveLifecycle(filePath) {
+    if (filePath.includes('/derived/') || filePath.includes('\\derived\\'))
+        return 'derived';
+    if (filePath.includes('/synced/') || filePath.includes('\\synced\\'))
+        return 'synced';
+    return 'declared'; // default
+}
+/**
+ * Validate and construct a typed KBNode from parsed frontmatter and body.
+ */
+export function parseKBNode(frontmatter, body, filePath) {
+    // Required: id
+    const id = frontmatter.id;
+    if (typeof id !== 'string' || !id) {
+        throw new Error(`Missing required field "id" in ${filePath}`);
+    }
+    if (!ID_PATTERN.test(id)) {
+        throw new Error(`Invalid ID format "${id}" in ${filePath}. Must match kb:<type>:<slug> (lowercase, hyphens, underscores, digits)`);
+    }
+    // Required: type
+    const type = frontmatter.type;
+    if (typeof type !== 'string' || !VALID_TYPES.includes(type)) {
+        throw new Error(`Invalid or missing type "${type}" in ${filePath}. Must be one of: ${VALID_TYPES.join(', ')}`);
+    }
+    const lifecycle = deriveLifecycle(filePath);
+    // Base node
+    const base = {
+        id: id,
+        type: type,
+        projections: Array.isArray(frontmatter.projections) ? frontmatter.projections : [],
+        created: String(frontmatter.created ?? ''),
+        content: body.trim(),
+        filePath,
+        lifecycle,
+    };
+    // Optional base fields
+    if (frontmatter.subtype)
+        base.subtype = String(frontmatter.subtype);
+    if (frontmatter.scope)
+        base.scope = frontmatter.scope;
+    if (frontmatter.source)
+        base.source = String(frontmatter.source);
+    if (Array.isArray(frontmatter.relates_to))
+        base.relates_to = frontmatter.relates_to;
+    // Type-specific fields
+    switch (type) {
+        case 'DECISION': {
+            const decision = base;
+            decision.status = frontmatter.status ?? 'proposed';
+            if (frontmatter.effective_from)
+                decision.effective_from = String(frontmatter.effective_from);
+            if (frontmatter.effective_until)
+                decision.effective_until = String(frontmatter.effective_until);
+            if (Array.isArray(frontmatter.applies_to))
+                decision.applies_to = frontmatter.applies_to;
+            if (frontmatter.superseded_by)
+                decision.superseded_by = String(frontmatter.superseded_by);
+            return decision;
+        }
+        case 'FACT': {
+            const fact = base;
+            if (frontmatter.confidence)
+                fact.confidence = frontmatter.confidence;
+            if (frontmatter.superseded_by)
+                fact.superseded_by = String(frontmatter.superseded_by);
+            return fact;
+        }
+        case 'SESSION': {
+            const session = base;
+            if (frontmatter.task_id)
+                session.task_id = String(frontmatter.task_id);
+            if (frontmatter.session_path)
+                session.session_path = String(frontmatter.session_path);
+            if (Array.isArray(frontmatter.produced))
+                session.produced = frontmatter.produced;
+            return session;
+        }
+        default:
+            return base;
+    }
+}
+/**
+ * Serialize a KBNode back to markdown with YAML frontmatter.
+ */
+export function serializeKBNode(node) {
+    // Build frontmatter object (exclude computed/internal fields)
+    const fm = {
+        id: node.id,
+        type: node.type,
+    };
+    // Decision-specific
+    if (node.type === 'DECISION') {
+        const d = node;
+        fm.status = d.status;
+        if (d.applies_to?.length)
+            fm.applies_to = d.applies_to;
+        if (d.effective_from)
+            fm.effective_from = d.effective_from;
+        if (d.effective_until)
+            fm.effective_until = d.effective_until;
+        if (d.superseded_by)
+            fm.superseded_by = d.superseded_by;
+    }
+    // Fact-specific
+    if (node.type === 'FACT') {
+        const f = node;
+        if (f.confidence)
+            fm.confidence = f.confidence;
+        if (f.superseded_by)
+            fm.superseded_by = f.superseded_by;
+    }
+    // Session-specific
+    if (node.type === 'SESSION') {
+        const s = node;
+        if (s.task_id)
+            fm.task_id = s.task_id;
+        if (s.session_path)
+            fm.session_path = s.session_path;
+        if (s.produced?.length)
+            fm.produced = s.produced;
+    }
+    // Common optional fields
+    if (node.subtype)
+        fm.subtype = node.subtype;
+    if (node.scope)
+        fm.scope = node.scope;
+    if (node.projections.length > 0)
+        fm.projections = node.projections;
+    if (node.source)
+        fm.source = node.source;
+    if (node.relates_to?.length)
+        fm.relates_to = node.relates_to;
+    fm.created = node.created;
+    const yamlStr = stringifyYaml(fm, { lineWidth: 0 }).trimEnd();
+    const body = node.content ? `\n${node.content}\n` : '\n';
+    return `---\n${yamlStr}\n---\n${body}`;
+}
+/**
+ * Parse edges.yaml file into KBEdge array.
+ */
+export function parseEdgesFile(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const content = readFileSync(filePath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!parsed)
+        return [];
+    if (!Array.isArray(parsed)) {
+        throw new Error(`edges.yaml must be a YAML array, got ${typeof parsed}`);
+    }
+    return parsed.map((entry, i) => {
+        if (!entry || typeof entry !== 'object') {
+            throw new Error(`Edge at index ${i} is not an object`);
+        }
+        const e = entry;
+        if (!e.type || !e.from || !e.to) {
+            throw new Error(`Edge at index ${i} missing required fields (type, from, to)`);
+        }
+        const edge = {
+            type: String(e.type),
+            from: String(e.from),
+            to: String(e.to),
+        };
+        if (e.evidence)
+            edge.evidence = String(e.evidence);
+        return edge;
+    });
+}
+/**
+ * Parse a YAML file containing an array of node objects (e.g., commits/2026-03.yaml, authors.yaml).
+ * Each entry must have at least a `type` field. ID is generated based on type:
+ * - COMMIT → kb:commit:<short-hash>
+ * - AUTHOR → kb:author:<slug>
+ * - Others → kb:<type>:<index>
+ */
+export function parseYamlArrayFile(filePath) {
+    const content = readFileSync(filePath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!Array.isArray(parsed)) {
+        throw new Error(`YAML array file must contain an array, got ${typeof parsed} in ${filePath}`);
+    }
+    return parsed.map((entry, index) => {
+        if (!entry || typeof entry !== 'object') {
+            throw new Error(`Entry at index ${index} is not an object in ${filePath}`);
+        }
+        const e = entry;
+        const type = e.type;
+        if (typeof type !== 'string' || !VALID_TYPES.includes(type)) {
+            throw new Error(`Invalid or missing type "${type}" at index ${index} in ${filePath}. Must be one of: ${VALID_TYPES.join(', ')}`);
+        }
+        // Generate ID based on type
+        let id;
+        switch (type) {
+            case 'COMMIT':
+                id = `kb:commit:${String(e.hash ?? '').slice(0, 8)}`;
+                break;
+            case 'AUTHOR': {
+                if (typeof e.id === 'string' && e.id.startsWith('kb:author:')) {
+                    id = e.id;
+                }
+                else if (typeof e.id === 'string') {
+                    id = `kb:author:${e.id}`;
+                }
+                else {
+                    const name = String(e.name ?? '');
+                    id = `kb:author:${name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')}`;
+                }
+                break;
+            }
+            default:
+                id = `kb:${type.toLowerCase()}:${index}`;
+                break;
+        }
+        const base = {
+            id,
+            type: type,
+            projections: Array.isArray(e.projections) ? e.projections : [],
+            created: type === 'COMMIT' ? (String(e.date ?? '').split('T')[0]) : '',
+            content: '',
+            filePath,
+            lifecycle: 'derived',
+        };
+        // Spread all entry fields onto the node, preserving base fields
+        const node = { ...e, ...base };
+        return node;
+    });
+}
+/**
+ * Append an edge to the edges.yaml file.
+ */
+export function appendEdge(filePath, edge) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    const entry = {
+        type: edge.type,
+        from: edge.from,
+        to: edge.to,
+    };
+    if (edge.evidence)
+        entry.evidence = edge.evidence;
+    const yamlEntry = stringifyYaml([entry], { lineWidth: 0 }).trimEnd();
+    if (!existsSync(filePath)) {
+        // New file — write with comment header
+        const header = '# Knowledge Graph edges\n# Format: {type, from, to, evidence?}\n\n';
+        appendFileSync(filePath, header + yamlEntry + '\n', 'utf-8');
+    }
+    else {
+        // Append to existing file
+        appendFileSync(filePath, '\n' + yamlEntry + '\n', 'utf-8');
+    }
+}
+//# sourceMappingURL=parser.js.map

package/dist/knowledge/parser.js.map

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

package/dist/knowledge/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Knowledge Base Types
+ *
+ * Semantic types for the persistent knowledge layer.
+ * KB nodes are stored as git-tracked markdown files with YAML frontmatter.
+ */
+/** Node types in the knowledge graph */
+export type KBNodeType = 'DECISION' | 'FACT' | 'SESSION' | 'COMMIT' | 'FILE_CHANGE' | 'AUTHOR' | 'TICKET' | 'INCIDENT';
+/** Lifecycle derived from directory path */
+export type KBLifecycle = 'declared' | 'derived' | 'synced';
+/** Scope of a knowledge node */
+export type KBScope = 'global' | 'project' | 'module';
+/** Base fields shared by all KB nodes */
+export interface KBNodeBase {
+    /** Semantic ID in format kb:<type>:<slug> */
+    id: string;
+    /** Node type */
+    type: KBNodeType;
+    /** Subtype within the node type (e.g., FACT: domain|error|preference, DECISION: adr|runbook) */
+    subtype?: string;
+    /** Scope of applicability */
+    scope?: KBScope;
+    /** Projections this node belongs to (e.g., 'epistemic', 'temporal') */
+    projections: string[];
+    /** Source node that produced this (e.g., session ID) */
+    source?: string;
+    /** Creation date (YYYY-MM-DD) */
+    created: string;
+    /** Markdown body content */
+    content: string;
+    /** Path to the .md file on disk */
+    filePath: string;
+    /** Lifecycle derived from directory structure */
+    lifecycle: KBLifecycle;
+    /** Semantic IDs of related nodes */
+    relates_to?: string[];
+}
+/** Decision node — architectural/design decisions */
+export interface KBDecision extends KBNodeBase {
+    type: 'DECISION';
+    /** Decision status */
+    status: 'active' | 'superseded' | 'deprecated' | 'proposed';
+    /** Date when decision took effect */
+    effective_from?: string;
+    /** Date when decision was superseded/deprecated */
+    effective_until?: string;
+    /** Semantic addresses of code this applies to */
+    applies_to?: string[];
+    /** ID of the decision that superseded this one */
+    superseded_by?: string;
+}
+/** Fact node — observed facts about the codebase */
+export interface KBFact extends KBNodeBase {
+    type: 'FACT';
+    /** Confidence level */
+    confidence?: 'high' | 'medium' | 'low';
+    /** ID of the fact that superseded this one */
+    superseded_by?: string;
+}
+/** Session node — records of design/work sessions */
+export interface KBSession extends KBNodeBase {
+    type: 'SESSION';
+    /** Associated Linear task ID */
+    task_id?: string;
+    /** Path to session transcript */
+    session_path?: string;
+    /** IDs of nodes produced during this session */
+    produced?: string[];
+}
+/** Union of all KB node types */
+export type KBNode = KBDecision | KBFact | KBSession | KBNodeBase;
+/** Edge in the knowledge graph */
+export interface KBEdge {
+    /** Edge type (e.g., PRODUCED, IMPLEMENTS, INFORMED_BY) */
+    type: string;
+    /** Source node semantic ID */
+    from: string;
+    /** Target node semantic ID */
+    to: string;
+    /** Optional evidence for the relationship */
+    evidence?: string;
+}
+/** Statistics about the knowledge base */
+export interface KBStats {
+    /** Total node count */
+    totalNodes: number;
+    /** Counts by node type */
+    byType: Partial<Record<KBNodeType, number>>;
+    /** Counts by lifecycle */
+    byLifecycle: Partial<Record<KBLifecycle, number>>;
+    /** Total edge count */
+    totalEdges: number;
+    /** Edge counts by type */
+    edgesByType: Record<string, number>;
+    /** Dangling edge references (from/to IDs that don't exist as nodes) */
+    danglingRefs: string[];
+    /** KB nodes referencing code addresses that don't resolve to graph nodes */
+    danglingCodeRefs: DanglingCodeRef[];
+}
+/** Filter for querying KB nodes */
+export interface KBQueryFilter {
+    /** Filter by node type */
+    type?: KBNodeType;
+    /** Filter by projection */
+    projection?: string;
+    /** Case-insensitive text search in body content */
+    text?: string;
+    /** Filter by decision status */
+    status?: string;
+    /** Filter by relates_to containing this ID */
+    relates_to?: string;
+    /** When true, return only nodes with dangling code references */
+    include_dangling_only?: boolean;
+}
+/** Parsed semantic address: file:name:TYPE or file:scope1:...:scopeN:name:TYPE */
+export interface ParsedSemanticAddress {
+    file: string;
+    name: string;
+    type: string;
+    scopePath: string[];
+}
+/** Result of resolving a semantic address to a code graph node */
+export interface ResolvedAddress {
+    address: string;
+    codeNodeId: string | null;
+    status: 'resolved' | 'dangling';
+}
+/** A dangling code reference from a KB node */
+export interface DanglingCodeRef {
+    nodeId: string;
+    address: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/knowledge/types.d.ts.map

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

package/dist/knowledge/types.js

@@ -0,0 +1,8 @@
+/**
+ * Knowledge Base Types
+ *
+ * Semantic types for the persistent knowledge layer.
+ * KB nodes are stored as git-tracked markdown files with YAML frontmatter.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/knowledge/types.js.map

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

package/dist/logging/Logger.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Logger - Lightweight logging for Grafema
+ *
+ * Features:
+ * - 5 log levels: silent, errors, warnings, info, debug
+ * - Context support for structured logging
+ * - Console and file output (or both via MultiLogger)
+ * - Safe handling of circular references
+ *
+ * Usage:
+ *   const logger = createLogger('info');
+ *   logger.info('Processing files', { count: 150 });
+ *
+ *   // Write logs to file (REG-199):
+ *   const logger = createLogger('info', { logFile: '.grafema/analysis.log' });
+ */
+/**
+ * Log level type
+ */
+export type LogLevel = 'silent' | 'errors' | 'warnings' | 'info' | 'debug';
+/**
+ * Logger interface
+ */
+export interface Logger {
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    trace(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * Console-based Logger implementation
+ *
+ * Respects log level threshold - methods below threshold are no-ops.
+ */
+export declare class ConsoleLogger implements Logger {
+    private readonly level;
+    private readonly priority;
+    constructor(logLevel?: LogLevel);
+    private shouldLog;
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    trace(message: string, context?: Record<string, unknown>): void;
+}
+/**
+ * File-based Logger implementation (REG-199)
+ *
+ * Writes log messages to a file with ISO timestamps using a write stream
+ * (non-blocking I/O). File is truncated on construction (overwritten each run).
+ * Parent directories are created automatically.
+ *
+ * Validates path on construction — throws if the directory is not writable
+ * or the path points to a directory.
+ */
+export declare class FileLogger implements Logger {
+    private readonly priority;
+    private readonly stream;
+    constructor(logLevel: LogLevel, filePath: string);
+    private shouldLog;
+    private writeLine;
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    trace(message: string, context?: Record<string, unknown>): void;
+    /** Flush and close the write stream. Returns when all data is written. */
+    close(): Promise<void>;
+}
+/**
+ * Multi-output Logger that delegates to multiple Logger instances.
+ *
+ * Each inner logger applies its own level filtering independently.
+ * Used to write to both console and file simultaneously.
+ */
+export declare class MultiLogger implements Logger {
+    private readonly loggers;
+    constructor(loggers: Logger[]);
+    error(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    info(message: string, context?: Record<string, unknown>): void;
+    debug(message: string, context?: Record<string, unknown>): void;
+    trace(message: string, context?: Record<string, unknown>): void;
+    /** Close all inner loggers that have a close() method (e.g., FileLogger). */
+    close(): Promise<void>;
+}
+/**
+ * Create a Logger instance with the specified log level.
+ *
+ * When logFile is specified, returns a MultiLogger that writes to both
+ * console and file. The file logger always captures at 'debug' level
+ * for complete post-mortem debugging, regardless of the console level.
+ */
+export declare function createLogger(level: LogLevel, options?: {
+    logFile?: string;
+}): Logger;
+//# sourceMappingURL=Logger.d.ts.map

package/dist/logging/Logger.d.ts.map

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