@skill-map/spec 0.18.0 → 0.20.0

package/schemas/view-slots.schema.json

@@ -0,0 +1,335 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/view-slots.schema.json",
+  "title": "ViewSlots",
+  "description": "Closed catalog of view slots. A view slot is a kernel-published handle that names a visual surface in the UI, fixes the renderer that draws there, and fixes the payload shape the plugin emits. The plugin author picks ONE slot per view contribution; the kernel validates `ctx.emitContribution(id, payload)` against that slot's payload schema in `$defs.payloads`. There is no separate notion of a 'contract' — the slot IS the contract. Closed catalog by design: every new slot requires a spec change + UI renderer mount + scaffolder support + conformance fixtures + tests. Compounds catalog evolution cost; see ROADMAP.md §UI contribution system → 'Known limitations carried forward'. Slots are versioned via the manifest field `catalogCompat` (semver against the catalog as a whole), not per-slot.",
+  "type": "object",
+  "$defs": {
+    "SlotName": {
+      "type": "string",
+      "enum": [
+        "card.title.right",
+        "card.subtitle.left",
+        "card.footer.left.counter",
+        "card.footer.right",
+        "graph.node.alert",
+        "inspector.header.badge.counter",
+        "inspector.header.badge.tag",
+        "inspector.body.panel.breakdown",
+        "inspector.body.panel.records",
+        "inspector.body.panel.tree",
+        "inspector.body.panel.key-values",
+        "inspector.body.panel.link-list",
+        "inspector.body.panel.markdown",
+        "topbar.actions.indicator"
+      ],
+      "description": "Closed enum of slot 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. Slots that share a payload shape (e.g. `card.subtitle.left`, `card.footer.right`, and `card.footer.left.counter` all carry a counter) reference the same payload schema in `$defs.payloads`."
+    },
+    "Severity": {
+      "type": "string",
+      "enum": ["info", "warn", "success", "danger"],
+      "description": "Closed severity palette aligned with PrimeNG `<p-tag>` / `<p-message>` severities. Used by counter, tag, alert, and icon slots 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": ["slot"],
+      "properties": {
+        "slot": { "$ref": "#/$defs/SlotName" },
+        "label": {
+          "type": "string",
+          "maxLength": 64,
+          "description": "Short human-readable label. Used as metadata (docs / plugin-doctor / aria-label) and, for some slots, rendered in the chip / panel header / table label. English-only per AGENTS.md (`Externalized texts, not internationalized`). Per-slot notes specify whether it is rendered inline; counter slots keep 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 slot 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-slot definition of 'empty' lives in the 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": {
+              "slot": {
+                "enum": [
+                  "card.subtitle.left",
+                  "card.footer.left.counter",
+                  "card.footer.right",
+                  "inspector.header.badge.counter"
+                ]
+              }
+            }
+          },
+          "then": { "required": ["slot", "icon"] }
+        },
+        {
+          "if": { "properties": { "slot": { "const": "card.title.right" } } },
+          "then": { "required": ["slot", "icon"] }
+        }
+      ],
+      "description": "Manifest-side declaration of a single view contribution, keyed in `IExtensionBase.viewContributions[<contributionId>]`. The plugin author picks ONE slot from the closed `SlotName` enum; the slot fixes the renderer and the payload shape. Slots whose renderer is the counter chip require `icon` in the manifest; same for `card.title.right` (the standalone icon slot)."
+    },
+    "payloads": {
+      "description": "Per-slot payload schemas. The kernel validates `ctx.emitContribution(id, payload)` calls against the entry corresponding to the declared slot before persisting to `scan_contributions`. Off-shape payloads emit an `extension.error` event and drop silently (mirror of `emitLink` off-contract drop pattern). Slots that share a renderer share a payload shape; the schema is defined inline at each slot to keep lookups direct (no internal indirection).",
+      "card.title.right": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "icon": {
+            "$ref": "#/$defs/IconString",
+            "description": "Optional payload-time icon override. When omitted the manifest-declared `icon` (which is required for this slot — see `IViewContribution.allOf`) is rendered instead. Lets a plugin emit a different icon per node without redeclaring the manifest."
+          },
+          "severity": { "$ref": "#/$defs/Severity" },
+          "tooltip": { "type": "string", "maxLength": 256 }
+        },
+        "description": "Single icon per node — small standalone marker rendered next to the card title. The manifest requires `icon`; the payload optionally overrides it per node and may add `severity` (color tint) and `tooltip`. No counts, no labels — for chip + number use a counter slot; for label + severity use a tag slot. 'Empty' for `emitWhenEmpty` is the absence of both payload `icon` and a manifest fallback (in practice never empty since the manifest icon is required)."
+      },
+      "card.subtitle.left": { "$ref": "#/$defs/payloads/_counter" },
+      "card.footer.left.counter": { "$ref": "#/$defs/payloads/_counter" },
+      "card.footer.right": { "$ref": "#/$defs/payloads/_counter" },
+      "inspector.header.badge.counter": { "$ref": "#/$defs/payloads/_counter" },
+      "_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` (enforced by `IViewContribution.allOf` for every counter slot); payload carries `value`, optionally `severity` and `tooltip`. The manifest `label` is metadata (docs / plugin-doctor / aria-label) and is NOT rendered inline."
+      },
+      "inspector.header.badge.tag": { "$ref": "#/$defs/payloads/_tag" },
+      "_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 }
+        }
+      },
+      "graph.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)."
+      },
+      "inspector.body.panel.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`."
+          }
+        }
+      },
+      "inspector.body.panel.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`."
+          }
+        }
+      },
+      "inspector.body.panel.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" }
+          }
+        }
+      },
+      "inspector.body.panel.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`."
+          }
+        }
+      },
+      "inspector.body.panel.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 analyzer)."
+                },
+                "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`."
+          }
+        }
+      },
+      "inspector.body.panel.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() === ''`."
+          }
+        }
+      },
+      "topbar.actions.indicator": {
+        "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 the topbar."
+          },
+          "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(...)` (analyzer context) — extractors do not see `emitScopeContribution`."
+      }
+    }
+  }
+}

package/schemas/extensions/rule.schema.json

@@ -1,43 +0,0 @@
-{
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://skill-map.dev/spec/v0/extensions/rule.schema.json",
-  "title": "ExtensionRule",
-  "description": "Manifest shape for a `Rule` extension. A rule consumes the full graph (nodes + links) after all extractors have run and emits `Issue[]`. Rules are dual-mode: `deterministic` rules MUST be byte-for-byte reproducible (same graph in → same issues out; time, random, and network are forbidden) and run synchronously inside `sm check` / `sm scan`. `probabilistic` rules invoke an LLM through the kernel's `RunnerPort` and execute only as queued jobs (`sm job submit rule:<id>`); their output MAY vary across runs and they NEVER participate in `sm scan`. See `architecture.md` §Execution modes for the full contract.",
-  "allOf": [
-    { "$ref": "base.schema.json" }
-  ],
-  "type": "object",
-  "required": ["id", "kind", "version", "emitsRuleIds", "defaultSeverity"],
-  "unevaluatedProperties": false,
-  "properties": {
-    "kind": { "const": "rule" },
-    "mode": {
-      "type": "string",
-      "enum": ["deterministic", "probabilistic"],
-      "default": "deterministic",
-      "description": "`deterministic` (default): pure code, byte-for-byte reproducible, runs during `sm check` and `sm scan`. `probabilistic`: invokes an LLM via `ctx.runner` and runs only as a queued job; never participates in scan-time pipelines. The kernel rejects probabilistic rules that try to register scan-time hooks at load time. Omitting the field is equivalent to declaring `deterministic`."
-    },
-    "emitsRuleIds": {
-      "type": "array",
-      "description": "List of `rule_id` values this rule may emit on issues. Typically a singleton (`trigger-collision` → emits `trigger-collision`). A rule emitting a `rule_id` not in this list → kernel logs `rule-id-violation` but keeps the issue (forward compatibility).",
-      "minItems": 1,
-      "items": { "type": "string" }
-    },
-    "defaultSeverity": {
-      "type": "string",
-      "enum": ["error", "warn", "info"],
-      "description": "Severity attached by default to emitted issues. Rules MAY override per-issue."
-    },
-    "consumes": {
-      "type": "string",
-      "enum": ["nodes", "links", "both"],
-      "default": "both",
-      "description": "Which slices of the graph the rule reads. The kernel MAY pass a restricted view when this is a strict subset."
-    },
-    "configurable": {
-      "type": "boolean",
-      "default": false,
-      "description": "If true, the rule reads its own config from `config_preferences` under the key `rules.<id>.<field>`. Implementations MAY surface these in `sm config`."
-    }
-  }
-}