json-humanized 2.0.0

package/src/config.js

@@ -0,0 +1,259 @@
+'use strict';
+
+/**
+ * config.js — load and merge .jh.config.json for custom rules, field mappings,
+ * default engine, format, and more.
+ *
+ * Config file is searched upward from cwd (like ESLint / Prettier).
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── defaults ────────────────────────────────────────────────────────────────
+
+const DEFAULTS = {
+  engine:   'local',
+  format:   'plain',
+  lang:     'English',
+  maxChars: 12000,
+  context:  '',
+
+  /**
+   * Custom field label overrides.
+   * Key: exact JSON field name (or glob pattern).
+   * Value: human-readable label (or null to hide the field).
+   *
+   * Example:
+   *   "fieldLabels": {
+   *     "usr_id":       "User ID",
+   *     "txn_ref":      "Transaction reference",
+   *     "internal_*":   null
+   *   }
+   */
+  fieldLabels: {},
+
+  /**
+   * Custom field type overrides.
+   * Possible types: email, date, money, phone, url, id, boolean,
+   *                 sensitive, coordinates, count, age, rating, text
+   *
+   * Example:
+   *   "fieldTypes": {
+   *     "invoice_no": "id",
+   *     "balance":    "money"
+   *   }
+   */
+  fieldTypes: {},
+
+  /**
+   * Fields to always hide (treated as sensitive).
+   * Example: ["internal_token", "debug_*"]
+   */
+  hiddenFields: [],
+
+  /**
+   * Template file path (Handlebars .hbs) for custom output.
+   * Relative to the config file location.
+   */
+  template: null,
+
+  /**
+   * AI provider: 'anthropic' | 'openai' | 'ollama'
+   */
+  aiProvider: 'anthropic',
+
+  /**
+   * Ollama base URL (only used when aiProvider = 'ollama')
+   */
+  ollamaUrl: 'http://localhost:11434',
+
+  /**
+   * Ollama model name
+   */
+  ollamaModel: 'llama3',
+
+  /**
+   * OpenAI model (only used when aiProvider = 'openai')
+   */
+  openaiModel: 'gpt-4o-mini',
+
+  /**
+   * Enable AI response caching (saves API calls for identical JSON)
+   */
+  cache: true,
+
+  /**
+   * Cache TTL in seconds (default 1 hour)
+   */
+  cacheTTL: 3600,
+};
+
+// ─── config file names ───────────────────────────────────────────────────────
+
+const CONFIG_FILES = [
+  '.jh.config.json',
+  '.jhrc.json',
+  'jh.config.json',
+];
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+/**
+ * Walk up directory tree looking for config file.
+ */
+function findConfigFile(startDir = process.cwd()) {
+  let dir = path.resolve(startDir);
+
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    for (const name of CONFIG_FILES) {
+      const candidate = path.join(dir, name);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+
+  return null;
+}
+
+/**
+ * Deep-merge two plain objects (right wins).
+ */
+function mergeDeep(target, source) {
+  const result = Object.assign({}, target);
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] !== null &&
+      typeof source[key] === 'object' &&
+      !Array.isArray(source[key]) &&
+      typeof target[key] === 'object' &&
+      target[key] !== null
+    ) {
+      result[key] = mergeDeep(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+// ─── glob-style pattern matching (simple: only * wildcard) ──────────────────
+
+function matchPattern(pattern, key) {
+  if (!pattern.includes('*')) return pattern === key;
+  const re = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+  return re.test(key);
+}
+
+// ─── public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Load config from disk and merge with defaults.
+ * @param {string} [configPath]  explicit path; if omitted, auto-detected.
+ * @returns {{ config: object, configPath: string|null }}
+ */
+function loadConfig(configPath) {
+  const filePath = configPath || findConfigFile();
+
+  if (!filePath) {
+    return { config: Object.assign({}, DEFAULTS), configPath: null };
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Failed to parse config file ${filePath}: ${err.message}`);
+  }
+
+  const config = mergeDeep(DEFAULTS, raw);
+
+  // Resolve template path relative to config file
+  if (config.template) {
+    config.template = path.resolve(path.dirname(filePath), config.template);
+  }
+
+  return { config, configPath: filePath };
+}
+
+/**
+ * Resolve a human-readable label for a JSON key.
+ * Uses fieldLabels from config; falls back to built-in camelCase/snake_case split.
+ *
+ * @param {string} key
+ * @param {object} fieldLabels  from config
+ * @returns {string|null}  null = hide this field
+ */
+function resolveLabel(key, fieldLabels = {}) {
+  for (const pattern of Object.keys(fieldLabels)) {
+    if (matchPattern(pattern, key)) {
+      return fieldLabels[pattern]; // may be null (= hide)
+    }
+  }
+  return null; // no override
+}
+
+/**
+ * Resolve a semantic field type override.
+ * @param {string} key
+ * @param {object} fieldTypes  from config
+ * @returns {string|null}
+ */
+function resolveType(key, fieldTypes = {}) {
+  for (const pattern of Object.keys(fieldTypes)) {
+    if (matchPattern(pattern, key)) {
+      return fieldTypes[pattern];
+    }
+  }
+  return null;
+}
+
+/**
+ * Check if a field should be hidden.
+ * @param {string} key
+ * @param {string[]} hiddenFields  from config
+ * @returns {boolean}
+ */
+function isHidden(key, hiddenFields = []) {
+  return hiddenFields.some(pattern => matchPattern(pattern, key));
+}
+
+/**
+ * Generate a minimal example config file content.
+ * @returns {string}  JSON string
+ */
+function generateExampleConfig() {
+  const example = {
+    engine:  'local',
+    format:  'plain',
+    lang:    'English',
+    maxChars: 12000,
+    cache:   true,
+    fieldLabels: {
+      'user_id':    'User ID',
+      'txn_ref':    'Transaction reference',
+      'internal_*': null,
+    },
+    fieldTypes: {
+      'invoice_no': 'id',
+      'balance':    'money',
+      'created':    'date',
+    },
+    hiddenFields: ['debug_*', 'internal_hash'],
+    aiProvider: 'anthropic',
+  };
+  return JSON.stringify(example, null, 2);
+}
+
+module.exports = {
+  DEFAULTS,
+  loadConfig,
+  resolveLabel,
+  resolveType,
+  isHidden,
+  generateExampleConfig,
+};

package/src/diff.js

@@ -0,0 +1,284 @@
+'use strict';
+
+/**
+ * diff.js — compare two JSON values and describe changes in human language.
+ * Works with both local rule-based and AI engines.
+ */
+
+const { humanize } = require('./index');
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function typeLabel(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+}
+
+function friendlyKey(key) {
+  return key
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/[_-]+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+function formatValue(v) {
+  if (v === null) return 'null';
+  if (typeof v === 'boolean') return v ? 'yes' : 'no';
+  if (typeof v === 'number') return String(v);
+  if (typeof v === 'string') return `"${v}"`;
+  if (Array.isArray(v)) return `[array with ${v.length} item(s)]`;
+  if (typeof v === 'object') return `{object with ${Object.keys(v).length} key(s)}`;
+  return String(v);
+}
+
+// ─── core diff logic ─────────────────────────────────────────────────────────
+
+function diffObjects(a, b, path = '') {
+  const changes = [];
+  const allKeys = new Set([...Object.keys(a), ...Object.keys(b)]);
+
+  for (const key of allKeys) {
+    const fullPath = path ? `${path}.${key}` : key;
+    const label = friendlyKey(key);
+
+    if (!(key in a)) {
+      changes.push({ type: 'added', path: fullPath, label, value: b[key] });
+    } else if (!(key in b)) {
+      changes.push({ type: 'removed', path: fullPath, label, value: a[key] });
+    } else if (
+      typeof a[key] === 'object' && a[key] !== null &&
+      typeof b[key] === 'object' && b[key] !== null &&
+      !Array.isArray(a[key]) && !Array.isArray(b[key])
+    ) {
+      const nested = diffObjects(a[key], b[key], fullPath);
+      changes.push(...nested);
+    } else if (JSON.stringify(a[key]) !== JSON.stringify(b[key])) {
+      changes.push({
+        type: 'changed',
+        path: fullPath,
+        label,
+        from: a[key],
+        to: b[key],
+      });
+    }
+  }
+
+  return changes;
+}
+
+function diffArrays(a, b) {
+  const changes = [];
+  const maxLen = Math.max(a.length, b.length);
+
+  for (let i = 0; i < maxLen; i++) {
+    if (i >= b.length) {
+      changes.push({ type: 'removed', path: `[${i}]`, label: `item ${i + 1}`, value: a[i] });
+    } else if (i >= a.length) {
+      changes.push({ type: 'added', path: `[${i}]`, label: `item ${i + 1}`, value: b[i] });
+    } else if (JSON.stringify(a[i]) !== JSON.stringify(b[i])) {
+      changes.push({ type: 'changed', path: `[${i}]`, label: `item ${i + 1}`, from: a[i], to: b[i] });
+    }
+  }
+
+  return changes;
+}
+
+function collectChanges(a, b) {
+  const ta = typeLabel(a);
+  const tb = typeLabel(b);
+
+  if (ta !== tb) {
+    return [{ type: 'type_changed', from: ta, to: tb, fromValue: a, toValue: b }];
+  }
+
+  if (ta === 'object') return diffObjects(a, b);
+  if (ta === 'array') return diffArrays(a, b);
+
+  if (JSON.stringify(a) !== JSON.stringify(b)) {
+    return [{ type: 'changed', path: 'root', label: 'value', from: a, to: b }];
+  }
+
+  return [];
+}
+
+// ─── render changes to text ──────────────────────────────────────────────────
+
+function renderChanges(changes, format = 'plain') {
+  if (changes.length === 0) {
+    return format === 'markdown'
+      ? '## ✅ No differences\n\nThe two JSON values are **identical**.'
+      : '✅ No differences — the two JSON values are identical.';
+  }
+
+  const added   = changes.filter(c => c.type === 'added');
+  const removed = changes.filter(c => c.type === 'removed');
+  const changed = changes.filter(c => c.type === 'changed');
+  const typeChg = changes.filter(c => c.type === 'type_changed');
+
+  const lines = [];
+
+  if (format === 'markdown') {
+    lines.push(`## 🔀 JSON Diff — ${changes.length} change(s) found\n`);
+
+    if (typeChg.length) {
+      lines.push(`### ⚠️ Type changed`);
+      for (const c of typeChg) {
+        lines.push(`- Root type changed from **${c.from}** to **${c.to}**`);
+      }
+      lines.push('');
+    }
+
+    if (added.length) {
+      lines.push(`### ➕ Added (${added.length})`);
+      for (const c of added) {
+        lines.push(`- **${c.label}** \`${c.path}\` was added with value ${formatValue(c.value)}`);
+      }
+      lines.push('');
+    }
+
+    if (removed.length) {
+      lines.push(`### ➖ Removed (${removed.length})`);
+      for (const c of removed) {
+        lines.push(`- **${c.label}** \`${c.path}\` was removed (was ${formatValue(c.value)})`);
+      }
+      lines.push('');
+    }
+
+    if (changed.length) {
+      lines.push(`### ✏️ Changed (${changed.length})`);
+      for (const c of changed) {
+        lines.push(`- **${c.label}** \`${c.path}\`: ${formatValue(c.from)} → ${formatValue(c.to)}`);
+      }
+      lines.push('');
+    }
+  } else {
+    lines.push(`Found ${changes.length} difference(s):\n`);
+
+    if (typeChg.length) {
+      for (const c of typeChg) {
+        lines.push(`⚠  Root type changed: ${c.from} → ${c.to}`);
+      }
+    }
+
+    if (added.length) {
+      lines.push(`\n➕ Added (${added.length}):`);
+      for (const c of added) {
+        lines.push(`   + ${c.label} (${c.path}): ${formatValue(c.value)}`);
+      }
+    }
+
+    if (removed.length) {
+      lines.push(`\n➖ Removed (${removed.length}):`);
+      for (const c of removed) {
+        lines.push(`   - ${c.label} (${c.path}): was ${formatValue(c.value)}`);
+      }
+    }
+
+    if (changed.length) {
+      lines.push(`\n✏  Changed (${changed.length}):`);
+      for (const c of changed) {
+        lines.push(`   ~ ${c.label} (${c.path}): ${formatValue(c.from)} → ${formatValue(c.to)}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── AI-powered diff ─────────────────────────────────────────────────────────
+
+async function diffWithAI(a, b, options = {}) {
+  const { apiKey, lang = 'English', context = '' } = options;
+
+  const key = apiKey || process.env.ANTHROPIC_API_KEY;
+  if (!key) throw new Error('ANTHROPIC_API_KEY is required for AI diff mode');
+
+  let sdk;
+  try {
+    sdk = require('@anthropic-ai/sdk');
+  } catch {
+    throw new Error('Install @anthropic-ai/sdk: npm install @anthropic-ai/sdk');
+  }
+
+  const client = new sdk.Anthropic({ apiKey: key });
+
+  const prompt = [
+    context ? `Context: ${context}\n` : '',
+    'You are a JSON diff analyst. Compare these two JSON values and describe all differences in plain, natural language.',
+    `Respond in ${lang}.`,
+    'Be concise but thorough. Group changes by: added fields, removed fields, changed values.',
+    '',
+    'BEFORE:',
+    JSON.stringify(a, null, 2).slice(0, 6000),
+    '',
+    'AFTER:',
+    JSON.stringify(b, null, 2).slice(0, 6000),
+  ].filter(Boolean).join('\n');
+
+  const response = await client.messages.create({
+    model: 'claude-opus-4-5',
+    max_tokens: 1024,
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  return response.content.map(b => b.text || '').join('');
+}
+
+// ─── public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Diff two JavaScript values and return a human-readable description.
+ *
+ * @param {*} a       - "before" value
+ * @param {*} b       - "after" value
+ * @param {object} options
+ * @param {'local'|'ai'} [options.engine='local']
+ * @param {'plain'|'markdown'|'json'} [options.format='plain']
+ * @param {string} [options.lang='English']   (AI only)
+ * @param {string} [options.context='']       (AI only)
+ * @param {string} [options.apiKey]
+ * @returns {Promise<string>}
+ */
+async function diff(a, b, options = {}) {
+  const { engine = 'local', format = 'plain' } = options;
+
+  if (engine === 'ai') {
+    return diffWithAI(a, b, options);
+  }
+
+  const changes = collectChanges(a, b);
+
+  if (format === 'json') {
+    return JSON.stringify({
+      changes,
+      summary: {
+        total: changes.length,
+        added:   changes.filter(c => c.type === 'added').length,
+        removed: changes.filter(c => c.type === 'removed').length,
+        changed: changes.filter(c => c.type === 'changed').length,
+      },
+    }, null, 2);
+  }
+
+  return renderChanges(changes, format);
+}
+
+/**
+ * Diff two JSON files.
+ */
+async function diffFiles(fileA, fileB, options = {}) {
+  const fs = require('fs');
+  const { parseAny } = require('./parsers');
+
+  const rawA = fs.readFileSync(fileA, 'utf8');
+  const rawB = fs.readFileSync(fileB, 'utf8');
+
+  const a = parseAny(rawA, fileA);
+  const b = parseAny(rawB, fileB);
+
+  return diff(a, b, options);
+}
+
+module.exports = { diff, diffFiles };

package/src/formatters/index.js

@@ -0,0 +1,113 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  json-humanized · Output formatters
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Plain text formatter (default)
+ */
+function formatPlain(text, meta = {}) {
+  const lines = [];
+  if (meta.filename) {
+    lines.push(`File: ${meta.filename}`);
+    lines.push('─'.repeat(50));
+  }
+  lines.push(text);
+  if (meta.engine) {
+    lines.push('');
+    lines.push(`[Processed by: ${meta.engine}]`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Markdown formatter
+ */
+function formatMarkdown(text, meta = {}) {
+  const lines = [];
+
+  if (meta.filename) {
+    lines.push(`# JSON Analysis: \`${meta.filename}\``);
+    lines.push('');
+  } else {
+    lines.push('# JSON Analysis');
+    lines.push('');
+  }
+
+  if (meta.timestamp) {
+    lines.push(`> Generated on ${new Date(meta.timestamp).toLocaleString()}`);
+    lines.push('');
+  }
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(text);
+  lines.push('');
+
+  if (meta.stats) {
+    lines.push('## Metadata');
+    lines.push('');
+    lines.push(`| Field | Value |`);
+    lines.push(`|-------|-------|`);
+    for (const [k, v] of Object.entries(meta.stats)) {
+      lines.push(`| ${k} | ${v} |`);
+    }
+    lines.push('');
+  }
+
+  if (meta.engine) {
+    lines.push(`---`);
+    lines.push(`*Processed by json-humanized (${meta.engine} engine)*`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Story/narrative formatter — wraps output in a storytelling frame
+ */
+function formatStory(text, meta = {}) {
+  const lines = [];
+  lines.push('━'.repeat(60));
+  lines.push('  📖  THE DATA STORY');
+  lines.push('━'.repeat(60));
+  lines.push('');
+  lines.push(text);
+  lines.push('');
+  lines.push('━'.repeat(60));
+  if (meta.filename) {
+    lines.push(`  Source: ${meta.filename}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * JSON formatter — outputs structured metadata alongside the description
+ */
+function formatJSON(text, meta = {}) {
+  const output = {
+    humanized: text,
+    metadata: {
+      engine: meta.engine || 'local',
+      filename: meta.filename || null,
+      timestamp: meta.timestamp || new Date().toISOString(),
+      stats: meta.stats || {},
+    },
+  };
+  return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Apply a named formatter
+ */
+function applyFormat(text, format = 'plain', meta = {}) {
+  switch (format) {
+    case 'markdown': return formatMarkdown(text, meta);
+    case 'story':    return formatStory(text, meta);
+    case 'json':     return formatJSON(text, meta);
+    default:         return formatPlain(text, meta);
+  }
+}
+
+module.exports = { applyFormat, formatPlain, formatMarkdown, formatStory, formatJSON };