@lyse-labs/lyse 0.1.0-alpha.2

package/dist/rules/a11y-essentials.js

@@ -0,0 +1,140 @@
+import { Linter } from "eslint";
+import { createRequire } from "module";
+import { createLyseRule } from "./_rule-module.js";
+// eslint-plugin-jsx-a11y ships no TypeScript declarations and is a CJS package.
+// We load it via createRequire (safe ESM→CJS bridge) to avoid import assertion
+// syntax that esbuild / vitest's transform pipeline rejects.
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- eslint-plugin-jsx-a11y ships no type declarations
+const jsxA11yPlugin = require("eslint-plugin-jsx-a11y");
+// @typescript-eslint/parser unlocks TSX-with-TS-syntax linting (interfaces,
+// generics, `as` casts). Without it, espree fails on the majority of real
+// React+TS files and the a11y axis emits zero findings. See #167.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- @typescript-eslint/parser exports a Parser interface; cast for Linter.Config compatibility
+const tsParser = require("@typescript-eslint/parser");
+const linter = new Linter({ configType: "flat" });
+const A11Y_RULES = [
+    "jsx-a11y/alt-text",
+    "jsx-a11y/anchor-has-content",
+    "jsx-a11y/label-has-associated-control",
+    "jsx-a11y/role-has-required-aria-props",
+    "jsx-a11y/aria-role",
+];
+// Flat config: only register the 5 rules we care about, all as "warn".
+// Cast to `never` because eslint-plugin-jsx-a11y lacks TS declarations and
+// the inferred `any` shape doesn't match Linter.Config[] exactly.
+// Two-entry flat config: @typescript-eslint/parser for .ts/.tsx (handles TS
+// syntax + JSX), espree default for .js/.jsx (cheaper, sufficient when no TS
+// features are present). Closes #167. The TS parser also handles plain JSX
+// cleanly, so this also acts as a safety net if file extensions lie.
+const flatConfig = [
+    {
+        files: ["**/*.{ts,tsx}"],
+        languageOptions: {
+            parser: tsParser,
+            parserOptions: {
+                ecmaVersion: 2022,
+                sourceType: "module",
+                ecmaFeatures: { jsx: true },
+            },
+        },
+        plugins: { "jsx-a11y": jsxA11yPlugin },
+        rules: Object.fromEntries(A11Y_RULES.map((r) => [r, "warn"])),
+    },
+    {
+        files: ["**/*.{js,jsx}"],
+        languageOptions: {
+            parserOptions: {
+                ecmaVersion: 2022,
+                sourceType: "module",
+                ecmaFeatures: { jsx: true },
+            },
+        },
+        plugins: { "jsx-a11y": jsxA11yPlugin },
+        rules: Object.fromEntries(A11Y_RULES.map((r) => [r, "warn"])),
+    },
+];
+const evaluate = async (_ctx, files) => {
+    const findings = [];
+    const parseErrors = [];
+    let opportunities = 0;
+    for (const f of files.ts) {
+        // If the upstream SWC parser already failed (`f.ast === null`), the pipeline
+        // surfaced this on stderr via `parseErrorCount`. Don't re-report it here as
+        // `coverage.parseErrors` (avoid I1 double-counting), but still attempt ESLint
+        // analysis — espree handles plain JSX even when SWC's `tsx: false` mode
+        // rejects it (e.g. `.jsx` files).
+        const swcFailed = f.ast === null;
+        // ESLint flat API surfaces parse failures as a single `fatal: true` message.
+        // `.tsx` files route through `@typescript-eslint/parser` (#167), `.jsx` keeps
+        // espree. Files that still fail to parse (real syntax errors, unsupported
+        // features) are excluded from `opportunities` and reported via
+        // `meta.coverage.parseErrors` (#155) — otherwise the score would be 100/100
+        // on N/0 analyzed, a credibility hole.
+        let messages;
+        try {
+            messages = linter.verify(f.source, flatConfig, { filename: f.path });
+        }
+        catch (e) {
+            if (!swcFailed) {
+                parseErrors.push({
+                    file: f.path,
+                    reason: e instanceof Error ? e.message : "parser threw non-Error value",
+                });
+            }
+            continue;
+        }
+        const fatal = messages.find((m) => m.fatal === true);
+        if (fatal) {
+            if (!swcFailed) {
+                parseErrors.push({
+                    file: f.path,
+                    reason: fatal.message,
+                });
+            }
+            continue;
+        }
+        // Opportunity heuristic: count JSX elements that COULD have a11y issues.
+        // Counted only AFTER successful parse so the score's denominator reflects
+        // what was actually analyzed.
+        opportunities += (f.source.match(/<(img|a|label|button|input|select|textarea)\b/g) ?? []).length;
+        for (const m of messages) {
+            if (!m.ruleId || !A11Y_RULES.includes(m.ruleId))
+                continue;
+            findings.push({
+                ruleId: "a11y/essentials",
+                axis: "a11y",
+                severity: m.severity === 2 ? "error" : "warning",
+                location: { file: f.path, line: m.line ?? 0, column: m.column ?? 0 },
+                message: `[${m.ruleId}] ${m.message}`,
+            });
+        }
+    }
+    const result = { findings, opportunities };
+    if (parseErrors.length > 0)
+        result.parseErrors = parseErrors;
+    return result;
+};
+export const rule = createLyseRule({
+    meta: {
+        axis: "a11y",
+        lyseRuleId: "a11y/essentials",
+        defaultSeverity: "warning",
+        shortDescription: "Essential accessibility checks (jsx-a11y subset)",
+        fullDescription: "Wraps the canonical `eslint-plugin-jsx-a11y` rules: `alt-text`, `anchor-has-content`, `label-has-associated-control`, `role-has-required-aria-props`, `aria-role`. Surface-level accessibility failures that AI agents most frequently introduce.",
+        helpUri: "https://github.com/lyse-labs/lyse/blob/main/docs/rules/a11y-essentials.md",
+        rationale: `Why it matters
+
+Missing alt text, empty anchors, unlabeled inputs, and invalid ARIA are the most common a11y regressions in AI-generated UI. They block screen-reader users and violate WCAG 2.1 SC 1.1.1, 2.4.4, 1.3.1, 4.1.2.
+
+Lyse depends on the canonical \`eslint-plugin-jsx-a11y\` rather than re-porting these rules — the upstream impl is battle-tested across millions of repos.`,
+        examples: [
+            { good: '<img src="/logo.png" alt="Lyse logo" />', bad: '<img src="/logo.png" />' },
+            { good: "<label htmlFor=\"email\">Email</label><input id=\"email\" />", bad: "<label>Email</label><input />" },
+        ],
+        allowlist: ['jsx-a11y allowlists per-rule (e.g., decorative `alt=""` for purely-presentational images)'],
+    },
+    defaultOptions: [],
+    create: () => ({ evaluate }),
+});
+//# sourceMappingURL=a11y-essentials.js.map

package/dist/rules/a11y-essentials.js.map

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

package/dist/rules/ai-surface-agents-md-quality.d.ts

@@ -0,0 +1,22 @@
+import type { Rule } from "../types.js";
+interface FencedBlock {
+    firstLine: string;
+    startLine: number;
+}
+declare function extractFencedBlocks(content: string): FencedBlock[];
+declare function startsWithRunnable(commandLine: string): boolean;
+interface QualityChecks {
+    hasRunnableCodeBlock: boolean;
+    referencesExitCodes: boolean;
+    referencesToolchainConfig: boolean;
+}
+declare function evaluateQuality(content: string, presentConfigs: Set<string>): QualityChecks;
+export declare const rule: Rule;
+export declare const _internal: {
+    extractFencedBlocks: typeof extractFencedBlocks;
+    startsWithRunnable: typeof startsWithRunnable;
+    evaluateQuality: typeof evaluateQuality;
+    EXIT_CODE_PATTERN: RegExp;
+    RUNNABLE_PREFIXES: string[];
+};
+export {};

package/dist/rules/ai-surface-agents-md-quality.js

@@ -0,0 +1,233 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { createLyseRule } from "./_rule-module.js";
+const RULE_ID = "ai-surface/agents-md-quality";
+const MAX_FILE_BYTES = 500_000;
+const CANDIDATE_PATHS = [
+    "AGENTS.md",
+    ".github/AGENTS.md",
+    "docs/AGENTS.md",
+];
+const RUNNABLE_PREFIXES = [
+    "pnpm",
+    "npm",
+    "yarn",
+    "bun",
+    "python",
+    "python3",
+    "cargo",
+    "make",
+    "bash",
+    "sh",
+    "node",
+    "tsx",
+    "deno",
+    "npx",
+    "go",
+    "rake",
+    "uv",
+    "poetry",
+    "ruff",
+    "ruby",
+];
+const TOOLCHAIN_CONFIG_FILES = [
+    "package.json",
+    "tsconfig.json",
+    "pyproject.toml",
+    "Cargo.toml",
+    "Makefile",
+    ".lyse.yaml",
+    ".lyse.yml",
+    "lyse.config.ts",
+    "lyse.config.js",
+    "go.mod",
+    "Gemfile",
+    "pom.xml",
+    "build.gradle",
+    "deno.json",
+    "deno.jsonc",
+    "biome.json",
+    "eslint.config.js",
+    "vitest.config.ts",
+];
+const EXIT_CODE_PATTERN = /exit\s+code|exit code\s+\d+|exits?\s+(with\s+)?\d+|status\s+code|return code/i;
+function readMarkdownIfSmall(absPath) {
+    try {
+        const stat = statSync(absPath);
+        if (!stat.isFile())
+            return null;
+        if (stat.size > MAX_FILE_BYTES)
+            return null;
+        return readFileSync(absPath, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+function extractFencedBlocks(content) {
+    const blocks = [];
+    const lines = content.split("\n");
+    let inFence = false;
+    let fenceMarker = "";
+    let firstLine = "";
+    let startLine = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const trimmed = line.trimStart();
+        if (!inFence) {
+            const m = trimmed.match(/^(`{3,}|~{3,})/);
+            if (m) {
+                inFence = true;
+                fenceMarker = m[1] ?? "";
+                firstLine = "";
+                startLine = i + 1;
+            }
+        }
+        else {
+            if (trimmed.startsWith(fenceMarker)) {
+                if (firstLine !== "")
+                    blocks.push({ firstLine, startLine });
+                inFence = false;
+                fenceMarker = "";
+                firstLine = "";
+                continue;
+            }
+            if (firstLine === "" && line.trim().length > 0) {
+                firstLine = line.trim();
+            }
+        }
+    }
+    return blocks;
+}
+function startsWithRunnable(commandLine) {
+    const cleaned = commandLine.replace(/^[$#>]\s*/, "").trim();
+    if (cleaned.length === 0)
+        return false;
+    const firstToken = cleaned.split(/\s+/, 1)[0] ?? "";
+    if (RUNNABLE_PREFIXES.includes(firstToken))
+        return true;
+    // Allow path-prefixed binaries like ./scripts/run.sh
+    if (/^\.\/[\w./-]+$/.test(firstToken))
+        return true;
+    return false;
+}
+function evaluateQuality(content, presentConfigs) {
+    const blocks = extractFencedBlocks(content);
+    const hasRunnableCodeBlock = blocks.some((b) => startsWithRunnable(b.firstLine));
+    const referencesExitCodes = EXIT_CODE_PATTERN.test(content);
+    let referencesToolchainConfig = false;
+    for (const cfg of presentConfigs) {
+        if (content.includes(cfg)) {
+            referencesToolchainConfig = true;
+            break;
+        }
+    }
+    return { hasRunnableCodeBlock, referencesExitCodes, referencesToolchainConfig };
+}
+function discoverPresentConfigs(repoRoot) {
+    const found = new Set();
+    for (const cfg of TOOLCHAIN_CONFIG_FILES) {
+        if (existsSync(join(repoRoot, cfg)))
+            found.add(cfg);
+    }
+    return found;
+}
+const evaluate = async (ctx, _files) => {
+    const findings = [];
+    if (!ctx.repoRoot) {
+        return { findings, opportunities: 0 };
+    }
+    const presentConfigs = discoverPresentConfigs(ctx.repoRoot);
+    const foundFiles = [];
+    for (const candidate of CANDIDATE_PATHS) {
+        const abs = join(ctx.repoRoot, candidate);
+        const content = readMarkdownIfSmall(abs);
+        if (content !== null) {
+            foundFiles.push({ rel: relative(ctx.repoRoot, abs) || candidate, content });
+        }
+    }
+    if (foundFiles.length === 0) {
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "info",
+            location: { file: "AGENTS.md", line: 1, column: 1 },
+            message: "No AGENTS.md found — coding agents have no command-first instructions",
+            suggestion: "create AGENTS.md at repo root with command-first sections (runnable shell commands + expected exit codes)",
+        });
+        return { findings, opportunities: 1 };
+    }
+    let opportunities = 0;
+    for (const { rel, content } of foundFiles) {
+        opportunities += 3;
+        const quality = evaluateQuality(content, presentConfigs);
+        if (!quality.hasRunnableCodeBlock) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: rel, line: 1, column: 1 },
+                message: "AGENTS.md has no fenced code block starting with a runnable shell command (pnpm/npm/python/...)",
+                suggestion: "add a section with a fenced code block whose first line is a real command an agent can run",
+            });
+        }
+        if (!quality.referencesExitCodes) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: rel, line: 1, column: 1 },
+                message: "AGENTS.md does not reference exit codes — agents cannot verify command success programmatically",
+                suggestion: "document expected exit codes (e.g., `exit code 0 = clean`) for the commands you list",
+            });
+        }
+        if (!quality.referencesToolchainConfig) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: rel, line: 1, column: 1 },
+                message: "AGENTS.md does not mention any toolchain config file present in the repo (package.json, tsconfig.json, ...)",
+                suggestion: "reference the project's actual config files so agents know which toolchain is in scope",
+            });
+        }
+    }
+    return { findings, opportunities };
+};
+export const rule = createLyseRule({
+    meta: {
+        axis: "ai-surface",
+        lyseRuleId: RULE_ID,
+        defaultSeverity: "warning",
+        shortDescription: "AGENTS.md should be command-first and machine-actionable",
+        fullDescription: "Reads `AGENTS.md` at the repo root (with `.github/AGENTS.md` and `docs/AGENTS.md` fallbacks) and verifies three quality signals: (1) at least one fenced code block whose first line is a runnable shell command (pnpm/npm/yarn/bun/python/cargo/make/bash/sh/node/tsx/deno/...), (2) at least one mention of exit codes / status codes / return codes, (3) at least one reference to a toolchain config file the repo actually has (package.json, tsconfig.json, pyproject.toml, Makefile, .lyse.yaml, etc.). Each failing signal emits one warning; absence of AGENTS.md emits one info finding.",
+        helpUri: "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-agents-md-quality.md",
+        rationale: `Why it matters
+
+Coding agents (Claude Code, Cursor, Copilot Workspace, etc.) consume AGENTS.md as their bootstrap context. Research from the kodustech/agent-readiness study (Stream 2) shows that command-first AGENTS.md sections — containing runnable commands and explicit exit-code semantics — shift agent task success by 35–55%.
+
+Mere presence is not enough. A prose-only AGENTS.md that explains the project in English without listing a single \`pnpm test\` block leaves the agent guessing at the toolchain. Worse, per Gloaguen et al. (2026), long unstructured context files *reduce* task success and *increase* token cost by 20%.
+
+The rule enforces the cheapest, highest-leverage discipline: at least one runnable command, at least one explicit exit-code expectation, and at least one reference to the toolchain config the agent will encounter.`,
+        examples: [
+            {
+                good: "## Build\\n\\n\\`\\`\\`bash\\npnpm install && pnpm test\\n\\`\\`\\`\\n\\nExit code 0 means clean. Uses package.json.",
+                bad: "# Welcome\\n\\nThis repo is a TypeScript project. Please read the README before contributing.",
+            },
+        ],
+        allowlist: [
+            "files larger than 500 KB — skipped to avoid pathological cases",
+            "repos with no AGENTS.md anywhere — emit a single info finding, not a warning",
+        ],
+    },
+    defaultOptions: [],
+    create: () => ({ evaluate }),
+});
+export const _internal = {
+    extractFencedBlocks,
+    startsWithRunnable,
+    evaluateQuality,
+    EXIT_CODE_PATTERN,
+    RUNNABLE_PREFIXES,
+};
+//# sourceMappingURL=ai-surface-agents-md-quality.js.map

package/dist/rules/ai-surface-agents-md-quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-surface-agents-md-quality.js","sourceRoot":"","sources":["../../src/rules/ai-surface-agents-md-quality.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAQ3C,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,MAAM,OAAO,GAAG,8BAA8B,CAAC;AAC/C,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,eAAe,GAAG;IACtB,WAAW;IACX,mBAAmB;IACnB,gBAAgB;CACjB,CAAC;AAEF,MAAM,iBAAiB,GAAG;IACxB,MAAM;IACN,KAAK;IACL,MAAM;IACN,KAAK;IACL,QAAQ;IACR,SAAS;IACT,OAAO;IACP,MAAM;IACN,MAAM;IACN,IAAI;IACJ,MAAM;IACN,KAAK;IACL,MAAM;IACN,KAAK;IACL,IAAI;IACJ,MAAM;IACN,IAAI;IACJ,QAAQ;IACR,MAAM;IACN,MAAM;CACP,CAAC;AAEF,MAAM,sBAAsB,GAAG;IAC7B,cAAc;IACd,eAAe;IACf,gBAAgB;IAChB,YAAY;IACZ,UAAU;IACV,YAAY;IACZ,WAAW;IACX,gBAAgB;IAChB,gBAAgB;IAChB,QAAQ;IACR,SAAS;IACT,SAAS;IACT,cAAc;IACd,WAAW;IACX,YAAY;IACZ,YAAY;IACZ,kBAAkB;IAClB,kBAAkB;CACnB,CAAC;AAEF,MAAM,iBAAiB,GACrB,+EAA+E,CAAC;AAElF,SAAS,mBAAmB,CAAC,OAAe;IAC1C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,OAAO,IAAI,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,GAAG,cAAc;YAAE,OAAO,IAAI,CAAC;QAC5C,OAAO,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAOD,SAAS,mBAAmB,CAAC,OAAe;IAC1C,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;YAC1C,IAAI,CAAC,EAAE,CAAC;gBACN,OAAO,GAAG,IAAI,CAAC;gBACf,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBACzB,SAAS,GAAG,EAAE,CAAC;gBACf,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;aAAM,CAAC;YACN,IAAI,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;gBACpC,IAAI,SAAS,KAAK,EAAE;oBAAE,MAAM,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC5D,OAAO,GAAG,KAAK,CAAC;gBAChB,WAAW,GAAG,EAAE,CAAC;gBACjB,SAAS,GAAG,EAAE,CAAC;gBACf,SAAS;YACX,CAAC;YACD,IAAI,SAAS,KAAK,EAAE,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC/C,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,kBAAkB,CAAC,WAAmB;IAC7C,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpD,IAAI,iBAAiB,CAAC,QAAQ,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,qDAAqD;IACrD,IAAI,gBAAgB,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACnD,OAAO,KAAK,CAAC;AACf,CAAC;AAQD,SAAS,eAAe,CAAC,OAAe,EAAE,cAA2B;IACnE,MAAM,MAAM,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,oBAAoB,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACjF,MAAM,mBAAmB,GAAG,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5D,IAAI,yBAAyB,GAAG,KAAK,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;QACjC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC1B,yBAAyB,GAAG,IAAI,CAAC;YACjC,MAAM;QACR,CAAC;IACH,CAAC;IACD,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,CAAC;AAClF,CAAC;AAED,SAAS,sBAAsB,CAAC,QAAgB;IAC9C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,GAAG,IAAI,sBAAsB,EAAE,CAAC;QACzC,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YAAE,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,QAAQ,GAAG,KAAK,EACpB,GAAgB,EAChB,MAAmB,EACM,EAAE;IAC3B,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;QAClB,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;IACxC,CAAC;IAED,MAAM,cAAc,GAAG,sBAAsB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE5D,MAAM,UAAU,GAAuC,EAAE,CAAC;IAC1D,KAAK,MAAM,SAAS,IAAI,eAAe,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,UAAU,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;IAED,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,QAAQ,CAAC,IAAI,CAAC;YACZ,MAAM,EAAE,OAAO;YACf,IAAI,EAAE,YAAY;YAClB,QAAQ,EAAE,MAAM;YAChB,QAAQ,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YACnD,OAAO,EACL,uEAAuE;YACzE,UAAU,EACR,2GAA2G;SAC9G,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC;IACxC,CAAC;IAED,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,KAAK,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,UAAU,EAAE,CAAC;QAC1C,aAAa,IAAI,CAAC,CAAC;QACnB,MAAM,OAAO,GAAG,eAAe,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAClC,QAAQ,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,OAAO;gBACf,IAAI,EAAE,YAAY;gBAClB,QAAQ,EAAE,SAAS;gBACnB,QAAQ,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC3C,OAAO,EACL,iGAAiG;gBACnG,UAAU,EACR,4FAA4F;aAC/F,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,mBAAmB,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,OAAO;gBACf,IAAI,EAAE,YAAY;gBAClB,QAAQ,EAAE,SAAS;gBACnB,QAAQ,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC3C,OAAO,EACL,iGAAiG;gBACnG,UAAU,EACR,sFAAsF;aACzF,CAAC,CAAC;QACL,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,yBAAyB,EAAE,CAAC;YACvC,QAAQ,CAAC,IAAI,CAAC;gBACZ,MAAM,EAAE,OAAO;gBACf,IAAI,EAAE,YAAY;gBAClB,QAAQ,EAAE,SAAS;gBACnB,QAAQ,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC3C,OAAO,EACL,6GAA6G;gBAC/G,UAAU,EACR,wFAAwF;aAC3F,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,CAAC;AACrC,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,IAAI,GAAS,cAAc,CAAC;IACvC,IAAI,EAAE;QACJ,IAAI,EAAE,YAAY;QAClB,UAAU,EAAE,OAAO;QACnB,eAAe,EAAE,SAAS;QAC1B,gBAAgB,EAAE,0DAA0D;QAC5E,eAAe,EACb,okBAAokB;QACtkB,OAAO,EACL,wFAAwF;QAC1F,SAAS,EAAE;;;;;;sNAMuM;QAClN,QAAQ,EAAE;YACR;gBACE,IAAI,EAAE,sHAAsH;gBAC5H,GAAG,EAAE,+FAA+F;aACrG;SACF;QACD,SAAS,EAAE;YACT,gEAAgE;YAChE,8EAA8E;SAC/E;KACF;IACD,cAAc,EAAE,EAAE;IAClB,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC;CAC7B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,mBAAmB;IACnB,kBAAkB;IAClB,eAAe;IACf,iBAAiB;IACjB,iBAAiB;CAClB,CAAC"}

package/dist/rules/ai-surface-component-manifest-json.d.ts

@@ -0,0 +1,19 @@
+import type { Rule } from "../types.js";
+interface ValidationOutcome {
+    warnings: string[];
+    hasValidComponents: boolean;
+}
+declare function isShadcnComponentsJson(data: unknown): boolean;
+declare function validateEntry(entry: unknown): {
+    ok: boolean;
+    reason?: string;
+};
+declare function validateManifest(data: unknown): ValidationOutcome;
+export declare const rule: Rule;
+export declare const _internal: {
+    validateManifest: typeof validateManifest;
+    validateEntry: typeof validateEntry;
+    isShadcnComponentsJson: typeof isShadcnComponentsJson;
+    CANDIDATE_PATTERNS: string[];
+};
+export {};

package/dist/rules/ai-surface-component-manifest-json.js

@@ -0,0 +1,232 @@
+import { readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import fg from "fast-glob";
+import { isPathExcluded } from "./_exclude.js";
+import { createLyseRule } from "./_rule-module.js";
+const RULE_ID = "ai-surface/component-manifest-json";
+const MAX_FILE_BYTES = 2_000_000;
+const CANDIDATE_PATTERNS = [
+    "components.json",
+    "lyse.components.json",
+    "apps/*/components.json",
+    "apps/*/lyse.components.json",
+    "packages/*/components.json",
+    "packages/*/lyse.components.json",
+];
+function discoverManifests(ctx) {
+    if (!ctx.repoRoot)
+        return [];
+    let entries = [];
+    try {
+        entries = fg.sync(CANDIDATE_PATTERNS, {
+            cwd: ctx.repoRoot,
+            absolute: false,
+            dot: false,
+            ignore: ["**/node_modules/**", "**/dist/**", "**/build/**", "**/.git/**"],
+            followSymbolicLinks: false,
+        });
+    }
+    catch {
+        return [];
+    }
+    const out = new Set();
+    for (const rel of entries) {
+        if (isPathExcluded(rel, ctx.excludePaths))
+            continue;
+        out.add(rel);
+    }
+    return Array.from(out).sort();
+}
+function readJsonIfSmall(absPath) {
+    try {
+        const stat = statSync(absPath);
+        if (!stat.isFile())
+            return { data: null, parseError: null };
+        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 isShadcnComponentsJson(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const obj = data;
+    // shadcn/ui components.json has $schema or aliases, not a `components` list
+    if (typeof obj.$schema === "string" && obj.$schema.includes("shadcn"))
+        return true;
+    if (typeof obj.aliases === "object" && obj.aliases !== null && !("components" in obj))
+        return true;
+    return false;
+}
+function validateEntry(entry) {
+    if (typeof entry === "string") {
+        return entry.trim().length > 0 ? { ok: true } : { ok: false, reason: "empty string entry" };
+    }
+    if (typeof entry !== "object" || entry === null) {
+        return { ok: false, reason: "entry is not an object" };
+    }
+    const e = entry;
+    if (typeof e.name !== "string" || e.name.trim().length === 0) {
+        return { ok: false, reason: "entry missing `name`" };
+    }
+    const hasSource = (typeof e.sourceFile === "string" && e.sourceFile.trim().length > 0) ||
+        (typeof e.import === "string" && e.import.trim().length > 0);
+    if (!hasSource) {
+        return { ok: false, reason: `entry "${e.name}" missing \`sourceFile\` or \`import\`` };
+    }
+    return { ok: true };
+}
+function validateManifest(data) {
+    const warnings = [];
+    if (typeof data !== "object" || data === null) {
+        return { warnings: ["manifest root is not a JSON object"], hasValidComponents: false };
+    }
+    const shape = data;
+    if (!("components" in shape)) {
+        return { warnings: ["manifest has no `components` array or object"], hasValidComponents: false };
+    }
+    const components = shape.components;
+    if (Array.isArray(components)) {
+        if (components.length === 0) {
+            warnings.push("`components` array is empty");
+            return { warnings, hasValidComponents: false };
+        }
+        for (let i = 0; i < components.length; i++) {
+            const result = validateEntry(components[i]);
+            if (!result.ok)
+                warnings.push(`components[${i}]: ${result.reason ?? "invalid entry"}`);
+        }
+        return { warnings, hasValidComponents: warnings.length === 0 };
+    }
+    if (typeof components === "object" && components !== null) {
+        const entries = Object.entries(components);
+        if (entries.length === 0) {
+            warnings.push("`components` object is empty");
+            return { warnings, hasValidComponents: false };
+        }
+        for (const [name, entry] of entries) {
+            if (typeof entry === "object" && entry !== null) {
+                const e = entry;
+                const hasSource = (typeof e.sourceFile === "string" && e.sourceFile.trim().length > 0) ||
+                    (typeof e.import === "string" && e.import.trim().length > 0);
+                if (!hasSource)
+                    warnings.push(`components.${name} missing \`sourceFile\` or \`import\``);
+            }
+            else if (typeof entry !== "string" || entry.trim().length === 0) {
+                warnings.push(`components.${name} has invalid value`);
+            }
+        }
+        return { warnings, hasValidComponents: warnings.length === 0 };
+    }
+    return { warnings: ["`components` must be an array or object"], hasValidComponents: false };
+}
+const evaluate = async (ctx, _files) => {
+    const findings = [];
+    if (!ctx.repoRoot) {
+        return { findings, opportunities: 0 };
+    }
+    const relFiles = discoverManifests(ctx);
+    // Filter out shadcn-style components.json (config file, not a manifest).
+    const lyseStyle = [];
+    let shadcnDetected = false;
+    for (const rel of relFiles) {
+        const abs = join(ctx.repoRoot, rel);
+        const { data } = readJsonIfSmall(abs);
+        if (data !== null && isShadcnComponentsJson(data)) {
+            shadcnDetected = true;
+            continue;
+        }
+        lyseStyle.push(rel);
+    }
+    if (lyseStyle.length === 0) {
+        const suggestion = shadcnDetected
+            ? "found a shadcn/ui components.json but no lyse-style component manifest; add `lyse.components.json` listing { name, sourceFile } entries for MCP cost reduction"
+            : "create a `components.json` or `lyse.components.json` listing your components ({ name, sourceFile }) so MCP servers can serve component lookups at ~5× lower cost than reading source files";
+        findings.push({
+            ruleId: RULE_ID,
+            axis: "ai-surface",
+            severity: "info",
+            location: { file: "components.json", line: 1, column: 1 },
+            message: "No component manifest JSON found — MCP tools fall back to source-file reads",
+            suggestion,
+        });
+        return { findings, opportunities: 1 };
+    }
+    let opportunities = 0;
+    for (const rel of lyseStyle) {
+        opportunities += 1;
+        const abs = join(ctx.repoRoot, rel);
+        const { data, parseError } = readJsonIfSmall(abs);
+        const relPath = relative(ctx.repoRoot, abs) || rel;
+        if (data === null) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: `Component manifest is not valid JSON${parseError ? ` (${parseError})` : ""}`,
+                suggestion: "ensure the manifest is parseable JSON",
+            });
+            continue;
+        }
+        const outcome = validateManifest(data);
+        for (const warn of outcome.warnings) {
+            findings.push({
+                ruleId: RULE_ID,
+                axis: "ai-surface",
+                severity: "warning",
+                location: { file: relPath, line: 1, column: 1 },
+                message: warn,
+                suggestion: "each entry should be { name: string, sourceFile: string } (or { name, import } for shadcn-style)",
+            });
+        }
+    }
+    return { findings, opportunities };
+};
+export const rule = createLyseRule({
+    meta: {
+        axis: "ai-surface",
+        lyseRuleId: RULE_ID,
+        defaultSeverity: "info",
+        shortDescription: "Component manifest JSON for MCP cost reduction",
+        fullDescription: "Looks for a component manifest at the repo root (`components.json`, `lyse.components.json`) or in a monorepo (`apps/*/components.json`, `packages/*/components.json`). When found, validates the file is parseable JSON, has a top-level `components` array or object, and each entry has `{ name, sourceFile }` or `{ name, import }`. Absence emits an info finding; malformed manifests emit warnings. shadcn/ui-style `components.json` (the CLI config file, not a manifest) is detected and not counted as a lyse manifest.",
+        helpUri: "https://github.com/lyse-labs/lyse/blob/main/docs/rules/ai-surface-component-manifest-json.md",
+        rationale: `Why it matters
+
+The Indeed MCP cost study (Stream 1) and the broader manifest-pattern literature (Stream 2) show that a static component manifest reduces MCP tool cost by ~5× compared to reading the underlying source files at lookup time. Agents calling \`lyse_components\` or equivalent get a deterministic, low-token list of components instead of paging through tsx files.
+
+The manifest is also the source of truth for component discovery in code-connect and MCP-driven design-to-code workflows — without it, tools must heuristically scan exports or rely on conventions that break across monorepos.
+
+Severity is intentionally informational for absence (the absence is a missed optimisation, not a bug). Malformed manifests are warnings because they will silently break consumers.`,
+        examples: [
+            {
+                good: '{ "components": [ { "name": "Button", "sourceFile": "packages/ui/src/button.tsx" } ] }',
+                bad: '{ "stuff": [] }',
+            },
+            {
+                good: '{ "components": { "Button": { "import": "@acme/ui" } } }',
+                bad: '{ "components": [ { "sourceFile": "x.tsx" } ] }',
+            },
+        ],
+        allowlist: [
+            "shadcn/ui `components.json` (the CLI config file) — detected via `$schema` or `aliases` and skipped",
+            "files larger than 2 MB — skipped to avoid pathological cases",
+            "files matching `ctx.excludePaths` config",
+        ],
+    },
+    defaultOptions: [],
+    create: () => ({ evaluate }),
+});
+export const _internal = {
+    validateManifest,
+    validateEntry,
+    isShadcnComponentsJson,
+    CANDIDATE_PATTERNS,
+};
+//# sourceMappingURL=ai-surface-component-manifest-json.js.map