@grafema/util 0.3.0-beta

package/dist/logging/Logger.js

@@ -0,0 +1,274 @@
+/**
+ * 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 } from 'fs';
+import { dirname, resolve } from 'path';
+/**
+ * Log level priorities (higher = more verbose)
+ */
+const LOG_LEVEL_PRIORITY = {
+    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) {
+    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, context) {
+    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 {
+    level;
+    priority;
+    constructor(logLevel = 'info') {
+        this.level = logLevel;
+        this.priority = LOG_LEVEL_PRIORITY[logLevel];
+    }
+    shouldLog(methodLevel) {
+        return this.priority >= methodLevel;
+    }
+    error(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.error))
+            return;
+        try {
+            console.error(formatMessage(`[ERROR] ${message}`, context));
+        }
+        catch {
+            console.log(`[ERROR] ${message} [logging failed]`);
+        }
+    }
+    warn(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.warn))
+            return;
+        try {
+            console.warn(formatMessage(`[WARN] ${message}`, context));
+        }
+        catch {
+            console.log(`[WARN] ${message} [logging failed]`);
+        }
+    }
+    info(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.info))
+            return;
+        try {
+            console.info(formatMessage(`[INFO] ${message}`, context));
+        }
+        catch {
+            console.log(`[INFO] ${message} [logging failed]`);
+        }
+    }
+    debug(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.debug))
+            return;
+        try {
+            console.debug(formatMessage(`[DEBUG] ${message}`, context));
+        }
+        catch {
+            console.log(`[DEBUG] ${message} [logging failed]`);
+        }
+    }
+    trace(message, context) {
+        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 {
+    priority;
+    stream;
+    constructor(logLevel, filePath) {
+        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
+        });
+    }
+    shouldLog(methodLevel) {
+        return this.priority >= methodLevel;
+    }
+    writeLine(level, message, context) {
+        const timestamp = new Date().toISOString();
+        const formatted = formatMessage(`${timestamp} [${level}] ${message}`, context);
+        this.stream.write(formatted + '\n');
+    }
+    error(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.error))
+            return;
+        this.writeLine('ERROR', message, context);
+    }
+    warn(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.warn))
+            return;
+        this.writeLine('WARN', message, context);
+    }
+    info(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.info))
+            return;
+        this.writeLine('INFO', message, context);
+    }
+    debug(message, context) {
+        if (!this.shouldLog(METHOD_LEVELS.debug))
+            return;
+        this.writeLine('DEBUG', message, context);
+    }
+    trace(message, context) {
+        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() {
+        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 {
+    loggers;
+    constructor(loggers) {
+        this.loggers = loggers;
+    }
+    error(message, context) {
+        for (const logger of this.loggers)
+            logger.error(message, context);
+    }
+    warn(message, context) {
+        for (const logger of this.loggers)
+            logger.warn(message, context);
+    }
+    info(message, context) {
+        for (const logger of this.loggers)
+            logger.info(message, context);
+    }
+    debug(message, context) {
+        for (const logger of this.loggers)
+            logger.debug(message, context);
+    }
+    trace(message, context) {
+        for (const logger of this.loggers)
+            logger.trace(message, context);
+    }
+    /** Close all inner loggers that have a close() method (e.g., FileLogger). */
+    async close() {
+        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, options) {
+    const consoleLogger = new ConsoleLogger(level);
+    if (options?.logFile) {
+        const fileLogger = new FileLogger('debug', options.logFile);
+        return new MultiLogger([consoleLogger, fileLogger]);
+    }
+    return consoleLogger;
+}
+//# sourceMappingURL=Logger.js.map

package/dist/logging/Logger.js.map

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

package/dist/notation/archetypes.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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 { EdgeMapping } from './types.js';
+/**
+ * Complete mapping of all edge types to archetypes.
+ *
+ * Keys match EDGE_TYPE values from @grafema/types/edges.
+ */
+export declare const EDGE_ARCHETYPE_MAP: Record<string, EdgeMapping>;
+/**
+ * Look up edge mapping. Returns a fallback for unmapped types.
+ */
+export declare function lookupEdge(edgeType: string): EdgeMapping;
+/**
+ * Generate a legend string from the archetype table.
+ * Single source of truth for all tools (describe, trace_dataflow, CLI).
+ */
+export declare function generateLegend(): string;
+//# sourceMappingURL=archetypes.d.ts.map

package/dist/notation/archetypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archetypes.d.ts","sourceRoot":"","sources":["../../src/notation/archetypes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,YAAY,CAAC;AAuBzD;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAqG1D,CAAC;AAEF;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,CAOxD;AAoBD;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAGvC"}

package/dist/notation/archetypes.js

@@ -0,0 +1,173 @@
+/**
+ * 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
+ */
+// Sort order by archetype: input → process → output
+// flow_in first (receives, reads), then deps, then calls, then side effects
+const SORT = {
+    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, operator, verb, sortOverride) {
+    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 = {
+    // === 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) {
+    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 = (() => {
+    const seen = new Set();
+    const result = [];
+    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() {
+    const parts = CANONICAL_OPERATORS.map(({ operator, verb }) => `${operator} ${verb}`);
+    return `Legend: ${parts.join('  ')}  {} contains`;
+}
+//# sourceMappingURL=archetypes.js.map

package/dist/notation/archetypes.js.map

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

package/dist/notation/fold.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Notation Fold Engine — structural compression of sibling blocks
+ *
+ * Pure function: NotationBlock[] → NotationBlock[]
+ * Fold is a view-layer transform, not part of DSL grammar.
+ *
+ * Implements 11 rules from notation-folding.md:
+ *   Rules 1-5: structural (language-agnostic)
+ *   Rules 6-7: cleanup (dedup, artifacts)
+ *   Rules 8-11: semantic (derivation/call patterns)
+ *
+ * Pipeline order matters — chains/dispatch collapse adjacent siblings first,
+ * making the remaining set more amenable to group folding.
+ *
+ * @module notation/fold
+ */
+import type { NotationBlock } from './types.js';
+/**
+ * Apply all folding rules to a list of sibling blocks.
+ * Returns a new list where repetitive structures are compressed.
+ *
+ * Folding is recursive — children of non-folded blocks are also folded.
+ */
+export declare function foldBlocks(blocks: NotationBlock[]): NotationBlock[];
+//# sourceMappingURL=fold.d.ts.map

package/dist/notation/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../src/notation/fold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA8HhD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CA2DnE"}