@quonfig/cli 0.1.0 → 0.2.0

package/dist/codegen/language-mappers/zod-to-string-mapper.d.ts

@@ -9,6 +9,7 @@ export declare class ZodToStringMapper extends ZodBaseMapper {
     function(input: string, output: string): string;
     functionArguments(value?: $ZodFunctionArgs): string;
     functionReturns(value: $ZodFunctionOut): string;
+    intersection(left: string, right: string): string;
     literal(value: string | number | boolean | null): string;
     never(): string;
     null(): string;
@@ -18,7 +19,7 @@ export declare class ZodToStringMapper extends ZodBaseMapper {
     record(keyType: string, valueType: string): string;
     renderField(type: z.ZodTypeAny, key?: string): string;
     string(): string;
-    tuple(wrappedTypes: string[]): string;
+    tuple(wrappedTypes: string[], rest?: string): string;
     undefined(): string;
     union(wrappedTypes: string[]): string;
     unknown(): string;

package/dist/codegen/language-mappers/zod-to-string-mapper.js

@@ -31,6 +31,9 @@ export class ZodToStringMapper extends ZodBaseMapper {
         const mapper = new ZodToStringMapper();
         return mapper.resolveType(value);
     }
+    intersection(left, right) {
+        return `z.intersection(${left}, ${right})`;
+    }
     literal(value) {
         return `z.literal(${JSON.stringify(value)})`;
     }
@@ -72,8 +75,9 @@ export class ZodToStringMapper extends ZodBaseMapper {
     string() {
         return 'z.string()';
     }
-    tuple(wrappedTypes) {
-        return `z.tuple([${wrappedTypes.join(', ')}])`;
+    tuple(wrappedTypes, rest) {
+        const base = `z.tuple([${wrappedTypes.join(', ')}])`;
+        return rest === undefined ? base : `${base}.rest(${rest})`;
     }
     undefined() {
         return 'z.undefined()';

package/dist/codegen/language-mappers/zod-to-typescript-mapper.d.ts

@@ -1,9 +1,11 @@
 import { z } from 'zod';
+import { $ZodType } from 'zod/v4/core';
 import { ZodTypeSupported } from '../types.js';
 import { ZodBaseMapper } from './zod-base-mapper.js';
 export type ZodToTypescriptMapperTarget = 'accessor' | 'raw';
 export declare class ZodToTypescriptMapper extends ZodBaseMapper {
     private fieldName;
+    private metaCaptureOpen;
     private metaDescription;
     private optionalProperty;
     private target;
@@ -18,6 +20,7 @@ export declare class ZodToTypescriptMapper extends ZodBaseMapper {
     function(args: string, returns: string): string;
     functionArguments(value?: z.ZodTuple): string;
     functionReturns(value: z.ZodTypeAny): string;
+    intersection(left: string, right: string): string;
     literal(value: string | number | boolean | null): string;
     never(): string;
     null(): string;
@@ -26,10 +29,11 @@ export declare class ZodToTypescriptMapper extends ZodBaseMapper {
     optional(wrappedType: string): string;
     record(keyType: string, valueType: string): string;
     renderField(type: ZodTypeSupported): string;
+    resolveType(type: $ZodType): string;
     string(): string;
-    tuple(wrappedTypes: string[]): string;
+    tuple(wrappedTypes: string[], rest?: string): string;
     undefined(): string;
     union(wrappedTypes: string[]): string;
     unknown(): string;
-    protected withMeta(description: string, resolveType: () => string): string;
+    protected withMeta(_description: string, resolveType: () => string): string;
 }

package/dist/codegen/language-mappers/zod-to-typescript-mapper.js

@@ -1,6 +1,10 @@
+import * as introspect from '../zod-introspection.js';
 import { ZodBaseMapper } from './zod-base-mapper.js';
 export class ZodToTypescriptMapper extends ZodBaseMapper {
     fieldName;
+    // A field's comment comes from its own meta, looking through optional/nullable/default wrappers only.
+    // Meta deeper inside (a union branch title, an array item description) must not become the field's comment.
+    metaCaptureOpen = true;
     metaDescription = undefined;
     optionalProperty;
     target;
@@ -41,6 +45,9 @@ export class ZodToTypescriptMapper extends ZodBaseMapper {
         const mapper = new ZodToTypescriptMapper();
         return mapper.resolveType(value);
     }
+    intersection(left, right) {
+        return [left, right].map((t) => (t.includes(' | ') || t.includes('=>') ? `(${t})` : t)).join(' & ');
+    }
     literal(value) {
         return JSON.stringify(value);
     }
@@ -102,11 +109,34 @@ export class ZodToTypescriptMapper extends ZodBaseMapper {
         result += `"${this.fieldName}"${this.optionalProperty ? '?' : ''}: ${resolved}`;
         return result;
     }
+    resolveType(type) {
+        const wasOpen = this.metaCaptureOpen;
+        if (wasOpen) {
+            const description = introspect.getMetaDescription(type);
+            if (description) {
+                this.metaDescription = description;
+            }
+        }
+        this.metaCaptureOpen =
+            wasOpen && (introspect.isOptional(type) || introspect.isNullable(type) || introspect.isDefault(type));
+        try {
+            return super.resolveType(type);
+        }
+        finally {
+            this.metaCaptureOpen = wasOpen;
+        }
+    }
     string() {
         return 'string';
     }
-    tuple(wrappedTypes) {
-        return `[${wrappedTypes.join(', ')}]`;
+    tuple(wrappedTypes, rest) {
+        const items = [...wrappedTypes];
+        if (rest !== undefined) {
+            // `...A | B[]` would parse as `...(A | (B[]))`, so wrap anything that isn't a simple type
+            const restType = /^[\w ,<>]+$/.test(rest) ? rest : `(${rest})`;
+            items.push(`...${restType}[]`);
+        }
+        return `[${items.join(', ')}]`;
     }
     undefined() {
         return 'undefined';
@@ -125,9 +155,8 @@ export class ZodToTypescriptMapper extends ZodBaseMapper {
     unknown() {
         return 'unknown';
     }
-    withMeta(description, resolveType) {
-        // Store the description to be used when rendering the field
-        this.metaDescription = description;
+    withMeta(_description, resolveType) {
+        // The description is captured in resolveType, which knows whether it belongs to this field
         return resolveType();
     }
 }

package/dist/codegen/language-mappers/zod-to-typescript-return-value-mapper.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { $ZodType } from 'zod/v4/core';
 import { ZodTypeSupported } from '../types.js';
 import { ZodBaseMapper } from './zod-base-mapper.js';
 export declare class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
@@ -6,9 +7,9 @@ export declare class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
     private FUNCTION_ARGUMENTS_NAME;
     private metaDescription;
     private returnTypePropertyPath;
-    constructor({ fieldName, returnTypePropertyPath }?: {
+    constructor({ fieldName, returnTypePropertyPath, }?: {
         fieldName?: string;
-        returnTypePropertyPath?: string[];
+        returnTypePropertyPath?: (number | string)[];
     });
     any(): string;
     array(): string;
@@ -17,6 +18,7 @@ export declare class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
     function(args: string, returns: string): string;
     functionArguments(value?: z.ZodTuple): string;
     functionReturns(): string;
+    intersection(): string;
     literal(): string;
     never(): string;
     null(): string;
@@ -25,8 +27,9 @@ export declare class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
     optional(wrappedType: string): string;
     record(): string;
     renderField(type: ZodTypeSupported): string;
+    protected resolveTupleItem(item: $ZodType, index: number): string;
     string(): string;
-    tuple(wrappedTypes: string[]): string;
+    tuple(wrappedTypes: string[], rest?: string): string;
     undefined(): string;
     union(wrappedTypes: string[]): string;
     unknown(): string;

package/dist/codegen/language-mappers/zod-to-typescript-return-value-mapper.js

@@ -3,8 +3,9 @@ export class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
     fieldName;
     FUNCTION_ARGUMENTS_NAME = 'params';
     metaDescription = undefined;
+    // Strings are property names, numbers are tuple indexes
     returnTypePropertyPath;
-    constructor({ fieldName, returnTypePropertyPath } = {}) {
+    constructor({ fieldName, returnTypePropertyPath, } = {}) {
         super();
         this.fieldName = fieldName;
         this.returnTypePropertyPath = returnTypePropertyPath ?? [];
@@ -36,6 +37,10 @@ export class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
     functionReturns() {
         return `Mustache.render(raw${this.printPropertyPath()} ?? "", ${this.FUNCTION_ARGUMENTS_NAME})`;
     }
+    intersection() {
+        // Explicitly not supporting navigation into intersections, pass the raw value through
+        return `raw${this.printPropertyPath()}`;
+    }
     literal() {
         return `raw${this.printPropertyPath()}`;
     }
@@ -102,18 +107,24 @@ export class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
         this.metaDescription = undefined;
         return result;
     }
+    resolveTupleItem(item, index) {
+        const mapper = new ZodToTypescriptReturnValueMapper({
+            returnTypePropertyPath: [...this.returnTypePropertyPath, index],
+        });
+        return mapper.resolveType(item);
+    }
     string() {
         return `raw${this.printPropertyPath()}`;
     }
-    tuple(wrappedTypes) {
-        const tupleNavigation = wrappedTypes.map((wt, index) => {
-            let massagedWrappedType = wt;
-            if (massagedWrappedType !== 'raw') {
-                // Remove trailing ! from the wrapped type
-                massagedWrappedType = massagedWrappedType.replace(/!$/, '');
-            }
-            return `${massagedWrappedType}?.[${index}]!`;
-        });
+    tuple(wrappedTypes, rest) {
+        // Each fixed item was already resolved at its own index by resolveTupleItem
+        const tupleNavigation = [...wrappedTypes];
+        if (rest !== undefined) {
+            // Pass the remaining items through untouched; truncating to the fixed items would drop data at runtime.
+            // Mustache is never extracted inside arrays, so the rest needs no per-item mapping.
+            const path = this.printPropertyPath().replace(/!$/, '');
+            tupleNavigation.push(`...(raw${path}?.slice(${wrappedTypes.length}) ?? [])`);
+        }
         return `[${tupleNavigation.join(`, `)}]`;
     }
     undefined() {
@@ -140,7 +151,7 @@ export class ZodToTypescriptReturnValueMapper extends ZodBaseMapper {
             return '';
         }
         // Always safe navigate the path to ensure we don't throw an error if the property doesn't exist
-        const path = paths.reduce((acc, part) => `${acc}?.['${part}']`, '');
+        const path = paths.reduce((acc, part) => (typeof part === 'number' ? `${acc}?.[${part}]` : `${acc}?.['${part}']`), '');
         // To satisfy TypeScript's type system, tell it the value is always defined
         return `${path}!`;
     }

package/dist/codegen/zod-introspection.d.ts

@@ -12,6 +12,7 @@ export declare function isAny(schema: $ZodType): schema is z.ZodAny;
 export declare function isArray(schema: $ZodType): schema is z.ZodArray<z.ZodTypeAny>;
 export declare function isObject(schema: $ZodType): schema is z.ZodObject<z.ZodRawShape>;
 export declare function isTuple(schema: $ZodType): schema is z.ZodTuple;
+export declare function isIntersection(schema: $ZodType): schema is z.ZodIntersection<z.ZodTypeAny, z.ZodTypeAny>;
 export declare function isRecord(schema: $ZodType): schema is z.ZodRecord;
 export declare function isEnum(schema: $ZodType): schema is z.ZodEnum<util.EnumLike>;
 export declare function isUnion(schema: $ZodType): schema is z.ZodUnion<[z.ZodTypeAny, ...z.ZodTypeAny[]]>;
@@ -31,6 +32,17 @@ export declare function getObjectShape(schema: z.ZodObject<z.ZodRawShape>): z.Zo
  * Gets the items from a tuple schema
  */
 export declare function getTupleItems(schema: z.ZodTuple): readonly $ZodType[];
+/**
+ * Gets the rest element from a tuple schema (`z.tuple([...]).rest(x)`), or undefined when it has none
+ */
+export declare function getTupleRest(schema: z.ZodTuple): $ZodType | undefined;
+/**
+ * Gets both sides of an intersection schema
+ */
+export declare function getIntersectionTypes(schema: z.ZodIntersection<z.ZodTypeAny, z.ZodTypeAny>): {
+    left: $ZodType;
+    right: $ZodType;
+};
 /**
  * Gets the key and value types from a record schema
  */

package/dist/codegen/zod-introspection.js

@@ -38,6 +38,9 @@ export function isObject(schema) {
 export function isTuple(schema) {
     return schema instanceof z.ZodTuple;
 }
+export function isIntersection(schema) {
+    return schema instanceof z.ZodIntersection;
+}
 export function isRecord(schema) {
     return schema instanceof z.ZodRecord;
 }
@@ -83,6 +86,18 @@ export function getObjectShape(schema) {
 export function getTupleItems(schema) {
     return schema.def.items;
 }
+/**
+ * Gets the rest element from a tuple schema (`z.tuple([...]).rest(x)`), or undefined when it has none
+ */
+export function getTupleRest(schema) {
+    return schema.def.rest ?? undefined;
+}
+/**
+ * Gets both sides of an intersection schema
+ */
+export function getIntersectionTypes(schema) {
+    return { left: schema.def.left, right: schema.def.right };
+}
 /**
  * Gets the key and value types from a record schema
  */

package/dist/commands/push.js

@@ -334,7 +334,7 @@ export function buildRealDeps(cmd, orgSlug) {
         },
         async validate(dir) {
             const { validateWorkspace } = await import('../verify/validate.js');
-            const result = validateWorkspace(dir);
+            const result = validateWorkspace(dir, { validateValues: true });
             const errors = result.issues.filter((i) => i.severity === 'error').map((i) => i.message);
             return { errors };
         },

package/dist/commands/verify.js

@@ -23,7 +23,7 @@ export default class Verify extends BaseCommand {
     async run() {
         const { args, flags } = await this.parse(Verify);
         const dir = args.path;
-        const result = validateWorkspace(dir);
+        const result = validateWorkspace(dir, { validateValues: true });
         if (flags.strict) {
             // Promote warnings to errors
             for (const issue of result.issues) {

package/dist/commands/workspace/bootstrap.js

@@ -83,7 +83,7 @@ export default class WorkspaceBootstrap extends BaseCommand {
             this.log('Verifying config files...');
             try {
                 const { validateWorkspace } = await import('../../verify/validate.js');
-                const result = validateWorkspace(resolvedDir);
+                const result = validateWorkspace(resolvedDir, { validateValues: true });
                 const errors = result.issues.filter((i) => i.severity === 'error');
                 if (errors.length > 0) {
                     this.log(`\nFound ${errors.length} validation error(s):\n`);

package/dist/migrate/push-to-cloud.js

@@ -47,7 +47,7 @@ const verifyOnDisk = (dir) => {
     // qfg-52qg: client-side verify against the cumulative tree before commit
     // lands. The Gitea pre-receive hook runs against the final HEAD; failing
     // here matches what the server would reject and avoids a wasted push.
-    const verifyResult = validateWorkspace(dir);
+    const verifyResult = validateWorkspace(dir, { validateValues: true });
     if (!verifyResult.valid)
         throw new MigratorVerifyError(verifyResult);
 };

package/dist/util/git-ops.js

@@ -509,7 +509,7 @@ const removeWorktree = async (dir, worktree) => {
  */
 const requireWorkspaceValidates = async (tree) => {
     const { validateWorkspace } = await import('../verify/validate.js');
-    const errors = validateWorkspace(tree).issues.filter((i) => i.severity === 'error');
+    const errors = validateWorkspace(tree, { validateValues: true }).issues.filter((i) => i.severity === 'error');
     if (errors.length === 0)
         return;
     const shown = errors.slice(0, 10).map((i) => `  ${i.file}: ${i.message}`);

package/dist/verify/schema-error-reshape.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Ajv errors -> readable `{ path, message }` violations (qfg-q5f6.1).
+ *
+ * SELF-CONTAINED ON PURPOSE. This file has no imports: it is copied verbatim
+ * into `cli/src/verify/` so `qfg verify`, the app server and the browser
+ * (list badge, view page) word every violation the same way. Change it here
+ * first and re-copy; do not let the two drift.
+ *
+ * It works on any error object shaped like Ajv's `ErrorObject` (keyword,
+ * instancePath, schemaPath, params, message), from Ajv run with
+ * `allErrors: true`.
+ *
+ * Tagged `oneOf` (plan 2026-09-25-advanced-schema-for-jev.md, W1): Ajv
+ * reports every branch's failures, which for a three-way union is mostly
+ * noise. When every branch is an object with the same `const` (or one-value
+ * `enum`) property, that property is the tag:
+ * - the value's tag picks a branch -> only that branch's errors are kept;
+ * - the tag is missing or unknown -> ONE error:
+ *   "`type` must be one of noul, score, choice".
+ * A `oneOf` without a tag is left as Ajv reported it.
+ */
+/** The subset of Ajv's `ErrorObject` this module reads. */
+export interface SchemaErrorLike {
+    keyword: string;
+    instancePath: string;
+    schemaPath: string;
+    params: object;
+    message?: string;
+    propertyName?: string;
+}
+export interface SchemaViolation {
+    /** Dotted path inside the value (`criteria[1]`, `a.b`); "" for the root. */
+    path: string;
+    message: string;
+}
+/** Keyword of the single error that replaces a missing/unknown-tag `oneOf`. */
+export declare const ONE_OF_TAG_KEYWORD = "oneOfTag";
+/**
+ * Ajv `instancePath` (JSON pointer) -> dotted path:
+ * `/questions/tone/criteria/1` -> `questions.tone.criteria[1]`.
+ * Walks the value so only real array indexes become `[n]`.
+ */
+export declare function instancePathToDotted(instancePath: string, value: unknown): string;
+export interface OneOfTag {
+    /** The tag property name, e.g. `type`. */
+    name: string;
+    /** Tag value of each branch, in branch order. */
+    values: unknown[];
+}
+/**
+ * Find the tag of a `oneOf`: the ONE property that is a `const` (or a
+ * one-value `enum`) in every branch, with distinct values. Undefined when
+ * there is none, or more than one candidate.
+ */
+export declare function findOneOfTag(branches: unknown[], root: unknown): OneOfTag | undefined;
+/**
+ * Collapse tagged `oneOf` noise. Returns a new list in Ajv's order: errors
+ * from non-selected branches are dropped, and a missing/unknown tag becomes
+ * a single `oneOfTag` error at the union's position.
+ */
+export declare function reshapeOneOfErrors<E extends SchemaErrorLike>(errors: readonly E[], rootSchema: unknown, value: unknown): (E | SchemaErrorLike)[];
+/** One error -> message. Undefined means "skip it, a nested error says why". */
+export declare function describeSchemaError(error: SchemaErrorLike): string | undefined;
+/**
+ * Ajv errors for `value` against `rootSchema` -> violations, with tagged
+ * `oneOf` noise collapsed. Call it only when validation failed: it never
+ * returns an empty list.
+ */
+export declare function schemaErrorsToViolations(errors: readonly SchemaErrorLike[], rootSchema: unknown, value: unknown): SchemaViolation[];