@gxp-dev/tools 2.0.71 → 2.0.72

package/bin/lib/lint/index.js

@@ -0,0 +1,284 @@
+/**
+ * GxP JSON Config Linter
+ *
+ * Validates `configuration.json` and `app-manifest.json` against JSON Schemas
+ * derived from the GxP templating system documentation. Schemas live in
+ * ./schemas/ and are composed via $ref.
+ *
+ * Public API:
+ *   - detectSchema(filePath): pick the correct schema for a file, or null.
+ *   - lintFile(filePath): return { file, ok, errors[] }.
+ *   - lintFiles(files): return aggregated results.
+ */
+
+const fs = require("fs")
+const path = require("path")
+const Ajv = require("ajv/dist/2020")
+const addFormats = require("ajv-formats")
+
+const SCHEMA_DIR = path.join(__dirname, "schemas")
+
+const SCHEMA_FILES = [
+	"common.schema.json",
+	"field.schema.json",
+	"card.schema.json",
+	"configuration.schema.json",
+	"app-manifest.schema.json",
+]
+
+let cachedAjv = null
+
+function getAjv() {
+	if (cachedAjv) {
+		return cachedAjv
+	}
+	const ajv = new Ajv({
+		allErrors: true,
+		strict: false,
+		allowUnionTypes: true,
+		verbose: true,
+	})
+	addFormats(ajv)
+
+	for (const fileName of SCHEMA_FILES) {
+		const schemaPath = path.join(SCHEMA_DIR, fileName)
+		const schema = JSON.parse(fs.readFileSync(schemaPath, "utf-8"))
+		// Reference schemas by their bare filename (how siblings $ref each other).
+		ajv.addSchema(schema, fileName)
+	}
+
+	cachedAjv = ajv
+	return ajv
+}
+
+/**
+ * Given a file path, decide which root schema should validate it.
+ * Matches exact filenames `configuration.json` / `app-manifest.json` and also
+ * suffixed variants like `broken-configuration.json` so users can keep multiple
+ * samples around during development. Returns the schema filename or null.
+ */
+function detectSchema(filePath) {
+	const base = path.basename(filePath)
+	if (base === "configuration.json" || /configuration\.json$/i.test(base)) {
+		return "configuration.schema.json"
+	}
+	if (base === "app-manifest.json" || /app-manifest\.json$/i.test(base)) {
+		return "app-manifest.schema.json"
+	}
+	return null
+}
+
+/**
+ * Walk a JSON document by dotted/bracketed pointer to locate a value.
+ * Falls back to the document start if the path is unresolvable — good enough
+ * for error location heuristics; the AJV path is always printed too.
+ */
+function locateInSource(source, instancePath) {
+	if (!instancePath || instancePath === "") {
+		return { line: 1, column: 1 }
+	}
+
+	// Split AJV 2020-12 JSON pointer: "/additionalTabs/0/cards/1/fieldsList/0/type"
+	const segments = instancePath.split("/").filter(Boolean)
+	let cursor = 0
+	let line = 1
+	let column = 1
+
+	// Simple forward scanner: find each segment's appearance after current cursor.
+	// Good enough for error pinpointing; not a full JSON parser.
+	for (const rawSegment of segments) {
+		const segment = decodeURIComponent(
+			rawSegment.replace(/~1/g, "/").replace(/~0/g, "~"),
+		)
+		let needle
+		if (/^\d+$/.test(segment)) {
+			// Array index — scan forward to the Nth top-level "," or "[" after cursor.
+			// Cheap approximation: skip.
+			needle = null
+		} else {
+			needle = `"${segment}"`
+		}
+		if (needle) {
+			const next = source.indexOf(needle, cursor)
+			if (next >= 0) {
+				cursor = next + needle.length
+			}
+		}
+	}
+
+	for (let i = 0; i < cursor && i < source.length; i++) {
+		if (source[i] === "\n") {
+			line++
+			column = 1
+		} else {
+			column++
+		}
+	}
+	return { line, column }
+}
+
+/**
+ * Lint a single file. Returns a result object; never throws for validation or
+ * JSON-parse errors (those become errors in the result).
+ */
+function lintFile(filePath) {
+	const absPath = path.resolve(filePath)
+	const result = {
+		file: absPath,
+		ok: true,
+		skipped: false,
+		reason: null,
+		errors: [],
+	}
+
+	if (!fs.existsSync(absPath)) {
+		result.ok = false
+		result.errors.push({
+			code: "file-not-found",
+			message: `File not found: ${absPath}`,
+			line: 1,
+			column: 1,
+			instancePath: "",
+		})
+		return result
+	}
+
+	const schemaKey = detectSchema(absPath)
+	if (!schemaKey) {
+		result.skipped = true
+		result.reason = "no-schema-for-filename"
+		return result
+	}
+
+	const source = fs.readFileSync(absPath, "utf-8")
+	let data
+	try {
+		data = JSON.parse(source)
+	} catch (e) {
+		result.ok = false
+		result.errors.push({
+			code: "json-parse-error",
+			message: `Invalid JSON: ${e.message}`,
+			line: 1,
+			column: 1,
+			instancePath: "",
+		})
+		return result
+	}
+
+	const ajv = getAjv()
+	const validate = ajv.getSchema(schemaKey)
+	const valid = validate(data)
+	if (!valid) {
+		result.ok = false
+		const seen = new Set()
+		for (const err of validate.errors || []) {
+			// Drop AJV's meta-errors that just restate "a nested if/then failed" —
+			// the real cause is the nested error itself, which we also have.
+			if (err.keyword === "if" || err.keyword === "allOf") {
+				continue
+			}
+			// Collapse duplicates that AJV emits when an inner schema is reached
+			// via multiple schemaPaths (e.g. through if/then and directly).
+			const dedupeKey = `${err.keyword}|${err.instancePath}|${err.params?.missingProperty || ""}|${err.params?.additionalProperty || ""}|${err.params?.allowedValue || ""}`
+			if (seen.has(dedupeKey)) {
+				continue
+			}
+			seen.add(dedupeKey)
+
+			const { line, column } = locateInSource(source, err.instancePath)
+			result.errors.push({
+				code: err.keyword,
+				message: formatAjvMessage(err),
+				line,
+				column,
+				instancePath: err.instancePath || "/",
+				schemaPath: err.schemaPath,
+				params: err.params,
+			})
+		}
+	}
+	return result
+}
+
+function formatAjvMessage(err) {
+	const at = err.instancePath || "(root)"
+	const core = err.message || "failed validation"
+	const hints = []
+	if (err.keyword === "enum" && err.params?.allowedValues) {
+		hints.push(`allowed: ${err.params.allowedValues.join(", ")}`)
+	}
+	if (err.keyword === "required" && err.params?.missingProperty) {
+		return `${at} missing required property "${err.params.missingProperty}"`
+	}
+	if (err.keyword === "type" && err.params?.type) {
+		return `${at} must be ${err.params.type}`
+	}
+	if (
+		err.keyword === "additionalProperties" &&
+		err.params?.additionalProperty
+	) {
+		return `${at} has unexpected property "${err.params.additionalProperty}"`
+	}
+	const tail = hints.length ? ` (${hints.join("; ")})` : ""
+	return `${at} ${core}${tail}`
+}
+
+function lintFiles(files) {
+	const results = files.map((f) => lintFile(f))
+	const summary = {
+		totalFiles: results.length,
+		filesWithErrors: results.filter((r) => !r.ok).length,
+		skipped: results.filter((r) => r.skipped).length,
+		totalErrors: results.reduce((n, r) => n + r.errors.length, 0),
+	}
+	return { results, summary }
+}
+
+/**
+ * Validate an already-parsed JSON value. `pathHint` is only used to pick the
+ * right root schema (via detectSchema). Useful for MCP tools that want to
+ * validate a prospective edit before touching disk.
+ */
+function lintData(data, pathHint) {
+	const result = { ok: true, skipped: false, reason: null, errors: [] }
+	const schemaKey = detectSchema(pathHint)
+	if (!schemaKey) {
+		result.skipped = true
+		result.reason = "no-schema-for-filename"
+		return result
+	}
+
+	const ajv = getAjv()
+	const validate = ajv.getSchema(schemaKey)
+	const valid = validate(data)
+	if (!valid) {
+		result.ok = false
+		const seen = new Set()
+		for (const err of validate.errors || []) {
+			if (err.keyword === "if" || err.keyword === "allOf") continue
+			const dedupeKey = `${err.keyword}|${err.instancePath}|${err.params?.missingProperty || ""}|${err.params?.additionalProperty || ""}`
+			if (seen.has(dedupeKey)) continue
+			seen.add(dedupeKey)
+
+			result.errors.push({
+				code: err.keyword,
+				message: formatAjvMessage(err),
+				line: 1,
+				column: 1,
+				instancePath: err.instancePath || "/",
+				schemaPath: err.schemaPath,
+				params: err.params,
+			})
+		}
+	}
+	return result
+}
+
+module.exports = {
+	detectSchema,
+	lintFile,
+	lintFiles,
+	lintData,
+	SCHEMA_DIR,
+}

package/bin/lib/lint/schemas/app-manifest.schema.json

@@ -0,0 +1,124 @@
+{
+	"$id": "https://gxp.dev/schemas/app-manifest.schema.json",
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "GxP App Manifest",
+	"description": "Plugin metadata + default datastore values. Read by the platform at install time and by the toolkit dev server.",
+	"type": "object",
+	"required": ["name", "version"],
+	"properties": {
+		"name": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Plugin display name."
+		},
+		"version": {
+			"type": "string",
+			"pattern": "^[0-9]+(\\.[0-9]+){0,2}([-+][A-Za-z0-9.-]+)?$",
+			"description": "Semver-like plugin version."
+		},
+		"description": { "type": "string" },
+		"manifest_version": {
+			"type": "integer",
+			"enum": [1, 2, 3]
+		},
+		"asset_dir": {
+			"type": "string",
+			"description": "Relative path to the asset directory, e.g. /src/public.",
+			"pattern": "^/?[A-Za-z0-9._-][A-Za-z0-9/._-]*$"
+		},
+		"configurationFile": { "type": "string" },
+		"appInstructionsFile": { "type": "string" },
+		"defaultStylingFile": { "type": "string" },
+		"appInstructions": { "type": "string" },
+		"defaultStyling": { "type": "string" },
+		"configuration": {
+			"type": ["object", "string"]
+		},
+		"settings": {
+			"type": "object",
+			"description": "Default key/value settings (pluginVars). Keys should match identifiers used in gxp-settings directives.",
+			"patternProperties": {
+				"^[A-Za-z_][A-Za-z0-9_]*$": {
+					"type": ["string", "number", "boolean", "null", "array", "object"]
+				}
+			},
+			"additionalProperties": false
+		},
+		"strings": {
+			"type": "object",
+			"description": "i18n strings. Must contain a `default` locale map; other keys are locale codes.",
+			"properties": {
+				"default": {
+					"type": "object",
+					"patternProperties": {
+						"^[A-Za-z_][A-Za-z0-9_]*$": { "type": "string" }
+					},
+					"additionalProperties": false
+				}
+			},
+			"patternProperties": {
+				"^[a-z]{2}(-[A-Z]{2})?$": {
+					"type": "object",
+					"additionalProperties": { "type": "string" }
+				}
+			},
+			"required": ["default"],
+			"additionalProperties": true
+		},
+		"assets": {
+			"type": "object",
+			"description": "Default asset URLs/paths keyed by gxp-src identifier.",
+			"patternProperties": {
+				"^[A-Za-z_][A-Za-z0-9_]*$": {
+					"$ref": "common.schema.json#/$defs/urlOrPath"
+				}
+			},
+			"additionalProperties": false
+		},
+		"triggerState": {
+			"type": "object",
+			"description": "Default values for dynamic state updated by sockets/CLI.",
+			"patternProperties": {
+				"^[A-Za-z_][A-Za-z0-9_]*$": {
+					"type": ["string", "number", "boolean", "null"]
+				}
+			},
+			"additionalProperties": false
+		},
+		"dependencies": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["identifier"],
+				"properties": {
+					"identifier": {
+						"$ref": "common.schema.json#/$defs/identifier"
+					},
+					"model": { "type": "string" },
+					"events": { "type": "object" }
+				},
+				"additionalProperties": true
+			}
+		},
+		"permissions": {
+			"type": "array",
+			"items": {
+				"oneOf": [
+					{ "$ref": "common.schema.json#/$defs/identifier" },
+					{
+						"type": "object",
+						"required": ["identifier"],
+						"properties": {
+							"identifier": {
+								"$ref": "common.schema.json#/$defs/identifier"
+							},
+							"description": { "type": "string" }
+						},
+						"additionalProperties": true
+					}
+				]
+			}
+		}
+	},
+	"additionalProperties": true
+}

package/bin/lib/lint/schemas/card.schema.json

@@ -0,0 +1,165 @@
+{
+	"$id": "https://gxp.dev/schemas/card.schema.json",
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "GxP Form Card",
+	"description": "A card inside additionalTabs.cards or a nested card_list/tabs_list.",
+	"type": "object",
+	"required": ["type"],
+	"properties": {
+		"type": {
+			"type": "string",
+			"enum": [
+				"fields_list",
+				"data_table",
+				"card_list",
+				"tabs_list",
+				"info_card",
+				"render_list",
+				"carousel",
+				"grid_view",
+				"component",
+				"data_display",
+				"button_group",
+				"form_builder"
+			]
+		},
+		"title": { "type": ["string", "null"] },
+		"tabId": { "type": ["string", "null"] },
+		"cols": { "$ref": "common.schema.json#/$defs/gridCols" },
+		"colsMd": { "$ref": "common.schema.json#/$defs/gridCols" },
+		"colsLg": { "$ref": "common.schema.json#/$defs/gridCols" },
+		"marginBottom": { "type": "integer", "minimum": 0 },
+		"showCard": { "type": "boolean" },
+		"border": { "type": "boolean" },
+		"listKey": { "type": ["string", "null"] },
+		"condition": { "type": ["string", "null"] },
+		"conditionParams": {
+			"$ref": "common.schema.json#/$defs/conditionParams"
+		},
+		"fieldsList": {
+			"type": "array",
+			"items": { "$ref": "field.schema.json" }
+		},
+		"cards": {
+			"type": "array",
+			"items": { "$ref": "card.schema.json" }
+		},
+		"tabsList": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["title"],
+				"properties": {
+					"title": { "type": "string" },
+					"tabId": { "type": ["string", "null"] },
+					"cards": {
+						"type": "array",
+						"items": { "$ref": "card.schema.json" }
+					}
+				},
+				"additionalProperties": true
+			}
+		},
+		"buttons": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"required": ["text"],
+				"properties": {
+					"text": { "type": "string" },
+					"type": { "type": "string" },
+					"icon": { "type": ["string", "null"] },
+					"href": { "type": ["string", "null"] },
+					"action": { "type": ["string", "null"] },
+					"condition": { "type": ["string", "null"] },
+					"conditionParams": {
+						"$ref": "common.schema.json#/$defs/conditionParams"
+					}
+				},
+				"additionalProperties": true
+			}
+		},
+		"component": { "type": ["string", "null"] },
+		"componentProps": { "type": "object" },
+		"headers": {
+			"type": "array",
+			"items": { "type": ["string", "object"] }
+		},
+		"rows": { "type": "array" },
+		"options": { "type": "object" },
+		"tableTitle": { "type": ["string", "null"] }
+	},
+	"allOf": [
+		{
+			"if": {
+				"properties": { "type": { "const": "fields_list" } },
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["fieldsList"],
+				"properties": {
+					"fieldsList": {
+						"type": "array",
+						"items": { "$ref": "field.schema.json" }
+					}
+				}
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "card_list" } },
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["cards"],
+				"properties": {
+					"cards": {
+						"type": "array",
+						"minItems": 1,
+						"items": { "$ref": "card.schema.json" }
+					}
+				}
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "tabs_list" } },
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["tabsList"]
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "button_group" } },
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["buttons"]
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "component" } },
+				"required": ["type"]
+			},
+			"then": {
+				"required": ["component"],
+				"properties": {
+					"component": { "type": "string", "minLength": 1 }
+				}
+			}
+		},
+		{
+			"if": {
+				"properties": { "type": { "const": "data_table" } },
+				"required": ["type"]
+			},
+			"then": {
+				"anyOf": [{ "required": ["headers"] }, { "required": ["rows"] }]
+			}
+		}
+	],
+	"additionalProperties": true
+}

package/bin/lib/lint/schemas/common.schema.json

@@ -0,0 +1,62 @@
+{
+	"$id": "https://gxp.dev/schemas/common.schema.json",
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "GxP Common Definitions",
+	"description": "Shared sub-schemas referenced by card and field schemas.",
+	"$defs": {
+		"conditionParam": {
+			"type": "object",
+			"properties": {
+				"name": { "type": "string" },
+				"value": {
+					"type": ["string", "number", "boolean", "null"]
+				},
+				"logic": {
+					"type": "string",
+					"enum": ["==", "!=", ">", ">=", "<", "<=", "in", "not_in", "includes"]
+				},
+				"column": { "type": ["string", "null"] }
+			},
+			"required": ["name", "logic"],
+			"additionalProperties": true
+		},
+		"conditionParams": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/conditionParam" }
+		},
+		"gridCols": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 12
+		},
+		"colorHex": {
+			"type": "string",
+			"pattern": "^#(?:[0-9a-fA-F]{3}){1,2}$"
+		},
+		"urlOrPath": {
+			"type": "string",
+			"description": "Absolute URL or site-relative path",
+			"pattern": "^(https?:)?(//)?/?[^\\s]*$"
+		},
+		"identifier": {
+			"type": "string",
+			"pattern": "^[A-Za-z_][A-Za-z0-9_-]*$"
+		},
+		"option": {
+			"type": "object",
+			"properties": {
+				"label": { "type": "string" },
+				"value": {
+					"type": ["string", "number", "boolean", "null"]
+				},
+				"disabled": { "type": "boolean" }
+			},
+			"required": ["label", "value"],
+			"additionalProperties": true
+		},
+		"options": {
+			"type": "array",
+			"items": { "$ref": "#/$defs/option" }
+		}
+	}
+}

package/bin/lib/lint/schemas/configuration.schema.json

@@ -0,0 +1,19 @@
+{
+	"$id": "https://gxp.dev/schemas/configuration.schema.json",
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"title": "GxP Plugin Configuration Form",
+	"description": "Defines the configuration form shown to admins in the GxP admin panel when they install or configure a plugin. Follows the GxP templating system (ShowPage > tabs > cards > fields).",
+	"type": "object",
+	"required": ["additionalTabs"],
+	"properties": {
+		"additionalTabs": {
+			"type": "array",
+			"description": "Top-level array of tab definitions. Each item is a card (usually card_list or fields_list) rendered under the plugin's configuration panel.",
+			"items": { "$ref": "card.schema.json" }
+		},
+		"title": { "type": ["string", "null"] },
+		"description": { "type": ["string", "null"] },
+		"version": { "type": ["string", "integer", "null"] }
+	},
+	"additionalProperties": true
+}