json-humanized 2.0.0

package/src/formatters/template.js

@@ -0,0 +1,132 @@
+'use strict';
+
+/**
+ * formatters/template.js — render humanized output via a custom Handlebars template.
+ *
+ * Requires: npm install handlebars
+ *
+ * Template variables available:
+ *   {{humanized}}   — the humanized text string
+ *   {{filename}}    — source filename
+ *   {{engine}}      — 'local' or 'ai'
+ *   {{format}}      — chosen output format
+ *   {{timestamp}}   — ISO timestamp
+ *   {{stats.type}}  — 'Object' | 'Array' | 'Primitive'
+ *   {{stats.keys}}  — number of top-level keys (objects)
+ *   {{stats.items}} — number of items (arrays)
+ *
+ * Example template (report.hbs):
+ *   # Report: {{filename}}
+ *   Generated: {{timestamp}}
+ *
+ *   {{humanized}}
+ *
+ *   ---
+ *   Engine: {{engine}} | Keys: {{stats.keys}}
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+function requireHandlebars() {
+  try {
+    return require('handlebars');
+  } catch {
+    throw new Error(
+      'Handlebars is required for template output.\n' +
+      'Install it with: npm install handlebars'
+    );
+  }
+}
+
+/**
+ * Compute basic stats about a parsed JSON value.
+ */
+function computeStats(data) {
+  if (data === null || data === undefined) {
+    return { type: 'Primitive', keys: 0, items: 0 };
+  }
+  if (Array.isArray(data)) {
+    return { type: 'Array', keys: 0, items: data.length };
+  }
+  if (typeof data === 'object') {
+    return { type: 'Object', keys: Object.keys(data).length, items: 0 };
+  }
+  return { type: 'Primitive', keys: 0, items: 0 };
+}
+
+/**
+ * Render using a Handlebars template file.
+ *
+ * @param {string} humanizedText   output from the humanizer / AI engine
+ * @param {string} templatePath    path to a .hbs file
+ * @param {object} context         extra context merged into template vars
+ * @returns {string}               rendered output
+ */
+function renderTemplate(humanizedText, templatePath, context = {}) {
+  const Handlebars = requireHandlebars();
+
+  const absPath = path.resolve(templatePath);
+  if (!fs.existsSync(absPath)) {
+    throw new Error(`Template file not found: ${absPath}`);
+  }
+
+  const source   = fs.readFileSync(absPath, 'utf8');
+  const template = Handlebars.compile(source);
+
+  const vars = {
+    humanized:  humanizedText,
+    filename:   context.filename  || '',
+    engine:     context.engine    || 'local',
+    format:     context.format    || 'plain',
+    timestamp:  new Date().toISOString(),
+    stats:      computeStats(context.data),
+    ...context,
+  };
+
+  return template(vars);
+}
+
+/**
+ * Render using an inline Handlebars template string.
+ *
+ * @param {string} humanizedText
+ * @param {string} templateString  Handlebars template source
+ * @param {object} context
+ * @returns {string}
+ */
+function renderTemplateString(humanizedText, templateString, context = {}) {
+  const Handlebars = requireHandlebars();
+
+  const template = Handlebars.compile(templateString);
+
+  const vars = {
+    humanized:  humanizedText,
+    filename:   context.filename  || '',
+    engine:     context.engine    || 'local',
+    format:     context.format    || 'plain',
+    timestamp:  new Date().toISOString(),
+    stats:      computeStats(context.data),
+    ...context,
+  };
+
+  return template(vars);
+}
+
+/**
+ * Generate an example .hbs template file at the given path.
+ */
+function generateExampleTemplate(outputPath) {
+  const example = `# {{filename}}
+> Generated: {{timestamp}} · Engine: {{engine}}
+
+{{humanized}}
+
+---
+*Stats: {{stats.type}}{{#if stats.keys}}, {{stats.keys}} keys{{/if}}{{#if stats.items}}, {{stats.items}} items{{/if}}*
+`;
+  fs.writeFileSync(outputPath, example, 'utf8');
+  return outputPath;
+}
+
+module.exports = { renderTemplate, renderTemplateString, generateExampleTemplate };

package/src/humanizer.js

@@ -0,0 +1,307 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  json-humanized · Rule-based humanization engine
+//  Works 100% offline, no API key needed
+// ─────────────────────────────────────────────────────────────────────────────
+
+const TYPE_LABELS = {
+  string:  'text value',
+  number:  'number',
+  boolean: 'flag',
+  object:  'object',
+  array:   'list',
+  null:    'empty value',
+};
+
+/**
+ * Detect semantic meaning from a key name
+ */
+function detectKeyContext(key) {
+  const k = key.toLowerCase();
+
+  if (/^(id|uuid|guid|_id)$/.test(k))          return 'identifier';
+  if (/(_id|Id)$/.test(key))                    return 'reference';
+  if (/(created|updated|modified|timestamp|date|time|at)$/i.test(k)) return 'datetime';
+  if (/(email|mail)$/i.test(k))                 return 'email';
+  if (/(url|uri|href|link|website)$/i.test(k))  return 'url';
+  if (/(phone|tel|mobile|fax)$/i.test(k))       return 'phone';
+  if (/(price|cost|amount|salary|wage|fee|balance)/i.test(k)) return 'money';
+  if (/(count|qty|quantity|num|total|sum|size|length)/i.test(k)) return 'count';
+  if (/(lat|latitude)/i.test(k))                return 'latitude';
+  if (/(lon|lng|longitude)/i.test(k))           return 'longitude';
+  if (/(password|secret|token|key|hash)/i.test(k)) return 'sensitive';
+  if (/(name|title|label|heading|subject)/i.test(k)) return 'name';
+  if (/(desc|description|about|bio|summary|notes|comment|text|body|content)/i.test(k)) return 'description';
+  if (/(status|state|phase|stage)/i.test(k))    return 'status';
+  if (/(type|kind|category|group|tag|class)/i.test(k)) return 'category';
+  if (/(enabled|active|visible|public|is_|has_)/i.test(k)) return 'boolean-flag';
+  if (/(^age$|_age$|^age_)/i.test(k))           return 'age';
+  if (/(version|ver)/i.test(k))                 return 'version';
+  if (/(color|colour)/i.test(k))                return 'color';
+  if (/(address|city|country|region|zip|postal)/i.test(k)) return 'location';
+  if (/(rating|score|rank)/i.test(k))           return 'rating';
+  if (/(error|err|exception|message|msg)/i.test(k)) return 'error';
+
+  return 'generic';
+}
+
+/**
+ * Format a key name into natural English label
+ */
+function humanizeKey(key) {
+  return key
+    .replace(/([A-Z])/g, ' $1')          // camelCase → spaced
+    .replace(/[_\-\.]+/g, ' ')           // snake_case / kebab-case → spaced
+    .replace(/\s+/g, ' ')
+    .trim()
+    .toLowerCase();
+}
+
+/**
+ * Format a value with contextual awareness
+ */
+function humanizeValue(value, key = '', depth = 0) {
+  if (value === null || value === undefined) return 'not specified';
+  if (value === '') return 'empty';
+
+  const ctx = detectKeyContext(key);
+  const type = typeof value;
+
+  if (type === 'boolean') {
+    if (ctx === 'boolean-flag') {
+      const label = humanizeKey(key);
+      return value ? `yes (${label} is active)` : `no (${label} is inactive)`;
+    }
+    return value ? 'yes' : 'no';
+  }
+
+  if (type === 'number') {
+    if (ctx === 'money')    return formatMoney(value);
+    if (ctx === 'count')    return `${value.toLocaleString()} item${value !== 1 ? 's' : ''}`;
+    if (ctx === 'rating')   return `${value} out of 10`;
+    if (ctx === 'age')      return `${value} year${value !== 1 ? 's' : ''} old`;
+    if (ctx === 'latitude') return `${Math.abs(value)}° ${value >= 0 ? 'N' : 'S'}`;
+    if (ctx === 'longitude')return `${Math.abs(value)}° ${value >= 0 ? 'E' : 'W'}`;
+    return value.toLocaleString();
+  }
+
+  if (type === 'string') {
+    if (ctx === 'sensitive') return '*** (hidden for security)';
+    if (ctx === 'datetime')  return formatDatetime(value);
+    if (ctx === 'email')     return `email address: ${value}`;
+    if (ctx === 'url')       return `link: ${value}`;
+    if (ctx === 'phone')     return `phone: ${value}`;
+    if (ctx === 'color')     return `color ${value}`;
+    if (ctx === 'version')   return `version ${value}`;
+    if (value.length > 200)  return `${value.slice(0, 200)}… (truncated, ${value.length} characters total)`;
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return humanizeArray(value, key, depth);
+  }
+
+  if (type === 'object') {
+    return humanizeObject(value, depth + 1);
+  }
+
+  return String(value);
+}
+
+function formatMoney(n) {
+  if (n >= 1_000_000) return `$${(n / 1_000_000).toFixed(2)}M`;
+  if (n >= 1_000)     return `$${(n / 1_000).toFixed(1)}K`;
+  return `$${n.toFixed(2)}`;
+}
+
+function formatDatetime(str) {
+  try {
+    const d = new Date(str);
+    if (isNaN(d.getTime())) return str;
+    return d.toLocaleString('en-US', {
+      year: 'numeric', month: 'long', day: 'numeric',
+      hour: '2-digit', minute: '2-digit',
+    });
+  } catch {
+    return str;
+  }
+}
+
+/**
+ * Humanize an array value
+ */
+function humanizeArray(arr, key = '', depth = 0) {
+  if (arr.length === 0) return 'an empty list';
+
+  const itemType = typeof arr[0];
+  const allSameType = arr.every(i => typeof i === itemType);
+  const label = humanizeKey(key) || 'items';
+
+  // Simple scalar arrays → inline sentence
+  if (allSameType && ['string', 'number', 'boolean'].includes(itemType) && arr.length <= 8) {
+    const formatted = arr.map(v => humanizeValue(v, '', depth));
+    if (formatted.length === 1) return formatted[0];
+    const last = formatted.pop();
+    return `${formatted.join(', ')} and ${last}`;
+  }
+
+  // Complex arrays → count + describe first element
+  const preview = humanizeValue(arr[0], '', depth + 1);
+  return `a collection of ${arr.length} ${label} (e.g. ${preview}${arr.length > 1 ? ', and more' : ''})`;
+}
+
+/**
+ * Humanize an object recursively, returns array of sentences
+ */
+function humanizeObject(obj, depth = 0) {
+  const entries = Object.entries(obj).filter(([, v]) => v !== undefined);
+  if (entries.length === 0) return 'an empty object';
+
+  const sentences = [];
+  const indent = '  '.repeat(depth);
+
+  for (const [key, value] of entries) {
+    const label = humanizeKey(key);
+    const ctx   = detectKeyContext(key);
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        sentences.push(`${indent}• ${capitalize(label)}: none`);
+      } else if (isScalarArray(value)) {
+        sentences.push(`${indent}• ${capitalize(label)}: ${humanizeArray(value, key, depth)}`);
+      } else {
+        sentences.push(`${indent}• ${capitalize(label)}: ${value.length} entr${value.length === 1 ? 'y' : 'ies'}`);
+        value.slice(0, 5).forEach((item, i) => {
+          if (typeof item === 'object' && item !== null) {
+            const sub = humanizeObject(item, depth + 1);
+            sentences.push(`${indent}  [${i + 1}] ${sub}`);
+          } else {
+            sentences.push(`${indent}  [${i + 1}] ${humanizeValue(item, '', depth + 1)}`);
+          }
+        });
+        if (value.length > 5) {
+          sentences.push(`${indent}  … and ${value.length - 5} more`);
+        }
+      }
+    } else if (typeof value === 'object' && value !== null) {
+      sentences.push(`${indent}• ${capitalize(label)}:`);
+      const sub = humanizeObject(value, depth + 1);
+      sentences.push(sub);
+    } else {
+      const hval = humanizeValue(value, key, depth);
+      if (ctx === 'identifier') {
+        sentences.push(`${indent}• Identifier: ${hval}`);
+      } else if (ctx === 'description') {
+        sentences.push(`${indent}• ${capitalize(label)}: "${hval}"`);
+      } else {
+        sentences.push(`${indent}• ${capitalize(label)}: ${hval}`);
+      }
+    }
+  }
+
+  return sentences.join('\n');
+}
+
+function isScalarArray(arr) {
+  return arr.every(i => typeof i !== 'object' || i === null);
+}
+
+function capitalize(str) {
+  if (!str) return '';
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  Top-level entry point
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Detect what kind of structure this JSON represents
+ */
+function detectTopLevelShape(data) {
+  if (Array.isArray(data)) {
+    if (data.length === 0) return { shape: 'empty-array' };
+    const first = data[0];
+    if (typeof first === 'object' && first !== null) return { shape: 'record-list', count: data.length };
+    return { shape: 'scalar-list', count: data.length };
+  }
+  if (typeof data === 'object' && data !== null) {
+    const keys = Object.keys(data);
+    // Detect common API shapes
+    if ('data' in data && ('meta' in data || 'links' in data || 'pagination' in data)) return { shape: 'api-response' };
+    if ('error' in data || 'errors' in data || 'message' in data && 'code' in data) return { shape: 'error-response' };
+    if ('users' in data || 'items' in data || 'results' in data || 'records' in data) return { shape: 'collection' };
+    if (keys.length <= 2) return { shape: 'simple-object' };
+    return { shape: 'complex-object', keys: keys.length };
+  }
+  return { shape: 'primitive' };
+}
+
+/**
+ * Build a natural-language introduction for the top-level shape
+ */
+function buildIntro(data, shape) {
+  switch (shape.shape) {
+    case 'empty-array':
+      return 'This JSON contains an empty list with no items.';
+    case 'record-list':
+      return `This JSON contains a list of ${shape.count} record${shape.count !== 1 ? 's' : ''}.`;
+    case 'scalar-list':
+      return `This JSON contains a list of ${shape.count} value${shape.count !== 1 ? 's' : ''}.`;
+    case 'api-response':
+      return 'This JSON is an API response with data and metadata.';
+    case 'error-response':
+      return 'This JSON describes an error or failure response.';
+    case 'collection':
+      return 'This JSON contains a collection of resources.';
+    case 'simple-object':
+      return 'This JSON contains a simple object with a few fields.';
+    case 'complex-object':
+      return `This JSON contains a structured object with ${shape.keys} fields.`;
+    case 'primitive':
+      return `This JSON contains a single value: ${String(data)}.`;
+    default:
+      return 'This JSON contains the following data:';
+  }
+}
+
+/**
+ * Generate a human-readable summary using the rule-based engine
+ */
+function humanizeLocal(data, options = {}) {
+  const { mode = 'structured', maxDepth = 10 } = options;
+  const shape = detectTopLevelShape(data);
+  const intro = buildIntro(data, shape);
+
+  if (shape.shape === 'primitive') {
+    return intro;
+  }
+
+  let body = '';
+
+  if (Array.isArray(data)) {
+    if (isScalarArray(data)) {
+      body = `\nValues: ${humanizeArray(data, 'items', 0)}`;
+    } else {
+      const lines = [];
+      const limit = Math.min(data.length, 20);
+      for (let i = 0; i < limit; i++) {
+        const item = data[i];
+        if (typeof item === 'object' && item !== null) {
+          lines.push(`\nRecord ${i + 1}:\n${humanizeObject(item, 1)}`);
+        } else {
+          lines.push(`\nItem ${i + 1}: ${humanizeValue(item)}`);
+        }
+      }
+      if (data.length > 20) lines.push(`\n… and ${data.length - 20} more records`);
+      body = lines.join('');
+    }
+  } else {
+    body = '\n' + humanizeObject(data, 0);
+  }
+
+  return `${intro}\n${body}`;
+}
+
+module.exports = { humanizeLocal, humanizeKey, humanizeValue, detectKeyContext };

package/src/index.js

@@ -0,0 +1,157 @@
+'use strict';
+
+// ─────────────────────────────────────────────────────────────────────────────
+//  json-humanized · Main public API  (v2.0)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const fs   = require('fs');
+const path = require('path');
+
+const { humanizeLocal }  = require('./humanizer');
+const { humanizeWithAI } = require('./strategies/ai');
+const { applyFormat }    = require('./formatters');
+const { withCache }      = require('./cache');
+const { loadConfig }     = require('./config');
+const { parseAny, parseFile } = require('./parsers');
+
+// ─── stats helper ────────────────────────────────────────────────────────────
+
+function computeStats(data) {
+  const stats = {};
+  if (Array.isArray(data)) {
+    stats['Type'] = 'Array';
+    stats['Total items'] = data.length;
+    if (data.length > 0 && typeof data[0] === 'object') {
+      stats['Keys per record'] = Object.keys(data[0] || {}).length;
+    }
+  } else if (typeof data === 'object' && data !== null) {
+    stats['Type'] = 'Object';
+    stats['Top-level keys'] = Object.keys(data).length;
+    const nested = Object.values(data).filter(v => typeof v === 'object' && v !== null).length;
+    if (nested > 0) stats['Nested objects'] = nested;
+  } else {
+    stats['Type'] = typeof data;
+    stats['Value'] = String(data).slice(0, 50);
+  }
+  return stats;
+}
+
+// ─── core humanize ───────────────────────────────────────────────────────────
+
+/**
+ * Core humanize function — works on already-parsed data.
+ *
+ * @param {any}    data
+ * @param {object} [options]
+ * @param {'local'|'ai'}            [options.engine='local']
+ * @param {'anthropic'|'openai'|'ollama'} [options.aiProvider='anthropic']
+ * @param {string}                  [options.apiKey]
+ * @param {'plain'|'markdown'|'story'|'json'} [options.format='plain']
+ * @param {'prose'|'structured'|'story'} [options.mode='structured']
+ * @param {string}                  [options.lang='English']
+ * @param {string}                  [options.context='']
+ * @param {string}                  [options.filename='']
+ * @param {number}                  [options.maxChars=12000]
+ * @param {string}                  [options.template]  path to .hbs template
+ * @param {boolean}                 [options.cache=true]
+ * @param {number}                  [options.cacheTTL=3600]
+ * @param {string}                  [options.configPath]  explicit config file
+ * @returns {Promise<string>}
+ */
+async function humanize(data, options = {}) {
+  // Merge config file options (if any) — CLI/API options take precedence
+  const { config } = loadConfig(options.configPath);
+  const merged = { ...config, ...options };
+
+  const {
+    engine     = 'local',
+    aiProvider = 'anthropic',
+    apiKey     = process.env.ANTHROPIC_API_KEY,
+    format     = 'plain',
+    mode       = 'structured',
+    lang       = 'English',
+    context    = '',
+    filename   = '',
+    maxChars   = 12000,
+    template,
+    cache      = true,
+    cacheTTL   = 3600,
+  } = merged;
+
+  const engineFn = async () => {
+    if (engine === 'ai') {
+      return humanizeWithAI(data, { apiKey, aiProvider, mode, lang, context, maxChars, ...merged });
+    }
+    return humanizeLocal(data, { mode });
+  };
+
+  // Use cache only for AI engine (local is instant)
+  const text = engine === 'ai'
+    ? await withCache(data, { engine, aiProvider, format, lang, context, cacheTTL }, engineFn, cache)
+    : await engineFn();
+
+  const stats = computeStats(data);
+  const meta  = { engine, aiProvider, filename, timestamp: new Date().toISOString(), stats, data };
+
+  // Template output takes priority over standard formatters
+  if (template) {
+    const { renderTemplate } = require('./formatters/template');
+    return renderTemplate(text, template, meta);
+  }
+
+  return applyFormat(text, format, meta);
+}
+
+// ─── file humanizer ──────────────────────────────────────────────────────────
+
+/**
+ * Humanize a JSON/YAML/TOML file from disk.
+ *
+ * @param {string} filePath
+ * @param {object} [options]  same as humanize()
+ */
+async function humanizeFile(filePath, options = {}) {
+  const resolved = path.resolve(filePath);
+
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`File not found: ${resolved}`);
+  }
+
+  const data = parseFile(resolved);
+
+  return humanize(data, {
+    ...options,
+    filename: options.filename || path.basename(resolved),
+  });
+}
+
+// ─── string humanizer ────────────────────────────────────────────────────────
+
+/**
+ * Humanize a raw JSON/YAML/TOML string.
+ *
+ * @param {string} rawString
+ * @param {object} [options]
+ */
+async function humanizeString(rawString, options = {}) {
+  let data;
+  try {
+    data = parseAny(rawString, options.filename || '');
+  } catch (err) {
+    throw new Error(`Invalid input: ${err.message}`);
+  }
+  return humanize(data, options);
+}
+
+// ─── exports ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  humanize,
+  humanizeFile,
+  humanizeString,
+  // Re-export sub-modules for power users
+  diff:   require('./diff'),
+  cache:  require('./cache'),
+  config: require('./config'),
+  watch:  require('./watch'),
+};