@pithyjs/mcp 0.0.0-stage → 0.1.0-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +123 -2
- package/dist/cli.d.ts +3 -0
- package/dist/cli.js +74 -0
- package/dist/errors/catalog.d.ts +48 -0
- package/dist/errors/catalog.js +252 -0
- package/dist/guard.d.ts +41 -0
- package/dist/guard.js +140 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.js +4 -0
- package/dist/knowledge.d.ts +157 -0
- package/dist/knowledge.js +163 -0
- package/dist/lookup.d.ts +47 -0
- package/dist/lookup.js +69 -0
- package/dist/pidl.d.ts +27 -0
- package/dist/pidl.js +251 -0
- package/dist/scaffold.d.ts +54 -0
- package/dist/scaffold.js +280 -0
- package/dist/search.d.ts +37 -0
- package/dist/search.js +129 -0
- package/dist/server.d.ts +25 -0
- package/dist/server.js +126 -0
- package/dist/snapshot.json +1 -0
- package/dist/template.d.ts +26 -0
- package/dist/template.js +66 -0
- package/dist/tokens.d.ts +71 -0
- package/dist/tokens.js +420 -0
- package/package.json +56 -3
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.template", "title": "MCP Template Check", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import type { TemplateFinding } from '@pithyjs/vite-plugin';
|
|
3
|
+
/** @codexApi {"parent":"pithy.mcp.template","name":"TemplateCheck","stability":"experimental","signature":"interface TemplateCheck { filename: string; checked: boolean; ok: boolean; findings: TemplateFinding[]; error?: string; note?: string }"} */
|
|
4
|
+
/**
|
|
5
|
+
* `checked` is false when the file type is one the plugin never reads.
|
|
6
|
+
* `ok` is true only for a checked module with no findings and no error.
|
|
7
|
+
*/
|
|
8
|
+
export interface TemplateCheck {
|
|
9
|
+
filename: string;
|
|
10
|
+
checked: boolean;
|
|
11
|
+
ok: boolean;
|
|
12
|
+
findings: TemplateFinding[];
|
|
13
|
+
error?: string;
|
|
14
|
+
/** For a `.pithy` file: what the check cannot see there. */
|
|
15
|
+
note?: string;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* Runs the Vite plugin's component-attribute check on one module, with
|
|
19
|
+
* ui-kit's `componentScopes`, as the dev server and build would.
|
|
20
|
+
*
|
|
21
|
+
* @param code - A `.ts` module with `html` templates, or a `.pithy` file.
|
|
22
|
+
* @param filename - The module's path; a `?query` is dropped. Default `component.ts`.
|
|
23
|
+
* @returns The findings, or the parse error the build would raise.
|
|
24
|
+
*/
|
|
25
|
+
/** @codexApi {"parent":"pithy.mcp.template","name":"checkTemplate","stability":"experimental","signature":"(code: string, filename?: string) => Promise<TemplateCheck>"} */
|
|
26
|
+
export declare function checkTemplate(code: string, filename?: string): Promise<TemplateCheck>;
|
package/dist/template.js
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.template", "title": "MCP Template Check", "category": "feature", "risk": "medium" } */
|
|
2
|
+
const PITHY_NOTE = 'In a .pithy file the plugin cannot see which names the template binds (...props), so it flags only an attribute value that does not parse; a bare word such as as="strong" passes here but is still read as JavaScript, not a string.';
|
|
3
|
+
let loaded;
|
|
4
|
+
// Both load vite and Babel, so only on the first check, never at startup.
|
|
5
|
+
const load = () => (loaded ??= Promise.all([
|
|
6
|
+
import('@pithyjs/vite-plugin'),
|
|
7
|
+
import('@pithyjs/ui-kit/compiler'),
|
|
8
|
+
]).then(([plugin, kit]) => ({
|
|
9
|
+
validate: plugin.validateTemplate,
|
|
10
|
+
scopes: kit.componentScopes,
|
|
11
|
+
})));
|
|
12
|
+
/**
|
|
13
|
+
* Runs the Vite plugin's component-attribute check on one module, with
|
|
14
|
+
* ui-kit's `componentScopes`, as the dev server and build would.
|
|
15
|
+
*
|
|
16
|
+
* @param code - A `.ts` module with `html` templates, or a `.pithy` file.
|
|
17
|
+
* @param filename - The module's path; a `?query` is dropped. Default `component.ts`.
|
|
18
|
+
* @returns The findings, or the parse error the build would raise.
|
|
19
|
+
*/
|
|
20
|
+
/** @codexApi {"parent":"pithy.mcp.template","name":"checkTemplate","stability":"experimental","signature":"(code: string, filename?: string) => Promise<TemplateCheck>"} */
|
|
21
|
+
export async function checkTemplate(code, filename = 'component.ts') {
|
|
22
|
+
const file = filename.split(/[?#]/, 1)[0] || 'component.ts';
|
|
23
|
+
if (!file.endsWith('.ts') && !file.endsWith('.pithy')) {
|
|
24
|
+
return {
|
|
25
|
+
filename: file,
|
|
26
|
+
checked: false,
|
|
27
|
+
ok: false,
|
|
28
|
+
findings: [],
|
|
29
|
+
error: 'Only .ts and .pithy modules are checked; the Vite plugin reads no others.',
|
|
30
|
+
};
|
|
31
|
+
}
|
|
32
|
+
let checker;
|
|
33
|
+
try {
|
|
34
|
+
checker = await load();
|
|
35
|
+
}
|
|
36
|
+
catch (e) {
|
|
37
|
+
loaded = undefined;
|
|
38
|
+
const error = `Could not load @pithyjs/vite-plugin: ${e.message}`;
|
|
39
|
+
return { filename: file, checked: false, ok: false, findings: [], error };
|
|
40
|
+
}
|
|
41
|
+
const { validate, scopes } = checker;
|
|
42
|
+
try {
|
|
43
|
+
const findings = await validate(code, {
|
|
44
|
+
filename: file,
|
|
45
|
+
componentScopes: scopes,
|
|
46
|
+
// The caller's path must not pick which tsconfig.json is read.
|
|
47
|
+
tsconfigRaw: '{}',
|
|
48
|
+
});
|
|
49
|
+
return {
|
|
50
|
+
filename: file,
|
|
51
|
+
checked: true,
|
|
52
|
+
ok: findings.length === 0,
|
|
53
|
+
findings,
|
|
54
|
+
...(file.endsWith('.pithy') ? { note: PITHY_NOTE } : {}),
|
|
55
|
+
};
|
|
56
|
+
}
|
|
57
|
+
catch (e) {
|
|
58
|
+
return {
|
|
59
|
+
filename: file,
|
|
60
|
+
checked: true,
|
|
61
|
+
ok: false,
|
|
62
|
+
findings: [],
|
|
63
|
+
error: e.message,
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
}
|
package/dist/tokens.d.ts
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.tokens", "title": "MCP Design Token Tools", "category": "feature", "risk": "medium" } */
|
|
2
|
+
import type { Citation, Knowledge } from './knowledge.js';
|
|
3
|
+
/**
|
|
4
|
+
* The closest known token in the same family: an attested rename first, else
|
|
5
|
+
* the longest shared prefix, then the smallest edit distance, then the shorter.
|
|
6
|
+
*
|
|
7
|
+
* @param token - An unknown `--name`.
|
|
8
|
+
* @param known - Every token the design system emits.
|
|
9
|
+
* @returns A suggestion, or `null` when none is close enough.
|
|
10
|
+
*/
|
|
11
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"suggestToken","stability":"experimental","signature":"(token: string, known: ReadonlySet<string>) => string | null"} */
|
|
12
|
+
export declare function suggestToken(token: string, known: ReadonlySet<string>): string | null;
|
|
13
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"TokenIssue","stability":"experimental","signature":"interface TokenIssue"} */
|
|
14
|
+
/** One problem `check_tokens` found. */
|
|
15
|
+
export interface TokenIssue {
|
|
16
|
+
kind: 'unknown-token' | 'raw-color' | 'physical-property';
|
|
17
|
+
line: number;
|
|
18
|
+
message: string;
|
|
19
|
+
/** The custom property, for `unknown-token`. */
|
|
20
|
+
token?: string;
|
|
21
|
+
/** The declaration's property, for `physical-property`. */
|
|
22
|
+
property?: string;
|
|
23
|
+
/** The raw color, for `raw-color`. */
|
|
24
|
+
value?: string;
|
|
25
|
+
/** The replacement, when there is one. */
|
|
26
|
+
suggestion?: string | null;
|
|
27
|
+
}
|
|
28
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"TokenCheck","stability":"experimental","signature":"interface TokenCheck { ok: boolean; issues: TokenIssue[]; total: number; truncated: boolean }"} */
|
|
29
|
+
/** `ok` when there are no issues; `issues` lists the first 200 of `total`. */
|
|
30
|
+
export interface TokenCheck {
|
|
31
|
+
ok: boolean;
|
|
32
|
+
issues: TokenIssue[];
|
|
33
|
+
total: number;
|
|
34
|
+
truncated: boolean;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Checks CSS or SCSS against the design-system rules: every `var(--name)` in a
|
|
38
|
+
* token family must exist (with a did-you-mean), no value, custom prop, Sass
|
|
39
|
+
* variable or at-rule argument holds a raw color, and properties are logical.
|
|
40
|
+
* The token check skips `--_` private props, props the sheet defines itself,
|
|
41
|
+
* Sass interpolation and families outside the design system.
|
|
42
|
+
*
|
|
43
|
+
* @param css - The stylesheet.
|
|
44
|
+
* @param names - Every token the design system emits.
|
|
45
|
+
* @returns The issues, in source order.
|
|
46
|
+
*/
|
|
47
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"checkTokens","stability":"experimental","signature":"(css: string, names: readonly string[]) => TokenCheck"} */
|
|
48
|
+
export declare function checkTokens(css: string, names: readonly string[]): TokenCheck;
|
|
49
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"TokensResult","stability":"experimental","signature":"type TokensResult"} */
|
|
50
|
+
/** Token names with their citation, or the families when `category` is unknown. */
|
|
51
|
+
export type TokensResult = {
|
|
52
|
+
found: true;
|
|
53
|
+
category: string | null;
|
|
54
|
+
tokens: string[];
|
|
55
|
+
citations: Citation[];
|
|
56
|
+
} | {
|
|
57
|
+
found: false;
|
|
58
|
+
category: string;
|
|
59
|
+
message: string;
|
|
60
|
+
categories: string[];
|
|
61
|
+
};
|
|
62
|
+
/**
|
|
63
|
+
* Lists design-system token names, all of them or one family (`color`,
|
|
64
|
+
* `space`, `radius`…), as the generated manifest lists them.
|
|
65
|
+
*
|
|
66
|
+
* @param k - The knowledge to read.
|
|
67
|
+
* @param category - A family: the first word after `--`.
|
|
68
|
+
* @returns The names and the manifest citation, or the known families.
|
|
69
|
+
*/
|
|
70
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"getTokens","stability":"experimental","signature":"(k: Knowledge, category?: string) => TokensResult"} */
|
|
71
|
+
export declare function getTokens(k: Knowledge, category?: string): TokensResult;
|
package/dist/tokens.js
ADDED
|
@@ -0,0 +1,420 @@
|
|
|
1
|
+
/** @codex { "id": "pithy.mcp.tokens", "title": "MCP Design Token Tools", "category": "feature", "risk": "medium" } */
|
|
2
|
+
// Ported from stylelint-plugin-pithy's token-exists rule, which exports none of it.
|
|
3
|
+
const FAMILIES = new Set([
|
|
4
|
+
'color',
|
|
5
|
+
'font',
|
|
6
|
+
'radius',
|
|
7
|
+
'space',
|
|
8
|
+
'spacing',
|
|
9
|
+
'shadow',
|
|
10
|
+
'motion',
|
|
11
|
+
'border',
|
|
12
|
+
'ring',
|
|
13
|
+
'control',
|
|
14
|
+
'icon',
|
|
15
|
+
'focus',
|
|
16
|
+
'line',
|
|
17
|
+
'blur',
|
|
18
|
+
'z',
|
|
19
|
+
]);
|
|
20
|
+
const KNOWN_MISTAKES = {
|
|
21
|
+
'--font-weight-regular': '--font-weight-normal',
|
|
22
|
+
'--font-size-md': '--font-size-body',
|
|
23
|
+
'--font-size-base': '--font-size-body',
|
|
24
|
+
'--font-family-sans': '--font-family-body',
|
|
25
|
+
'--color-border-subtle': '--color-border',
|
|
26
|
+
'--color-border-hover': '--color-border',
|
|
27
|
+
'--color-success-text': '--color-success',
|
|
28
|
+
'--color-surface-container': '--color-surface-variant',
|
|
29
|
+
'--color-surface-raised': '--color-surface-variant',
|
|
30
|
+
'--color-primary-dark': '--color-primary-hover',
|
|
31
|
+
'--color-primary-muted': '--color-primary-disabled',
|
|
32
|
+
'--ring-offset-default': '--ring-offset',
|
|
33
|
+
'--radius-full': '--radius-pill',
|
|
34
|
+
};
|
|
35
|
+
// Bare-number channel internals; never a useful suggestion for a value slot.
|
|
36
|
+
const CHANNEL_TOKEN = /-(?:l|c|h|rgb)$/;
|
|
37
|
+
const PHYSICAL = {
|
|
38
|
+
'margin-left': 'margin-inline-start',
|
|
39
|
+
'margin-right': 'margin-inline-end',
|
|
40
|
+
'margin-top': 'margin-block-start',
|
|
41
|
+
'margin-bottom': 'margin-block-end',
|
|
42
|
+
'padding-left': 'padding-inline-start',
|
|
43
|
+
'padding-right': 'padding-inline-end',
|
|
44
|
+
'padding-top': 'padding-block-start',
|
|
45
|
+
'padding-bottom': 'padding-block-end',
|
|
46
|
+
'border-left': 'border-inline-start',
|
|
47
|
+
'border-right': 'border-inline-end',
|
|
48
|
+
'border-top': 'border-block-start',
|
|
49
|
+
'border-bottom': 'border-block-end',
|
|
50
|
+
left: 'inset-inline-start',
|
|
51
|
+
right: 'inset-inline-end',
|
|
52
|
+
top: 'inset-block-start',
|
|
53
|
+
bottom: 'inset-block-end',
|
|
54
|
+
width: 'inline-size',
|
|
55
|
+
height: 'block-size',
|
|
56
|
+
'min-width': 'min-inline-size',
|
|
57
|
+
'max-width': 'max-inline-size',
|
|
58
|
+
'min-height': 'min-block-size',
|
|
59
|
+
'max-height': 'max-block-size',
|
|
60
|
+
'border-top-left-radius': 'border-start-start-radius',
|
|
61
|
+
'border-top-right-radius': 'border-start-end-radius',
|
|
62
|
+
'border-bottom-left-radius': 'border-end-start-radius',
|
|
63
|
+
'border-bottom-right-radius': 'border-end-end-radius',
|
|
64
|
+
};
|
|
65
|
+
const family = (token) => token.slice(2).split('-')[0];
|
|
66
|
+
function editDistance(a, b) {
|
|
67
|
+
let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
|
|
68
|
+
for (let i = 1; i <= a.length; i++) {
|
|
69
|
+
const row = [i];
|
|
70
|
+
for (let j = 1; j <= b.length; j++) {
|
|
71
|
+
row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
|
|
72
|
+
}
|
|
73
|
+
prev = row;
|
|
74
|
+
}
|
|
75
|
+
return prev[b.length];
|
|
76
|
+
}
|
|
77
|
+
function commonPrefix(a, b) {
|
|
78
|
+
let i = 0;
|
|
79
|
+
while (i < a.length && i < b.length && a[i] === b[i])
|
|
80
|
+
i++;
|
|
81
|
+
return i;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* The closest known token in the same family: an attested rename first, else
|
|
85
|
+
* the longest shared prefix, then the smallest edit distance, then the shorter.
|
|
86
|
+
*
|
|
87
|
+
* @param token - An unknown `--name`.
|
|
88
|
+
* @param known - Every token the design system emits.
|
|
89
|
+
* @returns A suggestion, or `null` when none is close enough.
|
|
90
|
+
*/
|
|
91
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"suggestToken","stability":"experimental","signature":"(token: string, known: ReadonlySet<string>) => string | null"} */
|
|
92
|
+
export function suggestToken(token, known) {
|
|
93
|
+
const attested = KNOWN_MISTAKES[token];
|
|
94
|
+
if (attested && known.has(attested))
|
|
95
|
+
return attested;
|
|
96
|
+
let bestPrefix = -1;
|
|
97
|
+
let tied = [];
|
|
98
|
+
for (const candidate of known) {
|
|
99
|
+
if (family(candidate) !== family(token) || CHANNEL_TOKEN.test(candidate))
|
|
100
|
+
continue;
|
|
101
|
+
const prefix = commonPrefix(token, candidate);
|
|
102
|
+
if (prefix > bestPrefix) {
|
|
103
|
+
bestPrefix = prefix;
|
|
104
|
+
tied = [candidate];
|
|
105
|
+
}
|
|
106
|
+
else if (prefix === bestPrefix)
|
|
107
|
+
tied.push(candidate);
|
|
108
|
+
}
|
|
109
|
+
let best = null;
|
|
110
|
+
let bestScore = Infinity;
|
|
111
|
+
for (const candidate of tied) {
|
|
112
|
+
const score = editDistance(token, candidate);
|
|
113
|
+
if (score < bestScore ||
|
|
114
|
+
(score === bestScore && best !== null && candidate.length < best.length)) {
|
|
115
|
+
bestScore = score;
|
|
116
|
+
best = candidate;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
return bestScore <= Math.max(3, Math.round(token.length * 0.5)) ? best : null;
|
|
120
|
+
}
|
|
121
|
+
const MAX_ISSUES = 200;
|
|
122
|
+
// Past this a name is not a typo of a token, and edit distance gets costly.
|
|
123
|
+
const MAX_SUGGEST_LENGTH = 64;
|
|
124
|
+
const own = (map, key) => Object.prototype.hasOwnProperty.call(map, key) ? map[key] : undefined;
|
|
125
|
+
// Properties whose `left`/`right` value has a logical keyword: prefix + start|end.
|
|
126
|
+
const PHYSICAL_VALUE = {
|
|
127
|
+
'text-align': '',
|
|
128
|
+
float: 'inline-',
|
|
129
|
+
clear: 'inline-',
|
|
130
|
+
};
|
|
131
|
+
/**
|
|
132
|
+
* `text` has comments blanked; `masked` also blanks url() and string contents
|
|
133
|
+
* and Sass `#{…}` interpolation, so none of them is read as CSS. Offsets and
|
|
134
|
+
* lines are kept.
|
|
135
|
+
*/
|
|
136
|
+
function mask(css) {
|
|
137
|
+
const text = css.split('');
|
|
138
|
+
const masked = css.split('');
|
|
139
|
+
const blank = (from, to, both) => {
|
|
140
|
+
for (let j = from; j < to; j++) {
|
|
141
|
+
if (css[j] === '\n')
|
|
142
|
+
continue;
|
|
143
|
+
masked[j] = ' ';
|
|
144
|
+
if (both)
|
|
145
|
+
text[j] = ' ';
|
|
146
|
+
}
|
|
147
|
+
};
|
|
148
|
+
let i = 0;
|
|
149
|
+
while (i < css.length) {
|
|
150
|
+
const c = css[i];
|
|
151
|
+
if (c === '/' && css[i + 1] === '*') {
|
|
152
|
+
const end = css.indexOf('*/', i + 2);
|
|
153
|
+
const stop = end < 0 ? css.length : end + 2;
|
|
154
|
+
blank(i, stop, true);
|
|
155
|
+
i = stop;
|
|
156
|
+
}
|
|
157
|
+
else if (c === '/' && css[i + 1] === '/') {
|
|
158
|
+
const end = css.indexOf('\n', i);
|
|
159
|
+
const stop = end < 0 ? css.length : end;
|
|
160
|
+
blank(i, stop, true);
|
|
161
|
+
i = stop;
|
|
162
|
+
}
|
|
163
|
+
else if (c === '"' || c === "'") {
|
|
164
|
+
let j = i + 1;
|
|
165
|
+
while (j < css.length && css[j] !== c && css[j] !== '\n')
|
|
166
|
+
j += css[j] === '\\' ? 2 : 1;
|
|
167
|
+
blank(i + 1, j, false);
|
|
168
|
+
i = j + 1;
|
|
169
|
+
}
|
|
170
|
+
else if (c === '#' && css[i + 1] === '{') {
|
|
171
|
+
let depth = 0;
|
|
172
|
+
let j = i + 1;
|
|
173
|
+
for (; j < css.length; j++) {
|
|
174
|
+
if (css[j] === '{')
|
|
175
|
+
depth++;
|
|
176
|
+
else if (css[j] === '}' && --depth === 0)
|
|
177
|
+
break;
|
|
178
|
+
}
|
|
179
|
+
const stop = Math.min(j + 1, css.length);
|
|
180
|
+
blank(i, stop, false);
|
|
181
|
+
i = stop;
|
|
182
|
+
}
|
|
183
|
+
else if (/url\($/i.test(css.slice(Math.max(0, i - 3), i + 1))) {
|
|
184
|
+
let j = i + 1;
|
|
185
|
+
while (/\s/.test(css[j] ?? ''))
|
|
186
|
+
j++;
|
|
187
|
+
// A quoted url() is a string; the string branch masks it next.
|
|
188
|
+
if (css[j] === '"' || css[j] === "'") {
|
|
189
|
+
i = j;
|
|
190
|
+
continue;
|
|
191
|
+
}
|
|
192
|
+
const end = css.indexOf(')', i);
|
|
193
|
+
const stop = end < 0 ? css.length : end;
|
|
194
|
+
blank(i + 1, stop, false);
|
|
195
|
+
i = stop;
|
|
196
|
+
}
|
|
197
|
+
else
|
|
198
|
+
i++;
|
|
199
|
+
}
|
|
200
|
+
return { text: text.join(''), masked: masked.join('') };
|
|
201
|
+
}
|
|
202
|
+
const RAW_COLOR = /#[0-9a-f]{3,8}\b|\b(?:rgba?|hsla?|oklch|oklab|hwb|lab|lch)\(\s*[-+]?[\d.]/gi;
|
|
203
|
+
/**
|
|
204
|
+
* Blanks each `selector(…)` argument of an `@supports` prelude, in one forward
|
|
205
|
+
* pass; lengths are kept. `color-selector(` is a Sass name, not the function.
|
|
206
|
+
*/
|
|
207
|
+
function blankSelectors(text) {
|
|
208
|
+
const out = text.split('');
|
|
209
|
+
const fn = /(?<![-\w$])selector\(/gi;
|
|
210
|
+
for (let m = fn.exec(text); m; m = fn.exec(text)) {
|
|
211
|
+
let depth = 1;
|
|
212
|
+
let j = m.index + m[0].length;
|
|
213
|
+
for (; j < text.length && depth > 0; j++) {
|
|
214
|
+
if (text[j] === '(')
|
|
215
|
+
depth++;
|
|
216
|
+
else if (text[j] === ')')
|
|
217
|
+
depth--;
|
|
218
|
+
if (depth > 0)
|
|
219
|
+
out[j] = ' ';
|
|
220
|
+
}
|
|
221
|
+
// A nested selector( lies in what was just blanked; resume after it.
|
|
222
|
+
fn.lastIndex = j;
|
|
223
|
+
}
|
|
224
|
+
return out.join('');
|
|
225
|
+
}
|
|
226
|
+
/**
|
|
227
|
+
* Splits masked text, in one pass, at top-level `{`, `}`, `;` and the end of
|
|
228
|
+
* input. A piece ending in `{` is a selector and is skipped, unless it is an
|
|
229
|
+
* at-rule other than `@extend`/`@at-root`/`@scope`, whose arguments can hold
|
|
230
|
+
* colors; `@supports` has its `selector(…)` arguments blanked first.
|
|
231
|
+
*/
|
|
232
|
+
function declarations(masked) {
|
|
233
|
+
const out = [];
|
|
234
|
+
let from = 0;
|
|
235
|
+
let depth = 0;
|
|
236
|
+
let colon = -1;
|
|
237
|
+
for (let i = 0; i <= masked.length; i++) {
|
|
238
|
+
const c = masked[i];
|
|
239
|
+
if (c === '(')
|
|
240
|
+
depth++;
|
|
241
|
+
else if (c === ')')
|
|
242
|
+
depth = Math.max(0, depth - 1);
|
|
243
|
+
else if (c === ':' && depth === 0 && colon < 0)
|
|
244
|
+
colon = i;
|
|
245
|
+
if (i < masked.length &&
|
|
246
|
+
(depth > 0 || (c !== '{' && c !== '}' && c !== ';')))
|
|
247
|
+
continue;
|
|
248
|
+
const lead = masked.slice(from, i).search(/\S/);
|
|
249
|
+
if (lead >= 0) {
|
|
250
|
+
const at = from + lead;
|
|
251
|
+
if (masked[at] === '@') {
|
|
252
|
+
if (!/^@(extend|at-root|scope)\b/i.test(masked.slice(at, at + 9)))
|
|
253
|
+
out.push({
|
|
254
|
+
prop: null,
|
|
255
|
+
propAt: at,
|
|
256
|
+
value: /^@supports\b/i.test(masked.slice(at, at + 10))
|
|
257
|
+
? blankSelectors(masked.slice(at, i))
|
|
258
|
+
: masked.slice(at, i),
|
|
259
|
+
valueAt: at,
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
else if (c !== '{' && colon >= 0) {
|
|
263
|
+
out.push({
|
|
264
|
+
prop: masked.slice(at, colon).trim(),
|
|
265
|
+
propAt: at,
|
|
266
|
+
value: masked.slice(colon + 1, i),
|
|
267
|
+
valueAt: colon + 1,
|
|
268
|
+
});
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
from = i + 1;
|
|
272
|
+
depth = 0;
|
|
273
|
+
colon = -1;
|
|
274
|
+
}
|
|
275
|
+
return out;
|
|
276
|
+
}
|
|
277
|
+
/**
|
|
278
|
+
* Checks CSS or SCSS against the design-system rules: every `var(--name)` in a
|
|
279
|
+
* token family must exist (with a did-you-mean), no value, custom prop, Sass
|
|
280
|
+
* variable or at-rule argument holds a raw color, and properties are logical.
|
|
281
|
+
* The token check skips `--_` private props, props the sheet defines itself,
|
|
282
|
+
* Sass interpolation and families outside the design system.
|
|
283
|
+
*
|
|
284
|
+
* @param css - The stylesheet.
|
|
285
|
+
* @param names - Every token the design system emits.
|
|
286
|
+
* @returns The issues, in source order.
|
|
287
|
+
*/
|
|
288
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"checkTokens","stability":"experimental","signature":"(css: string, names: readonly string[]) => TokenCheck"} */
|
|
289
|
+
export function checkTokens(css, names) {
|
|
290
|
+
const known = new Set(names);
|
|
291
|
+
const { masked } = mask(css);
|
|
292
|
+
const starts = [0];
|
|
293
|
+
for (let i = css.indexOf('\n'); i >= 0; i = css.indexOf('\n', i + 1))
|
|
294
|
+
starts.push(i + 1);
|
|
295
|
+
const lineAt = (at) => {
|
|
296
|
+
let lo = 0;
|
|
297
|
+
let hi = starts.length - 1;
|
|
298
|
+
while (lo < hi) {
|
|
299
|
+
const mid = (lo + hi + 1) >> 1;
|
|
300
|
+
if (starts[mid] <= at)
|
|
301
|
+
lo = mid;
|
|
302
|
+
else
|
|
303
|
+
hi = mid - 1;
|
|
304
|
+
}
|
|
305
|
+
return lo + 1;
|
|
306
|
+
};
|
|
307
|
+
const issues = [];
|
|
308
|
+
const segments = declarations(masked);
|
|
309
|
+
const selfDefined = new Set();
|
|
310
|
+
for (const d of segments)
|
|
311
|
+
if (d.prop?.startsWith('--'))
|
|
312
|
+
selfDefined.add(d.prop);
|
|
313
|
+
for (const m of masked.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)/gi)) {
|
|
314
|
+
const name = m[1];
|
|
315
|
+
const end = (m.index ?? 0) + m[0].length;
|
|
316
|
+
if (css.startsWith('#{', end))
|
|
317
|
+
continue;
|
|
318
|
+
if (name.startsWith('--_') || known.has(name) || selfDefined.has(name))
|
|
319
|
+
continue;
|
|
320
|
+
if (!FAMILIES.has(family(name)))
|
|
321
|
+
continue;
|
|
322
|
+
issues.push({
|
|
323
|
+
at: m.index ?? 0,
|
|
324
|
+
kind: 'unknown-token',
|
|
325
|
+
token: name,
|
|
326
|
+
line: lineAt(m.index ?? 0),
|
|
327
|
+
message: '',
|
|
328
|
+
});
|
|
329
|
+
}
|
|
330
|
+
for (const { prop, propAt, value, valueAt } of segments) {
|
|
331
|
+
if (prop && /^-?[a-zA-Z][-a-zA-Z]*$/.test(prop)) {
|
|
332
|
+
const p = prop.toLowerCase();
|
|
333
|
+
const base = p.replace(/-(width|style|color)$/, '');
|
|
334
|
+
const logical = own(PHYSICAL, p) ?? own(PHYSICAL, base);
|
|
335
|
+
if (logical) {
|
|
336
|
+
const suffix = own(PHYSICAL, p) ? '' : p.slice(p.lastIndexOf('-'));
|
|
337
|
+
issues.push({
|
|
338
|
+
at: propAt,
|
|
339
|
+
kind: 'physical-property',
|
|
340
|
+
property: p,
|
|
341
|
+
suggestion: logical + suffix,
|
|
342
|
+
line: lineAt(propAt),
|
|
343
|
+
message: `"${p}" is physical; use "${logical + suffix}".`,
|
|
344
|
+
});
|
|
345
|
+
}
|
|
346
|
+
else if (own(PHYSICAL_VALUE, p) !== undefined &&
|
|
347
|
+
/^\s*(left|right)\s*(!important\s*)?$/i.test(value)) {
|
|
348
|
+
const side = /left/i.test(value) ? 'start' : 'end';
|
|
349
|
+
const to = `${p}: ${PHYSICAL_VALUE[p]}${side}`;
|
|
350
|
+
issues.push({
|
|
351
|
+
at: propAt,
|
|
352
|
+
kind: 'physical-property',
|
|
353
|
+
property: p,
|
|
354
|
+
suggestion: to,
|
|
355
|
+
line: lineAt(propAt),
|
|
356
|
+
message: `"${p}: ${value.trim()}" is physical; use "${to}".`,
|
|
357
|
+
});
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
for (const c of value.matchAll(RAW_COLOR)) {
|
|
361
|
+
const at = valueAt + (c.index ?? 0);
|
|
362
|
+
// A bounded look for `)`: an unclosed function must not scan the rest.
|
|
363
|
+
const head = value.slice(c.index ?? 0, (c.index ?? 0) + 64);
|
|
364
|
+
const close = head.indexOf(')');
|
|
365
|
+
const raw = c[0].startsWith('#') || close < 0 ? c[0] : head.slice(0, close + 1);
|
|
366
|
+
issues.push({
|
|
367
|
+
at,
|
|
368
|
+
kind: 'raw-color',
|
|
369
|
+
value: raw,
|
|
370
|
+
line: lineAt(at),
|
|
371
|
+
message: `Raw color "${raw}"; use a --color-* token.`,
|
|
372
|
+
});
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
issues.sort((a, b) => a.at - b.at);
|
|
376
|
+
const kept = issues.slice(0, MAX_ISSUES).map(({ at: _at, ...i }) => i);
|
|
377
|
+
const suggestions = new Map();
|
|
378
|
+
for (const i of kept) {
|
|
379
|
+
if (i.kind !== 'unknown-token' || !i.token)
|
|
380
|
+
continue;
|
|
381
|
+
const name = i.token;
|
|
382
|
+
let s = suggestions.get(name);
|
|
383
|
+
if (s === undefined) {
|
|
384
|
+
s = name.length > MAX_SUGGEST_LENGTH ? null : suggestToken(name, known);
|
|
385
|
+
suggestions.set(name, s);
|
|
386
|
+
}
|
|
387
|
+
i.suggestion = s;
|
|
388
|
+
i.message = `Unknown design-system token "${name}"${s ? `; did you mean "${s}"?` : '.'}`;
|
|
389
|
+
}
|
|
390
|
+
return {
|
|
391
|
+
ok: issues.length === 0,
|
|
392
|
+
issues: kept,
|
|
393
|
+
total: issues.length,
|
|
394
|
+
truncated: issues.length > MAX_ISSUES,
|
|
395
|
+
};
|
|
396
|
+
}
|
|
397
|
+
/**
|
|
398
|
+
* Lists design-system token names, all of them or one family (`color`,
|
|
399
|
+
* `space`, `radius`…), as the generated manifest lists them.
|
|
400
|
+
*
|
|
401
|
+
* @param k - The knowledge to read.
|
|
402
|
+
* @param category - A family: the first word after `--`.
|
|
403
|
+
* @returns The names and the manifest citation, or the known families.
|
|
404
|
+
*/
|
|
405
|
+
/** @codexApi {"parent":"pithy.mcp.tokens","name":"getTokens","stability":"experimental","signature":"(k: Knowledge, category?: string) => TokensResult"} */
|
|
406
|
+
export function getTokens(k, category) {
|
|
407
|
+
const citations = [{ file: k.tokens.file }];
|
|
408
|
+
if (!category)
|
|
409
|
+
return { found: true, category: null, tokens: k.tokens.names, citations };
|
|
410
|
+
const c = category.trim().replace(/^--/, '').toLowerCase();
|
|
411
|
+
const tokens = k.tokens.names.filter(t => family(t) === c);
|
|
412
|
+
if (tokens.length > 0)
|
|
413
|
+
return { found: true, category: c, tokens, citations };
|
|
414
|
+
return {
|
|
415
|
+
found: false,
|
|
416
|
+
category: c,
|
|
417
|
+
message: `No token family "${c}".`,
|
|
418
|
+
categories: [...new Set(k.tokens.names.map(family))].sort(),
|
|
419
|
+
};
|
|
420
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,59 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@pithyjs/mcp",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.1.0-beta.1",
|
|
4
|
+
"description": "MCP server for PithyJS: grounded API and component lookup, template, token and PIDL checks, and route and component scaffolds for coding agents.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "dist/index.js",
|
|
7
|
+
"types": "dist/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"import": "./dist/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"bin": {
|
|
15
|
+
"pithy-mcp": "dist/cli.js"
|
|
16
|
+
},
|
|
17
|
+
"dependencies": {
|
|
18
|
+
"@modelcontextprotocol/sdk": "1.32.2",
|
|
19
|
+
"vite": "^6.3.5",
|
|
20
|
+
"zod": "^3.25.76",
|
|
21
|
+
"@pithyjs/ui-kit": "1.0.0-beta.26",
|
|
22
|
+
"@pithyjs/vite-plugin": "0.2.0-beta.25"
|
|
23
|
+
},
|
|
24
|
+
"peerDependencies": {
|
|
25
|
+
"@pithyjs/codex": "^0.1.0-beta.3"
|
|
26
|
+
},
|
|
27
|
+
"peerDependenciesMeta": {
|
|
28
|
+
"@pithyjs/codex": {
|
|
29
|
+
"optional": true
|
|
30
|
+
}
|
|
31
|
+
},
|
|
32
|
+
"devDependencies": {
|
|
33
|
+
"@types/node": "^22",
|
|
34
|
+
"typescript": "^5.8.3",
|
|
35
|
+
"vitest": "3.2.4",
|
|
36
|
+
"@pithyjs/codex": "0.1.0-beta.3"
|
|
37
|
+
},
|
|
38
|
+
"engines": {
|
|
39
|
+
"node": ">=18"
|
|
40
|
+
},
|
|
41
|
+
"license": "MIT",
|
|
42
|
+
"files": [
|
|
43
|
+
"dist"
|
|
44
|
+
],
|
|
45
|
+
"publishConfig": {
|
|
46
|
+
"access": "public",
|
|
47
|
+
"tag": "beta"
|
|
48
|
+
},
|
|
49
|
+
"repository": {
|
|
50
|
+
"type": "git",
|
|
51
|
+
"url": "git+https://github.com/PithyJS/pithyjs.git",
|
|
52
|
+
"directory": "packages/mcp"
|
|
53
|
+
},
|
|
54
|
+
"scripts": {
|
|
55
|
+
"build": "node ../../scripts/check-dist.mjs --unstamp $$ && tsc -p tsconfig.json && node ../../scripts/add-js-extensions.mjs dist && node scripts/build-snapshot.mjs && node ../../scripts/check-dist.mjs --stamp $$",
|
|
56
|
+
"test": "vitest run",
|
|
57
|
+
"test:watch": "vitest"
|
|
58
|
+
}
|
|
6
59
|
}
|