@parity-app/cli 0.4.0 → 0.5.1

package/dist/bin.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { _ as errorDetails, a as describeExec, c as describeProps, f as setCaller, g as errorCodes, h as closest, i as describeConsole, l as describeStatus, m as CodedError, n as describeAccessibility, o as describeModes, p as mcpCallerName, r as describeComponents, s as describeProblems, t as call, u as describeTokens, v as readErrorDetails } from "./client-Cf66-n3R.mjs";
+import { a as errorCodes, i as closest, o as errorDetails, r as CodedError, s as readErrorDetails } from "./schema-BpGSCLEu.mjs";
+import { a as describeExec, c as describeProps, f as setCaller, i as describeConsole, l as describeStatus, n as describeAccessibility, o as describeModes, p as mcpCallerName, r as describeComponents, s as describeProblems, t as call, u as describeTokens } from "./client-CoW-KcnT.mjs";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 import { dirname, join, normalize, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
@@ -99,6 +100,120 @@ function structuredExec(result) {
 		screenshots: result.screenshots.map(({ png: _png, ...shot }) => shot)
 	};
 }
+const screenshotSchema = {
+	type: "object",
+	properties: {
+		path: {
+			type: "string",
+			description: "Where the PNG was saved."
+		},
+		design: { type: "string" },
+		state: { type: "string" },
+		mode: { type: "string" }
+	},
+	required: [
+		"path",
+		"design",
+		"state",
+		"mode"
+	]
+};
+const strings$1 = {
+	type: "array",
+	items: { type: "string" }
+};
+const discardedSchema = {
+	type: "array",
+	description: "Patches each Replace threw away with the node it swapped out. Present only when there were some; reapply what's still wanted to the replacement with Responsive, Update with a state, or UpdateState.",
+	items: {
+		type: "object",
+		properties: {
+			design: { type: "string" },
+			replaced: {
+				type: "string",
+				description: "The node Replace swapped out."
+			},
+			replacement: {
+				type: "string",
+				description: "The node that took its place."
+			},
+			nodes: {
+				type: "array",
+				items: {
+					type: "object",
+					properties: {
+						id: {
+							type: "string",
+							description: "The old node's id, or instance/inner path."
+						},
+						name: { type: "string" },
+						viewports: {
+							...strings$1,
+							description: "Viewport ids it had responsive patches for."
+						},
+						states: {
+							...strings$1,
+							description: "State ids it had patches in."
+						},
+						variants: {
+							...strings$1,
+							description: "Variant options it had patches in, as param=option."
+						}
+					},
+					required: ["id"]
+				}
+			}
+		},
+		required: [
+			"design",
+			"replaced",
+			"replacement",
+			"nodes"
+		]
+	}
+};
+const warningGroupsSchema = {
+	type: "array",
+	description: "The warnings as data, in the same order: each finding once, with how many places and which. Errors come first, then warnings, then suggestions.",
+	items: {
+		type: "object",
+		properties: {
+			category: {
+				type: "string",
+				description: "Stable: render_failed, unknown_component, unknown_component_design, unknown_prop, invalid_option, not_a_token, not_a_length_token, overlap, kind_changed or unnamed_layout."
+			},
+			severity: {
+				type: "string",
+				enum: [
+					"error",
+					"warning",
+					"suggestion"
+				],
+				description: "error: a render failed, so a check or screenshot is missing. suggestion: worth doing, not wrong."
+			},
+			message: {
+				type: "string",
+				description: "What's wrong and what to do about it."
+			},
+			count: {
+				type: "integer",
+				minimum: 1,
+				description: "How many places it was found."
+			},
+			at: {
+				...strings$1,
+				description: "Every place: a node's design/node path, or a frame. Empty for a whole board."
+			}
+		},
+		required: [
+			"category",
+			"severity",
+			"message",
+			"count",
+			"at"
+		]
+	}
+};
 /** Execute's and screenshot's structured result. */
 const execOutputSchema = {
 	type: "object",
@@ -114,34 +229,19 @@ const execOutputSchema = {
 			description: "Lines from Print."
 		},
 		warnings: {
-			type: "array",
-			items: { type: "string" }
+			...strings$1,
+			description: "One line per warning group, places first."
 		},
+		warningGroups: warningGroupsSchema,
 		created: {
 			type: "object",
 			additionalProperties: { type: "string" },
 			description: "Names of designs and nodes created, mapped to their ids."
 		},
+		discarded: discardedSchema,
 		screenshots: {
 			type: "array",
-			items: {
-				type: "object",
-				properties: {
-					path: {
-						type: "string",
-						description: "Where the PNG was saved."
-					},
-					design: { type: "string" },
-					state: { type: "string" },
-					mode: { type: "string" }
-				},
-				required: [
-					"path",
-					"design",
-					"state",
-					"mode"
-				]
-			}
+			items: screenshotSchema
 		},
 		error: operationErrorSchema
 	},
@@ -287,8 +387,8 @@ const executeOperation = {
 */
 async function runCheck(library, options) {
 	if (!library) throw new Error("parity lib check <library> [--tab t] [--mode m]");
-	const { applyLibraryEdits, componentNode, generateId, librarySource, parseLibraryEdits, withLibraryContext } = await import("./src-DgI96EpD.mjs");
-	const { registryDir, registryEntries } = await import("./src-CJUvccJO.mjs");
+	const { applyLibraryEdits, componentNode, generateId, librarySource, parseLibraryEdits, withLibraryContext } = await import("./src-p0vFxRBz.mjs");
+	const { registryDir, registryEntries } = await import("./src-Cr8pfFJE.mjs");
 	const entry = (await registryEntries()).find((item) => item.manifest.id === library);
 	if (!entry) throw new Error(`The registry has no library "${library}"`);
 	let manifest = entry.manifest;
@@ -416,8 +516,8 @@ function describeCheck(report) {
 * because it reads the project's files and its own copy of TypeScript.
 */
 async function runLib(packageName, options) {
-	const { appManifestPath, generateLibrary, manifestText, mergeManifest, reviseLibrary } = await import("./src-DaCYZuwb.mjs");
-	const { covers, registryDir, registryEntries } = await import("./src-CJUvccJO.mjs");
+	const { appManifestPath, generateLibrary, manifestText, mergeManifest, reviseLibrary } = await import("./src-Zm_PYFFH.mjs");
+	const { covers, registryDir, registryEntries } = await import("./src-Cr8pfFJE.mjs");
 	const spec = packageName === void 0 ? void 0 : packageSpec(packageName);
 	let root = resolve(options.root ?? ".");
 	if (spec && (spec.version !== void 0 || options.registry && !options.root)) {
@@ -428,7 +528,7 @@ async function runLib(packageName, options) {
 		console.error(`Installing ${spec.name} ${version} on its own…`);
 		root = await installedVersion(spec.name, version);
 	}
-	const { parseLibraryEdits } = await import("./src-DaCYZuwb.mjs");
+	const { parseLibraryEdits } = await import("./src-Zm_PYFFH.mjs");
 	const trialEdits = options.edits ? parseLibraryEdits(JSON.parse(await readFile(resolve(options.edits), "utf8"))) : void 0;
 	const recordedId = options.registry && spec ? options.id ?? (await registryEntries()).find((entry) => entry.manifest.package?.name === spec.name)?.manifest.id : void 0;
 	const appErrors = recordedId ? await readAppErrors(registryDir(), recordedId) : void 0;
@@ -778,6 +878,13 @@ const frameSchema = {
 	state: string,
 	mode: string
 };
+const number = { type: "number" };
+const boxSchema = object({
+	x: number,
+	y: number,
+	width: number,
+	height: number
+});
 const designSchema = object({
 	id: string,
 	name: string,
@@ -899,9 +1006,44 @@ const problemsSchema = object({
 		type: "array",
 		items: object({
 			...frameSchema,
+			kind: {
+				type: "string",
+				enum: [
+					"render-error",
+					"unknown-component",
+					"content-wider",
+					"frame-overflow",
+					"clipped"
+				]
+			},
 			problem: string,
-			node: string
-		}, ["node"])
+			node: string,
+			name: string,
+			box: boxSchema,
+			container: object({
+				node: string,
+				name: string,
+				box: boxSchema
+			}, ["node", "name"]),
+			overflow: object({
+				left: number,
+				right: number,
+				top: number,
+				bottom: number
+			}, [
+				"left",
+				"right",
+				"top",
+				"bottom"
+			])
+		}, [
+			"kind",
+			"node",
+			"name",
+			"box",
+			"container",
+			"overflow"
+		])
 	},
 	frames: integer,
 	warnings: strings
@@ -1002,8 +1144,86 @@ const propsSchema = object({
 			"default",
 			"required"
 		])
-	}
-}, ["path", "import"]);
+	},
+	composition: object({
+		role: {
+			type: "string",
+			enum: [
+				"provider",
+				"wrapper",
+				"component"
+			],
+			description: "provider draws nothing and gives parts inside it context; wrapper draws and holds other parts."
+		},
+		parents: object({
+			status: {
+				type: "string",
+				enum: [
+					"listed",
+					"none",
+					"unknown"
+				],
+				description: "listed: insert it inside chain; none: it needs nothing; unknown: nothing says, see reason."
+			},
+			chain: {
+				type: "array",
+				description: "Outermost first.",
+				items: object({
+					component: string,
+					optional: boolean_
+				}, ["optional"])
+			},
+			from: {
+				...string,
+				description: "What said so, such as the library's examples or the error it throws."
+			},
+			reason: string
+		}, [
+			"chain",
+			"from",
+			"reason"
+		]),
+		holds: {
+			...strings,
+			description: "Parts that go directly inside it."
+		},
+		slots: {
+			type: "array",
+			items: object({
+				name: string,
+				key: string,
+				kind: {
+					type: "string",
+					enum: [
+						"children",
+						"element",
+						"render"
+					]
+				}
+			})
+		},
+		example: object({
+			node: {
+				type: "object",
+				description: "A node Insert takes as it is: the component inside its parents."
+			},
+			status: {
+				type: "string",
+				enum: [
+					"drawn",
+					"failing",
+					"untried"
+				],
+				description: "Whether the component has drawn on the canvas."
+			},
+			reason: string
+		}, ["reason"])
+	})
+}, [
+	"path",
+	"import",
+	"composition"
+]);
 const viewportSchema = object({
 	id: string,
 	name: string,
@@ -1334,13 +1554,13 @@ const tools = [
 		}
 	},
 	operationTool("screenshot", "Capture a design in any of its states and modes, rendered offscreen at real widths. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.screenshot, (result) => [text(describeExec(result)), ...result.screenshots.map((shot) => image(shot.png))]),
-	operationTool("find_problems", "Find layout problems in a design, rendered offscreen in every state and the modes it shows unless you narrow it: render errors, content wider than the frame, nodes cut off by a parent that clips, and components that aren't the project's. Run it after changes, with screenshot. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.problems, (result) => [text(describeProblems(result))]),
-	operationTool("check_accessibility", "Check a design's accessibility with axe-core against WCAG 2.2 AA, rendered offscreen in every state and the modes it shows unless you narrow it. Lists each rule broken, worst first, with the layers that break it (ids you can pass to execute), the frames, what's wrong and a link on how to fix it. state and mode take an id, a list, or \"all\"; mode also takes \"shown\". Automated checks find some issues, not all.", operations.accessibility, (result) => [text(describeAccessibility(result))]),
+	operationTool("find_problems", "Find layout problems in a design, rendered offscreen in every state and the modes it shows unless you narrow it: render errors, nodes that stick out of the frame, nodes cut off by an ancestor that clips, and components that aren't the project's. Each layout finding names the node and what it overflows, with both boxes and how far past each edge. Run it after changes, with screenshot. state and mode take an id, a list, or \"all\"; mode also takes \"shown\".", operations.problems, (result) => [text(describeProblems(result))]),
+	operationTool("check_accessibility", "Check a design's accessibility with axe-core against WCAG 2.2 AA, rendered offscreen in every state and the modes it shows unless you narrow it. Lists each rule broken, worst first, with the layers that break it (ids you can pass to execute), the frames, what's wrong and a link on how to fix it. A contrast failure names the color token to set as style.foreground so it passes in every frame checked, when one does. state and mode take an id, a list, or \"all\"; mode also takes \"shown\". Automated checks find some issues, not all.", operations.accessibility, (result) => [text(describeAccessibility(result))]),
 	operationTool("get_console", "Read what the project's own code wrote to the console: errors, warnings and logs from its components on the canvas, including while the person interacts with them, and from offscreen renders such as screenshots. Oldest first; the same message several times in a row is counted once. clear: true empties it after reading, so the next read shows only what's new.", operations.console, (result) => [text(describeConsole(result))]),
 	operationTool("open_project", "Open a project folder in a new Parity tab, or switch to it if it's already open.", operations.open, json),
 	operationTool("get_tokens", "Read tokens filtered by category, source or name, with values in every theme.", operations.tokens, (result) => [text(describeTokens(result))]),
 	operationTool("get_components", "List project components, libraries, icon sets and exports that were left out or failed to render.", operations.components, (result) => [text(describeComponents(result))]),
-	operationTool("get_props", "Read a component's props from source. all includes attributes it passes through.", operations.props, (result) => [text(describeProps(result))]),
+	operationTool("get_props", "Read a component's props from source, and its composition: the parents or provider it goes inside, the parts it holds, its slots and an example node to insert. all includes attributes it passes through.", operations.props, (result) => [text(describeProps(result))]),
 	{
 		name: "read_skill",
 		description: "Read the Parity design skill or a file it references.",
@@ -1465,7 +1685,8 @@ const usage = `parity: drive the Parity app from a terminal or an agent
                                             unless --limit says
   parity components [--tab t]               the components designs can use, by library
   parity props <Component> [--all] [--tab t]
-                                            a component's props from its source; --all adds the attributes it passes on
+                                            a component's props from its source, then what it goes inside and holds,
+                                            with an example to insert; --all adds the attributes it passes on
   parity lib [package] [--root dir] [--out file|-] [--registry] [--id id] [--name n] [--range r] [--json]
        [--only new|all|A,B] [--edits file] [--no-examples] [--no-tags]
                                             write a .lib.par: a package's components, tokens, breakpoints, icons and