tsdraft 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,8 +1,44 @@
 # Changelog
 
-## 0.3.0
+## 0.4.0
+
+- `fromPaper(length, "in" | "mm", { ratio, units })` turns a length on paper
+  into drawing units, to size text, symbols and dashes by how large they plot:
+  `fromPaper(3 / 32, "in", { ratio: 96, units: "ft" })` is 0.75. A wrong unit,
+  and a length or ratio of 0 or less, are compile errors as literals and thrown
+  errors otherwise. A result that would be written as 0, or is 1e100 or more,
+  throws.
+- `examples/site-plan.ts` is now the example sheet: a permit-style site plan for
+  an ARCH D sheet at 1" = 10', with property lines, setbacks, a building
+  footprint, dimensions, labels, site data, notes and a legend. Every text
+  height and annotation offset comes from `fromPaper`. Its default export is the drawing.
+- Breaking: a `Drawing` has `format: 0`, its format version, which is separate
+  from `dxf`. The builder sets it. A drawing written by hand needs it, and
+  `lint` reports one without it under the new rule `format`. Format 0 carries
+  no promise of stability.
+- Breaking: `LintRule` gained `format`, `id` and `duplicate-id`. Code that
+  switches over every rule, or uses `Record<LintRule, …>`, needs the three.
+- `toJSON(drawing)` writes a drawing as canonical JSON: the same drawing gives
+  the same string, whatever order its keys were set in.
+- `fromJSON(json)` reads a drawing from a JSON string or a parsed value. It
+  refuses a format version, a field or an entity kind it does not know, naming
+  each, then runs `lint`, and throws a `DrawingError`.
+- Entities take an `id` in their options: 1 to 64 letters, digits, `.`, `-` and
+  `_`. A malformed id and a second entity with the same id are builder errors
+  and `lint` errors, under the new rules `id` and `duplicate-id`. `toSVG` writes
+  the id as `data-id`.
+- A `Diagnostic` about an entity carries its `id`, and `call`, the file, line
+  and column of the call that drew it, when the drawing was built with
+  `createDrawing({ recordCalls: true })`. Setting
+  `globalThis.TSDRAFT_RECORD_CALLS = true` before a drawing's code runs turns
+  recording on for every builder that does not set the option, which is how a
+  tool that runs drawing files asks for it.
+- The builder's `layer`, `linetype` and entity methods now throw a
+  `DrawingError` with the same message as before. Its diagnostic has the rule,
+  the `id` and the `call` that broke it.
+- [docs/format.md](docs/format.md) describes all of the above.
 
-Every rule below was found by opening tsdraft's output in AutoCAD 2025.
+## 0.3.0
 
 - Breaking: `createDrawing()` now targets DXF R2018. Pass `{ dxf: "R12" }` for
   R12, which gets no new features.
@@ -52,13 +88,10 @@ Every rule below was found by opening tsdraft's output in AutoCAD 2025.
 
 ## 0.2.2
 
-Found by opening tsdraft's output in AutoCAD 2025.
-
 - Fixed: AutoCAD keeps two layers such as `straße` and `STRASSE` apart, but its
   `AUDIT` reports them as a duplicate name. `lint` now reports the second layer
   as a duplicate, and the builder throws at the `layer()` call. It does so for
-  the kinds of pair measured in AutoCAD, in either letter case and inside longer
-  names:
+  these kinds of pair, in either letter case and inside longer names:
   - a letter and the letters it stands for, such as `ß` and `ss`, `æ` and `ae`,
     `œ` and `oe`, `ij` and `ij`, `fi` and `fi`, `dž` and `dž`, and `þ` and `th`;
   - a composed character and its decomposed form, such as `é`;
@@ -71,13 +104,9 @@ Found by opening tsdraft's output in AutoCAD 2025.
 - When an entity names its layer by the other spelling of such a pair, the
   undefined-layer error now says which declared layer AutoCAD does not take it
   for. AutoCAD adds a layer for the entity, and `AUDIT` reports a duplicate name.
-- `pnpm test:cad` checks each kind of pair against AutoCAD, and 600 longer names
-  beside respellings of themselves.
 
 ## 0.2.1
 
-Every fix below was found by opening tsdraft's output in AutoCAD 2025.
-
 - Fixed: text holding `\U+XXXX` or `\M+NXXXX` came out in AutoCAD as the
   character those escapes stand for, so `\U+00B0` became a degree sign and
   `\U+000A` put a line feed inside a single-line text. Both DXF versions now
@@ -131,16 +160,11 @@ Every fix below was found by opening tsdraft's output in AutoCAD 2025.
   and about a line, polyline or arc that loses its length to rounding.
 - `lint` warns about text that contains `%%`, which AutoCAD stores as written
   but draws as a control code: `%%d` is drawn as a degree sign.
-- `pnpm test:cad` covers each fix above, and checks every character `lint`
-  accepts in text and in layer names, and each form of number the writers
-  print, against AutoCAD.
 
 ## 0.2.0
 
 0.1.1 was never published, so its changes ship here too.
 
-Every fix below comes from opening tsdraft's output in AutoCAD 2025.
-
 - `createDrawing({ dxf: "R2018" })` targets AC1032, the DXF version AutoCAD has
   used since 2018. It writes handles, owner links, the standard tables, model
   and paper space blocks, plot styles and `$INSUNITS`. R12 stays the default.
@@ -169,7 +193,6 @@ Every fix below comes from opening tsdraft's output in AutoCAD 2025.
 - Unknown units, and rectangle sizes of 0 or less, are rejected.
 - Breaking: a `Drawing` now has a required `dxf` field, and R12 layer names
   AutoCAD rejects now throw (see above).
-- `pnpm test:cad` runs the output through AutoCAD over ssh.
 - Published from GitHub Actions through npm trusted publishing, with a
   provenance attestation linking the package to its source commit.
 - `tsdraft/package.json` can be imported or resolved.

package/README.md

@@ -80,6 +80,23 @@ are AutoCAD's own definitions; `d.linetype({ name, pattern })` defines another,
 with dashes as positive lengths, gaps as negative ones and dots as 0. A
 lineweight is in millimetres.
 
+Text, symbols and dashes are sized by how large they plot. `fromPaper` turns a
+length on paper into drawing units for one scale, given as a plain ratio:
+
+```ts
+import { fromPaper } from "tsdraft";
+
+const view = { ratio: 120, units: "ft" } as const; // 1" = 10'
+const note = fromPaper(3 / 32, "in", view); // 0.9375 ft
+d.text([0, 0], "PROPERTY LINE", { height: note });
+```
+
+A paper unit other than `"in"` or `"mm"`, and a length or a ratio of 0 or less,
+are compile errors as literals and thrown errors otherwise. `fromPaper` also
+throws when the result would be written as 0 or is 1e100 or more.
+[`examples/site-plan.ts`](examples/site-plan.ts) is a whole sheet sized this
+way, and the file to copy to start a drawing.
+
 ## Status
 
 tsdraft is at an early stage. It draws layers, lines, polylines, rectangles,
@@ -89,8 +106,8 @@ hatches, blocks or paper space layouts. It writes DXF, not DWG. The drawing at
 the top builds its dimensions, leaders and stipple from lines and text, so in
 CAD they are plain lines and text, not dimension or hatch objects.
 
-The DXF output is tested by opening it in AutoCAD 2025 and running `AUDIT`. It
-has not been tested in BricsCAD or any other CAD program yet.
+The rules tsdraft checks are AutoCAD's. Other CAD programs may hold a drawing to
+other rules.
 
 ## Install
 
@@ -152,6 +169,8 @@ lint(drawing, { version: "R12" }); // check a drawing against another version
 ## Reference
 
 - [Rules](docs/rules.md) lists what `lint` refuses and what it warns about.
+- [The Drawing format](docs/format.md) covers format 0, entity ids, `toJSON`
+  and `fromJSON`, and what a diagnostic carries.
 - [Layer names](docs/layer-names.md) explains how AutoCAD compares layer and
   linetype names, and lists the pairs `AUDIT` calls duplicates and the
   characters it refuses.
@@ -170,9 +189,8 @@ pnpm example         # writes both examples to examples/out/ as DXF and SVG
 pnpm readme:drawing  # redraws the pictures in docs/assets/ from the examples
 ```
 
-[docs/development.md](docs/development.md) covers `pnpm test:cad` (which opens
-the output in AutoCAD), the package smoke test, the TypeScript compilers and
-releasing.
+[docs/development.md](docs/development.md) covers the package smoke test, the
+TypeScript compilers and releasing.
 
 ## Contributing
 

package/dist/callsite.d.ts

@@ -0,0 +1,47 @@
+/** A place in a source file, as the JavaScript engine names it in a stack. */
+export interface CallSite {
+    /** A `file://` URL for an ES module in Node, a path for CommonJS, and a URL in a browser. */
+    readonly file: string;
+    /** Counted from 1. */
+    readonly line: number;
+    /** Counted from 1. */
+    readonly column: number;
+}
+/**
+ * A stack that the engine has captured and formats when `stack` is first read. `whole` is true
+ * for a stack that starts inside tsdraft, and false for one cut down to the caller's frame.
+ */
+export interface HeldCall {
+    readonly stack?: unknown;
+    readonly whole: boolean;
+}
+type Method = (...args: never[]) => unknown;
+/**
+ * Captures the call of the builder method `method` that is running now, to be read later, or
+ * returns undefined where the engine gives no stack. It must be called from the builder's file.
+ *
+ * With `Error.captureStackTrace` the engine leaves out every frame down to `method`, so only the
+ * caller's frame is captured. Without it, the whole stack of a new error is kept.
+ */
+export declare function holdCall(method: Method): HeldCall | undefined;
+/** The location a held call names, or undefined when its stack has none. */
+export declare function readCall(held: HeldCall | undefined): CallSite | undefined;
+/**
+ * The caller's frame in a whole stack captured by `holdCall`: the first frame in neither of
+ * tsdraft's two files on it, which are those of the first frame, `holdCall`'s own, and of the
+ * second, the builder's. Frames are told apart by file and not counted, because an engine may
+ * leave a frame out. When the caller's code is in one file with tsdraft, as in a bundle, no
+ * frame qualifies and there is no location, which is better than a line inside tsdraft.
+ */
+export declare function callerInStack(stack: string): CallSite | undefined;
+/** Keeps the calls that drew `entities`, one for each entity in order. */
+export declare function recordCalls(entities: readonly object[], calls: readonly (HeldCall | undefined)[]): void;
+/** The call that drew the entity at `index` of `entities`, when the builder recorded it. */
+export declare function callOf(entities: readonly object[], index: number): CallSite | undefined;
+/**
+ * The location of each frame of a stack, innermost first. V8 writes a frame as
+ * `at name (file:1:2)` or `at file:1:2`, and Firefox and Safari as `name@file:1:2`. A line that
+ * is no frame, such as the error's message, is left out.
+ */
+export declare function parseStack(stack: string): CallSite[];
+export {};

package/dist/callsite.js

@@ -0,0 +1,82 @@
+// Where in the caller's code a builder method was called. The location comes from the engine's
+// stack, so it holds a path of the machine the drawing was built on. It is kept beside the
+// drawing, never in it.
+/** The calls that drew a drawing's entities, by its `entities` array and each entity's index. */
+const recorded = new WeakMap();
+/**
+ * Captures the call of the builder method `method` that is running now, to be read later, or
+ * returns undefined where the engine gives no stack. It must be called from the builder's file.
+ *
+ * With `Error.captureStackTrace` the engine leaves out every frame down to `method`, so only the
+ * caller's frame is captured. Without it, the whole stack of a new error is kept.
+ */
+export function holdCall(method) {
+    const errors = Error;
+    try {
+        if (typeof errors.captureStackTrace !== "function") {
+            return { stack: new Error().stack, whole: true };
+        }
+        const held = { whole: false };
+        const limit = errors.stackTraceLimit;
+        const limited = typeof limit === "number";
+        if (limited)
+            errors.stackTraceLimit = 1;
+        try {
+            errors.captureStackTrace(held, method);
+        }
+        finally {
+            if (limited)
+                errors.stackTraceLimit = limit;
+        }
+        return held;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The location a held call names, or undefined when its stack has none. */
+export function readCall(held) {
+    if (!held)
+        return undefined;
+    try {
+        const stack = held.stack;
+        if (typeof stack !== "string")
+            return undefined;
+        return held.whole ? callerInStack(stack) : parseStack(stack)[0];
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The caller's frame in a whole stack captured by `holdCall`: the first frame in neither of
+ * tsdraft's two files on it, which are those of the first frame, `holdCall`'s own, and of the
+ * second, the builder's. Frames are told apart by file and not counted, because an engine may
+ * leave a frame out. When the caller's code is in one file with tsdraft, as in a bundle, no
+ * frame qualifies and there is no location, which is better than a line inside tsdraft.
+ */
+export function callerInStack(stack) {
+    const [capture, builder, ...rest] = parseStack(stack);
+    return rest.find((frame) => frame.file !== capture?.file && frame.file !== builder?.file);
+}
+/** Keeps the calls that drew `entities`, one for each entity in order. */
+export function recordCalls(entities, calls) {
+    recorded.set(entities, calls);
+}
+/** The call that drew the entity at `index` of `entities`, when the builder recorded it. */
+export function callOf(entities, index) {
+    return readCall(recorded.get(entities)?.[index]);
+}
+/**
+ * The location of each frame of a stack, innermost first. V8 writes a frame as
+ * `at name (file:1:2)` or `at file:1:2`, and Firefox and Safari as `name@file:1:2`. A line that
+ * is no frame, such as the error's message, is left out.
+ */
+export function parseStack(stack) {
+    return stack.split("\n").flatMap((line) => {
+        const frame = /^\s*at .*?\((.+):(\d+):(\d+)\)$/.exec(line) ??
+            /^\s*at (.+):(\d+):(\d+)$/.exec(line) ??
+            /^[^@]*@(.+):(\d+):(\d+)$/.exec(line);
+        return frame ? [{ file: frame[1], line: Number(frame[2]), column: Number(frame[3]) }] : [];
+    });
+}

package/dist/drawing.d.ts

@@ -1,4 +1,4 @@
-import { type Description, type FrozenCurrent, type LayerLinetypeName, type LineweightMm, type LineweightOf, type LinetypeName, type NewLinetypeName, type Pattern, type R12EntityStyle, type R12LayerStates, type R12Lineweights, type R12Linetypes, type LayerColor, type LayerName, type Positive } from "./rules.ts";
+import { type Description, type EntityId, type FrozenCurrent, type LayerLinetypeName, type LineweightMm, type LineweightOf, type LinetypeName, type NewLinetypeName, type Pattern, type R12EntityStyle, type R12LayerStates, type R12Lineweights, type R12Linetypes, type LayerColor, type LayerName, type Positive } from "./rules.ts";
 /** A model-space point, in drawing units. Y points up, as in CAD. */
 export type Point = readonly [x: number, y: number];
 /**
@@ -51,6 +51,12 @@ export interface Layer {
     readonly plot?: boolean;
 }
 interface EntityBase {
+    /**
+     * A name for this entity that stays the same when the drawing's code changes around it: 1 to
+     * 64 letters A to Z or a to z, digits, `.`, `-` and `_`. No two entities of a drawing share
+     * one, whatever its case.
+     */
+    readonly id?: string;
     readonly layer: string;
     /** A linetype of the drawing, `"Continuous"`, `"ByBlock"` or `"ByLayer"`, the default. */
     readonly linetype?: string;
@@ -91,6 +97,11 @@ export interface Text extends EntityBase {
 }
 export type Entity = Line | Polyline | Circle | Arc | Text;
 export interface Drawing {
+    /**
+     * The version of the `Drawing` format, which is separate from the DXF version in `dxf`.
+     * Format 0 carries no promise of stability: a later tsdraft may change it without reading it.
+     */
+    readonly format: 0;
     readonly units: Units;
     /** The DXF version the drawing is written for. `toDXF` uses it unless told otherwise. */
     readonly dxf: DxfVersion;
@@ -108,6 +119,13 @@ export interface DrawingOptions<V extends DxfVersion = DxfVersion, S extends num
     readonly dxf?: V;
     /** The global linetype scale, which multiplies every linetype's pattern. Defaults to 1. */
     readonly linetypeScale?: V extends "R12" ? 1 | R12Linetypes : Positive<S>;
+    /**
+     * Whether to record the call that draws each entity, so that a `lint` diagnostic names it in
+     * `call`. It more than doubles the time the builder takes. Defaults to `false`, or to `true` when
+     * `globalThis.TSDRAFT_RECORD_CALLS` is `true`, which a tool that runs drawing files sets
+     * before it runs them.
+     */
+    readonly recordCalls?: boolean;
 }
 /** A linetype to define: a `Linetype`, whose description may be left out. */
 export interface LinetypeDefinition<N extends string = string, P extends readonly number[] = readonly number[], D extends string = string> {
@@ -170,12 +188,18 @@ export interface LayerOptions<C extends number = number, W extends number = numb
     readonly plot?: V extends "R12" ? true | R12LayerStates : boolean;
 }
 /**
- * The linetype and lineweight an entity may have of its own. Both default to ByLayer.
+ * The id an entity may have, and the linetype and lineweight it may have of its own. Both
+ * default to ByLayer.
  *
  * @typeParam L - The linetype as written, a name or a definition. A definition's literal mistakes
  *   are compile errors.
  */
-export interface EntityOptions<V extends DxfVersion = "R2018", T extends string = string, W extends number = number, L extends LinetypeValue = LinetypeDefinition> {
+export interface EntityOptions<V extends DxfVersion = "R2018", T extends string = string, W extends number = number, L extends LinetypeValue = LinetypeDefinition, I extends string = string> {
+    /**
+     * A name for the entity that no other entity of the drawing has: 1 to 64 letters A to Z or a
+     * to z, digits, `.`, `-` and `_`. Diagnostics and `toSVG` carry it.
+     */
+    readonly id?: EntityId<I>;
     /** A linetype of the drawing, `"Continuous"`, `"ByBlock"` or `"ByLayer"`. R2018 only. */
     readonly linetype?: V extends "R12" ? R12LinetypeChoice<T, L, "bylayer", R12EntityStyle> : LinetypeChoice<T, L>;
     /** In millimetres, or `"ByLayer"`, `"ByBlock"` or `"Default"`. R2018 only. */
@@ -187,7 +211,7 @@ export interface EntityOptions<V extends DxfVersion = "R2018", T extends string
  * @typeParam L - The linetype as written, a name or a definition. A definition's literal mistakes
  *   are compile errors.
  */
-export interface TextOptions<H extends number = number, V extends DxfVersion = "R2018", T extends string = string, W extends number = number, L extends LinetypeValue = LinetypeDefinition> extends EntityOptions<V, T, W, L> {
+export interface TextOptions<H extends number = number, V extends DxfVersion = "R2018", T extends string = string, W extends number = number, L extends LinetypeValue = LinetypeDefinition, I extends string = string> extends EntityOptions<V, T, W, L, I> {
     readonly height?: Positive<H>;
     /** Degrees counterclockwise. */
     readonly rotation?: number;
@@ -198,7 +222,9 @@ export interface TextOptions<H extends number = number, V extends DxfVersion = "
  *
  * Mistakes written as literals, such as a layer name the DXF version does not
  * allow or a negative radius, are compile errors. The same checks run again
- * when the code runs, for values the compiler cannot see.
+ * when the code runs, for values the compiler cannot see: `layer`, `linetype`
+ * and the entity methods then throw a `DrawingError` whose diagnostic has the
+ * rule, the entity's `id` and the `call` that broke it.
  */
 export declare class DrawingBuilder<V extends DxfVersion = "R2018", S extends number = number> {
     #private;
@@ -218,11 +244,11 @@ export declare class DrawingBuilder<V extends DxfVersion = "R2018", S extends nu
      * Options left out keep the values the layer has.
      */
     layer<N extends string, C extends number = number, W extends number = number, T extends string = string, const L extends LinetypeValue = LinetypeDefinition>(name: LayerName<N, V>, options?: LayerOptions<C, W, T, V, N, L>, draw?: () => void): this;
-    line<T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition>(from: Point, to: Point, options?: EntityOptions<V, T, W, L>): this;
-    polyline<T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition>(points: readonly Point[], closed?: boolean, options?: EntityOptions<V, T, W, L>): this;
+    line<T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(from: Point, to: Point, options?: EntityOptions<V, T, W, L, I>): this;
+    polyline<T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(points: readonly Point[], closed?: boolean, options?: EntityOptions<V, T, W, L, I>): this;
     /** Closed rectangle from its lower-left corner. */
-    rect<W extends number, H extends number, T extends string = string, LW extends number = number, const L extends LinetypeValue = LinetypeDefinition>(corner: Point, width: Positive<W>, height: Positive<H>, options?: EntityOptions<V, T, LW, L>): this;
-    circle<R extends number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition>(center: Point, radius: Positive<R>, options?: EntityOptions<V, T, W, L>): this;
+    rect<W extends number, H extends number, T extends string = string, LW extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(corner: Point, width: Positive<W>, height: Positive<H>, options?: EntityOptions<V, T, LW, L, I>): this;
+    circle<R extends number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(center: Point, radius: Positive<R>, options?: EntityOptions<V, T, W, L, I>): this;
     /**
      * Arc from `startAngle` counterclockwise to `endAngle`. Angles are stored
      * from 0 up to 360, so -90 becomes 270, because AutoCAD's AUDIT rejects
@@ -232,8 +258,8 @@ export declare class DrawingBuilder<V extends DxfVersion = "R2018", S extends nu
      * full turn would be written with equal angles, which AutoCAD holds as an
      * arc of no length, so it throws: draw a circle instead.
      */
-    arc<R extends number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition>(center: Point, radius: Positive<R>, startAngle: number, endAngle: number, options?: EntityOptions<V, T, W, L>): this;
-    text<H extends number = number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition>(at: Point, value: string, options?: TextOptions<H, V, T, W, L>): this;
+    arc<R extends number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(center: Point, radius: Positive<R>, startAngle: number, endAngle: number, options?: EntityOptions<V, T, W, L, I>): this;
+    text<H extends number = number, T extends string = string, W extends number = number, const L extends LinetypeValue = LinetypeDefinition, I extends string = string>(at: Point, value: string, options?: TextOptions<H, V, T, W, L, I>): this;
     build(): Drawing;
 }
 export declare function createDrawing<V extends DxfVersion = "R2018", S extends number = number>(options?: DrawingOptions<V, S>): DrawingBuilder<V>;