@lushly-dev/violet-afd 0.0.0-stage → 0.3.0-preview.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/LICENSE +21 -0
- package/README.md +29 -2
- package/dist/commands/analyze/compare.d.ts +34 -0
- package/dist/commands/analyze/compare.d.ts.map +1 -0
- package/dist/commands/analyze/compare.js +180 -0
- package/dist/commands/analyze/compare.js.map +1 -0
- package/dist/commands/analyze/compliance.d.ts +41 -0
- package/dist/commands/analyze/compliance.d.ts.map +1 -0
- package/dist/commands/analyze/compliance.js +166 -0
- package/dist/commands/analyze/compliance.js.map +1 -0
- package/dist/commands/analyze/deviations.d.ts +30 -0
- package/dist/commands/analyze/deviations.d.ts.map +1 -0
- package/dist/commands/analyze/deviations.js +201 -0
- package/dist/commands/analyze/deviations.js.map +1 -0
- package/dist/commands/analyze/health.d.ts +211 -0
- package/dist/commands/analyze/health.d.ts.map +1 -0
- package/dist/commands/analyze/health.js +697 -0
- package/dist/commands/analyze/health.js.map +1 -0
- package/dist/commands/analyze/index.d.ts +15 -0
- package/dist/commands/analyze/index.d.ts.map +1 -0
- package/dist/commands/analyze/index.js +31 -0
- package/dist/commands/analyze/index.js.map +1 -0
- package/dist/commands/analyze/snapshot.d.ts +64 -0
- package/dist/commands/analyze/snapshot.d.ts.map +1 -0
- package/dist/commands/analyze/snapshot.js +126 -0
- package/dist/commands/analyze/snapshot.js.map +1 -0
- package/dist/commands/analyze/trends.d.ts +82 -0
- package/dist/commands/analyze/trends.d.ts.map +1 -0
- package/dist/commands/analyze/trends.js +312 -0
- package/dist/commands/analyze/trends.js.map +1 -0
- package/dist/commands/analyze/violations.d.ts +84 -0
- package/dist/commands/analyze/violations.d.ts.map +1 -0
- package/dist/commands/analyze/violations.js +158 -0
- package/dist/commands/analyze/violations.js.map +1 -0
- package/dist/commands/apikeys/check.d.ts +39 -0
- package/dist/commands/apikeys/check.d.ts.map +1 -0
- package/dist/commands/apikeys/check.js +61 -0
- package/dist/commands/apikeys/check.js.map +1 -0
- package/dist/commands/apikeys/create.d.ts +36 -0
- package/dist/commands/apikeys/create.d.ts.map +1 -0
- package/dist/commands/apikeys/create.js +116 -0
- package/dist/commands/apikeys/create.js.map +1 -0
- package/dist/commands/apikeys/index.d.ts +15 -0
- package/dist/commands/apikeys/index.d.ts.map +1 -0
- package/dist/commands/apikeys/index.js +21 -0
- package/dist/commands/apikeys/index.js.map +1 -0
- package/dist/commands/apikeys/keys.d.ts +79 -0
- package/dist/commands/apikeys/keys.d.ts.map +1 -0
- package/dist/commands/apikeys/keys.js +239 -0
- package/dist/commands/apikeys/keys.js.map +1 -0
- package/dist/commands/audit/index.d.ts +11 -0
- package/dist/commands/audit/index.d.ts.map +1 -0
- package/dist/commands/audit/index.js +15 -0
- package/dist/commands/audit/index.js.map +1 -0
- package/dist/commands/audit/list.d.ts +101 -0
- package/dist/commands/audit/list.d.ts.map +1 -0
- package/dist/commands/audit/list.js +230 -0
- package/dist/commands/audit/list.js.map +1 -0
- package/dist/commands/changes/impact.d.ts +477 -0
- package/dist/commands/changes/impact.d.ts.map +1 -0
- package/dist/commands/changes/impact.js +541 -0
- package/dist/commands/changes/impact.js.map +1 -0
- package/dist/commands/changes/index.d.ts +11 -0
- package/dist/commands/changes/index.d.ts.map +1 -0
- package/dist/commands/changes/index.js +15 -0
- package/dist/commands/changes/index.js.map +1 -0
- package/dist/commands/constraints/index.d.ts +11 -0
- package/dist/commands/constraints/index.d.ts.map +1 -0
- package/dist/commands/constraints/index.js +19 -0
- package/dist/commands/constraints/index.js.map +1 -0
- package/dist/commands/constraints/list.d.ts +52 -0
- package/dist/commands/constraints/list.d.ts.map +1 -0
- package/dist/commands/constraints/list.js +103 -0
- package/dist/commands/constraints/list.js.map +1 -0
- package/dist/commands/constraints/set.d.ts +50 -0
- package/dist/commands/constraints/set.d.ts.map +1 -0
- package/dist/commands/constraints/set.js +137 -0
- package/dist/commands/constraints/set.js.map +1 -0
- package/dist/commands/constraints/validate.d.ts +38 -0
- package/dist/commands/constraints/validate.d.ts.map +1 -0
- package/dist/commands/constraints/validate.js +164 -0
- package/dist/commands/constraints/validate.js.map +1 -0
- package/dist/commands/docs/generator.d.ts +77 -0
- package/dist/commands/docs/generator.d.ts.map +1 -0
- package/dist/commands/docs/generator.js +256 -0
- package/dist/commands/docs/generator.js.map +1 -0
- package/dist/commands/docs/index.d.ts +6 -0
- package/dist/commands/docs/index.d.ts.map +1 -0
- package/dist/commands/docs/index.js +6 -0
- package/dist/commands/docs/index.js.map +1 -0
- package/dist/commands/export/export.d.ts +64 -0
- package/dist/commands/export/export.d.ts.map +1 -0
- package/dist/commands/export/export.js +193 -0
- package/dist/commands/export/export.js.map +1 -0
- package/dist/commands/export/index.d.ts +9 -0
- package/dist/commands/export/index.d.ts.map +1 -0
- package/dist/commands/export/index.js +13 -0
- package/dist/commands/export/index.js.map +1 -0
- package/dist/commands/import/flatten.d.ts +30 -0
- package/dist/commands/import/flatten.d.ts.map +1 -0
- package/dist/commands/import/flatten.js +121 -0
- package/dist/commands/import/flatten.js.map +1 -0
- package/dist/commands/import/index.d.ts +11 -0
- package/dist/commands/import/index.d.ts.map +1 -0
- package/dist/commands/import/index.js +19 -0
- package/dist/commands/import/index.js.map +1 -0
- package/dist/commands/import/json.d.ts +40 -0
- package/dist/commands/import/json.d.ts.map +1 -0
- package/dist/commands/import/json.js +209 -0
- package/dist/commands/import/json.js.map +1 -0
- package/dist/commands/import/tree.d.ts +39 -0
- package/dist/commands/import/tree.d.ts.map +1 -0
- package/dist/commands/import/tree.js +247 -0
- package/dist/commands/import/tree.js.map +1 -0
- package/dist/commands/import/validate.d.ts +53 -0
- package/dist/commands/import/validate.d.ts.map +1 -0
- package/dist/commands/import/validate.js +201 -0
- package/dist/commands/import/validate.js.map +1 -0
- package/dist/commands/index.d.ts +21 -0
- package/dist/commands/index.d.ts.map +1 -0
- package/dist/commands/index.js +21 -0
- package/dist/commands/index.js.map +1 -0
- package/dist/commands/json-schema.d.ts +21 -0
- package/dist/commands/json-schema.d.ts.map +1 -0
- package/dist/commands/json-schema.js +41 -0
- package/dist/commands/json-schema.js.map +1 -0
- package/dist/commands/node/create.d.ts +80 -0
- package/dist/commands/node/create.d.ts.map +1 -0
- package/dist/commands/node/create.js +174 -0
- package/dist/commands/node/create.js.map +1 -0
- package/dist/commands/node/delete.d.ts +28 -0
- package/dist/commands/node/delete.d.ts.map +1 -0
- package/dist/commands/node/delete.js +134 -0
- package/dist/commands/node/delete.js.map +1 -0
- package/dist/commands/node/deprecation.d.ts +23 -0
- package/dist/commands/node/deprecation.d.ts.map +1 -0
- package/dist/commands/node/deprecation.js +59 -0
- package/dist/commands/node/deprecation.js.map +1 -0
- package/dist/commands/node/get.d.ts +79 -0
- package/dist/commands/node/get.d.ts.map +1 -0
- package/dist/commands/node/get.js +106 -0
- package/dist/commands/node/get.js.map +1 -0
- package/dist/commands/node/graph.d.ts +138 -0
- package/dist/commands/node/graph.d.ts.map +1 -0
- package/dist/commands/node/graph.js +285 -0
- package/dist/commands/node/graph.js.map +1 -0
- package/dist/commands/node/index.d.ts +17 -0
- package/dist/commands/node/index.d.ts.map +1 -0
- package/dist/commands/node/index.js +31 -0
- package/dist/commands/node/index.js.map +1 -0
- package/dist/commands/node/list.d.ts +74 -0
- package/dist/commands/node/list.d.ts.map +1 -0
- package/dist/commands/node/list.js +130 -0
- package/dist/commands/node/list.js.map +1 -0
- package/dist/commands/node/operations.d.ts +35 -0
- package/dist/commands/node/operations.d.ts.map +1 -0
- package/dist/commands/node/operations.js +66 -0
- package/dist/commands/node/operations.js.map +1 -0
- package/dist/commands/node/scope.d.ts +14 -0
- package/dist/commands/node/scope.d.ts.map +1 -0
- package/dist/commands/node/scope.js +49 -0
- package/dist/commands/node/scope.js.map +1 -0
- package/dist/commands/node/update.d.ts +84 -0
- package/dist/commands/node/update.d.ts.map +1 -0
- package/dist/commands/node/update.js +229 -0
- package/dist/commands/node/update.js.map +1 -0
- package/dist/commands/registry.d.ts +114 -0
- package/dist/commands/registry.d.ts.map +1 -0
- package/dist/commands/registry.js +141 -0
- package/dist/commands/registry.js.map +1 -0
- package/dist/commands/specimen/get.d.ts +46 -0
- package/dist/commands/specimen/get.d.ts.map +1 -0
- package/dist/commands/specimen/get.js +121 -0
- package/dist/commands/specimen/get.js.map +1 -0
- package/dist/commands/specimen/index.d.ts +10 -0
- package/dist/commands/specimen/index.d.ts.map +1 -0
- package/dist/commands/specimen/index.js +16 -0
- package/dist/commands/specimen/index.js.map +1 -0
- package/dist/commands/specimen/set.d.ts +31 -0
- package/dist/commands/specimen/set.d.ts.map +1 -0
- package/dist/commands/specimen/set.js +188 -0
- package/dist/commands/specimen/set.js.map +1 -0
- package/dist/commands/specimen/shared.d.ts +16 -0
- package/dist/commands/specimen/shared.d.ts.map +1 -0
- package/dist/commands/specimen/shared.js +27 -0
- package/dist/commands/specimen/shared.js.map +1 -0
- package/dist/commands/system/doctor.d.ts +48 -0
- package/dist/commands/system/doctor.d.ts.map +1 -0
- package/dist/commands/system/doctor.js +224 -0
- package/dist/commands/system/doctor.js.map +1 -0
- package/dist/commands/system/index.d.ts +12 -0
- package/dist/commands/system/index.d.ts.map +1 -0
- package/dist/commands/system/index.js +17 -0
- package/dist/commands/system/index.js.map +1 -0
- package/dist/commands/system/validate.d.ts +47 -0
- package/dist/commands/system/validate.d.ts.map +1 -0
- package/dist/commands/system/validate.js +245 -0
- package/dist/commands/system/validate.js.map +1 -0
- package/dist/commands/token/add.d.ts +94 -0
- package/dist/commands/token/add.d.ts.map +1 -0
- package/dist/commands/token/add.js +162 -0
- package/dist/commands/token/add.js.map +1 -0
- package/dist/commands/token/catalog.d.ts +69 -0
- package/dist/commands/token/catalog.d.ts.map +1 -0
- package/dist/commands/token/catalog.js +175 -0
- package/dist/commands/token/catalog.js.map +1 -0
- package/dist/commands/token/compare.d.ts +140 -0
- package/dist/commands/token/compare.d.ts.map +1 -0
- package/dist/commands/token/compare.js +207 -0
- package/dist/commands/token/compare.js.map +1 -0
- package/dist/commands/token/copy.d.ts +31 -0
- package/dist/commands/token/copy.d.ts.map +1 -0
- package/dist/commands/token/copy.js +179 -0
- package/dist/commands/token/copy.js.map +1 -0
- package/dist/commands/token/definitions.d.ts +29 -0
- package/dist/commands/token/definitions.d.ts.map +1 -0
- package/dist/commands/token/definitions.js +63 -0
- package/dist/commands/token/definitions.js.map +1 -0
- package/dist/commands/token/index.d.ts +22 -0
- package/dist/commands/token/index.d.ts.map +1 -0
- package/dist/commands/token/index.js +44 -0
- package/dist/commands/token/index.js.map +1 -0
- package/dist/commands/token/lineage.d.ts +43 -0
- package/dist/commands/token/lineage.d.ts.map +1 -0
- package/dist/commands/token/lineage.js +187 -0
- package/dist/commands/token/lineage.js.map +1 -0
- package/dist/commands/token/matrix.d.ts +249 -0
- package/dist/commands/token/matrix.d.ts.map +1 -0
- package/dist/commands/token/matrix.js +658 -0
- package/dist/commands/token/matrix.js.map +1 -0
- package/dist/commands/token/override.d.ts +51 -0
- package/dist/commands/token/override.d.ts.map +1 -0
- package/dist/commands/token/override.js +158 -0
- package/dist/commands/token/override.js.map +1 -0
- package/dist/commands/token/previous-value.d.ts +23 -0
- package/dist/commands/token/previous-value.d.ts.map +1 -0
- package/dist/commands/token/previous-value.js +26 -0
- package/dist/commands/token/previous-value.js.map +1 -0
- package/dist/commands/token/reset.d.ts +29 -0
- package/dist/commands/token/reset.d.ts.map +1 -0
- package/dist/commands/token/reset.js +143 -0
- package/dist/commands/token/reset.js.map +1 -0
- package/dist/commands/token/resolve.d.ts +43 -0
- package/dist/commands/token/resolve.d.ts.map +1 -0
- package/dist/commands/token/resolve.js +136 -0
- package/dist/commands/token/resolve.js.map +1 -0
- package/dist/commands/token/subtract.d.ts +27 -0
- package/dist/commands/token/subtract.d.ts.map +1 -0
- package/dist/commands/token/subtract.js +129 -0
- package/dist/commands/token/subtract.js.map +1 -0
- package/dist/commands/webhooks/delete.d.ts +31 -0
- package/dist/commands/webhooks/delete.d.ts.map +1 -0
- package/dist/commands/webhooks/delete.js +94 -0
- package/dist/commands/webhooks/delete.js.map +1 -0
- package/dist/commands/webhooks/get.d.ts +50 -0
- package/dist/commands/webhooks/get.d.ts.map +1 -0
- package/dist/commands/webhooks/get.js +122 -0
- package/dist/commands/webhooks/get.js.map +1 -0
- package/dist/commands/webhooks/index.d.ts +24 -0
- package/dist/commands/webhooks/index.d.ts.map +1 -0
- package/dist/commands/webhooks/index.js +41 -0
- package/dist/commands/webhooks/index.js.map +1 -0
- package/dist/commands/webhooks/list.d.ts +72 -0
- package/dist/commands/webhooks/list.d.ts.map +1 -0
- package/dist/commands/webhooks/list.js +116 -0
- package/dist/commands/webhooks/list.js.map +1 -0
- package/dist/commands/webhooks/logs.d.ts +65 -0
- package/dist/commands/webhooks/logs.d.ts.map +1 -0
- package/dist/commands/webhooks/logs.js +138 -0
- package/dist/commands/webhooks/logs.js.map +1 -0
- package/dist/commands/webhooks/redact.d.ts +18 -0
- package/dist/commands/webhooks/redact.d.ts.map +1 -0
- package/dist/commands/webhooks/redact.js +24 -0
- package/dist/commands/webhooks/redact.js.map +1 -0
- package/dist/commands/webhooks/register.d.ts +78 -0
- package/dist/commands/webhooks/register.d.ts.map +1 -0
- package/dist/commands/webhooks/register.js +175 -0
- package/dist/commands/webhooks/register.js.map +1 -0
- package/dist/commands/webhooks/test.d.ts +32 -0
- package/dist/commands/webhooks/test.d.ts.map +1 -0
- package/dist/commands/webhooks/test.js +101 -0
- package/dist/commands/webhooks/test.js.map +1 -0
- package/dist/commands/webhooks/update.d.ts +77 -0
- package/dist/commands/webhooks/update.d.ts.map +1 -0
- package/dist/commands/webhooks/update.js +198 -0
- package/dist/commands/webhooks/update.js.map +1 -0
- package/dist/css.d.ts +3 -0
- package/dist/css.d.ts.map +1 -0
- package/dist/css.js +3 -0
- package/dist/css.js.map +1 -0
- package/dist/demo/index.d.ts +8 -0
- package/dist/demo/index.d.ts.map +1 -0
- package/dist/demo/index.js +8 -0
- package/dist/demo/index.js.map +1 -0
- package/dist/demo/realistic-system.d.ts +54 -0
- package/dist/demo/realistic-system.d.ts.map +1 -0
- package/dist/demo/realistic-system.js +919 -0
- package/dist/demo/realistic-system.js.map +1 -0
- package/dist/index.d.ts +21 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +60 -0
- package/dist/index.js.map +1 -0
- package/dist/types/command-result.d.ts +10 -0
- package/dist/types/command-result.d.ts.map +1 -0
- package/dist/types/command-result.js +11 -0
- package/dist/types/command-result.js.map +1 -0
- package/dist/types/index.d.ts +8 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/index.js +10 -0
- package/dist/types/index.js.map +1 -0
- package/dist/version.d.ts +3 -0
- package/dist/version.d.ts.map +1 -0
- package/dist/version.js +4 -0
- package/dist/version.js.map +1 -0
- package/dist/webhooks/dispatcher.d.ts +147 -0
- package/dist/webhooks/dispatcher.d.ts.map +1 -0
- package/dist/webhooks/dispatcher.js +420 -0
- package/dist/webhooks/dispatcher.js.map +1 -0
- package/dist/webhooks/index.d.ts +9 -0
- package/dist/webhooks/index.d.ts.map +1 -0
- package/dist/webhooks/index.js +9 -0
- package/dist/webhooks/index.js.map +1 -0
- package/dist/webhooks/signer.d.ts +119 -0
- package/dist/webhooks/signer.d.ts.map +1 -0
- package/dist/webhooks/signer.js +149 -0
- package/dist/webhooks/signer.js.map +1 -0
- package/dist/webhooks/url-policy.d.ts +73 -0
- package/dist/webhooks/url-policy.d.ts.map +1 -0
- package/dist/webhooks/url-policy.js +250 -0
- package/dist/webhooks/url-policy.js.map +1 -0
- package/dist/worker.d.ts +11 -0
- package/dist/worker.d.ts.map +1 -0
- package/dist/worker.js +31 -0
- package/dist/worker.js.map +1 -0
- package/package.json +84 -3
|
@@ -0,0 +1,658 @@
|
|
|
1
|
+
import { ChainTokens, InheritanceResolutionError, matchesGlob, resolveChainState, withResolutionCache, } from '@lushly-dev/violet-core/engine';
|
|
2
|
+
import { TokenCategorySchema } from '@lushly-dev/violet-core/types';
|
|
3
|
+
import { z } from 'zod';
|
|
4
|
+
import { ErrorCodes, failure, success } from '../../types/command-result.js';
|
|
5
|
+
import { validateCommand } from '../constraints/validate.js';
|
|
6
|
+
import { selectSubtree } from '../node/scope.js';
|
|
7
|
+
/**
|
|
8
|
+
* Upper bound on matrix columns. A matrix wider than this is not readable and
|
|
9
|
+
* the payload grows with nodes × tokens, so callers narrow with rootId/nodeIds.
|
|
10
|
+
*/
|
|
11
|
+
export const MAX_MATRIX_NODES = 200;
|
|
12
|
+
/** Upper bound on rows per page (`limit`) */
|
|
13
|
+
export const MAX_MATRIX_PAGE_SIZE = 5000;
|
|
14
|
+
export const MatrixGroupBySchema = z.enum(['category', 'tier']);
|
|
15
|
+
/** Row order by token id; groups (with groupBy) always stay in ascending order */
|
|
16
|
+
export const MatrixSortSchema = z.enum(['token-asc', 'token-desc']);
|
|
17
|
+
/**
|
|
18
|
+
* How a token's value arrived at a node.
|
|
19
|
+
*
|
|
20
|
+
* - add / override / copy / reset / include: the last operation on this node that
|
|
21
|
+
* set the token
|
|
22
|
+
* - inherited: the value flows unchanged from an ancestor (or an ancestor's include)
|
|
23
|
+
* - subtracted: this node removed the token
|
|
24
|
+
* - absent: the token does not exist here (never defined in this chain, or removed
|
|
25
|
+
* by an ancestor, which is reported as `source`)
|
|
26
|
+
* - unresolved: the node could not be resolved (e.g. a copy/include cycle)
|
|
27
|
+
*/
|
|
28
|
+
export const MatrixCellStateSchema = z.enum([
|
|
29
|
+
'add',
|
|
30
|
+
'override',
|
|
31
|
+
'copy',
|
|
32
|
+
'reset',
|
|
33
|
+
'include',
|
|
34
|
+
'inherited',
|
|
35
|
+
'subtracted',
|
|
36
|
+
'absent',
|
|
37
|
+
'unresolved',
|
|
38
|
+
]);
|
|
39
|
+
const LOCAL_STATES = new Set(['add', 'override', 'copy', 'reset', 'include']);
|
|
40
|
+
/**
|
|
41
|
+
* Input schema for tokens.matrix command
|
|
42
|
+
*/
|
|
43
|
+
const InputSchema = z.object({
|
|
44
|
+
rootId: z.string().min(1).optional(), // Subtree root (inclusive); defaults to every root
|
|
45
|
+
nodeIds: z.array(z.string().min(1)).min(1).max(MAX_MATRIX_NODES).optional(), // Explicit columns, in order
|
|
46
|
+
filter: z.string().optional(), // Glob pattern like "color.*"
|
|
47
|
+
category: TokenCategorySchema.optional(), // Only tokens of this category (from their metadata)
|
|
48
|
+
onlyVarying: z.boolean().optional().default(false), // Keep tokens whose value differs (see rowVaries)
|
|
49
|
+
onlyViolating: z.boolean().optional().default(false), // Keep tokens with a violation (implies includeViolations)
|
|
50
|
+
includeViolations: z.boolean().optional().default(false), // Run constraints.validate per node
|
|
51
|
+
groupBy: MatrixGroupBySchema.optional(), // Order rows by group and count each group (`groups`)
|
|
52
|
+
sort: MatrixSortSchema.optional().default('token-asc'), // Token id order (within each group)
|
|
53
|
+
summaryOnly: z.boolean().optional().default(false), // No rows: nodes, summary and groups only
|
|
54
|
+
limit: z.number().int().min(1).max(MAX_MATRIX_PAGE_SIZE).optional(), // Rows per page
|
|
55
|
+
cursor: z.string().min(1).optional(), // `page.nextCursor` or `page.prevCursor` of another page
|
|
56
|
+
around: z.string().min(1).optional(), // With limit: the page holding this token id
|
|
57
|
+
});
|
|
58
|
+
const ViolationSchema = z.object({
|
|
59
|
+
constraintId: z.string(),
|
|
60
|
+
severity: z.enum(['error', 'warning', 'info']),
|
|
61
|
+
message: z.string(),
|
|
62
|
+
});
|
|
63
|
+
const ReferenceErrorSchema = z.object({
|
|
64
|
+
code: z.enum(['TOKEN_REFERENCE_NOT_FOUND', 'CIRCULAR_REFERENCE', 'NOT_IMPLEMENTED']),
|
|
65
|
+
message: z.string(),
|
|
66
|
+
path: z.array(z.string()),
|
|
67
|
+
});
|
|
68
|
+
export const MatrixCellSchema = z.object({
|
|
69
|
+
state: MatrixCellStateSchema,
|
|
70
|
+
value: z.any().optional(), // As stored: a literal, or a reference such as { ref: 'color.brand' }
|
|
71
|
+
resolvedValue: z.union([z.string(), z.number()]).optional(), // References followed in this node
|
|
72
|
+
aliasOf: z.string().optional(), // Token the value refers to, when it is a single reference
|
|
73
|
+
referenceError: ReferenceErrorSchema.optional(), // Why the reference could not be followed
|
|
74
|
+
source: z.string().nullable(), // Node the value (or removal) came from
|
|
75
|
+
fromNode: z.string().optional(), // Copy source, included node, or reset target of a local value
|
|
76
|
+
violations: z.array(ViolationSchema).optional(),
|
|
77
|
+
});
|
|
78
|
+
/**
|
|
79
|
+
* Output schema for tokens.matrix command
|
|
80
|
+
*/
|
|
81
|
+
const OutputSchema = z.object({
|
|
82
|
+
nodes: z.array(z.object({
|
|
83
|
+
id: z.string(),
|
|
84
|
+
name: z.string(),
|
|
85
|
+
type: z.string(),
|
|
86
|
+
status: z.string(),
|
|
87
|
+
parentId: z.string().nullable(),
|
|
88
|
+
depth: z.number(),
|
|
89
|
+
error: z.string().optional(),
|
|
90
|
+
})),
|
|
91
|
+
tokens: z.array(z.object({
|
|
92
|
+
id: z.string(),
|
|
93
|
+
category: z.string(),
|
|
94
|
+
tier: z.string(),
|
|
95
|
+
varies: z.boolean(),
|
|
96
|
+
cells: z.record(z.string(), MatrixCellSchema),
|
|
97
|
+
})),
|
|
98
|
+
/** Counts over every matching row, not only this page */
|
|
99
|
+
summary: z.object({
|
|
100
|
+
nodes: z.number(),
|
|
101
|
+
tokens: z.number(),
|
|
102
|
+
varyingTokens: z.number(),
|
|
103
|
+
states: z.record(z.string(), z.number()),
|
|
104
|
+
violations: z.number(),
|
|
105
|
+
}),
|
|
106
|
+
/** With groupBy: one entry per category or tier, in row order */
|
|
107
|
+
groups: z
|
|
108
|
+
.array(z.object({
|
|
109
|
+
id: z.string(),
|
|
110
|
+
tokens: z.number(),
|
|
111
|
+
varyingTokens: z.number(),
|
|
112
|
+
violations: z.number(),
|
|
113
|
+
}))
|
|
114
|
+
.optional(),
|
|
115
|
+
/**
|
|
116
|
+
* With limit: where this page sits. Pass nextCursor (or prevCursor) as
|
|
117
|
+
* cursor for the page after (or before) it.
|
|
118
|
+
*/
|
|
119
|
+
page: z
|
|
120
|
+
.object({
|
|
121
|
+
limit: z.number(),
|
|
122
|
+
returned: z.number(),
|
|
123
|
+
/** Matching rows before this page */
|
|
124
|
+
offset: z.number(),
|
|
125
|
+
nextCursor: z.string().nullable(),
|
|
126
|
+
prevCursor: z.string().nullable(),
|
|
127
|
+
})
|
|
128
|
+
.optional(),
|
|
129
|
+
});
|
|
130
|
+
/** Sort key of a row: its group (when grouping) and its token id */
|
|
131
|
+
function rowKey(row, groupBy) {
|
|
132
|
+
return [groupBy ? row[groupBy] : '', row.id];
|
|
133
|
+
}
|
|
134
|
+
/** Row order: groups ascending, then token ids in `sort` order */
|
|
135
|
+
function compareKeys(a, b, sort) {
|
|
136
|
+
const ids = a[1].localeCompare(b[1]);
|
|
137
|
+
return a[0].localeCompare(b[0]) || (sort === 'token-desc' ? -ids : ids);
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* Opaque page cursor: the sort key of the last row on the page (or the first,
|
|
141
|
+
* for the page before it). Keyed on the row rather than an offset, so a token
|
|
142
|
+
* added between pages doesn't shift the rest by one.
|
|
143
|
+
*/
|
|
144
|
+
function encodeCursor({ groupBy, sort }, { key, before }) {
|
|
145
|
+
// base64url without Buffer, so the worker entrypoint can page too. Ascending
|
|
146
|
+
// next-page cursors leave the order and direction out, so cursors from
|
|
147
|
+
// before `sort` and `prevCursor` still work.
|
|
148
|
+
const order = sort === 'token-asc' ? {} : { s: sort };
|
|
149
|
+
const direction = before ? { d: 'before' } : {};
|
|
150
|
+
const bytes = new TextEncoder().encode(JSON.stringify({ g: groupBy ?? null, k: key, ...order, ...direction }));
|
|
151
|
+
return btoa(String.fromCharCode(...bytes))
|
|
152
|
+
.replace(/\+/g, '-')
|
|
153
|
+
.replace(/\//g, '_')
|
|
154
|
+
.replace(/=+$/, '');
|
|
155
|
+
}
|
|
156
|
+
function decodeCursor(cursor, { groupBy, sort }) {
|
|
157
|
+
try {
|
|
158
|
+
const binary = atob(cursor.replace(/-/g, '+').replace(/_/g, '/'));
|
|
159
|
+
const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
|
|
160
|
+
const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
|
|
161
|
+
const valid = parsed?.g === (groupBy ?? null) &&
|
|
162
|
+
(parsed.s ?? 'token-asc') === sort &&
|
|
163
|
+
(parsed.d === undefined || parsed.d === 'before') &&
|
|
164
|
+
Array.isArray(parsed.k) &&
|
|
165
|
+
parsed.k.length === 2 &&
|
|
166
|
+
parsed.k.every((part) => typeof part === 'string');
|
|
167
|
+
return valid ? { key: [parsed.k[0], parsed.k[1]], before: parsed.d === 'before' } : null;
|
|
168
|
+
}
|
|
169
|
+
catch {
|
|
170
|
+
return null;
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
/** Cell states, violations and (with groupBy) per-group counts over `rows` */
|
|
174
|
+
function countRows(rows, groupBy) {
|
|
175
|
+
const states = {};
|
|
176
|
+
let violationCount = 0;
|
|
177
|
+
const groups = new Map();
|
|
178
|
+
for (const row of rows) {
|
|
179
|
+
for (const state of row.states) {
|
|
180
|
+
states[state] = (states[state] ?? 0) + 1;
|
|
181
|
+
}
|
|
182
|
+
violationCount += row.violations;
|
|
183
|
+
if (groupBy) {
|
|
184
|
+
const id = row[groupBy];
|
|
185
|
+
const group = groups.get(id) ?? { id, tokens: 0, varyingTokens: 0, violations: 0 };
|
|
186
|
+
group.tokens += 1;
|
|
187
|
+
group.varyingTokens += row.varies ? 1 : 0;
|
|
188
|
+
group.violations += row.violations;
|
|
189
|
+
groups.set(id, group);
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
return { states, violationCount, groups: [...groups.values()] };
|
|
193
|
+
}
|
|
194
|
+
/**
|
|
195
|
+
* The rows of one page, at most `limit` of them, with where it sits. Pages
|
|
196
|
+
* reached with `around` start at a multiple of `limit`, where paging from the
|
|
197
|
+
* first page would put them, so a client can mix both.
|
|
198
|
+
*/
|
|
199
|
+
function pageOf(rows, order, start, limit) {
|
|
200
|
+
const { groupBy, sort } = order;
|
|
201
|
+
const keyOf = (row) => rowKey(row, groupBy);
|
|
202
|
+
let from = 0;
|
|
203
|
+
let to = rows.length;
|
|
204
|
+
if ('cursor' in start && start.cursor) {
|
|
205
|
+
const { key, before } = start.cursor;
|
|
206
|
+
const index = rows.findIndex((row) => compareKeys(keyOf(row), key, sort) >= 0);
|
|
207
|
+
const at = index < 0 ? rows.length : index;
|
|
208
|
+
if (before) {
|
|
209
|
+
to = at;
|
|
210
|
+
from = limit === undefined ? 0 : Math.max(0, to - limit);
|
|
211
|
+
}
|
|
212
|
+
else {
|
|
213
|
+
// The cursor's row may have gone since; the page starts after its key
|
|
214
|
+
from = rows[at] && compareKeys(keyOf(rows[at]), key, sort) === 0 ? at + 1 : at;
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
else if ('around' in start && limit !== undefined) {
|
|
218
|
+
from = Math.floor(start.around / limit) * limit;
|
|
219
|
+
}
|
|
220
|
+
if (limit === undefined) {
|
|
221
|
+
return { rows: rows.slice(from, to) };
|
|
222
|
+
}
|
|
223
|
+
to = Math.min(to, from + limit);
|
|
224
|
+
const pageRows = rows.slice(from, to);
|
|
225
|
+
const first = pageRows[0];
|
|
226
|
+
const last = pageRows[pageRows.length - 1];
|
|
227
|
+
return {
|
|
228
|
+
rows: pageRows,
|
|
229
|
+
page: {
|
|
230
|
+
limit,
|
|
231
|
+
returned: pageRows.length,
|
|
232
|
+
offset: from,
|
|
233
|
+
nextCursor: to < rows.length && last ? encodeCursor(order, { key: keyOf(last), before: false }) : null,
|
|
234
|
+
prevCursor: from > 0 && first ? encodeCursor(order, { key: keyOf(first), before: true }) : null,
|
|
235
|
+
},
|
|
236
|
+
};
|
|
237
|
+
}
|
|
238
|
+
/** Cell for a token this node's tree never had: absent, and no node on its chain removed it */
|
|
239
|
+
function neverDefined(cell) {
|
|
240
|
+
return cell.state === 'absent' && cell.source === null;
|
|
241
|
+
}
|
|
242
|
+
/**
|
|
243
|
+
* Whether a token's value differs between the columns.
|
|
244
|
+
*
|
|
245
|
+
* Values are compared with references followed, so two nodes that both point
|
|
246
|
+
* at `color.brand` differ when their brand colors do. A removal or a gap counts
|
|
247
|
+
* as a value of its own, but only inside a tree (columns sharing a root) where
|
|
248
|
+
* the token exists or was removed. A tree that never had the token, such as a
|
|
249
|
+
* shared set's own root, is left out, otherwise every token outside a shared
|
|
250
|
+
* set would count as varying. Unresolved columns are left out too.
|
|
251
|
+
*/
|
|
252
|
+
function rowVaries(cells) {
|
|
253
|
+
const treesWithToken = new Set(cells.filter((cell) => !neverDefined(cell)).map(({ tree }) => tree));
|
|
254
|
+
const distinct = new Set();
|
|
255
|
+
for (const { state, tree, key } of cells) {
|
|
256
|
+
if (state === 'unresolved' || !treesWithToken.has(tree)) {
|
|
257
|
+
continue;
|
|
258
|
+
}
|
|
259
|
+
distinct.add(key ?? '∅');
|
|
260
|
+
}
|
|
261
|
+
return distinct.size > 1;
|
|
262
|
+
}
|
|
263
|
+
/**
|
|
264
|
+
* Constraint violations per node, keyed by token id, from constraints.validate.
|
|
265
|
+
* Nodes that could not be resolved are skipped.
|
|
266
|
+
*/
|
|
267
|
+
async function collectViolations(context, nodes, filter) {
|
|
268
|
+
const violationsByNode = new Map();
|
|
269
|
+
for (const node of nodes) {
|
|
270
|
+
if (node.error) {
|
|
271
|
+
continue;
|
|
272
|
+
}
|
|
273
|
+
const result = await validateCommand.handler({ nodeId: node.id, filter }, context);
|
|
274
|
+
if (!result.success || !result.data) {
|
|
275
|
+
continue;
|
|
276
|
+
}
|
|
277
|
+
const byToken = new Map();
|
|
278
|
+
for (const tokenResult of result.data.results) {
|
|
279
|
+
if (tokenResult.violations.length > 0) {
|
|
280
|
+
byToken.set(tokenResult.tokenId, tokenResult.violations.map((violation) => ({
|
|
281
|
+
constraintId: violation.constraintId,
|
|
282
|
+
severity: violation.severity,
|
|
283
|
+
message: violation.message,
|
|
284
|
+
})));
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
violationsByNode.set(node.id, byToken);
|
|
288
|
+
}
|
|
289
|
+
return violationsByNode;
|
|
290
|
+
}
|
|
291
|
+
/**
|
|
292
|
+
* Walk every column's chain and count each token × node cell. Shared by
|
|
293
|
+
* tokens.matrix and nodes.graph (token trace). Rows are sorted by token id;
|
|
294
|
+
* with `tokenIds`, exactly those tokens get a row.
|
|
295
|
+
*
|
|
296
|
+
* Counting a row needs only its states and whether its values differ, so
|
|
297
|
+
* references are followed per token and cells (values, sources, violations)
|
|
298
|
+
* are built by `describe`, for the rows a caller returns (#114).
|
|
299
|
+
*/
|
|
300
|
+
export async function countTokenMatrix(context, columns, options = {}) {
|
|
301
|
+
// Every column walks the same ancestors; share reads and resolved chains
|
|
302
|
+
// across them, and with the constraints.validate calls for violations
|
|
303
|
+
const scoped = withResolutionCache(context);
|
|
304
|
+
const { db, resolutionCache: cache } = scoped;
|
|
305
|
+
// Walk each column's chain; its history tells local changes from inheritance
|
|
306
|
+
const matrixColumns = [];
|
|
307
|
+
const metadataById = new Map();
|
|
308
|
+
for (const node of columns) {
|
|
309
|
+
const ancestryChain = await cache.getAncestryChain(node.id);
|
|
310
|
+
const entry = {
|
|
311
|
+
id: node.id,
|
|
312
|
+
name: node.name,
|
|
313
|
+
type: node.type,
|
|
314
|
+
status: node.status,
|
|
315
|
+
parentId: node.parentId,
|
|
316
|
+
depth: ancestryChain.length,
|
|
317
|
+
};
|
|
318
|
+
const chain = [...ancestryChain, node.id];
|
|
319
|
+
let tokens;
|
|
320
|
+
try {
|
|
321
|
+
const state = await resolveChainState(db, node.id, ancestryChain, { cache });
|
|
322
|
+
tokens = new ChainTokens(state, chain);
|
|
323
|
+
for (const [id, token] of state.tokens) {
|
|
324
|
+
if (!metadataById.has(id)) {
|
|
325
|
+
metadataById.set(id, token.metadata);
|
|
326
|
+
}
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
catch (error) {
|
|
330
|
+
if (!(error instanceof InheritanceResolutionError)) {
|
|
331
|
+
throw error;
|
|
332
|
+
}
|
|
333
|
+
entry.error = error.message;
|
|
334
|
+
}
|
|
335
|
+
matrixColumns.push({ node: entry, chain, tokens });
|
|
336
|
+
}
|
|
337
|
+
const matrixNodes = matrixColumns.map((column) => column.node);
|
|
338
|
+
// Token ids each node subtracts, for the cells of tokens a column lacks
|
|
339
|
+
const subtractedBy = new Map();
|
|
340
|
+
const subtracted = async (nodeId) => {
|
|
341
|
+
let ids = subtractedBy.get(nodeId);
|
|
342
|
+
if (!ids) {
|
|
343
|
+
ids = new Set();
|
|
344
|
+
for (const op of await cache.getOperations(nodeId)) {
|
|
345
|
+
if (op.type === 'subtract')
|
|
346
|
+
ids.add(op.tokenId);
|
|
347
|
+
}
|
|
348
|
+
subtractedBy.set(nodeId, ids);
|
|
349
|
+
}
|
|
350
|
+
return ids;
|
|
351
|
+
};
|
|
352
|
+
// Tokens that exist somewhere but were subtracted in a column still need a row,
|
|
353
|
+
// so collect subtracted ids from the columns' own operations too
|
|
354
|
+
const rowIds = new Set(metadataById.keys());
|
|
355
|
+
for (const node of columns) {
|
|
356
|
+
for (const id of await subtracted(node.id)) {
|
|
357
|
+
rowIds.add(id);
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
const { filter } = options;
|
|
361
|
+
const { category } = options;
|
|
362
|
+
const tokenIds = (options.tokenIds ?? [...rowIds])
|
|
363
|
+
.filter((id) => !filter || matchesGlob(id, filter))
|
|
364
|
+
.filter((id) => !category || metadataById.get(id)?.category === category)
|
|
365
|
+
.sort((a, b) => a.localeCompare(b));
|
|
366
|
+
const violationsByNode = options.includeViolations
|
|
367
|
+
? await collectViolations(scoped, matrixNodes, filter)
|
|
368
|
+
: new Map();
|
|
369
|
+
/** A cell's state and the node its value (or removal) came from */
|
|
370
|
+
const locate = async (column, tokenId) => {
|
|
371
|
+
const { node, tokens } = column;
|
|
372
|
+
if (!tokens) {
|
|
373
|
+
return { state: 'unresolved', source: null };
|
|
374
|
+
}
|
|
375
|
+
const entry = tokens.entry(tokenId);
|
|
376
|
+
if (entry) {
|
|
377
|
+
let last;
|
|
378
|
+
for (const step of entry.history) {
|
|
379
|
+
if (step.nodeId === node.id)
|
|
380
|
+
last = step;
|
|
381
|
+
}
|
|
382
|
+
const state = (last?.operation ?? 'inherited');
|
|
383
|
+
const local = LOCAL_STATES.has(state);
|
|
384
|
+
return {
|
|
385
|
+
state: local ? state : 'inherited',
|
|
386
|
+
source: entry.resolvedAt,
|
|
387
|
+
...(local && last?.fromNode ? { fromNode: last.fromNode } : {}),
|
|
388
|
+
};
|
|
389
|
+
}
|
|
390
|
+
// Missing: find the nearest node on the chain that subtracted it
|
|
391
|
+
const { chain } = column;
|
|
392
|
+
for (let i = chain.length - 1; i >= 0; i--) {
|
|
393
|
+
if ((await subtracted(chain[i])).has(tokenId)) {
|
|
394
|
+
return chain[i] === node.id
|
|
395
|
+
? { state: 'subtracted', source: node.id }
|
|
396
|
+
: { state: 'absent', source: chain[i] };
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
return { state: 'absent', source: null };
|
|
400
|
+
};
|
|
401
|
+
const rows = [];
|
|
402
|
+
// Kept for describe, so a described row doesn't look its cells up again
|
|
403
|
+
const locations = new Map();
|
|
404
|
+
for (const tokenId of tokenIds) {
|
|
405
|
+
const states = [];
|
|
406
|
+
const located = [];
|
|
407
|
+
const compared = [];
|
|
408
|
+
let violations = 0;
|
|
409
|
+
for (const column of matrixColumns) {
|
|
410
|
+
const location = await locate(column, tokenId);
|
|
411
|
+
const { state, source } = location;
|
|
412
|
+
located.push(location);
|
|
413
|
+
states.push(state);
|
|
414
|
+
const { tokens } = column;
|
|
415
|
+
const entry = tokens?.entry(tokenId);
|
|
416
|
+
// Only a cell with a value carries violations (see describeCell)
|
|
417
|
+
if (entry) {
|
|
418
|
+
violations += violationsByNode.get(column.node.id)?.get(tokenId)?.length ?? 0;
|
|
419
|
+
}
|
|
420
|
+
const value = entry ? (tokens?.finalValue(tokenId) ?? entry.value) : undefined;
|
|
421
|
+
compared.push({
|
|
422
|
+
state,
|
|
423
|
+
source,
|
|
424
|
+
tree: column.chain[0],
|
|
425
|
+
key: value === undefined ? null : JSON.stringify(value),
|
|
426
|
+
});
|
|
427
|
+
}
|
|
428
|
+
locations.set(tokenId, located);
|
|
429
|
+
const metadata = metadataById.get(tokenId);
|
|
430
|
+
rows.push({
|
|
431
|
+
id: tokenId,
|
|
432
|
+
category: metadata?.category ?? 'custom',
|
|
433
|
+
tier: metadata?.tier ?? 'semantic',
|
|
434
|
+
varies: rowVaries(compared),
|
|
435
|
+
states,
|
|
436
|
+
violations,
|
|
437
|
+
});
|
|
438
|
+
}
|
|
439
|
+
const describeCell = (column, tokenId, located) => {
|
|
440
|
+
const token = column.tokens?.token(tokenId);
|
|
441
|
+
if (!token) {
|
|
442
|
+
return { state: located.state, source: located.source };
|
|
443
|
+
}
|
|
444
|
+
const cell = {
|
|
445
|
+
state: located.state,
|
|
446
|
+
value: token.value,
|
|
447
|
+
resolvedValue: token.resolvedValue,
|
|
448
|
+
...(token.aliasOf ? { aliasOf: token.aliasOf } : {}),
|
|
449
|
+
...(token.referenceError ? { referenceError: token.referenceError } : {}),
|
|
450
|
+
source: located.source,
|
|
451
|
+
};
|
|
452
|
+
if (located.fromNode) {
|
|
453
|
+
cell.fromNode = located.fromNode;
|
|
454
|
+
}
|
|
455
|
+
const violations = violationsByNode.get(column.node.id)?.get(tokenId);
|
|
456
|
+
if (violations) {
|
|
457
|
+
cell.violations = violations;
|
|
458
|
+
}
|
|
459
|
+
return cell;
|
|
460
|
+
};
|
|
461
|
+
const byId = new Map(rows.map((row) => [row.id, row]));
|
|
462
|
+
const describe = async (ids) => {
|
|
463
|
+
const described = [];
|
|
464
|
+
for (const id of ids) {
|
|
465
|
+
const row = byId.get(id);
|
|
466
|
+
const located = locations.get(id);
|
|
467
|
+
if (!row || !located)
|
|
468
|
+
continue;
|
|
469
|
+
const cells = {};
|
|
470
|
+
matrixColumns.forEach((column, index) => {
|
|
471
|
+
cells[column.node.id] = describeCell(column, id, located[index]);
|
|
472
|
+
});
|
|
473
|
+
described.push({
|
|
474
|
+
id: row.id,
|
|
475
|
+
category: row.category,
|
|
476
|
+
tier: row.tier,
|
|
477
|
+
varies: row.varies,
|
|
478
|
+
cells,
|
|
479
|
+
});
|
|
480
|
+
}
|
|
481
|
+
return described;
|
|
482
|
+
};
|
|
483
|
+
return { nodes: matrixNodes, rows, describe };
|
|
484
|
+
}
|
|
485
|
+
/**
|
|
486
|
+
* Every row of a matrix with its cells described, for callers that compare
|
|
487
|
+
* whole matrices (tokens.compare, changes.impact).
|
|
488
|
+
*/
|
|
489
|
+
export async function computeTokenMatrix(context, columns, options = {}) {
|
|
490
|
+
const matrix = await countTokenMatrix(context, columns, options);
|
|
491
|
+
return { nodes: matrix.nodes, rows: await matrix.describe(matrix.rows.map((row) => row.id)) };
|
|
492
|
+
}
|
|
493
|
+
/**
|
|
494
|
+
* tokens.matrix command
|
|
495
|
+
*
|
|
496
|
+
* Resolve tokens across many nodes at once and report, for every token × node
|
|
497
|
+
* cell, the value and how it got there. Powers the Matrix view and answers
|
|
498
|
+
* "what is this token everywhere?" in one call.
|
|
499
|
+
*/
|
|
500
|
+
export const tokensMatrixCommand = {
|
|
501
|
+
name: 'tokens.matrix',
|
|
502
|
+
description: 'Resolve tokens across many nodes and show how each value got there',
|
|
503
|
+
category: 'token',
|
|
504
|
+
inputSchema: InputSchema,
|
|
505
|
+
outputSchema: OutputSchema,
|
|
506
|
+
async handler(rawInput, context) {
|
|
507
|
+
const { db } = context;
|
|
508
|
+
// Parse input to apply defaults
|
|
509
|
+
const input = InputSchema.parse(rawInput);
|
|
510
|
+
if (input.rootId && input.nodeIds) {
|
|
511
|
+
return failure({
|
|
512
|
+
code: ErrorCodes.VALIDATION_ERROR,
|
|
513
|
+
message: 'Use either rootId or nodeIds, not both',
|
|
514
|
+
suggestion: 'Pass rootId for a subtree, nodeIds for explicit columns, or neither for all nodes',
|
|
515
|
+
});
|
|
516
|
+
}
|
|
517
|
+
// Pick the columns
|
|
518
|
+
let columns;
|
|
519
|
+
if (input.nodeIds) {
|
|
520
|
+
columns = [];
|
|
521
|
+
for (const nodeId of input.nodeIds) {
|
|
522
|
+
const node = await db.getNode(nodeId);
|
|
523
|
+
if (!node || node.deletedAt) {
|
|
524
|
+
return failure({
|
|
525
|
+
code: ErrorCodes.NODE_NOT_FOUND,
|
|
526
|
+
message: `Node '${nodeId}' not found`,
|
|
527
|
+
suggestion: `Use 'node.list' to see available nodes`,
|
|
528
|
+
});
|
|
529
|
+
}
|
|
530
|
+
columns.push(node);
|
|
531
|
+
}
|
|
532
|
+
}
|
|
533
|
+
else {
|
|
534
|
+
const scope = await selectSubtree(db, input.rootId);
|
|
535
|
+
if (!scope) {
|
|
536
|
+
return failure({
|
|
537
|
+
code: ErrorCodes.NODE_NOT_FOUND,
|
|
538
|
+
message: `Node '${input.rootId}' not found`,
|
|
539
|
+
suggestion: `Use 'node.list' to see available nodes`,
|
|
540
|
+
});
|
|
541
|
+
}
|
|
542
|
+
columns = scope;
|
|
543
|
+
}
|
|
544
|
+
const order = { groupBy: input.groupBy, sort: input.sort };
|
|
545
|
+
const cursor = input.cursor ? decodeCursor(input.cursor, order) : undefined;
|
|
546
|
+
if (cursor === null) {
|
|
547
|
+
return failure({
|
|
548
|
+
code: ErrorCodes.VALIDATION_ERROR,
|
|
549
|
+
message: 'cursor is not a page cursor for this groupBy and sort',
|
|
550
|
+
suggestion: 'Pass page.nextCursor or page.prevCursor from another page with the same groupBy and sort, or leave cursor out for the first page',
|
|
551
|
+
});
|
|
552
|
+
}
|
|
553
|
+
if (input.around && (input.cursor || input.limit === undefined)) {
|
|
554
|
+
return failure({
|
|
555
|
+
code: ErrorCodes.VALIDATION_ERROR,
|
|
556
|
+
message: input.cursor
|
|
557
|
+
? 'Use either around or cursor, not both'
|
|
558
|
+
: 'around picks a page, so it needs limit',
|
|
559
|
+
suggestion: 'Pass around with limit (and no cursor) to get the page holding a token, then page on with its cursors',
|
|
560
|
+
});
|
|
561
|
+
}
|
|
562
|
+
if (columns.length > MAX_MATRIX_NODES) {
|
|
563
|
+
return failure({
|
|
564
|
+
code: ErrorCodes.VALIDATION_ERROR,
|
|
565
|
+
message: `Matrix would have ${columns.length} nodes (max ${MAX_MATRIX_NODES})`,
|
|
566
|
+
suggestion: 'Narrow the matrix with rootId (a subtree) or nodeIds (explicit columns)',
|
|
567
|
+
});
|
|
568
|
+
}
|
|
569
|
+
const matrix = await countTokenMatrix(context, columns, {
|
|
570
|
+
filter: input.filter,
|
|
571
|
+
category: input.category,
|
|
572
|
+
includeViolations: input.includeViolations || input.onlyViolating,
|
|
573
|
+
});
|
|
574
|
+
const matrixNodes = matrix.nodes;
|
|
575
|
+
const { groupBy } = input;
|
|
576
|
+
const rows = matrix.rows.filter((row) => (!input.onlyVarying || row.varies) && (!input.onlyViolating || row.violations > 0));
|
|
577
|
+
if (groupBy || input.sort !== 'token-asc') {
|
|
578
|
+
rows.sort((a, b) => compareKeys(rowKey(a, groupBy), rowKey(b, groupBy), input.sort));
|
|
579
|
+
}
|
|
580
|
+
const { states, violationCount, groups } = countRows(rows, groupBy);
|
|
581
|
+
const varyingTokens = rows.filter((row) => row.varies).length;
|
|
582
|
+
const unresolved = matrixNodes.filter((node) => node.error).length;
|
|
583
|
+
const unresolvedNote = unresolved > 0 ? `; ${unresolved} node(s) could not be resolved` : '';
|
|
584
|
+
let start = cursor ? { cursor } : {};
|
|
585
|
+
if (input.around && !input.summaryOnly) {
|
|
586
|
+
const index = rows.findIndex((row) => row.id === input.around);
|
|
587
|
+
if (index < 0) {
|
|
588
|
+
return failure({
|
|
589
|
+
code: ErrorCodes.TOKEN_NOT_FOUND,
|
|
590
|
+
message: `Token '${input.around}' is not among the matching rows`,
|
|
591
|
+
suggestion: 'Check the token id, or loosen filter, category, onlyVarying or onlyViolating so its row matches',
|
|
592
|
+
});
|
|
593
|
+
}
|
|
594
|
+
start = { around: index };
|
|
595
|
+
}
|
|
596
|
+
// Summary and groups count every row; only the page's cells are described
|
|
597
|
+
const { rows: pageCounts, page } = input.summaryOnly
|
|
598
|
+
? { rows: [], page: undefined }
|
|
599
|
+
: pageOf(rows, order, start, input.limit);
|
|
600
|
+
const pageRows = await matrix.describe(pageCounts.map((row) => row.id));
|
|
601
|
+
const pageNote = page
|
|
602
|
+
? `; returned ${pageRows.length} from row ${page.offset + 1}${page.nextCursor ? ', more after page.nextCursor' : ''}`
|
|
603
|
+
: input.summaryOnly
|
|
604
|
+
? '; rows left out (summaryOnly)'
|
|
605
|
+
: '';
|
|
606
|
+
return success({
|
|
607
|
+
nodes: matrixNodes,
|
|
608
|
+
tokens: pageRows,
|
|
609
|
+
summary: {
|
|
610
|
+
nodes: matrixNodes.length,
|
|
611
|
+
tokens: rows.length,
|
|
612
|
+
varyingTokens,
|
|
613
|
+
states,
|
|
614
|
+
violations: violationCount,
|
|
615
|
+
},
|
|
616
|
+
...(groupBy ? { groups: [...groups.values()] } : {}),
|
|
617
|
+
...(page ? { page } : {}),
|
|
618
|
+
}, {
|
|
619
|
+
reasoning: `Resolved ${rows.length} token(s) across ${matrixNodes.length} node(s); ${varyingTokens} vary between nodes${pageNote}${unresolvedNote}`,
|
|
620
|
+
sources: matrixNodes.map((node) => ({ type: 'node', id: node.id, title: node.name })),
|
|
621
|
+
});
|
|
622
|
+
},
|
|
623
|
+
examples: [
|
|
624
|
+
{
|
|
625
|
+
description: 'Every token across every node',
|
|
626
|
+
input: {},
|
|
627
|
+
},
|
|
628
|
+
{
|
|
629
|
+
description: 'Color tokens across the xbox subtree',
|
|
630
|
+
input: { rootId: 'xbox', filter: 'color.*' },
|
|
631
|
+
},
|
|
632
|
+
{
|
|
633
|
+
description: 'Token counts per category, without rows, to load one category at a time',
|
|
634
|
+
input: { groupBy: 'category', summaryOnly: true },
|
|
635
|
+
},
|
|
636
|
+
{
|
|
637
|
+
description: 'The first 200 color tokens across every node; pass page.nextCursor for more',
|
|
638
|
+
input: { category: 'color', limit: 200 },
|
|
639
|
+
},
|
|
640
|
+
{
|
|
641
|
+
description: 'The page of 100 color tokens holding color.text.primary, for a link to it',
|
|
642
|
+
input: { category: 'color', limit: 100, around: 'color.text.primary' },
|
|
643
|
+
},
|
|
644
|
+
{
|
|
645
|
+
description: 'Rows grouped by category, token ids in reverse order within each group',
|
|
646
|
+
input: { groupBy: 'category', sort: 'token-desc' },
|
|
647
|
+
},
|
|
648
|
+
{
|
|
649
|
+
description: 'Only tokens that differ between three nodes, with constraint violations',
|
|
650
|
+
input: {
|
|
651
|
+
nodeIds: ['xbox-ios', 'xbox-android', 'xbox-ios-dark'],
|
|
652
|
+
onlyVarying: true,
|
|
653
|
+
includeViolations: true,
|
|
654
|
+
},
|
|
655
|
+
},
|
|
656
|
+
],
|
|
657
|
+
};
|
|
658
|
+
//# sourceMappingURL=matrix.js.map
|