@whzxc/agent-design-gallery 0.9.0 → 0.10.0
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/README.md +16 -0
- package/package.json +4 -1
- package/src/cli-output.mjs +25 -1
- package/src/cli.mjs +40 -8
- package/src/toolkit/arch-git.mjs +19 -0
- package/src/toolkit/build-store.mjs +5 -3
- package/src/toolkit/build-worker.mjs +5 -2
- package/src/toolkit/build.mjs +11 -5
- package/src/toolkit/commands.mjs +26 -15
- package/src/toolkit/config.mjs +6 -5
- package/src/toolkit/diff-inputs.mjs +5 -5
- package/src/toolkit/diff.mjs +14 -10
- package/src/toolkit/frame-document.mjs +6 -0
- package/src/toolkit/impact-eligibility.mjs +136 -0
- package/src/toolkit/impact-inputs.mjs +71 -0
- package/src/toolkit/impact-output.mjs +46 -0
- package/src/toolkit/impact-proof.mjs +67 -0
- package/src/toolkit/impact-selection.mjs +96 -0
- package/src/toolkit/impact.mjs +403 -0
- package/src/toolkit/implementation-query.mjs +53 -0
- package/src/toolkit/owner.mjs +4 -41
- package/src/toolkit/project-index.mjs +79 -18
- package/src/toolkit/results.mjs +2 -2
- package/src/toolkit/token-reachability.mjs +71 -0
|
@@ -1,20 +1,22 @@
|
|
|
1
|
-
import { readFile, realpath } from 'node:fs/promises';
|
|
1
|
+
import { readFile, realpath, readdir } from 'node:fs/promises';
|
|
2
2
|
import { readFileSync } from 'node:fs';
|
|
3
3
|
import path from 'node:path';
|
|
4
4
|
import { listSources, archFiles, sourceDirectories, relative, loadTokens } from './project.mjs';
|
|
5
5
|
import { tokenLocations } from './tokens.mjs';
|
|
6
6
|
import { CliError } from '../cli-output.mjs';
|
|
7
7
|
import { buildSource } from './build.mjs';
|
|
8
|
-
import { createBuildStore } from './build-store.mjs';
|
|
8
|
+
import { createBuildStore, BuildPool } from './build-store.mjs';
|
|
9
9
|
import { sourceFacts } from './source-facts.mjs';
|
|
10
10
|
import { sidecar } from './arch.mjs';
|
|
11
11
|
import { loadImplementationMap, validateImplementationMap } from './implementation-map.mjs';
|
|
12
12
|
import { createIndexStore, indexDigest } from './index-store.mjs';
|
|
13
13
|
import { defaultStateDirectory } from '../hub/registry.mjs';
|
|
14
14
|
import { sourceRelationships } from '../../public/relationships.js';
|
|
15
|
+
import { entryTokenReachability } from './token-reachability.mjs';
|
|
16
|
+
import { frameDocument } from './frame-document.mjs';
|
|
15
17
|
export { sourceFacts } from './source-facts.mjs';
|
|
16
18
|
|
|
17
|
-
const collectorIdentity = indexDigest(Buffer.concat(await Promise.all(['project-index.mjs', 'source-facts.mjs', 'implementation-map.mjs', 'owner-locators.mjs', 'owner-observation.mjs', 'owner-colors.mjs', 'tokens.mjs', 'arch.mjs'].map(name => readFile(new URL(name, import.meta.url))))));
|
|
19
|
+
const collectorIdentity = indexDigest(Buffer.concat(await Promise.all(['project-index.mjs', 'source-facts.mjs', 'implementation-map.mjs', 'owner-locators.mjs', 'owner-observation.mjs', 'owner-colors.mjs', 'tokens.mjs', 'token-reachability.mjs', 'arch.mjs'].map(name => readFile(new URL(name, import.meta.url))))));
|
|
18
20
|
|
|
19
21
|
export function discoverProject(config) {
|
|
20
22
|
const tsx = listSources(config.design, sourceDirectories(config)).map(file => relative(config, file));
|
|
@@ -29,12 +31,31 @@ export function tokenFacts(config) {
|
|
|
29
31
|
.map(item => ({ ...item, line: (item.theme === 'dark' && !item.inherited ? locations.dark : locations.light).get(name), references: [...item.declaration.matchAll(/var\(\s*(--[\w-]+)/g)].map(match => match[1]) })) }));
|
|
30
32
|
}
|
|
31
33
|
|
|
32
|
-
|
|
34
|
+
async function resolutionFiles(config, artifactDirectory) {
|
|
35
|
+
const files = [];
|
|
36
|
+
async function visit(directory) {
|
|
37
|
+
for (const entry of await readdir(directory, { withFileTypes: true })) {
|
|
38
|
+
if (['.git', '.adg', 'node_modules'].includes(entry.name)) continue;
|
|
39
|
+
const file = path.join(directory, entry.name);
|
|
40
|
+
if (file === config.output) continue;
|
|
41
|
+
if (entry.isDirectory()) await visit(file);
|
|
42
|
+
else if (!(artifactDirectory && !path.relative(artifactDirectory, file).startsWith('..') && !path.isAbsolute(path.relative(artifactDirectory, file)) && /\.(?:png|json)$/.test(file))) files.push(path.relative(config.design, file));
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
try { await visit(config.design); } catch (error) { if (error.code !== 'ENOENT') throw error; }
|
|
46
|
+
return files.sort();
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export async function openProjectIndex(config, { stateDirectory = defaultStateDirectory, persist = true, fresh = false, artifactDirectory } = {}) {
|
|
33
50
|
const inventory = discoverProject(config), root = await realpath(config.root), buildPromises = new Map();
|
|
34
51
|
const directory = path.join(stateDirectory, 'cache', indexDigest(root), 'index-v1');
|
|
35
52
|
const shards = await createIndexStore({ directory, persist });
|
|
36
53
|
const buildDirectory = path.join(stateDirectory, 'cache', indexDigest(root), 'build');
|
|
37
54
|
let storePromise, closed = false;
|
|
55
|
+
let freshPool;
|
|
56
|
+
const materializations = new Map();
|
|
57
|
+
const resolution = fresh ? await resolutionFiles(config, artifactDirectory) : null;
|
|
58
|
+
const physicalDesign = inventory.tsx.length ? await realpath(config.design) : null;
|
|
38
59
|
const observedInputs = new Map(), requestedSources = new Set();
|
|
39
60
|
const assertOpen = () => { if (closed) throw Error('Project index is closed.'); };
|
|
40
61
|
async function getBuild(source) {
|
|
@@ -42,17 +63,41 @@ export async function openProjectIndex(config, { stateDirectory = defaultStateDi
|
|
|
42
63
|
if (!inventory.tsx.includes(source)) throw Error(`Undiscovered TSX source ${source}.`);
|
|
43
64
|
requestedSources.add(source);
|
|
44
65
|
if (!buildPromises.has(source)) buildPromises.set(source, (async () => {
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
66
|
+
let built;
|
|
67
|
+
if (!persist) {
|
|
68
|
+
const snapshot = new Map();
|
|
69
|
+
built = await buildSource(config, path.join(config.root, source), { write: false, allowLegacy: false, snapshot });
|
|
70
|
+
built.dependencyHashes = Object.fromEntries([...snapshot].map(([file, bytes]) => [path.relative(config.design, file), indexDigest(bytes === null ? 'missing\0' : Buffer.concat([Buffer.from('present\0'), bytes]))]));
|
|
71
|
+
} else {
|
|
72
|
+
storePromise ??= createBuildStore({ config: { ...config, sourceFiles: inventory.tsx }, cacheDirectory: buildDirectory });
|
|
73
|
+
built = await (await storePromise).get(path.relative(config.design, path.join(config.root, source)).split(path.sep).join('/'));
|
|
51
74
|
}
|
|
52
|
-
return built;
|
|
75
|
+
return observeDependencies(built);
|
|
53
76
|
})().finally(() => buildPromises.delete(source)));
|
|
54
77
|
return buildPromises.get(source);
|
|
55
78
|
}
|
|
79
|
+
function observeDependencies(built) {
|
|
80
|
+
for (const [name, hash] of Object.entries(built.dependencyHashes)) {
|
|
81
|
+
if (observedInputs.has(name) && observedInputs.get(name) !== hash) throw new CliError('OWNER_INDEX_CHANGED', `Design dependency changed during query: ${name}.`);
|
|
82
|
+
observedInputs.set(name, hash);
|
|
83
|
+
}
|
|
84
|
+
return built;
|
|
85
|
+
}
|
|
86
|
+
function materialize(source) {
|
|
87
|
+
assertOpen();
|
|
88
|
+
if (!inventory.tsx.includes(source)) throw Error(`Undiscovered TSX source ${source}.`);
|
|
89
|
+
if (!materializations.has(source)) {
|
|
90
|
+
requestedSources.add(source); freshPool ??= new BuildPool();
|
|
91
|
+
materializations.set(source, freshPool.run({ config: { root, design: physicalDesign ?? config.design, output: config.output,
|
|
92
|
+
sources: config.sources, arch: config.arch, check: config.check, allowLegacy: false },
|
|
93
|
+
name: path.relative(physicalDesign ?? config.design, path.join(root, source)).split(path.sep).join('/') }, new AbortController().signal).then(built => {
|
|
94
|
+
observeDependencies(built);
|
|
95
|
+
for (const frame of built.frames) frame.document = theme => frameDocument(frame, theme, built.css);
|
|
96
|
+
return built;
|
|
97
|
+
}));
|
|
98
|
+
}
|
|
99
|
+
return materializations.get(source);
|
|
100
|
+
}
|
|
56
101
|
async function cached(projection, inputs, collect) {
|
|
57
102
|
const key = JSON.stringify({ version: 1, collectorIdentity, projection, inputs });
|
|
58
103
|
const hit = await shards.get(key);
|
|
@@ -62,9 +107,21 @@ export async function openProjectIndex(config, { stateDirectory = defaultStateDi
|
|
|
62
107
|
return {
|
|
63
108
|
inventory,
|
|
64
109
|
getBuild,
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
110
|
+
materialize,
|
|
111
|
+
async source(source, { tokens = false, fresh = false } = {}) {
|
|
112
|
+
const built = fresh ? await materialize(source) : await getBuild(source);
|
|
113
|
+
const inputs = fresh ? null : { source, build: built.inputHash ?? indexDigest(JSON.stringify({ ...built, frames: built.frames.map(({ document, ...frame }) => frame) })) };
|
|
114
|
+
const facts = fresh ? sourceFacts(config, source, built) : await cached('source', inputs, () => sourceFacts(config, source, built));
|
|
115
|
+
if (!tokens) return facts;
|
|
116
|
+
const collect = () => {
|
|
117
|
+
const scan = entryTokenReachability((built.cssBeforeTokens + built.cssAfterTokens).replace(/<\/style/gi, '<\\/style'), built.tokenCss);
|
|
118
|
+
return built.frames.map(frame => {
|
|
119
|
+
const reach = scan(frameDocument(frame, 'light', ''));
|
|
120
|
+
return { frame: frame.name, themes: ['light', 'dark'].map(theme => ({ theme, ...reach(theme) })) };
|
|
121
|
+
});
|
|
122
|
+
};
|
|
123
|
+
const tokenDependencies = fresh ? collect() : await cached('token-dependencies', inputs, collect);
|
|
124
|
+
return { ...facts, tokenDependencies };
|
|
68
125
|
},
|
|
69
126
|
tokens() { assertOpen(); return tokenFacts(config); },
|
|
70
127
|
async mappings({ selected, map: supplied, ...selection } = {}) {
|
|
@@ -94,6 +151,8 @@ export async function openProjectIndex(config, { stateDirectory = defaultStateDi
|
|
|
94
151
|
await shards.put(key, [...entries]); return value;
|
|
95
152
|
},
|
|
96
153
|
async verifyInputs() {
|
|
154
|
+
if (JSON.stringify(discoverProject(config)) !== JSON.stringify(inventory)) throw new CliError('OWNER_INDEX_CHANGED', 'Design source inventory changed during query.');
|
|
155
|
+
if (resolution && JSON.stringify(await resolutionFiles(config, artifactDirectory)) !== JSON.stringify(resolution)) throw new CliError('OWNER_INDEX_CHANGED', 'Design resolution inventory changed during query.');
|
|
97
156
|
for (const [name, hash] of observedInputs) {
|
|
98
157
|
let value;
|
|
99
158
|
try { value = indexDigest(Buffer.concat([Buffer.from('present\0'), await readFile(path.join(config.design, name))])); }
|
|
@@ -108,20 +167,22 @@ export async function openProjectIndex(config, { stateDirectory = defaultStateDi
|
|
|
108
167
|
try { text = await readFile(path.join(config.root, side), 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; }
|
|
109
168
|
return cached('architecture', { source, text }, () => ({ source, sidecar: side, ...sidecar(text) }));
|
|
110
169
|
},
|
|
111
|
-
async relationships() {
|
|
170
|
+
async relationships({ facts: supplied, projectPaths = false } = {}) {
|
|
112
171
|
const assets = await Promise.all(inventory.tsx.map(async source => {
|
|
113
|
-
const facts = await this.source(source);
|
|
172
|
+
const facts = supplied?.get(source) ?? await this.source(source);
|
|
173
|
+
if (projectPaths) return { path: source, imports: facts.imports };
|
|
114
174
|
const designRelative = file => path.relative(config.design, path.join(config.root, file)).split(path.sep).join('/');
|
|
115
175
|
return { path: designRelative(source), imports: facts.imports.map(designRelative) };
|
|
116
176
|
}));
|
|
117
177
|
assets.push(...inventory.architecture.map(source => ({ path: source, imports: [] })));
|
|
118
178
|
return sourceRelationships(assets);
|
|
119
179
|
},
|
|
120
|
-
stats: async () => ({ shards: shards.stats(), builds: storePromise ? (await storePromise).stats() : null,
|
|
180
|
+
stats: async () => ({ shards: shards.stats(), builds: storePromise ? (await storePromise).stats() : null,
|
|
181
|
+
materializations: freshPool?.stats() ?? null, requestedSources: [...requestedSources] }),
|
|
121
182
|
async close() {
|
|
122
183
|
closed = true;
|
|
123
184
|
try { if (storePromise) await (await storePromise).close(); }
|
|
124
|
-
finally { await shards.close(); }
|
|
185
|
+
finally { try { await freshPool?.close(); materializations.clear(); } finally { await shards.close(); } }
|
|
125
186
|
},
|
|
126
187
|
};
|
|
127
188
|
}
|
package/src/toolkit/results.mjs
CHANGED
|
@@ -3,9 +3,9 @@ import { CliError, classifyError } from '../cli-output.mjs';
|
|
|
3
3
|
/** @typedef {'light' | 'dark'} Theme */
|
|
4
4
|
/** @typedef {{source: string | null, frame: string | null, theme: Theme | null, line: number | null, column: number | null}} Location */
|
|
5
5
|
/** @typedef {Location & {code: string, message: string}} Finding */
|
|
6
|
-
/** @typedef {{project: string, readOnly: boolean, complete: boolean, sources: string[], summary: {sources: number, frames: number, evaluations: number, problems: number}, findings: Finding[]}} CheckData */
|
|
6
|
+
/** @typedef {{project: string, readOnly: boolean, complete: boolean, impact: object | null, sources: string[], summary: {sources: number, frames: number, evaluations: number, problems: number}, findings: Finding[]}} CheckData */
|
|
7
7
|
/** @typedef {{source: string, frame: string, theme: Theme, path: string, scale: number, width: number, height: number, pixelWidth: number, pixelHeight: number}} Capture */
|
|
8
|
-
/** @typedef {{project: string, outputDirectory: string, complete: boolean, base: {rev: string, sha: string} | null, captures: Capture[], deleted: string[]}} RenderData */
|
|
8
|
+
/** @typedef {{project: string, outputDirectory: string, complete: boolean, impact: object | null, base: {rev: string, sha: string} | null, captures: Capture[], deleted: string[]}} RenderData */
|
|
9
9
|
/** @typedef {{source: string, frame: string, fixture: string, theme: Theme, settled: boolean, size: {design: [number, number], implementation: [number, number]}, matched: number, offBy2px: {text: string, dx: number, dy: number, dw: number, off: number}[], missing: string[], extra: string[], paths: {design: string, implementation: string, overlay: string, report: string, html: string}}} Comparison */
|
|
10
10
|
/** @typedef {{project: string, complete: boolean, all: boolean, comparisons: Comparison[], skipped: {source: string, frame: string, reason: 'no_fixture'}[], summary: {frames: number, matched: number, offsets: number, missing: number, extra: number}, indexPath: string | null, summaryPath: string | null}} CompareData */
|
|
11
11
|
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import { decodeHTML } from 'entities';
|
|
2
|
+
import { parseTokens } from './tokens.mjs';
|
|
3
|
+
|
|
4
|
+
export function decodeCssEscapes(text) {
|
|
5
|
+
return text.replace(/\\(?:([\da-f]{1,6})(?:\r\n|[ \t\r\n\f])?|(\r\n|[\r\n\f])|([\s\S]))/gi, (_, hex, newline, char) => {
|
|
6
|
+
if (hex) {
|
|
7
|
+
const code = Number.parseInt(hex, 16);
|
|
8
|
+
return String.fromCodePoint(!code || code > 0x10ffff || code >= 0xd800 && code <= 0xdfff ? 0xfffd : code);
|
|
9
|
+
}
|
|
10
|
+
return newline ? '' : char;
|
|
11
|
+
});
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
function forms(text) {
|
|
15
|
+
const css = decodeCssEscapes(text), html = decodeHTML(text);
|
|
16
|
+
return [...new Set([text, css, html, decodeCssEscapes(html), decodeHTML(css)])];
|
|
17
|
+
}
|
|
18
|
+
// Decoding only adds candidates; raw spellings, text and inactive rules still participate.
|
|
19
|
+
const identifiers = text => [...new Set(forms(text).flatMap(value => [...value.matchAll(/--[\p{L}\p{N}_-]+/gu)].map(match => match[0])))];
|
|
20
|
+
|
|
21
|
+
function unbalancedVar(value) {
|
|
22
|
+
const stack = [];
|
|
23
|
+
let quote = null;
|
|
24
|
+
for (let i = 0; i < value.length; i++) {
|
|
25
|
+
const char = value[i];
|
|
26
|
+
if (char === '\\') { i++; continue; }
|
|
27
|
+
if (quote) { if (char === quote) quote = null; continue; }
|
|
28
|
+
if (char === '"' || char === "'") { quote = char; continue; }
|
|
29
|
+
if (char === '(') stack.push(/\bvar$/i.test(value.slice(Math.max(0, i - 3), i)));
|
|
30
|
+
else if (char === ')') stack.pop();
|
|
31
|
+
}
|
|
32
|
+
return stack.includes(true);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Conservative names/declarations (including absence), shared by candidates and later proofs. */
|
|
36
|
+
export function tokenReachability(document, tokenSource, theme) {
|
|
37
|
+
return reachability(identifiers(document).sort(), tokenSource, theme);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
export function entryTokenReachability(css, tokenSource) {
|
|
41
|
+
const shared = identifiers(css);
|
|
42
|
+
let parsed;
|
|
43
|
+
try { parsed = parseTokens(tokenSource); } catch {}
|
|
44
|
+
return markup => {
|
|
45
|
+
const roots = [...new Set([...shared, ...identifiers(markup)])].sort();
|
|
46
|
+
return theme => reachability(roots, tokenSource, theme, parsed);
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
function reachability(roots, tokenSource, theme, parsed) {
|
|
51
|
+
let tokens, definitions;
|
|
52
|
+
const result = (mode, names, via, fallbackReasons) => ({ mode, names, via,
|
|
53
|
+
declarations: definitions ? Object.fromEntries(names.map(name => [name, definitions.get(name) ?? null])) : {}, fallbackReasons });
|
|
54
|
+
const fallback = reason => result('full_sheet', [...new Set([...roots, ...identifiers(tokenSource)])].sort(), {}, [reason]);
|
|
55
|
+
try { tokens = parsed ?? parseTokens(tokenSource); } catch { return fallback('tokens_parse_failed'); }
|
|
56
|
+
definitions = new Map(tokens.light);
|
|
57
|
+
if (theme === 'dark') for (const [name, value] of tokens.dark) definitions.set(name, value);
|
|
58
|
+
const via = {}, queue = roots.map(name => ({ name, route: [] }));
|
|
59
|
+
for (let i = 0; i < queue.length; i++) {
|
|
60
|
+
const { name, route } = queue[i];
|
|
61
|
+
if (Object.hasOwn(via, name)) continue;
|
|
62
|
+
via[name] = route;
|
|
63
|
+
const value = definitions.get(name);
|
|
64
|
+
if (value === undefined) continue;
|
|
65
|
+
const variants = forms(value);
|
|
66
|
+
if (variants.some(unbalancedVar)) return fallback('unbalanced_var');
|
|
67
|
+
const targets = new Set(variants.flatMap(value => [...value.matchAll(/\bvar\(\s*(--[\p{L}\p{N}_-]+)/giu)].map(match => match[1])));
|
|
68
|
+
for (const target of targets) queue.push({ name: target, route: [...route, name] });
|
|
69
|
+
}
|
|
70
|
+
return result('reachable_declarations', Object.keys(via).sort(), via, []);
|
|
71
|
+
}
|