@faicad/faijs 0.13.2 → 0.16.0

package/dist/lang/keep.js

@@ -1,226 +0,0 @@
-/**
- * keep — 统一内外 keep 机制的语义集中点（L0 零依赖）
- *
- *
- * keep 机制的两面：
- * - 调用点声明：`cad.op(input, { keep: [a, b], keepHidden: true })`（UI / AI / 用户）
- * - 函数体声明：`exec.keep(...shapes)` / `exec.keepHidden(...shapes)`（库作者）
- *
- * 优先级：调用点 > 函数体（resolveKeep 先铺函数体声明，再用调用点覆盖写入）。
- *
- * 本文件是 keep 语义的唯一集中点：parseUserKeep / withoutKeepDirectives /
- * resolveKeep / validateKeepDirectives。消费方：compile（发射剥离）、
- * module-executor（statementKey）、terminal-dag（消费判定）、runtime.check（校验）。
- *
- * L0 边界：仅依赖 ./types 与 ../identity，零运行时依赖。
- */
-import { isVarRef, isCallRef, isExprRef, statementInputs } from './types.js';
-import { asPartName } from '../identity.js';
-// ── 剥离 ──
-/**
- * 剥离调用点 keep 指令（`keep` / `keepHidden` 两键）。
- *
- * 编译发射与 statementKey 必须剥离（设计 §7.1/§7.2）：keep 透传给库函数会
- * 挤占 params 槽 / 被当 Shape 传入（union/split 的 `...rest`）。
- */
-/**
- * Strip the call-site keep directives (`keep` / `keepHidden` keys). Both
- * compile emission and statement-key computation must strip them (design
- * §7.1/§7.2): passing keep through would crowd the params slot or be treated as
- * a Shape argument (union/split `...rest`).
- * @param args - the statement's args object, or undefined.
- * @returns the args with the keep and keepHidden keys removed.
- */
-export function withoutKeepDirectives(args) {
-    if (!args)
-        return {};
-    const { keep: _keep, keepHidden: _keepHidden, ...rest } = args;
-    return rest;
-}
-/** 判定 ArgIR 是否为"纯对象"位置实参（非 IR 变体、非数组的普通对象）。 */
-function isPlainObjectArg(arg) {
-    return (arg !== null &&
-        typeof arg === 'object' &&
-        !Array.isArray(arg) &&
-        !isVarRef(arg) &&
-        !isCallRef(arg) &&
-        !isExprRef(arg) &&
-        !('$param' in arg));
-}
-/**
- * 剥离位置实参槽中的 keep 指令（true-JS-subset 方案 §4.1）：keep/keepHidden 键
- * 存在于尾随纯对象位置实参（选项槽）中，发射/序列化前从该对象剥离。
- * 与 withoutKeepDirectives 同语义，只是载体从 args 记录变为 positional 尾随对象。
- * @param positional - the statement's positional argument slot.
- * @returns a copy of the positional slot with keep/keepHidden removed from the trailing plain object.
- */
-export function withoutKeepDirectivesFromPositional(positional) {
-    const last = positional[positional.length - 1];
-    if (!isPlainObjectArg(last))
-        return positional;
-    const obj = last;
-    const stripped = Object.fromEntries(Object.entries(obj).filter(([k]) => k !== 'keep' && k !== 'keepHidden'));
-    return [...positional.slice(0, -1), stripped];
-}
-// ── 解析 ──
-/**
- * 解析单条 keep 条目 → { target, hidden }；形态非法返回 undefined（validate 负责报错）。
- * hidden 为三态：undefined = 未指定（交由语句级 keepHidden 默认）；true/false = 显式指定。
- */
-function parseKeepEntry(entry) {
-    if (typeof entry === 'string') {
-        return { target: asPartName(entry) };
-    }
-    if (isVarRef(entry)) {
-        return { target: asPartName(entry.$ref) };
-    }
-    if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
-        const obj = entry;
-        const shape = obj.shape;
-        if (typeof shape === 'string') {
-            return { target: asPartName(shape), hidden: obj.hidden === true };
-        }
-        if (shape !== null && typeof shape === 'object' && isVarRef(shape)) {
-            return { target: asPartName(shape.$ref), hidden: obj.hidden === true };
-        }
-    }
-    return undefined;
-}
-/**
- * 解析调用点 keep / keepHidden 指令（IR 形态 → 目标与 hidden）。
- *
- * 两种条目形态等价（设计 §2.3）：标识符 `keep:[a,b]`（parser 产出 VarRefIR）
- * 与字符串字面量 `keep:['a']`（parser 产出 string）。
- * hidden 三态：仅 `{shape, hidden}` 显式条目写入；普通条目不写
- * （hidden 由语句级 keepHidden 兜底，设计 §2.4 `?? statementDefault`）。
- */
-/**
- * Parse the call-site keep / keepHidden directives (IR shape into targets and
- * hidden states). Identifier and string-literal entry forms are equivalent;
- * hidden is three-valued, with only explicit `{shape, hidden}` entries written.
- * @param stmt - the statement whose args hold the keep directives.
- * @returns the parsed user keep targets and hidden defaults.
- */
-export function parseUserKeep(stmt) {
-    const targets = [];
-    const hidden = new Map();
-    let statementDefault = false;
-    const args = stmt.args ?? {};
-    const keepArg = args.keep;
-    if (Array.isArray(keepArg)) {
-        for (const entry of keepArg) {
-            const parsed = parseKeepEntry(entry);
-            if (!parsed)
-                continue;
-            targets.push(parsed.target);
-            if (parsed.hidden !== undefined)
-                hidden.set(parsed.target, parsed.hidden);
-        }
-    }
-    const keepHiddenArg = args.keepHidden;
-    if (typeof keepHiddenArg === 'boolean')
-        statementDefault = keepHiddenArg;
-    return { targets, hidden, statementDefault };
-}
-// ── 合并（设计契约 §2.4） ──
-/**
- * 合并函数体声明与调用点声明。
- *
- * 优先级体现为两步顺序：先铺函数体声明（internal），再用调用点声明覆盖写入。
- * 调用点条目的 hidden = 逐条目 hidden ?? statementDefault（D1：默认可见）。
- */
-/**
- * Merge function-body declarations with call-site declarations. Precedence is a
- * two-step order: function-body declarations (internal) are laid down first,
- * then call-site declarations overwrite them.
- * @param stmt - the statement whose call-site keep directives to merge.
- * @param internal - the function-body keep registration, if any.
- * @returns the merged keep resolution with kept variables and hidden states.
- */
-export function resolveKeep(stmt, internal) {
-    const kept = new Set(internal?.kept ?? []);
-    const hidden = new Map(internal?.hidden ?? []);
-    const user = parseUserKeep(stmt);
-    for (const v of user.targets) {
-        kept.add(v);
-        hidden.set(v, user.hidden.get(v) ?? user.statementDefault);
-    }
-    return { kept, hidden };
-}
-// ── 静态校验（设计 §7.4，check 用，纯静态、第三方同样适用） ──
-/**
- * 校验语句的 keep / keepHidden 指令（纯静态，不依赖第三方签名）。
- * 返回错误消息列表（空 = 合法）：
- * - `keep` 必须是数组；条目必须是变量引用（字符串或标识符）或 `{shape, hidden}` 对象
- * - 引用目标必须是本语句 inputs 之一，或出现在 args 中（VarRefIR）
- * - `keepHidden` 必须是 boolean
- */
-/**
- * Validate a statement's keep / keepHidden directives (purely static, does not
- * depend on third-party signatures). Returns a list of error messages, empty
- * when the directives are legal.
- * @param stmt - the statement whose keep directives to validate.
- * @returns an array of error messages, empty when valid.
- */
-export function validateKeepDirectives(stmt) {
-    const errors = [];
-    const args = stmt.args ?? {};
-    if ('keep' in args) {
-        const keepArg = args.keep;
-        if (!Array.isArray(keepArg)) {
-            errors.push(`statement "${stmt.id}": keep must be an array of variable references`);
-        }
-        else {
-            // 合法引用目标：positional 中的 VarRefIR/ExprIR refs + args（除 keep/keepHidden 两键）中的引用
-            const referable = new Set(statementInputs(stmt).map(String));
-            const scan = (value) => {
-                if (value === null || typeof value !== 'object')
-                    return;
-                if (isVarRef(value)) {
-                    referable.add(String(value.$ref));
-                    return;
-                }
-                if (isExprRef(value)) {
-                    // ExprIR refs（引用变量）也是合法 keep 目标；params 是参数（自身是输入）无需加入
-                    for (const r of value.$expr.refs)
-                        referable.add(String(r));
-                    return;
-                }
-                if (isCallRef(value)) {
-                    for (const a of value.$call.args)
-                        scan(a);
-                    return;
-                }
-                if (Array.isArray(value)) {
-                    for (const item of value)
-                        scan(item);
-                    return;
-                }
-                for (const v of Object.values(value))
-                    scan(v);
-            };
-            for (const parg of stmt.positional)
-                scan(parg);
-            for (const [k, v] of Object.entries(args)) {
-                if (k === 'keep' || k === 'keepHidden')
-                    continue;
-                scan(v);
-            }
-            for (const entry of keepArg) {
-                const parsed = parseKeepEntry(entry);
-                if (!parsed) {
-                    errors.push(`statement "${stmt.id}": keep entries must be variable references or {shape, hidden} objects`);
-                    continue;
-                }
-                if (!referable.has(String(parsed.target))) {
-                    errors.push(`statement "${stmt.id}": keep target "${String(parsed.target)}" is not an input or argument variable of this statement`);
-                }
-            }
-        }
-    }
-    if ('keepHidden' in args && typeof args.keepHidden !== 'boolean') {
-        errors.push(`statement "${stmt.id}": keepHidden must be a boolean`);
-    }
-    return errors;
-}
-//# sourceMappingURL=keep.js.map

package/dist/lang/keep.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"keep.js","sourceRoot":"","sources":["../../src/lang/keep.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * keep — 统一内外 keep 机制的语义集中点（L0 零依赖）\n *\n *\n * keep 机制的两面：\n * - 调用点声明：`cad.op(input, { keep: [a, b], keepHidden: true })`（UI / AI / 用户）\n * - 函数体声明：`exec.keep(...shapes)` / `exec.keepHidden(...shapes)`（库作者）\n *\n * 优先级：调用点 > 函数体（resolveKeep 先铺函数体声明，再用调用点覆盖写入）。\n *\n * 本文件是 keep 语义的唯一集中点：parseUserKeep / withoutKeepDirectives /\n * resolveKeep / validateKeepDirectives。消费方：compile（发射剥离）、\n * module-executor（statementKey）、terminal-dag（消费判定）、runtime.check（校验）。\n *\n * L0 边界：仅依赖 ./types 与 ../identity，零运行时依赖。\n */\n\nimport type { ArgIR, CallRefIR, StatementIR, VarRefIR, ExprIR } from './types'\nimport { isVarRef, isCallRef, isExprRef, statementInputs } from './types'\nimport { asPartName, type PartName } from '../identity'\n\n// ── 数据结构（设计契约 §6） ──\n\n/** 函数体 `exec.keep` / `exec.keepHidden` 的运行时登记记录（ModuleExecutor 持有）。 */\nexport interface InternalKeepRecord {\n  /** 被声明保留的变量名集合 */\n  kept: Set<PartName>\n  /** kept 变量的 hidden 状态（未列出的 kept 变量 = 可见） */\n  hidden: Map<PartName, boolean>\n}\n\n/** keep 合并结果（terminal-dag 消费判定 + hidden 计算）。 */\nexport interface KeepResolution {\n  kept: Set<PartName>\n  /** 仅对 kept 中的变量有条目；未列出者 = 可见 */\n  hidden: Map<PartName, boolean>\n}\n\n/** 调用点 keep 指令解析结果。 */\nexport interface UserKeep {\n  targets: PartName[]\n  /** 逐条目 hidden（{shape, hidden:true} 形态） */\n  hidden: Map<PartName, boolean>\n  /** 语句级 hidden 默认（keepHidden: true），默认 false */\n  statementDefault: boolean\n}\n\n// ── 剥离 ──\n\n/**\n * 剥离调用点 keep 指令（`keep` / `keepHidden` 两键）。\n *\n * 编译发射与 statementKey 必须剥离（设计 §7.1/§7.2）：keep 透传给库函数会\n * 挤占 params 槽 / 被当 Shape 传入（union/split 的 `...rest`）。\n */\n/**\n * Strip the call-site keep directives (`keep` / `keepHidden` keys). Both\n * compile emission and statement-key computation must strip them (design\n * §7.1/§7.2): passing keep through would crowd the params slot or be treated as\n * a Shape argument (union/split `...rest`).\n * @param args - the statement's args object, or undefined.\n * @returns the args with the keep and keepHidden keys removed.\n */\nexport function withoutKeepDirectives(\n  args: Record<string, ArgIR> | undefined,\n): Record<string, ArgIR> {\n  if (!args) return {}\n  const { keep: _keep, keepHidden: _keepHidden, ...rest } = args\n  return rest\n}\n\n/** 判定 ArgIR 是否为\"纯对象\"位置实参（非 IR 变体、非数组的普通对象）。 */\nfunction isPlainObjectArg(arg: ArgIR): boolean {\n  return (\n    arg !== null &&\n    typeof arg === 'object' &&\n    !Array.isArray(arg) &&\n    !isVarRef(arg) &&\n    !isCallRef(arg) &&\n    !isExprRef(arg) &&\n    !('$param' in (arg as object))\n  )\n}\n\n/**\n * 剥离位置实参槽中的 keep 指令（true-JS-subset 方案 §4.1）：keep/keepHidden 键\n * 存在于尾随纯对象位置实参（选项槽）中，发射/序列化前从该对象剥离。\n * 与 withoutKeepDirectives 同语义，只是载体从 args 记录变为 positional 尾随对象。\n * @param positional - the statement's positional argument slot.\n * @returns a copy of the positional slot with keep/keepHidden removed from the trailing plain object.\n */\nexport function withoutKeepDirectivesFromPositional(positional: ArgIR[]): ArgIR[] {\n  const last = positional[positional.length - 1]\n  if (!isPlainObjectArg(last)) return positional\n  const obj = last as unknown as Record<string, ArgIR>\n  const stripped = Object.fromEntries(\n    Object.entries(obj).filter(([k]) => k !== 'keep' && k !== 'keepHidden'),\n  )\n  return [...positional.slice(0, -1), stripped as unknown as ArgIR]\n}\n\n// ── 解析 ──\n\n/**\n * 解析单条 keep 条目 → { target, hidden }；形态非法返回 undefined（validate 负责报错）。\n * hidden 为三态：undefined = 未指定（交由语句级 keepHidden 默认）；true/false = 显式指定。\n */\nfunction parseKeepEntry(entry: unknown): { target: PartName; hidden?: boolean } | undefined {\n  if (typeof entry === 'string') {\n    return { target: asPartName(entry) }\n  }\n  if (isVarRef(entry as ArgIR)) {\n    return { target: asPartName((entry as VarRefIR).$ref) }\n  }\n  if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {\n    const obj = entry as Record<string, unknown>\n    const shape = obj.shape\n    if (typeof shape === 'string') {\n      return { target: asPartName(shape), hidden: obj.hidden === true }\n    }\n    if (shape !== null && typeof shape === 'object' && isVarRef(shape as ArgIR)) {\n      return { target: asPartName((shape as VarRefIR).$ref), hidden: obj.hidden === true }\n    }\n  }\n  return undefined\n}\n\n/**\n * 解析调用点 keep / keepHidden 指令（IR 形态 → 目标与 hidden）。\n *\n * 两种条目形态等价（设计 §2.3）：标识符 `keep:[a,b]`（parser 产出 VarRefIR）\n * 与字符串字面量 `keep:['a']`（parser 产出 string）。\n * hidden 三态：仅 `{shape, hidden}` 显式条目写入；普通条目不写\n * （hidden 由语句级 keepHidden 兜底，设计 §2.4 `?? statementDefault`）。\n */\n/**\n * Parse the call-site keep / keepHidden directives (IR shape into targets and\n * hidden states). Identifier and string-literal entry forms are equivalent;\n * hidden is three-valued, with only explicit `{shape, hidden}` entries written.\n * @param stmt - the statement whose args hold the keep directives.\n * @returns the parsed user keep targets and hidden defaults.\n */\nexport function parseUserKeep(stmt: StatementIR): UserKeep {\n  const targets: PartName[] = []\n  const hidden = new Map<PartName, boolean>()\n  let statementDefault = false\n\n  const args = stmt.args ?? {}\n  const keepArg = args.keep\n  if (Array.isArray(keepArg)) {\n    for (const entry of keepArg) {\n      const parsed = parseKeepEntry(entry)\n      if (!parsed) continue\n      targets.push(parsed.target)\n      if (parsed.hidden !== undefined) hidden.set(parsed.target, parsed.hidden)\n    }\n  }\n\n  const keepHiddenArg = args.keepHidden\n  if (typeof keepHiddenArg === 'boolean') statementDefault = keepHiddenArg\n\n  return { targets, hidden, statementDefault }\n}\n\n// ── 合并（设计契约 §2.4） ──\n\n/**\n * 合并函数体声明与调用点声明。\n *\n * 优先级体现为两步顺序：先铺函数体声明（internal），再用调用点声明覆盖写入。\n * 调用点条目的 hidden = 逐条目 hidden ?? statementDefault（D1：默认可见）。\n */\n/**\n * Merge function-body declarations with call-site declarations. Precedence is a\n * two-step order: function-body declarations (internal) are laid down first,\n * then call-site declarations overwrite them.\n * @param stmt - the statement whose call-site keep directives to merge.\n * @param internal - the function-body keep registration, if any.\n * @returns the merged keep resolution with kept variables and hidden states.\n */\nexport function resolveKeep(\n  stmt: StatementIR,\n  internal?: InternalKeepRecord,\n): KeepResolution {\n  const kept = new Set(internal?.kept ?? [])\n  const hidden = new Map(internal?.hidden ?? [])\n\n  const user = parseUserKeep(stmt)\n  for (const v of user.targets) {\n    kept.add(v)\n    hidden.set(v, user.hidden.get(v) ?? user.statementDefault)\n  }\n\n  return { kept, hidden }\n}\n\n// ── 静态校验（设计 §7.4，check 用，纯静态、第三方同样适用） ──\n\n/**\n * 校验语句的 keep / keepHidden 指令（纯静态，不依赖第三方签名）。\n * 返回错误消息列表（空 = 合法）：\n * - `keep` 必须是数组；条目必须是变量引用（字符串或标识符）或 `{shape, hidden}` 对象\n * - 引用目标必须是本语句 inputs 之一，或出现在 args 中（VarRefIR）\n * - `keepHidden` 必须是 boolean\n */\n/**\n * Validate a statement's keep / keepHidden directives (purely static, does not\n * depend on third-party signatures). Returns a list of error messages, empty\n * when the directives are legal.\n * @param stmt - the statement whose keep directives to validate.\n * @returns an array of error messages, empty when valid.\n */\nexport function validateKeepDirectives(stmt: StatementIR): string[] {\n  const errors: string[] = []\n  const args = stmt.args ?? {}\n\n  if ('keep' in args) {\n    const keepArg = args.keep\n    if (!Array.isArray(keepArg)) {\n      errors.push(`statement \"${stmt.id}\": keep must be an array of variable references`)\n    } else {\n      // 合法引用目标：positional 中的 VarRefIR/ExprIR refs + args（除 keep/keepHidden 两键）中的引用\n      const referable = new Set<string>(statementInputs(stmt).map(String))\n      const scan = (value: unknown): void => {\n        if (value === null || typeof value !== 'object') return\n        if (isVarRef(value as ArgIR)) {\n          referable.add(String((value as VarRefIR).$ref))\n          return\n        }\n        if (isExprRef(value as ArgIR)) {\n          // ExprIR refs（引用变量）也是合法 keep 目标；params 是参数（自身是输入）无需加入\n          for (const r of (value as ExprIR).$expr.refs) referable.add(String(r))\n          return\n        }\n        if (isCallRef(value as CallRefIR)) {\n          for (const a of (value as CallRefIR).$call.args) scan(a)\n          return\n        }\n        if (Array.isArray(value)) {\n          for (const item of value) scan(item)\n          return\n        }\n        for (const v of Object.values(value as Record<string, unknown>)) scan(v)\n      }\n      for (const parg of stmt.positional) scan(parg)\n      for (const [k, v] of Object.entries(args)) {\n        if (k === 'keep' || k === 'keepHidden') continue\n        scan(v)\n      }\n      for (const entry of keepArg) {\n        const parsed = parseKeepEntry(entry)\n        if (!parsed) {\n          errors.push(\n            `statement \"${stmt.id}\": keep entries must be variable references or {shape, hidden} objects`,\n          )\n          continue\n        }\n        if (!referable.has(String(parsed.target))) {\n          errors.push(\n            `statement \"${stmt.id}\": keep target \"${String(parsed.target)}\" is not an input or argument variable of this statement`,\n          )\n        }\n      }\n    }\n  }\n\n  if ('keepHidden' in args && typeof args.keepHidden !== 'boolean') {\n    errors.push(`statement \"${stmt.id}\": keepHidden must be a boolean`)\n  }\n\n  return errors\n}\n"]}

package/dist/lang/parser.d.ts

@@ -1,91 +0,0 @@
-/**
- * parser — 文本 → ScriptIR（合法 JS 子集，设计文档 §2）
- *
- * 执行模型：`.fai.js` 文本先用 acorn 解析（合法性证明 J-1），再 walk AST 还原为 ScriptIR。
- * 绝不 eval / new Function / import() 真执行。
- *
- * 支持的语法（合法 JS 子集）：
- * - `// apiVersion: N` — 版本声明（可选，默认 1）
- * - `export default async (cad) => { ... }` — 唯一合法容器
- * - `const <name> = <literal>` → ParamDef（参数声明，右侧仅字面量）
- * - `const part<N>_v<M> = [await] cad.<op>(<inputVar>?, { ...args })` → StatementIR
- * - `cad.union/subtract/intersect(inputVar, inputVar)` → boolean op
- * - `cad.faceNormal(var)` / `cad.bboxCenter(var)` / ... → GeomRef
- * - `return { shape: part<N>_v<M>, name, color, metalness, roughness }` → ScriptIR.meta
- *
- * 禁止（acorn 抛错或 AST walk 拒绝即 ParseError）：
- * - `param` / `with` 关键字、对象字面量用 `=`
- * - 循环 / 条件 / IIFE / try-catch / 模板字符串
- * - 多 default export、函数定义（除顶层箭头外）
- * - eval / new Function / 动态 import()
- */
-import type { ScriptIR } from './types.js';
-export type { ParseErrorCode } from './parse-error.js';
-export { ParseError } from './parse-error.js';
-/**
- * The result of parsing a faijs source text: the ScriptIR plus supporting
- * line and variable mappings.
- */
-export interface ParseResult {
-    script: ScriptIR;
-    /** 语句 id → 变量名映射（新格式下为恒等映射） */
-    varToId: Map<string, string>;
-    /** 每条语句在源码中的行号（1-based，与 script.statements 一一对应；analyzeCode 用） */
-    statementLines: number[];
-}
-/**
- * 解析合法 JS 子集文本为 ScriptIR。
- *
- * 步骤：
- * 1. acorn.parse — 合法性闸门（J-1），抛 SyntaxError 即文本非法
- * 2. AST walk — 只接受允许的节点形状，遇违规即 ParseError
- * 3. 构建 ScriptIR
- *
- * 零函数知识：parser 不接收任何 schemas/函数元数据（A5/A14 已删），
- * 对 callee 名字完全均匀处理。
- *
- * @param code - the faijs valid-JS-subset source text to parse.
- * @returns the parsed ScriptIR plus line and variable mappings.
- * @throws ParseError — 含行号
- */
-export interface ParseScriptOptions {
-    /**
-     * 脚本内对「默认注入命名空间」的引用标识符（U10/R2）。缺省 'cad'——
-     * 与根门面 registerLib('cad', …, {default: true}) 声明一致；宿主换默认绑定名
-     * （如 registerLib('g', …, {default: true})）时须传入同名的 defaultNs，容器形参
-     * 与语句命名空间判定才与该声明一致。
-     */
-    defaultNs?: string;
-    /**
-     * Loose variable resolution for partial code text (CadRuntime.append receives
-     * only the newest statements). Unknown references resolve to their physical
-     * PartName instead of throwing; the caller validates them against the
-     * persistent ctx (AppendPrefixError when missing).
-     */
-    looseVars?: boolean;
-    /**
-     * Loose local-function calls for single-line extraction (codeToArgs).
-     * A bare callee that is not in the script's function set is accepted as a
-     * local call candidate instead of throwing E_REFERENCE (D15) — the caller
-     * validates it against the full script context. ABI shape is unknown for
-     * such callees, so the binding check (validateLocalAbi) is skipped.
-     */
-    looseLocalCalls?: boolean;
-}
-/**
- * Parse CAD script code text into a ScriptIR.
- *
- * @param code    - the script text to parse.
- * @param options - optional parse options (looseVars enables loose variable
- *                  resolution for partial append text).
- * @returns the parse result (script IR + parse diagnostics).
- */
-export declare function parseScript(code: string, options?: ParseScriptOptions): ParseResult;
-/**
- * Read the `// apiVersion: N` declaration from the top of a faijs source text,
- * defaulting to 1 when absent.
- * @param code - the faijs source text to inspect.
- * @returns the declared API version number, or 1 when none is present.
- */
-export declare function getApiVersion(code: string): number;
-//# sourceMappingURL=parser.d.ts.map

package/dist/lang/parser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/lang/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAMV,QAAQ,EAMT,MAAM,SAAS,CAAA;AAchB,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AA8wC1C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,QAAQ,CAAA;IAChB,+BAA+B;IAC/B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC5B,kEAAkE;IAClE,cAAc,EAAE,MAAM,EAAE,CAAA;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAydnF;AAiCD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGlD"}