bluetemberg-rules-typescript 0.1.0

package/llm/rules/coding-standards.md

@@ -0,0 +1,21 @@
+---
+description: Keep functions and components small, readable, and easy to reason about.
+scope: "**"
+---
+
+# Coding standards
+
+Keep functions and components small, readable, and easy to reason about.
+
+## Function complexity
+
+- Prefer small, single-purpose functions.
+- Keep control flow shallow; avoid deep nesting.
+- Use early returns and guard clauses to reduce `else` blocks.
+- Extract complex logic into well-named helpers.
+
+## Readability
+
+- Favor descriptive names for functions, variables, and components.
+- Avoid magic numbers/strings; use constants where appropriate.
+- Keep conditionals straightforward; prefer `if (!condition) return` patterns.

package/llm/rules/design-system-reuse.md

@@ -0,0 +1,13 @@
+---
+description: Reuse existing shared UI components and design tokens before creating new ones.
+scope: "**/*.{tsx,jsx,svelte,vue}"
+---
+
+# Design system usage
+
+When building new features or screens:
+
+- Reuse existing shared UI components before introducing new bespoke ones.
+- Prefer design tokens and shared theme primitives over hardcoded values.
+- Only introduce new UI components if no suitable shared component exists.
+- Keep component APIs and naming consistent across the workspace.

package/llm/rules/early-returns.md

@@ -0,0 +1,39 @@
+---
+description: Prefer early returns and guard clauses over nested conditionals.
+scope: "**"
+---
+
+# Early returns
+
+Use early returns and guard clauses to keep control flow flat and readable.
+
+## Patterns
+
+- Return early for invalid input, missing data, or edge cases at the top of functions.
+- Avoid `else` blocks when the `if` branch returns or throws.
+- Flatten nested `if`/`else` chains by inverting conditions.
+
+## Examples
+
+```ts
+// BAD — deeply nested
+function process(user) {
+  if (user) {
+    if (user.isActive) {
+      if (user.hasPermission) {
+        return doWork(user);
+      }
+    }
+  }
+  return null;
+}
+
+// GOOD — guard clauses
+function process(user) {
+  if (!user) return null;
+  if (!user.isActive) return null;
+  if (!user.hasPermission) return null;
+
+  return doWork(user);
+}
+```

package/llm/rules/no-console-log.md

@@ -0,0 +1,31 @@
+---
+description: Forbid console.log in production code; use a logger instead.
+scope: "src/**"
+---
+
+# No console.log in production code
+
+Never use `console.log` (or `console.warn`, `console.error`, `console.debug`) directly in source files under `src/`.
+
+Use the project logger instead so that log output is structured, level-controlled, and safe to ship.
+
+## Examples
+
+```ts
+// BAD
+console.log("Fetching page", slug);
+console.error("Something went wrong", err);
+
+// GOOD
+logger.info("Fetching page", { slug });
+logger.error("Something went wrong", { error: err });
+```
+
+## Exceptions
+
+CLI entry points and files whose sole purpose is user-facing terminal output may use `console.log` directly. All other `src/` code must use a structured logger.
+
+## Why
+
+- `console.*` calls leak implementation details and unstructured output into production.
+- A logger allows log-level filtering, structured metadata, and integration with observability tooling.

package/llm/rules/type-safety.md

@@ -0,0 +1,30 @@
+---
+description: Enforce strict type safety — no implicit any, no unguarded assertions.
+scope: "**"
+---
+
+# Type safety
+
+Maintain strict type safety across the codebase.
+
+## Rules
+
+- Never use `any`. Use `unknown` when the type is genuinely uncertain, then narrow.
+- Avoid type assertions (`as`) unless you add a comment explaining why it's safe.
+- Enable and respect `strict` mode in `tsconfig.json`.
+- Prefer type guards (`typeof`, `instanceof`, discriminated unions) over assertions.
+- Use `satisfies` for object literals when you want type checking without widening.
+
+## Examples
+
+```ts
+// BAD
+const data: any = fetchData();
+const name = (response as User).name;
+
+// GOOD
+const data: unknown = fetchData();
+if (isUser(data)) {
+  const name = data.name;
+}
+```

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "bluetemberg-rules-typescript",
+  "version": "0.1.0",
+  "description": "TypeScript code quality rules for Bluetemberg — type safety, coding standards, early returns, no console.log, design system reuse.",
+  "keywords": [
+    "bluetemberg-pack",
+    "rules",
+    "typescript",
+    "code-quality"
+  ],
+  "author": "Prototyp Digital",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/prototypdigital/bluetemberg-packs.git"
+  },
+  "files": [
+    "llm/"
+  ]
+}