@ifc-lite/cli 0.27.0 → 0.28.1

package/dist/commands/step-args.js

@@ -0,0 +1,299 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+/**
+ * Reading a STEP record's top-level argument list out of its text, for a
+ * caller that then edits one slot BY INDEX.
+ *
+ * The failure this exists to prevent is silent. A scanner that loses track of
+ * quote state or paren depth still produces parts; they are just not the
+ * record's arguments any more, because the commas it swallowed took every
+ * following slot with them. The write lands on whatever the mis-scan
+ * accumulated and the caller reports a success that did not happen
+ * (LTplus-AG/ifc-lite#2470, #4125 for the `mutate` instance). So this returns
+ * null rather than parts it does not believe in.
+ *
+ * The mis-scan nothing structural notices is an undoubled apostrophe, what an
+ * authoring tool emits when it forgets to double one. The scan closes the
+ * string at it and reopens on the next quote, so the text between the two is
+ * read inside-out and every comma in it is swallowed. TWO of them leave quote
+ * parity EVEN and paren depth at ZERO, so the scan ends clean on text that
+ * split wrong: `'guid',$,'John's wall',$,$,$,$,'A's',.NOTDEFINED.` is nine
+ * attributes read as four, and writing slot 2 deletes attributes 3 to 7.
+ *
+ * What always shows is a token ending where a token cannot end: the phantom
+ * terminator leaves the rest of the content where a separator belongs
+ * (`'John's wall'` closes after `John`, leaving a bare `s`). So this validates
+ * the list as a grammar rather than counting characters. An argument is ONE
+ * token, after a token only whitespace and then `,` or `)` may follow, and that
+ * (In the STEP examples below, `*\/` is a JavaScript escape so the example does not
+ * terminate this comment block. The backslash is not in the STEP text, and STEP
+ * gives `\` its own meaning, so strip it before copying an example into a test.)
+ *
+ * holds AT EVERY DEPTH. Applied to the top level alone it misses a phantom that
+ * swallows a `)`, a `(` and the comma between them, which leaves the depth
+ * balanced and each surviving part passing a token check on its own:
+ * `IFCLABEL('a's'),$,IFCLABEL('b's'),$` is four attributes read as two. Any
+ * two top-level slots that each hold a string inside parens can do it, and real
+ * entities have that shape (`IfcPerson`'s MiddleNames / PrefixTitles,
+ * `IfcPropertyTableValue`'s DefiningValues / DefinedValues).
+ *
+ * What the rule cannot see is a corruption whose bytes are themselves a valid
+ * argument list: a stray apostrophe at the END of a string's content emits a
+ * doubled quote by accident, so `''','''` is two arguments to its author and
+ * one to anyone reading the text. A generated sweep accepted 814 of 80,035 corruptions
+ * with a split other than the author's, down from 1,066 before the rule reached into
+ * lists, and every survivor it looked at had that shape; separating them needs the
+ * schema, not the text. That harness is NOT committed, so those figures record one run
+ * and cannot be reproduced from this tree.
+ *
+ * A STEP block comment is refused rather than understood, because `mutate` must
+ * not rewrite a record it cannot read: `/` breaks a bare run, so a part
+ * carrying a comment outside a string is never one token, whatever the comment
+ * CONTAINS. Whitespace in the comment is not what gives it away:
+ * `$,/*renamed*\/,$` has none and was read as three slots for two attributes,
+ * the same phantom-slot shift as the rest of #4125 (see {@link isTokenBreak}
+ * for why breaking on the OPENER is enough).
+ *
+ * Several readers in this repo DO skip comments; diverging from them is
+ * deliberate. The nearest is `validate.ts` in this very package, which skips
+ * `/* ... *\/` while counting top-level attribute indices; it returns indices
+ * rather than parts, so it never has to put the bytes back. `source-header.ts`'s
+ * `splitTopLevel` is closer still, since it returns PARTS, but it drops the
+ * comment bytes, so it cannot satisfy the round-trip contract below either.
+ * And `packages/parser`'s
+ * `entity-extractor.ts` reads comments at every depth through
+ * `StepTextScan.skipLexicalAt`, and says so as policy: one comment-skip rule for
+ * decoded STEP text rather than a fourth hand-rolled copy. The difference is what
+ * the two produce. That one extracts VALUES and collapses a comment to a space;
+ * this one must satisfy `parts.join(',') === input` byte for byte, because its
+ * caller rewrites the user's file. Skipping a comment under that contract would
+ * silently delete it from their file, and keeping it inside the part means the
+ * part is not one token. Doing both needs a richer return type than `string[]`,
+ * which is a different module. (`STEP_TRIVIA` itself is legal anywhere whitespace
+ * is. Its call sites are what place it, and they all put it immediately before a
+ * `\(`.)
+ *
+ * What this module does NOT cover, so its refusal is not read as more than it is:
+ * `mutate` finds records with a line regex that allows only whitespace before the
+ * `(`, so a comment after the class keyword is skipped BEFORE reaching this code,
+ * and the run reports success having changed nothing; and `lastIndexOf(')')` can
+ * slice into a legal trailing comment. Both are #4163, one on each SIDE of the
+ * argument list (before the `(`, after the `)`), and both are the same
+ * line-versus-record shape as the wrapped-record case #4163 also covers.
+ *
+ * `packages/export/src/step-argument-parser.ts` is the nearest copy, and this is
+ * deliberately its near-twin rather than an import: `@ifc-lite/export`'s
+ * `exports` map exposes only `.`, so reaching it would mean adding a published
+ * export (and an `api-surface` entry) to a v4.0.0 package to fix a CLI bug.
+ * #4125 tracks consolidating them (`derive-variants.mts` and
+ * `placement-datum.test.ts` are two the issue does not name), and that is a real merge rather
+ * than a no-op swap: its `splitTopLevelStepArguments` has the three structural
+ * checks and NO per-part check at all, which is exactly the top-level-only
+ * version the two paragraphs above show is insufficient. Measured, it splits
+ * `$,/* renamed *\/ $` into two parts and `'guid',$,'Name',/* c *\/,$` into five.
+ * The three structural checks are the contract the two DO share.
+ */
+/**
+ * Split a STEP argument list on top-level commas, or return null when the text
+ * cannot be scanned as one. `input` is the text BETWEEN a record's outermost
+ * parentheses; the module header says why null rather than parts.
+ *
+ * Nothing is trimmed and nothing is normalised, so for input this accepts
+ * `parts.join(',')` reproduces `input` byte for byte and a caller that replaces
+ * one part leaves every other byte of the record alone. Rejected: a quote still
+ * open at the end, a paren depth that does not return to zero, a depth that
+ * ever goes NEGATIVE (a stray closing paren balanced by a later opening one),
+ * and a part that is not one token at every depth (see {@link isLoneStepToken}).
+ *
+ * An EMPTY top-level slot (`a,,b`, or a trailing comma) is NOT rejected: it is
+ * invalid STEP that costs no alignment, since an empty argument is one part
+ * exactly as the entity parser counts it, so every index still names the
+ * attribute it is meant to. An empty INPUT is not an empty slot: `#1=IFCFOO();`
+ * has no arguments, so it splits to `[]` and any slot request then fails the
+ * caller's bounds check.
+ */
+export function splitTopLevelStepArgs(input) {
+    if (input === '')
+        return [];
+    const parts = [];
+    let current = '';
+    let depth = 0;
+    let inString = false;
+    for (let i = 0; i < input.length; i++) {
+        const char = input[i];
+        if (char === "'") {
+            current += char;
+            // A doubled quote INSIDE a string is an escaped apostrophe. Outside one
+            // the first quote opens a string and the second is read on its own next
+            // pass, so `''` there is the empty string rather than an escape.
+            if (inString && input[i + 1] === "'") {
+                current += input[i + 1];
+                i++;
+                continue;
+            }
+            inString = !inString;
+            continue;
+        }
+        if (!inString) {
+            if (char === '(') {
+                depth++;
+            }
+            else if (char === ')') {
+                depth--;
+                if (depth < 0)
+                    return null;
+            }
+            else if (char === ',' && depth === 0) {
+                parts.push(current);
+                current = '';
+                continue;
+            }
+        }
+        current += char;
+    }
+    if (inString || depth !== 0)
+        return null;
+    parts.push(current);
+    // These three are the contract this shares with
+    // `packages/export/src/step-argument-parser.ts`, which has exactly them and no
+    // per-part check. That parity, not speed, is why they are kept: they add no
+    // coverage at all, and deleting any one of them, or all three, fails no test
+    // (measured). Only the `depth < 0` check above is an early exit; these two run
+    // after the whole scan and save only a walk over the parts. Kept as
+    // the shared spelling until #4125 merges the copies.
+    return parts.every(isLoneStepToken) ? parts : null;
+}
+/**
+ * Is `part` exactly ONE STEP argument, all the way down? Surrounding whitespace
+ * is ignored, because a record may carry it and this must not refuse a record
+ * it could rewrite. An empty part passes, as an empty slot is accepted above.
+ */
+function isLoneStepToken(part) {
+    const text = part.trim();
+    return text === '' || skipToken(text, 0) === text.length;
+}
+/**
+ * Index just past the one token starting at `from`, or -1 when the text there
+ * is not one token. The forms, per ISO 10303-21: a string (`'...'`, `''`
+ * escaping an apostrophe), a list (`(...)`), or a bare run (`$`, `*`, `#123`, a
+ * number, an enumeration `.T.`, a binary `"0F"`) optionally applied to a list
+ * (`IFCINTEGER(3)`).
+ *
+ * Deliberately loose about what a bare run CONTAINS and strict only about where
+ * it may end: this is not a STEP validator and must not become one. A list's
+ * elements are held to the same rule, so a fragment left by a phantom string
+ * terminator is caught wherever it lands. Nesting is carried in `depth` rather
+ * than by recursing, so a pathologically nested record (this text comes from a
+ * file) refuses instead of overflowing the stack.
+ */
+function skipToken(text, from) {
+    let i = from;
+    let depth = 0;
+    let expectToken = true;
+    for (;;) {
+        i += countWhitespace(text, i);
+        const char = text[i];
+        if (expectToken) {
+            // A list element may be empty (`(1,,2)`), as a top-level slot may be.
+            if (depth > 0 && (char === ',' || char === ')')) {
+                expectToken = false;
+                continue;
+            }
+            if (char === "'") {
+                i = skipString(text, i);
+                if (i < 0)
+                    return -1;
+            }
+            else if (char === '(') {
+                depth++;
+                i++;
+                continue; // the list's first element is still a token to read
+            }
+            else {
+                const start = i;
+                while (i < text.length && !isTokenBreak(text[i]))
+                    i++;
+                // Nothing consumed: the end of the text, or a separator where a token
+                // belongs.
+                if (i === start)
+                    return -1;
+                const afterKeyword = i + countWhitespace(text, i);
+                if (text[afterKeyword] === '(') {
+                    depth++;
+                    i = afterKeyword + 1;
+                    continue;
+                }
+            }
+            expectToken = false;
+            continue;
+        }
+        // A token just closed, so only `,` or `)` may follow. At depth zero the
+        // token was the whole argument.
+        if (depth === 0)
+            return i;
+        if (char === ')') {
+            depth--;
+            i++;
+            continue;
+        }
+        if (char !== ',')
+            return -1;
+        i++;
+        expectToken = true;
+    }
+}
+/** Index just past the string starting at `from`, or -1 if it never closes. */
+function skipString(text, from) {
+    for (let i = from + 1; i < text.length; i++) {
+        if (text[i] !== "'")
+            continue;
+        if (text[i + 1] === "'")
+            i++;
+        else
+            return i + 1;
+    }
+    return -1;
+}
+/**
+ * Can this character only begin or separate another token?
+ *
+ * `/` is in the set for the STEP block comment, which opens with `/*`. Breaking
+ * on the OPENER is enough, and is why there is no comment state machine here: a
+ * comment can only sit where a token or a separator belongs, and either way the
+ * `/` ends the bare run short of the part's end, so `isLoneStepToken` refuses
+ * the part however the comment is written. `*` is deliberately NOT in the set,
+ * because it is the derived-attribute marker and a token in its own right, so
+ * breaking on it would refuse `$,$,*`.
+ */
+function isTokenBreak(char) {
+    return (char === "'" ||
+        char === '(' ||
+        char === ')' ||
+        char === ',' ||
+        char === '/' ||
+        char === ' ' ||
+        char === '\t');
+}
+/**
+ * How many whitespace characters run from `from`.
+ *
+ * Space and tab only, where every NAMED STEP whitespace set in this repo
+ * (`is_step_space`, `isSpaceByte`, `isAsciiSpace`, `STEP_TRIVIA`) is the six
+ * characters ` \t\n\r\x0b\x0c`. That is safe here only because the caller
+ * splits on newlines before this ever runs. `\n` and `\r` are in neither this
+ * set nor {@link isTokenBreak}, so a bare run spans them silently and two tokens
+ * separated by a newline come back as ONE part (measured: `'$\n$'` splits to
+ * `["$\n$"]`, where `'$ $'` and `'$\t$'` are refused). That is the same
+ * token-ending-where-it-cannot defect this module exists to catch, unreachable only
+ * because the caller pre-splits on newlines. #4163's multi-line work would
+ * start feeding real multi-line argument lists through here; widen both sets then
+ * rather than relying on that accident.
+ */
+function countWhitespace(text, from) {
+    let n = 0;
+    while (from + n < text.length && (text[from + n] === ' ' || text[from + n] === '\t'))
+        n++;
+    return n;
+}
+//# sourceMappingURL=step-args.js.map

package/dist/commands/step-args.js.map

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

package/dist/commands/subset-relations.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Spatial-structure relations for an extracted subset: which ones join it, and
+ * what text each one emits.
+ *
+ * `IfcRelContainedInSpatialStructure` is one-to-MANY, and a real exporter
+ * writes exactly ONE of them per storey, naming every product in that storey.
+ * An all-or-nothing rule (keep the relation only when every id it mentions is
+ * kept) therefore drops containment on ANY strict subset of a real model: the
+ * extracted products land outside the spatial tree and a viewer shows the
+ * storey with nothing under it. So the `RelatedElements` SET is rewritten down
+ * to the kept members instead of the relation being dropped.
+ *
+ * The no-dangling-reference invariant is unchanged: every `#id` in an emitted
+ * record is an id the subset keeps, and since #4128 the caller's forward
+ * closure keeps only ids the file DEFINES, so kept implies defined. That covers
+ * the ids this module CHOOSES; it does not cover the references inside a kept
+ * record, which are emitted verbatim, so a source file that already dangles
+ * still dangles. That is the rest of the rules:
+ *   - the RELATING object (`RelatingStructure` / `RelatingObject`, the spatial
+ *     parent) is a hard requirement. A containment with no parent is
+ *     meaningless, and it would dangle. A KNOWN residual gap follows from that,
+ *     and it is not this module's to close: `buildSubset` force-keeps only
+ *     `IfcProject` / `IfcSite` / `IfcBuilding` / `IfcBuildingStorey`, so a
+ *     product contained in an `IfcSpace` or `IfcSpatialZone` still has an
+ *     unkept parent and still loses containment. Widening that type list is the
+ *     wrong close, because it force-keeps every space AND its forward closure in
+ *     every extraction; the right one is a BACKWARD closure from each kept
+ *     product up its containment and aggregation edges, which keeps exactly the
+ *     seeds' ancestors and needs no type list at all. Either way it is a change
+ *     to how `buildSubset` seeds, not to the rule here. Filed as #4124.
+ *   - an empty intersection drops the relation.
+ *   - every other non-set reference must be kept too. That is attribute 1,
+ *     `OwnerHistory`; usually it already is, because each kept product's own
+ *     body names the same shared `IfcOwnerHistory` and the products' forward
+ *     closure keeps it. An exporter that writes a PER-RELATIONSHIP
+ *     `IfcOwnerHistory` referenced by nothing else hits this rule every time,
+ *     and dropping there was the orphaned-storey symptom again (#4126). This
+ *     function still takes no `parsed`, so it cannot close over such a
+ *     reference; it REPORTS it in {@link SpatialRelationPlan.blockedOn} and the
+ *     caller, which does have `parsed`, keeps it and replans. Purity is intact:
+ *     `blockedOn` is a finding, not a mutation.
+ *
+ * A KNOWN gap: {@link keepWhole}, the fallback for a record this module could
+ * not read as its six attributes, still drops on the same private
+ * `OwnerHistory` and reports nothing. That is deliberate. Its references are
+ * read off the raw body with no established string boundaries, so a `#6` it
+ * names may be text rather than a reference, and forward-closing over it would
+ * re-create the hash-in-a-Name bug the scanner exists to avoid.
+ *
+ * A relation that loses NO member re-emits its source line verbatim, so an
+ * extraction that happened to keep every member does not churn.
+ *
+ * ## What this module re-implements, and why
+ *
+ * Three things here already exist in `@ifc-lite/export`, and all three are
+ * copied for ONE reason: that package's `exports` map exposes only `.`, and its
+ * `index.ts` re-exports none of them, so reaching any of them would mean adding
+ * a published export (and an `api-surface` entry) to a v4.0.0 package in order
+ * to fix a CLI bug.
+ *
+ *   - `filterHiddenRefsFromRelationshipLine` (`reference-collector.ts`) is the
+ *     same job, done better: it filters EVERY parenthesised attribute of ANY
+ *     `IFCREL*` line against an `isExcluded` predicate, so it needs no slot
+ *     table at all, and it carries an edge case this module has no equivalent
+ *     of (`IfcRelConnectsStructuralMember`'s optional trailing placement).
+ *     Adopting it would delete most of this file. The export barrier above is
+ *     the whole reason it is not adopted here, and nothing else: fed only
+ *     today's three types it would change no behaviour, because the CALLER
+ *     picks which lines it sees. Widening the type set is the separate decision,
+ *     and that is the one that changes which relations survive an extraction.
+ *     Consolidation follow-up: #4125.
+ *   - `splitTopLevelStepArguments` (`step-argument-parser.ts`): see
+ *     {@link splitTopLevelArgs}.
+ *   - `STRUCTURE_RELATIONS` (`merged-empty-containers.ts`): three lines, see
+ *     below.
+ */
+/**
+ * One parsed STEP record, as `extract-entities.ts`'s `parseStep` produces it.
+ * Declared HERE and imported there, rather than the other way round, so the
+ * dependency runs one way: `extract-entities.ts` imports this module, never
+ * the reverse.
+ */
+export interface StepRecord {
+    id: number;
+    type: string;
+    /** Argument text between the outermost parentheses. */
+    body: string;
+    /** The verbatim `#id= TYPE(...);` text. */
+    full: string;
+}
+/**
+ * The assembled subset: the ids to emit, plus the record text to emit for the
+ * relations whose related-objects SET was filtered. An id absent from
+ * `rewritten` emits its source line unchanged.
+ */
+export interface Subset {
+    keep: Set<number>;
+    rewritten: ReadonlyMap<number, string>;
+}
+/** What {@link planSpatialRelations} found: relations to add, and their text. */
+export interface SpatialRelationPlan {
+    /** Relation ids that join the subset. */
+    add: number[];
+    /** Relation id → rewritten record text, for the ones that lost a member. */
+    rewritten: Map<number, string>;
+    /**
+     * Unkept non-SET references, in practice a relation-private `OwnerHistory`,
+     * of the relations that this plan dropped for THAT reason alone: their
+     * relating parent is kept and their member intersection is non-empty, so
+     * keeping these ids is all that stands between them and surviving. A caller
+     * holding the parsed model can close over them and replan (#4126). Every
+     * other drop is final and reports nothing here.
+     */
+    blockedOn: number[];
+}
+/**
+ * Decide every spatial-structure relation against a kept-id set.
+ *
+ * Pure in both arguments: adding relation ids to `keep` afterwards cannot
+ * change any verdict, because a relation of these types references products,
+ * spatial containers and an OwnerHistory, never another relation.
+ */
+export declare function planSpatialRelations(instances: Iterable<StepRecord>, keep: ReadonlySet<number>): SpatialRelationPlan;
+//# sourceMappingURL=subset-relations.d.ts.map

package/dist/commands/subset-relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subset-relations.d.ts","sourceRoot":"","sources":["../../src/commands/subset-relations.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClB,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,yCAAyC;IACzC,GAAG,EAAE,MAAM,EAAE,CAAC;IACd,4EAA4E;IAC5E,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B;;;;;;;OAOG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AA4CD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,QAAQ,CAAC,UAAU,CAAC,EAC/B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,mBAAmB,CAarB"}