@mat3ra/esse 2026.8.31-0 → 2026.9.5-0

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

@@ -7,6 +7,17 @@ export interface EntityGraphNodeManifest {
     isMonitor?: boolean;
     defaultUnits?: string;
 }
+/**
+ * Navigation facets derived at build time. Keys are sorted; a value is the slug as the
+ * corpus spells it — the enum a CateCom vocabulary schema narrows, or a path segment for
+ * M-CODE and the catalogues. A narrowing to several values is joined with "|" in enum
+ * order, because such a schema is the branch rather than a point on the ladder.
+ *
+ * Present on every `category` and `directory` node, absent on every other layer.
+ */
+export type EntityGraphFacets = Record<string, string>;
+/** The five coordinate fields of `core/reusable/categories`, in ladder order. */
+export declare const CATECOM_FIELDS: readonly ["tier1", "tier2", "tier3", "type", "subtype"];
 export interface EntityGraphNode {
     /** Schema `$id`, dash-separated, e.g. "in-memory-entity/named-defaultable". */
     id: string;
@@ -31,6 +42,8 @@ export interface EntityGraphNode {
     propertyCount: number;
     hasExample: boolean;
     manifest?: EntityGraphNodeManifest;
+    /** Navigation facets — see EntityGraphFacets. Category and directory nodes only. */
+    facets?: EntityGraphFacets;
     /** Map coordinates, baked at build time so the client renders without laying out. */
     x?: number;
     y?: number;
@@ -110,6 +123,29 @@ interface RawReference {
  * under `properties.data.oneOf` is recorded as a variant *of `data`*.
  */
 export declare function collectReferences(schema: JSONSchema): RawReference[];
+interface LoadedSchema {
+    sourcePath: string;
+    relativePath: string;
+    schema: JSONSchema;
+}
+interface FacetContext {
+    nodes: Map<string, EntityGraphNode>;
+    schemaById: Map<string, LoadedSchema>;
+    schemasBySourcePath: Map<string, LoadedSchema>;
+    /** `extends` targets per source id, sorted, so the upward walk is deterministic. */
+    extendsTargets: Map<string, string[]>;
+    /** Target of the `categories` property edge, per directory node id. */
+    categoriesTarget: Map<string, string>;
+    coordinateMemo: Map<string, EntityGraphFacets>;
+}
+/**
+ * Facets for one node, or undefined when no rule covers it.
+ *
+ * Category nodes carry their scheme's coordinate (CateCom's ladder or M-CODE's axes);
+ * directory nodes carry the catalogue they belong to, that catalogue's own axis, and — when
+ * the entry declares a `categories` property — the coordinate it is filed at.
+ */
+export declare function deriveFacets(node: EntityGraphNode, context: FacetContext): EntityGraphFacets | undefined;
 export interface BuildEntityGraphResult {
     graph: EntityGraph;
     lint: EntityGraphLintResult;

package/dist/js/scripts/buildEntityGraph.js

@@ -3,7 +3,7 @@ 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.ISOLATED_NODE_BASELINE = exports.CATECOM_FIELDS = void 0;
 exports.schemaIdToPublishedPath = schemaIdToPublishedPath;
 exports.publishedPathToSchemaId = publishedPathToSchemaId;
 exports.buildPublishedPathIndex = buildPublishedPathIndex;
@@ -11,6 +11,7 @@ exports.sourcePathToSchemaId = sourcePathToSchemaId;
 exports.classifyLayer = classifyLayer;
 exports.resolveJsonPointer = resolveJsonPointer;
 exports.collectReferences = collectReferences;
+exports.deriveFacets = deriveFacets;
 exports.buildEntityGraph = buildEntityGraph;
 exports.validateEntityGraph = validateEntityGraph;
 exports.writeEntityGraph = writeEntityGraph;
@@ -34,6 +35,8 @@ 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");
+/** The five coordinate fields of `core/reusable/categories`, in ladder order. */
+exports.CATECOM_FIELDS = ["tier1", "tier2", "tier3", "type", "subtype"];
 /**
  * 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.
@@ -210,6 +213,164 @@ function readPropertiesManifest() {
         return {};
     return ((_a = js_yaml_1.default.load(fs_1.default.readFileSync(settings_1.PROPERTIES_MANIFEST_PATH, "utf-8"))) !== null && _a !== void 0 ? _a : {});
 }
+// ── Facets ────────────────────────────────────────────────────────────────────
+const ENUM_HOLDER = /^(enum_options|enum|enums)$/;
+const DIMENSIONALITY = /^(zero|one|two|three)-dimensional$/;
+const OPERATIONS_PREFIX = "materials-category-components/operations/";
+const VALUE_SHAPES = ["scalar", "non-scalar", "structural", "elemental", "workflow"];
+const METHOD_BRANCHES = ["mathematical", "physical"];
+/** Source path segments below `schema/`, so `non-scalar` keeps the dash its `$id` loses. */
+function sourceSegments(node) {
+    return node.path
+        .replace(/^schema\//, "")
+        .replace(/\.json$/, "")
+        .split("/");
+}
+function sortedFacets(facets) {
+    return Object.fromEntries(Object.entries(facets).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * Which of the five CateCom fields this vocabulary schema narrows, each resolved to its enum.
+ *
+ * The enum is the coordinate, not the path segment: `fapprx/basisexp.json` narrows `tier2`
+ * to `basisExp`, and for methods the first segment (`mathematical`, `physical`) is not a tier
+ * at all — so counting path depth gets the ladder wrong.
+ */
+function ownNarrowings(id, context) {
+    var _a;
+    const loaded = context.schemaById.get(id);
+    if (!loaded)
+        return {};
+    const properties = ((_a = loaded.schema.properties) !== null && _a !== void 0 ? _a : {});
+    const narrowed = {};
+    exports.CATECOM_FIELDS.forEach((field) => {
+        var _a;
+        const property = properties[field];
+        if (!property)
+            return;
+        let values = Array.isArray(property.enum) ? property.enum : undefined;
+        if (!values && typeof property.$ref === "string") {
+            const [filePart, pointerPart] = property.$ref.split("#");
+            const target = (_a = context.schemasBySourcePath.get(path_1.default.resolve(path_1.default.dirname(loaded.sourcePath), filePart))) === null || _a === void 0 ? void 0 : _a.schema;
+            const fragment = resolveJsonPointer(target, `/${(pointerPart !== null && pointerPart !== void 0 ? pointerPart : "").replace(/^\//, "")}`);
+            values = fragment === null || fragment === void 0 ? void 0 : fragment.enum;
+        }
+        if (Array.isArray(values) && values.length > 0) {
+            narrowed[field] = values.map(String).join("|");
+        }
+    });
+    return narrowed;
+}
+/** Ancestors' narrowings (walking `extends` within the category layer), then this node's; own wins. */
+function catecomCoordinate(id, context) {
+    var _a;
+    const memoised = context.coordinateMemo.get(id);
+    if (memoised)
+        return memoised;
+    context.coordinateMemo.set(id, {});
+    const coordinate = {};
+    ((_a = context.extendsTargets.get(id)) !== null && _a !== void 0 ? _a : [])
+        .filter((parent) => { var _a; return ((_a = context.nodes.get(parent)) === null || _a === void 0 ? void 0 : _a.layer) === "category"; })
+        .forEach((parent) => Object.assign(coordinate, catecomCoordinate(parent, context)));
+    Object.assign(coordinate, ownNarrowings(id, context));
+    context.coordinateMemo.set(id, coordinate);
+    return coordinate;
+}
+/** Last segment of the first operation reached walking `extends` upward. */
+function mcodeOperation(id, context, seen = new Set()) {
+    var _a;
+    if (seen.has(id))
+        return undefined;
+    seen.add(id);
+    const parents = (_a = context.extendsTargets.get(id)) !== null && _a !== void 0 ? _a : [];
+    const direct = parents.find((parent) => parent.startsWith(OPERATIONS_PREFIX));
+    if (direct)
+        return direct.split("/").pop();
+    return parents.map((parent) => mcodeOperation(parent, context, seen)).find(Boolean);
+}
+/**
+ * Facets for one node, or undefined when no rule covers it.
+ *
+ * Category nodes carry their scheme's coordinate (CateCom's ladder or M-CODE's axes);
+ * directory nodes carry the catalogue they belong to, that catalogue's own axis, and — when
+ * the entry declares a `categories` property — the coordinate it is filed at.
+ */
+function deriveFacets(node, context) {
+    if (node.layer !== "category" && node.layer !== "directory")
+        return undefined;
+    const segments = sourceSegments(node);
+    const [, second, third, fourth] = segments;
+    const holder = ENUM_HOLDER.test(segments[segments.length - 1]);
+    const facets = {};
+    if (node.layer === "category") {
+        if (node.domain === "models_category" || node.domain === "methods_category") {
+            facets.scheme = "catecom";
+            if (node.domain === "methods_category")
+                facets.branch = second;
+            if (holder) {
+                facets.role = "enum-options";
+            }
+            else {
+                facets.role = "vocabulary";
+                Object.assign(facets, catecomCoordinate(node.id, context));
+            }
+        }
+        else if (node.domain === "materials_category") {
+            facets.scheme = "mcode";
+            facets.role = "recipe";
+            facets.structuralClass = second.replace(/_structures$/, "").replace(/_/g, "-");
+            facets.dimensionality = third;
+            const operation = mcodeOperation(node.id, context);
+            if (operation)
+                facets.operation = operation;
+        }
+        else if (node.domain === "materials_category_components" && second === "entities") {
+            facets.scheme = "mcode";
+            facets.role = "entity";
+            facets.entityRole = third;
+            // Dimensionality sits one segment deeper here than under materials_category.
+            facets.dimensionality = fourth;
+        }
+        else if (node.domain === "materials_category_components" && second === "operations") {
+            facets.scheme = "mcode";
+            facets.role = holder ? "enum-options" : "operation";
+            facets.operationKind = fourth;
+        }
+        else {
+            return undefined;
+        }
+        return sortedFacets(facets);
+    }
+    facets.catalogue = node.domain.replace(/_directory$/, "").replace(/_/g, "-");
+    if (holder) {
+        facets.role = "enum-options";
+        return sortedFacets(facets);
+    }
+    if (second === "legacy")
+        facets.legacy = "true";
+    if (node.domain === "properties_directory" && VALUE_SHAPES.includes(second)) {
+        facets.valueShape = second;
+    }
+    if (node.domain === "software_directory")
+        facets.softwareKind = second;
+    if (node.domain === "methods_directory" && METHOD_BRANCHES.includes(second)) {
+        facets.branch = second;
+    }
+    if (node.domain === "context_providers_directory") {
+        facets.scope = second === "by_application" ? "by-application" : "generic";
+        if (second === "by_application")
+            [facets.application] = third.split("_");
+    }
+    const coordinate = context.categoriesTarget.get(node.id);
+    if (coordinate) {
+        const inherited = catecomCoordinate(coordinate, context);
+        exports.CATECOM_FIELDS.forEach((field) => {
+            if (inherited[field])
+                facets[field] = inherited[field];
+        });
+    }
+    return sortedFacets(facets);
+}
 function buildEntityGraph() {
     const failures = [];
     const warnings = [];
@@ -350,6 +511,50 @@ function buildEntityGraph() {
             ...(((_a = entry.defaults) === null || _a === void 0 ? void 0 : _a.units) ? { defaultUnits: String(entry.defaults.units) } : {}),
         };
     });
+    // L11 — facets are total on the category and directory layers, and well formed.
+    // Assigned after the edges exist (the CateCom walk and the `categories` join both need
+    // them) and before layout, so node key order stays deterministic.
+    const extendsTargets = new Map();
+    const categoriesTarget = new Map();
+    edges.forEach((edge) => {
+        var _a, _b;
+        if (edge.kind === "extends") {
+            if (!extendsTargets.has(edge.source))
+                extendsTargets.set(edge.source, []);
+            extendsTargets.get(edge.source).push(edge.target);
+        }
+        if (edge.kind === "contains" && edge.label === "categories") {
+            if (((_a = nodes.get(edge.source)) === null || _a === void 0 ? void 0 : _a.layer) === "directory" &&
+                ((_b = nodes.get(edge.target)) === null || _b === void 0 ? void 0 : _b.layer) === "category") {
+                categoriesTarget.set(edge.source, edge.target);
+            }
+        }
+    });
+    extendsTargets.forEach((targets) => targets.sort());
+    const facetContext = {
+        nodes,
+        schemaById: new Map(loadedSchemas
+            .map((item) => [nodeIdBySourcePath.get(item.sourcePath), item])
+            .filter(([id]) => Boolean(id))),
+        schemasBySourcePath,
+        extendsTargets,
+        categoriesTarget,
+        coordinateMemo: new Map(),
+    };
+    [...nodes.keys()].sort().forEach((id) => {
+        const node = nodes.get(id);
+        if (node.layer !== "category" && node.layer !== "directory")
+            return;
+        const facets = deriveFacets(node, facetContext);
+        if (!facets || Object.keys(facets).length === 0) {
+            failures.push(`L11 ${node.path}: no facet rule covers this ${node.layer} path — add one to deriveFacets`);
+            return;
+        }
+        if (facets.dimensionality && !DIMENSIONALITY.test(facets.dimensionality)) {
+            failures.push(`L11 ${node.path}: dimensionality "${facets.dimensionality}" is not <zero|one|two|three>-dimensional`);
+        }
+        node.facets = facets;
+    });
     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;

package/dist/js/scripts/entity_graph.schema.json

@@ -154,6 +154,13 @@
                         "required": [
                             "name"
                         ]
+                    },
+                    "facets": {
+                        "description": "Navigation facets derived at build time: the CateCom coordinate a vocabulary schema narrows to, the M-CODE axes carried in a materials path, or the catalogue and axis a directory entry belongs to. Present on every category and directory node.",
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
                     }
                 },
                 "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/esse",
-    "version": "2026.8.31-0",
+    "version": "2026.9.5-0",
     "description": "Mat3ra's Excellent Source of Schemas and Examples (ESSE) for Digital Materials R&D",
     "scripts": {
         "transpile": "tsc -p tsconfig-transpile.json",
@@ -8,6 +8,7 @@
         "build-entity-graph": "ts-node build_entity_graph.ts --output ./site",
         "lint-entity-graph": "ts-node build_entity_graph.ts",
         "build-docs-pages": "ts-node build_docs_pages.ts",
+        "build-site": "npm run transpile-and-build-assets && ts-node build_site.ts && npm run check-site-links -- --site site",
         "check-site-links": "ts-node check_site_links.ts",
         "compile-types": "ts-node compile_ts.ts",
         "transpile-and-build-assets": "npm run set-schema-ids && npm run build-schemas && npm run compile-types && npm run transpile",