@ifc-lite/cli 0.4.0 → 0.5.1

package/dist/commands/query.js

@@ -58,6 +58,24 @@ const STANDARD_QTO_MAP = {
         Qto_FootingBaseQuantities: ['Length', 'Width', 'Height', 'CrossSectionArea', 'OuterSurfaceArea', 'GrossVolume', 'NetVolume', 'GrossWeight', 'NetWeight'],
     },
 };
+/** Valid built-in grouping keys */
+const VALID_GROUP_BY_KEYS = ['type', 'storey', 'material'];
+/**
+ * B9/F6: Auto-prefix Ifc for --type if user omits it.
+ * Returns the corrected type string, or the original if already prefixed.
+ */
+function normalizeTypeName(typeStr) {
+    return typeStr.split(',').map(t => {
+        const trimmed = t.trim();
+        if (trimmed.startsWith('Ifc') || trimmed.startsWith('IFC') || trimmed.startsWith('ifc')) {
+            return trimmed;
+        }
+        // Auto-prefix with Ifc
+        const prefixed = 'Ifc' + trimmed;
+        process.stderr.write(`Note: Auto-corrected type "${trimmed}" → "${prefixed}"\n`);
+        return prefixed;
+    }).join(',');
+}
 /**
  * Parse a --where filter string into psetName, propName, operator, value.
  * Supported formats:
@@ -90,33 +108,100 @@ function parseWhereFilter(filter) {
     // No operator found — exists check
     return { psetName, propName: rest, operator: 'exists' };
 }
+/**
+ * B3/F1: Apply --where filter to entities, searching both property sets AND quantity sets.
+ * Falls back to quantity sets when a property set match is not found.
+ */
+function applyWhereFilter(entities, parsed, bim) {
+    return entities.filter(e => {
+        // First try property sets
+        const props = bim.properties(e.ref);
+        const pset = props.find((p) => p.name === parsed.psetName);
+        if (pset) {
+            const prop = pset.properties.find((p) => p.name === parsed.propName);
+            if (prop) {
+                if (parsed.operator === 'exists')
+                    return true;
+                return compareValues(prop.value, parsed.operator, parsed.value);
+            }
+        }
+        // B3: Also search quantity sets
+        const qsets = bim.quantities(e.ref);
+        const qset = qsets.find((q) => q.name === parsed.psetName);
+        if (qset) {
+            const qty = qset.quantities.find((q) => q.name === parsed.propName);
+            if (qty) {
+                if (parsed.operator === 'exists')
+                    return true;
+                return compareValues(qty.value, parsed.operator, parsed.value);
+            }
+        }
+        return false;
+    });
+}
+function compareValues(actual, operator, expected) {
+    if (expected === undefined)
+        return actual != null;
+    const normActual = normalizeBooleanValue(actual);
+    const normExpected = normalizeBooleanValue(expected);
+    switch (operator) {
+        case '=': return String(normActual) === String(normExpected);
+        case '!=': return String(normActual) !== String(normExpected);
+        case '>': return Number(normActual) > Number(normExpected);
+        case '<': return Number(normActual) < Number(normExpected);
+        case '>=': return Number(normActual) >= Number(normExpected);
+        case '<=': return Number(normActual) <= Number(normExpected);
+        case 'contains': return String(normActual).toLowerCase().includes(String(normExpected).toLowerCase());
+        default: return false;
+    }
+}
+function normalizeBooleanValue(value) {
+    if (value === true || value === '.T.' || value === 'true' || value === 'TRUE')
+        return 'true';
+    if (value === false || value === '.F.' || value === 'false' || value === 'FALSE')
+        return 'false';
+    return value;
+}
+/**
+ * Helper: get a quantity value for an entity by name (searching all qsets).
+ */
+function getQuantityValue(bim, ref, quantityName) {
+    const qsets = bim.quantities(ref);
+    for (const qset of qsets) {
+        for (const q of qset.quantities) {
+            if (q.name === quantityName)
+                return Number(q.value) || 0;
+        }
+    }
+    return null;
+}
 export async function queryCommand(args) {
     const filePath = args.find(a => !a.startsWith('-'));
     if (!filePath)
         fatal('Usage: ifc-lite query <file.ifc> --type IfcWall [--props] [--limit N]');
-    const type = getFlag(args, '--type');
+    let type = getFlag(args, '--type');
     const limit = getFlag(args, '--limit');
     const offset = getFlag(args, '--offset');
     const propFilter = getFlag(args, '--where');
-    const showProps = hasFlag(args, '--props');
-    const showQuantities = hasFlag(args, '--quantities');
-    const showMaterials = hasFlag(args, '--materials');
-    const showClassifications = hasFlag(args, '--classifications');
-    const showAttributes = hasFlag(args, '--attributes');
-    const showRelationships = hasFlag(args, '--relationships');
-    const showTypeProps = hasFlag(args, '--type-props');
-    const showDocuments = hasFlag(args, '--documents');
-    const showAll = hasFlag(args, '--all');
     const jsonOutput = hasFlag(args, '--json');
     const countOnly = hasFlag(args, '--count');
     const spatial = hasFlag(args, '--spatial');
     const sumQuantity = getFlag(args, '--sum');
+    const avgQuantity = getFlag(args, '--avg');
+    const minQuantity = getFlag(args, '--min');
+    const maxQuantity = getFlag(args, '--max');
+    const sortBy = getFlag(args, '--sort');
+    const descSort = hasFlag(args, '--desc');
     const storeyFilter = getFlag(args, '--storey');
     const quantityNames = hasFlag(args, '--quantity-names');
     const propertyNames = hasFlag(args, '--property-names');
     const uniqueProp = getFlag(args, '--unique');
     const groupBy = getFlag(args, '--group-by');
     const spatialSummary = hasFlag(args, '--summary');
+    // B9/F6: Auto-prefix Ifc for --type
+    if (type) {
+        type = normalizeTypeName(type);
+    }
     const { bim } = await createHeadlessContext(filePath);
     // --quantity-names: list available quantities per entity type
     if (quantityNames) {
@@ -252,24 +337,46 @@ export async function queryCommand(args) {
         }
         return;
     }
-    // --unique: distinct values for a property path (PsetName.PropName)
+    // B6/F8: --unique: distinct values for a property path, material, or storey
     if (uniqueProp) {
         const targetType = type;
         if (!targetType)
-            fatal('--unique requires --type (e.g., --type IfcWall --unique PsetName.PropName)');
-        const dotIdx = uniqueProp.indexOf('.');
-        if (dotIdx <= 0)
-            fatal(`Invalid --unique path: "${uniqueProp}". Expected: PsetName.PropName`);
-        const psetName = uniqueProp.slice(0, dotIdx);
-        const propName = uniqueProp.slice(dotIdx + 1);
+            fatal('--unique requires --type (e.g., --type IfcWall --unique material)');
         const entities = bim.query().byType(...targetType.split(',')).toArray();
         const valueCounts = new Map();
-        for (const e of entities) {
-            const psets = bim.properties(e.ref);
-            const pset = psets.find((p) => p.name === psetName);
-            const prop = pset?.properties?.find((p) => p.name === propName);
-            const val = prop?.value != null ? String(prop.value) : '(no value)';
-            valueCounts.set(val, (valueCounts.get(val) ?? 0) + 1);
+        if (uniqueProp === 'material') {
+            // B6: Support --unique material
+            for (const e of entities) {
+                const mat = bim.materials(e.ref);
+                const val = mat?.materials?.[0] ?? mat?.name ?? '(no material)';
+                valueCounts.set(val, (valueCounts.get(val) ?? 0) + 1);
+            }
+        }
+        else if (uniqueProp === 'storey') {
+            for (const e of entities) {
+                const storey = bim.storey(e.ref);
+                const val = storey?.name ?? '(no storey)';
+                valueCounts.set(val, (valueCounts.get(val) ?? 0) + 1);
+            }
+        }
+        else if (uniqueProp === 'type') {
+            for (const e of entities) {
+                valueCounts.set(e.type, (valueCounts.get(e.type) ?? 0) + 1);
+            }
+        }
+        else {
+            const dotIdx = uniqueProp.indexOf('.');
+            if (dotIdx <= 0)
+                fatal(`Invalid --unique path: "${uniqueProp}". Expected: PsetName.PropName, or one of: material, storey, type`);
+            const psetName = uniqueProp.slice(0, dotIdx);
+            const propName = uniqueProp.slice(dotIdx + 1);
+            for (const e of entities) {
+                const psets = bim.properties(e.ref);
+                const pset = psets.find((p) => p.name === psetName);
+                const prop = pset?.properties?.find((p) => p.name === propName);
+                const val = prop?.value != null ? String(prop.value) : '(no value)';
+                valueCounts.set(val, (valueCounts.get(val) ?? 0) + 1);
+            }
         }
         if (jsonOutput) {
             const result = {};
@@ -293,7 +400,7 @@ export async function queryCommand(args) {
         if (storeys.length > 0) {
             for (const storey of storeys) {
                 const contained = bim.contains(storey.ref);
-                tree[storey.name || `Storey #${storey.ref.expressId}`] = contained.map(e => ({
+                tree[storey.name || `Storey #${storey.ref.expressId}`] = contained.map((e) => ({
                     type: e.type,
                     name: e.name,
                     globalId: e.globalId,
@@ -305,7 +412,7 @@ export async function queryCommand(args) {
             const buildings = bim.query().byType('IfcBuilding').toArray();
             for (const building of buildings) {
                 const contained = bim.contains(building.ref);
-                tree[building.name || `Building #${building.ref.expressId}`] = contained.map(e => ({
+                tree[building.name || `Building #${building.ref.expressId}`] = contained.map((e) => ({
                     type: e.type,
                     name: e.name,
                     globalId: e.globalId,
@@ -353,69 +460,126 @@ export async function queryCommand(args) {
     // --storey filter: restrict to entities in a specific storey
     if (storeyFilter) {
         const storeys = bim.storeys();
-        const matchedStorey = storeys.find(s => s.name === storeyFilter ||
+        const matchedStorey = storeys.find((s) => s.name === storeyFilter ||
             s.name.toLowerCase().includes(storeyFilter.toLowerCase()) ||
             String(s.ref.expressId) === storeyFilter);
         if (!matchedStorey) {
-            const names = storeys.map(s => s.name).filter(Boolean).join(', ');
+            const names = storeys.map((s) => s.name).filter(Boolean).join(', ');
             fatal(`Storey "${storeyFilter}" not found. Available: ${names || '(none)'}`);
         }
         const contained = bim.contains(matchedStorey.ref);
-        const storeyIds = new Set(contained.map(e => e.ref.expressId));
+        const storeyIds = new Set(contained.map((e) => e.ref.expressId));
         // Post-filter: only keep entities that are in this storey
         const baseEntities = q.toArray();
-        const storeyEntities = baseEntities.filter(e => storeyIds.has(e.ref.expressId));
-        // Apply --where filter to storey-filtered entities
+        let storeyEntities = baseEntities.filter((e) => storeyIds.has(e.ref.expressId));
+        // B3: Apply --where filter to storey-filtered entities (with quantity support)
         if (propFilter) {
             const parsed = parseWhereFilter(propFilter);
-            // Re-apply via manual filtering since we've already resolved entities
-            const finalEntities = storeyEntities.filter(e => {
-                const props = bim.properties(e.ref);
-                const pset = props.find(p => p.name === parsed.psetName);
-                if (!pset)
-                    return false;
-                const prop = pset.properties.find((p) => p.name === parsed.propName);
-                if (!prop)
-                    return false;
-                if (parsed.operator === 'exists')
-                    return true;
-                return String(prop.value) === String(parsed.value);
-            });
-            if (sumQuantity) {
-                outputSum(finalEntities, sumQuantity, bim, jsonOutput);
-                return;
-            }
-            if (countOnly) {
-                outputCount(finalEntities.length, jsonOutput);
-                return;
-            }
-            outputEntities(finalEntities, args, bim, jsonOutput);
+            storeyEntities = applyWhereFilter(storeyEntities, parsed, bim);
+        }
+        const sAggQty = sumQuantity ?? avgQuantity ?? minQuantity ?? maxQuantity;
+        const sAggMode = sumQuantity ? 'sum' : avgQuantity ? 'avg' : minQuantity ? 'min' : maxQuantity ? 'max' : undefined;
+        if (groupBy && sAggQty) {
+            outputGroupBy(storeyEntities, groupBy, sAggQty, bim, jsonOutput, limit ? parseInt(limit, 10) : undefined, sAggMode);
             return;
         }
         if (sumQuantity) {
             outputSum(storeyEntities, sumQuantity, bim, jsonOutput);
             return;
         }
+        if (avgQuantity) {
+            outputAggregation(storeyEntities, avgQuantity, 'avg', bim, jsonOutput);
+            return;
+        }
+        if (minQuantity) {
+            outputAggregation(storeyEntities, minQuantity, 'min', bim, jsonOutput);
+            return;
+        }
+        if (maxQuantity) {
+            outputAggregation(storeyEntities, maxQuantity, 'max', bim, jsonOutput);
+            return;
+        }
+        if (groupBy) {
+            outputGroupBy(storeyEntities, groupBy, undefined, bim, jsonOutput, limit ? parseInt(limit, 10) : undefined);
+            return;
+        }
         if (countOnly) {
             outputCount(storeyEntities.length, jsonOutput);
             return;
         }
+        if (sortBy) {
+            storeyEntities = sortEntities(storeyEntities, sortBy, descSort, bim);
+        }
         outputEntities(storeyEntities, args, bim, jsonOutput);
         return;
     }
-    // --where filter with proper syntax validation
+    // --where filter: search both property sets and quantity sets (B3)
     if (propFilter) {
         const parsed = parseWhereFilter(propFilter);
-        q = q.where(parsed.psetName, parsed.propName, parsed.operator, parsed.value);
+        // We need to do manual filtering to support quantity sets
+        let entities = q.toArray();
+        entities = applyWhereFilter(entities, parsed, bim);
+        const whereAggQty = sumQuantity ?? avgQuantity ?? minQuantity ?? maxQuantity;
+        const whereAggMode = sumQuantity ? 'sum' : avgQuantity ? 'avg' : minQuantity ? 'min' : maxQuantity ? 'max' : undefined;
+        // When grouping, don't slice entities — pass limit as groupLimit instead
+        if (groupBy && whereAggQty) {
+            outputGroupBy(entities, groupBy, whereAggQty, bim, jsonOutput, limit ? parseInt(limit, 10) : undefined, whereAggMode);
+            return;
+        }
+        if (groupBy) {
+            outputGroupBy(entities, groupBy, undefined, bim, jsonOutput, limit ? parseInt(limit, 10) : undefined);
+            return;
+        }
+        // Aggregations operate on the full filtered set (no offset/limit)
+        if (sumQuantity) {
+            outputSum(entities, sumQuantity, bim, jsonOutput);
+            return;
+        }
+        if (avgQuantity) {
+            outputAggregation(entities, avgQuantity, 'avg', bim, jsonOutput);
+            return;
+        }
+        if (minQuantity) {
+            outputAggregation(entities, minQuantity, 'min', bim, jsonOutput);
+            return;
+        }
+        if (maxQuantity) {
+            outputAggregation(entities, maxQuantity, 'max', bim, jsonOutput);
+            return;
+        }
+        // Apply offset/limit only for non-aggregation, non-group paths
+        if (offset)
+            entities = entities.slice(parseInt(offset, 10));
+        if (limit)
+            entities = entities.slice(0, parseInt(limit, 10));
+        if (countOnly) {
+            outputCount(entities.length, jsonOutput);
+            return;
+        }
+        if (sortBy) {
+            entities = sortEntities(entities, sortBy, descSort, bim);
+        }
+        outputEntities(entities, args, bim, jsonOutput);
+        return;
     }
-    if (limit)
+    if (limit && !groupBy)
         q = q.limit(parseInt(limit, 10));
     if (offset)
         q = q.offset(parseInt(offset, 10));
-    // --group-by + --sum combo: aggregate per group
-    if (groupBy && sumQuantity) {
+    // B11: Validate --group-by key
+    if (groupBy) {
+        if (!VALID_GROUP_BY_KEYS.includes(groupBy) && !groupBy.includes('.')) {
+            fatal(`Unknown grouping "${groupBy}". Valid options: ${VALID_GROUP_BY_KEYS.join(', ')}, or PsetName.PropName`);
+        }
+    }
+    // Detect aggregation quantity and mode for --group-by combos
+    const aggQuantity = sumQuantity ?? avgQuantity ?? minQuantity ?? maxQuantity;
+    const aggMode = sumQuantity ? 'sum' : avgQuantity ? 'avg' : minQuantity ? 'min' : maxQuantity ? 'max' : undefined;
+    // --group-by + aggregation combo: aggregate per group
+    if (groupBy && aggQuantity) {
         const entities = q.toArray();
-        outputGroupBy(entities, groupBy, sumQuantity, bim, jsonOutput);
+        // B12: pass limit to outputGroupBy to limit groups, not entities
+        outputGroupBy(entities, groupBy, aggQuantity, bim, jsonOutput, limit ? parseInt(limit, 10) : undefined, aggMode);
         return;
     }
     // --sum mode: aggregate a quantity across matched entities
@@ -424,10 +588,29 @@ export async function queryCommand(args) {
         outputSum(entities, sumQuantity, bim, jsonOutput);
         return;
     }
+    // B7/F2: --avg mode
+    if (avgQuantity) {
+        const entities = q.toArray();
+        outputAggregation(entities, avgQuantity, 'avg', bim, jsonOutput);
+        return;
+    }
+    // B7/F2: --min mode
+    if (minQuantity) {
+        const entities = q.toArray();
+        outputAggregation(entities, minQuantity, 'min', bim, jsonOutput);
+        return;
+    }
+    // B7/F2: --max mode
+    if (maxQuantity) {
+        const entities = q.toArray();
+        outputAggregation(entities, maxQuantity, 'max', bim, jsonOutput);
+        return;
+    }
     // --group-by mode: pivot table grouped by a property or 'type'/'material'
     if (groupBy) {
         const entities = q.toArray();
-        outputGroupBy(entities, groupBy, undefined, bim, jsonOutput);
+        // B12: pass limit to outputGroupBy to limit groups, not entities
+        outputGroupBy(entities, groupBy, undefined, bim, jsonOutput, limit ? parseInt(limit, 10) : undefined);
         return;
     }
     if (countOnly) {
@@ -435,7 +618,11 @@ export async function queryCommand(args) {
         outputCount(count, jsonOutput);
         return;
     }
-    const entities = q.toArray();
+    let entities = q.toArray();
+    // F7: --sort by quantity
+    if (sortBy) {
+        entities = sortEntities(entities, sortBy, descSort, bim);
+    }
     outputEntities(entities, args, bim, jsonOutput);
 }
 function outputCount(count, jsonOutput) {
@@ -473,6 +660,33 @@ function outputSum(entities, quantityName, bim, jsonOutput) {
             }
         }
     }
+    // B10: Better error when quantity not found
+    if (matched === 0 && entities.length > 0) {
+        const availableNames = new Set();
+        for (const [key] of allQuantityNames) {
+            availableNames.add(key.split('.').pop());
+        }
+        if (jsonOutput) {
+            printJson({
+                quantity: quantityName,
+                total: 0,
+                matchedEntities: 0,
+                totalEntities: entities.length,
+                error: `Quantity "${quantityName}" not found in any of the ${entities.length} entities.`,
+                availableQuantities: [...availableNames],
+                hint: 'Use --quantity-names --type <Type> to see all available quantities with details.',
+            });
+        }
+        else {
+            process.stdout.write(`0\n`);
+            process.stderr.write(`Quantity "${quantityName}" not found in any of the ${entities.length} entities.\n`);
+            if (availableNames.size > 0) {
+                process.stderr.write(`Available quantities: ${[...availableNames].join(', ')}\n`);
+            }
+            process.stderr.write(`Use --quantity-names --type <Type> to see all available quantities.\n`);
+        }
+        return;
+    }
     // Check for ambiguous area/volume quantities and warn
     const similarNames = [...allQuantityNames.entries()]
         .filter(([key]) => {
@@ -518,7 +732,133 @@ function outputSum(entities, quantityName, bim, jsonOutput) {
         }
     }
 }
-function outputGroupBy(entities, groupByKey, sumQuantity, bim, jsonOutput) {
+/**
+ * B7/F2: --avg, --min, --max aggregation functions.
+ */
+function outputAggregation(entities, quantityName, mode, bim, jsonOutput) {
+    let total = 0;
+    let matched = 0;
+    let minVal = Infinity;
+    let maxVal = -Infinity;
+    let minEntity = null;
+    let maxEntity = null;
+    for (const e of entities) {
+        const val = getQuantityValue(bim, e.ref, quantityName);
+        if (val !== null) {
+            total += val;
+            matched++;
+            if (val < minVal) {
+                minVal = val;
+                minEntity = e;
+            }
+            if (val > maxVal) {
+                maxVal = val;
+                maxEntity = e;
+            }
+        }
+    }
+    // B10: quantity not found
+    if (matched === 0) {
+        if (jsonOutput) {
+            printJson({ quantity: quantityName, error: `Quantity "${quantityName}" not found.`, hint: 'Use --quantity-names --type <Type> to see available quantities.' });
+        }
+        else {
+            process.stderr.write(`Quantity "${quantityName}" not found in any of the ${entities.length} entities.\n`);
+            process.stderr.write(`Use --quantity-names --type <Type> to see all available quantities.\n`);
+        }
+        return;
+    }
+    const avg = total / matched;
+    const label = mode.charAt(0).toUpperCase() + mode.slice(1);
+    if (jsonOutput) {
+        const result = { quantity: quantityName, matchedEntities: matched, totalEntities: entities.length };
+        if (mode === 'avg') {
+            result.average = avg;
+        }
+        else if (mode === 'min') {
+            result.min = minVal;
+            if (minEntity)
+                result.entity = { Name: minEntity.name, Type: minEntity.type, GlobalId: minEntity.globalId };
+        }
+        else {
+            result.max = maxVal;
+            if (maxEntity)
+                result.entity = { Name: maxEntity.name, Type: maxEntity.type, GlobalId: maxEntity.globalId };
+        }
+        printJson(result);
+    }
+    else {
+        if (mode === 'avg') {
+            process.stdout.write(`${avg}\n`);
+            process.stderr.write(`${label} ${quantityName}: ${avg.toFixed(4)} (${matched} entities)\n`);
+        }
+        else if (mode === 'min') {
+            process.stdout.write(`${minVal}\n`);
+            process.stderr.write(`${label} ${quantityName}: ${minVal} (${minEntity?.name ?? 'unknown'})\n`);
+        }
+        else {
+            process.stdout.write(`${maxVal}\n`);
+            process.stderr.write(`${label} ${quantityName}: ${maxVal} (${maxEntity?.name ?? 'unknown'})\n`);
+        }
+    }
+}
+/**
+ * F7: Sort entities by quantity, attribute, or property value.
+ * Supports: quantity names, entity attributes (name/type/globalId), PsetName.PropName
+ */
+function sortEntities(entities, sortBy, descending, bim) {
+    const ATTR_KEYS = ['name', 'type', 'globalId', 'globalid', 'description', 'objectType', 'objecttype'];
+    const isAttr = ATTR_KEYS.includes(sortBy) || ATTR_KEYS.includes(sortBy.toLowerCase());
+    const isDotted = sortBy.includes('.');
+    return entities.slice().sort((a, b) => {
+        let valA;
+        let valB;
+        if (isAttr) {
+            // Sort by entity attribute (alphabetical)
+            const key = sortBy.toLowerCase() === 'globalid' ? 'globalId'
+                : sortBy.toLowerCase() === 'objecttype' ? 'objectType'
+                    : sortBy.toLowerCase();
+            valA = a[key] ?? '';
+            valB = b[key] ?? '';
+            const cmp = String(valA).localeCompare(String(valB));
+            return descending ? -cmp : cmp;
+        }
+        else if (isDotted) {
+            // Sort by PsetName.PropName
+            const [psetName, propName] = sortBy.split('.', 2);
+            const getVal = (e) => {
+                const props = bim.properties(e.ref);
+                const pset = props.find((p) => p.name === psetName);
+                const prop = pset?.properties?.find((p) => p.name === propName);
+                if (prop?.value != null)
+                    return prop.value;
+                // Also check quantity sets
+                const qsets = bim.quantities(e.ref);
+                const qset = qsets.find((q) => q.name === psetName);
+                const qty = qset?.quantities?.find((q) => q.name === propName);
+                return qty?.value ?? null;
+            };
+            valA = getVal(a);
+            valB = getVal(b);
+            if (typeof valA === 'number' && typeof valB === 'number') {
+                return descending ? valB - valA : valA - valB;
+            }
+            const cmp = String(valA ?? '').localeCompare(String(valB ?? ''));
+            return descending ? -cmp : cmp;
+        }
+        else {
+            // Sort by quantity name (numeric)
+            valA = getQuantityValue(bim, a.ref, sortBy) ?? 0;
+            valB = getQuantityValue(bim, b.ref, sortBy) ?? 0;
+            return descending ? valB - valA : valA - valB;
+        }
+    });
+}
+function outputGroupBy(entities, groupByKey, sumQuantity, bim, jsonOutput, groupLimit, aggMode) {
+    // B11: Validate group-by key
+    if (!VALID_GROUP_BY_KEYS.includes(groupByKey) && !groupByKey.includes('.')) {
+        fatal(`Unknown grouping "${groupByKey}". Valid options: ${VALID_GROUP_BY_KEYS.join(', ')}, or PsetName.PropName`);
+    }
     const groups = new Map();
     for (const e of entities) {
         let groupValue;
@@ -531,7 +871,7 @@ function outputGroupBy(entities, groupByKey, sumQuantity, bim, jsonOutput) {
         }
         else if (groupByKey === 'material') {
             const mat = bim.materials(e.ref);
-            groupValue = mat?.materials?.[0]?.name ?? mat?.name ?? '(no material)';
+            groupValue = mat?.materials?.[0] ?? mat?.name ?? '(no material)';
         }
         else if (groupByKey.includes('.')) {
             // PsetName.PropName
@@ -552,48 +892,75 @@ function outputGroupBy(entities, groupByKey, sumQuantity, bim, jsonOutput) {
             groups.set(groupValue, [e]);
         }
     }
-    // Compute per-group sum if --sum is specified alongside --group-by
-    const groupSums = new Map();
+    // Compute per-group aggregation if a quantity is specified alongside --group-by
+    const mode = aggMode ?? 'sum';
+    const groupAgg = new Map();
     if (sumQuantity) {
         for (const [key, groupEntities] of groups) {
             let sum = 0;
+            let count = 0;
+            let minVal = Infinity;
+            let maxVal = -Infinity;
             for (const e of groupEntities) {
-                const qsets = bim.quantities(e.ref);
-                for (const qset of qsets) {
-                    for (const q of qset.quantities) {
-                        if (q.name === sumQuantity)
-                            sum += Number(q.value) || 0;
-                    }
+                const val = getQuantityValue(bim, e.ref, sumQuantity);
+                if (val !== null) {
+                    sum += val;
+                    count++;
+                    if (val < minVal)
+                        minVal = val;
+                    if (val > maxVal)
+                        maxVal = val;
                 }
             }
-            groupSums.set(key, sum);
+            if (mode === 'avg')
+                groupAgg.set(key, count > 0 ? sum / count : 0);
+            else if (mode === 'min')
+                groupAgg.set(key, count > 0 ? minVal : 0);
+            else if (mode === 'max')
+                groupAgg.set(key, count > 0 ? maxVal : 0);
+            else
+                groupAgg.set(key, sum);
         }
     }
+    const modeLabel = mode === 'sum' ? 'sum' : mode;
     if (jsonOutput) {
         const result = {};
-        for (const [key, groupEntities] of groups) {
+        let entries = [...groups.entries()];
+        // B12: --limit limits groups, not entities
+        if (groupLimit)
+            entries = entries.slice(0, groupLimit);
+        for (const [key, groupEntities] of entries) {
             const entry = { count: groupEntities.length };
             if (sumQuantity)
-                entry[sumQuantity] = groupSums.get(key) ?? 0;
+                entry[sumQuantity] = groupAgg.get(key) ?? 0;
+            if (sumQuantity && mode !== 'sum')
+                entry.aggregation = mode;
             result[key] = entry;
         }
         printJson(result);
     }
     else {
-        const sorted = [...groups.entries()].sort((a, b) => b[1].length - a[1].length);
-        process.stdout.write(`\nGrouped by ${groupByKey}${sumQuantity ? ` (sum: ${sumQuantity})` : ''}:\n\n`);
+        let sorted = [...groups.entries()].sort((a, b) => b[1].length - a[1].length);
+        // B12: --limit limits groups, not entities
+        if (groupLimit)
+            sorted = sorted.slice(0, groupLimit);
+        process.stdout.write(`\nGrouped by ${groupByKey}${sumQuantity ? ` (${modeLabel}: ${sumQuantity})` : ''}:\n\n`);
         for (const [key, groupEntities] of sorted) {
             if (sumQuantity) {
-                const sum = groupSums.get(key) ?? 0;
-                process.stdout.write(`  ${key}:  ${groupEntities.length} elements,  ${sumQuantity}: ${sum}\n`);
+                const agg = groupAgg.get(key) ?? 0;
+                process.stdout.write(`  ${key}:  ${groupEntities.length} elements,  ${sumQuantity} ${modeLabel}: ${mode === 'avg' ? agg.toFixed(4) : agg}\n`);
             }
             else {
                 process.stdout.write(`  ${key}: ${groupEntities.length}\n`);
             }
         }
         if (sumQuantity) {
-            const grandTotal = [...groupSums.values()].reduce((a, b) => a + b, 0);
-            process.stdout.write(`\n  Total: ${entities.length} entities in ${groups.size} groups, ${sumQuantity}: ${grandTotal}\n\n`);
+            const grandTotal = [...groupAgg.values()].reduce((a, b) => a + b, 0);
+            process.stdout.write(`\n  Total: ${entities.length} entities in ${groups.size} groups\n`);
+            if (grandTotal === 0 && entities.length > 0) {
+                process.stderr.write(`\n  Warning: All ${sumQuantity} values are 0. The file may not contain quantity data for this property.\n`);
+            }
+            process.stdout.write('\n');
         }
         else {
             process.stdout.write(`\n  Total: ${entities.length} entities in ${groups.size} groups\n\n`);