@canonical/code-standards 0.1.0 → 0.1.2

package/docs/code.md

@@ -8,7 +8,7 @@ Experimental APIs must be marked with the @experimental JSDoc tag in type defini
 
 ### Do
 
-(Do) Mark an experimental interface with a clear @experimental JSDoc tag and description.
+Mark an experimental interface with a clear @experimental JSDoc tag and description.
 ```typescript
 /**
  * Configuration for the data processing pipeline.
@@ -20,7 +20,7 @@ interface PipelineConfig {
 }
 ```
 
-(Do) Add an @experimental tag to a specific property with context about its experimental status.
+Add an @experimental tag to a specific property with context about its experimental status.
 ```typescript
 interface PipelineConfig {
   /**
@@ -31,7 +31,7 @@ interface PipelineConfig {
 }
 ```
 
-(Do) Describe the experimental status and any future plans for the API.
+Describe the experimental status and any future plans for the API.
 ```typescript
 interface CacheConfig {
   /**
@@ -44,7 +44,7 @@ interface CacheConfig {
 
 ### Don't
 
-(Don't) Use the @experimental tag without an explanation.
+Use the @experimental tag without an explanation.
 ```typescript
 interface ProcessorConfig {
   /** @experimental */ // Bad: No context provided.
@@ -52,7 +52,7 @@ interface ProcessorConfig {
 }
 ```
 
-(Don't) Use the @experimental tag without describing what is experimental.
+Use the @experimental tag without describing what is experimental.
 ```typescript
 /**
  * @experimental // Bad: No description of what is experimental.
@@ -70,7 +70,7 @@ Domain constants must be collected in a `constants.ts` file using named exports
 
 ### Do
 
-(Do) Create a `constants.ts` file with named exports at the domain level:
+Create a `constants.ts` file with named exports at the domain level
 ```typescript
 // features/pricing/constants.ts
 export const DEFAULT_CURRENCY = "USD";
@@ -78,7 +78,7 @@ export const TAX_RATE = 0.21;
 export const MAX_DISCOUNT_PERCENT = 50;
 ```
 
-(Do) Colocate `constants.ts` inside the domain folder it belongs to:
+Colocate `constants.ts` inside the domain folder it belongs to
 ```
 features/
 ├── pricing/
@@ -91,13 +91,13 @@ features/
 │   └── index.ts
 ```
 
-(Do) Import constants directly from the owning domain's `constants.ts`:
+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):
+Keep all exports in `constants.ts` as named exports with the same shape (plain values)
 ```typescript
 // constants.ts
 export const RECONNECT_INTERVAL_MS = 5000;
@@ -105,7 +105,7 @@ export const MAX_RETRIES = 3;
 export const DEFAULT_TIMEOUT_MS = 30_000;
 ```
 
-(Do) Keep single-use constants inline in the file that uses them:
+Keep single-use constants inline in the file that uses them
 ```typescript
 // features/pricing/applyDiscount.ts
 const MAX_DISCOUNT_PERCENT = 50;
@@ -118,7 +118,7 @@ export default function applyDiscount(price: number, rate: number): number {
 
 ### Don't
 
-(Don't) Use a default export in a constants file:
+Use a default export in a constants file
 ```typescript
 // Bad: default export forces consumers to name the import
 export default {
@@ -127,7 +127,7 @@ export default {
 };
 ```
 
-(Don't) Scatter constants across unrelated files instead of collecting them in `constants.ts`:
+Scatter constants across unrelated files instead of collecting them in `constants.ts`
 ```typescript
 // Bad: constants buried inside implementation files
 // calculatePrice.ts
@@ -136,7 +136,7 @@ const calculatePrice = (base: number) => base * (1 + TAX_RATE);
 export default calculatePrice;
 ```
 
-(Don't) Place constants far from the domain that owns them:
+Place constants far from the domain that owns them
 ```typescript
 // Bad: pricing constants in a top-level shared file
 // src/constants.ts
@@ -145,7 +145,7 @@ 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:
+Mix constants with functions, types, or other non-constant exports
 ```typescript
 // Bad: constants.ts should only contain constant values
 export const MAX_RETRIES = 3;
@@ -155,149 +155,20 @@ 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.
+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.
+Compose single-purpose functions to build complex logic.
 ```typescript
 const validatePassword = (password: string): boolean => {
   return password.length >= 8;
@@ -310,7 +181,7 @@ const validateForm = (email: string, password:string): boolean => {
 
 ### Don't
 
-(Don't) Mix multiple responsibilities in a single function.
+Mix multiple responsibilities in a single function.
 ```typescript
 const processUserData = (user: any) => {
   // Validates user data
@@ -328,7 +199,7 @@ Functions must be defined as close to their broadest point of use as possible. S
 
 ### 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.
+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 {
@@ -339,21 +210,11 @@ export function calculateSum(a: number, b: number): number {
 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.
+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
@@ -362,9 +223,7 @@ export const validateUser = (user: User) => { ... }; // Only used in one compone
 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 = () => {};
+```
 
 ---
 
@@ -374,14 +233,14 @@ Functions should be pure where possible. A pure function returns the same output
 
 ### Do
 
-(Do) Create pure functions that rely only on their inputs to compute the output.
+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.
+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.
@@ -394,7 +253,7 @@ function writeOutputToFile(data: string, path: string) {
 
 ### Don't
 
-(Don't) Create impure functions without annotation or documentation.
+Create impure functions without annotation or documentation.
 ```typescript
 let total = 0;
 const addToTotal = (value: number) => {
@@ -402,7 +261,7 @@ const addToTotal = (value: number) => {
 };
 ```
 
-(Don't) Hide side effects in functions that appear pure.
+Hide side effects in functions that appear pure.
 ```typescript
 function getConfig() {
   // Reads from disk without annotation
@@ -418,7 +277,7 @@ All function and method names must start with a verb that describes the action t
 
 ### Do
 
-(Do) Start function names with an action verb:
+Start function names with an action verb
 ```typescript
 const findPathToModule = (name: string): string => { /* ... */ };
 const fetchDataForUser = (userId: string): Promise<User> => { /* ... */ };
@@ -428,7 +287,7 @@ const isValidEmail = (email: string): boolean => { /* ... */ };
 const hasPermission = (user: User, action: string): boolean => { /* ... */ };
 ```
 
-(Do) Use descriptive verb prefixes that convey the operation:
+Use descriptive verb prefixes that convey the operation
 ```typescript
 // Retrieval: get, fetch, find, resolve, load, read
 const getUser = (id: string): User => { /* ... */ };
@@ -455,7 +314,7 @@ const buildQuery = (params: Params): string => { /* ... */ };
 
 ### Don't
 
-(Don't) Name functions as nouns or noun phrases — they read like values, not actions:
+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 => { /* ... */ };
@@ -468,7 +327,7 @@ const userPermissions = (user: User): Permission[] => { /* ... */ };
 // Good: getPermissions or listPermissions
 ```
 
-(Don't) Use vague or non-descriptive verbs that don't convey meaning:
+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) => { /* ... */ };
@@ -480,162 +339,13 @@ const processUser = (user: User) => { /* ... */ };
 
 ---
 
-## 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:
+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";
@@ -647,7 +357,7 @@ export interface PriceBreakdown {
 export type DiscountStrategy = "percentage" | "fixed";
 ```
 
-(Do) Colocate `types.ts` inside the domain folder it belongs to:
+Colocate `types.ts` inside the domain folder it belongs to
 ```
 features/
 ├── pricing/
@@ -661,7 +371,7 @@ features/
 │   └── index.ts
 ```
 
-(Do) Keep single-use types inline in the file that uses them:
+Keep single-use types inline in the file that uses them
 ```typescript
 // features/pricing/applyDiscount.ts
 type DiscountResult = { discounted: number; savings: number };
@@ -672,7 +382,7 @@ export default function applyDiscount(price: number, rate: number): DiscountResu
 }
 ```
 
-(Do) Import shared types from the owning domain's `types.ts`:
+Import shared types from the owning domain's `types.ts`
 ```typescript
 // features/pricing/calculatePrice.ts
 import type { Currency, PriceBreakdown } from "./types.js";
@@ -680,7 +390,7 @@ import type { Currency, PriceBreakdown } from "./types.js";
 
 ### Don't
 
-(Don't) Use a default export in a types file:
+Use a default export in a types file
 ```typescript
 // Bad: default export for a collection of types
 export default interface PriceBreakdown {
@@ -690,7 +400,7 @@ export default interface PriceBreakdown {
 }
 ```
 
-(Don't) Extract single-use types to `types.ts` when they are only used in one file:
+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
@@ -700,7 +410,7 @@ export type DiscountResult = { discounted: number; savings: number };
 import type { DiscountResult } from "./types.js"; // Unnecessary indirection
 ```
 
-(Don't) Place types far from the domain that owns them:
+Place types far from the domain that owns them
 ```typescript
 // Bad: all types dumped in a top-level shared file
 // src/types.ts
@@ -709,7 +419,7 @@ 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:
+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";