@khanhcan148/mk 0.1.21 → 0.1.22

package/src/lib/toml-emit.js

@@ -0,0 +1,219 @@
+/**
+ * toml-emit.js — Inline TOML serialiser (no @iarna/toml runtime dependency).
+ *
+ * Scope: top-level table + array-of-tables ([[key]]) + string + boolean + number.
+ * Does NOT support inline arrays of mixed types or nested tables beyond
+ * array-of-tables — throws a TypeError for unsupported shapes.
+ *
+ * Hard constraints met:
+ *   HC #2: no @iarna/toml runtime import.
+ *   HC #4: in-table key order = matcher first, command second, remaining lex-sorted.
+ *          Array-of-tables blocks sorted by (matcher, command) lex.
+ *           Always uses Array.from(...).sort() — never raw Object.keys iteration.
+ *
+ * @iarna/toml remains a devDep used ONLY in test round-trip assertions.
+ */
+
+/**
+ * Escape a raw string value to a TOML basic-string literal (without wrapping quotes).
+ * Handles TOML 1.0 required escapes: \\ \" \b \f \n \r \t \uXXXX for control chars.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeString(s) {
+  let out = '';
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    const cp = s.charCodeAt(i);
+    if (ch === '\\') { out += '\\\\'; }
+    else if (ch === '"') { out += '\\"'; }
+    else if (ch === '\b') { out += '\\b'; }
+    else if (ch === '\f') { out += '\\f'; }
+    else if (ch === '\n') { out += '\\n'; }
+    else if (ch === '\r') { out += '\\r'; }
+    else if (ch === '\t') { out += '\\t'; }
+    else if (cp < 0x20 || cp === 0x7f) {
+      out += '\\u' + cp.toString(16).padStart(4, '0');
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+/**
+ * Emit a scalar value as a TOML RHS token.
+ *
+ * @param {string|boolean|number|null|undefined} val
+ * @returns {string}
+ */
+export function emitScalar(val) {
+  if (val === null || val === undefined) {
+    throw new TypeError(`[toml-emit] null/undefined is not a valid TOML scalar`);
+  }
+  if (typeof val === 'boolean') return val ? 'true' : 'false';
+  if (typeof val === 'number') return String(val);
+  if (typeof val === 'string') return `"${escapeString(val)}"`;
+  throw new TypeError(`[toml-emit] Unsupported scalar type: ${typeof val} (${String(val)})`);
+}
+
+/**
+ * Sort keys in the canonical order:
+ *   1. matcher (first)
+ *   2. command (second)
+ *   3. all other keys, lexicographically sorted
+ *
+ * @param {string[]} keys
+ * @returns {string[]}
+ */
+function sortKeys(keys) {
+  const filtered = Array.from(keys).filter(k => k !== '__leadingComments');
+  const priority = ['matcher', 'command'];
+  const fixed = priority.filter(k => filtered.includes(k));
+  const rest = Array.from(filtered)
+    .filter(k => !priority.includes(k))
+    .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  return [...fixed, ...rest];
+}
+
+/**
+ * Emit a TOML table section: `[key]` header + key=value lines.
+ *
+ * Respects `__leadingComments` synthetic key: if present, emits those comment
+ * lines (verbatim) before the section header; the key itself is NOT emitted.
+ *
+ * @param {string} key   Section header name (e.g. "features", "hooks.PreToolUse")
+ * @param {object} obj   Key-value pairs; values must be scalars.
+ * @returns {string}
+ */
+export function emitTable(key, obj) {
+  const lines = [];
+
+  if (obj.__leadingComments) {
+    for (const line of obj.__leadingComments.split('\n')) {
+      lines.push(line);
+    }
+  }
+
+  lines.push(`[${key}]`);
+
+  for (const k of sortKeys(Object.keys(obj))) {
+    const v = obj[k];
+    if (typeof v === 'object' && v !== null) {
+      throw new TypeError(
+        `[toml-emit] emitTable does not support nested objects. Key "${k}" in table "${key}" ` +
+        `has type object. Use emitArrayOfTables for array-of-tables sections.`
+      );
+    }
+    lines.push(`${k} = ${emitScalar(v)}`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Emit an array-of-tables section: multiple `[[key]]` blocks.
+ *
+ * Each block is sorted by `(matcher, command)` lex before emission.
+ * Within each block, key order follows the canonical sort: matcher, command, rest lex.
+ *
+ * @param {string} key    Section header name (e.g. "hooks.PreToolUse")
+ * @param {object[]} arr  Array of objects; each object is one [[key]] block.
+ * @returns {string}
+ */
+export function emitArrayOfTables(key, arr) {
+  // Sort by (matcher, command) — both fields optional but present in hooks usage
+  const sorted = Array.from(arr).sort((a, b) => {
+    const am = String(a.matcher ?? '');
+    const bm = String(b.matcher ?? '');
+    if (am !== bm) return am < bm ? -1 : 1;
+    const ac = String(a.command ?? '');
+    const bc = String(b.command ?? '');
+    return ac < bc ? -1 : ac > bc ? 1 : 0;
+  });
+
+  const chunks = [];
+  for (const block of sorted) {
+    const lines = [];
+
+    // Block-level leading comment
+    if (block.__leadingComments) {
+      for (const line of block.__leadingComments.split('\n')) {
+        lines.push(line);
+      }
+    }
+
+    lines.push(`[[${key}]]`);
+
+    for (const k of sortKeys(Object.keys(block))) {
+      const v = block[k];
+      if (typeof v === 'object' && v !== null) {
+        throw new TypeError(
+          `[toml-emit] emitArrayOfTables does not support nested objects. ` +
+          `Key "${k}" in [[${key}]] has type object.`
+        );
+      }
+      lines.push(`${k} = ${emitScalar(v)}`);
+    }
+
+    chunks.push(lines.join('\n'));
+  }
+
+  return chunks.join('\n') + '\n';
+}
+
+/**
+ * Emit a complete TOML document from a structured descriptor object.
+ *
+ * Document descriptor shape:
+ * ```js
+ * {
+ *   __leadingComments?: string,   // file-level comments, emitted first
+ *   features?: { codex_hooks: boolean, ... },  // [features] table, emitted first among sections
+ *   'hooks.PreToolUse'?: { __type: 'array', items: [...] },  // array-of-tables
+ *   'hooks.PostToolUse'?: { __type: 'array', items: [...] },
+ *   'hooks.SessionStart'?: { __type: 'array', items: [...] },
+ *   // other plain table keys
+ * }
+ * ```
+ *
+ * Emission order:
+ *   1. File-level `__leadingComments`
+ *   2. `[features]` block (if present)
+ *   3. All other sections in insertion order (caller controls order)
+ *
+ * @param {object} doc
+ * @returns {string}
+ */
+export function emitToml(doc) {
+  const parts = [];
+
+  // File-level leading comments
+  if (doc.__leadingComments) {
+    parts.push(doc.__leadingComments + '\n');
+  }
+
+  // [features] always first among sections
+  if (doc.features) {
+    parts.push(emitTable('features', doc.features));
+  }
+
+  // Remaining sections in iteration order (caller sorts)
+  for (const key of Object.keys(doc)) {
+    if (key === '__leadingComments' || key === 'features') continue;
+
+    const val = doc[key];
+    if (val && typeof val === 'object' && val.__type === 'array') {
+      parts.push(emitArrayOfTables(key, val.items));
+    } else if (val && typeof val === 'object') {
+      parts.push(emitTable(key, val));
+    } else {
+      throw new TypeError(
+        `[toml-emit] Unsupported document-level value for key "${key}": expected object or array-descriptor`
+      );
+    }
+  }
+
+  return parts.join('\n');
+}