@lyse-labs/lyse 0.1.0-alpha.2 → 0.2.0-alpha.1

package/dist/rules/ai-surface-llms-txt-structure.js

@@ -0,0 +1,200 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createLyseRule } from "./_rule-module.js";
+const RULE_ID = "ai-surface/llms-txt-structure";
+const MAX_FILE_BYTES = 1_000_000;
+const README_CANDIDATES = ["README.md", "README", "readme.md"];
+const ALLOWLIST_DIRECTIVE = "lyse-disable ai-surface/llms-txt-structure";
+const H1_RE = /^#\s+\S/;
+const H2_RE = /^##\s+\S/;
+const BLOCKQUOTE_RE = /^>\s+\S/;
+const LIST_LINK_RE = /^\s*[-*]\s+\[([^\]]*)\]\(([^)]*)\)/;
+function readFileIfSmall(absPath) {
+    try {
+        const stat = statSync(absPath);
+        if (!stat.isFile())
+            return null;
+        if (stat.size > MAX_FILE_BYTES)
+            return null;
+        const content = readFileSync(absPath, "utf8");
+        // Strip UTF-8 BOM so VSCode-with-BOM / Notepad-default files don't break H1 detection.
+        return content.startsWith("") ? content.slice(1) : content;
+    }
+    catch {
+        return null;
+    }
+}
+function hasAllowlistDirective(repoRoot) {
+    for (const candidate of README_CANDIDATES) {
+        const abs = join(repoRoot, candidate);
+        const content = readFileIfSmall(abs);
+        if (content !== null && content.includes(ALLOWLIST_DIRECTIVE)) {
+            return true;
+        }
+    }
+    return false;
+}
+function analyseStructure(content) {
+    const report = {
+        hasH1: false,
+        hasBlockquote: false,
+        hasSection: false,
+        malformedLinks: [],
+    };
+    const lines = content.split("\n");
+    let firstMeaningfulIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if ((lines[i] ?? "").trim().length > 0) {
+            firstMeaningfulIdx = i;
+            break;
+        }
+    }
+    if (firstMeaningfulIdx >= 0 && H1_RE.test(lines[firstMeaningfulIdx] ?? "")) {
+        report.hasH1 = true;
+    }
+    if (report.hasH1) {
+        for (let i = firstMeaningfulIdx + 1; i < lines.length; i++) {
+            const line = lines[i] ?? "";
+            if (line.trim().length === 0)
+                continue;
+            if (BLOCKQUOTE_RE.test(line)) {
+                report.hasBlockquote = true;
+            }
+            break;
+        }
+    }
+    let currentSectionLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (H2_RE.test(line)) {
+            report.hasSection = true;
+            currentSectionLine = i + 1;
+            continue;
+        }
+        if (currentSectionLine < 0)
+            continue;
+        const match = line.match(LIST_LINK_RE);
+        if (!match)
+            continue;
+        const title = (match[1] ?? "").trim();
+        const url = (match[2] ?? "").trim();
+        if (title.length === 0 || url.length === 0) {
+            report.malformedLinks.push({
+                line: i + 1,
+                message: title.length === 0 && url.length === 0
+                    ? "Section link is missing both title and URL"
+                    : title.length === 0
+                        ? "Section link is missing a title"
+                        : "Section link is missing a URL",
+                suggestion: "format each entry as `- [<title>](<url>): <description>` per llmstxt.org spec",
+            });
+        }
+    }
+    return report;
+}
+const evaluate = async (ctx, _files) => {
+    const findings = [];
+    if (!ctx.repoRoot) {
+        return { findings, opportunities: 0 };
+    }
+    if (hasAllowlistDirective(ctx.repoRoot)) {
+        return { findings, opportunities: 0 };
+    }
+    const llmsTxtAbs = join(ctx.repoRoot, "llms.txt");
+    const content = readFileIfSmall(llmsTxtAbs);
+    if (content === null) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "warning",
+            location: { file: "llms.txt", line: 1, column: 1 },
+            message: "No llms.txt at repo root — AI agents have no top-level map of the design system",
+            suggestion: "add an llms.txt file (llmstxt.org spec) with an H1 title, a blockquote summary, and `## <section>` link lists",
+        });
+        return { findings, opportunities: 1 };
+    }
+    const report = analyseStructure(content);
+    if (!report.hasH1) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "error",
+            location: { file: "llms.txt", line: 1, column: 1 },
+            message: "llms.txt is missing a top-level `# <title>` H1 heading",
+            suggestion: "start the file with a single `# <Project Title>` line, per llmstxt.org",
+        });
+    }
+    if (!report.hasBlockquote) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "error",
+            location: { file: "llms.txt", line: 1, column: 1 },
+            message: "llms.txt is missing a `> <summary>` blockquote after the H1",
+            suggestion: "add a one-sentence `> ...` blockquote summarising the project right after the H1",
+        });
+    }
+    if (!report.hasSection) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "error",
+            location: { file: "llms.txt", line: 1, column: 1 },
+            message: "llms.txt has no `## <section>` headings — link lists are required by the spec",
+            suggestion: "add at least one `## <Section>` heading followed by `- [<title>](<url>): <description>` items, per llmstxt.org",
+        });
+    }
+    for (const issue of report.malformedLinks) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "error",
+            location: { file: "llms.txt", line: issue.line, column: 1 },
+            message: issue.message,
+            suggestion: issue.suggestion,
+        });
+    }
+    return { findings, opportunities: 1 };
+};
+export const rule = createLyseRule({
+    meta: {
+        axis: "ai-surface",
+        lyseRuleId: RULE_ID,
+        defaultSeverity: "warning",
+        shortDescription: "llms.txt at repo root must follow the llmstxt.org structure",
+        fullDescription: "Detects whether a design-system repository ships an `llms.txt` file at the repo root and validates the file's structure against the llmstxt.org specification: a single `# <title>` H1, a `> <summary>` blockquote, and at least one `## <section>` heading whose list items follow `- [<title>](<url>): <description>`. Absence emits a warning. A present-but-malformed `llms.txt` emits one error per structural issue. The optional companion file `llms-full.txt` is detected as a bonus signal but is not required.",
+        helpUri: "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-llms-txt-structure.md",
+        rationale: `Why it matters
+
+\`llms.txt\` (llmstxt.org, Tantum 2024) is the emerging convention for handing AI agents a token-cheap, curated map of a project. For a design system this is the AI-Consumable surface: a single discoverable entry that lists the canonical Quickstart, API reference, component index, and policy docs without forcing the agent to crawl the whole repo.
+
+Absence is a missed opportunity, not a bug — agents fall back to scanning the README and source tree, which is slower and more expensive. Structural errors (missing H1, missing summary, malformed link rows) are scored as errors because consumers (cursor, claude code, custom agents) parse the file on the assumption it follows the spec, and silent malformations break the contract.
+
+The companion \`llms-full.txt\` — a single-file inlining of every linked document — is a strong bonus signal but is not enforced as a hard requirement.`,
+        examples: [
+            {
+                good: `# Acme DS
+
+> A token-first React design system.
+
+## Docs
+
+- [Quickstart](https://acme.dev/quickstart): Get started in 3 minutes.
+- [API reference](https://acme.dev/api): Full method index.`,
+                bad: `Welcome to Acme DS. We ship Buttons and Cards.
+
+- random link list`,
+            },
+        ],
+        allowlist: [
+            "files larger than 1 MB at `llms.txt` — skipped to avoid pathological cases",
+            "repos whose README at the root contains the directive `lyse-disable ai-surface/llms-txt-structure` — rule is N/A",
+        ],
+    },
+    defaultOptions: [],
+    create: () => ({ evaluate }),
+});
+export const _internal = {
+    analyseStructure,
+};
+//# sourceMappingURL=ai-surface-llms-txt-structure.js.map

package/dist/rules/ai-surface-llms-txt-structure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-surface-llms-txt-structure.js","sourceRoot":"","sources":["../../src/rules/ai-surface-llms-txt-structure.ts"],"names":[],"mappings":"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"}

package/dist/rules/ai-surface-mcp-config-present.d.ts

@@ -0,0 +1,23 @@
+import type { Rule } from "../types.js";
+interface ServerValidation {
+    ok: boolean;
+    reason?: string;
+}
+declare function isAllowlisted(repoRoot: string): boolean;
+declare function discoverConfigs(repoRoot: string): string[];
+declare function validateServerEntry(name: string, entry: unknown): ServerValidation;
+interface ConfigValidation {
+    errors: string[];
+    validServers: number;
+}
+declare function validateConfig(data: unknown): ConfigValidation;
+export declare const rule: Rule;
+export declare const _internal: {
+    validateConfig: typeof validateConfig;
+    validateServerEntry: typeof validateServerEntry;
+    isAllowlisted: typeof isAllowlisted;
+    discoverConfigs: typeof discoverConfigs;
+    CANDIDATE_PATHS: string[];
+    DISABLE_DIRECTIVE: string;
+};
+export {};

package/dist/rules/ai-surface-mcp-config-present.js

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { createLyseRule } from "./_rule-module.js";
+const RULE_ID = "ai-surface/mcp-config-present";
+const MAX_FILE_BYTES = 1_000_000;
+const CANDIDATE_PATHS = [
+    ".mcp.json",
+    ".cursor/mcp.json",
+    "claude_desktop_config.json",
+];
+const README_CANDIDATES = ["README.md", "README", "readme.md", "README.mdx"];
+const DISABLE_DIRECTIVE = `lyse-disable ${RULE_ID}`;
+function readJsonIfSmall(absPath) {
+    try {
+        const stat = statSync(absPath);
+        if (!stat.isFile())
+            return { data: null, parseError: "not a regular file" };
+        if (stat.size > MAX_FILE_BYTES)
+            return { data: null, parseError: "file too large" };
+        const raw = readFileSync(absPath, "utf8");
+        if (raw.trim().length === 0)
+            return { data: null, parseError: "empty file" };
+        return { data: JSON.parse(raw), parseError: null };
+    }
+    catch (e) {
+        return { data: null, parseError: e instanceof Error ? e.message : "unknown parse error" };
+    }
+}
+function isAllowlisted(repoRoot) {
+    for (const candidate of README_CANDIDATES) {
+        const abs = join(repoRoot, candidate);
+        if (!existsSync(abs))
+            continue;
+        try {
+            const stat = statSync(abs);
+            if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+                continue;
+            const raw = readFileSync(abs, "utf8");
+            if (raw.includes(DISABLE_DIRECTIVE))
+                return true;
+        }
+        catch {
+            // ignore unreadable README
+        }
+    }
+    return false;
+}
+function discoverConfigs(repoRoot) {
+    const found = [];
+    for (const candidate of CANDIDATE_PATHS) {
+        const abs = join(repoRoot, candidate);
+        if (existsSync(abs))
+            found.push(candidate);
+    }
+    return found;
+}
+function validateServerEntry(name, entry) {
+    if (name.trim().length === 0) {
+        return { ok: false, reason: "server name is not a non-empty string" };
+    }
+    if (typeof entry !== "object" || entry === null) {
+        return { ok: false, reason: `server "${name}" is not an object` };
+    }
+    const e = entry;
+    if (typeof e.command !== "string" || e.command.trim().length === 0) {
+        return { ok: false, reason: `server "${name}" missing \`command\` (string)` };
+    }
+    if (e.args !== undefined && !Array.isArray(e.args)) {
+        return { ok: false, reason: `server "${name}" has \`args\` that is not an array` };
+    }
+    return { ok: true };
+}
+function validateConfig(data) {
+    if (typeof data !== "object" || data === null) {
+        return { errors: ["config root is not a JSON object"], validServers: 0 };
+    }
+    const shape = data;
+    if (!("mcpServers" in shape)) {
+        return { errors: ["missing top-level `mcpServers` object"], validServers: 0 };
+    }
+    const servers = shape.mcpServers;
+    if (typeof servers !== "object" || servers === null || Array.isArray(servers)) {
+        return { errors: ["`mcpServers` must be an object"], validServers: 0 };
+    }
+    const entries = Object.entries(servers);
+    if (entries.length === 0) {
+        return { errors: ["`mcpServers` object is empty (declare at least one server)"], validServers: 0 };
+    }
+    const errors = [];
+    let validServers = 0;
+    for (const [name, entry] of entries) {
+        const result = validateServerEntry(name, entry);
+        if (!result.ok) {
+            errors.push(result.reason ?? `server "${name}" is invalid`);
+        }
+        else {
+            validServers += 1;
+        }
+    }
+    return { errors, validServers };
+}
+const evaluate = async (ctx, _files) => {
+    const findings = [];
+    if (!ctx.repoRoot) {
+        return { findings, opportunities: 0 };
+    }
+    if (isAllowlisted(ctx.repoRoot)) {
+        return { findings, opportunities: 0 };
+    }
+    const configs = discoverConfigs(ctx.repoRoot);
+    if (configs.length === 0) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "warning",
+            location: { file: ".mcp.json", line: 1, column: 1 },
+            message: "No MCP config file found — design system is not declared as AI-agent-accessible",
+            suggestion: "create `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), or `claude_desktop_config.json` declaring at least one MCP server with a `command`",
+        });
+        return { findings, opportunities: 1 };
+    }
+    let opportunities = 0;
+    for (const rel of configs) {
+        opportunities += 1;
+        const abs = join(ctx.repoRoot, rel);
+        const { data, parseError } = readJsonIfSmall(abs);
+        if (parseError !== null) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "error",
+                location: { file: rel, line: 1, column: 1 },
+                message: `MCP config is not valid JSON (${parseError})`,
+                suggestion: "ensure the config is parseable JSON with a top-level `mcpServers` object",
+            });
+            continue;
+        }
+        const outcome = validateConfig(data);
+        for (const err of outcome.errors) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "error",
+                location: { file: rel, line: 1, column: 1 },
+                message: err,
+                suggestion: "each server entry must have a non-empty string key and a `command` (string); `args` (array) is optional",
+            });
+        }
+    }
+    return { findings, opportunities };
+};
+export const rule = createLyseRule({
+    meta: {
+        axis: "ai-surface",
+        lyseRuleId: RULE_ID,
+        defaultSeverity: "warning",
+        shortDescription: "Design system should declare at least one MCP server",
+        fullDescription: "Looks for an MCP (Model Context Protocol) configuration file at the repo root: `.mcp.json` (Claude Code convention), `.cursor/mcp.json` (Cursor convention), or `claude_desktop_config.json`. When found, validates the file is parseable JSON, has a top-level `mcpServers` object with at least one entry, and each server entry has a non-empty string key and a `command` (string); `args` (array) is optional. Absence emits one warning (DS not yet AI-agent-accessible). Malformed JSON, missing/empty `mcpServers`, or invalid server entries emit errors.",
+        helpUri: "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-mcp-config-present.md",
+        rationale: `Why it matters
+
+The Model Context Protocol (MCP) is the de-facto standard for letting coding agents (Claude Code, Cursor, Claude Desktop) call tools that surface a design system's components, tokens, and docs at lookup time. A design system without an MCP server declaration leaves agents to scrape README and source files heuristically — the cost-vs-accuracy regression documented in Stream 1 of the AI-Consumable track.
+
+The signal is binary and cheap to enforce: either the repo declares at least one valid \`mcpServers\` entry or it doesn't. A warning (not info) reflects the strategic importance of AI-Consumable readiness for Track 2 design systems: shipping a stable MCP surface is now table-stakes.
+
+Severity escalates to error when a config file is present but malformed — a broken \`.mcp.json\` silently breaks every agent that tries to connect, which is worse than no config at all.`,
+        examples: [
+            {
+                good: '{ "mcpServers": { "lyse": { "command": "npx", "args": ["@lyse-labs/lyse", "mcp"] } } }',
+                bad: '{ "mcpServers": {} }',
+            },
+            {
+                good: '{ "mcpServers": { "design-system": { "command": "node", "args": ["./mcp-server.js"] } } }',
+                bad: '{ "servers": [] }',
+            },
+        ],
+        allowlist: [
+            "files larger than 1 MB — skipped to avoid pathological cases",
+            "repos containing `// lyse-disable ai-surface/mcp-config-present` in an adjacent README — rule is N/A",
+        ],
+    },
+    defaultOptions: [],
+    create: () => ({ evaluate }),
+});
+export const _internal = {
+    validateConfig,
+    validateServerEntry,
+    isAllowlisted,
+    discoverConfigs,
+    CANDIDATE_PATHS,
+    DISABLE_DIRECTIVE,
+};
+//# sourceMappingURL=ai-surface-mcp-config-present.js.map

package/dist/rules/ai-surface-mcp-config-present.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-surface-mcp-config-present.js","sourceRoot":"","sources":["../../src/rules/ai-surface-mcp-config-present.ts"],"names":[],"mappings":"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"}

package/dist/rules/ai-surface-shadcn-registry-valid.d.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types.js";
+interface ItemValidation {
+    ok: boolean;
+    reasons: string[];
+}
+declare function validateRegistryItem(item: unknown): ItemValidation;
+declare function looksLikeRegistryItem(data: unknown): boolean;
+declare function looksLikeRegistryCollection(data: unknown): boolean;
+interface ParsedRegistry {
+    items: unknown[];
+    shape: "single" | "collection";
+}
+declare function extractRegistryItems(data: unknown): ParsedRegistry;
+export declare const rule: Rule;
+export declare const _internal: {
+    validateRegistryItem: typeof validateRegistryItem;
+    looksLikeRegistryItem: typeof looksLikeRegistryItem;
+    looksLikeRegistryCollection: typeof looksLikeRegistryCollection;
+    extractRegistryItems: typeof extractRegistryItems;
+    REGISTRY_CANDIDATES: string[];
+};
+export {};