@ng-solid/mcp 22.0.0

package/lib/style-contract.js

@@ -0,0 +1,167 @@
+/**
+ * Pure port of `tools/scripts/check-design-system-styles.mjs`.
+ *
+ * The original script walks the filesystem and calls `process.exit`. This module extracts
+ * the same rules into a pure function an MCP tool can run against a snippet an agent pastes,
+ * without touching disk. The three canonical regexes (BEM class shape, banned Tailwind
+ * utilities, raw CSS values) are NOT re-declared here -- they are read from
+ * `snapshot.styleContract` (`design-system.json`) so this module can never drift from the
+ * regexes the real `pnpm quality:styles` gate enforces.
+ */
+/** Parses a stringified `RegExp` literal (e.g. `"/^ns-.../"` or `"/.../i"`) back into a RegExp. */
+export function parseRegexLiteral(literal) {
+    const match = /^\/(.*)\/([a-z]*)$/.exec(literal);
+    if (!match) {
+        throw new Error(`Not a serialized RegExp literal: ${literal}`);
+    }
+    return new RegExp(match[1], match[2]);
+}
+function lineAt(code, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < code.length; i++) {
+        if (code[i] === '\n')
+            line++;
+    }
+    return line;
+}
+function ruleFrom(contract, id) {
+    const rule = contract.rules.find((candidate) => candidate.id === id);
+    if (!rule) {
+        throw new Error(`style contract snapshot is missing rule "${id}"`);
+    }
+    return rule;
+}
+const CLASS_ATTRIBUTE = /(?:^|\s)class="([^"]+)"/g;
+const CLASS_BINDING = /\[class\.([^\]]+)\]/g;
+const NG_CLASS_ATTRIBUTE = /\[ngClass\]="([\s\S]*?)"/g;
+const OBJECT_CLASS_KEY = /(?:'([^']+)'|([a-zA-Z][\w-]*))\s*:/g;
+const INLINE_STYLES = /\bstyles\s*:/;
+const SCSS_USE_IMPORT = /@use\b|@import\b/;
+function validateTemplateClasses(code, contract, violations) {
+    const bemPattern = parseRegexLiteral(contract.bemClassPattern);
+    const utilityPattern = parseRegexLiteral(contract.utilityClassPattern);
+    const bemRule = ruleFrom(contract, 'bem-naming');
+    const utilityRule = ruleFrom(contract, 'banned-utility');
+    const checkClass = (className, index) => {
+        const trimmed = className.trim();
+        if (!trimmed)
+            return;
+        if (!bemPattern.test(trimmed)) {
+            violations.push({
+                ruleId: bemRule.id,
+                severity: bemRule.severity,
+                message: `${bemRule.message} -- got "${trimmed}".`,
+                snippet: trimmed,
+                line: lineAt(code, index)
+            });
+        }
+        if (utilityPattern.test(trimmed)) {
+            violations.push({
+                ruleId: utilityRule.id,
+                severity: utilityRule.severity,
+                message: `${utilityRule.message} -- got "${trimmed}".`,
+                snippet: trimmed,
+                line: lineAt(code, index)
+            });
+        }
+    };
+    for (const match of code.matchAll(CLASS_ATTRIBUTE)) {
+        const listStart = match.index + match[0].indexOf(match[1]);
+        let offset = 0;
+        for (const className of match[1].split(/\s+/)) {
+            const at = match[1].indexOf(className, offset);
+            offset = at + className.length;
+            checkClass(className, listStart + at);
+        }
+    }
+    for (const match of code.matchAll(CLASS_BINDING)) {
+        checkClass(match[1], match.index);
+    }
+    for (const match of code.matchAll(NG_CLASS_ATTRIBUTE)) {
+        const bodyStart = match.index + match[0].indexOf(match[1]);
+        for (const key of match[1].matchAll(OBJECT_CLASS_KEY)) {
+            const name = key[1] ?? key[2];
+            checkClass(name, bodyStart + (key.index ?? 0));
+        }
+    }
+}
+function validateScss(code, contract, violations) {
+    if (!code.includes('@reference')) {
+        const rule = ruleFrom(contract, 'scss-reference-required');
+        violations.push({
+            ruleId: rule.id,
+            severity: rule.severity,
+            message: rule.message,
+            snippet: code.slice(0, 60).trim()
+        });
+    }
+    const useImportMatch = SCSS_USE_IMPORT.exec(code);
+    if (useImportMatch) {
+        const rule = ruleFrom(contract, 'no-use-import');
+        violations.push({
+            ruleId: rule.id,
+            severity: rule.severity,
+            message: rule.message,
+            snippet: useImportMatch[0],
+            line: lineAt(code, useImportMatch.index)
+        });
+    }
+    const rawValuePattern = parseRegexLiteral(contract.rawStyleValuePattern);
+    const globalRawValuePattern = new RegExp(rawValuePattern.source, rawValuePattern.flags.includes('g')
+        ? rawValuePattern.flags
+        : `${rawValuePattern.flags}g`);
+    const rawRule = ruleFrom(contract, 'no-raw-css-values');
+    for (const match of code.matchAll(globalRawValuePattern)) {
+        violations.push({
+            ruleId: rawRule.id,
+            severity: rawRule.severity,
+            message: `${rawRule.message} -- got "${match[0]}".`,
+            snippet: match[0],
+            line: lineAt(code, match.index)
+        });
+    }
+}
+function validateComponentTs(code, contract, violations) {
+    const match = INLINE_STYLES.exec(code);
+    if (match) {
+        const rule = ruleFrom(contract, 'no-inline-styles');
+        violations.push({
+            ruleId: rule.id,
+            severity: rule.severity,
+            message: rule.message,
+            snippet: code.slice(match.index, match.index + 40).trim(),
+            line: lineAt(code, match.index)
+        });
+    }
+    // Inline templates inside a `template: \`...\`` literal are still markup -- apply the same
+    // class rules a `.html` file would get.
+    validateTemplateClasses(code, contract, violations);
+}
+/**
+ * Validates a code snippet against the ng-solid style-architecture contract.
+ *
+ * @param code the raw source text to validate (a template, a component SCSS file, or a
+ *   component `.ts` source)
+ * @param kind which contract rules apply -- `'template'` runs the BEM/Tailwind-utility checks,
+ *   `'scss'` runs the `@reference`/`@use`/raw-value checks, `'component-ts'` runs the
+ *   inline-`styles:` check plus the template checks (component `.ts` files can carry an inline
+ *   template)
+ * @param contract `snapshot.styleContract` -- the canonical rule/pattern set, never duplicated here
+ */
+export function validateStyleContract(code, kind, contract) {
+    const violations = [];
+    if (kind === 'template') {
+        validateTemplateClasses(code, contract, violations);
+    }
+    else if (kind === 'scss') {
+        validateScss(code, contract, violations);
+    }
+    else {
+        validateComponentTs(code, contract, violations);
+    }
+    return {
+        valid: violations.every((violation) => violation.severity !== 'error'),
+        violations
+    };
+}
+//# sourceMappingURL=style-contract.js.map

package/lib/template-parser.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Near-literal port of BHD's `tools.template-parser.ts` -- a small, well-tested,
+ * hostile-input-bounded scanner over a template string that picks out the narrow set of
+ * binding forms `validate_component_usage` needs to check.
+ *
+ * Two changes from the BHD original:
+ *  1. The `ns` prefix replaces `bhd` wherever the caller filters out selector-prefixed noise
+ *     (that filtering lives in `tools.components.ts`, not here -- this module has no
+ *     hardcoded prefix of its own).
+ *  2. Banana-in-a-box `[(x)]="y"` bindings are recognized as a third candidate kind, `model`,
+ *     distinct from a plain property binding `[x]="y"`. BHD had no `model()` inputs; ng-solid
+ *     has 15+ (`ns-input`, `ns-drawer`, `ns-modal`, ...).
+ */
+export interface TemplateCandidates {
+    /** Plain attribute-form and property-binding-form names, e.g. `variant`, `disabled`. */
+    attributes: string[];
+    /** Event-binding names, e.g. `dismissed` from `(dismissed)="...". */
+    events: string[];
+    /** Banana-in-a-box model-binding names, e.g. `value` from `[(value)]="...". */
+    models: string[];
+    transitions: number;
+}
+/**
+ * Extracts the narrow binding forms supported by `validate_component_usage`.
+ *
+ * This intentionally treats quotes as ordinary characters and consumes a malformed
+ * candidate fragment through its next `=` so parsing cannot restart inside it.
+ */
+export declare function parseTemplateCandidates(template: string): TemplateCandidates;

package/lib/template-parser.js

@@ -0,0 +1,230 @@
+/**
+ * Near-literal port of BHD's `tools.template-parser.ts` -- a small, well-tested,
+ * hostile-input-bounded scanner over a template string that picks out the narrow set of
+ * binding forms `validate_component_usage` needs to check.
+ *
+ * Two changes from the BHD original:
+ *  1. The `ns` prefix replaces `bhd` wherever the caller filters out selector-prefixed noise
+ *     (that filtering lives in `tools.components.ts`, not here -- this module has no
+ *     hardcoded prefix of its own).
+ *  2. Banana-in-a-box `[(x)]="y"` bindings are recognized as a third candidate kind, `model`,
+ *     distinct from a plain property binding `[x]="y"`. BHD had no `model()` inputs; ng-solid
+ *     has 15+ (`ns-input`, `ns-drawer`, `ns-modal`, ...).
+ */
+function isAsciiLetter(value) {
+    const code = value.codePointAt(0) ?? -1;
+    return (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
+}
+function isAsciiDigit(value) {
+    const code = value.codePointAt(0) ?? -1;
+    return code >= 48 && code <= 57;
+}
+function isWhitespace(value) {
+    return (value === ' ' ||
+        value === '\n' ||
+        value === '\r' ||
+        value === '\t' ||
+        value === '\f');
+}
+function isIdentifierContinuation(value) {
+    return (isAsciiLetter(value) ||
+        isAsciiDigit(value) ||
+        value === '_' ||
+        value === '-');
+}
+function candidateKind(start, next) {
+    if (start === '[' && next === '(')
+        return 'model';
+    if (start === '[')
+        return 'property';
+    if (start === '(')
+        return 'event';
+    if (isAsciiLetter(start))
+        return 'attribute';
+    return 'malformed';
+}
+function consume(template, state) {
+    const character = template[state.index];
+    state.index += 1;
+    state.transitions += 1;
+    return character;
+}
+function consumeMalformedFragment(template, state) {
+    while (state.index < template.length &&
+        !isWhitespace(template[state.index])) {
+        if (consume(template, state) === '=')
+            return;
+    }
+}
+function parseAttributeCandidate(template, state, fragmentStart) {
+    let invalid = false;
+    while (state.index < template.length &&
+        !isWhitespace(template[state.index])) {
+        const characterIndex = state.index;
+        const character = consume(template, state);
+        if (character === '=') {
+            return invalid
+                ? undefined
+                : template.slice(fragmentStart, characterIndex);
+        }
+        if (characterIndex > fragmentStart && !isIdentifierContinuation(character))
+            invalid = true;
+    }
+    return undefined;
+}
+function closingDelimiter(kind) {
+    return kind === 'property' ? ']' : ')';
+}
+function bindingNameStart(character, characterIndex) {
+    return isAsciiLetter(character) ? characterIndex : -1;
+}
+function updateBindingCandidate(binding, character, characterIndex, delimiter) {
+    if (character === delimiter && binding.nameStart !== -1 && !binding.closed) {
+        binding.nameEnd = characterIndex;
+        binding.closed = true;
+        return;
+    }
+    if (binding.closed || !isIdentifierContinuation(character))
+        binding.invalid = true;
+}
+function completeBindingCandidate(template, binding) {
+    if (binding.invalid || !binding.closed)
+        return undefined;
+    return template.slice(binding.nameStart, binding.nameEnd);
+}
+function parseBindingCandidate(template, state, fragmentStart, kind) {
+    const binding = {
+        invalid: false,
+        nameStart: -1,
+        nameEnd: -1,
+        closed: false
+    };
+    const delimiter = closingDelimiter(kind);
+    while (state.index < template.length &&
+        !isWhitespace(template[state.index])) {
+        const characterIndex = state.index;
+        const character = consume(template, state);
+        if (character === '=') {
+            return completeBindingCandidate(template, binding);
+        }
+        const offset = characterIndex - fragmentStart;
+        if (offset === 0)
+            continue;
+        if (offset === 1) {
+            binding.nameStart = bindingNameStart(character, characterIndex);
+            if (binding.nameStart === -1)
+                binding.invalid = true;
+            continue;
+        }
+        updateBindingCandidate(binding, character, characterIndex, delimiter);
+    }
+    return undefined;
+}
+/**
+ * Parses `[(name)]=` starting at `fragmentStart` (which points at the `[`; the caller has
+ * already confirmed the next character is `(` via `candidateKind`).
+ */
+function parseModelCandidate(template, state, fragmentStart) {
+    const model = {
+        invalid: false,
+        nameStart: -1,
+        nameEnd: -1,
+        stage: 'name'
+    };
+    while (state.index < template.length &&
+        !isWhitespace(template[state.index])) {
+        const characterIndex = state.index;
+        const character = consume(template, state);
+        const offset = characterIndex - fragmentStart;
+        if (character === '=') {
+            return model.invalid || model.stage !== 'closed'
+                ? undefined
+                : template.slice(model.nameStart, model.nameEnd);
+        }
+        if (offset <= 1)
+            continue; // consumes '[' then '(', already validated by the caller
+        if (model.stage === 'name') {
+            if (model.nameStart === -1) {
+                model.nameStart = bindingNameStart(character, characterIndex);
+                if (model.nameStart === -1)
+                    model.invalid = true;
+                continue;
+            }
+            if (character === ')') {
+                model.nameEnd = characterIndex;
+                model.stage = 'awaiting-bracket';
+                continue;
+            }
+            if (!isIdentifierContinuation(character))
+                model.invalid = true;
+            continue;
+        }
+        if (model.stage === 'awaiting-bracket') {
+            if (character === ']') {
+                model.stage = 'closed';
+            }
+            else {
+                model.invalid = true;
+            }
+            continue;
+        }
+        // stage === 'closed': anything other than '=' before whitespace/end is invalid
+        model.invalid = true;
+    }
+    return undefined;
+}
+/**
+ * Extracts the narrow binding forms supported by `validate_component_usage`.
+ *
+ * This intentionally treats quotes as ordinary characters and consumes a malformed
+ * candidate fragment through its next `=` so parsing cannot restart inside it.
+ */
+export function parseTemplateCandidates(template) {
+    const attributes = [];
+    const events = [];
+    const models = [];
+    const state = { index: 0, transitions: 0 };
+    while (state.index < template.length) {
+        const start = template[state.index];
+        if (isWhitespace(start)) {
+            consume(template, state);
+            continue;
+        }
+        // A quote or other punctuation is not a candidate start. Advancing one character
+        // retains the prior scan's behavior of finding simple attributes within quotes.
+        if (!isAsciiLetter(start) &&
+            !isAsciiDigit(start) &&
+            start !== '[' &&
+            start !== '(') {
+            consume(template, state);
+            continue;
+        }
+        const fragmentStart = state.index;
+        const kind = candidateKind(start, template[state.index + 1]);
+        if (kind === 'malformed') {
+            consumeMalformedFragment(template, state);
+            continue;
+        }
+        let name;
+        if (kind === 'attribute') {
+            name = parseAttributeCandidate(template, state, fragmentStart);
+        }
+        else if (kind === 'model') {
+            name = parseModelCandidate(template, state, fragmentStart);
+        }
+        else {
+            name = parseBindingCandidate(template, state, fragmentStart, kind);
+        }
+        if (name === undefined)
+            continue;
+        if (kind === 'model') {
+            models.push(name);
+            continue;
+        }
+        attributes.push(name);
+        if (kind === 'event')
+            events.push(name);
+    }
+    return { attributes, events, models, transitions: state.transitions };
+}
+//# sourceMappingURL=template-parser.js.map

package/lib/tools.components.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Discovery, API, form-control, service/provider and style-validation tools -- the bulk of
+ * the ng-solid MCP surface. Split out of `tools.ts` to keep that file a thin aggregator.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ComponentDoc, NsSnapshot } from './types.js';
+export declare function jsonError(payload: Record<string, unknown>): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+/** Every response embedding markup MUST carry this trio -- `<ns-x>` does not work without it. */
+export interface ComponentTrio {
+    selector: string;
+    importStatement: string;
+    imports: string[];
+}
+export declare function importTrio(component: ComponentDoc): ComponentTrio;
+/** Plain Levenshtein edit distance, used to rank "did you mean" suggestions. */
+export declare function levenshtein(a: string, b: string): number;
+export declare function suggestComponents(snapshot: NsSnapshot, query: string, limit?: number): string[];
+export interface ComponentResolution {
+    component: ComponentDoc | null;
+    error?: string;
+    suggestions?: string[];
+}
+/**
+ * Resolves a user-supplied name to a `ComponentDoc`. Accepts a selector (`ns-button`), a class
+ * name (`NsButtonComponent`), a slug (`button`) or an attribute-directive selector
+ * (`[nsTooltip]`), case-insensitively. Never returns a bare "not found" -- always attaches
+ * distance-ranked suggestions.
+ */
+export declare function resolveComponent(snapshot: NsSnapshot, input: string): ComponentResolution;
+/** For an internal (non-exported) subcomponent, finds the public component that renders it. */
+export declare function findPublicSiblingFor(snapshot: NsSnapshot, doc: ComponentDoc): ComponentDoc | null;
+/** Builds a minimal-but-valid markup snippet for a component, honoring required inputs/models. */
+export declare function buildTemplateSnippet(doc: ComponentDoc, options?: {
+    includeOptional?: boolean;
+}): string;
+/** Renders a full Markdown doc for a component -- shared by `export_component_docs` and the `ns://component/{selector}/markdown` resource. */
+export declare function renderComponentMarkdown(snapshot: NsSnapshot, doc: ComponentDoc): string;
+export declare function registerComponentTools(server: McpServer): void;