kibi-plugin-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# kibi-plugin-ui
+
+## 0.1.0
+
+### Minor Changes
+
+- ee91b85: Projects with a UI can opt into the experimental `kibi-plugin-ui`, which keeps agents on the agreed design: `kb_check` then requires every React or Angular component to implement a design requirement and blocks a component that loses the class names or test ids marking its agreed pattern, such as a timeline rewritten as cards. `/kibi-bootstrap` offers the plugin when it finds component files, and a declined offer is remembered in `package.json` `kibi.declinedPlugins`. Requirements that only name a UI pattern are now proved by fresh isolated component tests, so pattern rules do not need browser tests. Projects without the plugin see no new blocking findings.
+  - Add the `kibi.check-policy.v1` capability to `kibi-plugin-sdk`: a JSON policy with ownership and pattern-marker rules, validated by `validateCheckPolicyDocument`. `kb_check` reads activated policies as data from the package and never imports plugin code; an unreadable policy blocks. The builtin plugin ships an empty policy.
+  - Add the canonical `policy-ownership` and `policy-markers` rules (inert without an activated policy) to the rule registry, the `kb_check` schema and the CLI.
+  - Add built-in `ui_pattern`, `same_pattern`, `pattern_marker` and `ui_container` predicate schemas with suggestion keywords.
+  - Proof ladder: a scenario whose requirements are grounded only in `ui_pattern`, `same_pattern` and `pattern_marker` accepts `unit` and `integration` tests with fresh receipts; each scenario obligation now reports `acceptedScopes`.
+  - `kb_plan_bootstrap` returns `pluginOffers` and a `plugin_offer` recommended action; `kibi.declinedPlugins` is validated as a list of bare package names. The `kibi-bootstrap` and `kibi-usage` skills cover the offer and the UI pattern workflow.
+  - New package `kibi-plugin-ui` ships the UI design policy. It is optional and not part of the default install.
+
+  Migration: none required. To enable the guard, install `kibi-plugin-ui` as a dev dependency and activate `kibi.check-policy.v1` in `augment` mode under `package.json` `kibi.plugins`; expect `policy-ownership` findings for existing components until they are linked to design requirements or tagged `review:ui-unconstrained`.
+
+### Patch Changes
+
+- Updated dependencies [ee91b85]
+  - kibi-plugin-sdk@0.5.0

package/README.md

@@ -1,3 +1,81 @@
-# Temporary Holding Version
+# kibi-plugin-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Experimental Kibi plugin that keeps UI components on their agreed design
+patterns. It contributes one capability, `kibi.check-policy.v1`: a JSON policy
+that `kb_check` reads as data. Kibi never imports this package's code while
+checking.
+
+With the plugin active, `kb_check` blocks two kinds of drift:
+
+- **`policy-ownership`**: a React or Angular component (`*.tsx`, `*.jsx`,
+  `*.component.ts`, tests and stories excluded) must implement a current
+  requirement grounded in UI design vocabulary: `ui_pattern`, `same_pattern`,
+  `ui_container` or `visual_layout_rule`. In React files the rule matches
+  PascalCase symbols and skips names ending in `Props`, `State`, `Context`,
+  `Variant(s)` or `Type(s)`. Tag a component
+  `review:ui-unconstrained` when it genuinely has no design constraint.
+- **`policy-markers`**: a component implementing a requirement that names a
+  `ui_pattern` must still contain every `pattern_marker` the KB declares for
+  that pattern, in its source file or its `.html` template. Rewriting a
+  line-and-dots timeline as cards drops the timeline markers and fails the
+  check.
+
+Requirements grounded only in `ui_pattern`, `same_pattern` and
+`pattern_marker` are proved by component-scope tests (`verification_scope:
+unit` or `integration`) with fresh proof receipts, so pattern requirements do
+not need end-to-end tests. Those three predicates and the scope rule are part
+of Kibi core; this plugin only turns enforcement on.
+
+Colours, spacing and which component library renders a scrollbar are lint
+concerns and stay out of this plugin.
+
+## Install and activate
+
+`/kibi-bootstrap` offers this plugin when it finds UI sources. To enable it by
+hand:
+
+```bash
+npm install --save-dev kibi-plugin-ui
+```
+
+```json
+{
+  "kibi": {
+    "plugins": [
+      {
+        "package": "kibi-plugin-ui",
+        "capabilities": {
+          "kibi.check-policy.v1": { "mode": "augment" }
+        }
+      }
+    ]
+  }
+}
+```
+
+Check policies only support `augment`. To decline the bootstrap offer
+permanently, list the package under `kibi.declinedPlugins`:
+
+```json
+{ "kibi": { "declinedPlugins": ["kibi-plugin-ui"] } }
+```
+
+## Modeling a pattern
+
+```text
+REQ-feed-timeline-pattern  requires_predicate
+  FACT-feed-timeline       ui_pattern(activity_feed, line_dots_timeline)
+  FACT-feed-variants       same_pattern(activity_feed, editor_view, read_only_view)
+FACT-timeline-dot          pattern_marker(line_dots_timeline, timeline_dot)
+FACT-timeline-connector    pattern_marker(line_dots_timeline, timeline-connector)
+```
+
+Markers are literal class names or test ids. Both `timeline_dot` and
+`timeline-dot` spellings match. Write one component test per variant so a
+divergent branch inside a single template is caught by proof rather than by
+the static marker check, which cannot see branches.
+
+See the [plugin guide](https://looted.github.io/kibi/reference/plugins.html)
+for how check policies work and the
+[UI requirements guide](https://github.com/Looted/kibi/blob/master/docs/ui-requirements.md)
+for the full modeling workflow.

package/check-policy.json

@@ -0,0 +1,64 @@
+{
+  "contractVersion": "kibi.check-policy.v1",
+  "id": "ui-design",
+  "title": "UI design coverage",
+  "ownership": [
+    {
+      "id": "ui-component-ownership",
+      "description": "Every UI component implements a current requirement grounded in UI design vocabulary (ui_pattern, same_pattern, ui_container or visual_layout_rule), or carries review:ui-unconstrained.",
+      "include": ["**/*.tsx", "**/*.jsx"],
+      "exclude": [
+        "**/*.test.*",
+        "**/*.spec.*",
+        "**/*.stories.*",
+        "**/__tests__/**",
+        "**/tests/**",
+        "**/e2e/**",
+        "**/dist/**",
+        "**/build/**",
+        "**/node_modules/**"
+      ],
+      "symbolTitlePattern": "^(?![A-Za-z0-9]*(Props|State|Context|Variants?|Types?)$)[A-Z][A-Za-z0-9]*$",
+      "requirePredicates": [
+        "ui_pattern",
+        "same_pattern",
+        "ui_container",
+        "visual_layout_rule"
+      ],
+      "exemptTag": "review:ui-unconstrained"
+    },
+    {
+      "id": "ui-angular-component-ownership",
+      "description": "Every Angular component class implements a current requirement grounded in UI design vocabulary, or carries review:ui-unconstrained.",
+      "include": ["**/*.component.ts"],
+      "exclude": [
+        "**/*.spec.ts",
+        "**/__tests__/**",
+        "**/tests/**",
+        "**/e2e/**",
+        "**/dist/**",
+        "**/node_modules/**"
+      ],
+      "symbolTitlePattern": "^[A-Za-z0-9]+Component$",
+      "requirePredicates": [
+        "ui_pattern",
+        "same_pattern",
+        "ui_container",
+        "visual_layout_rule"
+      ],
+      "exemptTag": "review:ui-unconstrained"
+    }
+  ],
+  "markers": [
+    {
+      "id": "ui-pattern-markers",
+      "description": "A component implementing a requirement that names a ui_pattern keeps every pattern_marker of that pattern in its source or its .html template.",
+      "patternPredicate": "ui_pattern",
+      "patternArgument": 1,
+      "markerPredicate": "pattern_marker",
+      "markerPatternArgument": 0,
+      "markerArgument": 1,
+      "siblingExtensions": [".html"]
+    }
+  ]
+}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+import { type CheckPolicyDocument } from "kibi-plugin-sdk";
+/**
+ * The UI design check policy this package ships. Kibi reads the same
+ * `check-policy.json` as data during `kb_check`; this export exists for tools
+ * and tests that want the document without reading the file.
+ */
+export declare const UI_CHECK_POLICY: CheckPolicyDocument;
+/**
+ * Named plugin export required by the Kibi host loader. The plugin declares no
+ * permissions: it only contributes a check policy document.
+ */
+export declare const kibiPlugin: {
+    apiVersion: "kibi.plugin.v1";
+    id: string;
+    version: string;
+    permissions: {
+        network: false;
+        metered: false;
+        secrets: never[];
+    };
+    capabilities: {
+        checkPolicy: {
+            id: string;
+            document: CheckPolicyDocument;
+        };
+    };
+};
+export default kibiPlugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,iBAAiB,CAAC;AAKzB;;;;GAIG;AAEH,eAAO,MAAM,eAAe,EAAE,mBAE7B,CAAC;AAEF;;;GAGG;AAEH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;CAerB,CAAC;AAGH,eAAe,UAAU,CAAC"}

package/dist/index.js

@@ -0,0 +1,34 @@
+import { createRequire } from "node:module";
+import { KIBI_PLUGIN_API_VERSION, defineKibiPlugin, validateCheckPolicyDocument, } from "kibi-plugin-sdk";
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+/**
+ * The UI design check policy this package ships. Kibi reads the same
+ * `check-policy.json` as data during `kb_check`; this export exists for tools
+ * and tests that want the document without reading the file.
+ */
+// implements REQ-ui-plugin-design-policy
+export const UI_CHECK_POLICY = validateCheckPolicyDocument(require("../check-policy.json"));
+/**
+ * Named plugin export required by the Kibi host loader. The plugin declares no
+ * permissions: it only contributes a check policy document.
+ */
+// implements REQ-ui-plugin-design-policy
+export const kibiPlugin = defineKibiPlugin({
+    apiVersion: KIBI_PLUGIN_API_VERSION,
+    id: "kibi-plugin-ui",
+    version: packageJson.version,
+    permissions: {
+        network: false,
+        metered: false,
+        secrets: [],
+    },
+    capabilities: {
+        checkPolicy: {
+            id: "kibi-plugin-ui.check-policy",
+            document: UI_CHECK_POLICY,
+        },
+    },
+});
+// implements REQ-ui-plugin-design-policy
+export default kibiPlugin;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "kibi-plugin-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Experimental Kibi check policy that keeps UI components on their agreed design patterns",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./check-policy.json": "./check-policy.json"
+  },
+  "files": ["dist", "check-policy.json", "CHANGELOG.md", "README.md"],
+  "kibi": {
+    "checkPolicy": "check-policy.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test --timeout 15000 .",
+    "prepack": "npm run build && node ../../scripts/verify-package-contract.mjs kibi-plugin-ui"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "AGPL-3.0-or-later",
+  "author": "Piotr Franczyk",
+  "homepage": "https://looted.github.io/kibi/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Looted/kibi.git",
+    "directory": "packages/plugin-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/Looted/kibi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["kibi", "kibi-plugin", "design-system", "ui"],
+  "dependencies": {
+    "kibi-plugin-sdk": "^0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "latest",
+    "typescript": "^5.7.0"
+  }
+}