spec-up-t 1.5.0 → 1.6.0-beta.1

package/src/utils/logger.js

@@ -15,30 +15,127 @@ class Logger {
     static success(message, ...args) {
         console.log(chalk.green('✅'), chalk.green(message), ...args);
         messageCollector.addMessage('success', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
      * Error messages - red with X mark
+     * 
+     * Enhanced error logging with optional context and actionable guidance.
+     * 
+     * @param {string} message - The main error message
+     * @param {...any} args - Additional arguments. Can include:
+     *   - Regular values (strings, numbers, objects) for message formatting
+     *   - An options object (if last arg is object with 'hint', 'context', or 'details' keys):
+     *     - hint: Actionable suggestion for fixing the error
+     *     - context: Additional context about where/why the error occurred
+     *     - details: Technical details or error objects
+     * 
+     * @example
+     * Logger.error('File not found', { 
+     *   context: 'specs.json',
+     *   hint: 'Create a specs.json file in your project root',
+     *   details: error.message 
+     * });
      */
     static error(message, ...args) {
-        console.log(chalk.red('❌'), chalk.red(message), ...args);
-        messageCollector.addMessage('error', message, args);
+        // Extract options object if present (last arg with special keys)
+        const lastArg = args[args.length - 1];
+        const isOptionsObject = lastArg && typeof lastArg === 'object' &&
+            (lastArg.hint || lastArg.context || lastArg.details);
+
+        const options = isOptionsObject ? args.pop() : {};
+        const regularArgs = args;
+
+        // Display main error message
+        console.log(chalk.red('❌'), chalk.red(message), ...regularArgs);
+
+        // Display context if provided - helps identify the scope of the error
+        if (options.context) {
+            console.log(chalk.red('   Context:'), chalk.gray(options.context));
+        }
+
+        // Display technical details if provided - useful for debugging
+        if (options.details) {
+            const detailsStr = typeof options.details === 'object'
+                ? JSON.stringify(options.details, null, 2)
+                : String(options.details);
+            console.log(chalk.red('   Details:'), chalk.gray(detailsStr));
+        }
+
+        // Display actionable hint if provided - most valuable for authors
+        if (options.hint) {
+            console.log(chalk.yellow('   💡 How to fix:'), chalk.yellow(options.hint));
+        }
+
+        // Collect message with all context for healthcheck/JSON output
+        messageCollector.addMessage('error', message, [...regularArgs, options]);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
      * Warning messages - yellow with warning symbol
+     * 
+     * Enhanced warning logging with optional context and actionable guidance.
+     * 
+     * @param {string} message - The main warning message
+     * @param {...any} args - Additional arguments. Can include:
+     *   - Regular values (strings, numbers, objects) for message formatting
+     *   - An options object (if last arg is object with 'hint', 'context', or 'details' keys):
+     *     - hint: Actionable suggestion for addressing the warning
+     *     - context: Additional context about where/why the warning occurred
+     *     - details: Technical details or related information
+     * 
+     * @example
+     * Logger.warn('Using fallback configuration', { 
+     *   context: 'specs.json missing optional field',
+     *   hint: 'Add "output_path" to specs.json for better control',
+     *   details: 'Using default: ./docs' 
+     * });
      */
     static warn(message, ...args) {
-        console.log(chalk.yellow('🟡'), chalk.yellow(message), ...args);
-        messageCollector.addMessage('warn', message, args);
+        // Extract options object if present (last arg with special keys)
+        const lastArg = args[args.length - 1];
+        const isOptionsObject = lastArg && typeof lastArg === 'object' &&
+            (lastArg.hint || lastArg.context || lastArg.details);
+
+        const options = isOptionsObject ? args.pop() : {};
+        const regularArgs = args;
+
+        // Display main warning message
+        console.log(chalk.keyword('orange')('❗'), chalk.yellow(message), ...regularArgs);
+
+        // Display context if provided - helps identify the scope of the warning
+        if (options.context) {
+            console.log(chalk.yellow('   Context:'), chalk.gray(options.context));
+        }
+
+        // Display technical details if provided - useful for understanding the situation
+        if (options.details) {
+            const detailsStr = typeof options.details === 'object'
+                ? JSON.stringify(options.details, null, 2)
+                : String(options.details);
+            console.log(chalk.yellow('   Details:'), chalk.gray(detailsStr));
+        }
+
+        // Display actionable hint if provided - helps authors improve their spec
+        if (options.hint) {
+            console.log(chalk.cyan('   💡 Suggestion:'), chalk.cyan(options.hint));
+        }
+
+        // Collect message with all context for healthcheck/JSON output
+        messageCollector.addMessage('warn', message, [...regularArgs, options]);
+
+        console.log(); // Extra newline for readability
     }
 
-    /**
-     * Info messages - blue with info symbol
-     */
     static info(message, ...args) {
-        console.log(chalk.blue('📒'), chalk.blue(message), ...args);
+        console.log(chalk.blue('📋'), chalk.blue(message), ...args);
         messageCollector.addMessage('info', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -47,6 +144,8 @@ class Logger {
     static process(message, ...args) {
         console.log(chalk.cyan('🔄'), chalk.cyan(message), ...args);
         messageCollector.addMessage('process', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -55,14 +154,18 @@ class Logger {
     static debug(message, ...args) {
         console.log(chalk.gray('🔍'), chalk.gray(message), ...args);
         messageCollector.addMessage('debug', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
      * Highlight important data - magenta
      */
     static highlight(message, ...args) {
-        console.log(chalk.blue('✨'), chalk.blue(message), ...args);
+        console.log(chalk.blue('📋'), chalk.blue(message), ...args);
         messageCollector.addMessage('highlight', message, args);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -71,6 +174,8 @@ class Logger {
     static separator() {
         console.log(chalk.gray('═'.repeat(60)));
         messageCollector.addMessage('separator', '═'.repeat(60), []);
+
+        console.log(); // Extra newline for readability
     }
 
     /**
@@ -82,6 +187,8 @@ class Logger {
         const progressMessage = `[${bar}] ${percentage}% ${message}`;
         console.log(chalk.cyan(`📊 ${progressMessage}`));
         messageCollector.addMessage('progress', progressMessage, [current, total]);
+
+        console.log(); // Extra newline for readability
     }
 }
 

package/src/utils/regex-patterns.js

@@ -109,12 +109,14 @@ const templateTags = {
    * Pattern breakdown:
    * - ^def$ → Exact match for "def" (definition)
    * - ^ref$ → Exact match for "ref" (reference)
+   * - ^iref$ → Exact match for "iref" (inline reference - copies existing term)
    * - ^xref → Starts with "xref" (external reference)
    * - ^tref → Starts with "tref" (typed reference)
    * 
    * Examples:
    * - "def" → matches
    * - "ref" → matches
+   * - "iref" → matches
    * - "xref" → matches
    * - "tref" → matches
    * - "xref:spec,term" → matches (starts with xref)
@@ -122,7 +124,7 @@ const templateTags = {
    * Flags:
    * - i: case-insensitive matching
    */
-  terminology: /^def$|^ref$|^xref|^tref$/i
+  terminology: /^def$|^ref$|^iref$|^xref|^tref$/i
 };
 
 /**

package/test/logger.test.js

@@ -0,0 +1,290 @@
+/**
+ * @file Unit tests for enhanced Logger.error and Logger.warn functionality
+ * 
+ * Tests the new context, hint, and details options for error and warning messages.
+ * Ensures backward compatibility with existing simple message calls.
+ */
+
+const Logger = require('../src/utils/logger');
+const messageCollector = require('../src/utils/message-collector');
+
+// Mock console.log to capture output
+let consoleLogs = [];
+const originalConsoleLog = console.log;
+
+beforeAll(() => {
+    console.log = (...args) => {
+        consoleLogs.push(args);
+    };
+});
+
+afterAll(() => {
+    console.log = originalConsoleLog;
+});
+
+beforeEach(() => {
+    consoleLogs = [];
+    messageCollector.clearMessages();
+});
+
+afterEach(() => {
+    messageCollector.stopCollecting();
+});
+
+describe('Enhanced Logger.error', () => {
+    test('should work with simple message (backward compatibility)', () => {
+        Logger.error('Simple error message');
+
+        expect(consoleLogs.length).toBeGreaterThan(0);
+        expect(consoleLogs[0].join(' ')).toContain('Simple error message');
+    });
+
+    test('should work with message and regular arguments', () => {
+        Logger.error('Error with args', 'arg1', 123);
+
+        expect(consoleLogs.length).toBeGreaterThan(0);
+        const output = consoleLogs[0].join(' ');
+        expect(output).toContain('Error with args');
+        expect(output).toContain('arg1');
+        expect(output).toContain('123');
+    });
+
+    test('should display context when provided', () => {
+        consoleLogs = [];
+        Logger.error('Test error', { context: 'specs.json' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Context:');
+        expect(allOutput).toContain('specs.json');
+    });
+
+    test('should display hint when provided', () => {
+        consoleLogs = [];
+        Logger.error('Test error', { hint: 'Run npm install' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('How to fix:');
+        expect(allOutput).toContain('Run npm install');
+    });
+
+    test('should display details when provided', () => {
+        consoleLogs = [];
+        Logger.error('Test error', { details: 'Error code: 404' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Details:');
+        expect(allOutput).toContain('Error code: 404');
+    });
+
+    test('should handle all options together', () => {
+        consoleLogs = [];
+        Logger.error('Test error', {
+            context: 'Test context',
+            hint: 'Test hint',
+            details: 'Test details'
+        });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Test error');
+        expect(allOutput).toContain('Context:');
+        expect(allOutput).toContain('Test context');
+        expect(allOutput).toContain('How to fix:');
+        expect(allOutput).toContain('Test hint');
+        expect(allOutput).toContain('Details:');
+        expect(allOutput).toContain('Test details');
+    });
+
+    test('should handle regular args mixed with options', () => {
+        consoleLogs = [];
+        Logger.error('Error', 'arg1', 'arg2', { hint: 'Fix it' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Error');
+        expect(allOutput).toContain('arg1');
+        expect(allOutput).toContain('arg2');
+        expect(allOutput).toContain('Fix it');
+    });
+
+    test('should handle object details', () => {
+        consoleLogs = [];
+        Logger.error('Test error', {
+            details: { code: 404, message: 'Not found' }
+        });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('404');
+        expect(allOutput).toContain('Not found');
+    });
+
+    test('should not treat regular object as options', () => {
+        consoleLogs = [];
+        Logger.error('Test error', { someData: 'value' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Test error');
+        // Should treat it as regular argument, not as options
+        // The object will be stringified as [object Object]
+        expect(allOutput).toContain('[object Object]');
+    });
+
+    test('should collect enhanced messages', () => {
+        messageCollector.startCollecting('test');
+
+        Logger.error('Test error', {
+            context: 'test context',
+            hint: 'test hint',
+            details: 'test details'
+        });
+
+        const messages = messageCollector.getMessages();
+        expect(messages).toHaveLength(1);
+        expect(messages[0].type).toBe('error');
+        expect(messages[0].message).toBe('Test error');
+
+        // Should have collected the options
+        const additionalData = messages[0].additionalData;
+        expect(additionalData).toBeDefined();
+        expect(additionalData.length).toBeGreaterThan(0);
+
+        messageCollector.stopCollecting();
+    });
+});
+
+describe('Enhanced Logger.warn', () => {
+    test('should work with simple message (backward compatibility)', () => {
+        Logger.warn('Simple warning message');
+
+        expect(consoleLogs.length).toBeGreaterThan(0);
+        expect(consoleLogs[0].join(' ')).toContain('Simple warning message');
+    });
+
+    test('should work with message and regular arguments', () => {
+        Logger.warn('Warning with args', 'arg1', 123);
+
+        expect(consoleLogs.length).toBeGreaterThan(0);
+        const output = consoleLogs[0].join(' ');
+        expect(output).toContain('Warning with args');
+        expect(output).toContain('arg1');
+        expect(output).toContain('123');
+    });
+
+    test('should display context when provided', () => {
+        consoleLogs = [];
+        Logger.warn('Test warning', { context: 'Configuration file' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Context:');
+        expect(allOutput).toContain('Configuration file');
+    });
+
+    test('should display hint when provided', () => {
+        consoleLogs = [];
+        Logger.warn('Test warning', { hint: 'Consider updating to latest version' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Suggestion:');
+        expect(allOutput).toContain('Consider updating to latest version');
+    });
+
+    test('should display details when provided', () => {
+        consoleLogs = [];
+        Logger.warn('Test warning', { details: 'Using fallback: default' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Details:');
+        expect(allOutput).toContain('Using fallback: default');
+    });
+
+    test('should handle all options together', () => {
+        consoleLogs = [];
+        Logger.warn('Test warning', {
+            context: 'Test context',
+            hint: 'Test suggestion',
+            details: 'Test details'
+        });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Test warning');
+        expect(allOutput).toContain('Context:');
+        expect(allOutput).toContain('Test context');
+        expect(allOutput).toContain('Suggestion:');
+        expect(allOutput).toContain('Test suggestion');
+        expect(allOutput).toContain('Details:');
+        expect(allOutput).toContain('Test details');
+    });
+
+    test('should handle regular args mixed with options', () => {
+        consoleLogs = [];
+        Logger.warn('Warning', 'arg1', 'arg2', { hint: 'Update config' });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Warning');
+        expect(allOutput).toContain('arg1');
+        expect(allOutput).toContain('arg2');
+        expect(allOutput).toContain('Update config');
+    });
+
+    test('should collect enhanced messages', () => {
+        messageCollector.startCollecting('test');
+
+        Logger.warn('Test warning', {
+            context: 'test context',
+            hint: 'test hint',
+            details: 'test details'
+        });
+
+        const messages = messageCollector.getMessages();
+        expect(messages).toHaveLength(1);
+        expect(messages[0].type).toBe('warn');
+        expect(messages[0].message).toBe('Test warning');
+
+        messageCollector.stopCollecting();
+    });
+});
+
+describe('Edge Cases', () => {
+    test('should handle empty options object', () => {
+        consoleLogs = [];
+        Logger.error('Test', {});
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Test');
+        // Should just show the message without extra lines
+    });
+
+    test('should handle null and undefined in options', () => {
+        consoleLogs = [];
+        Logger.error('Test', {
+            context: null,
+            hint: undefined,
+            details: 'valid'
+        });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Test');
+        expect(allOutput).toContain('Details:');
+        expect(allOutput).toContain('valid');
+    });
+
+    test('should handle special characters in options', () => {
+        consoleLogs = [];
+        Logger.error('Test', {
+            hint: 'Fix with: npm run build && npm test'
+        });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('npm run build && npm test');
+    });
+
+    test('should handle multiline strings in options', () => {
+        consoleLogs = [];
+        Logger.error('Test', {
+            details: 'Line 1\nLine 2\nLine 3'
+        });
+
+        const allOutput = consoleLogs.map(log => log.join(' ')).join('\n');
+        expect(allOutput).toContain('Line 1');
+        expect(allOutput).toContain('Line 2');
+        expect(allOutput).toContain('Line 3');
+    });
+});

package/assets/css/insert-trefs.css

@@ -1 +0,0 @@
-/* Currently empty */

package/src/utils/LOGGER.md

@@ -1,81 +0,0 @@
-# Logger Utility
-
-A centralized logging utility for the spec-up-t project that provides consistent, color-coded console output using chalk.
-
-## Features
-
-- **Color-coded messages** for different log levels
-- **Consistent icons** and formatting
-- **Progress indicators** with visual progress bars
-- **Section separators** for organized output
-- **Terminal-friendly** symbols that work across platforms
-
-## Usage
-
-```javascript
-const Logger = require('./src/utils/logger');
-
-// Success messages (green with checkmark)
-Logger.success('Operation completed successfully');
-
-// Error messages (red with X mark)
-Logger.error('Failed to process request');
-
-// Warning messages (yellow with warning symbol)
-Logger.warn('Configuration file not found, using defaults');
-
-// Info messages (blue with info symbol)
-Logger.info('Processing 42 external references');
-
-// Processing status (cyan with arrow)
-Logger.process('Processing repository: owner/repo (15 terms)');
-
-// Highlighted information (magenta with star)
-Logger.highlight('Grouped 42 terms into 6 repositories');
-
-// Progress indicators
-Logger.progress(3, 5, 'Processing terms'); // Shows: [████████████░░░░░░░░] 60% Processing terms
-
-// Section separators
-Logger.separator(); // Shows: ════════════════════════════════════════════════════════════
-```
-
-## Log Levels
-
-| Method | Color | Icon | Purpose |
-|--------|-------|------|---------|
-| `success()` | Green | ✓ | Successful operations |
-| `error()` | Red | ✗ | Errors and failures |
-| `warn()` | Yellow | ⚠ | Warnings and non-critical issues |
-| `info()` | Blue | ℹ | General information |
-| `process()` | Cyan | → | Processing status updates |
-| `highlight()` | Magenta | ★ | Important data/summaries |
-| `debug()` | Gray | ◦ | Debug information |
-
-## Migration from console.log
-
-**Before:**
-```javascript
-console.log(`✅ Successfully processed ${count} items`);
-console.log(`❌ Failed to fetch data from ${url}`);
-console.log(`⚠️ Missing configuration file`);
-```
-
-**After:**
-```javascript
-Logger.success(`Successfully processed ${count} items`);
-Logger.error(`Failed to fetch data from ${url}`);
-Logger.warn('Missing configuration file');
-```
-
-## Dependencies
-
-- `chalk@4` - For terminal colors (CommonJS compatible version)
-
-## Installation
-
-The logger is automatically available when chalk v4 is installed:
-
-```bash
-npm install chalk@4
-```