@wire-dsl/engine 0.2.2 → 0.2.4

package/dist/index.cjs

@@ -49,6 +49,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/parser/index.ts
 var import_chevrotain = require("chevrotain");
+var import_components = require("@wire-dsl/language-support/components");
 
 // src/sourcemap/builder.ts
 var SourceMapBuilder = class {
@@ -1343,6 +1344,374 @@ var WireDSLVisitorWithSourceMap = class extends WireDSLVisitor {
   }
 };
 var visitor = new WireDSLVisitor();
+function getEnumOptions(property) {
+  if (property.type === "enum" && Array.isArray(property.options)) {
+    return property.options;
+  }
+  return void 0;
+}
+function buildComponentRulesFromMetadata() {
+  return Object.fromEntries(
+    Object.entries(import_components.COMPONENTS).map(([componentName, metadata]) => {
+      const allowedProps = Object.keys(metadata.properties);
+      const requiredProps = Object.entries(metadata.properties).filter(([, property]) => property.required === true && property.defaultValue === void 0).map(([propertyName]) => propertyName);
+      const enumProps = {};
+      const booleanProps = /* @__PURE__ */ new Set();
+      Object.entries(metadata.properties).forEach(([propertyName, property]) => {
+        const enumOptions = getEnumOptions(property);
+        if (enumOptions) {
+          enumProps[propertyName] = enumOptions;
+        }
+        if (property.type === "boolean") {
+          booleanProps.add(propertyName);
+        }
+      });
+      return [
+        componentName,
+        {
+          allowedProps,
+          requiredProps,
+          enumProps,
+          booleanProps
+        }
+      ];
+    })
+  );
+}
+function buildLayoutRulesFromMetadata() {
+  return Object.fromEntries(
+    Object.entries(import_components.LAYOUTS).map(([layoutName, metadata]) => {
+      const allowedParams = Object.keys(metadata.properties);
+      const requiredParamsFromProperties = Object.entries(metadata.properties).filter(([, property]) => property.required === true && property.defaultValue === void 0).map(([propertyName]) => propertyName);
+      const requiredParams = Array.from(
+        /* @__PURE__ */ new Set([...metadata.requiredProperties || [], ...requiredParamsFromProperties])
+      );
+      const enumParams = {};
+      Object.entries(metadata.properties).forEach(([propertyName, property]) => {
+        const enumOptions = getEnumOptions(property);
+        if (enumOptions) {
+          enumParams[propertyName] = enumOptions;
+        }
+      });
+      return [
+        layoutName,
+        {
+          allowedParams,
+          requiredParams,
+          enumParams
+        }
+      ];
+    })
+  );
+}
+var BUILT_IN_COMPONENTS = new Set(Object.keys(import_components.COMPONENTS));
+var COMPONENT_RULES = buildComponentRulesFromMetadata();
+var LAYOUT_RULES = buildLayoutRulesFromMetadata();
+function toFallbackRange() {
+  return {
+    start: { line: 1, column: 0 },
+    end: { line: 1, column: 1 }
+  };
+}
+function splitDiagnostics(diagnostics) {
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  const warnings = diagnostics.filter((d) => d.severity === "warning");
+  return { errors, warnings };
+}
+function buildParseDiagnosticsResult(diagnostics, ast, sourceMap) {
+  const { errors, warnings } = splitDiagnostics(diagnostics);
+  return {
+    ast,
+    sourceMap,
+    diagnostics,
+    errors,
+    warnings,
+    hasErrors: errors.length > 0
+  };
+}
+function buildParseResult(ast, sourceMap, diagnostics) {
+  const { errors, warnings } = splitDiagnostics(diagnostics);
+  return {
+    ast,
+    sourceMap,
+    diagnostics,
+    errors,
+    warnings,
+    hasErrors: errors.length > 0
+  };
+}
+function tokenToRange(token) {
+  if (!token) return toFallbackRange();
+  const startLine = token.startLine || 1;
+  const startColumn = Math.max(0, (token.startColumn || 1) - 1);
+  const endLine = token.endLine || startLine;
+  const endColumn = token.endColumn ?? token.startColumn ?? startColumn + 1;
+  return {
+    start: {
+      line: startLine,
+      column: startColumn,
+      offset: token.startOffset
+    },
+    end: {
+      line: endLine,
+      column: endColumn,
+      offset: token.endOffset
+    }
+  };
+}
+function createLexerDiagnostic(error) {
+  const startLine = error.line || 1;
+  const startColumn = Math.max(0, (error.column || 1) - 1);
+  const length = Math.max(1, error.length || 1);
+  return {
+    message: error.message || "Lexer error",
+    severity: "error",
+    phase: "lexer",
+    code: "LEXER_ERROR",
+    range: {
+      start: {
+        line: startLine,
+        column: startColumn,
+        offset: error.offset
+      },
+      end: {
+        line: startLine,
+        column: startColumn + length,
+        offset: error.offset !== void 0 ? error.offset + length : void 0
+      }
+    }
+  };
+}
+function createParserDiagnostic(error) {
+  const token = error?.token || error?.previousToken || error?.resyncedTokens?.[0];
+  const range = token ? tokenToRange(token) : toFallbackRange();
+  return {
+    message: error?.message || "Parser error",
+    severity: "error",
+    phase: "parser",
+    code: "PARSER_ERROR",
+    range
+  };
+}
+function isBooleanLike(value) {
+  if (typeof value === "number") return value === 0 || value === 1;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === "true" || normalized === "false";
+}
+function getPropertyRange(entry, propertyName, mode = "full") {
+  const prop = entry?.properties?.[propertyName];
+  if (!prop) return entry?.range || toFallbackRange();
+  if (mode === "name") return prop.nameRange;
+  if (mode === "value") return prop.valueRange;
+  return prop.range;
+}
+function formatAllowedNames(names, emptyMessage) {
+  return names.length > 0 ? names.join(", ") : emptyMessage;
+}
+function getMissingRequiredNames(requiredNames, providedValues) {
+  return requiredNames.filter((name) => providedValues[name] === void 0);
+}
+function validateSemanticDiagnostics(ast, sourceMap) {
+  const diagnostics = [];
+  const sourceMapByNodeId = new Map(sourceMap.map((entry) => [entry.nodeId, entry]));
+  const definedComponents = new Set(ast.definedComponents.map((dc) => dc.name));
+  const emitWarning = (message, code, range, nodeId, suggestion) => {
+    diagnostics.push({
+      message,
+      code,
+      severity: "warning",
+      phase: "semantic",
+      range,
+      nodeId,
+      suggestion
+    });
+  };
+  const checkComponent = (component) => {
+    const nodeId = component._meta?.nodeId;
+    const entry = nodeId ? sourceMapByNodeId.get(nodeId) : void 0;
+    const componentType = component.componentType;
+    if (!BUILT_IN_COMPONENTS.has(componentType) && !definedComponents.has(componentType)) {
+      emitWarning(
+        `Component "${componentType}" is not a built-in component and has no local definition.`,
+        "COMPONENT_UNRESOLVED",
+        entry?.nameRange || entry?.range || toFallbackRange(),
+        nodeId,
+        `Define it with: define Component "${componentType}" { ... }`
+      );
+      return;
+    }
+    const rules = COMPONENT_RULES[componentType];
+    if (!rules) return;
+    const missingRequiredProps = getMissingRequiredNames(rules.requiredProps, component.props);
+    if (missingRequiredProps.length > 0) {
+      emitWarning(
+        `Component "${componentType}" is missing required propert${missingRequiredProps.length === 1 ? "y" : "ies"}: ${missingRequiredProps.join(", ")}.`,
+        "COMPONENT_MISSING_REQUIRED_PROPERTY",
+        entry?.nameRange || entry?.range || toFallbackRange(),
+        nodeId,
+        `Add: ${missingRequiredProps.map((name) => `${name}: ...`).join(" ")}`
+      );
+    }
+    const allowed = new Set(rules.allowedProps);
+    for (const [propName, propValue] of Object.entries(component.props)) {
+      if (!allowed.has(propName)) {
+        emitWarning(
+          `Property "${propName}" is not recognized for component "${componentType}".`,
+          "COMPONENT_UNKNOWN_PROPERTY",
+          getPropertyRange(entry, propName, "name"),
+          nodeId,
+          `Allowed properties: ${formatAllowedNames(
+            rules.allowedProps,
+            "(this component does not accept properties)"
+          )}`
+        );
+        continue;
+      }
+      const enumValues = rules.enumProps?.[propName];
+      if (enumValues) {
+        const normalizedValue = String(propValue);
+        if (!enumValues.includes(normalizedValue)) {
+          emitWarning(
+            `Invalid value "${normalizedValue}" for property "${propName}" in component "${componentType}".`,
+            "COMPONENT_INVALID_PROPERTY_VALUE",
+            getPropertyRange(entry, propName, "value"),
+            nodeId,
+            `Expected one of: ${enumValues.join(", ")}`
+          );
+        }
+      }
+      if (rules.booleanProps.has(propName) && !isBooleanLike(propValue)) {
+        emitWarning(
+          `Property "${propName}" in component "${componentType}" expects a boolean value.`,
+          "COMPONENT_BOOLEAN_PROPERTY_EXPECTED",
+          getPropertyRange(entry, propName, "value"),
+          nodeId,
+          "Use true or false."
+        );
+      }
+    }
+  };
+  const checkLayout = (layout) => {
+    const nodeId = layout._meta?.nodeId;
+    const entry = nodeId ? sourceMapByNodeId.get(nodeId) : void 0;
+    const rules = LAYOUT_RULES[layout.layoutType];
+    if (layout.children.length === 0) {
+      emitWarning(
+        `Layout "${layout.layoutType}" is empty.`,
+        "LAYOUT_EMPTY",
+        entry?.bodyRange || entry?.range || toFallbackRange(),
+        nodeId,
+        "Add at least one child: component, layout, or cell."
+      );
+    }
+    if (!rules) {
+      emitWarning(
+        `Layout type "${layout.layoutType}" is not recognized by semantic validation rules.`,
+        "LAYOUT_UNKNOWN_TYPE",
+        entry?.nameRange || entry?.range || toFallbackRange(),
+        nodeId,
+        `Use one of: ${Object.keys(LAYOUT_RULES).join(", ")}.`
+      );
+    } else {
+      const missingRequiredParams = getMissingRequiredNames(rules.requiredParams, layout.params);
+      if (missingRequiredParams.length > 0) {
+        emitWarning(
+          `Layout "${layout.layoutType}" is missing required parameter${missingRequiredParams.length === 1 ? "" : "s"}: ${missingRequiredParams.join(", ")}.`,
+          "LAYOUT_MISSING_REQUIRED_PARAMETER",
+          entry?.nameRange || entry?.range || toFallbackRange(),
+          nodeId,
+          `Add: ${missingRequiredParams.map((name) => `${name}: ...`).join(", ")}`
+        );
+      }
+      const allowed = new Set(rules.allowedParams);
+      for (const [paramName, paramValue] of Object.entries(layout.params)) {
+        if (!allowed.has(paramName)) {
+          emitWarning(
+            `Parameter "${paramName}" is not recognized for layout "${layout.layoutType}".`,
+            "LAYOUT_UNKNOWN_PARAMETER",
+            getPropertyRange(entry, paramName, "name"),
+            nodeId,
+            `Allowed parameters: ${formatAllowedNames(
+              rules.allowedParams,
+              "(this layout does not accept parameters)"
+            )}`
+          );
+          continue;
+        }
+        const enumValues = rules.enumParams?.[paramName];
+        if (enumValues) {
+          const normalizedValue = String(paramValue);
+          if (!enumValues.includes(normalizedValue)) {
+            emitWarning(
+              `Invalid value "${normalizedValue}" for parameter "${paramName}" in layout "${layout.layoutType}".`,
+              "LAYOUT_INVALID_PARAMETER_VALUE",
+              getPropertyRange(entry, paramName, "value"),
+              nodeId,
+              `Expected one of: ${enumValues.join(", ")}`
+            );
+          }
+        }
+        if (layout.layoutType === "grid" && paramName === "columns") {
+          const columns = Number(paramValue);
+          if (!Number.isFinite(columns) || columns < 1 || columns > 12) {
+            emitWarning(
+              `Grid "columns" must be a number between 1 and 12.`,
+              "LAYOUT_GRID_COLUMNS_RANGE",
+              getPropertyRange(entry, paramName, "value"),
+              nodeId,
+              "Use values from 1 to 12."
+            );
+          }
+        }
+        if (layout.layoutType === "split" && paramName === "sidebar") {
+          const sidebar = Number(paramValue);
+          if (!Number.isFinite(sidebar) || sidebar <= 0) {
+            emitWarning(
+              'Split "sidebar" must be a positive number.',
+              "LAYOUT_SPLIT_SIDEBAR_INVALID",
+              getPropertyRange(entry, paramName, "value"),
+              nodeId,
+              "Use a value like sidebar: 240."
+            );
+          }
+        }
+      }
+    }
+    for (const child of layout.children) {
+      if (child.type === "component") {
+        checkComponent(child);
+      } else if (child.type === "layout") {
+        checkLayout(child);
+      } else if (child.type === "cell") {
+        checkCell(child);
+      }
+    }
+  };
+  const checkCell = (cell) => {
+    const nodeId = cell._meta?.nodeId;
+    const entry = nodeId ? sourceMapByNodeId.get(nodeId) : void 0;
+    if (cell.props.span !== void 0) {
+      const span = Number(cell.props.span);
+      if (!Number.isFinite(span) || span < 1 || span > 12) {
+        emitWarning(
+          'Cell "span" should be a number between 1 and 12.',
+          "CELL_SPAN_RANGE",
+          getPropertyRange(entry, "span", "value"),
+          nodeId,
+          "Use values from 1 to 12."
+        );
+      }
+    }
+    for (const child of cell.children) {
+      if (child.type === "component") checkComponent(child);
+      if (child.type === "layout") checkLayout(child);
+    }
+  };
+  ast.screens.forEach((screen) => {
+    checkLayout(screen.layout);
+  });
+  return diagnostics;
+}
 function parseWireDSL(input) {
   const lexResult = WireDSLLexer.tokenize(input);
   if (lexResult.errors.length > 0) {
@@ -1359,29 +1728,56 @@ ${parserInstance.errors.map((e) => e.message).join("\n")}`);
   validateComponentDefinitionCycles(ast);
   return ast;
 }
-function parseWireDSLWithSourceMap(input, filePath = "<input>") {
+function parseWireDSLWithSourceMap(input, filePath = "<input>", options) {
+  const throwOnError = options?.throwOnError ?? true;
+  const includeSemanticWarnings = options?.includeSemanticWarnings ?? true;
+  const diagnostics = [];
   const lexResult = WireDSLLexer.tokenize(input);
   if (lexResult.errors.length > 0) {
-    throw new Error(`Lexer errors:
+    diagnostics.push(...lexResult.errors.map(createLexerDiagnostic));
+    if (throwOnError) {
+      throw new Error(`Lexer errors:
 ${lexResult.errors.map((e) => e.message).join("\n")}`);
+    }
+    return buildParseDiagnosticsResult(diagnostics);
   }
   parserInstance.input = lexResult.tokens;
   const cst = parserInstance.project();
   if (parserInstance.errors.length > 0) {
-    throw new Error(`Parser errors:
+    diagnostics.push(...parserInstance.errors.map(createParserDiagnostic));
+    if (throwOnError) {
+      throw new Error(`Parser errors:
 ${parserInstance.errors.map((e) => e.message).join("\n")}`);
+    }
+    return buildParseDiagnosticsResult(diagnostics);
   }
   const sourceMapBuilder = new SourceMapBuilder(filePath, input);
   const visitorWithSourceMap = new WireDSLVisitorWithSourceMap(sourceMapBuilder);
   const ast = visitorWithSourceMap.visit(cst);
-  validateComponentDefinitionCycles(ast);
   const sourceMap = sourceMapBuilder.build();
-  return {
-    ast,
-    sourceMap,
-    errors: []
-    // No errors if we got here (errors throw exceptions)
-  };
+  try {
+    validateComponentDefinitionCycles(ast);
+  } catch (error) {
+    const projectEntry = sourceMap.find((entry) => entry.type === "project");
+    diagnostics.push({
+      message: error instanceof Error ? error.message : "Semantic validation error",
+      severity: "error",
+      phase: "semantic",
+      code: "COMPONENT_CIRCULAR_DEFINITION",
+      range: projectEntry?.range || toFallbackRange(),
+      nodeId: projectEntry?.nodeId
+    });
+    if (throwOnError) {
+      throw error;
+    }
+  }
+  if (includeSemanticWarnings) {
+    diagnostics.push(...validateSemanticDiagnostics(ast, sourceMap));
+  }
+  if (!throwOnError) {
+    return buildParseDiagnosticsResult(diagnostics, ast, sourceMap);
+  }
+  return buildParseResult(ast, sourceMap, diagnostics);
 }
 function validateComponentDefinitionCycles(ast) {
   if (!ast.definedComponents || ast.definedComponents.length === 0) {

package/dist/index.d.cts

@@ -70,7 +70,22 @@ interface InsertionPoint {
 interface ParseResult {
     ast: AST;
     sourceMap: SourceMapEntry[];
+    diagnostics: ParseError[];
     errors: ParseError[];
+    warnings: ParseError[];
+    hasErrors: boolean;
+}
+/**
+ * Parse result with diagnostics and optional AST/SourceMap
+ * Used by tolerant editor flows where diagnostics are needed even when parsing fails
+ */
+interface ParseDiagnosticsResult {
+    ast?: AST;
+    sourceMap?: SourceMapEntry[];
+    diagnostics: ParseError[];
+    errors: ParseError[];
+    warnings: ParseError[];
+    hasErrors: boolean;
 }
 /**
  * Parse error with optional nodeId reference
@@ -79,6 +94,11 @@ interface ParseError {
     message: string;
     range: CodeRange;
     severity: 'error' | 'warning';
+    code?: string;
+    phase?: 'lexer' | 'parser' | 'semantic';
+    expected?: string;
+    actual?: string;
+    suggestion?: string;
     nodeId?: string;
 }
 /**
@@ -148,6 +168,10 @@ interface ASTComponent {
         nodeId: string;
     };
 }
+interface ParseWireDSLWithSourceMapOptions {
+    throwOnError?: boolean;
+    includeSemanticWarnings?: boolean;
+}
 declare function parseWireDSL(input: string): AST;
 /**
  * Parse Wire DSL with SourceMap generation
@@ -177,6 +201,9 @@ declare function parseWireDSL(input: string): AST;
  * ```
  */
 declare function parseWireDSLWithSourceMap(input: string, filePath?: string): ParseResult;
+declare function parseWireDSLWithSourceMap(input: string, filePath: string | undefined, options: ParseWireDSLWithSourceMapOptions & {
+    throwOnError: false;
+}): ParseDiagnosticsResult;
 interface ParsedWireframe {
     name: string;
     components: ParsedComponent[];
@@ -1287,4 +1314,4 @@ declare class SourceMapResolver {
 
 declare const version = "0.0.1";
 
-export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseError, type ParseResult, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };
+export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseDiagnosticsResult, type ParseError, type ParseResult, type ParseWireDSLWithSourceMapOptions, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };

package/dist/index.d.ts

@@ -70,7 +70,22 @@ interface InsertionPoint {
 interface ParseResult {
     ast: AST;
     sourceMap: SourceMapEntry[];
+    diagnostics: ParseError[];
     errors: ParseError[];
+    warnings: ParseError[];
+    hasErrors: boolean;
+}
+/**
+ * Parse result with diagnostics and optional AST/SourceMap
+ * Used by tolerant editor flows where diagnostics are needed even when parsing fails
+ */
+interface ParseDiagnosticsResult {
+    ast?: AST;
+    sourceMap?: SourceMapEntry[];
+    diagnostics: ParseError[];
+    errors: ParseError[];
+    warnings: ParseError[];
+    hasErrors: boolean;
 }
 /**
  * Parse error with optional nodeId reference
@@ -79,6 +94,11 @@ interface ParseError {
     message: string;
     range: CodeRange;
     severity: 'error' | 'warning';
+    code?: string;
+    phase?: 'lexer' | 'parser' | 'semantic';
+    expected?: string;
+    actual?: string;
+    suggestion?: string;
     nodeId?: string;
 }
 /**
@@ -148,6 +168,10 @@ interface ASTComponent {
         nodeId: string;
     };
 }
+interface ParseWireDSLWithSourceMapOptions {
+    throwOnError?: boolean;
+    includeSemanticWarnings?: boolean;
+}
 declare function parseWireDSL(input: string): AST;
 /**
  * Parse Wire DSL with SourceMap generation
@@ -177,6 +201,9 @@ declare function parseWireDSL(input: string): AST;
  * ```
  */
 declare function parseWireDSLWithSourceMap(input: string, filePath?: string): ParseResult;
+declare function parseWireDSLWithSourceMap(input: string, filePath: string | undefined, options: ParseWireDSLWithSourceMapOptions & {
+    throwOnError: false;
+}): ParseDiagnosticsResult;
 interface ParsedWireframe {
     name: string;
     components: ParsedComponent[];
@@ -1287,4 +1314,4 @@ declare class SourceMapResolver {
 
 declare const version = "0.0.1";
 
-export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseError, type ParseResult, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };
+export { type AST, type ASTCell, type ASTComponent, type ASTDefinedComponent, type ASTLayout, type ASTScreen, type CapturedTokens, type CodeRange, DENSITY_TOKENS, DEVICE_PRESETS, type DesignTokens, type DevicePreset, type IRComponent, type IRComponentNode, type IRContainerNode, type IRContract, IRGenerator, type IRLayout, type IRMeta, type IRMetadata, type IRNode, type IRNodeStyle, type IRProject, type IRScreen, type IRStyle, type IRWireframe, type InsertionPoint, LayoutEngine, type LayoutPosition, type LayoutResult, type ParseDiagnosticsResult, type ParseError, type ParseResult, type ParseWireDSLWithSourceMapOptions, type ParsedComponent, type ParsedWireframe, type Position, type PositionQueryResult, type PropertySourceMap, type SVGComponent, type SVGRenderOptions, SVGRenderer, SkeletonSVGRenderer, SketchSVGRenderer, SourceMapBuilder, type SourceMapEntry, type SourceMapNodeType, SourceMapResolver, buildSVG, calculateLayout, createSVGElement, generateIR, generateStableNodeId, getTypeFromNodeId, isValidDevice, isValidNodeId, parseWireDSL, parseWireDSLWithSourceMap, renderToSVG, resolveDevicePreset, resolveGridPosition, resolveTokens, version };

package/dist/index.js

@@ -1,5 +1,6 @@
 // src/parser/index.ts
 import { Lexer, createToken, CstParser } from "chevrotain";
+import { COMPONENTS, LAYOUTS } from "@wire-dsl/language-support/components";
 
 // src/sourcemap/builder.ts
 var SourceMapBuilder = class {
@@ -1294,6 +1295,374 @@ var WireDSLVisitorWithSourceMap = class extends WireDSLVisitor {
   }
 };
 var visitor = new WireDSLVisitor();
+function getEnumOptions(property) {
+  if (property.type === "enum" && Array.isArray(property.options)) {
+    return property.options;
+  }
+  return void 0;
+}
+function buildComponentRulesFromMetadata() {
+  return Object.fromEntries(
+    Object.entries(COMPONENTS).map(([componentName, metadata]) => {
+      const allowedProps = Object.keys(metadata.properties);
+      const requiredProps = Object.entries(metadata.properties).filter(([, property]) => property.required === true && property.defaultValue === void 0).map(([propertyName]) => propertyName);
+      const enumProps = {};
+      const booleanProps = /* @__PURE__ */ new Set();
+      Object.entries(metadata.properties).forEach(([propertyName, property]) => {
+        const enumOptions = getEnumOptions(property);
+        if (enumOptions) {
+          enumProps[propertyName] = enumOptions;
+        }
+        if (property.type === "boolean") {
+          booleanProps.add(propertyName);
+        }
+      });
+      return [
+        componentName,
+        {
+          allowedProps,
+          requiredProps,
+          enumProps,
+          booleanProps
+        }
+      ];
+    })
+  );
+}
+function buildLayoutRulesFromMetadata() {
+  return Object.fromEntries(
+    Object.entries(LAYOUTS).map(([layoutName, metadata]) => {
+      const allowedParams = Object.keys(metadata.properties);
+      const requiredParamsFromProperties = Object.entries(metadata.properties).filter(([, property]) => property.required === true && property.defaultValue === void 0).map(([propertyName]) => propertyName);
+      const requiredParams = Array.from(
+        /* @__PURE__ */ new Set([...metadata.requiredProperties || [], ...requiredParamsFromProperties])
+      );
+      const enumParams = {};
+      Object.entries(metadata.properties).forEach(([propertyName, property]) => {
+        const enumOptions = getEnumOptions(property);
+        if (enumOptions) {
+          enumParams[propertyName] = enumOptions;
+        }
+      });
+      return [
+        layoutName,
+        {
+          allowedParams,
+          requiredParams,
+          enumParams
+        }
+      ];
+    })
+  );
+}
+var BUILT_IN_COMPONENTS = new Set(Object.keys(COMPONENTS));
+var COMPONENT_RULES = buildComponentRulesFromMetadata();
+var LAYOUT_RULES = buildLayoutRulesFromMetadata();
+function toFallbackRange() {
+  return {
+    start: { line: 1, column: 0 },
+    end: { line: 1, column: 1 }
+  };
+}
+function splitDiagnostics(diagnostics) {
+  const errors = diagnostics.filter((d) => d.severity === "error");
+  const warnings = diagnostics.filter((d) => d.severity === "warning");
+  return { errors, warnings };
+}
+function buildParseDiagnosticsResult(diagnostics, ast, sourceMap) {
+  const { errors, warnings } = splitDiagnostics(diagnostics);
+  return {
+    ast,
+    sourceMap,
+    diagnostics,
+    errors,
+    warnings,
+    hasErrors: errors.length > 0
+  };
+}
+function buildParseResult(ast, sourceMap, diagnostics) {
+  const { errors, warnings } = splitDiagnostics(diagnostics);
+  return {
+    ast,
+    sourceMap,
+    diagnostics,
+    errors,
+    warnings,
+    hasErrors: errors.length > 0
+  };
+}
+function tokenToRange(token) {
+  if (!token) return toFallbackRange();
+  const startLine = token.startLine || 1;
+  const startColumn = Math.max(0, (token.startColumn || 1) - 1);
+  const endLine = token.endLine || startLine;
+  const endColumn = token.endColumn ?? token.startColumn ?? startColumn + 1;
+  return {
+    start: {
+      line: startLine,
+      column: startColumn,
+      offset: token.startOffset
+    },
+    end: {
+      line: endLine,
+      column: endColumn,
+      offset: token.endOffset
+    }
+  };
+}
+function createLexerDiagnostic(error) {
+  const startLine = error.line || 1;
+  const startColumn = Math.max(0, (error.column || 1) - 1);
+  const length = Math.max(1, error.length || 1);
+  return {
+    message: error.message || "Lexer error",
+    severity: "error",
+    phase: "lexer",
+    code: "LEXER_ERROR",
+    range: {
+      start: {
+        line: startLine,
+        column: startColumn,
+        offset: error.offset
+      },
+      end: {
+        line: startLine,
+        column: startColumn + length,
+        offset: error.offset !== void 0 ? error.offset + length : void 0
+      }
+    }
+  };
+}
+function createParserDiagnostic(error) {
+  const token = error?.token || error?.previousToken || error?.resyncedTokens?.[0];
+  const range = token ? tokenToRange(token) : toFallbackRange();
+  return {
+    message: error?.message || "Parser error",
+    severity: "error",
+    phase: "parser",
+    code: "PARSER_ERROR",
+    range
+  };
+}
+function isBooleanLike(value) {
+  if (typeof value === "number") return value === 0 || value === 1;
+  const normalized = String(value).trim().toLowerCase();
+  return normalized === "true" || normalized === "false";
+}
+function getPropertyRange(entry, propertyName, mode = "full") {
+  const prop = entry?.properties?.[propertyName];
+  if (!prop) return entry?.range || toFallbackRange();
+  if (mode === "name") return prop.nameRange;
+  if (mode === "value") return prop.valueRange;
+  return prop.range;
+}
+function formatAllowedNames(names, emptyMessage) {
+  return names.length > 0 ? names.join(", ") : emptyMessage;
+}
+function getMissingRequiredNames(requiredNames, providedValues) {
+  return requiredNames.filter((name) => providedValues[name] === void 0);
+}
+function validateSemanticDiagnostics(ast, sourceMap) {
+  const diagnostics = [];
+  const sourceMapByNodeId = new Map(sourceMap.map((entry) => [entry.nodeId, entry]));
+  const definedComponents = new Set(ast.definedComponents.map((dc) => dc.name));
+  const emitWarning = (message, code, range, nodeId, suggestion) => {
+    diagnostics.push({
+      message,
+      code,
+      severity: "warning",
+      phase: "semantic",
+      range,
+      nodeId,
+      suggestion
+    });
+  };
+  const checkComponent = (component) => {
+    const nodeId = component._meta?.nodeId;
+    const entry = nodeId ? sourceMapByNodeId.get(nodeId) : void 0;
+    const componentType = component.componentType;
+    if (!BUILT_IN_COMPONENTS.has(componentType) && !definedComponents.has(componentType)) {
+      emitWarning(
+        `Component "${componentType}" is not a built-in component and has no local definition.`,
+        "COMPONENT_UNRESOLVED",
+        entry?.nameRange || entry?.range || toFallbackRange(),
+        nodeId,
+        `Define it with: define Component "${componentType}" { ... }`
+      );
+      return;
+    }
+    const rules = COMPONENT_RULES[componentType];
+    if (!rules) return;
+    const missingRequiredProps = getMissingRequiredNames(rules.requiredProps, component.props);
+    if (missingRequiredProps.length > 0) {
+      emitWarning(
+        `Component "${componentType}" is missing required propert${missingRequiredProps.length === 1 ? "y" : "ies"}: ${missingRequiredProps.join(", ")}.`,
+        "COMPONENT_MISSING_REQUIRED_PROPERTY",
+        entry?.nameRange || entry?.range || toFallbackRange(),
+        nodeId,
+        `Add: ${missingRequiredProps.map((name) => `${name}: ...`).join(" ")}`
+      );
+    }
+    const allowed = new Set(rules.allowedProps);
+    for (const [propName, propValue] of Object.entries(component.props)) {
+      if (!allowed.has(propName)) {
+        emitWarning(
+          `Property "${propName}" is not recognized for component "${componentType}".`,
+          "COMPONENT_UNKNOWN_PROPERTY",
+          getPropertyRange(entry, propName, "name"),
+          nodeId,
+          `Allowed properties: ${formatAllowedNames(
+            rules.allowedProps,
+            "(this component does not accept properties)"
+          )}`
+        );
+        continue;
+      }
+      const enumValues = rules.enumProps?.[propName];
+      if (enumValues) {
+        const normalizedValue = String(propValue);
+        if (!enumValues.includes(normalizedValue)) {
+          emitWarning(
+            `Invalid value "${normalizedValue}" for property "${propName}" in component "${componentType}".`,
+            "COMPONENT_INVALID_PROPERTY_VALUE",
+            getPropertyRange(entry, propName, "value"),
+            nodeId,
+            `Expected one of: ${enumValues.join(", ")}`
+          );
+        }
+      }
+      if (rules.booleanProps.has(propName) && !isBooleanLike(propValue)) {
+        emitWarning(
+          `Property "${propName}" in component "${componentType}" expects a boolean value.`,
+          "COMPONENT_BOOLEAN_PROPERTY_EXPECTED",
+          getPropertyRange(entry, propName, "value"),
+          nodeId,
+          "Use true or false."
+        );
+      }
+    }
+  };
+  const checkLayout = (layout) => {
+    const nodeId = layout._meta?.nodeId;
+    const entry = nodeId ? sourceMapByNodeId.get(nodeId) : void 0;
+    const rules = LAYOUT_RULES[layout.layoutType];
+    if (layout.children.length === 0) {
+      emitWarning(
+        `Layout "${layout.layoutType}" is empty.`,
+        "LAYOUT_EMPTY",
+        entry?.bodyRange || entry?.range || toFallbackRange(),
+        nodeId,
+        "Add at least one child: component, layout, or cell."
+      );
+    }
+    if (!rules) {
+      emitWarning(
+        `Layout type "${layout.layoutType}" is not recognized by semantic validation rules.`,
+        "LAYOUT_UNKNOWN_TYPE",
+        entry?.nameRange || entry?.range || toFallbackRange(),
+        nodeId,
+        `Use one of: ${Object.keys(LAYOUT_RULES).join(", ")}.`
+      );
+    } else {
+      const missingRequiredParams = getMissingRequiredNames(rules.requiredParams, layout.params);
+      if (missingRequiredParams.length > 0) {
+        emitWarning(
+          `Layout "${layout.layoutType}" is missing required parameter${missingRequiredParams.length === 1 ? "" : "s"}: ${missingRequiredParams.join(", ")}.`,
+          "LAYOUT_MISSING_REQUIRED_PARAMETER",
+          entry?.nameRange || entry?.range || toFallbackRange(),
+          nodeId,
+          `Add: ${missingRequiredParams.map((name) => `${name}: ...`).join(", ")}`
+        );
+      }
+      const allowed = new Set(rules.allowedParams);
+      for (const [paramName, paramValue] of Object.entries(layout.params)) {
+        if (!allowed.has(paramName)) {
+          emitWarning(
+            `Parameter "${paramName}" is not recognized for layout "${layout.layoutType}".`,
+            "LAYOUT_UNKNOWN_PARAMETER",
+            getPropertyRange(entry, paramName, "name"),
+            nodeId,
+            `Allowed parameters: ${formatAllowedNames(
+              rules.allowedParams,
+              "(this layout does not accept parameters)"
+            )}`
+          );
+          continue;
+        }
+        const enumValues = rules.enumParams?.[paramName];
+        if (enumValues) {
+          const normalizedValue = String(paramValue);
+          if (!enumValues.includes(normalizedValue)) {
+            emitWarning(
+              `Invalid value "${normalizedValue}" for parameter "${paramName}" in layout "${layout.layoutType}".`,
+              "LAYOUT_INVALID_PARAMETER_VALUE",
+              getPropertyRange(entry, paramName, "value"),
+              nodeId,
+              `Expected one of: ${enumValues.join(", ")}`
+            );
+          }
+        }
+        if (layout.layoutType === "grid" && paramName === "columns") {
+          const columns = Number(paramValue);
+          if (!Number.isFinite(columns) || columns < 1 || columns > 12) {
+            emitWarning(
+              `Grid "columns" must be a number between 1 and 12.`,
+              "LAYOUT_GRID_COLUMNS_RANGE",
+              getPropertyRange(entry, paramName, "value"),
+              nodeId,
+              "Use values from 1 to 12."
+            );
+          }
+        }
+        if (layout.layoutType === "split" && paramName === "sidebar") {
+          const sidebar = Number(paramValue);
+          if (!Number.isFinite(sidebar) || sidebar <= 0) {
+            emitWarning(
+              'Split "sidebar" must be a positive number.',
+              "LAYOUT_SPLIT_SIDEBAR_INVALID",
+              getPropertyRange(entry, paramName, "value"),
+              nodeId,
+              "Use a value like sidebar: 240."
+            );
+          }
+        }
+      }
+    }
+    for (const child of layout.children) {
+      if (child.type === "component") {
+        checkComponent(child);
+      } else if (child.type === "layout") {
+        checkLayout(child);
+      } else if (child.type === "cell") {
+        checkCell(child);
+      }
+    }
+  };
+  const checkCell = (cell) => {
+    const nodeId = cell._meta?.nodeId;
+    const entry = nodeId ? sourceMapByNodeId.get(nodeId) : void 0;
+    if (cell.props.span !== void 0) {
+      const span = Number(cell.props.span);
+      if (!Number.isFinite(span) || span < 1 || span > 12) {
+        emitWarning(
+          'Cell "span" should be a number between 1 and 12.',
+          "CELL_SPAN_RANGE",
+          getPropertyRange(entry, "span", "value"),
+          nodeId,
+          "Use values from 1 to 12."
+        );
+      }
+    }
+    for (const child of cell.children) {
+      if (child.type === "component") checkComponent(child);
+      if (child.type === "layout") checkLayout(child);
+    }
+  };
+  ast.screens.forEach((screen) => {
+    checkLayout(screen.layout);
+  });
+  return diagnostics;
+}
 function parseWireDSL(input) {
   const lexResult = WireDSLLexer.tokenize(input);
   if (lexResult.errors.length > 0) {
@@ -1310,29 +1679,56 @@ ${parserInstance.errors.map((e) => e.message).join("\n")}`);
   validateComponentDefinitionCycles(ast);
   return ast;
 }
-function parseWireDSLWithSourceMap(input, filePath = "<input>") {
+function parseWireDSLWithSourceMap(input, filePath = "<input>", options) {
+  const throwOnError = options?.throwOnError ?? true;
+  const includeSemanticWarnings = options?.includeSemanticWarnings ?? true;
+  const diagnostics = [];
   const lexResult = WireDSLLexer.tokenize(input);
   if (lexResult.errors.length > 0) {
-    throw new Error(`Lexer errors:
+    diagnostics.push(...lexResult.errors.map(createLexerDiagnostic));
+    if (throwOnError) {
+      throw new Error(`Lexer errors:
 ${lexResult.errors.map((e) => e.message).join("\n")}`);
+    }
+    return buildParseDiagnosticsResult(diagnostics);
   }
   parserInstance.input = lexResult.tokens;
   const cst = parserInstance.project();
   if (parserInstance.errors.length > 0) {
-    throw new Error(`Parser errors:
+    diagnostics.push(...parserInstance.errors.map(createParserDiagnostic));
+    if (throwOnError) {
+      throw new Error(`Parser errors:
 ${parserInstance.errors.map((e) => e.message).join("\n")}`);
+    }
+    return buildParseDiagnosticsResult(diagnostics);
   }
   const sourceMapBuilder = new SourceMapBuilder(filePath, input);
   const visitorWithSourceMap = new WireDSLVisitorWithSourceMap(sourceMapBuilder);
   const ast = visitorWithSourceMap.visit(cst);
-  validateComponentDefinitionCycles(ast);
   const sourceMap = sourceMapBuilder.build();
-  return {
-    ast,
-    sourceMap,
-    errors: []
-    // No errors if we got here (errors throw exceptions)
-  };
+  try {
+    validateComponentDefinitionCycles(ast);
+  } catch (error) {
+    const projectEntry = sourceMap.find((entry) => entry.type === "project");
+    diagnostics.push({
+      message: error instanceof Error ? error.message : "Semantic validation error",
+      severity: "error",
+      phase: "semantic",
+      code: "COMPONENT_CIRCULAR_DEFINITION",
+      range: projectEntry?.range || toFallbackRange(),
+      nodeId: projectEntry?.nodeId
+    });
+    if (throwOnError) {
+      throw error;
+    }
+  }
+  if (includeSemanticWarnings) {
+    diagnostics.push(...validateSemanticDiagnostics(ast, sourceMap));
+  }
+  if (!throwOnError) {
+    return buildParseDiagnosticsResult(diagnostics, ast, sourceMap);
+  }
+  return buildParseResult(ast, sourceMap, diagnostics);
 }
 function validateComponentDefinitionCycles(ast) {
   if (!ast.definedComponents || ast.definedComponents.length === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wire-dsl/engine",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "WireDSL engine - Parser, IR generator, layout engine, and SVG renderer (browser-safe, pure JS/TS)",
   "type": "module",
   "exports": {
@@ -31,7 +31,8 @@
   },
   "dependencies": {
     "chevrotain": "11.1.1",
-    "zod": "4.3.6"
+    "zod": "4.3.6",
+    "@wire-dsl/language-support": "0.2.4"
   },
   "devDependencies": {
     "@types/node": "25.2.0",