@mat3ra/esse 2026.8.18-2 → 2026.8.25-0

package/dist/js/scripts/buildEntityGraph.js

@@ -0,0 +1,420 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ISOLATED_NODE_BASELINE = void 0;
+exports.schemaIdToPublishedPath = schemaIdToPublishedPath;
+exports.publishedPathToSchemaId = publishedPathToSchemaId;
+exports.buildPublishedPathIndex = buildPublishedPathIndex;
+exports.sourcePathToSchemaId = sourcePathToSchemaId;
+exports.classifyLayer = classifyLayer;
+exports.resolveJsonPointer = resolveJsonPointer;
+exports.collectReferences = collectReferences;
+exports.buildEntityGraph = buildEntityGraph;
+exports.validateEntityGraph = validateEntityGraph;
+exports.writeEntityGraph = writeEntityGraph;
+/**
+ * Extracts the schema reference graph from the ESSE sources.
+ *
+ * The graph records how schemas relate to one another: which schemas extend which
+ * (`allOf`), which contain which (`properties`/`items`), and which are variants of a
+ * union (`oneOf`/`anyOf`). It is emitted as a single `graph.json` asset for the site,
+ * and doubles as a lint over the schema corpus.
+ *
+ * IMPORTANT: this reads the *source* schemas, never the resolved ones under `dist`.
+ * Resolution inlines `$ref`s and merges `allOf`, which destroys exactly the structure
+ * recorded here.
+ */
+const fs_1 = __importDefault(require("fs"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const path_1 = __importDefault(require("path"));
+const settings_1 = require("../esse/settings");
+const ajv_1 = require("../utils/ajv");
+const filesystem_1 = require("../utils/filesystem");
+const entity_graph_schema_json_1 = __importDefault(require("./entity_graph.schema.json"));
+const entityGraphLayout_1 = require("./entityGraphLayout");
+/**
+ * Isolated schemas at the time the lint baseline was taken; growth is reported, not failed.
+ * These are leaf definitions and externally-consumed formats that nothing else references.
+ */
+exports.ISOLATED_NODE_BASELINE = 34;
+const REPOSITORY_ROOT = path_1.default.resolve(__dirname, "../../../");
+const ENTITY_DOMAINS = [
+    "material",
+    "model",
+    "method",
+    "property",
+    "workflow",
+    "job",
+    "software",
+    "compute",
+];
+/**
+ * Maps a schema `$id` to the path of its resolved copy on the published site.
+ *
+ * Exactly invertible by {@link publishedPathToSchemaId}: an `$id` is a path with underscores
+ * replaced by dashes, so no `$id` ever contains an underscore and the mapping is injective.
+ *
+ * What is *not* recoverable is the **source** path, because a source directory may contain a
+ * literal dash (`properties_directory/non-scalar`) that the round-trip through `$id` turns into
+ * an underscore. Read `node.path` for that.
+ */
+function schemaIdToPublishedPath(schemaId) {
+    return `schema/${schemaId.replace(/-/g, "_")}.json`;
+}
+/** Recovers a schema `$id` from the path of its published copy. */
+function publishedPathToSchemaId(publishedPath) {
+    return publishedPath
+        .replace(/^schema\//, "")
+        .replace(/\.json$/, "")
+        .replace(/_/g, "-");
+}
+/** Builds the published-path to `$id` lookup, for callers that prefer a map to a function. */
+function buildPublishedPathIndex(nodes) {
+    return Object.fromEntries(nodes.map((node) => [node.publishedPath, node.id]));
+}
+/** Derives the `$id` a schema at this source path must declare, per `setSchemaIds`. */
+function sourcePathToSchemaId(sourcePath) {
+    return path_1.default
+        .relative(settings_1.SCHEMAS_DIR, sourcePath)
+        .replace(/\.json$/, "")
+        .replace(/_/g, "-");
+}
+function schemaIdSegments(schemaId) {
+    // Work from the underscored form so that "non-scalar" and "non_scalar" agree.
+    return schemaId.replace(/-/g, "_").split("/");
+}
+/**
+ * Assigns a layer to every schema. The classification is total by contract: an
+ * unclassifiable path is a lint failure, so a newly added top-level directory forces a
+ * deliberate decision here instead of silently landing in a catch-all bucket.
+ */
+function classifyLayer(schemaId) {
+    const segments = schemaIdSegments(schemaId);
+    const [first, second] = segments;
+    if (first === "core") {
+        if (second === "primitive")
+            return { layer: "primitive" };
+        if (second === "abstract")
+            return { layer: "abstract" };
+        if (second === "reusable")
+            return { layer: "reusable" };
+        if (second === "reference")
+            return { layer: "reference" };
+        return undefined;
+    }
+    if (first === "definitions")
+        return { layer: "definition" };
+    if (first === "in_memory_entity")
+        return { layer: "in-memory-entity" };
+    if (first === "system")
+        return { layer: "system" };
+    if (segments.length === 1)
+        return { layer: "entity" };
+    if (ENTITY_DOMAINS.includes(first))
+        return { layer: "entity-component", ownerEntity: first };
+    if (first.endsWith("_category") || first === "materials_category_components") {
+        return { layer: "category" };
+    }
+    if (first.endsWith("_directory"))
+        return { layer: "directory" };
+    if (first === "apse")
+        return { layer: "application-parsing" };
+    return undefined;
+}
+/** Resolves a JSON pointer within a document, returning undefined when it does not exist. */
+function resolveJsonPointer(document, pointer) {
+    if (pointer === "" || pointer === "/")
+        return document;
+    const tokens = pointer
+        .replace(/^\//, "")
+        .split("/")
+        .map((token) => token.replace(/~1/g, "/").replace(/~0/g, "~"));
+    return tokens.reduce((current, token) => {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        const container = current;
+        return token in container ? container[token] : undefined;
+    }, document);
+}
+/**
+ * Collects every `$ref` in a schema together with the relationship it expresses.
+ *
+ * The relationship comes from the innermost enclosing structural keyword: a `$ref` inside
+ * `properties.foo.allOf[0]` extends, while one inside `allOf[0].properties.foo` is contained.
+ * The enclosing property name travels with the reference regardless of kind, so a union
+ * under `properties.data.oneOf` is recorded as a variant *of `data`*.
+ */
+function collectReferences(schema) {
+    const references = [];
+    const walk = (value, context) => {
+        if (Array.isArray(value)) {
+            value.forEach((item) => walk(item, context));
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        const node = value;
+        if (typeof node.$ref === "string") {
+            references.push({ ref: node.$ref, kind: context.kind, label: context.label });
+        }
+        Object.entries(node).forEach(([key, child]) => {
+            if (key === "$ref")
+                return;
+            if (key === "allOf") {
+                walk(child, { kind: "extends", label: context.label });
+            }
+            else if (key === "anyOf" || key === "oneOf") {
+                walk(child, { kind: "variant", label: context.label });
+            }
+            else if (key === "properties" && child !== null && typeof child === "object") {
+                Object.entries(child).forEach(([propertyName, propertySchema]) => {
+                    walk(propertySchema, { kind: "contains", label: propertyName });
+                });
+            }
+            else if (key === "items") {
+                walk(child, {
+                    kind: "contains",
+                    label: context.label ? `${context.label}[]` : "[]",
+                });
+            }
+            else {
+                walk(child, context);
+            }
+        });
+    };
+    // No structural keyword yet, so no relationship yet. Every `$ref` in the corpus today
+    // passes through one before it is reached; a future one that does not gets `kind`
+    // undefined and fails L4, which is the point — the classification stays deliberate
+    // rather than defaulting to `contains` and quietly mislabelling the edge.
+    walk(schema, {});
+    return references;
+}
+function loadSchemas() {
+    const loaded = [];
+    (0, filesystem_1.walkDirSync)(settings_1.SCHEMAS_DIR, (filePath) => {
+        if (!filePath.endsWith(".json"))
+            return;
+        loaded.push({
+            sourcePath: filePath,
+            relativePath: path_1.default.relative(REPOSITORY_ROOT, filePath),
+            schema: JSON.parse(fs_1.default.readFileSync(filePath, "utf-8")),
+        });
+    });
+    return loaded.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
+}
+function readPropertiesManifest() {
+    var _a;
+    if (!fs_1.default.existsSync(settings_1.PROPERTIES_MANIFEST_PATH))
+        return {};
+    return ((_a = js_yaml_1.default.load(fs_1.default.readFileSync(settings_1.PROPERTIES_MANIFEST_PATH, "utf-8"))) !== null && _a !== void 0 ? _a : {});
+}
+function buildEntityGraph() {
+    const failures = [];
+    const warnings = [];
+    const loadedSchemas = loadSchemas();
+    const schemasBySourcePath = new Map(loadedSchemas.map((item) => [item.sourcePath, item]));
+    const nodes = new Map();
+    const nodeIdBySourcePath = new Map();
+    loadedSchemas.forEach(({ sourcePath, relativePath, schema }) => {
+        var _a, _b;
+        const expectedId = sourcePathToSchemaId(sourcePath);
+        const declaredId = typeof schema.$id === "string" ? schema.$id : undefined;
+        if (declaredId !== expectedId) {
+            failures.push(`L2 ${relativePath}: $id is ${JSON.stringify(declaredId)}, expected ${JSON.stringify(expectedId)} (run "npm run set-schema-ids")`);
+        }
+        const id = declaredId !== null && declaredId !== void 0 ? declaredId : expectedId;
+        const classification = classifyLayer(id);
+        if (!classification) {
+            failures.push(`L3 ${relativePath}: no layer rule matches this path — add one to classifyLayer`);
+        }
+        const relativeToSchemas = path_1.default.relative(settings_1.SCHEMAS_DIR, sourcePath);
+        const domain = relativeToSchemas.includes(path_1.default.sep)
+            ? relativeToSchemas.split(path_1.default.sep)[0]
+            : "(root)";
+        const properties = ((_a = schema.properties) !== null && _a !== void 0 ? _a : {});
+        nodes.set(id, {
+            id,
+            path: relativePath,
+            publishedPath: schemaIdToPublishedPath(id),
+            title: typeof schema.title === "string" ? schema.title : "",
+            description: typeof schema.description === "string" ? schema.description : "",
+            domain,
+            layer: (_b = classification === null || classification === void 0 ? void 0 : classification.layer) !== null && _b !== void 0 ? _b : "entity",
+            ...((classification === null || classification === void 0 ? void 0 : classification.ownerEntity) ? { ownerEntity: classification.ownerEntity } : {}),
+            inDegree: 0,
+            outDegree: 0,
+            propertyCount: Object.keys(properties).length,
+            hasExample: fs_1.default.existsSync(path_1.default.join(settings_1.EXAMPLES_DIR, relativeToSchemas)),
+        });
+        nodeIdBySourcePath.set(sourcePath, id);
+    });
+    const edges = [];
+    let sameDocumentRefCount = 0;
+    loadedSchemas.forEach(({ sourcePath, relativePath, schema }) => {
+        const sourceId = nodeIdBySourcePath.get(sourcePath);
+        collectReferences(schema).forEach(({ ref, kind, label }) => {
+            var _a;
+            const [filePart, pointerPart] = ref.split("#");
+            const pointer = pointerPart ? `/${pointerPart.replace(/^\//, "")}` : undefined;
+            if (!filePart) {
+                // Same-document reference: valid, but not an edge between schemas.
+                sameDocumentRefCount += 1;
+                if (pointer && resolveJsonPointer(schema, pointer) === undefined) {
+                    failures.push(`L5 ${relativePath}: pointer ${pointer} does not exist in itself`);
+                }
+                return;
+            }
+            const targetPath = path_1.default.resolve(path_1.default.dirname(sourcePath), filePart);
+            const targetId = nodeIdBySourcePath.get(targetPath);
+            if (!targetId) {
+                failures.push(`L1 ${relativePath}: $ref "${ref}" does not resolve to a schema`);
+                return;
+            }
+            if (!kind) {
+                failures.push(`L4 ${relativePath}: $ref "${ref}" is not inside allOf, oneOf, anyOf, ` +
+                    `properties or items, so its relationship kind is undecided`);
+                return;
+            }
+            if (pointer) {
+                const targetSchema = (_a = schemasBySourcePath.get(targetPath)) === null || _a === void 0 ? void 0 : _a.schema;
+                if (resolveJsonPointer(targetSchema, pointer) === undefined) {
+                    failures.push(`L5 ${relativePath}: $ref "${ref}" points at ${pointer}, which does not exist in the target`);
+                }
+            }
+            edges.push({
+                source: sourceId,
+                target: targetId,
+                kind,
+                ...(label ? { label } : {}),
+                ...(pointer ? { pointer } : {}),
+            });
+        });
+    });
+    edges.forEach((edge) => {
+        const source = nodes.get(edge.source);
+        const target = nodes.get(edge.target);
+        if (source)
+            source.outDegree += 1;
+        if (target)
+            target.inDegree += 1;
+    });
+    // L7 — reference cycles. The README forbids them; keep it true as schemas are added.
+    const adjacency = new Map();
+    edges.forEach((edge) => {
+        if (!adjacency.has(edge.source))
+            adjacency.set(edge.source, new Set());
+        adjacency.get(edge.source).add(edge.target);
+    });
+    const VISITING = 1;
+    const VISITED = 2;
+    const state = new Map();
+    const trail = [];
+    const visit = (id) => {
+        var _a;
+        state.set(id, VISITING);
+        trail.push(id);
+        [...((_a = adjacency.get(id)) !== null && _a !== void 0 ? _a : [])].sort().forEach((neighbour) => {
+            if (state.get(neighbour) === VISITING) {
+                const cycleStart = trail.indexOf(neighbour);
+                failures.push(`L7 cycle: ${[...trail.slice(cycleStart), neighbour].join(" -> ")}`);
+            }
+            else if (state.get(neighbour) === undefined) {
+                visit(neighbour);
+            }
+        });
+        trail.pop();
+        state.set(id, VISITED);
+    };
+    [...nodes.keys()].sort().forEach((id) => {
+        if (state.get(id) === undefined)
+            visit(id);
+    });
+    // L6 — every manifest entry must point at a schema that exists.
+    const propertiesManifest = readPropertiesManifest();
+    Object.entries(propertiesManifest).forEach(([name, entry]) => {
+        var _a;
+        const schemaId = entry === null || entry === void 0 ? void 0 : entry.schemaId;
+        if (typeof schemaId !== "string")
+            return;
+        const node = nodes.get(schemaId);
+        if (!node) {
+            failures.push(`L6 manifest/properties.yaml: "${name}" references schemaId "${schemaId}", which does not exist`);
+            return;
+        }
+        node.manifest = {
+            name,
+            ...(entry.isResult ? { isResult: true } : {}),
+            ...(entry.isMonitor ? { isMonitor: true } : {}),
+            ...(((_a = entry.defaults) === null || _a === void 0 ? void 0 : _a.units) ? { defaultUnits: String(entry.defaults.units) } : {}),
+        };
+    });
+    const sortedNodes = (0, entityGraphLayout_1.computeEntityGraphLayout)([...nodes.values()].sort((a, b) => a.id.localeCompare(b.id)));
+    const sortedEdges = edges.sort((a, b) => {
+        var _a, _b, _c, _d;
+        return a.source.localeCompare(b.source) ||
+            a.target.localeCompare(b.target) ||
+            a.kind.localeCompare(b.kind) ||
+            ((_a = a.label) !== null && _a !== void 0 ? _a : "").localeCompare((_b = b.label) !== null && _b !== void 0 ? _b : "") ||
+            ((_c = a.pointer) !== null && _c !== void 0 ? _c : "").localeCompare((_d = b.pointer) !== null && _d !== void 0 ? _d : "");
+    });
+    const isolatedNodes = sortedNodes.filter((node) => !node.inDegree && !node.outDegree);
+    if (isolatedNodes.length > exports.ISOLATED_NODE_BASELINE) {
+        warnings.push(`L8 ${isolatedNodes.length} isolated schemas, up from a baseline of ${exports.ISOLATED_NODE_BASELINE}: ` +
+            `${isolatedNodes.map((node) => node.id).join(", ")}`);
+    }
+    const schemasWithExample = sortedNodes.filter((node) => node.hasExample).length;
+    warnings.push(`L9 example coverage: ${schemasWithExample}/${sortedNodes.length} schemas have an example ` +
+        `(${Math.round((schemasWithExample / sortedNodes.length) * 100)}%)`);
+    const edgeCountsByKind = {
+        extends: 0,
+        contains: 0,
+        variant: 0,
+    };
+    sortedEdges.forEach((edge) => {
+        edgeCountsByKind[edge.kind] += 1;
+    });
+    const layerCounts = {};
+    sortedNodes.forEach((node) => {
+        var _a;
+        layerCounts[node.layer] = ((_a = layerCounts[node.layer]) !== null && _a !== void 0 ? _a : 0) + 1;
+    });
+    return {
+        graph: {
+            meta: {
+                nodeCount: sortedNodes.length,
+                edgeCount: sortedEdges.length,
+                edgeCountsByKind,
+                layerCounts: Object.fromEntries(Object.entries(layerCounts).sort()),
+                sameDocumentRefCount,
+                schemasWithExample,
+                isolatedNodeCount: isolatedNodes.length,
+            },
+            nodes: sortedNodes,
+            edges: sortedEdges,
+        },
+        lint: { failures, warnings },
+    };
+}
+/**
+ * L10 — validates the emitted graph against its schema.
+ *
+ * That schema lives here rather than in `schema/`: it describes a build artifact, not an
+ * entity of digital materials science, so it has no business in the corpus this tool
+ * measures. Imported rather than read from disk so it resolves identically whether the
+ * module runs from source or from the transpiled copy in `dist/`.
+ */
+function validateEntityGraph(graph) {
+    const { isValid, errors } = (0, ajv_1.validate)(graph, entity_graph_schema_json_1.default);
+    if (isValid)
+        return [];
+    return (errors !== null && errors !== void 0 ? errors : []).map((error) => { var _a; return `L10 graph.json${error.instancePath} ${(_a = error.message) !== null && _a !== void 0 ? _a : "is invalid"}`; });
+}
+/** Writes `graph.json` into the given directory, creating it when missing. */
+function writeEntityGraph(graph, outputDir) {
+    fs_1.default.mkdirSync(outputDir, { recursive: true });
+    const outputPath = path_1.default.join(outputDir, "graph.json");
+    fs_1.default.writeFileSync(outputPath, `${JSON.stringify(graph, null, 4)}\n`, "utf8");
+    return outputPath;
+}

package/dist/js/scripts/checkSiteLinks.d.ts

@@ -0,0 +1,6 @@
+export interface SiteLinkProblem {
+    page: string;
+    href: string;
+    reason: string;
+}
+export declare function checkSiteLinks(siteDir: string): SiteLinkProblem[];

package/dist/js/scripts/checkSiteLinks.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkSiteLinks = checkSiteLinks;
+/**
+ * Verifies that every internal link in the assembled site resolves.
+ *
+ * The site is stitched together from four sources — resolved schemas, the concept docs, the
+ * explorer and the Entity Map — each of which links into the others. Nothing else checks that
+ * those links land anywhere, and a stale href is invisible until someone clicks it.
+ *
+ * External URLs are not fetched; this is a build step, not a crawler.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const HREF_PATTERN = /(?:href|src)\s*=\s*"([^"]+)"/g;
+function listFiles(directory, extension) {
+    if (!fs_1.default.existsSync(directory))
+        return [];
+    return fs_1.default.readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const entryPath = path_1.default.join(directory, entry.name);
+        if (entry.isDirectory())
+            return listFiles(entryPath, extension);
+        return entry.name.endsWith(extension) ? [entryPath] : [];
+    });
+}
+/** True for anything this build step cannot or should not resolve on disk. */
+function isExternal(href) {
+    return /^[a-z][a-z0-9+.-]*:/i.test(href) || href.startsWith("//") || href.startsWith("data:");
+}
+function checkSiteLinks(siteDir) {
+    const problems = [];
+    const pages = listFiles(siteDir, ".html");
+    if (pages.length === 0) {
+        return [{ page: siteDir, href: "", reason: "no HTML pages found — was the site built?" }];
+    }
+    pages.forEach((page) => {
+        const html = fs_1.default.readFileSync(page, "utf-8");
+        const seen = new Set();
+        Array.from(html.matchAll(HREF_PATTERN)).forEach((match) => {
+            const href = match[1];
+            if (seen.has(href))
+                return;
+            seen.add(href);
+            if (isExternal(href) || href.startsWith("#") || href.trim() === "")
+                return;
+            // Only the path part is checked; in-page fragments and the map's hash routes are
+            // resolved by the browser, not the filesystem.
+            const [pathPart] = href.split("#");
+            if (!pathPart)
+                return;
+            const target = path_1.default.resolve(path_1.default.dirname(page), pathPart);
+            const relativePage = path_1.default.relative(siteDir, page);
+            if (!target.startsWith(path_1.default.resolve(siteDir))) {
+                problems.push({
+                    page: relativePage,
+                    href,
+                    reason: "escapes the site directory",
+                });
+                return;
+            }
+            const resolved = fs_1.default.existsSync(target) && fs_1.default.statSync(target).isDirectory()
+                ? path_1.default.join(target, "index.html")
+                : target;
+            if (!fs_1.default.existsSync(resolved)) {
+                problems.push({ page: relativePage, href, reason: "target does not exist" });
+            }
+        });
+    });
+    return problems;
+}

package/dist/js/scripts/entityGraphLayout.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Computes map coordinates for the entity graph.
+ *
+ * The layout is deliberately *not* a force simulation. A force layout arranges schemas by
+ * how densely they reference one another, which reproduces the directory tree and teaches a
+ * reader nothing they could not get from `ls -R`. This places schemas by architectural
+ * layer instead: the primitives everything is built from sit at the centre, the root
+ * entities form a ring around them, and the category/directory catalogues sit on the rim.
+ * Reading outward from the middle is reading the build-up the concept docs describe.
+ *
+ * Being a pure function of the graph, it is also deterministic: unchanged schemas keep their
+ * coordinates from one release to the next, so the map is worth building spatial memory of.
+ */
+import type { EntityGraphNode } from "./buildEntityGraph";
+/**
+ * Assigns `x`/`y` to every node in place and returns the same array.
+ *
+ * Nodes are grouped into bands by layer, then ordered within a band by domain so that
+ * schemas from the same corner of the corpus land next to one another on the ring.
+ */
+export declare function computeEntityGraphLayout(nodes: EntityGraphNode[]): EntityGraphNode[];

package/dist/js/scripts/entityGraphLayout.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeEntityGraphLayout = computeEntityGraphLayout;
+/** Layers ordered from the centre outward, following the dependency direction. */
+const LAYER_BANDS = [
+    ["definition", "primitive"],
+    ["abstract"],
+    ["reusable", "reference"],
+    ["in-memory-entity", "system"],
+    ["entity"],
+    ["entity-component"],
+    ["category"],
+    ["directory", "application-parsing"],
+];
+/** Minimum arc length between neighbouring nodes on a ring, in graph units. */
+const NODE_SPACING = 62;
+/** Minimum radial distance between consecutive bands. */
+const BAND_GAP = 190;
+/** Radial wobble as a fraction of BAND_GAP, so bands read as belts rather than wireframe circles. */
+const JITTER_FRACTION = 0.16;
+/** Stable hash used for deterministic jitter; identical input always yields identical output. */
+function hashToUnitInterval(value) {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        // eslint-disable-next-line no-bitwise
+        hash = Math.imul(hash ^ value.charCodeAt(index), 16777619);
+    }
+    // eslint-disable-next-line no-bitwise
+    return ((hash >>> 0) % 10000) / 10000;
+}
+/**
+ * Assigns `x`/`y` to every node in place and returns the same array.
+ *
+ * Nodes are grouped into bands by layer, then ordered within a band by domain so that
+ * schemas from the same corner of the corpus land next to one another on the ring.
+ */
+function computeEntityGraphLayout(nodes) {
+    const nodesByLayer = new Map();
+    nodes.forEach((node) => {
+        if (!nodesByLayer.has(node.layer))
+            nodesByLayer.set(node.layer, []);
+        nodesByLayer.get(node.layer).push(node);
+    });
+    let previousRadius = 0;
+    LAYER_BANDS.forEach((layers) => {
+        const band = layers
+            .flatMap((layer) => { var _a; return (_a = nodesByLayer.get(layer)) !== null && _a !== void 0 ? _a : []; })
+            .sort((a, b) => {
+            var _a, _b;
+            return a.domain.localeCompare(b.domain) ||
+                ((_a = a.ownerEntity) !== null && _a !== void 0 ? _a : "").localeCompare((_b = b.ownerEntity) !== null && _b !== void 0 ? _b : "") ||
+                a.id.localeCompare(b.id);
+        });
+        if (band.length === 0)
+            return;
+        // Grow the ring until neighbours are at least NODE_SPACING apart along the arc.
+        const circumferenceRadius = (band.length * NODE_SPACING) / (2 * Math.PI);
+        const radius = Math.max(previousRadius + BAND_GAP, circumferenceRadius);
+        band.forEach((node, index) => {
+            const angle = (2 * Math.PI * index) / band.length;
+            const jitter = (hashToUnitInterval(node.id) - 0.5) * BAND_GAP * JITTER_FRACTION;
+            const effectiveRadius = radius + jitter;
+            node.x = Math.round(Math.cos(angle) * effectiveRadius * 100) / 100;
+            node.y = Math.round(Math.sin(angle) * effectiveRadius * 100) / 100;
+        });
+        previousRadius = radius;
+    });
+    // Any layer not named in LAYER_BANDS would be left without coordinates; the lint's
+    // total-classification rule prevents that, but fail loudly rather than render at 0,0.
+    const unplaced = nodes.filter((node) => node.x === undefined || node.y === undefined);
+    if (unplaced.length > 0) {
+        throw new Error(`Layout missed ${unplaced.length} node(s); add their layer to LAYER_BANDS: ` +
+            `${unplaced.map((node) => node.layer).join(", ")}`);
+    }
+    return nodes;
+}