@quonfig/cli 0.2.1 → 0.2.3

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,12 +19,16 @@
  *  - 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';
+import { DURATION_FORMAT_HINT, isValidIsoDuration, parseDoubleValue, parseIntValue } from './value-grammar.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
 // only copies cli/src/verify/, so any out-of-tree imports break it. Source of
@@ -66,8 +70,26 @@ const OperatorSchema = z.enum(OPERATORS);
 const LogLevelSchema = z.enum(LOG_LEVELS);
 const BoolValueSchema = z.object({ type: z.literal('bool'), value: z.boolean() });
 const StringValueSchema = z.object({ type: z.literal('string'), value: z.string() });
-const IntValueSchema = z.object({ type: z.literal('int'), value: z.union([z.number(), z.string()]) });
-const DoubleValueSchema = z.object({ type: z.literal('double'), value: z.union([z.number(), z.string()]) });
+// Value grammars (qfg-e87r.30): the same definitions qfg create / set-default /
+// override use (value-grammar.ts). Issues carry params.valueGrammar so the
+// reporter can add the config key (formatSchemaIssue).
+const grammarIssue = (ctx, message) => ctx.addIssue({ code: 'custom', message, params: { valueGrammar: true } });
+const IntValueSchema = z.object({
+    type: z.literal('int'),
+    value: z.union([z.number(), z.string()]).superRefine((value, ctx) => {
+        const ok = typeof value === 'number' ? Number.isSafeInteger(value) : parseIntValue(value) !== undefined;
+        if (!ok)
+            grammarIssue(ctx, `invalid int ${JSON.stringify(value)}. Expected a whole number (optional -, ASCII digits) within +/-(2^53-1).`);
+    }),
+});
+const DoubleValueSchema = z.object({
+    type: z.literal('double'),
+    value: z.union([z.number(), z.string()]).superRefine((value, ctx) => {
+        const ok = typeof value === 'number' ? Number.isFinite(value) : parseDoubleValue(value) !== undefined;
+        if (!ok)
+            grammarIssue(ctx, `invalid double ${JSON.stringify(value)}. Expected a finite decimal number with an optional exponent, such as 2.5, .5 or -1.5e3.`);
+    }),
+});
 const JsonValueSchema = z.object({
     type: z.literal('json'),
     value: z.any().refine((v) => typeof v !== 'string', {
@@ -75,7 +97,13 @@ const JsonValueSchema = z.object({
     }),
 });
 const StringListValueSchema = z.object({ type: z.literal('string_list'), value: z.array(z.string()) });
-const DurationValueSchema = z.object({ type: z.literal('duration'), value: z.string() });
+const DurationValueSchema = z.object({
+    type: z.literal('duration'),
+    value: z.string().superRefine((value, ctx) => {
+        if (!isValidIsoDuration(value))
+            grammarIssue(ctx, `invalid duration ${JSON.stringify(value)}. ${DURATION_FORMAT_HINT}`);
+    }),
+});
 const LogLevelValueSchema = z.object({ type: z.literal('log_level'), value: LogLevelSchema });
 const SchemaValueSchema = z.object({
     type: z.literal('schema'),
@@ -154,6 +182,17 @@ const StoredConfigSchema = z
 })
     .passthrough(); // Allow extra fields (tags, schemaUsageMode, etc.)
 const SchemaDocumentSchema = z.object({}).passthrough();
+/**
+ * `Schema: <path> - <message>`. A value-grammar issue (duration / int /
+ * double) also names the config key, so the hook's error says which config
+ * holds the bad value, not just which file (qfg-e87r.30).
+ */
+function formatSchemaIssue(issue, parsed) {
+    const base = `Schema: ${issue.path.join('.')} - ${issue.message}`;
+    const isGrammar = issue.code === 'custom' && issue.params?.valueGrammar;
+    const key = typeof parsed === 'object' && parsed !== null ? parsed.key : undefined;
+    return isGrammar && typeof key === 'string' ? `${base} (config "${key}")` : base;
+}
 /** Maps config directory names to their expected config type. */
 const DIR_TO_TYPE = {
     configs: 'config',
@@ -466,7 +505,7 @@ export function validateWorkspace(workspaceDir, options = {}) {
                 for (const issue of result.error.issues) {
                     issues.push({
                         file: relPath,
-                        message: `Schema: ${issue.path.join('.')} - ${issue.message}`,
+                        message: formatSchemaIssue(issue, parsed),
                         severity: 'error',
                     });
                 }
@@ -631,8 +670,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) {
@@ -772,7 +813,7 @@ export function validateFileMap(files, options = {}) {
             for (const issue of result.error.issues) {
                 issues.push({
                     file: relPath,
-                    message: `Schema: ${issue.path.join('.')} - ${issue.message}`,
+                    message: formatSchemaIssue(issue, parsed),
                     severity: 'error',
                 });
             }
@@ -866,8 +907,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 +982,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/verify/value-grammar.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The ONE value grammar for durations (qfg-2agi.3) and int/double input
+ * (qfg-2agi.23), shared by qfg create, set-default, override and verify
+ * (qfg-e87r.30). util/coerce.ts re-exports it.
+ *
+ * SELF-CONTAINED ON PURPOSE: no imports. It lives under src/verify/ because the
+ * standalone qfg-verify pre-receive hook (app-gitea Dockerfile) is built from
+ * this directory alone.
+ */
+export declare const DURATION_FORMAT_HINT = "Expected an ISO 8601 duration such as PT30S, PT5M, PT1H30M or P1DT6H (days, hours, minutes, seconds; a fraction only on seconds; at most P36500D).";
+export declare const isValidIsoDuration: (value: string) => boolean;
+export declare const parseIntValue: (value: string) => number | undefined;
+export declare const parseDoubleValue: (value: string) => number | undefined;

package/dist/verify/value-grammar.js

@@ -0,0 +1,63 @@
+/**
+ * The ONE value grammar for durations (qfg-2agi.3) and int/double input
+ * (qfg-2agi.23), shared by qfg create, set-default, override and verify
+ * (qfg-e87r.30). util/coerce.ts re-exports it.
+ *
+ * SELF-CONTAINED ON PURPOSE: no imports. It lives under src/verify/ because the
+ * standalone qfg-verify pre-receive hook (app-gitea Dockerfile) is built from
+ * this directory alone.
+ */
+// The ONE duration grammar (qfg-2agi.29), shared by qfg create, set-default,
+// override and verify. Fixture of record: integration-test-data
+// tests/duration/grammar.yaml (test/util/duration-grammar.test.ts holds this
+// function to it).
+//
+//   ^P(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+(?:\.\d+)?S)?)?$
+//
+// plus: at least one component, no dangling T, a fraction only on S with at
+// most 9 digits, total magnitude <= P36500D. [0-9] (not \d) and the whole
+// string anchored so ports to other regex engines stay strict.
+// JS \d is already ASCII-only; [0-9] is kept so a copy into Python/.NET is safe.
+/* eslint-disable unicorn/better-regex */
+const ISO_DURATION_PATTERN = /^P(?:(?<d>[0-9]+)D)?(?:T(?:(?<h>[0-9]+)H)?(?:(?<m>[0-9]+)M)?(?:(?<s>[0-9]+)(?:\.(?<f>[0-9]{1,9}))?S)?)?$/;
+/* eslint-enable unicorn/better-regex */
+export const DURATION_FORMAT_HINT = 'Expected an ISO 8601 duration such as PT30S, PT5M, PT1H30M or P1DT6H (days, hours, minutes, seconds; a fraction only on seconds; at most P36500D).';
+const NANOS_PER_SECOND = 1000000000n;
+const MAX_DURATION_NANOS = 36500n * 86400n * NANOS_PER_SECOND;
+export const isValidIsoDuration = (value) => {
+    const match = ISO_DURATION_PATTERN.exec(value);
+    if (!match?.groups)
+        return false;
+    const { d, f, h, m, s } = match.groups;
+    // At least one component; a T must be followed by at least one of H/M/S.
+    if (d === undefined && h === undefined && m === undefined && s === undefined)
+        return false;
+    if (value.includes('T') && h === undefined && m === undefined && s === undefined)
+        return false;
+    // Exact integer arithmetic: huge digit strings cannot overflow past the cap.
+    const nanos = (BigInt(d ?? 0) * 86400n + BigInt(h ?? 0) * 3600n + BigInt(m ?? 0) * 60n + BigInt(s ?? 0)) * NANOS_PER_SECOND +
+        BigInt((f ?? '').padEnd(9, '0'));
+    return nanos <= MAX_DURATION_NANOS;
+};
+// The ONE int/double input grammar (qfg-2agi.23), shared by qfg create and
+// set-default. Strict whole-string matches with ASCII digits only: no
+// surrounding whitespace, no hex, no trailing junk ('12abc'), no NaN/Infinity.
+// An int must stay within +/-(2^53-1) because it is written as a JSON number
+// and anything larger silently loses precision. Returns undefined when the
+// input is not valid.
+/* eslint-disable unicorn/better-regex */
+const INT_PATTERN = /^-?[0-9]+$/;
+const DOUBLE_PATTERN = /^-?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][-+]?[0-9]+)?$/;
+/* eslint-enable unicorn/better-regex */
+export const parseIntValue = (value) => {
+    if (!INT_PATTERN.test(value))
+        return undefined;
+    const int = Number(value);
+    return Number.isSafeInteger(int) ? int : undefined;
+};
+export const parseDoubleValue = (value) => {
+    if (!DOUBLE_PATTERN.test(value))
+        return undefined;
+    const double = Number(value);
+    return Number.isFinite(double) ? double : undefined;
+};

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-declare const _default: "0.2.1";
+declare const _default: "0.2.3";
 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.3';