@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.
@@ -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
- export async function openProjectIndex(config, { stateDirectory = defaultStateDirectory, persist = true } = {}) {
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
- if (!persist) return buildSource(config, path.join(config.root, source), { write: false, allowLegacy: false });
46
- storePromise ??= createBuildStore({ config: { ...config, sourceFiles: inventory.tsx }, cacheDirectory: buildDirectory });
47
- const built = await (await storePromise).get(path.relative(config.design, path.join(config.root, source)).split(path.sep).join('/'));
48
- for (const [name, hash] of Object.entries(built.dependencyHashes)) {
49
- if (observedInputs.has(name) && observedInputs.get(name) !== hash) throw new CliError('OWNER_INDEX_CHANGED', `Design dependency changed during query: ${name}.`);
50
- observedInputs.set(name, hash);
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
- async source(source) {
66
- const built = await getBuild(source);
67
- return cached('source', { source, build: built.inputHash ?? indexDigest(JSON.stringify({ ...built, frames: built.frames.map(({ document, ...frame }) => frame) })) }, () => sourceFacts(config, source, built));
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, requestedSources: [...requestedSources] }),
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
  }
@@ -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
+ }