@schemyx/mcp 0.1.0 → 0.1.1

package/dist/codebase-scanner/recipes.d.ts

@@ -0,0 +1,74 @@
+import type { CodebaseBundle, CodebaseManifest, Confidence, ContextDepth, GraphEdge, PatternDecision, PatternScores, RecipeGroup, RecipeRecord, RecipeStatus, RegistryEntry, ReviewItem, SearchMatch } from './types';
+export declare function toRecipeRecord(entry: RegistryEntry): RecipeRecord;
+export declare function groupRecipes(recipes: RecipeRecord[]): Map<RecipeGroup, RecipeRecord[]>;
+export declare function toManifest(bundle: CodebaseBundle): CodebaseManifest;
+export declare function toGroupsIndex(recipesByGroup: Map<RecipeGroup, RecipeRecord[]>): {
+    v: string;
+    groups: {
+        [k: string]: {
+            count: number;
+            recipeFile: string;
+        };
+    };
+};
+export declare function toAliasesIndex(recipes: RecipeRecord[]): {
+    v: string;
+    aliases: Record<string, string[]>;
+};
+export declare function toTermsIndex(recipes: RecipeRecord[]): {
+    v: string;
+    terms: Record<string, string[]>;
+};
+export declare function recipeAliases(recipe: RecipeRecord): string[];
+export declare function recipeTerms(recipe: RecipeRecord): string[];
+export declare function readJsonLines<T>(filePath: string): Promise<T[]>;
+export declare function readAllRecipes(outputDir: string): Promise<RecipeRecord[]>;
+export declare function scoreRecipe(recipe: RecipeRecord, exactKey: string | undefined, terms: string[]): number;
+export declare function toSearchMatch(recipe: RecipeRecord, score: number): SearchMatch;
+export declare function readPatternScores(value: unknown): PatternScores | undefined;
+export declare function readPatternDecision(value: unknown): PatternDecision | undefined;
+export declare function numberScoreField(value: unknown): number | undefined;
+export declare function unitScoreField(value: unknown): number | undefined;
+export declare function resolveSearchStatus(matches: SearchMatch[], exactKeyLookup: boolean, reviewItems: ReviewItem[]): {
+    status: string;
+    resolvedKey?: string;
+    confidence: Confidence | 'none';
+    why: string[];
+    reviewItem?: string;
+};
+export declare function statusWeight(status: RecipeStatus): number;
+export declare function confidenceWeight(confidence: Confidence): number;
+export declare function normalizeDepth(value: unknown): ContextDepth;
+export declare function toRelatedRecipe(recipe: RecipeRecord): {
+    k: string;
+    s: string;
+    p: string | undefined;
+    status: RecipeStatus;
+    confidence: Confidence;
+};
+export declare function addPackRecipe(selected: Map<string, {
+    recipe: RecipeRecord;
+    why: string;
+}>, recipe: RecipeRecord, why: string): void;
+export declare function trimRecipeForDepth(recipe: RecipeRecord, depth: ContextDepth): RecipeRecord | {
+    k: string;
+    g: "file" | "component" | "hook" | "route" | "api" | "controller" | "service" | "module" | "model" | "style" | "dependency" | "cluster" | "rule";
+    s: string;
+    d: string[];
+    u: string[];
+    p: string | undefined;
+    status: RecipeStatus;
+    confidence: Confidence;
+    v: Record<string, unknown>;
+} | {
+    k: string;
+    g: "file" | "component" | "hook" | "route" | "api" | "controller" | "service" | "module" | "model" | "style" | "dependency" | "cluster" | "rule";
+    s: string;
+    p: string | undefined;
+    status: RecipeStatus;
+    confidence: Confidence;
+    d?: undefined;
+    u?: undefined;
+    v?: undefined;
+};
+export declare function collectGraphNeighborhood(key: string, edges: GraphEdge[], direction: string, radius: number): Set<string>;

package/dist/codebase-scanner/recipes.js

@@ -0,0 +1,585 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toRecipeRecord = toRecipeRecord;
+exports.groupRecipes = groupRecipes;
+exports.toManifest = toManifest;
+exports.toGroupsIndex = toGroupsIndex;
+exports.toAliasesIndex = toAliasesIndex;
+exports.toTermsIndex = toTermsIndex;
+exports.recipeAliases = recipeAliases;
+exports.recipeTerms = recipeTerms;
+exports.readJsonLines = readJsonLines;
+exports.readAllRecipes = readAllRecipes;
+exports.scoreRecipe = scoreRecipe;
+exports.toSearchMatch = toSearchMatch;
+exports.readPatternScores = readPatternScores;
+exports.readPatternDecision = readPatternDecision;
+exports.numberScoreField = numberScoreField;
+exports.unitScoreField = unitScoreField;
+exports.resolveSearchStatus = resolveSearchStatus;
+exports.statusWeight = statusWeight;
+exports.confidenceWeight = confidenceWeight;
+exports.normalizeDepth = normalizeDepth;
+exports.toRelatedRecipe = toRelatedRecipe;
+exports.addPackRecipe = addPackRecipe;
+exports.trimRecipeForDepth = trimRecipeForDepth;
+exports.collectGraphNeighborhood = collectGraphNeighborhood;
+const node_fs_1 = require("node:fs");
+const path = require("node:path");
+const constants_1 = require("./constants");
+const utils_1 = require("./utils");
+function toRecipeRecord(entry) {
+    return {
+        k: entry.key,
+        g: entry.group,
+        d: entry.dependencies,
+        u: entry.usedBy,
+        s: entry.summary,
+        t: entry.tags,
+        ...(entry.path ? { p: entry.path } : {}),
+        confidence: entry.confidence,
+        status: entry.status,
+        v: entry.value,
+    };
+}
+function groupRecipes(recipes) {
+    const grouped = new Map();
+    for (const group of constants_1.recipeGroups) {
+        grouped.set(group, []);
+    }
+    for (const recipe of recipes) {
+        grouped.get(recipe.g)?.push(recipe);
+    }
+    return grouped;
+}
+function toManifest(bundle) {
+    return {
+        v: constants_1.bundleSchemaVersion,
+        scanId: bundle.scanId,
+        rootName: path.basename(bundle.rootPath),
+        projectType: bundle.projectType,
+        generatedAt: bundle.generatedAt,
+        localOnly: true,
+        schema: {
+            graph: constants_1.graphSchemaVersion,
+            index: constants_1.indexSchemaVersion,
+            recipe: constants_1.recipeSchemaVersion,
+        },
+        extractors: [
+            { id: 'core.files', version: '1.0.0' },
+            { id: 'typescript', version: '1.0.0' },
+            { id: 'react', version: '1.0.0' },
+            { id: 'nextjs.app-router', version: '1.0.0' },
+            { id: 'nestjs', version: '1.0.0' },
+            { id: 'prisma', version: '1.0.0' },
+            { id: 'styles', version: '1.1.0' },
+            { id: 'css.rules', version: '1.0.0' },
+            { id: 'theme.tokens', version: '1.0.0' },
+            { id: 'class.expressions', version: '1.0.0' },
+            { id: 'component-style-definitions', version: '1.0.0' },
+            { id: 'web.templates', version: '1.0.0' },
+            { id: 'php-web', version: '1.0.0' },
+            { id: 'python-web', version: '1.0.0' },
+            { id: 'ruby-web', version: '1.0.0' },
+            { id: 'sql', version: '1.0.0' },
+            { id: 'ui.patterns', version: '1.2.0' },
+            { id: 'ui.composition', version: '1.0.0' },
+            { id: 'connected.patterns', version: '1.0.0' },
+            { id: 'concept.cluster', version: '1.0.0' },
+            { id: 'dataflow.model-reference', version: '1.0.0' },
+        ],
+        stats: {
+            files: bundle.files.length,
+            nodes: bundle.nodes.length,
+            edges: bundle.edges.length,
+            recipes: bundle.entries.length,
+            reviewItems: bundle.reviewItems.length,
+        },
+        paths: {
+            nodes: 'graph/nodes.jsonl',
+            edges: 'graph/edges.jsonl',
+            groups: 'index/groups.json',
+            aliases: 'index/aliases.json',
+            terms: 'index/terms.json',
+            review: 'review/items.json',
+        },
+    };
+}
+function toGroupsIndex(recipesByGroup) {
+    return {
+        v: constants_1.indexSchemaVersion,
+        groups: Object.fromEntries(constants_1.recipeGroups.map((group) => [
+            group,
+            {
+                count: recipesByGroup.get(group)?.length ?? 0,
+                recipeFile: `recipes/${group}.jsonl`,
+            },
+        ])),
+    };
+}
+function toAliasesIndex(recipes) {
+    const aliases = Object.create(null);
+    for (const recipe of recipes) {
+        for (const alias of recipeAliases(recipe)) {
+            const existing = Object.prototype.hasOwnProperty.call(aliases, alias) ? aliases[alias] : [];
+            aliases[alias] = (0, utils_1.unique)([...existing, recipe.k]).sort();
+        }
+    }
+    return {
+        v: constants_1.indexSchemaVersion,
+        aliases,
+    };
+}
+function toTermsIndex(recipes) {
+    const terms = Object.create(null);
+    for (const recipe of recipes) {
+        for (const term of recipeTerms(recipe)) {
+            const existing = Object.prototype.hasOwnProperty.call(terms, term) ? terms[term] : [];
+            terms[term] = (0, utils_1.unique)([...existing, recipe.k]).sort();
+        }
+    }
+    return {
+        v: constants_1.indexSchemaVersion,
+        terms,
+    };
+}
+function recipeAliases(recipe) {
+    return (0, utils_1.unique)([
+        recipe.k,
+        recipe.k.toLowerCase(),
+        typeof recipe.v.name === 'string' ? recipe.v.name : '',
+        typeof recipe.v.route === 'string' ? recipe.v.route : '',
+        typeof recipe.v.handler === 'string' ? recipe.v.handler : '',
+        ...recipe.t,
+    ])
+        .map((item) => item.toLowerCase())
+        .filter(Boolean);
+}
+function recipeTerms(recipe) {
+    return (0, utils_1.unique)([recipe.k, recipe.g, recipe.s, ...recipe.t, JSON.stringify(recipe.v)]
+        .join(' ')
+        .toLowerCase()
+        .split(/[^a-z0-9_-]+/)
+        .filter((term) => term.length > 1)).slice(0, 80);
+}
+async function readJsonLines(filePath) {
+    try {
+        const content = await node_fs_1.promises.readFile(filePath, 'utf8');
+        return content
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+async function readAllRecipes(outputDir) {
+    const grouped = await Promise.all(constants_1.recipeGroups.map((group) => readJsonLines(path.join(outputDir, 'recipes', `${group}.jsonl`))));
+    return grouped.flat();
+}
+function scoreRecipe(recipe, exactKey, terms) {
+    if (exactKey && recipe.k === exactKey) {
+        return 100;
+    }
+    if (!terms.length) {
+        return statusWeight(recipe.status) + confidenceWeight(recipe.confidence);
+    }
+    const serializedValue = JSON.stringify(recipe.v).toLowerCase();
+    const haystack = [
+        recipe.k,
+        recipe.g,
+        recipe.s,
+        ...recipe.t,
+        ...recipe.d,
+        ...recipe.u,
+        String(recipe.v.name ?? ''),
+        String(recipe.v.path ?? ''),
+        String(recipe.v.route ?? ''),
+        String(recipe.v.handler ?? ''),
+        serializedValue.slice(0, 8000),
+    ]
+        .join(' ')
+        .toLowerCase();
+    let score = statusWeight(recipe.status) + confidenceWeight(recipe.confidence);
+    const ruleType = String(recipe.v.ruleType ?? '');
+    const patternScores = readPatternScores(recipe.v.scores);
+    const patternDecision = readPatternDecision(recipe.v.decision);
+    const wantsUiComposition = terms.some((term) => [
+        'ui',
+        'layout',
+        'layouts',
+        'page',
+        'homepage',
+        'home',
+        'hero',
+        'section',
+        'sections',
+        'card',
+        'cards',
+        'surface',
+        'surfaces',
+        'background',
+        'backgrounds',
+        'padding',
+        'spacing',
+        'responsive',
+        'mobile',
+        'desktop',
+        'heading',
+        'headings',
+        'typography',
+    ].includes(term));
+    if (recipe.g === 'cluster') {
+        score += wantsUiComposition ? 4 : 18;
+        if (patternScores) {
+            score += patternScores.canonical * 8;
+            score -= patternScores.oneOffRisk * 5;
+        }
+        if (patternDecision?.reuse === 'prefer') {
+            score += 5;
+        }
+        else if (patternDecision?.reuse === 'review') {
+            score -= 4;
+        }
+        else if (patternDecision?.reuse === 'avoid') {
+            score -= 10;
+        }
+    }
+    if (ruleType === 'ui-composition') {
+        score += wantsUiComposition ? 36 : 14;
+    }
+    if (ruleType === 'ui-pattern') {
+        score += wantsUiComposition ? 16 : 6;
+    }
+    if (ruleType === 'connected-pattern') {
+        const domain = String(recipe.v.domain ?? '');
+        const concept = String(recipe.v.concept ?? '');
+        const usageCount = typeof recipe.v.usageCount === 'number' ? recipe.v.usageCount : 0;
+        const canonical = recipe.v.canonical === true;
+        const wantsStyleContract = terms.some((term) => ['style', 'styles', 'styling', 'variant', 'variants', 'primary', 'secondary'].includes(term));
+        const wantsConnectedPattern = terms.some((term) => [
+            'connected',
+            'pattern',
+            'patterns',
+            'canonical',
+            'structure',
+            'composition',
+            'flow',
+            'flows',
+            'graph',
+            'children',
+            'hierarchy',
+        ].includes(term));
+        const wantsBackendPattern = terms.some((term) => [
+            'api',
+            'route',
+            'routes',
+            'controller',
+            'service',
+            'database',
+            'model',
+            'prisma',
+            'backend',
+            'flow',
+            'flows',
+        ].includes(term));
+        if (wantsStyleContract && !wantsConnectedPattern) {
+            score -= 22;
+        }
+        else if ((domain === 'frontend' && wantsUiComposition) ||
+            (domain !== 'frontend' && wantsBackendPattern)) {
+            score += 34;
+        }
+        else {
+            score += 16;
+        }
+        if (canonical && (!wantsStyleContract || wantsConnectedPattern)) {
+            score += 10;
+        }
+        if (patternScores && (!wantsStyleContract || wantsConnectedPattern)) {
+            score += patternScores.canonical * 14;
+            score -= patternScores.oneOffRisk * 10;
+        }
+        if (!wantsStyleContract || wantsConnectedPattern) {
+            if (patternDecision?.reuse === 'prefer') {
+                score += 8;
+            }
+            else if (patternDecision?.reuse === 'review') {
+                score -= 6;
+            }
+            else if (patternDecision?.reuse === 'avoid') {
+                score -= 14;
+            }
+        }
+        if (!wantsStyleContract || wantsConnectedPattern) {
+            const conceptTerms = concept.split(/[-_.]+/).filter(Boolean);
+            const conceptHits = conceptTerms.filter((term) => terms.includes(term) || terms.includes(`${term}s`)).length;
+            if (terms.includes(concept) || terms.includes(`${concept}s`)) {
+                score += 16;
+            }
+            score += conceptHits * 10;
+            for (const specificTerm of ['api', 'route', 'controller', 'service', 'model', 'data']) {
+                const termRequested = terms.includes(specificTerm);
+                const conceptMatchesTerm = conceptTerms.includes(specificTerm) || (specificTerm === 'data' && domain === 'data');
+                if (!termRequested) {
+                    continue;
+                }
+                if (conceptMatchesTerm) {
+                    score += 16;
+                }
+                else {
+                    score -= 24;
+                }
+            }
+        }
+        if (!wantsStyleContract || wantsConnectedPattern) {
+            score += Math.min(usageCount, 12);
+        }
+    }
+    const locatorHaystack = [
+        recipe.k,
+        ...recipe.t,
+        String(recipe.v.name ?? ''),
+        String(recipe.v.path ?? ''),
+    ]
+        .join(' ')
+        .toLowerCase();
+    const wantsHero = terms.includes('hero') || terms.includes('headline');
+    const wantsHomepage = terms.includes('homepage') || terms.includes('home') || terms.includes('landing');
+    if (wantsHero && locatorHaystack.includes('hero')) {
+        score += 30;
+    }
+    if (wantsHomepage &&
+        ruleType === 'ui-composition' &&
+        (locatorHaystack.includes('hero-section') ||
+            locatorHaystack.includes('components.sections') ||
+            locatorHaystack.includes('route.root') ||
+            locatorHaystack.includes('app.page'))) {
+        score += 16;
+    }
+    if (String(recipe.v.kind ?? '') === 'component-style-definition') {
+        score += terms.some((term) => ['style', 'styles', 'styling', 'variant', 'variants', 'primary', 'secondary'].includes(term))
+            ? 28
+            : 12;
+    }
+    for (const term of terms) {
+        if (recipe.k.toLowerCase() === term) {
+            score += 20;
+        }
+        else if (recipe.k.toLowerCase().includes(term)) {
+            score += 10;
+        }
+        if (recipe.t.some((tag) => tag.toLowerCase() === term)) {
+            score += 8;
+        }
+        else if (haystack.includes(term)) {
+            score += 3;
+        }
+    }
+    return score;
+}
+function toSearchMatch(recipe, score) {
+    const scores = readPatternScores(recipe.v.scores);
+    const decision = readPatternDecision(recipe.v.decision);
+    return {
+        k: recipe.k,
+        g: recipe.g,
+        kind: String(recipe.v.kind ?? recipe.g),
+        name: typeof recipe.v.name === 'string' ? recipe.v.name : undefined,
+        s: recipe.s,
+        t: recipe.t,
+        d: recipe.d,
+        u: recipe.u,
+        p: recipe.p ?? (typeof recipe.v.path === 'string' ? recipe.v.path : null),
+        confidence: recipe.confidence,
+        status: recipe.status,
+        score: Number(score.toFixed(2)),
+        ...(scores ? { scores } : {}),
+        ...(decision ? { decision } : {}),
+    };
+}
+function readPatternScores(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const record = value;
+    const appearances = numberScoreField(record.appearances);
+    const files = numberScoreField(record.files);
+    const routes = numberScoreField(record.routes);
+    const structuralSimilarity = unitScoreField(record.structuralSimilarity);
+    const styleSimilarity = unitScoreField(record.styleSimilarity);
+    const behaviorSimilarity = unitScoreField(record.behaviorSimilarity);
+    const canonical = unitScoreField(record.canonical);
+    const oneOffRisk = unitScoreField(record.oneOffRisk);
+    if (appearances === undefined ||
+        files === undefined ||
+        routes === undefined ||
+        structuralSimilarity === undefined ||
+        styleSimilarity === undefined ||
+        behaviorSimilarity === undefined ||
+        canonical === undefined ||
+        oneOffRisk === undefined) {
+        return undefined;
+    }
+    return {
+        appearances,
+        files,
+        routes,
+        owners: (0, utils_1.stringArrayValue)(record.owners).slice(0, 12),
+        structuralSimilarity,
+        styleSimilarity,
+        behaviorSimilarity,
+        canonical,
+        oneOffRisk,
+    };
+}
+function readPatternDecision(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const record = value;
+    const reuse = record.reuse;
+    const scope = record.scope;
+    const reason = record.reason;
+    if (reuse !== 'prefer' && reuse !== 'allow' && reuse !== 'avoid' && reuse !== 'review') {
+        return undefined;
+    }
+    if (typeof scope !== 'string' || typeof reason !== 'string') {
+        return undefined;
+    }
+    return { reuse, scope, reason };
+}
+function numberScoreField(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function unitScoreField(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? (0, utils_1.clampPatternScore)(value) : undefined;
+}
+function resolveSearchStatus(matches, exactKeyLookup, reviewItems) {
+    if (!matches.length) {
+        return { status: 'not_found', confidence: 'none', why: [] };
+    }
+    const first = matches[0];
+    const reviewItem = reviewItems.find((item) => item.status === 'open' && item.candidates.includes(first.k));
+    const isHighConfidenceStyleContract = first.g === 'style' &&
+        first.kind === 'component-style-definition' &&
+        first.confidence === 'high';
+    if (!isHighConfidenceStyleContract && (first.status === 'needs_review' || reviewItem)) {
+        return {
+            status: 'needs_review',
+            confidence: first.confidence,
+            why: ['unresolved-review-item'],
+            reviewItem: reviewItem?.id,
+        };
+    }
+    if (exactKeyLookup || matches.length === 1 || first.status === 'approved' || first.score >= 12) {
+        return {
+            status: 'resolved',
+            resolvedKey: first.k,
+            confidence: first.confidence,
+            why: exactKeyLookup ? ['exact-key'] : ['best-ranked-match'],
+        };
+    }
+    return { status: 'candidates', confidence: first.confidence, why: ['multiple-candidates'] };
+}
+function statusWeight(status) {
+    switch (status) {
+        case 'approved':
+            return 20;
+        case 'inferred':
+            return 8;
+        case 'needs_review':
+            return 4;
+        case 'stale':
+            return 1;
+    }
+}
+function confidenceWeight(confidence) {
+    switch (confidence) {
+        case 'high':
+            return 6;
+        case 'medium':
+            return 4;
+        case 'low':
+            return 2;
+        case 'inferred':
+            return 1;
+    }
+}
+function normalizeDepth(value) {
+    const depth = (0, utils_1.stringArg)(value);
+    return depth === 'standard' || depth === 'deep' ? depth : 'brief';
+}
+function toRelatedRecipe(recipe) {
+    return {
+        k: recipe.k,
+        s: recipe.s,
+        p: recipe.p ?? (typeof recipe.v.path === 'string' ? recipe.v.path : undefined),
+        status: recipe.status,
+        confidence: recipe.confidence,
+    };
+}
+function addPackRecipe(selected, recipe, why) {
+    if (!selected.has(recipe.k)) {
+        selected.set(recipe.k, { recipe, why });
+    }
+}
+function trimRecipeForDepth(recipe, depth) {
+    if (depth === 'deep') {
+        return recipe;
+    }
+    if (depth === 'standard') {
+        return {
+            k: recipe.k,
+            g: recipe.g,
+            s: recipe.s,
+            d: recipe.d,
+            u: recipe.u.slice(0, 10),
+            p: recipe.p,
+            status: recipe.status,
+            confidence: recipe.confidence,
+            v: recipe.v,
+        };
+    }
+    return {
+        k: recipe.k,
+        g: recipe.g,
+        s: recipe.s,
+        p: recipe.p,
+        status: recipe.status,
+        confidence: recipe.confidence,
+    };
+}
+function collectGraphNeighborhood(key, edges, direction, radius) {
+    const selected = new Set([key]);
+    let frontier = new Set([key]);
+    for (let depth = 0; depth < radius; depth += 1) {
+        const next = new Set();
+        for (const edge of edges) {
+            for (const nodeKey of frontier) {
+                const outbound = edge.from === nodeKey && (direction === 'out' || direction === 'both');
+                const inbound = edge.to === nodeKey && (direction === 'in' || direction === 'both');
+                if (outbound && !selected.has(edge.to)) {
+                    next.add(edge.to);
+                }
+                if (inbound && !selected.has(edge.from)) {
+                    next.add(edge.from);
+                }
+            }
+        }
+        for (const item of next) {
+            selected.add(item);
+        }
+        frontier = next;
+        if (!frontier.size) {
+            break;
+        }
+    }
+    return selected;
+}
+//# sourceMappingURL=recipes.js.map