@skill-map/spec 0.17.0 → 0.19.0

package/schemas/view-contracts.schema.json

@@ -0,0 +1,298 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/view-contracts.schema.json",
+  "title": "ViewContracts",
+  "description": "Closed catalog of view contracts. A view contract is a semantic spec a plugin author picks by name to surface per-node (or per-scope) data in the UI without shipping any UI code. The kernel publishes this catalog; plugin authors pick by `contract` name in their extension manifest's `viewContributions` map; the UI driving adapter maps `contract → slot(s) + renderer` (slot policy is UI-only, kernel does not know about slots). The plugin emits per-node payloads via `ctx.emitContribution(id, payload)` — payloads are validated at emit time against the contract's payload schema in `$defs.payloads`. Closed catalog by design: every new contract requires a spec change + UI renderer + scaffolder support + conformance fixtures + tests. Compounds catalog evolution cost; see ROADMAP.md §UI contribution system → 'Known limitations carried forward'. Contracts are versioned via the manifest field `catalogCompat` (semver against the catalog as a whole), not per-contract.",
+  "type": "object",
+  "$defs": {
+    "ContractName": {
+      "type": "string",
+      "enum": [
+        "node-counter",
+        "node-tag",
+        "node-breakdown",
+        "node-records",
+        "node-tree",
+        "node-key-values",
+        "node-link-list",
+        "node-markdown",
+        "node-alert",
+        "scope-stat"
+      ],
+      "description": "Closed enum of contract identifiers. Adding an entry requires the full spec/UI/scaffolder/conformance round-trip per ROADMAP.md §UI contribution system. Removing or renaming an entry is a catalog-major-bump and triggers `sm plugins upgrade` migration."
+    },
+    "Severity": {
+      "type": "string",
+      "enum": ["info", "warn", "success", "danger"],
+      "description": "Closed severity palette aligned with PrimeNG `<p-tag>` / `<p-message>` severities. Used by `node-counter`, `node-tag`, and `node-alert` for color/contrast hints. The UI maps each severity to a theme-aware tint; plugins do not pick raw colors."
+    },
+    "IconString": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Single string, dual-resolved by the UI. If the value matches a Unicode `\\p{Extended_Pictographic}` codepoint, render as emoji text. Otherwise resolve as a PrimeIcons class id (without the `pi-` prefix; the UI prepends it). Unknown PrimeIcons names render no icon (silent fallback) plus a console warning. The plugin author types either the emoji character or the icon name; the discrimination is automatic."
+    },
+    "IViewContribution": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["contract"],
+      "properties": {
+        "contract": { "$ref": "#/$defs/ContractName" },
+        "label": {
+          "type": "string",
+          "maxLength": 64,
+          "description": "Short human-readable label. Used as metadata (docs / plugin-doctor / aria-label) and, for some contracts, rendered in the chip / panel header / table label. English-only per AGENTS.md (`Externalized texts, not internationalized`). Per-contract notes specify whether it is rendered inline; `node-counter` keeps it as metadata only."
+        },
+        "tooltip": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "Hover tooltip shown on the chip or panel header. English-only."
+        },
+        "icon": { "$ref": "#/$defs/IconString" },
+        "emptyText": {
+          "type": "string",
+          "maxLength": 128,
+          "description": "Text shown in the empty placeholder when the contract permits an empty payload. Defaults to a UI-supplied generic 'No data.' string. English-only."
+        },
+        "emitWhenEmpty": {
+          "type": "boolean",
+          "default": false,
+          "description": "When false (default), the kernel drops emissions whose payload is structurally empty (zero counter value, empty array, empty tree, etc.) so the slot stays silent. When true, the renderer surfaces an empty placeholder instead. Per-contract definition of 'empty' lives in the contract's payload schema notes."
+        },
+        "priority": {
+          "type": "number",
+          "default": 100,
+          "description": "Optional ordering hint. Slots configured with `order: 'priority'` sort contributions ASC by this value, with alphabetical tie-break by qualified id. Default 100 — plugins use it to suggest where their contribution belongs relative to others sharing the same slot. The slot has the final say on whether `priority` is honoured at all."
+        }
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "contract": { "const": "node-counter" } } },
+          "then": { "required": ["contract", "icon"] }
+        }
+      ],
+      "description": "Manifest-side declaration of a single view contribution, keyed in `IExtensionBase.viewContributions[<contributionId>]`. The plugin author picks the contract by name; the rest is presentation tuning. The plugin NEVER picks a slot — the UI maps contract → slot(s). Some contracts add per-contract requireds (e.g. `node-counter` requires `icon`)."
+    },
+    "payloads": {
+      "description": "Per-contract payload schemas, keyed by contract name. The kernel validates `ctx.emitContribution(id, payload)` calls against the entry corresponding to the declared contract before persisting to `scan_contributions`. Off-contract payloads emit an `extension.error` event and drop silently (mirror of `emitLink` off-contract drop pattern).",
+      "node-counter": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["value"],
+        "properties": {
+          "value": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Single non-negative integer for the chip / badge. 'Empty' for `emitWhenEmpty` purposes is `value === 0`."
+          },
+          "tooltip": { "type": "string", "maxLength": 256 },
+          "severity": {
+            "$ref": "#/$defs/Severity",
+            "description": "Optional severity for visual tinting. The slot decides whether to honour it (`SLOT_REGISTRY[slot].respectSeverity`). The plugin emits the data; the UI decides the presentation."
+          }
+        },
+        "description": "Single icon + integer pair, modelled after the `.sm-gnode__stat` rows in the card footer. Manifest requires `icon`; payload carries `value`, optionally `severity` and `tooltip`. The manifest `label` is metadata (docs / plugin-doctor / aria-label) and is NOT rendered inline."
+      },
+      "node-tag": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label"],
+        "properties": {
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 32,
+            "description": "Tag text (e.g. 'fresh', 'stale', '7d ago'). 'Empty' for `emitWhenEmpty` is `label === ''`."
+          },
+          "severity": { "$ref": "#/$defs/Severity" },
+          "tooltip": { "type": "string", "maxLength": 256 }
+        }
+      },
+      "node-breakdown": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["entries"],
+        "properties": {
+          "entries": {
+            "type": "array",
+            "maxItems": 20,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["label", "value"],
+              "properties": {
+                "label": { "type": "string", "minLength": 1, "maxLength": 32 },
+                "value": { "type": "integer", "minimum": 0 },
+                "tooltip": { "type": "string", "maxLength": 256 }
+              }
+            },
+            "description": "Top-N labeled values rendered as a horizontal bar chart. Hard cap 20 entries (overflow rejected at validation, plugin should pre-truncate). 'Empty' for `emitWhenEmpty` is `entries.length === 0`."
+          }
+        }
+      },
+      "node-records": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["columns", "rows"],
+        "properties": {
+          "columns": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 6,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["key", "label"],
+              "properties": {
+                "key": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$" },
+                "label": { "type": "string", "minLength": 1, "maxLength": 32 }
+              }
+            },
+            "description": "Column declarations (max 6). Each row's value at `key` is rendered under `label`."
+          },
+          "rows": {
+            "type": "array",
+            "maxItems": 50,
+            "items": {
+              "type": "object",
+              "additionalProperties": {
+                "oneOf": [
+                  { "type": "string", "maxLength": 256 },
+                  { "type": "number" },
+                  { "type": "boolean" },
+                  { "type": "null" }
+                ]
+              }
+            },
+            "description": "Tabular rows (max 50). Cell values are scalar only (string ≤256 chars, number, boolean, or null). 'Empty' for `emitWhenEmpty` is `rows.length === 0`."
+          }
+        }
+      },
+      "node-tree": {
+        "$ref": "#/$defs/payloads/_TreeNode",
+        "description": "Recursive tree rendered as an indented hierarchy. Hard caps: max depth 6, max 200 total nodes per tree (validator enforces). 'Empty' for `emitWhenEmpty` is the root having no `children`."
+      },
+      "_TreeNode": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label"],
+        "properties": {
+          "label": { "type": "string", "minLength": 1, "maxLength": 64 },
+          "marker": { "$ref": "#/$defs/IconString" },
+          "tooltip": { "type": "string", "maxLength": 256 },
+          "children": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/payloads/_TreeNode" }
+          }
+        }
+      },
+      "node-key-values": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["entries"],
+        "properties": {
+          "entries": {
+            "type": "array",
+            "maxItems": 50,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["key", "value"],
+              "properties": {
+                "key": { "type": "string", "minLength": 1, "maxLength": 64 },
+                "value": {
+                  "oneOf": [
+                    { "type": "string", "maxLength": 512 },
+                    { "type": "number" },
+                    { "type": "boolean" },
+                    { "type": "null" }
+                  ]
+                },
+                "tooltip": { "type": "string", "maxLength": 256 }
+              }
+            },
+            "description": "Flat key/value pairs (max 50). Renders as a definition list. 'Empty' for `emitWhenEmpty` is `entries.length === 0`."
+          }
+        }
+      },
+      "node-link-list": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["entries"],
+        "properties": {
+          "entries": {
+            "type": "array",
+            "maxItems": 100,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["path"],
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 512,
+                  "description": "Node path within the scope. Resolved by the UI to a clickable link via `Router.navigate` — never rendered as a raw `[href]` (per the renderer attr-sanitization rule)."
+                },
+                "label": { "type": "string", "minLength": 1, "maxLength": 128 },
+                "kind": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 32,
+                  "description": "Optional Provider kind id (informational). The UI may apply per-kind tinting from `kindRegistry`."
+                }
+              }
+            },
+            "description": "List of in-scope node paths (max 100). 'Empty' for `emitWhenEmpty` is `entries.length === 0`."
+          }
+        }
+      },
+      "node-markdown": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["markdown"],
+        "properties": {
+          "markdown": {
+            "type": "string",
+            "maxLength": 4096,
+            "description": "Markdown text rendered with a sanitized allow-list (paragraphs, headings up to H3, lists, inline code, fenced code, emphasis, strong, blockquote). HTML, scripts, embedded SVG, image tags, and link autodetection are stripped. Hard cap 4096 chars to keep render cost bounded. 'Empty' for `emitWhenEmpty` is `markdown.trim() === ''`."
+          }
+        }
+      },
+      "node-alert": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "icon": { "$ref": "#/$defs/IconString" },
+          "severity": { "$ref": "#/$defs/Severity" },
+          "count": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 99,
+            "description": "Optional badge count rendered next to the icon (1-99; 99+ collapses to '99+'). Omit for an icon-only marker."
+          },
+          "tooltip": { "type": "string", "maxLength": 256 }
+        },
+        "description": "Decoration on the graph node (corner badge / pin). At least one of `icon`, `severity`, `count` is required. 'Empty' for `emitWhenEmpty` is the absence of `icon` AND `count`. Hard cap 1 marker per node per plugin extension (slot config enforces)."
+      },
+      "scope-stat": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["value"],
+        "properties": {
+          "value": {
+            "oneOf": [
+              { "type": "integer", "minimum": 0 },
+              { "type": "string", "minLength": 1, "maxLength": 64 }
+            ],
+            "description": "Either a non-negative integer or a short string. The UI renders it as a single chip in `topbar.actions.indicator`."
+          },
+          "label": { "type": "string", "minLength": 1, "maxLength": 32 },
+          "tooltip": { "type": "string", "maxLength": 256 },
+          "severity": { "$ref": "#/$defs/Severity" }
+        },
+        "description": "Single value summarizing the entire scope. Emitted ONCE per scan (not per node). Plugins use `ctx.emitScopeContribution(...)` (rule context) — extractors do not see `emitScopeContribution`."
+      }
+    }
+  }
+}