Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 20 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,26 @@
inserts with `eachDrawn`. It must stay bounded: boxes are worked out once and found through
a grid, and every box the grid looks at and every point a check reads count against one
limit, which ends the checks with `text-check-capped` when it is reached.
- `checkIntent` in `src/intent.ts` checks a drawing against the intent given beside it: so
far, setbacks. It is not `lint` either, and its rules and type are its own. It finds
entities of model space by id, with `idKey`, and reads no layer's state. It takes any value
as the intent and never throws: a field it does not know, an id that names nothing or a
count that does not match is an `intent-unchecked` warning, never a pass with nothing said.
Unlike `lint`, it measures the points as the drawing holds them, not as written: rounding
the points and then the distance makes a footprint on its setback line warn, and hides a
real shortfall. It measures from the property line's first corner, and compares with one
tolerance, `toleranceOf`, for the arithmetic alone, never wider than the writers' rounding
moves a coordinate. A test of two outlines must hold when no side meets another exactly,
as on a turned lot: `contained` cuts a footprint's side at every corner of the lot within
the tolerance of it, and a corner of the lot inside the footprint puts it off the lot. It
takes only simple outlines, judged with `turn`, which is exact for the doubles held, and
refuses one that crosses or touches itself, such as a lot
with a hole. Each outline is read once and paid for before it is read, the search for its
sides that meet uses `grid` from `src/inspect.ts`, every point looked at counts against one
limit, what goes past it is one warning for each setback, and the warnings stop at a
number of their own. A warning names the part of the intent it is about
by `item`, a path such as `setbacks[0]`, so a later check of intent gets a field of
`Intent` of its own and adds no field to the warning.
- AutoCAD sizes dashes on the paper in a viewport, so `toSVG` scales a pattern by the
linetype scale over the viewport's scale there. `toSVG` draws a layout with `elements`, the
walk it draws model space with, under a `Look` that says how wide and what color a pen is.
Expand Down
21 changes: 21 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,27 @@

## Unreleased

- `checkIntent(drawing, intent)` checks a drawing against what it is meant to hold to, given
as data beside it, and returns warnings. Its one check is setbacks: `intent.setbacks` names
a property line and its footprints by their ids, as closed polylines of model space, with
one setback for every side or one for each side in the order of the property line's points.
`footprint-in-setback` warns of a footprint nearer a side than its setback, with the `side`,
the `required` setback and the distance `provided`, measured in drawing units from the side
itself to the footprint's outline, from the points as the drawing holds them and with a
tolerance for the arithmetic alone. `footprint-off-property` warns of a footprint not wholly
inside its property line, and `intent-unchecked` says what part of the intent could not be
checked and why, such as an id that names nothing, a field it does not know or an outline
that crosses or touches itself, worked out exactly for the doubles held, so a lot with a
hole is not checked. A point that repeats the one before it is the same corner. Each warning
about a setback gives `item`, its path in the intent, such as `setbacks[0]`. The work and
the number of warnings are bounded. It never changes what `lint` reports or what `toDXF`
writes. [docs/intent.md](docs/intent.md) describes it.
- `tsdraft render` and `tsdraft dev` check a drawing file's export `intent` on each build and
put the warnings in `diagnostics` after those of `inspectText`, with `item`, `side`,
`required` and `provided` where they apply. They never change the exit code, and
`timings.intent` gives the time the check took. `schema` stays 3. The example sheet exports
the setbacks of its residence, and its lot and residence have the ids `lot` and
`residence`.
- The dimension style `Standard`, which every R2018 DXF holds, names the text style
`Standard`. It named none, and AutoCAD draws no text for a dimension in a style with no
text style: once `Standard` was made current, a dimension a drafter drew in it with
Expand Down
24 changes: 23 additions & 1 deletion GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,8 @@ and `_`, each used once in a drawing. A diagnostic about the entity carries the
empty, fix each one, errors first. A warning whose rule starts with `text-` is about a
text as it plots: it lies over another text, it runs past the border, cell or room it
starts in, or it runs off the paper. See [Fitting text](#fitting-text-with-measuretext).
A `footprint-` warning says a building crosses a setback: see
[Checking intent](#checking-intent).
4. Look at the PNG at `outputs.png`, and at each sheet's in `outputs.layouts`. The JSON says
whether the drawing breaks a rule. Only the picture shows whether it is the drawing you
meant. When `outputs.png` is `null`, `outputs.pngError` says why, and `outputs.svg` is the
Expand Down Expand Up @@ -156,7 +158,8 @@ until it is stopped, so start it in the background.
where to read the fields of a title block.
- `outputs.svg` and `outputs.png` are model space. `outputs.layouts` has a picture of each
sheet as it plots.
- `diagnostics` is what `lint` found, and after it the warnings about text as it plots. An
- `diagnostics` is what `lint` found, and after it the warnings about text as it plots and
about [intent](#checking-intent). An
error stops `toDXF` from writing the file. A warning does not. A `text-` warning has
`bounds`, the box of the text on its picture, and `other`, the text it lies over or the
closed polyline it runs past. For a text inside a block, `entity` is the insert, and
Expand Down Expand Up @@ -247,6 +250,25 @@ keeping `drafting.ts` in a `lib` folder beside it. Change two import strings to
Its parameters come first and every position is worked out from them. Its columns and line
breaks are laid out with `measureText`. Its symbols are blocks, and so is its title block.

## Checking intent

Export `intent` beside the drawing, and each build checks that every footprint keeps out of
its setbacks. It names closed polylines of model space by their ids:

```ts
export const intent: Intent = {
setbacks: [{ property: "lot", footprints: ["house"], distance: [25, 7.5, 20, 7.5] }],
};
```

`distance` is in drawing units: one setback for every side, or one for each side in the order
of the property line's points. For a `rect` drawn from the lot's front left corner, that is the
front, the right side, the rear and the left side. A `footprint-in-setback` warning gives the
`side`, its `required` setback and the distance `provided`. `intent-unchecked` means part of
the intent was not checked, and says why, such as an outline that crosses itself.
[docs/intent.md](https://github.com/Surfside-Software/tsdraft/blob/main/docs/intent.md) has
the rest.

## Dimensions

Define a dimension style, then dimension between two points:
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,8 @@ lint(drawing, { version: "R12" }); // check a drawing against another version
text plots with `measureText`, the warnings of `inspectText` about text that
overlaps or leaves its border, what tsdraft escapes in text, and what AutoCAD
does with it after a save.
- [Checks of intent](docs/intent.md) covers `checkIntent`, which warns of a
footprint that crosses a setback, and the `intent` a drawing file exports.
- [The `tsdraft` command](docs/command.md) covers `render`, `dev`, the JSON they
give, and what happens without the PNG renderer.

Expand Down
5 changes: 5 additions & 0 deletions cli/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@
a build or change the exit code, so a throw there gives no warnings. Each warning brings
its own `bounds`, in its picture's coordinates: do not box it again with `aboutEntity`,
which would give the box of a whole insert.
- When the drawing file exports `intent`, the worker runs the library's `checkIntent` after
`inspectText`, and puts its warnings last, under the same terms: no failed build, no change
to the exit code, and each warning's own `bounds`. When the copy of tsdraft the drawing
loaded has no `checkIntent`, or its `checkIntent` throws, the build gets one
`intent-unchecked` warning that says so, so an intent is never passed over without a word.
- `render --view` draws one rectangle with `toSVG`'s `view`, with no margin, as
`outputs.view`, and writes no other picture. `tsdraft dev` has no view: its server keeps
only SVG strings and a worker ends after one build. A `Builder` passes the view to the
Expand Down
35 changes: 31 additions & 4 deletions cli/src/state.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,14 @@
// The JSON that `tsdraft render` prints and `tsdraft dev` serves as /state.json. Agents program
// against it, so a change here is a change to the interface.
import type { Diagnostic, DxfVersion, Entity, PaperUnit, TextWarning, Units } from "tsdraft";
import type {
Diagnostic,
DxfVersion,
Entity,
IntentWarning,
PaperUnit,
TextWarning,
Units,
} from "tsdraft";

/** The result of one build of a drawing file. */
export interface BuildState {
Expand Down Expand Up @@ -46,8 +54,9 @@ export interface BuildState {
readonly drawing: DrawingSummary | null;
/**
* What `lint` reports for the drawing, errors first, and after it what `inspectText` warns of
* in the text as it plots: a rule that starts with `text-`. When the file threw a
* `DrawingError`, as `toDXF` and the builder do, its diagnostics, without `kind` and
* in the text as it plots: a rule that starts with `text-`. Then, when the file has an export
* `intent`, what `checkIntent` warns of where the drawing does not hold to it. When the file
* threw a `DrawingError`, as `toDXF` and the builder do, its diagnostics, without `kind` and
* `bounds`. When the build failed because the drawing could not be drawn even without what
* `lint` reported, what `lint` reported, without `kind` and `bounds`. Otherwise empty when
* the build failed.
Expand Down Expand Up @@ -160,13 +169,29 @@ export interface PngFont {
* plots, turned and justified, and of both texts when two overlap, in the coordinates of its
* picture: pass it to `render --view`. `other` names the other text of an overlap, or the
* closed polyline the text runs past, the same way.
*
* A warning of `checkIntent` has the rule `footprint-in-setback`, `footprint-off-property` or
* `intent-unchecked`, and `item`, the path in the export `intent` of what it is about, such as
* `setbacks[0]`, where lint's `item` is a path in the drawing. Its `entity` is the footprint,
* or the entity an id names, in model space, with that entity's `kind`, `layer`, `id` and
* `call`, and `other` is the property line. A footprint warning has
* `bounds` in drawing units: for `footprint-in-setback`, the box of the two points of the side
* and the footprint nearest each other, larger on every side by the setback, and for
* `footprint-off-property` the footprint's box. `footprint-in-setback` also gives `side`,
* `required` and `provided`.
*/
export interface BuildDiagnostic extends Omit<Diagnostic, "rule"> {
readonly rule: Diagnostic["rule"] | TextWarning["rule"];
readonly rule: Diagnostic["rule"] | TextWarning["rule"] | IntentWarning["rule"];
readonly kind?: Entity["kind"];
/** The box around the entity, in drawing units, worked out as `extents` is. */
readonly bounds?: Box;
readonly other?: TextWarning["other"];
/** The side of the property line, counted from 0 in the order of its points. */
readonly side?: number;
/** The setback of that side, in drawing units. */
readonly required?: number;
/** The least distance from that side to the footprint, in drawing units, as measured. */
readonly provided?: number;
}

export interface Box {
Expand All @@ -182,6 +207,8 @@ export interface Timings {
readonly lint?: number;
/** Looking at the text as it plots, for the warnings whose rule starts with `text-`. */
readonly inspect?: number;
/** Checking the drawing against the file's export `intent`, when it has one. */
readonly intent?: number;
readonly svg?: number;
/** Rasterizing the PNG, when one was asked for. Not counted in `ms`. */
readonly png?: number;
Expand Down
56 changes: 55 additions & 1 deletion cli/src/worker.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ import type {
DimensionStyle,
Drawing,
Entity,
Intent,
IntentWarning,
Layout,
LinearDimension,
PaperInfo,
Expand Down Expand Up @@ -105,6 +107,7 @@ export interface WorkerResult {
readonly load?: number;
readonly lint?: number;
readonly inspect?: number;
readonly intent?: number;
readonly svg?: number;
};
readonly drawing: DrawingSummary | null;
Expand Down Expand Up @@ -155,6 +158,8 @@ interface Library {
drawing: Drawing,
options?: { drawNoPlot?: boolean; xrefs?: Readonly<Record<string, Drawing>> },
) => TextWarning[];
/** Where the drawing does not hold to its intent. A copy of tsdraft from before it has none. */
readonly checkIntent?: (drawing: Drawing, intent: Intent) => IntentWarning[];
/** What a viewport shows, and the papers. A copy of tsdraft from before layouts has neither. */
readonly viewportView?: (viewport: Viewport, paperUnits: PaperUnit, units: Units) => ViewportView;
readonly PAPERS?: Readonly<Record<string, PaperInfo>>;
Expand Down Expand Up @@ -489,7 +494,13 @@ async function warm(library: string | null, deadline: number): Promise<void> {
}

async function build({ file, root, drawNoPlot, view }: BuildRequest): Promise<WorkerResult> {
const timings: { load?: number; lint?: number; inspect?: number; svg?: number } = {};
const timings: {
load?: number;
lint?: number;
inspect?: number;
intent?: number;
svg?: number;
} = {};
const fail = (error: BuildError, thrown?: unknown): WorkerResult => ({
ok: false,
files: [...readFiles(file), ...missingFile(thrown)],
Expand All @@ -509,17 +520,20 @@ async function build({ file, root, drawNoPlot, view }: BuildRequest): Promise<Wo
let t = now();
let drawing: Drawing;
let referenced: Readonly<Record<string, Drawing>>;
let intent: unknown;
try {
const module = (await import(pathToFileURL(file).href)) as {
default?: unknown;
xrefs?: unknown;
intent?: unknown;
};
let value = module.default;
if (typeof value === "function") value = await (value as () => unknown)();
const problem = notADrawing(value, "default" in module) ?? notXrefs(module.xrefs);
if (problem) return fail(atExport(file, problem));
drawing = value as Drawing;
referenced = (module.xrefs ?? {}) as Readonly<Record<string, Drawing>>;
intent = module.intent;
} catch (thrown) {
timings.load = now() - t;
return fail(describe(thrown, root), thrown);
Expand Down Expand Up @@ -549,6 +563,11 @@ async function build({ file, root, drawNoPlot, view }: BuildRequest): Promise<Wo
t = now();
const diagnostics = [...linted, ...textWarnings(library, shown, drawn, drawNoPlot === true)];
timings.inspect = now() - t;
if (intent !== undefined) {
t = now();
diagnostics.push(...intentWarnings(library, shown, intent));
timings.intent = now() - t;
}
t = now();
const fontsOf = fontsIn(library, [shown, ...Object.values(drawn)]);
const { svg, min, max } = framed(
Expand Down Expand Up @@ -707,6 +726,41 @@ function textWarnings(
}
}

/**
* What `checkIntent` warns of where the drawing does not hold to the file's export `intent`,
* each with the kind of the entity it names. A warning brings its own box. It is never the
* reason a build fails. A copy of tsdraft from before `checkIntent`, or a throw from it, gives
* one warning that the intent was not checked.
*/
function intentWarnings(library: Library, drawing: Drawing, intent: unknown): BuildDiagnostic[] {
if (library.checkIntent === undefined) {
return [
{
rule: "intent-unchecked",
severity: "warning",
message:
"The copy of tsdraft this drawing imports has no checkIntent, so the export `intent` was not checked. Update it",
},
];
}
try {
return library.checkIntent(drawing, intent as Intent).map((warning) => {
const kind =
warning.entity === undefined ? undefined : drawing.entities?.[warning.entity]?.kind;
return withPath(kind === undefined ? warning : { ...warning, kind });
});
} catch (thrown) {
const reason = thrown instanceof Error ? thrown.message : String(thrown);
return [
{
rule: "intent-unchecked",
severity: "warning",
message: `checkIntent stopped with an error, so the export \`intent\` was not checked: ${reason}`,
},
];
}
}

/** Gives the file of a diagnostic's `call` as a path, as `error.file` is: Node's stack has a URL. */
function withPath<D extends Pick<Diagnostic, "call">>(d: D): D {
return d.call ? { ...d, call: { ...d.call, file: toPath(d.call.file) } } : d;
Expand Down
14 changes: 14 additions & 0 deletions cli/test/fixtures/setback.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// A drawing file whose footprint, drawn on line 8, is 15 from the front of its lot, inside the
// front setback of 25 that its export `intent` gives.
import { createDrawing, type Intent } from "tsdraft";

const d = createDrawing({ units: "ft" });

d.layer("C-PROP", { color: 7 }, () => d.rect([0, 0], 100, 140, { id: "lot" }));
d.layer("C-BLDG", { color: 5 }, () => d.rect([25, 15], 50, 40, { id: "house" }));

export default d.build();

export const intent: Intent = {
setbacks: [{ property: "lot", footprints: ["house"], distance: [25, 7.5, 20, 7.5] }],
};
Loading
Loading