@faicad/faijs-fcstd 0.17.0

package/dist/feature-translate.d.ts

@@ -0,0 +1,193 @@
+/**
+ * M4 — whitelisted feature translation: FCStd objects → cad-op call plan.
+ *
+ * M4.1 whitelist: anything not listed → baked (S3, no silent loss).
+ * M4.2 primitives → cad.box/cylinder/cone/sphere
+ * M4.3 booleans   → cad.union/subtract/intersect
+ * M4.6 Pad/Pocket → cad.extrude/cad.subtract over the M3 sketch contour (M6: sketch is a cad.sketch face)
+ *
+ * The call plan is an intermediate representation: M5 lowers it to .fai.js
+ * (statements sN, variables partN). Geometry values are already mm (D7).
+ */
+import type { FcstdObject } from './document.js';
+import { type ExpressionBinding } from './expressions.js';
+import type { FilletEdgeEntry } from './fillet-edges.js';
+/**
+ * One cad-op call in the M4 call plan (lowered to .fai.js by M5).
+ */
+export interface CadCall {
+    /** target variable name (partN, assigned by M5) */
+    out: string;
+    /** cad-op name, e.g. "cad.box" */
+    op: string;
+    /** positional + named params, JSON-serializable */
+    params: Record<string, unknown>;
+    /** variable names this call consumes (rendered positionally before literals) */
+    inputs: string[];
+    /** positional literal values appended after `inputs` (e.g. a direction Vec3) */
+    literals?: unknown[];
+    /** FCStd object this call came from */
+    source: string;
+    /**
+     * When true, `inputs` is bookkeeping-only (dependency tracking / variable
+     * remapping / consumed-set) and must NOT be rendered as positional args —
+     * the real args come from `params`. Used by params-only ops like
+     * `cad.compound` whose members live in `params.members` (rendering `inputs`
+     * positionally would shadow `params`).
+     */
+    noPositionalArgs?: boolean;
+}
+/**
+ * A raw JS expression argument that M5 renders verbatim instead of JSON-encoding.
+ *
+ * Needed when a call argument is itself a function call against a variable that
+ * only exists at run time — e.g. `cad.edgeRef(part3, 17)` for the edge selection
+ * of a Fillet/Chamfer (the EdgeTopoRef must be resolved against the live base
+ * shape, so it cannot be baked into the IR as a literal).
+ */
+export interface JsExpr {
+    /** the JS source to emit in the argument position */
+    readonly __jsExpr: string;
+}
+/**
+ * Wrap raw JS source as a verbatim argument (`JsExpr`).
+ *
+ * @param code - the JS expression source to emit in the argument position.
+ * @returns the `JsExpr` marker carrying that source.
+ */
+export declare function jsExpr(code: string): JsExpr;
+/**
+ * True for a `JsExpr` marker (used by M5 to render verbatim).
+ *
+ * @param v - the value to test.
+ * @returns true when `v` is a `JsExpr` marker.
+ */
+export declare function isJsExpr(v: unknown): v is JsExpr;
+/**
+ * Outcome of translating one FCStd object: a cad-op call plan, an explicit
+ * bake with reason, or preserved-only (no geometry emitted).
+ */
+export type TranslateVerdict = {
+    kind: 'translated';
+    calls: CadCall[];
+    reason?: string;
+} | {
+    kind: 'baked';
+    reason: string;
+} | {
+    kind: 'preserved-only';
+    reason: string;
+};
+/**
+ * H7 (hole_puzzle corpus, 2026-09-20): marker input for a subtract whose base
+ * is implied by the Body's feature order (no explicit BaseFeature property).
+ * Codegen retargets this at the chain head when folding the feature into its
+ * Body chain. Never a legal variable name (contains `::`), so it cannot be
+ * confused with a real input.
+ */
+export declare const BODY_CHAIN_BASE = "::body-chain-base::";
+/**
+ * True when the object type is on the M4.1 translation whitelist.
+ *
+ * @param type - the FCStd object type, e.g. "Part::Box".
+ * @returns true when the type is whitelisted for translation.
+ */
+export declare function isWhitelisted(type: string): boolean;
+/**
+ * H10 (plan §3.1/§3.5): C4's Python exception, decided by PROPERTY presence —
+ * NOT by the `Python` type-name suffix. Matches the library profile's
+ * pythonObjects口径 (profile.mjs: type contains "Python" or carries
+ * Python/Proxy properties); here only the property evidence qualifies, so a
+ * Python-suffixed type without the property stays a plain translation gap.
+ * @param obj - the FCStd object to inspect.
+ * @returns true when the object is a Python-scripted feature whose serialized
+ *   shape is opaque (legitimate `python-baked` under C4).
+ */
+export declare function isPythonOpaque(obj: FcstdObject): boolean;
+/**
+ * M11.1/M11.2: the ExpressionEngine binding for `name`, if any. `value` is
+ * undefined for non-constant expressions (references/arithmetic) — the caller
+ * must bake with an explicit reason instead of estimating.
+ *
+ * @param obj - the FCStd object whose ExpressionEngine to inspect.
+ * @param name - the property name to look up.
+ * @returns the binding for `name`, or undefined when the object has no
+ *   ExpressionEngine binding for it.
+ */
+export declare function expressionBindingOf(obj: FcstdObject, name: string): ExpressionBinding | undefined;
+/**
+ * M11.2: detect a non-constant expression binding on a property.
+ *
+ * @param obj - the FCStd object whose ExpressionEngine to inspect.
+ * @param name - the property name to look up.
+ * @returns true when `name` has a binding that is NOT a constant expression.
+ */
+export declare function hasNonConstantBinding(obj: FcstdObject, name: string): boolean;
+/**
+ * M9.1 — Pad/Pocket `Type` enumeration (App::PropertyEnumeration, stored as
+ * the string enum label OR its integer index — both seen in the corpus).
+ * FreeCAD sources: Pad.h / Pocket.h TypeEnum lists (differs between the two):
+ *   Pad:    0=Length 1=UpToLast 2=UpToFirst 3=UpToFace 4=TwoLengths
+ *   Pocket: 0=Length 1=ThroughAll 2=UpToFirst 3=UpToFace 4=TwoLengths
+ * A missing Type property means Length (0) — the FreeCAD default.
+ */
+export type FeatureType = 'Length' | 'ThroughAll' | 'UpToLast' | 'UpToFirst' | 'UpToFace' | 'TwoLengths' | 'unknown';
+/**
+ * Read the Pad/Pocket `Type` enumeration of an object (M9.1).
+ *
+ * @param obj - the FCStd Pad or Pocket object.
+ * @param kind - which type-enum table to apply (Pad vs Pocket labels differ).
+ * @returns the parsed feature type; 'Length' when Type is missing, 'unknown'
+ *   when the stored label/index is not recognized.
+ */
+export declare function featureTypeOf(obj: FcstdObject, kind: 'pad' | 'pocket'): FeatureType;
+/**
+ * Parse a PartDesign ReferenceAxis reference into a 3D axis + pivot point.
+ *
+ * FreeCAD stores this as an `App::PropertyLinkSub` string that either names a
+ * standard body axis (`V_Axis` / `H_Axis` / `N_Axis`, or the generic `Axis`
+ * that PartDesign revolves around = +Z) or an edge/vertex of another feature.
+ * Edge/vertex axes require resolving referenced geometry, which the port does
+ * not yet do (explicit downgrade, no silent loss).
+ *
+ * @param ref - the ReferenceAxis (or Direction) LinkSub string, may be undefined.
+ * @returns a unit axis and pivot point, or undefined when the reference names
+ *   edge/vertex geometry (unsupported).
+ */
+export declare function parseReferenceAxis(ref: string | undefined): {
+    axis: [number, number, number];
+    at: [number, number, number];
+} | undefined;
+/**
+ * Placement position (translation) of an object.
+ *
+ * @param obj - the FCStd object to read.
+ * @returns the (Px, Py, Pz) translation from its Placement, or (0,0,0) when absent.
+ */
+export declare function placementPos(obj: FcstdObject): [number, number, number];
+/**
+ * M4 translate one object. `inputVar` maps a dependency object name to the
+ * variable holding its geometry (sketch contours or prior solid).
+ *
+ * `docObjects` (optional) is the full document object list — needed by the
+ * UpToFace datum-plane path to read the target plane's Placement (plan
+ * extrude-upto-face §4.3-C1). When absent, UpToFace keeps the explicit bake.
+ *
+ * @param obj - the FCStd object to translate.
+ * @param inputVar - resolves a dependency object name to the variable holding
+ *   its geometry (sketch contours or prior solid).
+ * @param docObjects - the full document object list, needed by the UpToFace
+ *   datum-plane path; optional.
+ * @param shapeCarriers - objects whose Shape is stored as a .brp member; optional.
+ * @param brokenShapeAssets - objects whose Shape `file` attribute points at a missing/empty member (explicit gap); optional.
+ * @param filletEdgesData - parsed PropertyFilletEdges binaries keyed by object name (Part::Chamfer/Fillet); optional.
+ * @returns the cad-op call plan, or an explicit bake/preserve verdict with reason.
+ */
+export declare function translateObject(obj: FcstdObject, inputVar: (depName: string) => string | undefined, docObjects?: readonly FcstdObject[], 
+/** H7: names of objects whose Shape is stored as a .brp member (probed from the ZIP). */
+shapeCarriers?: ReadonlySet<string>, 
+/** E4: objects whose Shape `file` attribute points at a missing/empty member. */
+brokenShapeAssets?: ReadonlySet<string>, 
+/** P8: parsed PropertyFilletEdges binaries keyed by object name (Part::Chamfer/Fillet). */
+filletEdgesData?: ReadonlyMap<string, FilletEdgeEntry[]>): TranslateVerdict;
+//# sourceMappingURL=feature-translate.d.ts.map

package/dist/feature-translate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-translate.d.ts","sourceRoot":"","sources":["../src/feature-translate.ts"],"names":[],"mappings":"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"}