@faicad/faijs 0.19.0 → 0.22.2

package/dist/lang/metadata-extractor.js

@@ -20,6 +20,7 @@ import { isHostVarRef, isHostParamRef, isHostCallRef, isHostExprRef } from './ho
 import { ParseError } from './parse-error.js';
 import { fnv1a32 } from './fnv-hash.js';
 import { assertSecure } from './security-scanner.js';
+import { SCRIPT_UNIT_NAMES, UNIT_DIM, UNIT_SCALE, SCRIPT_UNIT_TO_NAME } from '../units.js';
 const CONTROL_FLOW_TYPES = new Set([
     'IfStatement', 'ForStatement', 'ForInStatement', 'ForOfStatement',
     'WhileStatement', 'DoWhileStatement', 'SwitchStatement', 'TryStatement',
@@ -36,8 +37,8 @@ function derivePackageName(specifier) {
     }
     return specifier.split('/')[0];
 }
-function numFold(v, usedParam = false) {
-    return Number.isFinite(v) ? { ok: true, value: v, usedParam } : { ok: false };
+function numFold(v, usedParam = false, usedUnit = false) {
+    return Number.isFinite(v) ? { ok: true, value: v, usedParam, usedUnit } : { ok: false };
 }
 function looseEq(a, b) {
     let x = a;
@@ -57,12 +58,23 @@ function looseEq(a, b) {
 function tryFoldConstExpr(node, symbols) {
     switch (node.type) {
         case 'Literal':
-            return { ok: true, value: node.value, usedParam: false };
+            return { ok: true, value: node.value, usedParam: false, usedUnit: false };
         case 'Identifier': {
+            // P7/D10.4: unit constants (MM, INCH, DEGREE, …) are recognized as
+            // foldable constants. Their values come from UNIT_SCALE (the single
+            // source of truth). The `usedUnit` flag is set so that `parseValueExpr`
+            // can mark the line as computed (host read-only downgrade), preventing
+            // the folded base value (e.g. 254) from being written back to source.
+            if (SCRIPT_UNIT_NAMES.has(node.name)) {
+                const unitName = SCRIPT_UNIT_TO_NAME[node.name];
+                if (unitName) {
+                    return { ok: true, value: UNIT_SCALE[unitName], usedParam: false, usedUnit: true };
+                }
+            }
             if (!symbols.paramNames.has(node.name))
                 return { ok: false };
             const v = symbols.paramValues.get(node.name);
-            return v === undefined ? { ok: false } : { ok: true, value: v, usedParam: true };
+            return v === undefined ? { ok: false } : { ok: true, value: v, usedParam: true, usedUnit: false };
         }
         case 'UnaryExpression': {
             const operand = tryFoldConstExpr(node.argument, symbols);
@@ -70,11 +82,11 @@ function tryFoldConstExpr(node, symbols) {
                 return { ok: false };
             const v = operand.value;
             switch (node.operator) {
-                case '-': return typeof v === 'number' ? numFold(-v, operand.usedParam) : { ok: false };
-                case '+': return typeof v === 'number' ? numFold(+v, operand.usedParam) : { ok: false };
-                case '!': return { ok: true, value: !v, usedParam: operand.usedParam };
-                case '~': return typeof v === 'number' ? { ok: true, value: ~v, usedParam: operand.usedParam } : { ok: false };
-                case 'typeof': return { ok: true, value: typeof v, usedParam: operand.usedParam };
+                case '-': return typeof v === 'number' ? numFold(-v, operand.usedParam, operand.usedUnit) : { ok: false };
+                case '+': return typeof v === 'number' ? numFold(+v, operand.usedParam, operand.usedUnit) : { ok: false };
+                case '!': return { ok: true, value: !v, usedParam: operand.usedParam, usedUnit: operand.usedUnit };
+                case '~': return typeof v === 'number' ? { ok: true, value: ~v, usedParam: operand.usedParam, usedUnit: operand.usedUnit } : { ok: false };
+                case 'typeof': return { ok: true, value: typeof v, usedParam: operand.usedParam, usedUnit: operand.usedUnit };
                 default: return { ok: false };
             }
         }
@@ -88,20 +100,21 @@ function tryFoldConstExpr(node, symbols) {
             const a = left.value;
             const b = right.value;
             const usedParam = left.usedParam || right.usedParam;
-            const numBin = (op) => typeof a === 'number' && typeof b === 'number' ? numFold(op(a, b), usedParam) : { ok: false };
+            const usedUnit = left.usedUnit || right.usedUnit;
+            const numBin = (op) => typeof a === 'number' && typeof b === 'number' ? numFold(op(a, b), usedParam, usedUnit) : { ok: false };
             const cmpBin = (op) => {
                 if (typeof a === 'number' && typeof b === 'number')
-                    return { ok: true, value: op(a, b), usedParam };
+                    return { ok: true, value: op(a, b), usedParam, usedUnit };
                 if (typeof a === 'string' && typeof b === 'string')
-                    return { ok: true, value: op(a, b), usedParam };
+                    return { ok: true, value: op(a, b), usedParam, usedUnit };
                 return { ok: false };
             };
             switch (node.operator) {
                 case '+': {
                     if (typeof a === 'number' && typeof b === 'number')
-                        return numFold(a + b, usedParam);
+                        return numFold(a + b, usedParam, usedUnit);
                     if (typeof a === 'string' || typeof b === 'string')
-                        return { ok: true, value: String(a) + String(b), usedParam };
+                        return { ok: true, value: String(a) + String(b), usedParam, usedUnit };
                     return { ok: false };
                 }
                 case '-': return numBin((x, y) => x - y);
@@ -113,10 +126,10 @@ function tryFoldConstExpr(node, symbols) {
                 case '<=': return cmpBin((x, y) => x <= y);
                 case '>': return cmpBin((x, y) => x > y);
                 case '>=': return cmpBin((x, y) => x >= y);
-                case '==': return { ok: true, value: looseEq(a, b), usedParam };
-                case '!=': return { ok: true, value: !looseEq(a, b), usedParam };
-                case '===': return { ok: true, value: a === b, usedParam };
-                case '!==': return { ok: true, value: a !== b, usedParam };
+                case '==': return { ok: true, value: looseEq(a, b), usedParam, usedUnit };
+                case '!=': return { ok: true, value: !looseEq(a, b), usedParam, usedUnit };
+                case '===': return { ok: true, value: a === b, usedParam, usedUnit };
+                case '!==': return { ok: true, value: a !== b, usedParam, usedUnit };
                 default: return { ok: false };
             }
         }
@@ -129,10 +142,11 @@ function tryFoldConstExpr(node, symbols) {
                 return { ok: false };
             const a = left.value;
             const usedParam = left.usedParam || right.usedParam;
+            const usedUnit = left.usedUnit || right.usedUnit;
             switch (node.operator) {
-                case '&&': return { ok: true, value: a ? right.value : left.value, usedParam };
-                case '||': return { ok: true, value: a ? left.value : right.value, usedParam };
-                case '??': return { ok: true, value: a === null ? right.value : left.value, usedParam };
+                case '&&': return { ok: true, value: a ? right.value : left.value, usedParam, usedUnit };
+                case '||': return { ok: true, value: a ? left.value : right.value, usedParam, usedUnit };
+                case '??': return { ok: true, value: a === null ? right.value : left.value, usedParam, usedUnit };
                 default: return { ok: false };
             }
         }
@@ -141,6 +155,7 @@ function tryFoldConstExpr(node, symbols) {
             const quasis = node.quasis;
             const exprs = node.expressions;
             let usedParam = false;
+            let usedUnit = false;
             for (let i = 0; i < quasis.length; i++) {
                 const cooked = quasis[i].value?.cooked;
                 parts.push(cooked ?? '');
@@ -149,10 +164,11 @@ function tryFoldConstExpr(node, symbols) {
                     if (!r.ok)
                         return { ok: false };
                     usedParam = usedParam || r.usedParam;
+                    usedUnit = usedUnit || r.usedUnit;
                     parts.push(String(r.value));
                 }
             }
-            return { ok: true, value: parts.join(''), usedParam };
+            return { ok: true, value: parts.join(''), usedParam, usedUnit };
         }
         case 'ConditionalExpression': {
             const test = tryFoldConstExpr(node.test, symbols);
@@ -161,7 +177,7 @@ function tryFoldConstExpr(node, symbols) {
             const chosen = tryFoldConstExpr(test.value ? node.consequent : node.alternate, symbols);
             if (!chosen.ok)
                 return { ok: false };
-            return { ok: true, value: chosen.value, usedParam: test.usedParam || chosen.usedParam };
+            return { ok: true, value: chosen.value, usedParam: test.usedParam || chosen.usedParam, usedUnit: test.usedUnit || chosen.usedUnit };
         }
         default:
             return { ok: false };
@@ -240,6 +256,11 @@ export function collectExprIdentifiers(node, symbols, line, params, refs, opts)
             else if (symbols.declared.has(name)) {
                 refs.add(name);
             }
+            else if (SCRIPT_UNIT_NAMES.has(name)) {
+                // P6/D7: unit constants (MM, INCH, DEGREE, …) are global read-only constants.
+                // Treat as a known reference — do not throw E_REFERENCE.
+                refs.add(name);
+            }
             else if (opts?.lenient === true) {
                 // lenient：未知标识符跳过（ArgSource 记录路径，保证提取不抛新错）
             }
@@ -310,6 +331,130 @@ function isExpressionNode(node) {
         return false;
     return true;
 }
+// ── P6/D8: 静态量纲校验（dimension pass） ──
+/**
+ * P6/D8 R4: Determine the dimension of an AST expression node.
+ *
+ * Returns the DimName if the expression can be statically determined to carry
+ * a dimension, `'bare'` for a bare number literal, or `null` if it cannot be
+ * determined (R5: pass through).
+ */
+function inferDim(node) {
+    if (!node)
+        return null;
+    switch (node.type) {
+        case 'Literal':
+            if (typeof node.value === 'number')
+                return 'bare';
+            return null;
+        case 'UnaryExpression':
+            if (node.operator === '-' || node.operator === '+' || node.operator === '~') {
+                return inferDim(node.argument);
+            }
+            return null;
+        case 'Identifier':
+            // Unit constant? → its dimension
+            if (SCRIPT_UNIT_NAMES.has(node.name)) {
+                const unitName = SCRIPT_UNIT_TO_NAME[node.name];
+                return unitName ? (UNIT_DIM[unitName] ?? null) : null;
+            }
+            // Declared variable or parameter → cannot determine (R5: pass through)
+            return null;
+        case 'BinaryExpression': {
+            const left = inferDim(node.left);
+            const right = inferDim(node.right);
+            switch (node.operator) {
+                case '*': {
+                    // number * unitConst → unit's dim; unitConst * number → same
+                    if (left === 'bare' && right && right !== 'bare')
+                        return right;
+                    if (right === 'bare' && left && left !== 'bare')
+                        return left;
+                    // both bare → bare (dimensionless multiply)
+                    if (left === 'bare' && right === 'bare')
+                        return 'bare';
+                    // both have dims → compound (length * length → area); pass through
+                    return null;
+                }
+                case '/': {
+                    // same dim / same dim → dimensionless (bare)
+                    if (left && right && left === right && left !== 'bare')
+                        return 'bare';
+                    // dim / bare → dim
+                    if (left && left !== 'bare' && right === 'bare')
+                        return left;
+                    // bare / dim → 1/dim (not a simple dim); pass through
+                    if (left === 'bare' && right && right !== 'bare')
+                        return null;
+                    if (left === 'bare' && right === 'bare')
+                        return 'bare';
+                    return null;
+                }
+                case '+':
+                case '-': {
+                    // Both sides must have the same dimension (R3)
+                    if (left === right)
+                        return left;
+                    // R3: if both sides are determinable but differ → mismatch.
+                    // But inferDim can't report errors — it returns the dim or null.
+                    // We return a special sentinel 'mismatch' to signal checkDim.
+                    if (left && right && left !== 'bare' && right !== 'bare' && left !== right) {
+                        return 'mismatch';
+                    }
+                    // If one is bare and the other has a dim → the result has that dim
+                    if (left === 'bare' && right && right !== 'bare')
+                        return right;
+                    if (right === 'bare' && left && left !== 'bare')
+                        return left;
+                    // If either is null (unknown), pass through (R5)
+                    return null;
+                }
+                default:
+                    return null;
+            }
+        }
+        case 'ParenthesizedExpression':
+            return inferDim(node.expression);
+        case 'ArrayExpression':
+            // vec3 — check first element for dimensionality
+            if (node.elements && node.elements.length > 0 && node.elements[0]) {
+                return inferDim(node.elements[0]);
+            }
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * P6/D8: Check if an argument expression has the required dimension.
+ *
+ * - R2: bare number literal on a dimensioned slot → E_DIM_BARE_NUMBER
+ * - R3: mismatched dimensions → E_DIM_MISMATCH
+ * - R5: cannot determine → pass (no error)
+ *
+ * Appends errors to ctx.dimErrors (does not throw — extraction continues).
+ */
+function checkDim(node, expectedDim, ctx) {
+    const actualDim = inferDim(node);
+    // R5: cannot determine → pass through
+    if (actualDim === null)
+        return;
+    // R3: mismatched dimensions within the expression (e.g. mm + degree)
+    if (actualDim === 'mismatch') {
+        ctx.dimErrors.push(new ParseError(`dimension mismatch in expression: "${ctx.sourceText.slice(node.start, node.end)}"`, lineOf(node), 'E_DIM_MISMATCH'));
+        return;
+    }
+    // R2: bare number on dimensioned slot
+    if (actualDim === 'bare') {
+        ctx.dimErrors.push(new ParseError(`bare number literal requires unit suffix (expected ${expectedDim}): "${ctx.sourceText.slice(node.start, node.end)}"`, lineOf(node), 'E_DIM_BARE_NUMBER'));
+        return;
+    }
+    // R3: dimension mismatch with expected
+    if (actualDim !== expectedDim) {
+        ctx.dimErrors.push(new ParseError(`dimension mismatch: expected ${expectedDim}, got ${actualDim} in "${ctx.sourceText.slice(node.start, node.end)}"`, lineOf(node), 'E_DIM_MISMATCH'));
+        return;
+    }
+}
 /**
  * 在折叠之前记录一条参数槽（ArgSource）。
  *
@@ -358,7 +503,10 @@ function parseValueExpr(node, ctx, path) {
         const r = tryFoldConstExpr(node, ctx.symbols);
         if (r.ok) {
             // F1-E1：仅折叠表达式引用参数才标 computed；纯字面量（负字面量）不标
-            if (r.usedParam)
+            // P7/D10.4: unit constants (usedUnit) also mark computed — the folded
+            // base value (e.g. 254 for `10 * INCH`) must NOT be written back to
+            // source code (would lose the unit and change geometry in non-base contexts).
+            if (r.usedParam || r.usedUnit)
                 ctx.computed.value = true;
             return r.value;
         }
@@ -948,6 +1096,8 @@ export function extractMetadata(code, options) {
     let terminalShapes;
     // P0-B：参数槽记录累积（跨语句共享，语句顺序追加）
     const argSources = [];
+    // P6/D8: dimension 校验错误累积（跨语句共享）
+    const allDimErrors = [];
     // ── 逐顶层语句分类 ──
     for (const stmtNode of bodyNodes) {
         const rawLine = lineOf(stmtNode);
@@ -961,6 +1111,8 @@ export function extractMetadata(code, options) {
             stmtId: asStmtId(`s${line}`),
             codeOffset,
             argSources,
+            opDims: options?.opDims,
+            dimErrors: allDimErrors,
         };
         switch (stmtNode.type) {
             case 'ImportDeclaration':
@@ -1097,16 +1249,22 @@ export function extractMetadata(code, options) {
             }
         }
     }
-    // P0-B：名称集合 = 参数 ∪ 已声明变量 ∪ 命名空间绑定 ∪ 本地函数名（字典序去重）。
+    // P0-B：名称集合 = 参数 ∪ 已声明变量 ∪ 命名空间绑定 ∪ 本地函数名 ∪ 单位常量（字典序去重）。
     // 宿主把「参数表达式」中的未知标识符当作参数名（期望名）处理时用它做联想。
+    // P6/D7：单位常量名（MM, INCH, DEGREE, …）加入 knownNames，使表达式实时校验通过。
     const names = [
         ...new Set([
             ...symbols.paramNames,
             ...symbols.declared,
             ...symbols.nsBindings.keys(),
             ...symbols.localFnParams.keys(),
+            ...SCRIPT_UNIT_NAMES,
         ]),
     ].sort();
+    // P6/D8: dimension 校验——如果有错误，抛出第一个（用 stage='dimension' 包装）
+    if (allDimErrors.length > 0) {
+        throw allDimErrors[0];
+    }
     return { lines, params, imports, functions, blocks, keep: symbols.keep, meta, terminalShapes, argSources, names };
 }
 function isLiteralValue(init) {
@@ -1206,6 +1364,14 @@ function classifyOpCall(call, line, vctx, opts) {
         throw new ParseError('expected <ns>.<op>(...) or local function call', line, 'E_STATEMENT');
     }
     const positional = parsePositionalArgs(call.arguments ?? [], vctx, line);
+    // P6/D8: dimension pass — check each argument against declared paramDims
+    if (vctx.opDims && call.arguments) {
+        // Build the full callee key for opDims lookup: 'cad.box' for default ns,
+        // 'otherNs.box' for non-default ns, or just 'box' for local fn.
+        const dimKey = namespace !== undefined ? `${namespace}.${callee}` : `${vctx.symbols.defaultNsName}.${callee}`;
+        const localKey = local ? callee : dimKey;
+        checkOpCallDims(call, local ? localKey : dimKey, vctx);
+    }
     const summary = buildLineSummary({
         callee,
         line,
@@ -1221,6 +1387,104 @@ function classifyOpCall(call, line, vctx, opts) {
     attachAssemblySummary(summary);
     return summary;
 }
+/**
+ * P6/D8: Check dimension constraints on op call arguments.
+ *
+ * Handles both object-form (`cad.box({ width: 10 * MM })`) and positional-form
+ * (`cad.box(10 * MM, 10 * MM, 10 * MM)`). For positional form, uses slotMap
+ * to map positional args to parameter names. For vec3 params, checks each element.
+ *
+ * Errors are accumulated in `ctx.dimErrors` (does not throw).
+ */
+function checkOpCallDims(call, calleeKey, ctx) {
+    const decl = ctx.opDims?.[calleeKey];
+    if (!decl || !decl.paramDims)
+        return;
+    const args = call.arguments ?? [];
+    if (args.length === 0)
+        return;
+    const slotMap = decl.slotMap;
+    const shapeArity = slotMap?.shapeArity ?? 0;
+    // ── Object form ──
+    // Look for an ObjectExpression arg that contains keys matching paramDims.
+    // It could be at position `shapeArity` (with slotMap) or at any position
+    // (without slotMap — e.g. fai_extrude(shape, { length: 5 })).
+    if (slotMap) {
+        const firstNonShape = args[shapeArity];
+        if (firstNonShape?.type === 'ObjectExpression') {
+            const hasDimKeys = firstNonShape.properties.some((p) => p?.type === 'Property' && p.key?.type === 'Identifier' && p.key.name in decl.paramDims);
+            if (hasDimKeys) {
+                for (const prop of firstNonShape.properties) {
+                    if (prop?.type !== 'Property')
+                        continue;
+                    const keyNode = prop.key;
+                    if (keyNode?.type !== 'Identifier')
+                        continue;
+                    const paramName = keyNode.name;
+                    const dim = decl.paramDims[paramName];
+                    if (!dim)
+                        continue;
+                    checkDim(prop.value, dim, ctx);
+                    if (slotMap.vec3Keys?.includes(paramName) && prop.value?.type === 'ArrayExpression') {
+                        for (const el of prop.value.elements ?? []) {
+                            if (el)
+                                checkDim(el, dim, ctx);
+                        }
+                    }
+                }
+                return;
+            }
+        }
+    }
+    else {
+        // No slotMap — scan all args for ObjectExpression with dim keys
+        for (const arg of args) {
+            if (arg?.type !== 'ObjectExpression')
+                continue;
+            const hasDimKeys = arg.properties.some((p) => p?.type === 'Property' && p.key?.type === 'Identifier' && p.key.name in decl.paramDims);
+            if (!hasDimKeys)
+                continue;
+            for (const prop of arg.properties) {
+                if (prop?.type !== 'Property')
+                    continue;
+                const keyNode = prop.key;
+                if (keyNode?.type !== 'Identifier')
+                    continue;
+                const paramName = keyNode.name;
+                const dim = decl.paramDims[paramName];
+                if (!dim)
+                    continue;
+                checkDim(prop.value, dim, ctx);
+            }
+            return;
+        }
+    }
+    // ── Positional form ──
+    if (!slotMap)
+        return;
+    const keys = slotMap.keys;
+    const vec3Keys = new Set(slotMap.vec3Keys ?? []);
+    let keyIdx = 0;
+    for (let i = shapeArity; i < args.length && keyIdx < keys.length; i++) {
+        const arg = args[i];
+        if (arg?.type === 'ObjectExpression')
+            break; // trailing options object
+        const paramName = keys[keyIdx];
+        const dim = decl.paramDims[paramName];
+        keyIdx++;
+        if (!dim)
+            continue;
+        if (vec3Keys.has(paramName) && arg?.type === 'ArrayExpression') {
+            for (const el of arg.elements ?? []) {
+                if (el)
+                    checkDim(el, dim, ctx);
+            }
+        }
+        else if (arg) {
+            checkDim(arg, dim, ctx);
+        }
+    }
+}
 /**
  * P2-f4：装配语句摘要附加（cad.assembly / asmN.do_assemble / asmN.solve）。
  *