@nysds/mcp-server 1.19.4 → 1.20.0

package/dist/lib/relationships.js

@@ -0,0 +1,434 @@
+/**
+ * Component Relationships & Integration
+ *
+ * Derives how components connect to each other, to their npm packages, and to
+ * the guides that cover them — all from the Custom Elements Manifest, so it
+ * stays in sync as components are added or renamed.
+ *
+ * Two derivation passes:
+ *
+ * 1. **Family** — components declared under the same `packages/<name>/` source
+ *    directory ship in the same npm package. Containment *within* a family is
+ *    read from the docs rather than the directory name, which is unreliable
+ *    (`packages/nys-checkbox` contains the container `nys-checkboxgroup`):
+ *
+ *    a. A container's slot descriptions name its children — "Default slot for
+ *       `nys-checkbox` elements", "Accepts `<nys-tab>` and `<nys-tabpanel>`".
+ *    b. A child's description names its container — "for use within
+ *       `nys-select`", "a single step within `nys-stepper`".
+ *    c. A component marked "**Slotted component.**" or "**Internal
+ *       component.**" falls back to the only unmarked member of its family.
+ *
+ *    This is how `nys-option` is known to belong inside `nys-select`, and
+ *    `nys-checkbox` inside `nys-checkboxgroup` rather than the reverse.
+ *
+ * 2. **Mentions** — component JSDoc names sibling and alternative components in
+ *    prose (`For 7+ options, use \`nys-select\``). Scanning descriptions, slots,
+ *    and attribute docs recovers those edges in both directions.
+ *
+ * Mentions are filtered against the set of registered tag names, which drops
+ * event names (`nys-change`, `nys-input`), CSS variables, and stale references
+ * to components that no longer exist. A tag that is *also* an event name
+ * (`nys-select` is both a component and an event emitted by `nys-textarea`) is
+ * additionally checked against its surrounding phrasing so an "emits
+ * `nys-select`" sentence does not fabricate a component relationship.
+ */
+import { getAllComponents, getComponent, } from "./cem-parser.js";
+import { getGuidesMentioning } from "./guides.js";
+let cachedFamilies = null;
+let cachedModulePaths = null;
+let cachedTagSet = null;
+let cachedEventNames = null;
+let cachedMentions = null;
+/** Map every component tag to the module path it was declared in. */
+function getModulePaths() {
+    if (cachedModulePaths)
+        return cachedModulePaths;
+    const paths = new Map();
+    for (const component of getAllComponents()) {
+        if (component.modulePath && component.tagName) {
+            paths.set(component.tagName.toLowerCase(), component.modulePath);
+        }
+    }
+    cachedModulePaths = paths;
+    return paths;
+}
+function packageDirFor(tagName) {
+    const path = getModulePaths().get(tagName.toLowerCase());
+    if (!path)
+        return undefined;
+    const [dir] = path.split("/src/");
+    return dir && dir !== path ? dir : undefined;
+}
+function getFamilies() {
+    if (cachedFamilies)
+        return cachedFamilies;
+    // Group tags by their source package directory
+    const byDir = new Map();
+    for (const component of getAllComponents()) {
+        const tag = component.tagName?.toLowerCase();
+        if (!tag)
+            continue;
+        const dir = packageDirFor(tag);
+        if (!dir)
+            continue;
+        const members = byDir.get(dir);
+        if (members) {
+            members.push(tag);
+        }
+        else {
+            byDir.set(dir, [tag]);
+        }
+    }
+    const families = new Map();
+    for (const [dir, memberTags] of byDir) {
+        const dirName = dir.split("/").pop() ?? "";
+        const parentOf = deriveContainment(memberTags);
+        // The container is the member nothing else contains. If the docs leave that
+        // ambiguous, fall back to the component named after its directory.
+        const roots = memberTags.filter((t) => !parentOf.has(t));
+        const primaryTag = roots.length === 1
+            ? roots[0]
+            : (roots.find((t) => t === dirName) ??
+                memberTags.find((t) => t === dirName) ??
+                memberTags[0]);
+        const info = {
+            packageDir: dir,
+            packageName: dirName.startsWith("nys-")
+                ? `@nysds/${dirName}`
+                : "@nysds/components",
+            primaryTag,
+            memberTags: memberTags.sort(),
+            parentOf,
+        };
+        for (const tag of memberTags) {
+            families.set(tag, info);
+        }
+    }
+    cachedFamilies = families;
+    return families;
+}
+/** Phrasing a child uses to name the container it belongs inside. */
+const CONTAINMENT_PHRASE = /\b(?:within|inside|in an?|part of|child of|children of|slotted (?:in|into|inside))\s+(?:an?\s+)?[`'"<]*\s*(nys-[a-z][a-z0-9-]*)/gi;
+/** Markers that identify a component as non-standalone. */
+const SUBCOMPONENT_MARKER = /\*\*(?:slotted|internal|sub)\s+component\.?\*\*/i;
+/**
+ * Work out which family members nest inside which, from the docs alone.
+ */
+function deriveContainment(memberTags) {
+    const parentOf = new Map();
+    if (memberTags.length < 2)
+        return parentOf;
+    const members = new Set(memberTags);
+    const declarations = new Map(memberTags.map((t) => [t, getComponent(t)]));
+    // (a) A container's slot descriptions name the children it accepts.
+    for (const [tag, component] of declarations) {
+        if (!component)
+            continue;
+        for (const slot of component.slots ?? []) {
+            for (const match of (slot.description ?? "").matchAll(TAG_PATTERN)) {
+                const child = match[0].toLowerCase();
+                if (child !== tag && members.has(child) && !parentOf.has(child)) {
+                    parentOf.set(child, tag);
+                }
+            }
+        }
+    }
+    // (b) A child's own description names the container it belongs inside.
+    for (const [tag, component] of declarations) {
+        if (!component || parentOf.has(tag))
+            continue;
+        const text = `${component.summary ?? ""}\n${component.description ?? ""}`;
+        for (const match of text.matchAll(CONTAINMENT_PHRASE)) {
+            const parent = match[1].toLowerCase();
+            if (parent !== tag && members.has(parent)) {
+                parentOf.set(tag, parent);
+                break;
+            }
+        }
+    }
+    // (c) A component explicitly marked as slotted/internal that still has no
+    // container falls back to the family's only unmarked member.
+    const marked = new Set(memberTags.filter((t) => {
+        const c = declarations.get(t);
+        return SUBCOMPONENT_MARKER.test(`${c?.summary ?? ""}\n${c?.description ?? ""}`);
+    }));
+    const unmarked = memberTags.filter((t) => !marked.has(t));
+    if (unmarked.length === 1) {
+        for (const tag of marked) {
+            if (!parentOf.has(tag))
+                parentOf.set(tag, unmarked[0]);
+        }
+    }
+    // Guard against a doc cycle producing an unrooted family.
+    for (const [child, parent] of parentOf) {
+        if (parentOf.get(parent) === child)
+            parentOf.delete(child);
+    }
+    return parentOf;
+}
+/**
+ * Get the npm package a component ships in.
+ * Subcomponents resolve to their parent's package.
+ */
+export function getPackageName(tagName) {
+    return (getFamilies().get(tagName.toLowerCase())?.packageName ?? "@nysds/components");
+}
+// ============================================================================
+// Mention derivation
+// ============================================================================
+const TAG_PATTERN = /nys-[a-z][a-z0-9-]*/g;
+/** Phrasing that marks a `nys-*` string as an event name, not a component. */
+const EVENT_CONTEXT_BEFORE = /\b(emit|emits|emitted|emitting|dispatch|dispatches|dispatched|fire|fires|fired|listen|listens|listening to|handler for|event)\b[^.]{0,60}$/i;
+const EVENT_CONTEXT_AFTER = /^[`'")\]]*\s*(event|events)\b/i;
+function getTagSet() {
+    if (cachedTagSet)
+        return cachedTagSet;
+    cachedTagSet = new Set(getAllComponents()
+        .map((c) => c.tagName?.toLowerCase())
+        .filter((t) => Boolean(t)));
+    return cachedTagSet;
+}
+/**
+ * Every event name emitted anywhere in the design system.
+ *
+ * Most (`nys-change`, `nys-input`) are already excluded by the tag-set filter.
+ * This set exists for the overlap cases — names that are simultaneously a
+ * registered component tag and an event name.
+ */
+function getEventNames() {
+    if (cachedEventNames)
+        return cachedEventNames;
+    const names = new Set();
+    for (const component of getAllComponents()) {
+        for (const event of component.events ?? []) {
+            if (event.name)
+                names.add(event.name.toLowerCase());
+        }
+    }
+    cachedEventNames = names;
+    return names;
+}
+/** All prose a component's docs expose, concatenated for scanning. */
+function documentedText(component) {
+    return [
+        component.summary,
+        component.description,
+        ...(component.slots ?? []).map((s) => s.description),
+        ...(component.attributes ?? []).map((a) => a.description),
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+function extractMentions(component) {
+    const selfTag = component.tagName?.toLowerCase() ?? "";
+    const text = documentedText(component);
+    const tags = getTagSet();
+    const eventNames = getEventNames();
+    const mentions = new Set();
+    for (const match of text.matchAll(TAG_PATTERN)) {
+        const tag = match[0].toLowerCase();
+        if (tag === selfTag)
+            continue;
+        // Drops event names, CSS variables, utility classes, and references to
+        // components that no longer exist.
+        if (!tags.has(tag))
+            continue;
+        // Ambiguous: this string is both a component tag and an event name.
+        // Fall back to the surrounding phrasing.
+        if (eventNames.has(tag)) {
+            const index = match.index ?? 0;
+            const before = text.slice(Math.max(0, index - 80), index);
+            const after = text.slice(index + tag.length, index + tag.length + 20);
+            if (EVENT_CONTEXT_BEFORE.test(before) ||
+                EVENT_CONTEXT_AFTER.test(after)) {
+                continue;
+            }
+        }
+        mentions.add(tag);
+    }
+    return mentions;
+}
+function getMentionGraph() {
+    if (cachedMentions)
+        return cachedMentions;
+    const graph = new Map();
+    for (const component of getAllComponents()) {
+        const tag = component.tagName?.toLowerCase();
+        if (!tag)
+            continue;
+        graph.set(tag, extractMentions(component));
+    }
+    cachedMentions = graph;
+    return graph;
+}
+// ============================================================================
+// Relationship assembly
+// ============================================================================
+/** Whether the docs say a subcomponent is also usable outside its container. */
+function allowsStandalone(tagName) {
+    const component = getComponent(tagName);
+    return /\bstandalone\b/i.test(`${component?.summary ?? ""}\n${component?.description ?? ""}`);
+}
+function summaryOf(tagName) {
+    const component = getComponent(tagName);
+    return (component?.summary ||
+        component?.description?.split("\n")[0] ||
+        "No description");
+}
+export function getRelationships(tagName) {
+    const tag = tagName.toLowerCase();
+    const family = getFamilies().get(tag);
+    const mentions = getMentionGraph();
+    const packageName = getPackageName(tag);
+    const children = [];
+    const siblings = [];
+    let parent;
+    if (family) {
+        const parentTag = family.parentOf.get(tag);
+        if (parentTag) {
+            parent = {
+                tagName: parentTag,
+                summary: summaryOf(parentTag),
+                relation: "parent",
+                note: allowsStandalone(tag)
+                    ? `Container for <${tag}>. <${tag}> also works standalone, but the container handles grouping, validation, and form submission.`
+                    : `<${tag}> must be nested inside <${parentTag}>.`,
+                samePackage: true,
+            };
+        }
+        for (const member of family.memberTags) {
+            if (member === tag)
+                continue;
+            const memberParent = family.parentOf.get(member);
+            if (memberParent === tag) {
+                children.push({
+                    tagName: member,
+                    summary: summaryOf(member),
+                    relation: "child",
+                    note: `Nested inside <${tag}>. Ships in ${packageName} — no extra install or import.`,
+                    samePackage: true,
+                });
+            }
+            else if (parentTag && memberParent === parentTag) {
+                siblings.push({
+                    tagName: member,
+                    summary: summaryOf(member),
+                    relation: "sibling",
+                    note: `Used alongside <${tag}> inside <${parentTag}>. Ships in ${packageName}.`,
+                    samePackage: true,
+                });
+            }
+        }
+    }
+    // Cross-package edges from JSDoc prose, in both directions
+    const familyTags = new Set(family?.memberTags ?? [tag]);
+    const outgoing = mentions.get(tag) ?? new Set();
+    const incoming = new Set();
+    for (const [source, targets] of mentions) {
+        if (targets.has(tag))
+            incoming.add(source);
+    }
+    const relatedTags = new Set([...outgoing, ...incoming]);
+    const related = [];
+    for (const other of [...relatedTags].sort()) {
+        if (familyTags.has(other))
+            continue;
+        const isOutgoing = outgoing.has(other);
+        const isIncoming = incoming.has(other);
+        const relation = isOutgoing && isIncoming
+            ? "mutual"
+            : isOutgoing
+                ? "mentions"
+                : "mentioned-by";
+        const note = relation === "mutual"
+            ? `<${tag}> and <${other}> reference each other in their docs — usually alternatives for the same job.`
+            : relation === "mentions"
+                ? `The <${tag}> docs point to <${other}>.`
+                : `The <${other}> docs point back to <${tag}>.`;
+        related.push({
+            tagName: other,
+            summary: summaryOf(other),
+            relation,
+            note,
+            samePackage: getPackageName(other) === packageName,
+        });
+    }
+    return { package: packageName, parent, children, siblings, related };
+}
+// ============================================================================
+// Integration payload
+// ============================================================================
+const STYLES_NOTE = "NYSDS components render unstyled without the CSS variables from @nysds/styles. " +
+    "Use '@nysds/styles/full' on a new project (reset + typography + utility classes) " +
+    "or '@nysds/styles' on an existing one (variables only).";
+/**
+ * Build the full integration payload for a component: what to install, what to
+ * import, what has to be nested inside it, and which guides cover it.
+ */
+export function getIntegration(component) {
+    const tag = component.tagName?.toLowerCase() ?? "";
+    const relationships = getRelationships(tag);
+    const packageName = relationships.package;
+    const className = component.name || "NysComponent";
+    // A subcomponent is required for correct usage of its parent, and vice versa.
+    const requires = [
+        ...(relationships.parent ? [relationships.parent] : []),
+        ...relationships.children,
+    ];
+    const attributeNames = new Set((component.attributes ?? []).map((a) => a.name));
+    const isFormControl = attributeNames.has("showError") || attributeNames.has("errorMessage");
+    const guides = [...getGuidesMentioning(tag)];
+    if (isFormControl && !guides.some((g) => g.topic === "form-validation")) {
+        guides.push({
+            guide: "form-validation",
+            topic: "form-validation",
+            call: `get_guide({ topic: "form-validation" })`,
+        });
+    }
+    const nextSteps = [];
+    for (const required of requires) {
+        nextSteps.push(`get_component({ tagName: "${required.tagName}" }) — ${required.relation === "parent"
+            ? `the container <${tag}> goes inside`
+            : `nested inside <${tag}>`}`);
+    }
+    nextSteps.push(`validate_component_api({ tagName: "${tag}", attributes: { ... } }) — check attributes before shipping`);
+    if (guides.length > 0) {
+        nextSteps.push(`${guides[0].call} — guide covering <${tag}>`);
+    }
+    nextSteps.push(`get_utility_classes({ category: "spacing" }) — spacing around <${tag}> without wrapper elements`);
+    return {
+        package: packageName,
+        install: `npm install ${packageName} @nysds/styles`,
+        imports: {
+            component: `import '${packageName}';`,
+            allComponents: `import '@nysds/components';`,
+            react: `import { ${className} } from '@nysds/components/react';`,
+            styles: `@import '@nysds/styles';`,
+        },
+        stylesNote: STYLES_NOTE,
+        requires,
+        usedWith: relationships.siblings,
+        alternatives: relationships.related,
+        guides,
+        styling: {
+            cssCustomProperties: (component.cssProperties ?? []).map((p) => ({
+                name: p.name,
+                description: p.description,
+            })),
+            spacing: `Apply spacing with utility classes on the element itself, e.g. <${tag} class="nys-margin-b-300">. Call get_utility_classes({ category: "spacing" }).`,
+            tokens: `Style overrides should reference design tokens, not raw values. Call find_tokens({ query: "..." }) or get_token({ token: "--nys-..." }).`,
+        },
+        nextSteps,
+    };
+}
+/**
+ * Clear cached derivations (useful for testing).
+ */
+export function clearRelationshipCache() {
+    cachedFamilies = null;
+    cachedModulePaths = null;
+    cachedTagSet = null;
+    cachedEventNames = null;
+    cachedMentions = null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nysds/mcp-server",
-  "version": "1.19.4",
+  "version": "1.20.0",
   "description": "MCP server for the New York State Design System. Exposes components, tokens, and documentation to AI assistants.",
   "type": "module",
   "bin": {
@@ -30,8 +30,8 @@
     "zod": "^3.25"
   },
   "devDependencies": {
-    "@nysds/styles": "^1.19.4",
-    "@nysds/tokens": "^1.19.4",
+    "@nysds/styles": "^1.20.0",
+    "@nysds/tokens": "^1.20.0",
     "@types/node": "^22.0.0",
     "typescript": "^5.9.3"
   },