@quonfig/cli 0.0.1

package/dist/verify/validate.js

@@ -0,0 +1,756 @@
+/**
+ * Workspace validation logic.
+ *
+ * This module validates a Quonfig workspace directory against the StoredConfig
+ * schema. It can be used from both the oclif CLI (`qfg verify`) and the
+ * standalone compiled binary (git pre-receive hook).
+ *
+ * Validation checks:
+ *  - Valid JSON
+ *  - Schema compliance (StoredConfigSchema from Zod)
+ *  - Key matches filename
+ *  - Key constraints (1-512 chars, no slashes, not "new")
+ *  - Config type matches directory
+ *  - Segment constraints (valueType=bool, sendToClientSdk=false)
+ *  - Log level constraints (valueType=log_level)
+ *  - Referential integrity (IN_SEG/NOT_IN_SEG reference existing segments)
+ *  - schemaKey references existing schemas
+ *  - Rule structure (criteria + value present)
+ *  - Value type consistency
+ *  - Weighted values non-empty and consistent
+ */
+import { z } from "zod";
+// ── Schemas (subset of app-quonfig config-schemas.ts) ───────────────────
+const ConfigTypeSchema = z.enum([
+    "feature_flag",
+    "config",
+    "log_level",
+    "segment",
+    "schema",
+]);
+const ValueTypeSchema = z.enum([
+    "bool",
+    "string",
+    "int",
+    "double",
+    "json",
+    "string_list",
+    "duration",
+    "log_level",
+]);
+const OperatorSchema = z.enum([
+    "ALWAYS_TRUE",
+    "PROP_IS_ONE_OF",
+    "PROP_IS_NOT_ONE_OF",
+    "PROP_STARTS_WITH_ONE_OF",
+    "PROP_DOES_NOT_START_WITH_ONE_OF",
+    "PROP_ENDS_WITH_ONE_OF",
+    "PROP_DOES_NOT_END_WITH_ONE_OF",
+    "PROP_CONTAINS_ONE_OF",
+    "PROP_DOES_NOT_CONTAIN_ONE_OF",
+    "PROP_LESS_THAN",
+    "PROP_LESS_THAN_OR_EQUAL",
+    "PROP_GREATER_THAN",
+    "PROP_GREATER_THAN_OR_EQUAL",
+    "PROP_BEFORE",
+    "PROP_AFTER",
+    "PROP_MATCHES",
+    "PROP_DOES_NOT_MATCH",
+    "IN_SEG",
+    "NOT_IN_SEG",
+    "IN_INT_RANGE",
+    "LOOKUP_KEY_IN",
+    "LOOKUP_KEY_NOT_IN",
+]);
+const LogLevelSchema = z.enum([
+    "TRACE",
+    "DEBUG",
+    "INFO",
+    "WARN",
+    "ERROR",
+    "FATAL",
+]);
+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()]) });
+const JsonValueSchema = z.object({ type: z.literal("json"), value: z.unknown() });
+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 LogLevelValueSchema = z.object({ type: z.literal("log_level"), value: LogLevelSchema });
+const SchemaValueSchema = z.object({
+    type: z.literal("schema"),
+    value: z.object({ schemaType: z.string(), schema: z.string() }),
+});
+const ProvidedValueSchema = z.object({
+    type: z.literal("provided"),
+    value: z.object({ source: z.string(), lookup: z.string() }),
+});
+const ValueSchema = z.discriminatedUnion("type", [
+    BoolValueSchema,
+    StringValueSchema,
+    IntValueSchema,
+    DoubleValueSchema,
+    JsonValueSchema,
+    StringListValueSchema,
+    DurationValueSchema,
+    LogLevelValueSchema,
+    SchemaValueSchema,
+    ProvidedValueSchema,
+]);
+const MAX_WEIGHT = 100_000;
+const WeightedValueSchema = z.object({
+    value: ValueSchema,
+    weight: z.number().int().min(0).max(MAX_WEIGHT),
+});
+const WeightedValuesSchema = z.object({
+    type: z.literal("weighted_values"),
+    value: z.object({
+        weightedValues: z.array(WeightedValueSchema),
+        hashByPropertyName: z.string().default("user.key"),
+        splitEvenly: z.boolean().optional(),
+    }),
+});
+const RuleValueSchema = z.union([ValueSchema, WeightedValuesSchema]);
+const CriterionSchema = z.object({
+    propertyName: z.string().optional(),
+    operator: OperatorSchema,
+    valueToMatch: ValueSchema.optional(),
+});
+const ConfigRuleSchema = z.object({
+    criteria: z.array(CriterionSchema),
+    value: RuleValueSchema,
+});
+/** Environment ID must be a slug: lowercase alphanumeric + dashes, not a UUID. */
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const ConfigEnvironmentSchema = z.object({
+    id: z.string(),
+    rules: z.array(ConfigRuleSchema),
+});
+const VariantSchema = z.object({
+    id: z.string().optional(),
+    key: z.string().optional(),
+    value: ValueSchema,
+    description: z.string().optional(),
+});
+const StoredConfigSchema = z.object({
+    id: z.string().optional(),
+    projectId: z.string().optional(),
+    key: z.string(),
+    type: ConfigTypeSchema,
+    valueType: ValueTypeSchema,
+    name: z.string().optional(),
+    description: z.string().optional(),
+    sendToClientSdk: z.boolean().default(false),
+    schemaKey: z.string().optional(),
+    accessLevel: z.string().optional(),
+    protection: z.string().optional(),
+    default: z.object({
+        rules: z.array(ConfigRuleSchema),
+    }),
+    environments: z.array(ConfigEnvironmentSchema).default([]),
+    variants: z.array(VariantSchema).default([]),
+}).passthrough(); // Allow extra fields (tags, schemaUsageMode, etc.)
+const SchemaDocumentSchema = z.object({}).passthrough();
+/** Maps config directory names to their expected config type. */
+const DIR_TO_TYPE = {
+    "configs": "config",
+    "feature-flags": "feature_flag",
+    "segments": "segment",
+    "log-levels": "log_level",
+};
+const CONFIG_DIRS = new Set(Object.keys(DIR_TO_TYPE));
+const SCHEMA_DIRS = new Set(["schemas", "schemas-protected"]);
+const KNOWN_DIRS = new Set([...CONFIG_DIRS, ...SCHEMA_DIRS]);
+// Operators that reference segments
+const SEGMENT_OPERATORS = new Set(["IN_SEG", "NOT_IN_SEG"]);
+// Operators that require a propertyName
+const PROPERTY_OPERATORS = new Set([
+    "PROP_IS_ONE_OF", "PROP_IS_NOT_ONE_OF",
+    "PROP_STARTS_WITH_ONE_OF", "PROP_DOES_NOT_START_WITH_ONE_OF",
+    "PROP_ENDS_WITH_ONE_OF", "PROP_DOES_NOT_END_WITH_ONE_OF",
+    "PROP_CONTAINS_ONE_OF", "PROP_DOES_NOT_CONTAIN_ONE_OF",
+    "PROP_LESS_THAN", "PROP_LESS_THAN_OR_EQUAL",
+    "PROP_GREATER_THAN", "PROP_GREATER_THAN_OR_EQUAL",
+    "PROP_BEFORE", "PROP_AFTER",
+    "PROP_MATCHES", "PROP_DOES_NOT_MATCH",
+]);
+// Operators that require a valueToMatch
+const VALUE_REQUIRED_OPERATORS = new Set([
+    ...PROPERTY_OPERATORS,
+    "IN_SEG", "NOT_IN_SEG",
+    "IN_INT_RANGE",
+    "LOOKUP_KEY_IN", "LOOKUP_KEY_NOT_IN",
+]);
+// ── Validation from filesystem ──────────────────────────────────────────
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Validate an entire workspace directory on disk.
+ */
+export function validateWorkspace(workspaceDir) {
+    const issues = [];
+    let filesChecked = 0;
+    // Collect all configs for cross-reference checks
+    const allConfigs = [];
+    const allSchemaFiles = [];
+    const segmentKeys = new Set();
+    const schemaKeys = new Set();
+    // Check for unexpected top-level entries
+    let entries;
+    try {
+        entries = fs.readdirSync(workspaceDir, { withFileTypes: true });
+    }
+    catch (err) {
+        return {
+            issues: [{
+                    file: workspaceDir,
+                    message: `Cannot read workspace directory: ${err.message}`,
+                    severity: "error",
+                }],
+            filesChecked: 0,
+            valid: false,
+        };
+    }
+    for (const entry of entries) {
+        if (entry.name.startsWith("."))
+            continue; // skip .git, .qf, etc.
+        if (entry.isDirectory() && !KNOWN_DIRS.has(entry.name)) {
+            issues.push({
+                file: entry.name,
+                message: `Unexpected directory "${entry.name}"`,
+                severity: "warning",
+                suggestion: `Expected directories: ${[...KNOWN_DIRS].join(", ")}`,
+            });
+        }
+    }
+    // First pass: parse all files and collect keys
+    for (const dir of KNOWN_DIRS) {
+        const dirPath = path.join(workspaceDir, dir);
+        if (!fs.existsSync(dirPath))
+            continue;
+        const files = fs.readdirSync(dirPath).filter(f => f.endsWith(".json") && !f.startsWith("."));
+        for (const file of files) {
+            const filePath = path.join(dirPath, file);
+            const relPath = `${dir}/${file}`;
+            filesChecked++;
+            // Read and parse JSON
+            let raw;
+            try {
+                raw = fs.readFileSync(filePath, "utf-8");
+            }
+            catch (err) {
+                issues.push({ file: relPath, message: `Cannot read file: ${err.message}`, severity: "error" });
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (err) {
+                issues.push({
+                    file: relPath,
+                    message: `Invalid JSON: ${err.message}`,
+                    severity: "error",
+                });
+                continue;
+            }
+            if (SCHEMA_DIRS.has(dir)) {
+                const result = SchemaDocumentSchema.safeParse(parsed);
+                if (!result.success) {
+                    for (const issue of result.error.issues) {
+                        issues.push({
+                            file: relPath,
+                            message: `Schema: ${issue.path.join(".")} - ${issue.message}`,
+                            severity: "error",
+                        });
+                    }
+                    continue;
+                }
+                const schemaKey = file.replace(/\.json$/, "");
+                schemaKeys.add(schemaKey);
+                validateKey(schemaKey, relPath, issues);
+                allSchemaFiles.push({ key: schemaKey, file: relPath });
+                continue;
+            }
+            // Validate against StoredConfigSchema
+            const result = StoredConfigSchema.safeParse(parsed);
+            if (!result.success) {
+                for (const issue of result.error.issues) {
+                    issues.push({
+                        file: relPath,
+                        message: `Schema: ${issue.path.join(".")} - ${issue.message}`,
+                        severity: "error",
+                    });
+                }
+                continue;
+            }
+            const config = result.data;
+            const expectedKey = file.replace(/\.json$/, "");
+            // Key matches filename
+            if (config.key !== expectedKey) {
+                issues.push({
+                    file: relPath,
+                    message: `Key "${config.key}" does not match filename "${expectedKey}"`,
+                    severity: "error",
+                    suggestion: `Rename file to "${config.key}.json" or set key to "${expectedKey}"`,
+                });
+            }
+            // Key constraints
+            validateKey(config.key, relPath, issues);
+            // Config type matches directory
+            const expectedType = DIR_TO_TYPE[dir];
+            if (expectedType && config.type !== expectedType) {
+                issues.push({
+                    file: relPath,
+                    message: `Type "${config.type}" in directory "${dir}" (expected "${expectedType}")`,
+                    severity: "error",
+                    suggestion: `Move to "${typeToDir(config.type)}/" or change type to "${expectedType}"`,
+                });
+            }
+            // Type-specific constraints
+            if (config.type === "segment") {
+                if (config.valueType !== "bool") {
+                    issues.push({
+                        file: relPath,
+                        message: `Segment must have valueType "bool", got "${config.valueType}"`,
+                        severity: "error",
+                    });
+                }
+                if (config.sendToClientSdk) {
+                    issues.push({
+                        file: relPath,
+                        message: `Segment must have sendToClientSdk=false`,
+                        severity: "error",
+                    });
+                }
+                segmentKeys.add(config.key);
+            }
+            if (config.type === "log_level" && config.valueType !== "log_level") {
+                issues.push({
+                    file: relPath,
+                    message: `Log level must have valueType "log_level", got "${config.valueType}"`,
+                    severity: "error",
+                });
+            }
+            // Validate environment IDs are slugs, not UUIDs
+            validateEnvironmentIds(config.environments, relPath, issues);
+            // Validate rules
+            validateRules(config.default.rules, relPath, "default", config.valueType, issues);
+            for (const env of config.environments) {
+                validateRules(env.rules, relPath, `environments[${env.id}]`, config.valueType, issues);
+            }
+            // Collect for cross-reference
+            allConfigs.push({ key: config.key, type: config.type, dir, file: relPath });
+            // Check schemaKey reference (collected, validated in second pass)
+            if (config.schemaKey) {
+                // Will be checked after all files are parsed
+            }
+        }
+    }
+    // Second pass: referential integrity
+    for (const dir of KNOWN_DIRS) {
+        const dirPath = path.join(workspaceDir, dir);
+        if (!fs.existsSync(dirPath))
+            continue;
+        const files = fs.readdirSync(dirPath).filter(f => f.endsWith(".json") && !f.startsWith("."));
+        for (const file of files) {
+            const filePath = path.join(dirPath, file);
+            const relPath = `${dir}/${file}`;
+            if (SCHEMA_DIRS.has(dir)) {
+                continue;
+            }
+            let raw;
+            try {
+                raw = fs.readFileSync(filePath, "utf-8");
+            }
+            catch {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                continue;
+            }
+            const result = StoredConfigSchema.safeParse(parsed);
+            if (!result.success)
+                continue;
+            const config = result.data;
+            // Check segment references in criteria
+            const segRefs = collectSegmentReferences(config);
+            for (const ref of segRefs) {
+                if (!segmentKeys.has(ref)) {
+                    issues.push({
+                        file: relPath,
+                        message: `References segment "${ref}" which does not exist`,
+                        severity: "error",
+                        suggestion: `Create segments/${ref}.json or remove the segment reference`,
+                    });
+                }
+            }
+            // Check schemaKey references
+            if (config.schemaKey && !schemaKeys.has(config.schemaKey)) {
+                issues.push({
+                    file: relPath,
+                    message: `References schema "${config.schemaKey}" which does not exist`,
+                    severity: "error",
+                    suggestion: `Create schemas/${config.schemaKey}.json or schemas-protected/${config.schemaKey}.json, or remove schemaKey`,
+                });
+            }
+        }
+    }
+    // Check for duplicate keys across directories
+    const keyToFiles = new Map();
+    for (const c of allConfigs) {
+        const existing = keyToFiles.get(c.key) || [];
+        existing.push(c.file);
+        keyToFiles.set(c.key, existing);
+    }
+    for (const [key, files] of keyToFiles) {
+        if (files.length > 1) {
+            issues.push({
+                file: files.join(", "),
+                message: `Duplicate key "${key}" found in multiple files`,
+                severity: "error",
+                suggestion: `Each key must be unique across the workspace`,
+            });
+        }
+    }
+    const schemaKeyToFiles = new Map();
+    for (const schemaFile of allSchemaFiles) {
+        const existing = schemaKeyToFiles.get(schemaFile.key) || [];
+        existing.push(schemaFile.file);
+        schemaKeyToFiles.set(schemaFile.key, existing);
+    }
+    for (const [key, files] of schemaKeyToFiles) {
+        if (files.length > 1) {
+            issues.push({
+                file: files.join(", "),
+                message: `Duplicate schema key "${key}" found in multiple files`,
+                severity: "error",
+                suggestion: `Each schema key must be unique across schema directories`,
+            });
+        }
+    }
+    const hasErrors = issues.some(i => i.severity === "error");
+    return { issues, filesChecked, valid: !hasErrors };
+}
+// ── Validate from in-memory file map (for git hook) ─────────────────────
+/**
+ * Validate configs provided as a map of { "dir/file.json": jsonString }.
+ * Used by the pre-receive hook which reads files from git objects.
+ */
+export function validateFileMap(files) {
+    const issues = [];
+    let filesChecked = 0;
+    const segmentKeys = new Set();
+    const schemaKeys = new Set();
+    const allSchemaFiles = [];
+    const allConfigs = [];
+    const parsedConfigs = [];
+    for (const [relPath, content] of files) {
+        const parts = relPath.split("/");
+        if (parts.length < 2)
+            continue;
+        const dir = parts[0];
+        const file = parts[parts.length - 1];
+        if (!KNOWN_DIRS.has(dir))
+            continue;
+        if (!file.endsWith(".json") || file.startsWith("."))
+            continue;
+        filesChecked++;
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (err) {
+            issues.push({ file: relPath, message: `Invalid JSON: ${err.message}`, severity: "error" });
+            continue;
+        }
+        if (SCHEMA_DIRS.has(dir)) {
+            const result = SchemaDocumentSchema.safeParse(parsed);
+            if (!result.success) {
+                for (const issue of result.error.issues) {
+                    issues.push({
+                        file: relPath,
+                        message: `Schema: ${issue.path.join(".")} - ${issue.message}`,
+                        severity: "error",
+                    });
+                }
+                continue;
+            }
+            const schemaKey = file.replace(/\.json$/, "");
+            schemaKeys.add(schemaKey);
+            validateKey(schemaKey, relPath, issues);
+            allSchemaFiles.push({ key: schemaKey, file: relPath });
+            continue;
+        }
+        const result = StoredConfigSchema.safeParse(parsed);
+        if (!result.success) {
+            for (const issue of result.error.issues) {
+                issues.push({
+                    file: relPath,
+                    message: `Schema: ${issue.path.join(".")} - ${issue.message}`,
+                    severity: "error",
+                });
+            }
+            continue;
+        }
+        const config = result.data;
+        const expectedKey = file.replace(/\.json$/, "");
+        if (config.key !== expectedKey) {
+            issues.push({
+                file: relPath,
+                message: `Key "${config.key}" does not match filename "${expectedKey}"`,
+                severity: "error",
+                suggestion: `Rename file to "${config.key}.json" or set key to "${expectedKey}"`,
+            });
+        }
+        validateKey(config.key, relPath, issues);
+        const expectedType = DIR_TO_TYPE[dir];
+        if (expectedType && config.type !== expectedType) {
+            issues.push({
+                file: relPath,
+                message: `Type "${config.type}" in directory "${dir}" (expected "${expectedType}")`,
+                severity: "error",
+                suggestion: `Move to "${typeToDir(config.type)}/" or change type to "${expectedType}"`,
+            });
+        }
+        if (config.type === "segment") {
+            if (config.valueType !== "bool") {
+                issues.push({ file: relPath, message: `Segment must have valueType "bool", got "${config.valueType}"`, severity: "error" });
+            }
+            if (config.sendToClientSdk) {
+                issues.push({ file: relPath, message: `Segment must have sendToClientSdk=false`, severity: "error" });
+            }
+            segmentKeys.add(config.key);
+        }
+        if (config.type === "log_level" && config.valueType !== "log_level") {
+            issues.push({ file: relPath, message: `Log level must have valueType "log_level", got "${config.valueType}"`, severity: "error" });
+        }
+        validateEnvironmentIds(config.environments, relPath, issues);
+        validateRules(config.default.rules, relPath, "default", config.valueType, issues);
+        for (const env of config.environments) {
+            validateRules(env.rules, relPath, `environments[${env.id}]`, config.valueType, issues);
+        }
+        allConfigs.push({ key: config.key, file: relPath });
+        parsedConfigs.push({ relPath, config, dir });
+    }
+    // Referential integrity
+    for (const { relPath, config } of parsedConfigs) {
+        const segRefs = collectSegmentReferences(config);
+        for (const ref of segRefs) {
+            if (!segmentKeys.has(ref)) {
+                issues.push({
+                    file: relPath,
+                    message: `References segment "${ref}" which does not exist`,
+                    severity: "error",
+                    suggestion: `Create segments/${ref}.json or remove the segment reference`,
+                });
+            }
+        }
+        if (config.schemaKey && !schemaKeys.has(config.schemaKey)) {
+            issues.push({
+                file: relPath,
+                message: `References schema "${config.schemaKey}" which does not exist`,
+                severity: "error",
+                suggestion: `Create schemas/${config.schemaKey}.json or schemas-protected/${config.schemaKey}.json, or remove schemaKey`,
+            });
+        }
+    }
+    // Duplicate keys
+    const keyToFiles = new Map();
+    for (const c of allConfigs) {
+        const existing = keyToFiles.get(c.key) || [];
+        existing.push(c.file);
+        keyToFiles.set(c.key, existing);
+    }
+    for (const [key, fileList] of keyToFiles) {
+        if (fileList.length > 1) {
+            issues.push({
+                file: fileList.join(", "),
+                message: `Duplicate key "${key}" found in multiple files`,
+                severity: "error",
+            });
+        }
+    }
+    const schemaKeyToFiles = new Map();
+    for (const schemaFile of allSchemaFiles) {
+        const existing = schemaKeyToFiles.get(schemaFile.key) || [];
+        existing.push(schemaFile.file);
+        schemaKeyToFiles.set(schemaFile.key, existing);
+    }
+    for (const [key, fileList] of schemaKeyToFiles) {
+        if (fileList.length > 1) {
+            issues.push({
+                file: fileList.join(", "),
+                message: `Duplicate schema key "${key}" found in multiple files`,
+                severity: "error",
+            });
+        }
+    }
+    const hasErrors = issues.some(i => i.severity === "error");
+    return { issues, filesChecked, valid: !hasErrors };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────
+function validateEnvironmentIds(environments, file, issues) {
+    for (const env of environments) {
+        if (UUID_RE.test(env.id)) {
+            issues.push({
+                file,
+                message: `Environment ID "${env.id}" is a UUID — must be a human-readable slug (e.g., "production", "my-ci-env")`,
+                severity: "error",
+                suggestion: `Replace the UUID with the environment's slugified name`,
+            });
+        }
+        else if (!SLUG_RE.test(env.id)) {
+            issues.push({
+                file,
+                message: `Environment ID "${env.id}" is not a valid slug (expected lowercase alphanumeric + dashes)`,
+                severity: "error",
+                suggestion: `Use a slugified name like "production" or "my-ci-env"`,
+            });
+        }
+    }
+}
+function validateKey(key, file, issues) {
+    if (key.length === 0) {
+        issues.push({ file, message: `Key is empty`, severity: "error" });
+    }
+    if (key.length > 512) {
+        issues.push({ file, message: `Key exceeds 512 characters (${key.length})`, severity: "error" });
+    }
+    if (key === "new") {
+        issues.push({ file, message: `Key cannot be "new" (reserved)`, severity: "error" });
+    }
+    if (/[/\\]/.test(key)) {
+        issues.push({ file, message: `Key contains slash or backslash`, severity: "error" });
+    }
+}
+function validateRules(rules, file, context, expectedValueType, issues) {
+    if (rules.length === 0) {
+        issues.push({ file, message: `${context}: no rules defined`, severity: "warning" });
+    }
+    for (let i = 0; i < rules.length; i++) {
+        const rule = rules[i];
+        const ruleCtx = `${context}.rules[${i}]`;
+        // Check value type consistency
+        // Skip weighted_values (contains its own values), schema, and provided (special types)
+        const SPECIAL_VALUE_TYPES = new Set(["weighted_values", "schema", "provided"]);
+        if (!SPECIAL_VALUE_TYPES.has(rule.value.type)) {
+            if (rule.value.type !== expectedValueType) {
+                issues.push({
+                    file,
+                    message: `${ruleCtx}: value type "${rule.value.type}" does not match config valueType "${expectedValueType}"`,
+                    severity: "error",
+                });
+            }
+        }
+        else if (rule.value.type === "weighted_values") {
+            // Validate weighted values
+            const wv = rule.value.value;
+            if (wv.weightedValues.length === 0) {
+                issues.push({ file, message: `${ruleCtx}: weighted values list is empty`, severity: "error" });
+            }
+            for (let j = 0; j < wv.weightedValues.length; j++) {
+                if (wv.weightedValues[j].value.type !== expectedValueType) {
+                    issues.push({
+                        file,
+                        message: `${ruleCtx}.weightedValues[${j}]: value type "${wv.weightedValues[j].value.type}" does not match config valueType "${expectedValueType}"`,
+                        severity: "error",
+                    });
+                }
+            }
+        }
+        // Check criteria
+        for (let j = 0; j < rule.criteria.length; j++) {
+            const criterion = rule.criteria[j];
+            const critCtx = `${ruleCtx}.criteria[${j}]`;
+            if (PROPERTY_OPERATORS.has(criterion.operator) && !criterion.propertyName) {
+                issues.push({
+                    file,
+                    message: `${critCtx}: operator "${criterion.operator}" requires propertyName`,
+                    severity: "error",
+                });
+            }
+            if (VALUE_REQUIRED_OPERATORS.has(criterion.operator) && !criterion.valueToMatch) {
+                issues.push({
+                    file,
+                    message: `${critCtx}: operator "${criterion.operator}" requires valueToMatch`,
+                    severity: "error",
+                });
+            }
+        }
+    }
+}
+function collectSegmentReferences(config) {
+    const refs = [];
+    function scanRules(rules) {
+        for (const rule of rules) {
+            for (const criterion of rule.criteria) {
+                if (SEGMENT_OPERATORS.has(criterion.operator) && criterion.valueToMatch) {
+                    // The segment key is stored in the valueToMatch string value
+                    const val = criterion.valueToMatch;
+                    if (val.type === "string") {
+                        refs.push(val.value);
+                    }
+                    else if (val.type === "string_list") {
+                        refs.push(...val.value);
+                    }
+                }
+            }
+        }
+    }
+    scanRules(config.default.rules);
+    for (const env of config.environments) {
+        scanRules(env.rules);
+    }
+    return refs;
+}
+function typeToDir(type) {
+    for (const [dir, t] of Object.entries(DIR_TO_TYPE)) {
+        if (t === type)
+            return dir;
+    }
+    return type;
+}
+// ── Output formatting ───────────────────────────────────────────────────
+export function formatResult(result) {
+    const lines = [];
+    if (result.valid) {
+        lines.push(`OK: ${result.filesChecked} files checked, no errors found.`);
+    }
+    else {
+        const errors = result.issues.filter(i => i.severity === "error");
+        const warnings = result.issues.filter(i => i.severity === "warning");
+        lines.push(`FAILED: ${errors.length} error(s), ${warnings.length} warning(s) in ${result.filesChecked} files.\n`);
+    }
+    // Group issues by file
+    const byFile = new Map();
+    for (const issue of result.issues) {
+        const existing = byFile.get(issue.file) || [];
+        existing.push(issue);
+        byFile.set(issue.file, existing);
+    }
+    for (const [file, fileIssues] of byFile) {
+        lines.push(`  ${file}:`);
+        for (const issue of fileIssues) {
+            const prefix = issue.severity === "error" ? "ERROR" : "WARN ";
+            lines.push(`    ${prefix}: ${issue.message}`);
+            if (issue.suggestion) {
+                lines.push(`           -> ${issue.suggestion}`);
+            }
+        }
+        lines.push("");
+    }
+    if (result.issues.length > 0) {
+        const warnings = result.issues.filter(i => i.severity === "warning");
+        if (warnings.length > 0 && result.valid) {
+            lines.push(`\n${warnings.length} warning(s) found.`);
+        }
+    }
+    return lines.join("\n");
+}