@canonical/code-standards 0.1.0

package/docs/code.md

@@ -0,0 +1,720 @@
+# Code Standards
+
+Standards for code development.
+
+## code/api/stability
+
+Experimental APIs must be marked with the @experimental JSDoc tag in type definition files. The tag must include a description of what is experimental.
+
+### Do
+
+(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;
+}
+```
+
+### Don't
+
+(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>;
+}
+```
+
+---
+
+## code/constants/file
+
+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`.
+
+### Do
+
+(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);
+}
+```
+
+### Don't
+
+(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 };
+```
+
+---
+
+## code/export/barrel-public-api
+
+Barrel files must exist only to define a public API surface. Internal implementation code must import concrete modules directly rather than routing through local barrels. Public barrels may exist at package entry points or at explicitly public subdomain boundaries.
+
+### Do
+
+(Do) Use a barrel for a package entry point or explicit public API:
+```typescript
+// src/index.ts
+export { Button } from "./components/Button.js";
+export type { ButtonProps } from "./components/Button.types.js";
+```
+
+(Do) Import internal implementation code from the owning file:
+```typescript
+// src/build/buildTheme.ts
+import { computeDeltas } from "./computeDeltas.js";
+import { recoverPrimitiveRef } from "./recoverPrimitiveRef.js";
+```
+
+(Do) Keep compatibility barrels thin and documented as public facades:
+```typescript
+/** Public compatibility surface. */
+export { computeDeltas } from "./computeDeltas.js";
+export { formatDelta } from "./formatDelta.js";
+```
+
+### Don't
+
+(Don't) Route internal code through a sibling barrel just because it exists:
+```typescript
+// Bad: internal implementation depends on a local barrel
+import { computeDeltas, recoverPrimitiveRef } from "./index.js";
+```
+
+(Don't) Hide domain ownership behind convenience barrels:
+```typescript
+// Bad: types appear to belong to context.ts instead of their owning domains
+import type { Artifact, CSSNode, OverlayToken } from "./context.js";
+```
+
+(Don't) Create folder barrels for implementation-only directories with no public API contract:
+```typescript
+// build/helpers/index.ts
+export * from "./parse.js";
+export * from "./format.js";
+export * from "./walk.js";
+```
+
+---
+
+## code/export/shape
+
+Files must use either a single default export or multiple named exports. When using multiple named exports, all exports must have the same type or shape.
+
+### Do
+
+(Do) Use a single default export for files implementing a single component or function:
+```typescript
+// ComponentName.tsx
+export default ComponentName;
+```
+
+(Do) Name atomic function files after the function they export:
+```typescript
+// assignElement.ts
+export default function assignElement(target: Element, source: Partial<Element>) {
+  // ...
+}
+
+// formatCurrency.ts
+export default function formatCurrency(value: number) {
+  // ...
+}
+```
+
+(Do) Use multiple named exports for files providing a public API or a collection of related items, and ensure all exports have the same type:
+```typescript
+// index.ts
+export { ComponentA, ComponentB };
+
+// types.ts
+export type TypeA = { ... };
+export type TypeB = { ... };
+
+// Consistent export shape:
+export const myFuncA = (value: string) => {};
+export const myFuncB = (value: string) => {};
+export const myFuncC = (value: string) => {};
+```
+
+### Don't
+
+(Don't) Mix default and unrelated named exports in a way that confuses the file's purpose:
+```typescript
+export default ComponentName;
+export const helper = () => {};
+```
+
+(Don't) Name an atomic function file with a name that doesn't match its exported function:
+```typescript
+// helpers.ts — wrong: generic name instead of function name
+export default function assignElement(target: Element, source: Partial<Element>) {
+  // ...
+}
+
+// utils.ts — wrong: generic name instead of function name
+export default function formatCurrency(value: number) {
+  // ...
+}
+```
+
+(Don't) Provide multiple unrelated exports from a file meant for a single domain:
+```typescript
+export default debounce;
+export const throttle = () => {};
+export const logger = () => {};
+```
+
+(Don't) Export objects of different types or shapes from the same file:
+```typescript
+export const transformer = (value: string) => {};
+export const reducer = (map: string[]) => {};
+class ABC {}
+export { ABC };
+```
+
+---
+
+## code/function/composition
+
+Each function must handle exactly one specific task. Complex operations must be broken down into smaller, single-purpose functions.
+
+### Do
+
+(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);
+};
+```
+
+### Don't
+
+(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
+};
+```
+
+---
+
+## code/function/location
+
+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.
+
+### Do
+
+(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,
+  };
+};
+
+### Don't
+
+(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 = () => {};
+
+---
+
+## code/function/purity
+
+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.
+
+### Do
+
+(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);
+}
+```
+
+### Don't
+
+(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');
+}
+```
+
+---
+
+## code/naming/function-verb
+
+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.
+
+### Do
+
+(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 => { /* ... */ };
+```
+
+### Don't
+
+(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
+```
+
+---
+
+## code/naming/single-export-file
+
+Files that contain a single export must be named after that export. This applies to functions, classes, types, constants, and any other single-export module. The file name must match the exported identifier exactly, preserving its casing (camelCase for functions/variables, PascalCase for classes/types/components).
+
+### Do
+
+(Do) Name files after the single function they export:
+```typescript
+// isAccepted.ts
+export const isAccepted = (status: string): boolean => {
+  return status === "accepted";
+};
+
+// formatCurrency.ts
+export default function formatCurrency(value: number): string {
+  return `$${value.toFixed(2)}`;
+}
+```
+
+(Do) Name files after the single type or interface they export:
+```typescript
+// ConnectionConfig.ts
+export interface ConnectionConfig {
+  host: string;
+  port: number;
+}
+
+// UserRole.ts
+export type UserRole = "admin" | "editor" | "viewer";
+```
+
+(Do) Name files after the single class they export:
+```typescript
+// EventEmitter.ts
+export class EventEmitter {
+  // ...
+}
+```
+
+(Do) Name files after the single constant they export:
+```typescript
+// DEFAULT_TIMEOUT.ts
+export const DEFAULT_TIMEOUT = 5000;
+```
+
+### Don't
+
+(Don't) Use generic names like `helpers.ts`, `utils.ts`, or `types.ts` for files with a single export:
+```typescript
+// helpers.ts — wrong: should be isAccepted.ts
+export const isAccepted = (status: string): boolean => {
+  return status === "accepted";
+};
+
+// utils.ts — wrong: should be formatCurrency.ts
+export default function formatCurrency(value: number): string {
+  return `$${value.toFixed(2)}`;
+}
+```
+
+(Don't) Use names that describe the domain instead of the export:
+```typescript
+// validation.ts — wrong: should be isAccepted.ts
+export const isAccepted = (status: string): boolean => {
+  return status === "accepted";
+};
+
+// network.ts — wrong: should be ConnectionConfig.ts
+export interface ConnectionConfig {
+  host: string;
+  port: number;
+}
+```
+
+---
+
+## code/package/lib-folder
+
+Packages that export reusable logic (components, utilities, hooks, types) must organize their exportable code in a `lib` folder within the `src` directory. This convention ensures consistency across the monorepo and clearly identifies code that is part of the package's public API.
+
+### Do
+
+(Do) Place all reusable/exportable code in `src/lib/`:
+```
+packages/my-package/
+├── src/
+│   ├── lib/
+│   │   ├── Button/
+│   │   │   ├── Button.tsx
+│   │   │   ├── Button.tests.tsx
+│   │   │   ├── types.ts
+│   │   │   └── index.ts
+│   │   ├── hooks/
+│   │   │   └── useToggle.ts
+│   │   ├── types/
+│   │   │   └── index.ts
+│   │   └── index.ts
+│   ├── storybook/           # Storybook-specific files (not exported)
+│   └── index.ts             # Re-exports from lib
+└── package.json
+```
+
+(Do) Re-export from the lib folder in the package entry point:
+```typescript
+// src/index.ts
+export * from "./lib/index.js";
+```
+
+(Do) Use the lib folder for components, hooks, utilities, types, and any other code meant to be consumed by package users:
+```typescript
+// src/lib/index.ts
+export * from "./Button/index.js";
+export * from "./hooks/index.js";
+export type * from "./types/index.js";
+```
+
+### Don't
+
+(Don't) Use alternative folder names like `ui`, `components`, or `utils` for exportable code at the package level:
+```
+// Bad: Using 'ui' instead of 'lib'
+packages/my-package/
+├── src/
+│   ├── ui/              # Wrong: should be 'lib'
+│   │   └── Button/
+│   └── index.ts
+```
+
+(Don't) Mix exportable and non-exportable code at the same level:
+```
+// Bad: Mixing concerns
+packages/my-package/
+├── src/
+│   ├── Button/          # Component mixed with...
+│   ├── storybook/       # ...non-exportable storybook config
+│   └── test-utils/      # ...and test utilities
+```
+
+(Don't) Create deeply nested lib-like structures; keep lib at the top level of src:
+```
+// Bad: Nested lib folders
+packages/my-package/
+├── src/
+│   ├── features/
+│   │   └── lib/         # Wrong: lib should be at src level
+```
+
+---
+
+## code/types/file
+
+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`.
+
+### Do
+
+(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";
+```
+
+### Don't
+
+(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}`;
+```
+
+---