@konvert7/klint 0.23.0 → 0.24.1

package/README.md

@@ -8,7 +8,14 @@ Use klint when "please follow AGENTS.md" is not strong enough. Put the rule in `
 
 ## Install
 
-klint currently runs on Bun.
+For macOS native CLI usage:
+
+```sh
+brew tap konvert7/tap
+brew install klint
+```
+
+For TypeScript projects using Bun:
 
 ```sh
 bun add -d @konvert7/klint
@@ -90,6 +97,7 @@ klint is for rules that are too project-specific or context-heavy for a formatte
 | Layer boundaries | `src/components/**` must not import from `src/data/**` |
 | Singleton ownership | `process.env.API_KEY` may only appear in `src/lib/auth.ts` |
 | Forbidden patterns | `console.log(` is blocked inside hook libraries |
+| Raw JSX elements | `<button>` is blocked outside `src/components/ui/**` |
 | Type-aware mistakes | Promise-returning calls cannot be silently discarded |
 | Repository policy | Custom `klint.rules.ts` rules run with the same severity/config system |
 
@@ -266,6 +274,18 @@ arch:
       message: "Libraries should return or throw, not terminate the process"
 ```
 
+Block raw JSX/HTML elements with `jsx-element` to push consumers onto design-system primitives. It is AST-matched on intrinsic (lowercase) tag names, so it is robust to whitespace, attributes, and lookalikes like `<buttonGroup>`:
+
+```yaml
+arch:
+  forbidden:
+    - jsx-element: ["button", "input", "label"]
+      in: ["src/app/**/*.tsx", "src/components/**/*.tsx", "!src/components/ui/**"]
+      message: "Use the design-system primitives in @/components/ui/* instead of raw HTML elements"
+```
+
+`jsx-element` matches intrinsic HTML elements only — not custom components like `<Button>`. Use `arch.imports` to restrict those.
+
 ### Singleton Locations
 
 Enforce that a pattern appears only in one designated file:
@@ -279,6 +299,17 @@ arch:
       message: "Use the auth module"
 ```
 
+`singleton` accepts `jsx-element` too — pin a raw element to the one primitive file that is allowed to render it:
+
+```yaml
+arch:
+  singleton:
+    - jsx-element: "button"
+      only: "src/components/ui/button.tsx"
+      in: ["src/**/*.tsx"]
+      message: "Raw <button> belongs only to the Button primitive"
+```
+
 ### Python Architecture Checks
 
 The Rust engine can apply architecture rules to Python projects:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konvert7/klint",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Architecture-as-Code linter for TypeScript. Enforce layer boundaries, import rules, and singleton patterns in YAML.",
   "type": "module",
   "bin": {
@@ -64,10 +64,10 @@
     "zod": "^4.4.3"
   },
   "optionalDependencies": {
-    "@konvert7/klint-darwin-arm64": "0.23.0",
-    "@konvert7/klint-darwin-x64": "0.23.0",
-    "@konvert7/klint-linux-x64": "0.23.0",
-    "@konvert7/klint-win32-x64": "0.23.0"
+    "@konvert7/klint-darwin-arm64": "0.24.1",
+    "@konvert7/klint-darwin-x64": "0.24.1",
+    "@konvert7/klint-linux-x64": "0.24.1",
+    "@konvert7/klint-win32-x64": "0.24.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.7",

package/skill/klint-rules/SKILL.md

@@ -4,6 +4,19 @@ description: Add, modify, or explain klint architecture rules for this repo. Use
 argument-hint: <constraint to enforce>
 ---
 
+## Schema
+
+The full, authoritative config schema lives in the repo and is the source of truth for every field below:
+
+- YAML: <https://github.com/konvert7/klint/blob/main/klint.schema.yaml>
+- JSON: <https://github.com/konvert7/klint/blob/main/klint.schema.json>
+
+Wire it into `klint.yaml` for editor autocomplete and validation:
+
+```yaml
+# yaml-language-server: $schema=./klint.schema.yaml
+```
+
 ## Workflow
 
 1. **Understand the constraint** — if scope is ambiguous, ask: which files/layers are involved? should it block or warn? are there legitimate exceptions?
@@ -19,8 +32,10 @@ argument-hint: <constraint to enforce>
    |---|---|
    | Layer X must not import from layer Y | `arch.imports` + `deny` |
    | Layer X may only import from Y and Z | `arch.imports` + `allow` |
-   | Pattern P must only appear in one designated file | `arch.singleton` |
-   | Pattern P must never appear inside a scoped layer | `arch.forbidden` |
+   | Pattern P must only appear in one designated file | `arch.singleton` + `pattern` |
+   | Pattern P must never appear inside a scoped layer | `arch.forbidden` + `pattern` |
+   | Raw HTML/JSX element must never appear in a scoped layer | `arch.forbidden` + `jsx-element` |
+   | Raw HTML/JSX element may only appear in one primitive file | `arch.singleton` + `jsx-element` |
 
 4. **Read `klint.yaml`** — check existing `arch.layers` and rules before adding anything. Add a new named layer to `arch.layers` if the file group doesn't exist yet.
 
@@ -69,29 +84,56 @@ arch:
 ```
 
 ### Singleton — one designated location
+
+Pin a `pattern` (literal string) **or** a `jsx-element` (AST-matched tag) to exactly one file. Every other in-scope occurrence is a violation.
+
 ```yaml
 arch:
   singleton:
+    # pattern: literal string match — fires if it appears anywhere except `only`
     - pattern: "process.env.API_KEY"
       only: "src/lib/auth.ts"
-      in: ["src/**"]           # optional: limit scan scope (default: all files)
+      in: ["src/**"]           # optional: limit scan scope (default: all files). string OR array
       message: "Use the auth module instead of reading API_KEY directly"
+      severity: error          # optional — default error; use warn to record without blocking
+
+    # jsx-element: pin a raw element to its design-system primitive
+    - jsx-element: "button"     # one tag, or a list: ["button", "input"]
+      only: "src/components/ui/button.tsx"
+      in: ["src/**/*.tsx"]
+      message: "Raw <button> belongs only to the Button primitive"
 ```
 
-`pattern` is a **literal string match**. It fires if the pattern appears in any in-scope file except the `only` file.
+Required: `only` + `message`, plus one of `pattern` / `jsx-element` (not both in the same stanza).
 
 ### Forbidden — banned pattern in scope
+
+Block a `pattern` (literal string) **or** a `jsx-element` (AST-matched tag) inside a scoped layer.
+
 ```yaml
 arch:
   forbidden:
+    # pattern: literal substring — no regex
     - pattern: "console.log("
-      in: ["src/lib/**"]
+      in: ["src/lib/**"]       # string OR array; supports ! negation
       message: "Use the logger — console.log leaks into the agent event stream"
+      severity: error          # optional — default error; use warn to record without blocking
+
+    # jsx-element: forbid raw HTML elements outside the design system
+    - jsx-element: ["button", "input", "label"]
+      in: ["src/app/**/*.tsx", "src/components/**/*.tsx", "!src/components/ui/**"]
+      message: "Use the design-system primitives in @/components/ui/* instead of raw HTML elements"
 ```
 
+Required: `in` + `message`, plus one of `pattern` / `jsx-element` (not both in the same stanza).
+
+`jsx-element` matches intrinsic element names on the AST (opening and self-closing tags), so it is robust to whitespace, attributes, and naming collisions like `<buttonGroup>` — unlike a literal `pattern: "<button"` scan. It works on `.tsx`/`.jsx` files in both the TS and Rust engines.
+
 ## Pitfalls
 
 - `pattern` in `singleton` and `forbidden` is a **literal string** — will not catch `process.env["KEY"]` (bracket notation). Grep for both forms if both are possible.
+- `jsx-element` matches **intrinsic** (lowercase HTML) tags only — `button`, `input`, `label`. It does not match custom React components like `<Button>`; to restrict those, use `arch.imports` against the component's module instead.
+- A `forbidden`/`singleton` stanza takes either `pattern` or `jsx-element`, never both — split into two stanzas if you need both.
 - `only` in `singleton` is relative to the project root — use forward slashes on all platforms.
 - `severity: warn` records the violation but does not block the session. Use `error` (the default) to block.
 - Path aliases (`@/*`) resolve via `tsconfig.json` `compilerOptions.paths`, including `extends` chains.

package/tools/generate-homebrew-formula.ts

@@ -0,0 +1,64 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+interface FormulaOptions {
+  version: string;
+  darwinArm64Sha: string;
+  darwinX64Sha: string;
+}
+
+export function homebrewFormula(options: FormulaOptions): string {
+  const version = options.version.replace(/^v/, "");
+
+  return `# typed: false
+# frozen_string_literal: true
+
+class Klint < Formula
+  desc "Architecture-as-Code linter for TypeScript, Python, and Swift projects"
+  homepage "https://github.com/konvert7/klint"
+  version "${version}"
+  license "MIT"
+
+  if Hardware::CPU.arm?
+    url "https://github.com/konvert7/klint/releases/download/native-v${version}/klint-${version}-darwin-arm64.tar.gz"
+    sha256 "${options.darwinArm64Sha}"
+  else
+    url "https://github.com/konvert7/klint/releases/download/native-v${version}/klint-${version}-darwin-x64.tar.gz"
+    sha256 "${options.darwinX64Sha}"
+  end
+
+  def install
+    binary = File.exist?("klint") ? "klint" : Dir["klint-*/klint"].first
+    odie "klint binary not found" unless binary
+    bin.install binary => "klint"
+  end
+
+  test do
+    assert_match "klint-rs", shell_output("#{bin}/klint --version")
+  end
+end
+`;
+}
+
+if (import.meta.main) {
+  const args = process.argv.slice(2);
+  const output = requireValue(args, "--output");
+  const formula = homebrewFormula({
+    version: requireValue(args, "--version"),
+    darwinArm64Sha: requireValue(args, "--darwin-arm64-sha"),
+    darwinX64Sha: requireValue(args, "--darwin-x64-sha"),
+  });
+
+  const path = resolve(output);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, formula);
+}
+
+function requireValue(args: string[], name: string): string {
+  const index = args.indexOf(name);
+  const value = index >= 0 ? args[index + 1] : undefined;
+  if (!value) {
+    throw new Error(`${name} is required`);
+  }
+  return value;
+}