@canonical/code-standards 0.1.0

package/data/code.ttl

@@ -0,0 +1,437 @@
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# General Code Category
+cs:CodeCategory a cs:Category ;
+    rdfs:label "Code"@en ;
+    rdfs:comment "General typescript coding standards and best practices"@en ;
+    cs:slug "code" .
+
+# Function Purity Standard
+cs:FunctionPurity a cs:CodeStandard ;
+    cs:name "code/function/purity" ;
+    cs:hasCategory cs:CodeCategory ;
+    cs:description "Functions should be pure where possible. A pure function returns the same output for the same input and does not modify external state or perform I/O operations. If a function must perform side effects (e.g., I/O in CLI tools), it must be explicitly annotated and documented with the reason for impurity using the @note tag in TSDoc/JSDoc." ;
+    cs:dos """
+(Do) Create pure functions that rely only on their inputs to compute the output.
+```typescript
+const calculatePrice = (basePrice: number, taxRate: number): number => {
+  return basePrice * (1 + taxRate);
+};
+```
+
+(Do) Annotate and document impure functions that perform I/O or modify external state, explaining why impurity is necessary using @note.
+```typescript
+/**
+ * Writes data to the file system.
+ * @note - This function is impure - it modifies the file system.
+ */
+function writeOutputToFile(data: string, path: string) {
+  fs.writeFileSync(path, data);
+}
+```
+""" ;
+    cs:donts """
+(Don't) Create impure functions without annotation or documentation.
+```typescript
+let total = 0;
+const addToTotal = (value: number) => {
+  total += value; // Modifies external state, not documented
+};
+```
+
+(Don't) Hide side effects in functions that appear pure.
+```typescript
+function getConfig() {
+  // Reads from disk without annotation
+  return fs.readFileSync('config.json');
+}
+```
+""" .
+
+# Function Composition Standard
+cs:FunctionComposition a cs:CodeStandard ;
+    cs:name "code/function/composition" ;
+    cs:hasCategory cs:CodeCategory ;
+    cs:description "Each function must handle exactly one specific task. Complex operations must be broken down into smaller, single-purpose functions." ;
+    cs:dos """
+(Do) Define functions with a single, clear responsibility.
+```typescript
+const validateEmail = (email: string): boolean => {
+  return /^[^@]+@[^@]+\\.[^@]+$/.test(email);
+};
+```
+
+(Do) Compose single-purpose functions to build complex logic.
+```typescript
+const validatePassword = (password: string): boolean => {
+  return password.length >= 8;
+};
+
+const validateForm = (email: string, password:string): boolean => {
+  return validateEmail(email) && validatePassword(password);
+};
+```
+""" ;
+    cs:donts """
+(Don't) Mix multiple responsibilities in a single function.
+```typescript
+const processUserData = (user: any) => {
+  // Validates user data
+  // Transforms the data
+  // Saves to the database
+  // Sends a notification
+};
+```
+""" .
+
+# Function Location Standard
+cs:FunctionLocation a cs:CodeStandard ;
+    cs:name "code/function/location" ;
+    cs:hasCategory cs:CodeCategory ;
+    cs:description "Functions must be defined as close to their broadest point of use as possible. Shared utilities must be placed in a common location, and each function must serve a single feature or responsibility." ;
+    cs:dos """
+(Do) Place functions in the file or module where they are most broadly used. If a function is shared across multiple components or modules, place it in a common utility location.
+```typescript
+// utils/math.ts
+export function calculateSum(a: number, b: number): number {
+  return a + b;
+}
+
+// Used in multiple places
+import { calculateSum } from './utils/math.js';
+
+// For single-use functions, keep them close to their usage:
+```typescript
+// services/UserService.ts
+const formatUserName = (user: User) => `${user.firstName} ${user.lastName}`;
+
+const getProfileData = (user: User) => {
+  const formattedName = formatUserName(user);
+  return {
+    ...user,
+    formattedName,
+  };
+};
+
+""" ;
+    cs:donts """
+(Don't) Place functions far from where they are used, or in a generic location if only used in one place.
+```typescript
+// utils/validators.ts
+export const validateUser = (user: User) => { ... }; // Only used in one component
+
+// services/UserService.ts
+import { validateUser } from '../utils/validators.js'; // Less ideal if only used here
+
+// Don't mix unrelated functions in a single file:
+```typescript
+export const mathFunc = () => {};
+export const stringFunc = () => {};
+""" .
+
+# API Stability Standard
+cs:APIStability a cs:CodeStandard ;
+    cs:name "code/api/stability" ;
+    cs:hasCategory cs:CodeCategory ;
+    cs:description "Experimental APIs must be marked with the @experimental JSDoc tag in type definition files. The tag must include a description of what is experimental." ;
+    cs:dos """
+(Do) Mark an experimental interface with a clear @experimental JSDoc tag and description.
+```typescript
+/**
+ * Configuration for the data processing pipeline.
+ * @experimental The streaming API is experimental and may change
+ * in future releases. Currently, it only supports JSON data.
+ */
+interface PipelineConfig {
+  // ...
+}
+```
+
+(Do) Add an @experimental tag to a specific property with context about its experimental status.
+```typescript
+interface PipelineConfig {
+  /**
+   * @experimental The custom transformers API is in beta, and the interface
+   * may change to support stronger type validation.
+   */
+  transformers?: DataTransformer[];
+}
+```
+
+(Do) Describe the experimental status and any future plans for the API.
+```typescript
+interface CacheConfig {
+  /**
+   * @experimental The distributed cache API is experimental and will be
+   * replaced with a new consensus-based implementation in v2.1.
+   */
+  distributed?: boolean;
+}
+```
+""" ;
+    cs:donts """
+(Don't) Use the @experimental tag without an explanation.
+```typescript
+interface ProcessorConfig {
+  /** @experimental */ // Bad: No context provided.
+  streaming?: boolean;
+}
+```
+
+(Don't) Use the @experimental tag without describing what is experimental.
+```typescript
+/**
+ * @experimental // Bad: No description of what is experimental.
+ */
+interface QueueConfig {
+  processor: (item: any) => Promise<void>;
+}
+```
+""" .
+
+# Function Verb Naming Standard
+cs:FunctionVerbNaming a cs:CodeStandard ;
+    cs:name "code/naming/function-verb" ;
+    cs:hasCategory cs:CodeCategory ;
+    cs:description "All function and method names must start with a verb that describes the action the function performs. Names like `pathToX` or `dataForUser` describe a result, not an action — use `findPathToX` or `fetchDataForUser` instead. This makes the function's intent immediately clear and distinguishes functions from plain values or constants." ;
+    cs:dos """
+(Do) Start function names with an action verb:
+```typescript
+const findPathToModule = (name: string): string => { /* ... */ };
+const fetchDataForUser = (userId: string): Promise<User> => { /* ... */ };
+const parseConfigFile = (path: string): Config => { /* ... */ };
+const calculateTotalPrice = (items: Item[]): number => { /* ... */ };
+const isValidEmail = (email: string): boolean => { /* ... */ };
+const hasPermission = (user: User, action: string): boolean => { /* ... */ };
+```
+
+(Do) Use descriptive verb prefixes that convey the operation:
+```typescript
+// Retrieval: get, fetch, find, resolve, load, read
+const getUser = (id: string): User => { /* ... */ };
+const fetchOrders = (): Promise<Order[]> => { /* ... */ };
+const findMatchingRule = (rules: Rule[], input: string): Rule | undefined => { /* ... */ };
+
+// Transformation: format, parse, convert, transform, map, normalize
+const formatDate = (date: Date): string => { /* ... */ };
+const parseResponse = (raw: string): Response => { /* ... */ };
+
+// Validation: is, has, can, should, validate, check
+const isActive = (user: User): boolean => { /* ... */ };
+const hasExpired = (token: Token): boolean => { /* ... */ };
+const validateInput = (data: unknown): data is FormData => { /* ... */ };
+
+// Mutation: set, update, add, remove, delete, reset, clear
+const setTheme = (theme: Theme): void => { /* ... */ };
+const removeItem = (id: string): void => { /* ... */ };
+
+// Creation: create, build, generate, compose, make
+const createConnection = (config: Config): Connection => { /* ... */ };
+const buildQuery = (params: Params): string => { /* ... */ };
+```
+""" ;
+    cs:donts """
+(Don't) Name functions as nouns or noun phrases — they read like values, not actions:
+```typescript
+// Bad: reads like a variable, not a function
+const pathToModule = (name: string): string => { /* ... */ };
+// Good: findPathToModule
+
+const dataForUser = (userId: string): Promise<User> => { /* ... */ };
+// Good: fetchDataForUser
+
+const userPermissions = (user: User): Permission[] => { /* ... */ };
+// Good: getPermissions or listPermissions
+```
+
+(Don't) Use vague or non-descriptive verbs that don't convey meaning:
+```typescript
+// Bad: "do" and "process" are too vague on their own
+const doEmail = (email: string) => { /* ... */ };
+// Good: sendEmail, validateEmail, formatEmail
+
+const processUser = (user: User) => { /* ... */ };
+// Good: activateUser, deactivateUser, updateUser
+```
+""" .
+
+# Constants File Standard
+cs:ConstantsFile a cs:CodeStandard ;
+    cs:name "code/constants/file" ;
+    cs:hasCategory cs:CodeCategory ;
+    cs:description "Domain constants must be collected in a `constants.ts` file using named exports (no default export). The file must be colocated at the level of the domain that owns the constants — inside the domain folder when one exists. Constants files always use named exports so consumers can import exactly what they need. Single-use constants that are only referenced in one file may be declared inline in that file instead of being extracted to `constants.ts`." ;
+    cs:dos """
+(Do) Create a `constants.ts` file with named exports at the domain level:
+```typescript
+// features/pricing/constants.ts
+export const DEFAULT_CURRENCY = "USD";
+export const TAX_RATE = 0.21;
+export const MAX_DISCOUNT_PERCENT = 50;
+```
+
+(Do) Colocate `constants.ts` inside the domain folder it belongs to:
+```
+features/
+├── pricing/
+│   ├── constants.ts          # Domain constants live here
+│   ├── calculatePrice.ts
+│   └── index.ts
+├── auth/
+│   ├── constants.ts          # Auth-specific constants
+│   ├── validateToken.ts
+│   └── index.ts
+```
+
+(Do) Import constants directly from the owning domain's `constants.ts`:
+```typescript
+// features/pricing/calculatePrice.ts
+import { TAX_RATE, DEFAULT_CURRENCY } from "./constants.js";
+```
+
+(Do) Keep all exports in `constants.ts` as named exports with the same shape (plain values):
+```typescript
+// constants.ts
+export const RECONNECT_INTERVAL_MS = 5000;
+export const MAX_RETRIES = 3;
+export const DEFAULT_TIMEOUT_MS = 30_000;
+```
+
+(Do) Keep single-use constants inline in the file that uses them:
+```typescript
+// features/pricing/applyDiscount.ts
+const MAX_DISCOUNT_PERCENT = 50;
+
+export default function applyDiscount(price: number, rate: number): number {
+  const capped = Math.min(rate, MAX_DISCOUNT_PERCENT / 100);
+  return price * (1 - capped);
+}
+```
+""" ;
+    cs:donts """
+(Don't) Use a default export in a constants file:
+```typescript
+// Bad: default export forces consumers to name the import
+export default {
+  DEFAULT_CURRENCY: "USD",
+  TAX_RATE: 0.21,
+};
+```
+
+(Don't) Scatter constants across unrelated files instead of collecting them in `constants.ts`:
+```typescript
+// Bad: constants buried inside implementation files
+// calculatePrice.ts
+export const TAX_RATE = 0.21;
+const calculatePrice = (base: number) => base * (1 + TAX_RATE);
+export default calculatePrice;
+```
+
+(Don't) Place constants far from the domain that owns them:
+```typescript
+// Bad: pricing constants in a top-level shared file
+// src/constants.ts
+export const TAX_RATE = 0.21;        // Belongs in pricing/
+export const MAX_RETRIES = 3;        // Belongs in network/
+export const SESSION_TTL_MS = 3600;  // Belongs in auth/
+```
+
+(Don't) Mix constants with functions, types, or other non-constant exports:
+```typescript
+// Bad: constants.ts should only contain constant values
+export const MAX_RETRIES = 3;
+export const formatRetryMessage = (n: number) => `Retry ${n} of ${MAX_RETRIES}`;
+export type RetryConfig = { max: number };
+```
+""" .
+
+# Types File Standard
+cs:TypesFile a cs:CodeStandard ;
+    cs:name "code/types/file" ;
+    cs:hasCategory cs:CodeCategory ;
+    cs:description "Reusable domain types must be collected in a `types.ts` file using named exports (no default export), colocated at the level of the domain that owns them. Types that are only used in a single file may be declared inline in that file instead of being extracted to `types.ts`." ;
+    cs:dos """
+(Do) Create a `types.ts` file with named exports for types shared across the domain:
+```typescript
+// features/pricing/types.ts
+export type Currency = "USD" | "EUR" | "GBP";
+export interface PriceBreakdown {
+  base: number;
+  tax: number;
+  total: number;
+}
+export type DiscountStrategy = "percentage" | "fixed";
+```
+
+(Do) Colocate `types.ts` inside the domain folder it belongs to:
+```
+features/
+├── pricing/
+│   ├── types.ts              # Shared domain types live here
+│   ├── constants.ts
+│   ├── calculatePrice.ts
+│   └── index.ts
+├── auth/
+│   ├── types.ts              # Auth-specific types
+│   ├── validateToken.ts
+│   └── index.ts
+```
+
+(Do) Keep single-use types inline in the file that uses them:
+```typescript
+// features/pricing/applyDiscount.ts
+type DiscountResult = { discounted: number; savings: number };
+
+export default function applyDiscount(price: number, rate: number): DiscountResult {
+  const savings = price * rate;
+  return { discounted: price - savings, savings };
+}
+```
+
+(Do) Import shared types from the owning domain's `types.ts`:
+```typescript
+// features/pricing/calculatePrice.ts
+import type { Currency, PriceBreakdown } from "./types.js";
+```
+""" ;
+    cs:donts """
+(Don't) Use a default export in a types file:
+```typescript
+// Bad: default export for a collection of types
+export default interface PriceBreakdown {
+  base: number;
+  tax: number;
+  total: number;
+}
+```
+
+(Don't) Extract single-use types to `types.ts` when they are only used in one file:
+```typescript
+// Bad: types.ts contains a type only used in applyDiscount.ts
+// types.ts
+export type DiscountResult = { discounted: number; savings: number };
+
+// applyDiscount.ts
+import type { DiscountResult } from "./types.js"; // Unnecessary indirection
+```
+
+(Don't) Place types far from the domain that owns them:
+```typescript
+// Bad: all types dumped in a top-level shared file
+// src/types.ts
+export type Currency = "USD" | "EUR" | "GBP";  // Belongs in pricing/
+export type AuthToken = { jwt: string };         // Belongs in auth/
+export type RetryPolicy = { max: number };       // Belongs in network/
+```
+
+(Don't) Mix types with functions, constants, or other non-type exports:
+```typescript
+// Bad: types.ts should only contain type declarations
+export type Currency = "USD" | "EUR" | "GBP";
+export const DEFAULT_CURRENCY: Currency = "USD";
+export const formatCurrency = (value: number, currency: Currency) => `${currency} ${value}`;
+```
+""" .

package/data/css.ttl

@@ -0,0 +1,265 @@
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+# CSS Category
+cs:CSSCategory a cs:Category ;
+    rdfs:label "CSS"@en ;
+    rdfs:comment "Standards for CSS technical implementation"@en ;
+    cs:slug "css" .
+
+# CSS Selector Namespace Standard
+cs:CSSSelectorNamespace a cs:CodeStandard ;
+    cs:name "css/selectors/namespace" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description "All component selectors must be prefixed with the `.ds` namespace (e.g., `.ds.button`)." ;
+    cs:dos """
+(Do) Prefix all component selectors with `.ds`.
+```css
+/* Component root with namespace */
+.ds.button {
+  /* Base styles */
+}
+```
+""" ;
+    cs:donts """
+(Don't) Omit the `.ds` namespace from component selectors.
+```css
+/* Bad: Missing .ds namespace */
+.button {
+  /* styles */
+}
+```
+""" .
+
+# CSS Component Encapsulation Standard
+cs:CSSComponentEncapsulation a cs:CodeStandard ;
+    cs:name "css/component/encapsulation" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description "Component styles must be encapsulated using the component's root class as a boundary. All internal element styles must be scoped to the component's namespace." ;
+    cs:dos """
+(Do) Scope internal element styles using the component's namespace.
+```css
+.ds.button {
+  /* Component root styles */
+  
+  & > .icon {
+    /* Internal element styles */
+    margin-right: var(--button-icon-spacing);
+  }
+}
+```
+""" ;
+    cs:donts """
+(Don't) Don't style internal elements without the component namespace.
+```css
+/* Bad: Internal element not scoped to component */
+.icon {
+  margin-right: var(--button-icon-spacing);
+}
+```
+""" .
+
+# CSS State Handling Standard
+cs:CSSStateHandling a cs:CodeStandard ;
+    cs:name "css/component/states" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description "Component states must be handled using attribute selectors for native states and class modifiers for custom states." ;
+    cs:dos """
+(Do) Use attribute selectors for native element states.
+```css
+.ds.button {
+  &[disabled] {
+    opacity: var(--button-disabled-opacity);
+  }
+}
+```
+""" ;
+    cs:donts """
+(Don't) Use class modifiers for native states.
+```css
+/* Bad: Using class for native state */
+.ds.button.disabled {
+  opacity: var(--button-disabled-opacity);
+}
+```
+""" .
+
+# CSS Specificity Management Standard
+cs:CSSSpecificityManagement a cs:CodeStandard ;
+    cs:name "css/selectors/specificity" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description """CSS selectors must follow a strict specificity pattern:
+- Component root must use namespace + component name (.ds.button)
+- Single modifier class for variants (.ds.button.primary)
+- Single attribute for states (.ds.button[disabled])""" ;
+    cs:dos """
+(Do) Use a single modifier class for component variants.
+```css
+.ds.button.primary {
+  /* Variant: root + modifier (3 classes) */
+  background: var(--button-primary-background);
+}
+```
+""" ;
+    cs:donts """
+(Don't) Combine multiple modifiers or mix states with variants.
+```css
+/* Bad: Mixing variant with state */
+.ds.button.primary[disabled].large {
+  /* Too specific: root + 2 modifiers + state */
+}
+```
+""" .
+
+# CSS Selector Semantics Standard
+cs:CSSSelectorSemantics a cs:CodeStandard ;
+    cs:name "css/selectors/semantics" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description "CSS class names must describe the purpose or state of an element, not its appearance." ;
+    cs:dos """
+(Do) Use semantic modifier classes to represent component variations.
+```css
+/* Semantic modifier for a primary button */
+.ds.button.primary {
+  --modifier-color: var(--color-primary);
+}
+```
+""" ;
+    cs:donts """
+(Don't) Use non-semantic or presentational class names.
+```css
+/* Bad: 'big' describes appearance, not purpose */
+.ds.button.big {
+  padding: 1rem;
+}
+```
+""" .
+
+# Theme Activation Standard
+cs:ThemeActivation a cs:CodeStandard ;
+    cs:name "css/themes/activation" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description """Theme tokens must be activated through CSS classes on container elements. See styling/themes/definition for theme token structure.""" ;
+    cs:dos """
+(Do) Define semantic tokens within theme classes.
+```css
+.canonical {
+  --spacing-vertical-medium: var(--spacing-unit-2x);
+  --color-background: var(--color-neutral-100);
+}
+```
+""" ;
+    cs:donts """
+(Don't) Hardcode theme names in component styles.
+```css
+/* Bad: Component locked to specific theme */
+.ds.button {
+  padding: var(--canonical-spacing-vertical-medium);
+}
+```
+""" .
+
+# CSS Property Values Standard
+cs:CSSPropertyValues a cs:CodeStandard ;
+    cs:name "css/properties/values" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description """CSS properties must use design tokens for design decisions (see styling/tokens/creation) and raw values for properties that are independent from design decisions, or "unthemable".""" ;
+    cs:dos """
+(Do) Use design tokens for design decisions.
+```css
+.ds.button {
+  /* Design decision uses token */
+  background: var(--button-background);
+}
+```
+(Do) Use raw values for unthemable properties (independent of design decisions).
+```css
+.ds.skip-link {
+    visibility: hidden;
+}
+```
+""" ;
+    cs:donts """
+(Don't) Use raw values for design decisions.
+```css
+.ds.button {
+  /* Bad: Design decision using raw value */
+  background: #0066CC;
+}
+```
+""" .
+
+# Child Element Naming Standard
+cs:CSSChildElementNaming a cs:CodeStandard ;
+    cs:name "css/selectors/child-elements" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description """Child elements within components must use simple, role-based class names (e.g., `.header`, `.content`, `.icon`) scoped by the parent selector, NOT verbose prefixed names that repeat the component name.""" ;
+    cs:dos """
+(Do) Use simple role-based class names scoped by the parent.
+```css
+.ds.accordion-item {
+  & > .header {
+    /* Header styles */
+  }
+
+  & > .header > .chevron {
+    /* Chevron indicator */
+  }
+
+  & > .header > .heading {
+    /* Heading text */
+  }
+
+  & > .content {
+    /* Collapsible content */
+  }
+}
+
+.ds.breadcrumbs-item {
+  & > .link {
+    /* Link styles */
+  }
+
+  & > .separator {
+    /* Separator styles */
+  }
+}
+```
+""" ;
+    cs:donts """
+(Don't) Use verbose prefixed class names that repeat the component name.
+```css
+/* Bad: Redundant component prefix in child class names */
+.ds.accordion-item .accordion-item-header {
+  /* 'accordion-item-' prefix is redundant */
+}
+
+.ds.accordion-item .accordion-item-chevron {
+  /* Already scoped by parent, no need to repeat */
+}
+
+.ds.timeline-event .timeline-event-marker {
+  /* Verbose and BEM-like */
+}
+```
+""" .
+
+# Component Naming Convention for CSS
+cs:CSSComponentNamingConvention a cs:CodeStandard ;
+    cs:name "css/selectors/naming-convention" ;
+    cs:hasCategory cs:CSSCategory ;
+    cs:description "Component CSS class names must be the kebab-case version of the component's PascalCase name." ;
+    cs:dos """
+(Do) Convert PascalCase component names to kebab-case for CSS classes:
+- `MyComponent` -> `.ds.my-component`
+- `UserProfile` -> `.ds.user-profile`
+- `Button` -> `.ds.button`
+""" ;
+    cs:donts """
+(Don't) Use PascalCase or other formats in CSS class names:
+- `.ds.MyComponent` (Bad: Not kebab-case)
+- `.ds.user_profile` (Bad: Not kebab-case)
+""" .