@dialecte/create 0.0.1

package/python/generate/helpers.py

@@ -0,0 +1,143 @@
+"""Shared utility functions for the generation pipeline."""
+import re
+import unicodedata
+from typing import Any
+
+
+# ---------------------------------------------------------------------------
+# XSD pattern → JS regex conversion
+# ---------------------------------------------------------------------------
+
+# XSD Unicode block names → (start, end) code-point ranges.
+# Covers all blocks that appear in IEC 61850 XSDs and common XML XSD patterns.
+# Source: Unicode 15.1 block ranges.
+_UNICODE_BLOCKS: dict[str, tuple[int, int]] = {
+    'IsBasicLatin':             (0x0000, 0x007F),
+    'IsLatin-1Supplement':      (0x0080, 0x00FF),
+    'IsLatinExtended-A':        (0x0100, 0x017F),
+    'IsLatinExtended-B':        (0x0180, 0x024F),
+    'IsIPAExtensions':          (0x0250, 0x02AF),
+    'IsSpacingModifierLetters': (0x02B0, 0x02FF),
+    'IsCombiningDiacriticalMarks': (0x0300, 0x036F),
+    'IsGreek':                  (0x0370, 0x03FF),
+    'IsCyrillic':               (0x0400, 0x04FF),
+    'IsArmenian':               (0x0530, 0x058F),
+    'IsHebrew':                 (0x0590, 0x05FF),
+    'IsArabic':                 (0x0600, 0x06FF),
+    'IsThai':                   (0x0E00, 0x0E7F),
+    'IsHiragana':               (0x3040, 0x309F),
+    'IsKatakana':               (0x30A0, 0x30FF),
+    'IsCJKUnifiedIdeographs':   (0x4E00, 0x9FFF),
+}
+
+
+def _block_range_escape(start: int, end: int) -> str:
+    """Emit a JS-safe character range string like ``\\x00-\\x7F``."""
+    def _esc(cp: int) -> str:
+        if cp <= 0xFF:
+            return f'\\x{cp:02x}'
+        if cp <= 0xFFFF:
+            return f'\\u{cp:04x}'
+        return f'\\u{{{cp:x}}}'
+    return f'{_esc(start)}-{_esc(end)}'
+
+
+def xsd_pattern_to_js(pattern: str) -> str:
+    """Convert an XSD regular expression to a JS-compatible regex string.
+
+    Handles:
+      - ``\\i`` / ``\\I`` (XML initial name char class)
+      - ``\\c`` / ``\\C`` (XML name char class)
+      - ``\\p{BlockName}`` → Unicode code-point range
+      - ``&#xHHHH;`` and ``&#DDD;`` XML character references
+    """
+    result = pattern
+
+    # \i  → XML initial name character (letter, underscore, colon)
+    result = result.replace(r'\i', '[A-Za-z_:]')
+    # \I  → complement
+    result = result.replace(r'\I', '[^A-Za-z_:]')
+
+    # \c  → XML name character (letter, digit, dot, dash, underscore, colon)
+    result = result.replace(r'\c', '[-.:0-9A-Z_a-z]')
+    # \C  → complement
+    result = result.replace(r'\C', '[^-.:0-9A-Z_a-z]')
+
+    # \p{BlockName} → code-point range
+    def _replace_block(m: re.Match[str]) -> str:
+        name = m.group(1)
+        rng = _UNICODE_BLOCKS.get(name)
+        if rng:
+            return _block_range_escape(*rng)
+        # Unknown block — leave as-is (will fail in JS, intentionally loud)
+        return m.group(0)
+
+    result = re.sub(r'\\p\{([^}]+)\}', _replace_block, result)
+
+    # XML hex character reference &#xHHHH;
+    result = re.sub(
+        r'&#x([0-9A-Fa-f]+);',
+        lambda m: chr(int(m.group(1), 16)),
+        result,
+    )
+    # XML decimal character reference &#DDD;
+    result = re.sub(
+        r'&#(\d+);',
+        lambda m: chr(int(m.group(1), 10)),
+        result,
+    )
+
+    return result
+def local_name(qname: str) -> str:
+    """Extract local name from a Clark-notation QName like '{uri}local' or 'prefix:local'."""
+    if qname.startswith('{'):
+        return qname.split('}', 1)[-1]
+    if ':' in qname:
+        return qname.split(':', 1)[-1]
+    return qname
+def namespace_uri(qname: str) -> str | None:
+    """Extract namespace URI from Clark-notation QName '{uri}local'. Returns None if absent."""
+    if qname.startswith('{'):
+        return qname[1:].split('}', 1)[0]
+    return None
+def tokenize_xpath(xpath: str) -> list[str]:
+    """Split an XPath selector into its element path tokens.
+
+    Strips namespace prefixes and leading './'.
+    Examples:
+        'tNS:LNode'       -> ['LNode']
+        './/SubNetwork'    -> ['SubNetwork']
+        'Bay/ConductingEquipment' -> ['Bay', 'ConductingEquipment']
+    """
+    if not xpath:
+        return []
+    # Remove leading ./ or .//
+    cleaned = re.sub(r'^\.//?', '', xpath)
+    parts = cleaned.split('/')
+    tokens = []
+    for part in parts:
+        part = part.strip()
+        if not part or part == '.':
+            continue
+        # Strip namespace prefix
+        tokens.append(local_name(part))
+    return tokens
+def get_facet_value(facet: Any) -> Any:
+    """Extract a scalar value from an xmlschema facet object.
+
+    Tries multiple access patterns that xmlschema uses across versions.
+    """
+    for attr in ('value', 'v', 'min_value', 'max_value'):
+        val = getattr(facet, attr, None)
+        if val is not None:
+            return val
+    # Fallback: try elem attribute
+    elem = getattr(facet, 'elem', None)
+    if elem is not None:
+        raw = elem.get('value')
+        if raw is not None:
+            try:
+                return int(raw)
+            except (ValueError, TypeError):
+                return raw
+    return None

package/python/generate/ir.py

@@ -0,0 +1,81 @@
+"""Internal Representation — Python dataclasses for XSD schema data.
+
+Never serialized directly. Used as the in-memory model between
+Parse → Collect → Derive → Emit phases.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from generate.xpath_parser import FieldPath, SelectorPath
+@dataclass
+class Namespace:
+    prefix: str
+    uri: str
+@dataclass
+class Facets:
+    enumeration: list[str] | None = None
+    pattern: list[str] | None = None
+    min_length: int | None = None
+    max_length: int | None = None
+    length: int | None = None
+    min_inclusive: int | str | None = None
+    max_inclusive: int | str | None = None
+    min_exclusive: int | str | None = None
+    max_exclusive: int | str | None = None
+    total_digits: int | None = None
+    fraction_digits: int | None = None
+    white_space: str | None = None  # 'preserve' | 'replace' | 'collapse'
+
+    def is_empty(self) -> bool:
+        return all(v is None for v in vars(self).values())
+@dataclass
+class AttributeDef:
+    required: bool = False
+    default: str | None = None
+    fixed: str | None = None
+    namespace: Namespace | None = None
+    facets: Facets | None = None
+@dataclass
+class IdentityConstraint:
+    kind: str  # 'unique' | 'key' | 'keyref'
+    name: str
+    selector: list[SelectorPath]  # parsed XPath alternatives (union)
+    fields: list[FieldPath]  # parsed field XPath expressions
+    deep: bool = False
+    refer: str | None = None  # keyref only
+
+@dataclass
+class ChildDef:
+    required: bool = False
+    min_occurs: int = 0
+    max_occurs: int | None = None  # None = unbounded
+    constraints: list[IdentityConstraint] | None = None
+    facets: Facets | None = None
+
+@dataclass
+class ChoiceGroup:
+    options: list[str]
+    min_occurs: int = 0
+    max_occurs: int | None = None
+@dataclass
+class TextContent:
+    facets: Facets | None = None
+@dataclass
+class ElementDef:
+    tag: str
+    namespace: Namespace
+    documentation: str | None = None
+    parents: list[str] = field(default_factory=list)
+    attr_sequence: list[str] = field(default_factory=list)
+    attr_any: bool = False
+    attributes: dict[str, AttributeDef] = field(default_factory=dict)
+    child_sequence: list[str] = field(default_factory=list)
+    child_any: bool = False
+    children: dict[str, ChildDef] = field(default_factory=dict)
+    choices: list[ChoiceGroup] = field(default_factory=list)
+    constraints: list[IdentityConstraint] = field(default_factory=list)
+    text_content: TextContent | None = None
+    identity_fields: list[str] = field(default_factory=list)

package/python/generate/orphans.py

@@ -0,0 +1,69 @@
+"""Orphan element detection and parent injection from a JSON sidecar mapping.
+
+Inserted between Collect and Derive phases. Handles XSD global elements that
+are children-via-xs:any wildcards (e.g. IEC 61850-6-100 extension elements)
+whose parent-child relationships are domain knowledge, not XSD-declared.
+"""
+import json
+from pathlib import Path
+
+from generate.ir import ChildDef, ElementDef
+
+
+def load_parent_mapping(entry_path: Path) -> dict[str, list[str]]:
+    """Read parent-mapping.json from the same directory as the entry XSD.
+
+    Returns empty dict if the file does not exist.
+    """
+    mapping_file = entry_path.parent / 'parent-mapping.json'
+    if not mapping_file.exists():
+        return {}
+    with open(mapping_file) as f:
+        return json.load(f)
+
+
+def detect_orphans(elements: dict[str, ElementDef], root_name: str) -> list[str]:
+    """Return parentless element names, excluding the root element."""
+    return sorted(
+        name for name, e in elements.items()
+        if not e.parents and name != root_name
+    )
+
+
+def inject_orphan_parents(
+    elements: dict[str, ElementDef],
+    mapping: dict[str, list[str]],
+    root_name: str = '',
+) -> list[str]:
+    """Inject parent-child links from the sidecar mapping.
+
+    For each mapped orphan:
+      - Sets element.parents to the mapped parent list
+      - Adds element to each parent's children dict and child_sequence
+
+    *root_name* is excluded from orphan detection.
+    Returns names of orphan elements NOT covered by the mapping (for warnings).
+    """
+    orphan_names = {name for name, e in elements.items() if not e.parents and name != root_name}
+    mapped_orphans = orphan_names & mapping.keys()
+    unmapped = sorted(orphan_names - mapping.keys())
+
+    for name in sorted(mapped_orphans):
+        parents = mapping[name]
+
+        elem = elements[name]
+        valid_parents = [p for p in parents if p in elements]
+        elem.parents = valid_parents
+
+        for parent_name in valid_parents:
+            parent = elements[parent_name]
+            if name not in parent.children:
+                parent.children[name] = ChildDef(
+                    required=False,
+                    min_occurs=0,
+                    max_occurs=None,
+                )
+            if name not in parent.child_sequence:
+                parent.child_sequence.append(name)
+
+    return unmapped

package/python/generate/xpath_parser.py

@@ -0,0 +1,167 @@
+"""Parse XSD identity-constraint XPath selectors and fields (§3.11.6).
+
+Implements the restricted grammar from XSD 1.1 Part 1, §3.11.6.2 (selectors)
+and §3.11.6.3 (fields):
+
+  Selector  ::=  Path ( '|' Path )*
+  Path      ::=  ('.' '//')? Step ( '/' Step )*
+  Step      ::=  '.' | NameTest
+  NameTest  ::=  QName | '*' | NCName ':*'
+
+Field variant: last step can also be ``@ NameTest``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+from generate.helpers import local_name
+
+
+# ---------------------------------------------------------------------------
+# IR dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class XPathStep:
+    """A single step in a selector/field path.
+
+    kind:
+      - 'self'        → the literal '.'
+      - 'name'        → local element name (ns stripped)
+      - 'wildcard'    → '*'
+      - 'ns-wildcard' → 'NCName:*'  (value = NCName)
+    """
+    kind: Literal['self', 'name', 'wildcard', 'ns-wildcard']
+    value: str | None = None
+
+
+@dataclass(frozen=True)
+class SelectorPath:
+    """One alternative of a selector (before/after '|')."""
+    deep: bool = False
+    steps: tuple[XPathStep, ...] = ()
+
+
+@dataclass(frozen=True)
+class FieldTarget:
+    """The terminal target of a field XPath — element or attribute.
+
+    kind:
+      - 'element'   → child element name
+      - 'attribute'  → @attrName
+      - 'wildcard'   → * or @*
+      - 'ns-wildcard' → NCName:* or @NCName:*
+    """
+    kind: Literal['element', 'attribute', 'wildcard', 'ns-wildcard']
+    value: str | None = None
+    is_attribute: bool = False
+
+
+@dataclass(frozen=True)
+class FieldPath:
+    """Parsed XPath field expression."""
+    deep: bool = False
+    steps: tuple[XPathStep, ...] = ()
+    target: FieldTarget = field(default_factory=lambda: FieldTarget(kind='wildcard'))
+
+
+# ---------------------------------------------------------------------------
+# Parser
+# ---------------------------------------------------------------------------
+
+_PIPE_RE = re.compile(r'\s*\|\s*')
+
+
+def parse_selector(xpath: str) -> list[SelectorPath]:
+    """Parse a selector XPath into a list of SelectorPath alternatives."""
+    if not xpath or not xpath.strip():
+        return []
+    alternatives = _PIPE_RE.split(xpath.strip())
+    return [_parse_selector_path(alt.strip()) for alt in alternatives if alt.strip()]
+
+
+def parse_field(xpath: str) -> FieldPath:
+    """Parse a field XPath into a FieldPath."""
+    if not xpath or not xpath.strip():
+        return FieldPath()
+    return _parse_field_path(xpath.strip())
+
+
+# ---------------------------------------------------------------------------
+# Internal
+# ---------------------------------------------------------------------------
+
+def _parse_selector_path(raw: str) -> SelectorPath:
+    """Parse one selector alternative (no '|')."""
+    deep, remainder = _consume_deep_prefix(raw)
+    tokens = _split_steps(remainder)
+    steps = tuple(_parse_step(t) for t in tokens)
+    return SelectorPath(deep=deep, steps=steps)
+
+
+def _parse_field_path(raw: str) -> FieldPath:
+    """Parse a field XPath expression."""
+    deep, remainder = _consume_deep_prefix(raw)
+    tokens = _split_steps(remainder)
+
+    if not tokens:
+        return FieldPath(deep=deep)
+
+    # Check if last token is an attribute reference
+    last = tokens[-1]
+    if last.startswith('@'):
+        steps = tuple(_parse_step(t) for t in tokens[:-1])
+        target = _parse_field_target(last, is_attribute=True)
+    else:
+        steps = tuple(_parse_step(t) for t in tokens[:-1])
+        target = _parse_field_target(last, is_attribute=False)
+
+    return FieldPath(deep=deep, steps=steps, target=target)
+
+
+def _consume_deep_prefix(raw: str) -> tuple[bool, str]:
+    """Strip leading './' or './/' and return (deep, remainder)."""
+    if raw.startswith('.//'):
+        return True, raw[3:]
+    if raw.startswith('./'):
+        return False, raw[2:]
+    return False, raw
+
+
+def _split_steps(raw: str) -> list[str]:
+    """Split path into step tokens on '/' boundaries."""
+    if not raw:
+        return []
+    parts = raw.split('/')
+    return [p.strip() for p in parts if p.strip()]
+
+
+def _parse_step(token: str) -> XPathStep:
+    """Parse a single step token into an XPathStep."""
+    if token == '.':
+        return XPathStep(kind='self')
+    if token == '*':
+        return XPathStep(kind='wildcard')
+    if token.endswith(':*'):
+        prefix = token[:-2]
+        return XPathStep(kind='ns-wildcard', value=prefix)
+    # QName — strip namespace prefix
+    return XPathStep(kind='name', value=local_name(token))
+
+
+def _parse_field_target(token: str, *, is_attribute: bool) -> FieldTarget:
+    """Parse the terminal token of a field path."""
+    raw = token.lstrip('@').strip()
+
+    if raw == '*':
+        return FieldTarget(kind='wildcard', is_attribute=is_attribute)
+    if raw.endswith(':*'):
+        return FieldTarget(kind='ns-wildcard', value=raw[:-2], is_attribute=is_attribute)
+    return FieldTarget(
+        kind='attribute' if is_attribute else 'element',
+        value=local_name(raw),
+        is_attribute=is_attribute,
+    )

package/python/generate/xsi_type.py

@@ -0,0 +1,150 @@
+"""xsi:type expansion — resolve XSD type-derivation polymorphism into the IR.
+
+Some schemas (notably IEC 61131-10) model their content polymorphically: a named
+element slot is declared with an **abstract** complex type, and instances select a
+concrete variant at runtime via the ``xsi:type`` attribute. For example::
+
+    <BodyContent xsi:type="FBD"><Network>…</Network></BodyContent>
+
+Here ``BodyContent`` is the element name; ``FBD`` is a *type* selected via
+``xsi:type``. The concrete forms (``FBD``, ``Block``, ``DataSource``, …) have **no**
+global element declarations, so the element-instance-driven collector never reaches
+their children.
+
+This module reverses the XSD type-derivation graph (``schema.maps.types``) to find,
+for any declared type, the concrete types that may substitute it. Their children and
+attributes are unioned into the slot element (as optional members, since each is only
+required for a specific ``xsi:type``), and an ``xsi:type`` enumeration attribute is
+added listing the valid variant names.
+
+This expansion runs automatically for every schema. For slots declared with a
+concrete (non-abstract) type that has no derived variants, ``_concrete_substitution_types``
+returns ``[]`` and ``expand`` is a no-op — zero overhead. Schemas may freely mix
+abstract-typed slots (expanded) with concrete-typed slots (untouched).
+"""
+from typing import Any
+
+from generate.extractors.attributes import extract_attributes
+from generate.extractors.children import extract_children_from_type, iter_type_child_elements
+from generate.helpers import local_name
+from generate.ir import AttributeDef, ChildDef, Facets, Namespace
+
+XSI_NAMESPACE = Namespace(prefix='xsi', uri='http://www.w3.org/2001/XMLSchema-instance')
+XSI_TYPE_KEY = 'xsi:type'
+
+
+class XsiTypeExpander:
+    """Expands abstract-typed element slots with their xsi:type substitution variants."""
+
+    def __init__(self, schema: Any) -> None:
+        self._derived = _build_derived_map(schema)
+
+    def expand(
+        self,
+        xsd_elem: Any,
+        attr_seq: list[str],
+        attrs: dict[str, AttributeDef],
+        child_seq: list[str],
+        children: dict[str, ChildDef],
+    ) -> None:
+        """Union substitution-variant children/attributes into an element's IR (in place).
+
+        Idempotent and additive: existing entries are never overwritten or removed.
+        Safe to call multiple times for the same element name (e.g. when the same slot
+        is declared in several parents with different abstract base types).
+        """
+        types = self._concrete_substitution_types(getattr(xsd_elem, 'type', None))
+        if not types:
+            return
+
+        for variant in types:
+            v_seq, _v_any, v_details = extract_children_from_type(variant)
+            for name in v_seq:
+                if name in children:
+                    continue
+                detail = v_details[name]
+                children[name] = ChildDef(
+                    required=False,
+                    min_occurs=0,
+                    max_occurs=detail.max_occurs,
+                    constraints=detail.constraints,
+                    facets=detail.facets,
+                )
+                child_seq.append(name)
+
+        for variant in types:
+            a_seq, _a_any, a_details = extract_attributes(variant)
+            for key in a_seq:
+                if key in attrs:
+                    continue
+                detail = a_details[key]
+                attrs[key] = AttributeDef(
+                    required=False,
+                    default=detail.default,
+                    fixed=detail.fixed,
+                    namespace=detail.namespace,
+                    facets=detail.facets,
+                )
+                attr_seq.append(key)
+
+        variant_names = sorted(local_name(getattr(t, 'name', '') or '') for t in types)
+        if variant_names and XSI_TYPE_KEY not in attrs:
+            attrs[XSI_TYPE_KEY] = AttributeDef(
+                required=False,
+                namespace=XSI_NAMESPACE,
+                facets=Facets(enumeration=variant_names),
+            )
+            attr_seq.append(XSI_TYPE_KEY)
+
+        # Keep attribute order consistent with extract_attributes (alphabetical).
+        attr_seq.sort()
+
+    def iter_variant_child_elements(self, xsd_elem: Any):
+        """Yield XsdElement children contributed by an element's substitution variants.
+
+        Used by the collector to recurse into elements that are only reachable through
+        xsi:type substitution (e.g. ``Network`` under an abstract ``BodyContent`` slot).
+        """
+        for variant in self._concrete_substitution_types(getattr(xsd_elem, 'type', None)):
+            yield from iter_type_child_elements(variant)
+
+    def _concrete_substitution_types(self, xsd_type: Any) -> list[Any]:
+        """Transitive concrete types derivable from *xsd_type* (BFS through abstract bases)."""
+        if xsd_type is None:
+            return []
+        result: list[Any] = []
+        seen: set[int] = set()
+        queue: list[Any] = [xsd_type]
+        while queue:
+            current = queue.pop(0)
+            for derived in self._derived.get(id(current), []):
+                if id(derived) in seen:
+                    continue
+                seen.add(id(derived))
+                queue.append(derived)
+                if not getattr(derived, 'abstract', False):
+                    result.append(derived)
+        result.sort(key=lambda t: local_name(getattr(t, 'name', '') or ''))
+        return result
+
+
+def _build_derived_map(schema: Any) -> dict[int, list[Any]]:
+    """Map ``id(base_type)`` → directly-derived complex types across all schemas.
+
+    xmlschema API:
+      XMLSchema.maps.types: dict[str, XsdType] — every global type in the schema set
+      XsdComplexType.base_type: XsdType | None
+      XsdComplexType.derivation: 'extension' | 'restriction' | None
+    """
+    derived: dict[int, list[Any]] = {}
+    types = getattr(getattr(schema, 'maps', None), 'types', None)
+    if not types:
+        return derived
+    for xsd_type in types.values():
+        base = getattr(xsd_type, 'base_type', None)
+        if base is None:
+            continue
+        if getattr(xsd_type, 'derivation', None) not in ('extension', 'restriction'):
+            continue
+        derived.setdefault(id(base), []).append(xsd_type)
+    return derived

package/python/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "dialecte-generate"
+version = "0.1.0"
+description = "XSD to TypeScript definition generator for Dialecte"
+requires-python = ">=3.13"
+dependencies = ["xmlschema>=4.3.1"]
+
+[project.optional-dependencies]
+dev = ["pytest>=9.0.2"]
+
+[project.scripts]
+dialecte-generate = "generate.__main__:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

package/templates/dialecte/README.md

@@ -0,0 +1,39 @@
+# **packageName**
+
+Dialecte SDK for `__dialecteId__`.
+
+Built on [`@dialecte/core`](https://github.com/dialecte/core) and scaffolded with
+[`@dialecte/create`](https://github.com/dialecte/create).
+
+## Install
+
+```sh
+npm install __packageName__ @dialecte/core
+```
+
+## Usage
+
+```ts
+import { create__DialecteName__Project } from '__packageName__/__version__'
+
+const project = create__DialecteName__Project()
+await project.open('my-project')
+```
+
+## Regenerate definitions
+
+The element definitions in `src/__version__/definition/` are generated from an XSD schema.
+To regenerate after a schema change:
+
+```sh
+npm create @dialecte generate -- --entry ./path/to/schema.xsd --out-dir ./src/__version__/definition
+```
+
+## Develop
+
+```sh
+npm install
+npm run build        # type-check + bundle (ESM + d.ts)
+npm test             # vitest (browser)
+npm run doc:dev      # vitepress docs
+```

package/templates/dialecte/_gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+*.tsbuildinfo
+.DS_Store

package/templates/dialecte/docs/.vitepress/config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+	title: '__packageName__',
+	description: 'Dialecte SDK for __dialecteId__',
+	themeConfig: {
+		nav: [{ text: 'Guide', link: '/' }],
+		sidebar: [
+			{
+				text: 'Introduction',
+				items: [{ text: 'Getting started', link: '/' }],
+			},
+		],
+	},
+})