@quonfig/cli 0.2.1 → 0.2.2

package/dist/verify/map-key-order.js

@@ -0,0 +1,246 @@
+/**
+ * Integer map key order warning (qfg-e87r.21).
+ *
+ * JavaScript objects always put integer keys first, ascending, then every
+ * other key in insertion order. The app editor reads a value with JSON.parse
+ * and saves it with JSON.stringify, so a hand-written map
+ * `{"b": 2, "a": 1, "5": 0}` comes back from an app save as
+ * `{"5": 0, "b": 2, "a": 1}`. Nothing is lost, but git gets a one-time
+ * key-order diff. This check warns about it up front.
+ *
+ * Scope: maps only, meaning objects under an `additionalProperties` schema
+ * (keys the author chooses). Objects with only schema-fixed `properties` are
+ * skipped. A map is checked only if it has at least one integer key, and the
+ * file text is scanned for the real key order (JSON.parse already reorders)
+ * only if some map has one.
+ *
+ * Lives inside cli/src/verify/ because the app-gitea hook build only copies
+ * this directory (see validate.ts). No dependencies on purpose.
+ */
+/** Largest array index in JavaScript: 2^32 - 2. */
+const MAX_INTEGER_KEY = 4_294_967_294;
+/** True for keys JavaScript moves to the front: "0", "5", "1001"; not "007", "-1", "1.5". */
+export function isIntegerKey(key) {
+    return /^(?:0|[1-9]\d*)$/.test(key) && Number(key) <= MAX_INTEGER_KEY;
+}
+const isPlainObject = (node) => typeof node === 'object' && node !== null && !Array.isArray(node);
+/**
+ * Find maps in `value` (walked with `schema`) whose key order in the file
+ * would change on an app save. `readOrderedValue` returns `value` as written
+ * in the file (see scanOrderedJson); it is only called when some map has an
+ * integer key, so maps without one cost nothing extra.
+ */
+export function findMapKeyOrderWarnings(schema, value, readOrderedValue, basePath) {
+    const candidates = new Map();
+    const walk = (node, nodeSchema, segments, depth) => {
+        if (depth > 64)
+            return;
+        const schemas = expandSchema(schema, nodeSchema);
+        if (schemas.length === 0)
+            return;
+        if (Array.isArray(node)) {
+            for (const [index, child] of node.entries()) {
+                for (const s of schemas)
+                    walk(child, itemSchema(s, index), [...segments, index], depth + 1);
+            }
+            return;
+        }
+        if (!isPlainObject(node))
+            return;
+        const keys = Object.keys(node);
+        if (schemas.some((s) => isMapSchema(s)) && keys.some((k) => isIntegerKey(k))) {
+            candidates.set(formatPath(basePath, segments), segments);
+        }
+        for (const key of keys) {
+            for (const s of schemas) {
+                const child = propertySchema(s, key);
+                if (child !== undefined)
+                    walk(node[key], child, [...segments, key], depth + 1);
+            }
+        }
+    };
+    walk(value, schema, [], 0);
+    if (candidates.size === 0)
+        return [];
+    const ordered = readOrderedValue();
+    if (!ordered)
+        return [];
+    const warnings = [];
+    for (const [path, segments] of candidates) {
+        const node = navigate(ordered, segments);
+        if (node?.kind !== 'object')
+            continue;
+        const keys = node.keys;
+        const integerKeys = keys.filter((k) => isIntegerKey(k));
+        const saved = [...integerKeys].sort((a, b) => Number(a) - Number(b));
+        saved.push(...keys.filter((k) => !isIntegerKey(k)));
+        if (saved.every((k, i) => k === keys[i]))
+            continue;
+        warnings.push({ integerKeys, path });
+    }
+    return warnings.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+// ── Schema navigation ───────────────────────────────────────────────────
+function isMapSchema(schema) {
+    return schema.additionalProperties === true || isPlainObject(schema.additionalProperties);
+}
+/** Resolve local `$ref`s and flatten allOf/anyOf/oneOf into the schemas that apply. */
+function expandSchema(root, schema, seen = new Set()) {
+    if (!isPlainObject(schema) || seen.has(schema))
+        return [];
+    seen.add(schema);
+    const out = [schema];
+    if (typeof schema.$ref === 'string')
+        out.push(...expandSchema(root, resolveRef(root, schema.$ref), seen));
+    for (const keyword of ['allOf', 'anyOf', 'oneOf']) {
+        const branches = schema[keyword];
+        if (Array.isArray(branches))
+            for (const branch of branches)
+                out.push(...expandSchema(root, branch, seen));
+    }
+    return out;
+}
+function resolveRef(root, ref) {
+    if (!ref.startsWith('#'))
+        return undefined;
+    let node = root;
+    for (const raw of ref.slice(1).split('/').filter(Boolean)) {
+        const part = decodeURIComponent(raw).replaceAll('~1', '/').replaceAll('~0', '~');
+        if (!isPlainObject(node))
+            return undefined;
+        node = node[part];
+    }
+    return node;
+}
+function propertySchema(schema, key) {
+    const properties = schema.properties;
+    if (isPlainObject(properties) && key in properties)
+        return properties[key];
+    return isMapSchema(schema) ? schema.additionalProperties : undefined;
+}
+function itemSchema(schema, index) {
+    if (Array.isArray(schema.prefixItems) && index < schema.prefixItems.length)
+        return schema.prefixItems[index];
+    // draft-07 tuple form
+    if (Array.isArray(schema.items))
+        return index < schema.items.length ? schema.items[index] : schema.additionalItems;
+    return schema.items;
+}
+function formatPath(base, segments) {
+    let out = base;
+    for (const segment of segments)
+        out += typeof segment === 'number' ? `[${segment}]` : `.${segment}`;
+    return out;
+}
+export function navigate(node, segments) {
+    let current = node;
+    for (const segment of segments) {
+        if (current?.kind === 'object' && typeof segment === 'string')
+            current = current.entries.get(segment);
+        else if (current?.kind === 'array' && typeof segment === 'number')
+            current = current.items[segment];
+        else
+            return undefined;
+    }
+    return current;
+}
+/**
+ * Parse JSON text keeping each object's keys in file order. Duplicate keys
+ * keep their first position, as JavaScript does. Returns undefined on text
+ * that is not JSON (JSON.parse has already reported it).
+ */
+export function scanOrderedJson(text) {
+    let pos = 0;
+    const skipWhitespace = () => {
+        while (pos < text.length && ' \t\n\r'.includes(text[pos]))
+            pos++;
+    };
+    const readString = () => {
+        const start = pos;
+        pos++; // opening quote
+        while (pos < text.length && text[pos] !== '"')
+            pos += text[pos] === '\\' ? 2 : 1;
+        if (pos >= text.length)
+            throw new Error('unterminated string');
+        pos++; // closing quote
+        return JSON.parse(text.slice(start, pos));
+    };
+    const readValue = () => {
+        skipWhitespace();
+        const ch = text[pos];
+        if (ch === '{') {
+            pos++;
+            const keys = [];
+            const entries = new Map();
+            skipWhitespace();
+            if (text[pos] === '}') {
+                pos++;
+                return { entries, keys, kind: 'object' };
+            }
+            for (;;) {
+                skipWhitespace();
+                if (text[pos] !== '"')
+                    throw new Error('expected key');
+                const key = readString();
+                skipWhitespace();
+                if (text[pos] !== ':')
+                    throw new Error('expected colon');
+                pos++;
+                const child = readValue();
+                if (!entries.has(key))
+                    keys.push(key);
+                entries.set(key, child);
+                skipWhitespace();
+                if (text[pos] === ',') {
+                    pos++;
+                    continue;
+                }
+                if (text[pos] === '}') {
+                    pos++;
+                    return { entries, keys, kind: 'object' };
+                }
+                throw new Error('expected , or }');
+            }
+        }
+        if (ch === '[') {
+            pos++;
+            const items = [];
+            skipWhitespace();
+            if (text[pos] === ']') {
+                pos++;
+                return { items, kind: 'array' };
+            }
+            for (;;) {
+                items.push(readValue());
+                skipWhitespace();
+                if (text[pos] === ',') {
+                    pos++;
+                    continue;
+                }
+                if (text[pos] === ']') {
+                    pos++;
+                    return { items, kind: 'array' };
+                }
+                throw new Error('expected , or ]');
+            }
+        }
+        if (ch === '"') {
+            readString();
+            return { kind: 'scalar' };
+        }
+        const start = pos;
+        while (pos < text.length && !',}] \t\n\r'.includes(text[pos]))
+            pos++;
+        if (pos === start)
+            throw new Error('expected value');
+        return { kind: 'scalar' };
+    };
+    try {
+        const node = readValue();
+        skipWhitespace();
+        return pos === text.length ? node : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/verify/validate.d.ts

@@ -19,6 +19,8 @@
  *  - Schema-bound JSON values match their schema, and every schema compiles
  *    (Ajv, opt-in via `validateValues`, which the CLI and the pre-receive
  *    hook both set; see validateBoundJsonValues)
+ *  - Warning: a schema map whose integer keys an app save would move to the
+ *    front (same gate; see warnMapKeyOrder)
  *  - Rule structure (criteria + value present)
  *  - Value type consistency
  *  - Weighted values non-empty and consistent

package/dist/verify/validate.js

@@ -19,11 +19,14 @@
  *  - Schema-bound JSON values match their schema, and every schema compiles
  *    (Ajv, opt-in via `validateValues`, which the CLI and the pre-receive
  *    hook both set; see validateBoundJsonValues)
+ *  - Warning: a schema map whose integer keys an app save would move to the
+ *    front (same gate; see warnMapKeyOrder)
  *  - Rule structure (criteria + value present)
  *  - Value type consistency
  *  - Weighted values non-empty and consistent
  */
 import { z } from 'zod';
+import { findMapKeyOrderWarnings, navigate, scanOrderedJson } from './map-key-order.js';
 import { compileSchema, validateAgainstSchema } from './schema-validator.js';
 // Inlined to keep this directory self-contained for the standalone bun-compile
 // build that runs as the qfg-verify pre-receive hook in app-gitea — that build
@@ -631,8 +634,10 @@ export function validateWorkspace(workspaceDir, options = {}) {
                     });
                 }
             }
-            if (options.validateValues)
+            if (options.validateValues) {
                 validateBoundJsonValues(parsed, config, schemaDocuments, relPath, issues);
+                warnMapKeyOrder(raw, parsed, config, schemaDocuments, relPath, issues);
+            }
             // Check environment IDs referenced in config exist in quonfig.json
             if (declaredEnvIds.size > 0) {
                 for (const env of config.environments) {
@@ -866,8 +871,10 @@ export function validateFileMap(files, options = {}) {
                 suggestion: `Create schemas/${config.schemaKey}.json or schemas-protected/${config.schemaKey}.json, or remove schemaKey`,
             });
         }
-        if (options.validateValues)
+        if (options.validateValues) {
             validateBoundJsonValues(raw, config, schemaDocuments, relPath, issues);
+            warnMapKeyOrder(files.get(relPath) ?? '', raw, config, schemaDocuments, relPath, issues);
+        }
         // Check environment IDs referenced in config exist in quonfig.json
         if (declaredEnvIds.size > 0) {
             for (const env of config.environments) {
@@ -939,6 +946,57 @@ function validateBoundJsonValues(raw, config, schemaDocuments, file, issues) {
     };
     walk(raw, '');
 }
+/**
+ * Warn when a schema map (an object under `additionalProperties`) has integer
+ * keys that are not first, ascending (qfg-e87r.21). The app saves with
+ * JSON.stringify, which moves them there, so a hand-written file gets a
+ * one-time key-order diff. Same scope as validateBoundJsonValues. Always a
+ * warning: it never fails verify or rejects a push.
+ */
+function warnMapKeyOrder(text, raw, config, schemaDocuments, file, issues) {
+    if (config.type !== 'config' || config.valueType !== 'json' || !config.schemaKey)
+        return;
+    const schema = schemaDocuments.get(config.schemaKey);
+    if (!schema)
+        return;
+    // The file is scanned for its real key order at most once, and only if a
+    // map with an integer key exists.
+    let ordered = null;
+    const orderedDocument = () => {
+        if (ordered === null)
+            ordered = scanOrderedJson(text);
+        return ordered;
+    };
+    const walk = (node, segments, docPath) => {
+        if (Array.isArray(node)) {
+            for (const [index, child] of node.entries())
+                walk(child, [...segments, index], `${docPath}[${index}]`);
+            return;
+        }
+        if (typeof node !== 'object' || node === null)
+            return;
+        const record = node;
+        if (record.type === 'json' && 'value' in record) {
+            const valueSegments = [...segments, 'value'];
+            const warnings = findMapKeyOrderWarnings(schema, record.value, () => {
+                const doc = orderedDocument();
+                return doc && navigate(doc, valueSegments);
+            }, docPath || 'value');
+            for (const warning of warnings) {
+                const keys = warning.integerKeys.map((k) => `"${k}"`).join(', ');
+                issues.push({
+                    file,
+                    message: `map at ${warning.path} has integer keys (${keys}) that aren't first, in ascending order. Saving from the app moves them to the front. Reorder them here to avoid a one-time diff.`,
+                    severity: 'warning',
+                });
+            }
+            return;
+        }
+        for (const [key, child] of Object.entries(record))
+            walk(child, [...segments, key], docPath ? `${docPath}.${key}` : key);
+    };
+    walk(raw, [], '');
+}
 /**
  * A schema that does not compile is an error on the schema file, bound or not.
  * Gated on `validateValues` with the value checks; the CLI and the pre-receive

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.2.1";
+declare const _default: "0.2.2";
 export default _default;

package/dist/version.js

@@ -1,2 +1,2 @@
 // AUTO-GENERATED from package.json by scripts/generate-version.mjs — do not edit.
-export default '0.2.1';
+export default '0.2.2';