@canonical/anatomy-dsl 0.2.0

package/README.md

@@ -0,0 +1,145 @@
+# Anatomy DSL
+
+A YAML-based DSL for representing design system component anatomies — platform-agnostic structural primitives that precede implementation.
+
+## Quick Example
+
+```yaml
+---
+node:
+  uri: global.component.button
+  styles:
+    layout.type: flow
+    layout.direction: horizontal
+    layout.align: center
+    spacing.internal: spacing/medium
+    appearance.background: color/surface/button
+    appearance.radius: radius/button
+  edges:
+    - node:
+        uri: global.subcomponent.button-icon
+      relation:
+        cardinality: "0..1"
+        slotName: icon
+    - node:
+        role: label text
+      relation:
+        cardinality: "1"
+        slotName: default
+```
+
+Style values are **design token paths** (`spacing/medium`, `color/surface/button`) — forward-slash delimited references resolved at runtime against the active theme. Primitives like `flow` and `center` are used for layout semantics that don't vary across themes.
+
+## Install
+
+```sh
+bun add -D @canonical/anatomy-dsl
+```
+
+## Usage
+
+```typescript
+import { parse } from "yaml";
+import { parseAnatomyYAML, anatomyToTTL } from "@canonical/anatomy-dsl";
+
+const raw = parse(readFileSync("Button.anatomy.yaml", "utf8"));
+const spec = parseAnatomyYAML(raw);
+const ttl = anatomyToTTL(spec);
+```
+
+The button example above produces:
+
+```turtle
+@prefix : <http://anatomy-dsl.example.org/ontology#> .
+
+[] a :Specification ;
+    :rootNode [
+        a :NamedNode ;
+        :uri "global.component.button" ;
+        :hasStyle
+            [ :styleKey "layout.type" ; :styleValue "flow" ] ,
+            [ :styleKey "layout.direction" ; :styleValue "horizontal" ] ,
+            [ :styleKey "layout.align" ; :styleValue "center" ] ,
+            [ :styleKey "spacing.internal" ; :styleValue "spacing/medium" ] ,
+            [ :styleKey "appearance.background" ; :styleValue "color/surface/button" ] ,
+            [ :styleKey "appearance.radius" ; :styleValue "radius/button" ] ;
+        :hasEdge [
+            a :Edge ;
+            :edgeTarget [
+                a :NamedNode ;
+                :uri "global.subcomponent.button-icon"
+            ] ;
+            :hasRelation [
+                a :Relation ;
+                :cardinality "0..1" ;
+                :slotName "icon"
+            ]
+        ] , [
+            a :Edge ;
+            :edgeTarget [
+                a :AnonymousNode ;
+                :role "label text"
+            ] ;
+            :hasRelation [
+                a :Relation ;
+                :cardinality "1" ;
+                :slotName "default"
+            ]
+        ]
+    ] .
+```
+
+## API
+
+### `parseAnatomyYAML(raw: unknown): Specification`
+
+Converts a parsed YAML object (from any YAML library) into the typed `Specification` structure. Handles field mapping between the YAML format and the TypeScript types.
+
+### `anatomyToTTL(spec: Specification): string`
+
+Pure function. Takes a `Specification`, returns a Turtle (RDF) string. No I/O, no side effects.
+
+### Types
+
+All types mirror the [OWL ontology](definitions/ontology.ttl) exactly:
+
+| Type | Description |
+|------|-------------|
+| `Specification` | Root — contains exactly one `NamedNode` |
+| `NamedNode` | Design system entity with a `uri` |
+| `AnonymousNode` | Structural element with a `role` |
+| `Node` | `NamedNode \| AnonymousNode` (discriminated on `type`) |
+| `Edge` | Reified parent→child relationship |
+| `Relation` | Cardinality and optional slot name |
+| `Style` | Reified key-value tuple |
+| `Switch` | Polymorphic position (discriminator: `props \| internal \| override`) |
+| `SwitchCase` | One alternative within a switch |
+
+## Repository Structure
+
+```
+definitions/   Turtle ontology (OWL) + SHACL shapes
+schemas/       JSON Schema for validating .anatomy.yaml files
+docs/          API reference (merged WD404 + WD404.1)
+examples/      Example anatomy files (YAML + Turtle pairs)
+src/           TypeScript types, parser, and transform
+```
+
+## Scope
+
+The Anatomy DSL describes **structure only**. It does not handle:
+
+- **Prop mapping** — which props a component accepts and how they map to behaviour
+- **State or state machines** — component states, transitions, or interaction logic
+- **Modifier descriptions** — only design token references are supported, not semantic modifier definitions
+
+## Design Notes
+
+Styles are modelled as reified key-value tuples (`hasStyle [ styleKey "…" ; styleValue "…" ]`). This keeps the ontology open-ended while remaining lossless. Frequently used style keys may be promoted to first-class datatype properties in a future version.
+
+## Specification Status
+
+| Index   | Title                    | Status         |
+|---------|--------------------------|----------------|
+| [WD404](https://docs.google.com/document/d/1eFr-SNsAZyidnZzpWp1Jeegiat_SSM7mOW_G8p3nXo8/edit?tab=t.pndvuecem8cf)   | Anatomy DSL              | Approved       |
+| [WD404.1](https://docs.google.com/document/d/1eFr-SNsAZyidnZzpWp1Jeegiat_SSM7mOW_G8p3nXo8/edit?tab=t.pndvuecem8cf) | Anatomy DSL — Addendum 1 | Pending Review |

package/dist/esm/index.js

@@ -0,0 +1,2 @@
+export { parseAnatomyYAML } from "./parse.js";
+export { anatomyToTTL } from "./transform.js";

package/dist/esm/parse.js

@@ -0,0 +1,72 @@
+export function parseAnatomyYAML(raw) {
+    const doc = raw;
+    return {
+        root: toNamedNode(doc.node),
+    };
+}
+function toNamedNode(raw) {
+    return {
+        type: "named",
+        uri: raw.uri,
+        ...(raw.styles ? { styles: toStyles(raw.styles) } : {}),
+        ...(raw.edges ? { edges: raw.edges.map(toEdge) } : {}),
+    };
+}
+function toNode(raw) {
+    if ("uri" in raw && raw.uri) {
+        return toNamedNode(raw);
+    }
+    const anon = raw;
+    return {
+        type: "anonymous",
+        role: anon.role,
+        ...(anon.styles ? { styles: toStyles(anon.styles) } : {}),
+        ...(anon.edges ? { edges: anon.edges.map(toEdge) } : {}),
+    };
+}
+function toStyles(raw) {
+    return Object.entries(raw).map(([key, value]) => ({
+        key,
+        value: String(value),
+    }));
+}
+function toEdge(raw) {
+    let target;
+    if (raw.switch) {
+        target = toSwitch(raw.switch);
+    }
+    else if (raw.node) {
+        target = toNode(raw.node);
+    }
+    else if (raw.uri) {
+        target = { type: "named", uri: raw.uri };
+    }
+    else {
+        throw new Error("Edge must have node, uri, or switch");
+    }
+    return {
+        target,
+        relation: toRelation(raw.relation),
+    };
+}
+function toSwitch(raw) {
+    return {
+        discriminator: raw.on,
+        cases: raw.cases.map(toSwitchCase),
+    };
+}
+function toSwitchCase(raw) {
+    if (raw.uri !== undefined) {
+        const node = { type: "named", uri: raw.uri };
+        return { value: raw.uri, node };
+    }
+    const node = toNode(raw.node);
+    const value = node.type === "named" ? node.uri : node.role;
+    return { value, node };
+}
+function toRelation(raw) {
+    return {
+        cardinality: raw.cardinality,
+        ...(raw.slotName ? { slotName: raw.slotName } : {}),
+    };
+}

package/dist/esm/transform.js

@@ -0,0 +1,116 @@
+const PREFIX = "@prefix : <http://anatomy-dsl.example.org/ontology#> .";
+const INDENT = "    ";
+export function anatomyToTTL(spec) {
+    const lines = [PREFIX, ""];
+    lines.push("[] a :Specification ;");
+    lines.push(`${INDENT}:rootNode [`);
+    writeNode(lines, spec.root, 2);
+    lines.push(`${INDENT}] .`);
+    return `${lines.join("\n")}\n`;
+}
+function writeNode(lines, node, depth) {
+    if (node.type === "named") {
+        writeNamedNode(lines, node, depth);
+    }
+    else {
+        writeAnonymousNode(lines, node, depth);
+    }
+    const styles = node.styles ?? [];
+    const edges = node.edges ?? [];
+    if (styles.length > 0) {
+        writeStyles(lines, styles, depth, edges.length === 0);
+    }
+    if (edges.length > 0) {
+        writeEdges(lines, edges, depth);
+    }
+}
+function writeNamedNode(lines, node, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :NamedNode ;`);
+    const hasMore = (node.styles && node.styles.length > 0) ||
+        (node.edges && node.edges.length > 0);
+    lines.push(`${indent}:uri "${node.uri}"${hasMore ? " ;" : ""}`);
+}
+function writeAnonymousNode(lines, node, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :AnonymousNode ;`);
+    const hasMore = (node.styles && node.styles.length > 0) ||
+        (node.edges && node.edges.length > 0);
+    lines.push(`${indent}:role "${node.role}"${hasMore ? " ;" : ""}`);
+}
+function writeStyles(lines, styles, depth, isLast) {
+    const indent = INDENT.repeat(depth);
+    const innerIndent = INDENT.repeat(depth + 1);
+    lines.push(`${indent}:hasStyle`);
+    for (const [i, style] of styles.entries()) {
+        const sep = i < styles.length - 1 ? " ," : isLast ? "" : " ;";
+        lines.push(`${innerIndent}[ :styleKey "${style.key}" ; :styleValue "${style.value}" ]${sep}`);
+    }
+}
+function writeEdges(lines, edges, depth) {
+    const indent = INDENT.repeat(depth);
+    for (const [i, edge] of edges.entries()) {
+        if (i === 0) {
+            lines.push(`${indent}:hasEdge [`);
+        }
+        else {
+            lines.push(`${indent}] , [`);
+        }
+        writeEdge(lines, edge, depth + 1);
+    }
+    lines.push(`${indent}]`);
+}
+function writeEdge(lines, edge, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :Edge ;`);
+    if (isSwitch(edge.target)) {
+        lines.push(`${indent}:edgeSwitch [`);
+        writeSwitch(lines, edge.target, depth + 1);
+        lines.push(`${indent}] ;`);
+    }
+    else {
+        lines.push(`${indent}:edgeTarget [`);
+        writeNode(lines, edge.target, depth + 1);
+        lines.push(`${indent}] ;`);
+    }
+    writeRelation(lines, edge, depth);
+}
+function writeSwitch(lines, sw, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :Switch ;`);
+    lines.push(`${indent}:discriminator "${sw.discriminator}" ;`);
+    for (const [i, sc] of sw.cases.entries()) {
+        if (i === 0) {
+            lines.push(`${indent}:hasCase [`);
+        }
+        else {
+            lines.push(`${indent}] , [`);
+        }
+        writeSwitchCase(lines, sc, depth + 1);
+    }
+    lines.push(`${indent}]`);
+}
+function writeSwitchCase(lines, sc, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :SwitchCase ;`);
+    lines.push(`${indent}:caseNode [`);
+    writeNode(lines, sc.node, depth + 1);
+    lines.push(`${indent}]`);
+}
+function writeRelation(lines, edge, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}:hasRelation [`);
+    const inner = INDENT.repeat(depth + 1);
+    lines.push(`${inner}a :Relation ;`);
+    if (edge.relation.slotName) {
+        lines.push(`${inner}:cardinality "${edge.relation.cardinality}" ;`);
+        lines.push(`${inner}:slotName "${edge.relation.slotName}"`);
+    }
+    else {
+        lines.push(`${inner}:cardinality "${edge.relation.cardinality}"`);
+    }
+    lines.push(`${indent}]`);
+}
+function isSwitch(target) {
+    return "discriminator" in target;
+}

package/dist/esm/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { parseAnatomyYAML } from "./parse.js";
+export { anatomyToTTL } from "./transform.js";
+export type { AnonymousNode, Edge, NamedNode, Node, Relation, Specification, Style, Switch, SwitchCase, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { parseAnatomyYAML } from "./parse.js";
+export { anatomyToTTL } from "./transform.js";

package/dist/parse.d.ts

@@ -0,0 +1,2 @@
+import type { Specification } from "./types.js";
+export declare function parseAnatomyYAML(raw: unknown): Specification;

package/dist/parse.js

@@ -0,0 +1,72 @@
+export function parseAnatomyYAML(raw) {
+    const doc = raw;
+    return {
+        root: toNamedNode(doc.node),
+    };
+}
+function toNamedNode(raw) {
+    return {
+        type: "named",
+        uri: raw.uri,
+        ...(raw.styles ? { styles: toStyles(raw.styles) } : {}),
+        ...(raw.edges ? { edges: raw.edges.map(toEdge) } : {}),
+    };
+}
+function toNode(raw) {
+    if ("uri" in raw && raw.uri) {
+        return toNamedNode(raw);
+    }
+    const anon = raw;
+    return {
+        type: "anonymous",
+        role: anon.role,
+        ...(anon.styles ? { styles: toStyles(anon.styles) } : {}),
+        ...(anon.edges ? { edges: anon.edges.map(toEdge) } : {}),
+    };
+}
+function toStyles(raw) {
+    return Object.entries(raw).map(([key, value]) => ({
+        key,
+        value: String(value),
+    }));
+}
+function toEdge(raw) {
+    let target;
+    if (raw.switch) {
+        target = toSwitch(raw.switch);
+    }
+    else if (raw.node) {
+        target = toNode(raw.node);
+    }
+    else if (raw.uri) {
+        target = { type: "named", uri: raw.uri };
+    }
+    else {
+        throw new Error("Edge must have node, uri, or switch");
+    }
+    return {
+        target,
+        relation: toRelation(raw.relation),
+    };
+}
+function toSwitch(raw) {
+    return {
+        discriminator: raw.on,
+        cases: raw.cases.map(toSwitchCase),
+    };
+}
+function toSwitchCase(raw) {
+    if (raw.uri !== undefined) {
+        const node = { type: "named", uri: raw.uri };
+        return { value: raw.uri, node };
+    }
+    const node = toNode(raw.node);
+    const value = node.type === "named" ? node.uri : node.role;
+    return { value, node };
+}
+function toRelation(raw) {
+    return {
+        cardinality: raw.cardinality,
+        ...(raw.slotName ? { slotName: raw.slotName } : {}),
+    };
+}

package/dist/transform.d.ts

@@ -0,0 +1,2 @@
+import type { Specification } from "./types.js";
+export declare function anatomyToTTL(spec: Specification): string;

package/dist/transform.js

@@ -0,0 +1,114 @@
+const PREFIX = "@prefix : <http://anatomy-dsl.example.org/ontology#> .";
+const INDENT = "    ";
+export function anatomyToTTL(spec) {
+    const lines = [PREFIX, ""];
+    lines.push("[] a :Specification ;");
+    lines.push(`${INDENT}:rootNode [`);
+    writeNode(lines, spec.root, 2);
+    lines.push(`${INDENT}] .`);
+    return `${lines.join("\n")}\n`;
+}
+function writeNode(lines, node, depth) {
+    if (node.type === "named") {
+        writeNamedNode(lines, node, depth);
+    }
+    else {
+        writeAnonymousNode(lines, node, depth);
+    }
+    const styles = node.styles ?? [];
+    const edges = node.edges ?? [];
+    if (styles.length > 0) {
+        writeStyles(lines, styles, depth, edges.length === 0);
+    }
+    if (edges.length > 0) {
+        writeEdges(lines, edges, depth);
+    }
+}
+function writeNamedNode(lines, node, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :NamedNode ;`);
+    const hasMore = (node.styles && node.styles.length > 0) || (node.edges && node.edges.length > 0);
+    lines.push(`${indent}:uri "${node.uri}"${hasMore ? " ;" : ""}`);
+}
+function writeAnonymousNode(lines, node, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :AnonymousNode ;`);
+    const hasMore = (node.styles && node.styles.length > 0) || (node.edges && node.edges.length > 0);
+    lines.push(`${indent}:role "${node.role}"${hasMore ? " ;" : ""}`);
+}
+function writeStyles(lines, styles, depth, isLast) {
+    const indent = INDENT.repeat(depth);
+    const innerIndent = INDENT.repeat(depth + 1);
+    lines.push(`${indent}:hasStyle`);
+    for (const [i, style] of styles.entries()) {
+        const sep = i < styles.length - 1 ? " ," : isLast ? "" : " ;";
+        lines.push(`${innerIndent}[ :styleKey "${style.key}" ; :styleValue "${style.value}" ]${sep}`);
+    }
+}
+function writeEdges(lines, edges, depth) {
+    const indent = INDENT.repeat(depth);
+    for (const [i, edge] of edges.entries()) {
+        if (i === 0) {
+            lines.push(`${indent}:hasEdge [`);
+        }
+        else {
+            lines.push(`${indent}] , [`);
+        }
+        writeEdge(lines, edge, depth + 1);
+    }
+    lines.push(`${indent}]`);
+}
+function writeEdge(lines, edge, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :Edge ;`);
+    if (isSwitch(edge.target)) {
+        lines.push(`${indent}:edgeSwitch [`);
+        writeSwitch(lines, edge.target, depth + 1);
+        lines.push(`${indent}] ;`);
+    }
+    else {
+        lines.push(`${indent}:edgeTarget [`);
+        writeNode(lines, edge.target, depth + 1);
+        lines.push(`${indent}] ;`);
+    }
+    writeRelation(lines, edge, depth);
+}
+function writeSwitch(lines, sw, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :Switch ;`);
+    lines.push(`${indent}:discriminator "${sw.discriminator}" ;`);
+    for (const [i, sc] of sw.cases.entries()) {
+        if (i === 0) {
+            lines.push(`${indent}:hasCase [`);
+        }
+        else {
+            lines.push(`${indent}] , [`);
+        }
+        writeSwitchCase(lines, sc, depth + 1);
+    }
+    lines.push(`${indent}]`);
+}
+function writeSwitchCase(lines, sc, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}a :SwitchCase ;`);
+    lines.push(`${indent}:caseNode [`);
+    writeNode(lines, sc.node, depth + 1);
+    lines.push(`${indent}]`);
+}
+function writeRelation(lines, edge, depth) {
+    const indent = INDENT.repeat(depth);
+    lines.push(`${indent}:hasRelation [`);
+    const inner = INDENT.repeat(depth + 1);
+    lines.push(`${inner}a :Relation ;`);
+    if (edge.relation.slotName) {
+        lines.push(`${inner}:cardinality "${edge.relation.cardinality}" ;`);
+        lines.push(`${inner}:slotName "${edge.relation.slotName}"`);
+    }
+    else {
+        lines.push(`${inner}:cardinality "${edge.relation.cardinality}"`);
+    }
+    lines.push(`${indent}]`);
+}
+function isSwitch(target) {
+    return "discriminator" in target;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,3 @@
+export { parseAnatomyYAML } from "./parse.js";
+export { anatomyToTTL } from "./transform.js";
+export type { AnonymousNode, Edge, NamedNode, Node, Relation, Specification, Style, Switch, SwitchCase, } from "./types.js";

package/dist/types/parse.d.ts

@@ -0,0 +1,2 @@
+import type { Specification } from "./types.js";
+export declare function parseAnatomyYAML(raw: unknown): Specification;

package/dist/types/transform.d.ts

@@ -0,0 +1,2 @@
+import type { Specification } from "./types.js";
+export declare function anatomyToTTL(spec: Specification): string;

package/dist/types/types.d.ts

@@ -0,0 +1,36 @@
+export interface Specification {
+    root: NamedNode;
+}
+export interface NamedNode {
+    type: "named";
+    uri: string;
+    styles?: Style[];
+    edges?: Edge[];
+}
+export interface AnonymousNode {
+    type: "anonymous";
+    role: string;
+    styles?: Style[];
+    edges?: Edge[];
+}
+export type Node = NamedNode | AnonymousNode;
+export interface Edge {
+    target: Node | Switch;
+    relation: Relation;
+}
+export interface Relation {
+    cardinality: string;
+    slotName?: string;
+}
+export interface Style {
+    key: string;
+    value: string;
+}
+export interface Switch {
+    discriminator: "props" | "internal" | "override";
+    cases: SwitchCase[];
+}
+export interface SwitchCase {
+    value: string;
+    node: Node;
+}

package/dist/types.d.ts

@@ -0,0 +1,36 @@
+export interface Specification {
+    root: NamedNode;
+}
+export interface NamedNode {
+    type: "named";
+    uri: string;
+    styles?: Style[];
+    edges?: Edge[];
+}
+export interface AnonymousNode {
+    type: "anonymous";
+    role: string;
+    styles?: Style[];
+    edges?: Edge[];
+}
+export type Node = NamedNode | AnonymousNode;
+export interface Edge {
+    target: Node | Switch;
+    relation: Relation;
+}
+export interface Relation {
+    cardinality: string;
+    slotName?: string;
+}
+export interface Style {
+    key: string;
+    value: string;
+}
+export interface Switch {
+    discriminator: "props" | "internal" | "override";
+    cases: SwitchCase[];
+}
+export interface SwitchCase {
+    value: string;
+    node: Node;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@canonical/anatomy-dsl",
+  "description": "Anatomy DSL meta-model: TypeScript types mirroring the OWL ontology, and a YAML-to-Turtle transform",
+  "version": "0.2.0",
+  "type": "module",
+  "module": "dist/esm/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "LGPL-3.0",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "biome check && tsc --noEmit",
+    "check:fix": "biome check --write",
+    "check:ts": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@canonical/biome-config": "^0.17.1",
+    "@canonical/typescript-config": "^0.17.1",
+    "expect-type": "^1.3.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "yaml": "^2.7.1"
+  }
+}