@grafema/util 0.3.0-beta

package/src/knowledge/types.ts

@@ -0,0 +1,146 @@
+/**
+ * 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;
+}

package/src/logging/Logger.ts

@@ -0,0 +1,303 @@
+/**
+ * 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' });
+ */
+
+import { createWriteStream, writeFileSync, mkdirSync, accessSync, statSync, constants, type WriteStream } from 'fs';
+import { dirname, resolve } from 'path';
+
+/**
+ * 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;
+}
+
+/**
+ * Log level priorities (higher = more verbose)
+ */
+const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+  silent: 0,
+  errors: 1,
+  warnings: 2,
+  info: 3,
+  debug: 4,
+};
+
+/**
+ * Minimum level required for each method
+ */
+const METHOD_LEVELS = {
+  error: LOG_LEVEL_PRIORITY.errors,
+  warn: LOG_LEVEL_PRIORITY.warnings,
+  info: LOG_LEVEL_PRIORITY.info,
+  debug: LOG_LEVEL_PRIORITY.debug,
+  trace: LOG_LEVEL_PRIORITY.debug,
+};
+
+/**
+ * Safe JSON stringify that handles circular references
+ */
+function safeStringify(obj: unknown): string {
+  const seen = new WeakSet();
+  return JSON.stringify(obj, (_key, value) => {
+    if (typeof value === 'object' && value !== null) {
+      if (seen.has(value)) {
+        return '[Circular]';
+      }
+      seen.add(value);
+    }
+    return value;
+  });
+}
+
+/**
+ * Format log message with optional context
+ */
+function formatMessage(message: string, context?: Record<string, unknown>): string {
+  if (!context || Object.keys(context).length === 0) {
+    return message;
+  }
+  try {
+    return `${message} ${safeStringify(context)}`;
+  } catch {
+    return `${message} [context serialization failed]`;
+  }
+}
+
+/**
+ * Console-based Logger implementation
+ *
+ * Respects log level threshold - methods below threshold are no-ops.
+ */
+export class ConsoleLogger implements Logger {
+  private readonly level: LogLevel;
+  private readonly priority: number;
+
+  constructor(logLevel: LogLevel = 'info') {
+    this.level = logLevel;
+    this.priority = LOG_LEVEL_PRIORITY[logLevel];
+  }
+
+  private shouldLog(methodLevel: number): boolean {
+    return this.priority >= methodLevel;
+  }
+
+  error(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.error)) return;
+    try {
+      console.error(formatMessage(`[ERROR] ${message}`, context));
+    } catch {
+      console.log(`[ERROR] ${message} [logging failed]`);
+    }
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.warn)) return;
+    try {
+      console.warn(formatMessage(`[WARN] ${message}`, context));
+    } catch {
+      console.log(`[WARN] ${message} [logging failed]`);
+    }
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.info)) return;
+    try {
+      console.info(formatMessage(`[INFO] ${message}`, context));
+    } catch {
+      console.log(`[INFO] ${message} [logging failed]`);
+    }
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.debug)) return;
+    try {
+      console.debug(formatMessage(`[DEBUG] ${message}`, context));
+    } catch {
+      console.log(`[DEBUG] ${message} [logging failed]`);
+    }
+  }
+
+  trace(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.trace)) return;
+    try {
+      console.debug(formatMessage(`[TRACE] ${message}`, context));
+    } catch {
+      console.log(`[TRACE] ${message} [logging failed]`);
+    }
+  }
+}
+
+/**
+ * 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 class FileLogger implements Logger {
+  private readonly priority: number;
+  private readonly stream: WriteStream;
+
+  constructor(logLevel: LogLevel, filePath: string) {
+    this.priority = LOG_LEVEL_PRIORITY[logLevel];
+    const resolvedPath = resolve(filePath);
+
+    // Create parent directories
+    const dir = dirname(resolvedPath);
+    mkdirSync(dir, { recursive: true });
+
+    // Validate: parent directory must be writable
+    try {
+      accessSync(dir, constants.W_OK);
+    } catch {
+      throw new Error(`Cannot write log file: directory '${dir}' is not writable`);
+    }
+
+    // Validate: path must not point to an existing directory
+    try {
+      if (statSync(resolvedPath).isDirectory()) {
+        throw new Error(`Cannot write log file: '${resolvedPath}' is a directory`);
+      }
+    } catch (e) {
+      // If stat throws, file doesn't exist yet — that's fine
+      if (e instanceof Error && e.message.includes('is a directory')) throw e;
+    }
+
+    // Truncate/create file synchronously (validates writeability),
+    // then open stream in append mode for non-blocking writes
+    writeFileSync(resolvedPath, '');
+    this.stream = createWriteStream(resolvedPath, { flags: 'a' });
+    this.stream.on('error', () => {
+      // Silently ignore stream errors — don't crash analysis for logging failures
+    });
+  }
+
+  private shouldLog(methodLevel: number): boolean {
+    return this.priority >= methodLevel;
+  }
+
+  private writeLine(level: string, message: string, context?: Record<string, unknown>): void {
+    const timestamp = new Date().toISOString();
+    const formatted = formatMessage(`${timestamp} [${level}] ${message}`, context);
+    this.stream.write(formatted + '\n');
+  }
+
+  error(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.error)) return;
+    this.writeLine('ERROR', message, context);
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.warn)) return;
+    this.writeLine('WARN', message, context);
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.info)) return;
+    this.writeLine('INFO', message, context);
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.debug)) return;
+    this.writeLine('DEBUG', message, context);
+  }
+
+  trace(message: string, context?: Record<string, unknown>): void {
+    if (!this.shouldLog(METHOD_LEVELS.trace)) return;
+    this.writeLine('TRACE', message, context);
+  }
+
+  /** Flush and close the write stream. Returns when all data is written. */
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.stream.end(resolve);
+    });
+  }
+}
+
+/**
+ * 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 class MultiLogger implements Logger {
+  private readonly loggers: Logger[];
+
+  constructor(loggers: Logger[]) {
+    this.loggers = loggers;
+  }
+
+  error(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.error(message, context);
+  }
+
+  warn(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.warn(message, context);
+  }
+
+  info(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.info(message, context);
+  }
+
+  debug(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.debug(message, context);
+  }
+
+  trace(message: string, context?: Record<string, unknown>): void {
+    for (const logger of this.loggers) logger.trace(message, context);
+  }
+
+  /** Close all inner loggers that have a close() method (e.g., FileLogger). */
+  async close(): Promise<void> {
+    for (const logger of this.loggers) {
+      if (logger instanceof FileLogger) {
+        await logger.close();
+      }
+    }
+  }
+}
+
+/**
+ * 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 function createLogger(level: LogLevel, options?: { logFile?: string }): Logger {
+  const consoleLogger = new ConsoleLogger(level);
+
+  if (options?.logFile) {
+    const fileLogger = new FileLogger('debug', options.logFile);
+    return new MultiLogger([consoleLogger, fileLogger]);
+  }
+
+  return consoleLogger;
+}

package/src/notation/archetypes.ts

@@ -0,0 +1,189 @@
+/**
+ * Edge → Archetype Mapping Table
+ *
+ * Maps every EDGE_TYPE from @grafema/types to a visual archetype + operator + verb.
+ * Pure data — no side effects.
+ *
+ * Archetypes (7 base + 2 structural):
+ *   contains (implicit nesting, no operator)
+ *   depends   o-   dependency/import
+ *   flow_out  >    outward data/call flow
+ *   flow_in   <    inward data/type flow
+ *   write     =>   persistent side effect
+ *   exception >x   error/rejection
+ *   publishes ~>>  event/message
+ *   gates     ?|   conditional guard
+ *   governs   |=   governance/invariant
+ *
+ * @module notation/archetypes
+ */
+
+import type { Archetype, EdgeMapping } from './types.js';
+
+// Sort order by archetype: input → process → output
+// flow_in first (receives, reads), then deps, then calls, then side effects
+const SORT: Record<Archetype, number> = {
+  contains: 0,
+  flow_in: 1,
+  depends: 2,
+  flow_out: 3,
+  write: 4,
+  publishes: 5,
+  exception: 6,
+  gates: 7,
+  governs: 8,
+};
+
+/** Sort order for "returns" verbs — output comes last */
+const RETURNS_SORT = 9;
+
+function m(archetype: Archetype, operator: string, verb: string, sortOverride?: number): EdgeMapping {
+  return { archetype, operator, verb, sortOrder: sortOverride ?? SORT[archetype] };
+}
+
+/**
+ * Complete mapping of all edge types to archetypes.
+ *
+ * Keys match EDGE_TYPE values from @grafema/types/edges.
+ */
+export const EDGE_ARCHETYPE_MAP: Record<string, EdgeMapping> = {
+  // === Containment (operator='', defines { } nesting) ===
+  CONTAINS:       m('contains', '', 'contains'),
+  HAS_SCOPE:      m('contains', '', 'scopes'),
+  HAS_MEMBER:     m('contains', '', 'has'),
+  HAS_BODY:       m('contains', '', 'body'),
+  HAS_PROPERTY:   m('contains', '', 'property'),
+  HAS_ELEMENT:    m('contains', '', 'element'),
+  HAS_INIT:       m('contains', '', 'init'),
+  HAS_UPDATE:     m('contains', '', 'update'),
+  HAS_CALLBACK:   m('contains', '', 'callback'),
+  HAS_CATCH:      m('contains', '', 'catch'),
+  HAS_FINALLY:    m('contains', '', 'finally'),
+  DECLARES:       m('contains', '', 'declares'),
+  DEFINES:        m('contains', '', 'defines'),
+  MOUNTS:         m('contains', '', 'mounts'),
+  PROPERTY_KEY:   m('contains', '', 'key'),
+  PROPERTY_VALUE: m('contains', '', 'value'),
+
+  // === Depends (o-) ===
+  DEPENDS_ON:     m('depends', 'o-', 'depends on'),
+  IMPORTS:        m('depends', 'o-', 'imports'),
+  IMPORTS_FROM:   m('depends', 'o-', 'imports from'),
+  EXPORTS:        m('depends', 'o-', 'exports'),
+  USES:           m('depends', 'o-', 'uses'),
+  USES_CONFIG:    m('depends', 'o-', 'uses config'),
+  USES_SECRET:    m('depends', 'o-', 'uses secret'),
+  DEPLOYED_TO:    m('depends', 'o-', 'deployed to'),
+  SCHEDULED_BY:   m('depends', 'o-', 'scheduled by'),
+
+  // === Flow Out (>) ===
+  CALLS:              m('flow_out', '>', 'calls'),
+  DELEGATES_TO:       m('flow_out', '>', 'delegates to'),
+  ROUTES_TO:          m('flow_out', '>', 'routes to'),
+  HANDLED_BY:         m('flow_out', '>', 'handled by'),
+  MAKES_REQUEST:      m('flow_out', '>', 'requests'),
+  CALLS_API:          m('flow_out', '>', 'calls API'),
+  INVOKES_FUNCTION:   m('flow_out', '>', 'invokes'),
+  PASSES_ARGUMENT:    m('flow_out', '>', 'passes'),
+  RETURNS:            m('flow_out', '>', 'returns', RETURNS_SORT),
+  CALL_RETURNS:       m('flow_out', '>', 'call returns', RETURNS_SORT),
+  YIELDS:             m('flow_out', '>', 'yields', RETURNS_SORT),
+  RESPONDS_WITH:      m('flow_out', '>', 'responds with', RETURNS_SORT),
+  INTERACTS_WITH:     m('flow_out', '>', 'interacts with'),
+  ITERATES_OVER:      m('flow_out', '>', 'iterates'),
+  ASSIGNS_TO:         m('flow_out', '>', 'assigns to'),
+  MODIFIES:           m('flow_out', '>', 'modifies'),
+  CAPTURES:           m('flow_out', '>', 'captures'),
+  FLOWS_INTO:         m('flow_out', '>', 'flows into'),
+
+  // === Flow In (<) ===
+  READS_FROM:         m('flow_in', '<', 'reads'),
+  RECEIVES_ARGUMENT:  m('flow_in', '<', 'receives'),
+  ASSIGNED_FROM:      m('flow_in', '<', 'assigned from'),
+  DERIVES_FROM:       m('flow_in', '<', 'derives from'),
+  SPREADS_FROM:       m('flow_in', '<', 'spreads from'),
+  ELEMENT_OF:         m('flow_in', '<', 'element of'),
+  KEY_OF:             m('flow_in', '<', 'key of'),
+  DESTRUCTURED_FROM:  m('flow_in', '<', 'destructured from'),
+  HTTP_RECEIVES:      m('flow_in', '<', 'receives HTTP'),
+  EXTENDS:            m('flow_in', '<', 'extends'),
+  IMPLEMENTS:         m('flow_in', '<', 'implements'),
+  INSTANCE_OF:        m('flow_in', '<', 'instance of'),
+
+  // === Write (=>) ===
+  WRITES_TO:          m('write', '=>', 'writes'),
+  LOGS_TO:            m('write', '=>', 'logs to'),
+  PERFORMS_REDIS:      m('write', '=>', 'redis'),
+
+  // === Exception (>x) ===
+  THROWS:             m('exception', '>x', 'throws'),
+  REJECTS:            m('exception', '>x', 'rejects'),
+  CATCHES_FROM:       m('exception', '>x', 'catches from'),
+
+  // === Publishes (~>>) ===
+  EMITS_EVENT:        m('publishes', '~>>', 'emits'),
+  LISTENS_TO:         m('publishes', '~>>', 'listens to'),
+  PUBLISHES_TO:       m('publishes', '~>>', 'publishes to'),
+  SUBSCRIBES_TO:      m('publishes', '~>>', 'subscribes to'),
+  EXPOSED_VIA:        m('publishes', '~>>', 'exposed via'),
+  EXPOSES:            m('publishes', '~>>', 'exposes'),
+  JOINS_ROOM:         m('publishes', '~>>', 'joins room'),
+
+  // === Gates (?|) ===
+  HAS_CONDITION:      m('gates', '?|', 'guards'),
+  HAS_CONSEQUENT:     m('gates', '?|', 'then'),
+  HAS_ALTERNATE:      m('gates', '?|', 'else'),
+  HAS_CASE:           m('gates', '?|', 'case'),
+  HAS_DEFAULT:        m('gates', '?|', 'default'),
+
+  // === Governs (|=) ===
+  GOVERNS:            m('governs', '|=', 'governs'),
+  VIOLATES:           m('governs', '|=', 'violates'),
+  AFFECTS:            m('governs', '|=', 'affects'),
+  MONITORED_BY:       m('governs', '|=', 'monitored by'),
+  MEASURED_BY:        m('governs', '|=', 'measured by'),
+  PROVISIONED_BY:     m('governs', '|=', 'provisioned by'),
+  REGISTERS_VIEW:     m('governs', '|=', 'registers view'),
+
+  // === Fallback ===
+  UNKNOWN:            m('flow_out', '>', 'unknown'),
+};
+
+/**
+ * Look up edge mapping. Returns a fallback for unmapped types.
+ */
+export function lookupEdge(edgeType: string): EdgeMapping {
+  return EDGE_ARCHETYPE_MAP[edgeType] ?? {
+    archetype: 'flow_out',
+    operator: '>',
+    verb: edgeType.toLowerCase().replace(/_/g, ' '),
+    sortOrder: SORT.flow_out,
+  };
+}
+
+/**
+ * Canonical operator → verb mapping, one entry per unique operator.
+ * Derived from the archetype table — single source of truth.
+ */
+const CANONICAL_OPERATORS: Array<{ operator: string; verb: string }> = (() => {
+  const seen = new Set<string>();
+  const result: Array<{ operator: string; verb: string }> = [];
+  const entries = Object.values(EDGE_ARCHETYPE_MAP);
+  // Sort by archetype sort order for consistent legend ordering
+  entries.sort((a, b) => a.sortOrder - b.sortOrder);
+  for (const entry of entries) {
+    if (!entry.operator || seen.has(entry.operator)) continue;
+    seen.add(entry.operator);
+    result.push({ operator: entry.operator, verb: entry.verb });
+  }
+  return result;
+})();
+
+/**
+ * Generate a legend string from the archetype table.
+ * Single source of truth for all tools (describe, trace_dataflow, CLI).
+ */
+export function generateLegend(): string {
+  const parts = CANONICAL_OPERATORS.map(({ operator, verb }) => `${operator} ${verb}`);
+  return `Legend: ${parts.join('  ')}  {} contains`;
+}