@kensnzk/koyu 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (142) hide show
  1. package/dist/analysis/contracts.d.ts +217 -0
  2. package/dist/analysis/contracts.d.ts.map +1 -0
  3. package/dist/analysis/contracts.js +27 -0
  4. package/dist/analysis/contracts.js.map +1 -0
  5. package/dist/analysis/index.d.ts +5 -0
  6. package/dist/analysis/index.d.ts.map +1 -0
  7. package/dist/analysis/index.js +17 -0
  8. package/dist/analysis/index.js.map +1 -0
  9. package/dist/analysis/json.d.ts +21 -0
  10. package/dist/analysis/json.d.ts.map +1 -0
  11. package/dist/analysis/json.js +111 -0
  12. package/dist/analysis/json.js.map +1 -0
  13. package/dist/cli.js +94 -26
  14. package/dist/cli.js.map +1 -1
  15. package/dist/core/site.d.ts +9 -0
  16. package/dist/core/site.d.ts.map +1 -1
  17. package/dist/core/site.js +6 -0
  18. package/dist/core/site.js.map +1 -1
  19. package/dist/diagnostics.d.ts +2 -0
  20. package/dist/diagnostics.d.ts.map +1 -0
  21. package/dist/diagnostics.js +3 -0
  22. package/dist/diagnostics.js.map +1 -0
  23. package/dist/diff.d.ts +2 -0
  24. package/dist/diff.d.ts.map +1 -0
  25. package/dist/diff.js +3 -0
  26. package/dist/diff.js.map +1 -0
  27. package/dist/form.d.ts +5 -0
  28. package/dist/form.d.ts.map +1 -0
  29. package/dist/form.js +4 -0
  30. package/dist/form.js.map +1 -0
  31. package/dist/graph.d.ts +2 -0
  32. package/dist/graph.d.ts.map +1 -0
  33. package/dist/graph.js +3 -0
  34. package/dist/graph.js.map +1 -0
  35. package/dist/index.d.ts +2 -15
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +35 -50
  38. package/dist/index.js.map +1 -1
  39. package/dist/mcp.js +40 -20
  40. package/dist/mcp.js.map +1 -1
  41. package/dist/model.d.ts +3 -0
  42. package/dist/model.d.ts.map +1 -0
  43. package/dist/model.js +3 -0
  44. package/dist/model.js.map +1 -0
  45. package/dist/validate/assessment.d.ts +8 -0
  46. package/dist/validate/assessment.d.ts.map +1 -0
  47. package/dist/validate/assessment.js +1738 -0
  48. package/dist/validate/assessment.js.map +1 -0
  49. package/dist/validate/builtin/access.d.ts +55 -0
  50. package/dist/validate/builtin/access.d.ts.map +1 -0
  51. package/dist/validate/builtin/access.js +494 -0
  52. package/dist/validate/builtin/access.js.map +1 -0
  53. package/dist/validate/builtin/daylight.d.ts +44 -0
  54. package/dist/validate/builtin/daylight.d.ts.map +1 -0
  55. package/dist/validate/builtin/daylight.js +233 -0
  56. package/dist/validate/builtin/daylight.js.map +1 -0
  57. package/dist/validate/builtin/door-column-collisions.d.ts +47 -0
  58. package/dist/validate/builtin/door-column-collisions.d.ts.map +1 -0
  59. package/dist/validate/builtin/door-column-collisions.js +189 -0
  60. package/dist/validate/builtin/door-column-collisions.js.map +1 -0
  61. package/dist/validate/builtin/envelope.d.ts +30 -0
  62. package/dist/validate/builtin/envelope.d.ts.map +1 -0
  63. package/dist/validate/builtin/envelope.js +169 -0
  64. package/dist/validate/builtin/envelope.js.map +1 -0
  65. package/dist/validate/builtin/freeze.d.ts +3 -0
  66. package/dist/validate/builtin/freeze.d.ts.map +1 -0
  67. package/dist/validate/builtin/freeze.js +21 -0
  68. package/dist/validate/builtin/freeze.js.map +1 -0
  69. package/dist/validate/builtin/index.d.ts +38 -0
  70. package/dist/validate/builtin/index.d.ts.map +1 -0
  71. package/dist/validate/builtin/index.js +106 -0
  72. package/dist/validate/builtin/index.js.map +1 -0
  73. package/dist/validate/builtin/site.d.ts +62 -0
  74. package/dist/validate/builtin/site.d.ts.map +1 -0
  75. package/dist/validate/builtin/site.js +333 -0
  76. package/dist/validate/builtin/site.js.map +1 -0
  77. package/dist/validate/builtin/vertical-runs.d.ts +53 -0
  78. package/dist/validate/builtin/vertical-runs.d.ts.map +1 -0
  79. package/dist/validate/builtin/vertical-runs.js +290 -0
  80. package/dist/validate/builtin/vertical-runs.js.map +1 -0
  81. package/dist/validate/contracts.d.ts +188 -0
  82. package/dist/validate/contracts.d.ts.map +1 -0
  83. package/dist/validate/contracts.js +28 -0
  84. package/dist/validate/contracts.js.map +1 -0
  85. package/dist/validate/index.d.ts +2 -59
  86. package/dist/validate/index.d.ts.map +1 -1
  87. package/dist/validate/index.js +22 -70
  88. package/dist/validate/index.js.map +1 -1
  89. package/dist/vocabulary.d.ts +2 -0
  90. package/dist/vocabulary.d.ts.map +1 -0
  91. package/dist/vocabulary.js +3 -0
  92. package/dist/vocabulary.js.map +1 -0
  93. package/package.json +37 -5
  94. package/src/analysis/contracts.ts +234 -0
  95. package/src/analysis/index.ts +61 -0
  96. package/src/analysis/json.ts +117 -0
  97. package/src/cli.ts +103 -28
  98. package/src/core/site.ts +17 -0
  99. package/src/diagnostics.ts +8 -0
  100. package/src/diff.ts +14 -0
  101. package/src/form.ts +37 -0
  102. package/src/graph.ts +12 -0
  103. package/src/index.ts +39 -195
  104. package/src/mcp.ts +42 -25
  105. package/src/model.ts +43 -0
  106. package/src/validate/assessment.ts +1934 -0
  107. package/src/validate/builtin/access.ts +642 -0
  108. package/src/validate/builtin/daylight.ts +321 -0
  109. package/src/validate/builtin/door-column-collisions.ts +266 -0
  110. package/src/validate/builtin/envelope.ts +227 -0
  111. package/src/validate/builtin/freeze.ts +19 -0
  112. package/src/validate/builtin/index.ts +156 -0
  113. package/src/validate/builtin/site.ts +445 -0
  114. package/src/validate/builtin/vertical-runs.ts +390 -0
  115. package/src/validate/contracts.ts +240 -0
  116. package/src/validate/index.ts +45 -99
  117. package/src/vocabulary.ts +9 -0
  118. package/dist/validate/access.d.ts +0 -6
  119. package/dist/validate/access.d.ts.map +0 -1
  120. package/dist/validate/access.js +0 -248
  121. package/dist/validate/access.js.map +0 -1
  122. package/dist/validate/envelope.d.ts +0 -4
  123. package/dist/validate/envelope.d.ts.map +0 -1
  124. package/dist/validate/envelope.js +0 -55
  125. package/dist/validate/envelope.js.map +0 -1
  126. package/dist/validate/light.d.ts +0 -6
  127. package/dist/validate/light.d.ts.map +0 -1
  128. package/dist/validate/light.js +0 -28
  129. package/dist/validate/light.js.map +0 -1
  130. package/dist/validate/runs.d.ts +0 -16
  131. package/dist/validate/runs.d.ts.map +0 -1
  132. package/dist/validate/runs.js +0 -60
  133. package/dist/validate/runs.js.map +0 -1
  134. package/dist/validate/site.d.ts +0 -6
  135. package/dist/validate/site.d.ts.map +0 -1
  136. package/dist/validate/site.js +0 -63
  137. package/dist/validate/site.js.map +0 -1
  138. package/src/validate/access.ts +0 -291
  139. package/src/validate/envelope.ts +0 -59
  140. package/src/validate/light.ts +0 -43
  141. package/src/validate/runs.ts +0 -87
  142. package/src/validate/site.ts +0 -84
@@ -0,0 +1,445 @@
1
+ import type {
2
+ AnalysisArtifact,
3
+ AnalysisDefinition,
4
+ AnalysisRef,
5
+ Evidence,
6
+ SourceRef,
7
+ SubjectRef,
8
+ } from "../../analysis/contracts.js";
9
+ import { codePointCompare } from "../../analysis/json.js";
10
+ import {
11
+ canonicalSpaceOrder,
12
+ displayName,
13
+ isOutside,
14
+ polygonAreaM2,
15
+ regionOf,
16
+ shapeEscapesPolygon,
17
+ type Model,
18
+ type SitePolygon,
19
+ type Space,
20
+ type Zone,
21
+ } from "../../core/model.js";
22
+ import { siteReport } from "../../core/site.js";
23
+ import type { Rule, RuleEvaluation, RuleOutcome } from "../contracts.js";
24
+ import { freezeBuiltin } from "./freeze.js";
25
+
26
+ export const SITE_CONTAINMENT_TOLERANCE_MM = 1;
27
+ export const SITE_AREA_TOLERANCE_M2 = 0.05;
28
+ export const SITE_FRONTAGE_MIN_MM = 2000;
29
+
30
+ export const SITE_ESCAPE_RULE_ID = freezeBuiltin({
31
+ id: "koyu.schematic.site.escape",
32
+ revision: "1",
33
+ } as const);
34
+
35
+ export const SITE_AREA_RULE_ID = freezeBuiltin({
36
+ id: "koyu.schematic.site.area",
37
+ revision: "1",
38
+ } as const);
39
+
40
+ export const SITE_FRONTAGE_RULE_ID = freezeBuiltin({
41
+ id: "koyu.schematic.site.frontage",
42
+ revision: "1",
43
+ } as const);
44
+
45
+ export type SitePointMm = {
46
+ readonly x: number;
47
+ readonly y: number;
48
+ };
49
+
50
+ export type SitePolygonObservation = {
51
+ readonly siteRef: string;
52
+ readonly declaredAreaM2: number | null;
53
+ readonly rawAreaM2: number;
54
+ readonly roundedAreaM2: number;
55
+ };
56
+
57
+ export type SiteRoadObservation = {
58
+ readonly roadRef: string;
59
+ readonly name: string;
60
+ readonly widthMm: number;
61
+ readonly frontageMm: number;
62
+ };
63
+
64
+ export type SiteMetricsObservation = {
65
+ readonly siteName: string | null;
66
+ readonly polygonVertexCount: number | null;
67
+ readonly declaredAreaM2: number | null;
68
+ readonly derivedAreaM2: number;
69
+ readonly areaBasisM2: number;
70
+ readonly footprintM2: number;
71
+ readonly totalFloorM2: number;
72
+ readonly coveragePercent: number | null;
73
+ readonly floorAreaRatioPercent: number | null;
74
+ };
75
+
76
+ export type SiteSpaceRelationObservation = {
77
+ readonly siteRef: string;
78
+ readonly spaceRef: string;
79
+ readonly firstNonContainedPointMm: SitePointMm | null;
80
+ };
81
+
82
+ export type SiteAnalysisValue = {
83
+ readonly selectedSiteRef: string | null;
84
+ readonly metrics: SiteMetricsObservation;
85
+ readonly polygons: readonly SitePolygonObservation[];
86
+ readonly roads: readonly SiteRoadObservation[];
87
+ readonly spaceRelations: readonly SiteSpaceRelationObservation[];
88
+ };
89
+
90
+ export const SITE_ANALYSIS_ID: AnalysisRef<SiteAnalysisValue> = freezeBuiltin({
91
+ id: "koyu.analysis.site",
92
+ revision: "1",
93
+ });
94
+
95
+ export const SITE_ANALYSIS: AnalysisDefinition<SiteAnalysisValue> = freezeBuiltin<AnalysisDefinition<SiteAnalysisValue>>({
96
+ ...SITE_ANALYSIS_ID,
97
+ title: "Site observations",
98
+ model: "consistent",
99
+ dependencies: [],
100
+ context: [],
101
+ run: ({ model }): AnalysisArtifact<SiteAnalysisValue> => {
102
+ const coreModel = model as unknown as Model;
103
+ const report = siteReport(coreModel);
104
+ // The ratios and their rounding come from core, so the artifact, the CLI and the MCP
105
+ // adapter cannot drift apart by each dividing on their own.
106
+ const metrics: SiteMetricsObservation = {
107
+ siteName: report.siteZone ? namedPath(report.siteZone) : null,
108
+ polygonVertexCount: report.polygon?.points.length ?? null,
109
+ declaredAreaM2: report.declaredArea ?? null,
110
+ derivedAreaM2: report.derivedArea,
111
+ areaBasisM2: report.areaBasis,
112
+ footprintM2: report.footprint,
113
+ totalFloorM2: report.totalFloor,
114
+ coveragePercent: report.coveragePercent ?? null,
115
+ floorAreaRatioPercent: report.floorAreaRatioPercent ?? null,
116
+ };
117
+ const polygons: SitePolygonObservation[] = [];
118
+ const spaceRelations: SiteSpaceRelationObservation[] = [];
119
+ const evidence: Evidence[] = [];
120
+ const spaces = canonicalSpaceOrder(coreModel).filter((space) => space.rects.length > 0);
121
+
122
+ for (const polygon of [...coreModel.polygons.values()].sort((a, b) => codePointCompare(a.path, b.path))) {
123
+ const zone = coreModel.zones.get(polygon.path);
124
+ if (!zone || zone.attrs["site"] !== 1) continue;
125
+
126
+ const rawAreaM2 = polygonAreaM2(polygon.points as SitePolygon["points"]);
127
+ const declared = zone.attrs["area"];
128
+ const observation: SitePolygonObservation = {
129
+ siteRef: polygon.path,
130
+ declaredAreaM2: typeof declared === "number" ? declared : null,
131
+ rawAreaM2,
132
+ roundedAreaM2: Math.round(rawAreaM2 * 100) / 100,
133
+ };
134
+ polygons.push(observation);
135
+ evidence.push(siteAreaEvidence(observation, zone, polygon));
136
+
137
+ for (const space of spaces) {
138
+ if (isOutside(space) || space.path.startsWith(`${polygon.path}/`)) continue;
139
+ let firstNonContainedPointMm: SitePointMm | null = null;
140
+ for (const shape of regionOf(space)) {
141
+ const point = shapeEscapesPolygon(shape, polygon.points as SitePolygon["points"], SITE_CONTAINMENT_TOLERANCE_MM);
142
+ if (point) {
143
+ firstNonContainedPointMm = { x: point.x, y: point.y };
144
+ break;
145
+ }
146
+ }
147
+ const relation: SiteSpaceRelationObservation = {
148
+ siteRef: polygon.path,
149
+ spaceRef: space.path,
150
+ firstNonContainedPointMm,
151
+ };
152
+ spaceRelations.push(relation);
153
+ evidence.push(siteSpaceEvidence(relation, space, polygon));
154
+ }
155
+ }
156
+
157
+ const roads = report.roads
158
+ .map(({ road, width, frontage }): SiteRoadObservation => ({
159
+ roadRef: road.path,
160
+ name: displayName(road),
161
+ widthMm: width,
162
+ frontageMm: frontage,
163
+ }))
164
+ .sort((a, b) => codePointCompare(a.roadRef, b.roadRef));
165
+ for (const road of roads) {
166
+ evidence.push(roadEvidence(
167
+ road,
168
+ coreModel.spaces.get(road.roadRef)!,
169
+ report.siteZone,
170
+ ));
171
+ }
172
+
173
+ return {
174
+ state: "complete",
175
+ value: {
176
+ selectedSiteRef: report.siteZone?.path ?? null,
177
+ metrics,
178
+ polygons,
179
+ roads,
180
+ spaceRelations,
181
+ },
182
+ evidence,
183
+ };
184
+ },
185
+ });
186
+
187
+ export const SITE_ESCAPE_RULE: Rule = freezeBuiltin<Rule>({
188
+ ...SITE_ESCAPE_RULE_ID,
189
+ title: "Site containment",
190
+ level: "violation",
191
+ model: "consistent",
192
+ analyses: [{ analysis: SITE_ANALYSIS_ID, accept: "complete" }],
193
+ context: [],
194
+ authority: [],
195
+ evaluate: ({ get }) => evaluateSiteContainment(get(SITE_ANALYSIS_ID)),
196
+ });
197
+
198
+ export const SITE_AREA_RULE: Rule = freezeBuiltin<Rule>({
199
+ ...SITE_AREA_RULE_ID,
200
+ title: "Declared and polygon site area",
201
+ level: "caution",
202
+ model: "consistent",
203
+ analyses: [{ analysis: SITE_ANALYSIS_ID, accept: "complete" }],
204
+ context: [],
205
+ authority: [],
206
+ evaluate: ({ get }) => evaluateSiteArea(get(SITE_ANALYSIS_ID)),
207
+ });
208
+
209
+ export const SITE_FRONTAGE_RULE: Rule = freezeBuiltin<Rule>({
210
+ ...SITE_FRONTAGE_RULE_ID,
211
+ title: "Site road frontage",
212
+ level: "violation",
213
+ model: "consistent",
214
+ analyses: [{ analysis: SITE_ANALYSIS_ID, accept: "complete" }],
215
+ context: [],
216
+ authority: [],
217
+ evaluate: ({ get }) => evaluateSiteFrontage(get(SITE_ANALYSIS_ID)),
218
+ });
219
+
220
+ function evaluateSiteContainment(artifact: AnalysisArtifact<SiteAnalysisValue>): RuleEvaluation {
221
+ if (artifact.state !== "complete") return analysisIndeterminate(artifact);
222
+ if (artifact.value.spaceRelations.length === 0) {
223
+ return notApplicable("No regioned space and site-polygon pair is available");
224
+ }
225
+
226
+ const evidenceById = new Map(artifact.evidence.map((item) => [item.id, item]));
227
+ return applicable(artifact.value.spaceRelations.map((relation): RuleOutcome => {
228
+ const witness = relation.firstNonContainedPointMm;
229
+ const failed = witness !== null;
230
+ const evidence = requireEvidence(evidenceById, siteSpaceEvidenceId(relation.siteRef, relation.spaceRef));
231
+ return {
232
+ id: siteSpacePairId(relation.siteRef, relation.spaceRef),
233
+ status: failed ? "fail" : "pass",
234
+ subjects: [spaceSubject(relation.spaceRef)],
235
+ message: failed
236
+ ? `${relation.spaceRef} escapes the site shape (near ${witness.x},${witness.y})`
237
+ : `${relation.spaceRef} is contained by ${relation.siteRef} within the ${SITE_CONTAINMENT_TOLERANCE_MM} mm geometry tolerance`,
238
+ evidence: [evidence],
239
+ };
240
+ }));
241
+ }
242
+
243
+ function evaluateSiteArea(artifact: AnalysisArtifact<SiteAnalysisValue>): RuleEvaluation {
244
+ if (artifact.state !== "complete") return analysisIndeterminate(artifact);
245
+ const population = artifact.value.polygons.filter(
246
+ (polygon): polygon is SitePolygonObservation & { declaredAreaM2: number } => polygon.declaredAreaM2 !== null,
247
+ );
248
+ if (population.length === 0) return notApplicable("No site polygon has a declared area");
249
+
250
+ const evidenceById = new Map(artifact.evidence.map((item) => [item.id, item]));
251
+ return applicable(population.map((polygon): RuleOutcome => {
252
+ const differenceM2 = Math.abs(polygon.declaredAreaM2 - polygon.rawAreaM2);
253
+ const failed = differenceM2 >= SITE_AREA_TOLERANCE_M2;
254
+ const source = requireEvidence(evidenceById, siteAreaEvidenceId(polygon.siteRef));
255
+ return {
256
+ id: polygon.siteRef,
257
+ status: failed ? "fail" : "pass",
258
+ subjects: [siteSubject(polygon.siteRef)],
259
+ message: failed
260
+ ? `Declared and derived site areas disagree: declared ${polygon.declaredAreaM2} m2 / derived ${polygon.roundedAreaM2.toFixed(2)} m2 (${polygon.siteRef})`
261
+ : `${polygon.siteRef} declared and polygon areas differ by less than ${SITE_AREA_TOLERANCE_M2} m2`,
262
+ evidence: [{
263
+ id: "area-difference",
264
+ kind: "comparison",
265
+ observed: { value: differenceM2, unit: "m2" },
266
+ operator: "<",
267
+ required: { value: SITE_AREA_TOLERANCE_M2, unit: "m2" },
268
+ subjects: [siteSubject(polygon.siteRef)],
269
+ sources: source.sources,
270
+ producedBy: SITE_AREA_RULE_ID,
271
+ }],
272
+ };
273
+ }));
274
+ }
275
+
276
+ function evaluateSiteFrontage(artifact: AnalysisArtifact<SiteAnalysisValue>): RuleEvaluation {
277
+ if (artifact.state !== "complete") return analysisIndeterminate(artifact);
278
+ if (artifact.value.selectedSiteRef === null) return notApplicable("No site zone is selected");
279
+ if (artifact.value.roads.length === 0) return notApplicable("No exterior road space is available");
280
+
281
+ const siteRef = artifact.value.selectedSiteRef;
282
+ const evidenceById = new Map(artifact.evidence.map((item) => [item.id, item]));
283
+ return applicable(artifact.value.roads.map((road): RuleOutcome => {
284
+ const failed = road.frontageMm < SITE_FRONTAGE_MIN_MM;
285
+ const source = requireEvidence(evidenceById, roadEvidenceId(road.roadRef));
286
+ return {
287
+ id: road.roadRef,
288
+ status: failed ? "fail" : "pass",
289
+ subjects: [spaceSubject(road.roadRef)],
290
+ message: failed
291
+ ? `Road frontage is ${road.frontageMm}mm, under the ${SITE_FRONTAGE_MIN_MM}mm this pack screens for: ${road.roadRef} (widen the frontage onto the road)`
292
+ : `${road.roadRef} has ${road.frontageMm}mm of frontage, at or above the ${SITE_FRONTAGE_MIN_MM}mm minimum`,
293
+ evidence: [{
294
+ id: "frontage-minimum",
295
+ kind: "comparison",
296
+ observed: { value: road.frontageMm, unit: "mm" },
297
+ operator: ">=",
298
+ required: { value: SITE_FRONTAGE_MIN_MM, unit: "mm" },
299
+ subjects: [spaceSubject(road.roadRef), siteSubject(siteRef)],
300
+ sources: source.sources,
301
+ producedBy: SITE_FRONTAGE_RULE_ID,
302
+ }],
303
+ };
304
+ }));
305
+ }
306
+
307
+ function siteAreaEvidence(
308
+ observation: SitePolygonObservation,
309
+ zone: Zone,
310
+ polygon: SitePolygon,
311
+ ): Evidence {
312
+ const subject = siteSubject(observation.siteRef);
313
+ return {
314
+ id: siteAreaEvidenceId(observation.siteRef),
315
+ kind: "fact",
316
+ name: "siteAreaMeasurements",
317
+ value: observation,
318
+ subjects: [subject],
319
+ sources: [modelSource(subject, zone), modelSource(subject, polygon)],
320
+ producedBy: SITE_ANALYSIS_ID,
321
+ };
322
+ }
323
+
324
+ function siteSpaceEvidence(
325
+ observation: SiteSpaceRelationObservation,
326
+ space: Space,
327
+ polygon: SitePolygon,
328
+ ): Evidence {
329
+ const spaceRef = spaceSubject(observation.spaceRef);
330
+ const siteRef = siteSubject(observation.siteRef);
331
+ return {
332
+ id: siteSpaceEvidenceId(observation.siteRef, observation.spaceRef),
333
+ kind: "geometry",
334
+ geometry: {
335
+ siteRef: observation.siteRef,
336
+ spaceRef: observation.spaceRef,
337
+ toleranceMm: SITE_CONTAINMENT_TOLERANCE_MM,
338
+ firstNonContainedPointMm: observation.firstNonContainedPointMm,
339
+ },
340
+ subjects: [spaceRef, siteRef],
341
+ sources: [modelSource(spaceRef, space), modelSource(siteRef, polygon)],
342
+ producedBy: SITE_ANALYSIS_ID,
343
+ };
344
+ }
345
+
346
+ function roadEvidence(
347
+ observation: SiteRoadObservation,
348
+ road: Space,
349
+ site: Zone | undefined,
350
+ ): Evidence {
351
+ const roadRef = spaceSubject(observation.roadRef);
352
+ if (site) {
353
+ const siteRef = siteSubject(site.path);
354
+ return {
355
+ id: roadEvidenceId(observation.roadRef),
356
+ kind: "fact",
357
+ name: "roadFrontageMeasurement",
358
+ value: observation,
359
+ subjects: [roadRef, siteRef],
360
+ sources: [modelSource(roadRef, road), modelSource(siteRef, site)],
361
+ producedBy: SITE_ANALYSIS_ID,
362
+ };
363
+ }
364
+ return {
365
+ id: roadEvidenceId(observation.roadRef),
366
+ kind: "fact",
367
+ name: "roadFrontageMeasurement",
368
+ value: observation,
369
+ subjects: [roadRef],
370
+ sources: [modelSource(roadRef, road)],
371
+ producedBy: SITE_ANALYSIS_ID,
372
+ };
373
+ }
374
+
375
+ function applicable(outcomes: RuleOutcome[]): RuleEvaluation {
376
+ if (outcomes.length === 0) throw new Error("applicable evaluation requires an outcome");
377
+ return {
378
+ applicability: "applicable",
379
+ outcomes: outcomes as [RuleOutcome, ...RuleOutcome[]],
380
+ };
381
+ }
382
+
383
+ function notApplicable(reason: string): RuleEvaluation {
384
+ return { applicability: "not-applicable", reason, evidence: [] };
385
+ }
386
+
387
+ function analysisIndeterminate(
388
+ artifact: Exclude<AnalysisArtifact<SiteAnalysisValue>, { state: "complete" }>,
389
+ ): RuleEvaluation {
390
+ return {
391
+ applicability: "indeterminate",
392
+ reason: "Site observations are incomplete",
393
+ missing: artifact.missing,
394
+ evidence: artifact.state === "partial" ? artifact.evidence : [],
395
+ };
396
+ }
397
+
398
+ function requireEvidence(evidence: ReadonlyMap<string, Evidence>, id: string): Evidence {
399
+ const item = evidence.get(id);
400
+ if (!item) throw new Error(`missing site evidence: ${id}`);
401
+ return item;
402
+ }
403
+
404
+ function modelSource(
405
+ subject: SubjectRef,
406
+ source: { readonly line: number; readonly file?: string },
407
+ ): SourceRef {
408
+ return {
409
+ kind: "model",
410
+ subject,
411
+ location: {
412
+ ...(source.file !== undefined ? { file: source.file } : {}),
413
+ line: source.line,
414
+ },
415
+ };
416
+ }
417
+
418
+ function siteSubject(ref: string): SubjectRef {
419
+ return { kind: "site", ref };
420
+ }
421
+
422
+ function spaceSubject(ref: string): SubjectRef {
423
+ return { kind: "space", ref };
424
+ }
425
+
426
+ function siteAreaEvidenceId(siteRef: string): string {
427
+ return `site-area:${siteRef}`;
428
+ }
429
+
430
+ function siteSpaceEvidenceId(siteRef: string, spaceRef: string): string {
431
+ return siteSpacePairId(siteRef, spaceRef);
432
+ }
433
+
434
+ function roadEvidenceId(roadRef: string): string {
435
+ return `site-road:${roadRef}`;
436
+ }
437
+
438
+ function siteSpacePairId(siteRef: string, spaceRef: string): string {
439
+ return JSON.stringify(["site-space", siteRef, spaceRef]);
440
+ }
441
+
442
+ function namedPath(value: { readonly path: string; readonly attrs: Readonly<Record<string, unknown>> }): string {
443
+ const name = value.attrs["name"];
444
+ return typeof name === "string" ? name : (value.path.split("/").pop() ?? value.path);
445
+ }