@karmicsoft/lc-serialize 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+LightCode Platform License — Community, Educational, and Partnership Use
+© KarmicSoft. All rights reserved.
+
+This package (@karmicsoft/lc-serialize) is part of the LightCode platform
+components developed by KarmicSoft (Erasmus+ project "Strengthening the Digital
+Transformation of Higher Education Through Low-Code", No. 2022-1-FR01-KA220-HED-000086863).
+
+Free access and use are granted for educational and non-commercial academic
+purposes, and for LightCode partner and collaboration projects. Use outside this
+scope — commercial activities, professional services, or proprietary integrations —
+requires a separate commercial agreement.
+
+Full terms: see licence.md in the lightcodepedia repository
+(https://lightcodepedia.org). Contact KarmicSoft for a partnership or commercial
+license.

package/README.md

@@ -0,0 +1,73 @@
+# @karmicsoft/lc-serialize
+
+Faithful YAML round-trip for git-backed structured content — a **LightCode** brick.
+© KarmicSoft (see `LICENSE`).
+
+Reads and writes the **same YAML that lives in git**, losing nothing:
+
+- **key order preserved** (no reordering → minimal git diffs);
+- **unquoted dates kept as strings** (`1830-05-29` stays a string — no `js-yaml` timestamp→ISO coercion);
+- **block-scalar chomping preserved** (`|` / `|-` / `|+`);
+- **null preserved**, nested objects/lists, `[]` for empty arrays.
+
+## Install
+
+```sh
+npm install @karmicsoft/lc-serialize
+```
+
+## API
+
+```js
+import { load, dump, roundtrip, isByteIdentical, isLossless } from '@karmicsoft/lc-serialize';
+
+const obj  = load(yamlText);      // parse (dates stay strings)
+const yaml = dump(obj);           // serialize (block style, key order preserved)
+const yaml2 = roundtrip(yamlText); // load()→dump()
+isByteIdentical(yamlText);        // roundtrip === source ?
+isLossless(yamlText);             // parsed data survives round-trip (order-independent)
+```
+
+`dump(obj, { order })` — pass an explicit key order if you want a canonical order
+instead of the object's own order. Omit it to preserve the source order.
+
+## One-liner corpus check (CLI)
+
+Ships a `bin` — point it at a folder (or a file); exits non-zero on any data loss:
+
+```sh
+npx @karmicsoft/lc-serialize lc-serialize-check ./content
+#  → "N file(s) checked · 0 data-loss · K byte-drift (advisory)"
+#  LC_VERBOSE=1 lists every drifting file
+```
+
+`isLossless` is the gate (must be 0). Byte-drift is advisory: a lossless file can
+still reformat — **comments are dropped** and flow style (`{a: 1}` / `[1, 2]`)
+becomes block. On a Sveltia-generated corpus drift ≈ 0; hand-annotated files drift
+by exactly their comments.
+
+## CI recipe (round-trip over the whole corpus, in code)
+
+```js
+import { isLossless, isByteIdentical } from '@karmicsoft/lc-serialize';
+import { readFileSync } from 'node:fs';
+import { globSync } from 'glob';
+
+let loss = 0, drift = 0;
+for (const f of globSync('content/**/*.yaml')) {
+  const src = readFileSync(f, 'utf8');
+  if (!isLossless(src))       { loss++;  console.error('LOSS  ', f); }   // ← must be 0 (fail CI)
+  else if (!isByteIdentical(src)) { drift++; console.warn ('drift ', f); } // ← advisory
+}
+process.exit(loss ? 1 : 0);
+```
+
+### Scope of the guarantee
+
+- **`isLossless` is the contract** — no data lost. Assert this in CI; it must be 0.
+- **`isByteIdentical`** additionally holds when the source is already in **canonical
+  block style** (your migrated corpus largely is). It will differ — while staying
+  lossless — for files that carry **YAML comments** (`# …`, dropped on parse) or
+  **flow style** (`{a: 1}`, `[1, 2]`). Treat byte-drift as an **advisory / drift
+  detector**, not a failure.
+- Round-trip is **idempotent**: after one `dump`, further round-trips are byte-stable.

package/check-corpus.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/*!
+ * lc-serialize-check — "does any of my files lose data?" over a whole corpus.
+ * © KarmicSoft — LightCode.
+ *
+ *   npx @karmicsoft/lc-serialize lc-serialize-check ./content
+ *   node check-corpus.mjs <dir-or-file>        (LC_VERBOSE=1 lists every drift)
+ *
+ * isLossless (the CONTRACT) must be 0 → exit 1 on any loss (use as a CI gate).
+ * isByteIdentical is advisory: a lossless file can still reformat (comments are
+ * dropped, flow style {a: 1} / [1, 2] becomes block style) — that is drift, not loss.
+ */
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { isLossless, isByteIdentical } from './index.js';
+
+const root = process.argv[2] || '.';
+const EXT = ['.yaml', '.yml'];
+
+function walk(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    if (name.startsWith('.') || name === 'node_modules') continue;
+    const p = join(dir, name);
+    const s = statSync(p);
+    if (s.isDirectory()) walk(p, out);
+    else if (EXT.some((e) => name.toLowerCase().endsWith(e))) out.push(p);
+  }
+  return out;
+}
+
+let files;
+try {
+  files = statSync(root).isDirectory() ? walk(root) : [root];
+} catch {
+  console.error('path not found: ' + root);
+  process.exit(2);
+}
+
+let loss = 0, drift = 0, checked = 0;
+for (const f of files) {
+  let src;
+  try { src = readFileSync(f, 'utf8'); } catch { continue; }
+  checked++;
+  try {
+    if (!isLossless(src)) { loss++; console.error('LOSS   ' + f); }
+    else if (!isByteIdentical(src)) { drift++; if (process.env.LC_VERBOSE) console.warn('drift  ' + f); }
+  } catch (e) { loss++; console.error('ERROR  ' + f + ' — ' + e.message); }
+}
+
+console.log(`\n${checked} file(s) checked · ${loss} data-loss · ${drift} byte-drift (advisory)`);
+console.log(loss
+  ? '❌ FAIL — data would be lost on write-back. Fix before deploying.'
+  : '✅ PASS — no data lost' + (drift ? ` (${drift} file(s) reformat only — normalization, not loss).` : '.'));
+process.exit(loss ? 1 : 0);

package/example.yaml

@@ -0,0 +1,27 @@
+# Example fiche — feed it to load()/dump() to see the round-trip.
+id: louise-michel
+slug: louise-michel
+type: person
+title: Louise Michel
+gender: féminin
+birth:
+  date: 1830-05-29
+  year: 1830
+professions:
+  - institutrice
+  - anarchiste
+addresses:
+  - id: 24-rue-houdon
+    role: résidence
+    period: 1871
+  - id: cimetiere-de-levallois
+    role: mémoire
+image:
+  credit: BnF · domaine public — Gallica
+body: |
+  Institutrice et militante anarchiste.
+
+  Surnommée « la Vierge rouge ».
+workflow:
+  draft: false
+  aiText: null

package/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @karmicsoft/lc-serialize — faithful YAML round-trip for git-backed content.
+ * © KarmicSoft — LightCode.
+ */
+
+/** Parse YAML with the CORE schema so unquoted dates stay strings (no timestamp coercion). */
+export function load(text: string): any;
+
+/**
+ * Serialize a value to block-style YAML, preserving the object's own key order
+ * (minimal git diffs). Pass `{ order }` for an explicit canonical key order.
+ */
+export function dump(obj: any, opts?: { order?: string[] }): string;
+
+/** load() → dump(): the round-trip a corpus CI uses to prove non-loss. */
+export function roundtrip(text: string): string;
+
+/** True when roundtrip(text) === text. Holds for canonical block-style YAML. */
+export function isByteIdentical(text: string): boolean;
+
+/** True when the parsed data survives a round-trip (order-independent). The contract. */
+export function isLossless(text: string): boolean;

package/index.js

@@ -0,0 +1,107 @@
+/*!
+ * @karmicsoft/lc-serialize — faithful YAML round-trip for git-backed content.
+ * © KarmicSoft — LightCode. See LICENSE.
+ *
+ * Reads/writes the SAME YAML that lives in git, losing nothing:
+ *  - key order preserved (no reordering → minimal git diffs)
+ *  - unquoted dates kept as strings (no timestamp coercion: 1830-05-29 stays a string)
+ *  - block-scalar chomping preserved (| / |- / |+)
+ *  - null preserved, nested objects/lists, [] for empty arrays
+ */
+import yaml from 'js-yaml';
+
+/** Parse YAML WITHOUT date/timestamp coercion (CORE schema). */
+export function load(text) {
+  return yaml.load(text, { schema: yaml.CORE_SCHEMA });
+}
+
+/** Serialize a plain object to block-style YAML, preserving its key order. */
+export function dump(obj, opts = {}) {
+  return emitMap(obj, 0, opts.order || null) + '\n';
+}
+
+/** load() → dump(): the round-trip your CI uses to prove non-loss. */
+export function roundtrip(text) {
+  return dump(load(text));
+}
+
+/** Byte-identical check. Holds for canonical block-style YAML (see README § scope). */
+export function isByteIdentical(text) {
+  return roundtrip(text) === text;
+}
+
+/** Semantic non-loss: the parsed data survives a round-trip (order-independent). */
+export function isLossless(text) {
+  return deepEqual(load(text), load(roundtrip(text)));
+}
+
+// ── emitter ──────────────────────────────────────────────────────────────
+const pad = (n) => '  '.repeat(n);
+const isArr = Array.isArray;
+const isObj = (v) => v && typeof v === 'object' && !isArr(v);
+
+function quote(s) { return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'; }
+function scalarStr(s) {
+  if (s === '') return '""';
+  if (/^\s|\s$/.test(s)) return quote(s);
+  if (/:\s/.test(s) || /:$/.test(s)) return quote(s);
+  if (/\s#/.test(s)) return quote(s);
+  if (/^[>|&*!%@`"'\[\]{}?,]/.test(s)) return quote(s);
+  if (/^-(\s|$)/.test(s)) return quote(s);
+  if (/^(true|false|null|~|yes|no|on|off)$/i.test(s)) return quote(s);
+  if (/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(s)) return quote(s);
+  return s;
+}
+function scalarInline(v, p) {
+  if (v === null || v === undefined) return 'null';
+  const t = typeof v;
+  if (t === 'number' || t === 'boolean') return String(v);
+  const s = String(v);
+  if (s.indexOf('\n') !== -1) {
+    const trail = (/(\n*)$/.exec(s)[1] || '').length;         // trailing newlines
+    const chomp = trail === 0 ? '-' : (trail === 1 ? '' : '+'); // faithful chomping
+    const lines = s.replace(/\n+$/, '').split('\n');
+    let out = '|' + chomp;
+    for (const ln of lines) out += '\n' + (ln === '' ? '' : p + '  ' + ln);
+    for (let i = 0; i < trail - 1; i++) out += '\n';
+    return out;
+  }
+  return scalarStr(s);
+}
+function orderedKeys(map, order) {
+  const keys = [], seen = new Set();
+  if (order) for (const k of order) if (Object.prototype.hasOwnProperty.call(map, k)) { keys.push(k); seen.add(k); }
+  for (const k of Object.keys(map)) if (!seen.has(k)) keys.push(k);
+  return keys;
+}
+function emitMap(map, indent, order) {
+  return orderedKeys(map, order).map((k) => emitKV(map, k, indent)).join('\n');
+}
+function emitKV(map, k, indent) {
+  const p = pad(indent), v = map[k];
+  if (v === null || v === undefined) return p + k + ': null';
+  if (isArr(v)) {
+    if (v.length === 0) return p + k + ': []';
+    let o = p + k + ':';
+    for (const it of v) o += '\n' + emitSeqItem(it, indent + 1);
+    return o;
+  }
+  if (isObj(v)) return p + k + ':\n' + emitMap(v, indent + 1, null);
+  return p + k + ': ' + scalarInline(v, p);
+}
+function emitSeqItem(item, indent) {
+  const p = pad(indent);
+  if (isObj(item)) {
+    const mt = emitMap(item, indent + 1, null), lead = pad(indent + 1), lines = mt.split('\n');
+    lines[0] = p + '- ' + lines[0].slice(lead.length);
+    return lines.join('\n');
+  }
+  if (isArr(item)) return p + '- []';
+  return p + '- ' + scalarInline(item, p);
+}
+function deepEqual(a, b) { return JSON.stringify(sortDeep(a)) === JSON.stringify(sortDeep(b)); }
+function sortDeep(v) {
+  if (isArr(v)) return v.map(sortDeep);
+  if (isObj(v)) { const o = {}; for (const k of Object.keys(v).sort()) o[k] = sortDeep(v[k]); return o; }
+  return v;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@karmicsoft/lc-serialize",
+  "version": "0.1.0",
+  "description": "Faithful YAML round-trip for git-backed structured content — a LightCode brick.",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  },
+  "bin": {
+    "lc-serialize-check": "./check-corpus.mjs"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "check-corpus.mjs",
+    "example.yaml",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test.mjs"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "KarmicSoft",
+  "homepage": "https://lightcodepedia.org",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/michelzam/lightcodepedia",
+    "directory": "packages/lc-serialize"
+  },
+  "dependencies": {
+    "js-yaml": "^4.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "yaml",
+    "round-trip",
+    "git-cms",
+    "lightcode",
+    "karmicsoft"
+  ]
+}