@synergy-design-system/metadata 1.0.0 → 3.0.1

package/dist/public/types.d.ts

@@ -0,0 +1,374 @@
+/**
+ * Public API types for querying metadata artifacts.
+ * These types intentionally avoid coupling to internal collector/pipeline modules.
+ */
+import type { ComponentRules } from '../config/types.js';
+/** Logical metadata layer names used for query and response shaping. */
+export type LayerName = 'full' | 'interface' | 'examples';
+/** Verbosity levels for response formatting in public query helpers. */
+export type Verbosity = 'readable' | 'compact' | 'minified';
+/** Named documentation item with free-text description. */
+export type ComponentNamedDescription = {
+    description: string;
+    name: string;
+};
+/** Component interface attribute metadata extracted from docs/source. */
+export type ComponentInterfaceAttribute = {
+    default?: string;
+    description: string;
+    fieldName?: string;
+    name: string;
+    reflects: boolean;
+    type?: string;
+};
+/** Component interface property metadata extracted from docs/source. */
+export type ComponentInterfaceProperty = {
+    access: 'public' | 'readonly';
+    default?: string;
+    description: string;
+    name: string;
+    type?: string;
+};
+/** Component method metadata extracted from docs/source. */
+export type ComponentInterfaceMethod = {
+    description: string;
+    name: string;
+    parameters: Array<{
+        name: string;
+        type?: string;
+    }>;
+    returnType?: string;
+};
+/** Component custom event metadata extracted from docs/source. */
+export type ComponentInterfaceEvent = {
+    description: string;
+    name: string;
+    type?: string;
+};
+/** Normalized interface snapshot for one web component. */
+export type ComponentInterfaceSnapshot = {
+    attributes: ComponentInterfaceAttribute[];
+    cssParts: ComponentNamedDescription[];
+    dependencies: string[];
+    documentation?: string;
+    events: ComponentInterfaceEvent[];
+    methods: ComponentInterfaceMethod[];
+    properties: ComponentInterfaceProperty[];
+    since: string;
+    slots: ComponentNamedDescription[];
+    sourceModulePath: string;
+    status: string;
+    summary: string;
+    tagName: string;
+};
+/** Angular-specific component integration metadata. */
+export type ComponentAngularCustom = {
+    componentName: string;
+    exportPath: string;
+    packageName: string;
+    selector: string;
+    sourcePath: string;
+};
+/** React wrapper component integration metadata. */
+export type ComponentReactWrapperCustom = {
+    componentName: string;
+    exportPath: string;
+    packageName: string;
+    sourcePath: string;
+};
+/** React JSX type integration metadata. */
+export type ComponentReactJsxCustom = {
+    componentName: string;
+    documentation?: string;
+    events?: Array<{
+        name: string;
+        type: string;
+    }>;
+    packageName: string;
+    since: string;
+    sourcePath: string;
+    status: string;
+    subpathExport: string;
+    typeName: string;
+};
+/** Vue-specific component integration metadata. */
+export type ComponentVueCustom = {
+    componentName: string;
+    exportPath: string;
+    packageName: string;
+    sourcePath: string;
+};
+/** Component-specific custom metadata payload. */
+export type ComponentCustom = {
+    clusters?: string[];
+    frameworks?: {
+        angular?: ComponentAngularCustom;
+        react?: {
+            jsx?: ComponentReactJsxCustom;
+            wrapper?: ComponentReactWrapperCustom;
+        };
+        vue?: ComponentVueCustom;
+    };
+    interfaceSnapshot?: ComponentInterfaceSnapshot;
+    override?: {
+        stories?: Array<{
+            description?: {
+                type: string;
+                value: string;
+            };
+            name: string;
+            title?: {
+                type: string;
+                value: string;
+            };
+        }>;
+        storySourcePath?: string;
+        storyTags?: string[];
+    };
+    rules?: ComponentRules;
+};
+/** Font artifact metadata. */
+export type FontCustom = {
+    artifactPath?: string;
+    artifactType?: string;
+};
+/** Style entity custom metadata. */
+export type StyleCustom = {
+    moduleName?: string;
+};
+/** Token entity custom metadata. */
+export type TokenCustom = {
+    artifactPath?: string;
+    format?: 'css' | 'javascript' | 'sass' | 'figma';
+    sourceType?: string;
+    theme?: 'sick2025-light' | 'sick2025-dark' | 'sick2018-light' | 'sick2018-dark';
+};
+/** Migration entity custom metadata. */
+export type MigrationCustom = {
+    migrationType?: string;
+    versions?: string[];
+};
+/** Setup entity custom metadata. */
+export type SetupCustom = {
+    artifactGroups?: Record<string, string[]>;
+    exports?: string[];
+    framework?: 'angular' | 'react' | 'vue';
+    migrationType?: string;
+    moduleClass?: string;
+    packageName?: string;
+    packageVersion?: string;
+    subpathExports?: string[];
+    validators?: string[];
+    valueAccessors?: string[];
+    versions?: string[];
+};
+/** Metadata for one icon inside an icon-set asset. */
+export type AssetIconData = {
+    categories?: string[];
+    tags?: string[];
+};
+/** Icon-set asset custom metadata. */
+export type AssetIconSetCustom = {
+    exportName: string;
+    iconCount: number;
+    icons: Record<string, AssetIconData>;
+    theme: string;
+    variant: string;
+};
+/** Logo asset custom metadata. */
+export type AssetLogoCustom = {
+    category: string;
+    files: string[];
+    theme: string;
+};
+/** System-icon asset custom metadata. */
+export type AssetSystemIconCustom = {
+    files: string[];
+    theme: string;
+};
+/**
+ * Common, ergonomic custom shape for mixed asset entity results.
+ * Asset APIs can return icon sets, logos, system icons, and setup-like records.
+ * Optional fields allow consumers to access shared values (e.g. theme/iconCount)
+ * without narrow/cast gymnastics while still exposing richer fields when present.
+ */
+export type AssetCustom = {
+    category?: string;
+    exportName?: string;
+    files?: string[];
+    iconCount?: number;
+    icons?: Record<string, AssetIconData>;
+    theme?: string;
+    variant?: string;
+};
+/** Common request options shared by public domain query helpers. */
+export type PublicRequestOptions = {
+    includeLayerRefs?: boolean;
+    includeSources?: boolean;
+    layer?: LayerName;
+    limit?: number;
+    offset?: number;
+    strictLayer?: boolean;
+    verbosity?: Verbosity;
+};
+/** Standardized public error code set for metadata APIs. */
+export type PublicErrorCode = 'DATA_NOT_READY' | 'INTERNAL_ERROR' | 'INVALID_LAYER' | 'INVALID_QUERY' | 'INVALID_VERBOSITY' | 'LAYER_NOT_AVAILABLE' | 'NOT_FOUND';
+/** Public error payload returned by metadata APIs. */
+export type PublicError = {
+    code: PublicErrorCode;
+    details?: Record<string, unknown>;
+    message: string;
+};
+/** Shared response metadata envelope returned by metadata APIs. */
+export type PublicResponseMeta = {
+    builtAt: string;
+    requestedLayer: LayerName;
+    requestedVerbosity: Verbosity;
+    resolvedLayer: LayerName;
+    schemaVersion: string;
+    total: number;
+    warnings?: string[];
+};
+/** Generic public response wrapper used by metadata APIs. */
+export type PublicResponse<T> = {
+    data: T;
+    errors?: PublicError[];
+    meta: PublicResponseMeta;
+};
+/** Relation reference from one entity to another. */
+export type MetadataRelationRef = {
+    id: string;
+    kind: string;
+};
+/** Reference to one generated layer file. */
+export type MetadataLayerRef = {
+    layer: string;
+    path: string;
+};
+/** Canonical metadata entity shape used across public APIs. */
+export type MetadataEntity<TCustom = Record<string, unknown>> = {
+    custom?: TCustom;
+    id: string;
+    kind: string;
+    layers?: Record<string, MetadataLayerRef[]>;
+    name: string;
+    package: string;
+    relations: MetadataRelationRef[];
+    since: string;
+    sources: string[];
+    status: string;
+    tags: string[];
+};
+/** Entity alias for icon-set assets. */
+export type AssetIconSetEntity = MetadataEntity<AssetIconSetCustom>;
+/** Entity alias for logo assets. */
+export type AssetLogoEntity = MetadataEntity<AssetLogoCustom>;
+/** Entity alias for system-icon assets. */
+export type AssetSystemIconEntity = MetadataEntity<AssetSystemIconCustom>;
+/** Entity alias for mixed asset payloads. */
+export type AssetEntity = MetadataEntity<AssetCustom>;
+/** Entity alias for component payloads. */
+export type ComponentEntity = MetadataEntity<ComponentCustom>;
+/** Aggregated component cluster entry returned by cluster APIs. */
+export type ComponentCluster = {
+    category?: string;
+    componentCount: number;
+    componentIds: string[];
+    description?: string;
+    id: string;
+    name: string;
+};
+/** Entity alias for font payloads. */
+export type FontEntity = MetadataEntity<FontCustom>;
+/** Entity alias for migration payloads. */
+export type MigrationEntity = MetadataEntity<MigrationCustom>;
+/** Entity alias for setup payloads. */
+export type SetupEntity = MetadataEntity<SetupCustom>;
+/** Entity alias for style payloads. */
+export type StyleEntity = MetadataEntity<StyleCustom>;
+/** Entity alias for token payloads. */
+export type TokenEntity = MetadataEntity<TokenCustom>;
+/** One index entry describing how to locate and search an entity. */
+export type MetadataIndexEntry = {
+    corePath: string;
+    id: string;
+    kind: string;
+    layers?: Record<string, number>;
+    name: string;
+    search: string[];
+};
+/** Root metadata index structure stored in data/index.json. */
+export type MetadataIndex = {
+    entities: MetadataIndexEntry[];
+    builtAt: string;
+    version: string;
+};
+/** Filter options for low-level metadata store queries. */
+export type MetadataQuery = {
+    id?: string;
+    kind?: string;
+    layer?: LayerName;
+    package?: string;
+    status?: string;
+    tags?: string[];
+};
+/** Runtime options for constructing a metadata store. */
+export type MetadataStoreOptions = {
+    dataDir?: string;
+};
+/** Matching mode used by icon search filter groups. */
+export type IconFilterMode = 'and' | 'or';
+/** Query object for searching icons across one or more icon-set assets. */
+export type IconSearchQuery = {
+    /**
+     * Scope to one or more asset entities by ID, e.g. `'asset:sick2018-icons'` or
+     * `['sick2025-icons-fill', 'sick2025-icons-outline']`. Searches all icon sets when omitted.
+     */
+    assetId?: string | string[];
+    /**
+     * Filter by category. Accepts a single string or an array of strings.
+     * Each value is a case-insensitive partial match against any of the icon's categories.
+     * When multiple values are provided, `filterMode` controls whether the icon must match
+     * all categories (and) or at least one (or). Defaults to `'or'`.
+     */
+    category?: string | string[];
+    /**
+     * Controls how multiple `category` values and the combination of `category` + `tags` are
+     * evaluated. `'or'` (default): icon matches if any filter field matches.
+     * `'and'`: icon must match all provided filter fields.
+     */
+    filterMode?: IconFilterMode;
+    /** Case-insensitive partial match on icon name. */
+    name?: string;
+    /** Filter by tag. At least one tag value must match (case-insensitive partial match). */
+    tags?: string[];
+};
+/** One icon search hit with icon-set and categorization context. */
+export type IconSearchResult = {
+    assetId: string;
+    iconName: string;
+    categories: string[];
+    tags: string[];
+    theme?: string;
+    variant?: string;
+};
+/** Public low-level metadata store interface for entity and layer access. */
+export interface MetadataStore {
+    /** Find entities by query filters. */
+    findEntities: (query?: MetadataQuery) => Promise<MetadataEntity[]>;
+    /** List entity IDs and layer file refs for all entities in a package and layer. */
+    getDataForLayer: (packageName: string, layer: LayerName) => Promise<Array<{
+        entityId: string;
+        files: MetadataLayerRef[];
+    }>>;
+    /** Get one entity by exact ID. Returns `null` when not found. */
+    getEntity: (id: string) => Promise<MetadataEntity | null>;
+    /** Get metadata index data (`data/index.json`). */
+    getIndex: () => Promise<MetadataIndex>;
+    /** Return only layer file references for one entity and layer. */
+    getLayerFiles: (entityId: string, layer: LayerName) => Promise<MetadataLayerRef[]>;
+    /** Get all entities belonging to a package. */
+    getPackageEntities: (packageName: string) => Promise<MetadataEntity[]>;
+    /** Read UTF-8 content for one layer file reference. */
+    readLayerFile: (ref: MetadataLayerRef) => Promise<string>;
+}

package/dist/public/types.js

@@ -0,0 +1,5 @@
+/**
+ * Public API types for querying metadata artifacts.
+ * These types intentionally avoid coupling to internal collector/pipeline modules.
+ */
+export {};

package/dist/public/utils.d.ts

@@ -0,0 +1,48 @@
+import type { LayerName, MetadataEntity, MetadataLayerRef, MetadataStore, PublicRequestOptions } from './types.js';
+/** Resolved content for one referenced metadata layer file. */
+export type LayerFileContent = {
+    content: string;
+    ref: MetadataLayerRef;
+};
+/** Matching configuration for user-input-to-entity lookup helpers. */
+export type EntityLookupOptions<T> = {
+    extraCandidates?: Array<string | undefined> | ((entity: MetadataEntity<T>) => Array<string | undefined>);
+    prefix: string;
+    prefixedCandidates?: (input: string) => string[];
+};
+/**
+ * Normalize user-provided lookup values to the canonical comparison format.
+ */
+export declare const normalizeLookupValue: (value: string) => string;
+/**
+ * Match a user-provided name/id against a metadata entity using a shared normalization strategy.
+ */
+export declare const matchesEntityNameOrId: <T>(entity: MetadataEntity<T>, nameOrId: string, options: EntityLookupOptions<T>) => boolean;
+/**
+ * Return a new array sorted by `entity.id` in ascending order.
+ */
+export declare const sortByEntityId: <T>(entities: MetadataEntity<T>[]) => MetadataEntity<T>[];
+/**
+ * Return a paginated slice with safe `offset`/`limit` handling.
+ */
+export declare const paginate: <T>(items: T[], limit?: number, offset?: number) => T[];
+/**
+ * Collect layer file references from one or more entities.
+ * When `layer` is provided, only references from that layer are returned.
+ */
+export declare const collectLayerReferences: <T>(entities: MetadataEntity<T>[], layer?: LayerName) => MetadataLayerRef[];
+/**
+ * Read content for all layer files referenced by a single entity.
+ * This is a convenience helper built on top of `store.readLayerFile`.
+ */
+export declare const readLayerFilesForEntity: <T>(store: MetadataStore, entity: MetadataEntity<T>, layer?: LayerName) => Promise<LayerFileContent[]>;
+/**
+ * Check whether an entity has at least one reference for the requested layer.
+ */
+export declare const layerExistsForEntity: <T>(entity: MetadataEntity<T>, layer: LayerName) => boolean;
+/**
+ * Apply response visibility options to an entity.
+ * - `includeLayerRefs=false` removes `layers` from the result
+ * - `includeSources=true` includes source references, otherwise returns an empty `sources` array
+ */
+export declare const mapEntityForResponse: <T>(entity: MetadataEntity<T>, options: PublicRequestOptions) => MetadataEntity<T>;

package/dist/public/utils.js

@@ -0,0 +1,98 @@
+/**
+ * Normalize user-provided lookup values to the canonical comparison format.
+ */
+export const normalizeLookupValue = (value) => value.trim().toLowerCase();
+/**
+ * Match a user-provided name/id against a metadata entity using a shared normalization strategy.
+ */
+export const matchesEntityNameOrId = (entity, nameOrId, options) => {
+    const input = normalizeLookupValue(nameOrId);
+    const entityId = normalizeLookupValue(entity.id);
+    const shortId = entityId.startsWith(`${options.prefix}:`) ? entityId.slice(options.prefix.length + 1) : entityId;
+    const entityName = normalizeLookupValue(entity.name);
+    const extraCandidates = typeof options.extraCandidates === 'function'
+        ? options.extraCandidates(entity)
+        : (options.extraCandidates ?? []);
+    const normalizedCandidates = [
+        entityId,
+        shortId,
+        entityName,
+        ...extraCandidates
+            .filter((candidate) => typeof candidate === 'string' && candidate.length > 0)
+            .map(normalizeLookupValue),
+    ];
+    if (normalizedCandidates.includes(input)) {
+        return true;
+    }
+    if (!input.includes(':') && `${options.prefix}:${input}` === entityId) {
+        return true;
+    }
+    return options.prefixedCandidates?.(input).includes(entityId) ?? false;
+};
+/**
+ * Return a new array sorted by `entity.id` in ascending order.
+ */
+export const sortByEntityId = (entities) => entities.toSorted((a, b) => a.id.localeCompare(b.id));
+/**
+ * Return a paginated slice with safe `offset`/`limit` handling.
+ */
+export const paginate = (items, limit, offset) => {
+    const safeOffset = Math.max(0, offset ?? 0);
+    const safeLimit = limit !== undefined ? Math.max(0, limit) : undefined;
+    const sliced = items.slice(safeOffset);
+    if (safeLimit === undefined) {
+        return sliced;
+    }
+    return sliced.slice(0, safeLimit);
+};
+/**
+ * Collect layer file references from one or more entities.
+ * When `layer` is provided, only references from that layer are returned.
+ */
+export const collectLayerReferences = (entities, layer) => {
+    const unique = new Map();
+    entities.forEach((entity) => {
+        const layers = entity.layers ?? {};
+        if (layer) {
+            (layers[layer] ?? []).forEach((ref) => {
+                unique.set(`${ref.layer}:${ref.path}`, ref);
+            });
+            return;
+        }
+        Object.values(layers).forEach((refs) => {
+            refs.forEach((ref) => {
+                unique.set(`${ref.layer}:${ref.path}`, ref);
+            });
+        });
+    });
+    return [...unique.values()];
+};
+/**
+ * Read content for all layer files referenced by a single entity.
+ * This is a convenience helper built on top of `store.readLayerFile`.
+ */
+export const readLayerFilesForEntity = async (store, entity, layer) => {
+    const refs = collectLayerReferences([entity], layer);
+    return Promise.all(refs.map(async (ref) => ({
+        content: await store.readLayerFile(ref),
+        ref,
+    })));
+};
+/**
+ * Check whether an entity has at least one reference for the requested layer.
+ */
+export const layerExistsForEntity = (entity, layer) => !!entity.layers?.[layer] && entity.layers[layer].length > 0;
+/**
+ * Apply response visibility options to an entity.
+ * - `includeLayerRefs=false` removes `layers` from the result
+ * - `includeSources=true` includes source references, otherwise returns an empty `sources` array
+ */
+export const mapEntityForResponse = (entity, options) => {
+    const includeSources = options.includeSources ?? false;
+    const includeLayerRefs = options.includeLayerRefs ?? true;
+    return {
+        ...entity,
+        layers: includeLayerRefs ? entity.layers : undefined,
+        sources: includeSources ? entity.sources : [],
+    };
+};

package/package.json

@@ -4,16 +4,46 @@
     "url": "https://www.sick.com"
   },
   "description": "Metadata for the Synergy Design System, usable by MCP Servers or other AI tools",
-  "devDependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.12.2",
+    "@types/serve-handler": "^6.1.4",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "chai": "^6.2.2",
+    "custom-elements-manifest": "^2.1.0",
+    "eslint": "^9.39.4",
+    "execa": "^9.6.1",
+    "playwright": "^1.59.1",
+    "prettier": "^3.8.3",
+    "rimraf": "^6.1.3",
+    "serve-handler": "^6.1.7",
+    "typescript": "^5.9.3",
+    "zod": "^4.3.6",
+    "@synergy-design-system/docs": "0.1.0",
+    "@synergy-design-system/eslint-config-syn": "^0.1.0",
+    "@synergy-design-system/components": "3.12.1",
+    "@synergy-design-system/fonts": "1.0.6",
+    "@synergy-design-system/styles": "2.0.4",
+    "@synergy-design-system/tokens": "^3.12.1"
+  },
   "exports": {
     ".": {
-      "default": "./src/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./public": {
+      "types": "./dist/public/index.d.ts",
+      "default": "./dist/public/index.js"
     },
     "./package.json": "./package.json"
   },
   "files": [
-    "src/**/*.js",
-    "README.md"
+    "data/**",
+    "dist/index.d.ts",
+    "dist/index.js",
+    "dist/public/**",
+    "README.md",
+    "CHANGELOG.md"
   ],
   "homepage": "https://github.com/synergy-design-system/synergy-design-system/tree/main/packages/metadata",
   "keywords": [
@@ -26,14 +56,26 @@
     "Synergy Metadata"
   ],
   "license": "MIT",
-  "main": "./src/index.js",
+  "main": "./dist/index.js",
   "name": "@synergy-design-system/metadata",
   "repository": {
     "type": "git",
     "url": "https://github.com/synergy-design-system/synergy-design-system.git",
     "directory": "packages/metadata"
   },
+  "types": "./dist/index.d.ts",
   "type": "module",
-  "version": "1.0.0",
-  "scripts": {}
+  "version": "3.0.1",
+  "scripts": {
+    "build:all": "METADATA_LOG_LEVEL=info pnpm run build:ts && RUN_STORYBOOK_SCRAPER=true pnpm run build:data",
+    "build": "METADATA_LOG_LEVEL=info pnpm run build:ts && pnpm run build:data",
+    "build:data": "node dist/internal/cli/build.js",
+    "build:ts": "tsc && tsc -p tsconfig.rules.json",
+    "clean": "rimraf dist && ( [ -d data ] && find data -type f ! -name '.gitkeep' -delete && find data -type d -empty -delete || true )",
+    "lint:js": "eslint src config",
+    "lint:schemas": "node src/internal/cli/schema-lint.js",
+    "lint": "pnpm run /^lint:.*/",
+    "pretest": "pnpm run build:ts",
+    "test": "node --test --test-timeout=15000 test/**/*.test.mjs"
+  }
 }

package/LICENSE

@@ -1,9 +0,0 @@
-The MIT License
-
-Copyright 2023 SICK AG
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/src/index.js

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