@canonical/code-standards 0.1.0 → 0.1.1

package/data/code.ttl

@@ -15,16 +15,19 @@ 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
+    cs:do [
+        cs:description "Create pure functions that rely only on their inputs to compute the output." ;
+        cs:language "typescript" ;
+        cs:code """
 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Annotate and document impure functions that perform I/O or modify external state, explaining why impurity is necessary using @note." ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Writes data to the file system.
  * @note - This function is impure - it modifies the file system.
@@ -32,41 +35,47 @@ const calculatePrice = (basePrice: number, taxRate: number): number => {
 function writeOutputToFile(data: string, path: string) {
   fs.writeFileSync(path, data);
 }
-```
-""" ;
-    cs:donts """
-(Don't) Create impure functions without annotation or documentation.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create impure functions without annotation or documentation." ;
+        cs:language "typescript" ;
+        cs:code """
 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Hide side effects in functions that appear pure." ;
+        cs:language "typescript" ;
+        cs:code """
 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
+    cs:do [
+        cs:description "Define functions with a single, clear responsibility." ;
+        cs:language "typescript" ;
+        cs:code """
 const validateEmail = (email: string): boolean => {
   return /^[^@]+@[^@]+\\.[^@]+$/.test(email);
 };
-```
-
-(Do) Compose single-purpose functions to build complex logic.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Compose single-purpose functions to build complex logic." ;
+        cs:language "typescript" ;
+        cs:code """
 const validatePassword = (password: string): boolean => {
   return password.length >= 8;
 };
@@ -74,28 +83,30 @@ const validatePassword = (password: string): boolean => {
 const validateForm = (email: string, password:string): boolean => {
   return validateEmail(email) && validatePassword(password);
 };
-```
-""" ;
-    cs:donts """
-(Don't) Mix multiple responsibilities in a single function.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix multiple responsibilities in a single function." ;
+        cs:language "typescript" ;
+        cs:code """
 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
+    cs:do [
+        cs:description "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." ;
+        cs:language "typescript" ;
+        cs:code """
 // utils/math.ts
 export function calculateSum(a: number, b: number): number {
   return a + b;
@@ -105,22 +116,12 @@ 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,
-  };
-};
-
-""" ;
-    cs:donts """
-(Don't) Place functions far from where they are used, or in a generic location if only used in one place.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Place functions far from where they are used, or in a generic location if only used in one place." ;
+        cs:language "typescript" ;
+        cs:code """
 // utils/validators.ts
 export const validateUser = (user: User) => { ... }; // Only used in one component
 
@@ -128,19 +129,18 @@ 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 = () => {};
-""" .
+    """
+    ] .
 
 # 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
+    cs:do [
+        cs:description "Mark an experimental interface with a clear @experimental JSDoc tag and description." ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Configuration for the data processing pipeline.
  * @experimental The streaming API is experimental and may change
@@ -149,10 +149,12 @@ cs:APIStability a cs:CodeStandard ;
 interface PipelineConfig {
   // ...
 }
-```
-
-(Do) Add an @experimental tag to a specific property with context about its experimental status.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Add an @experimental tag to a specific property with context about its experimental status." ;
+        cs:language "typescript" ;
+        cs:code """
 interface PipelineConfig {
   /**
    * @experimental The custom transformers API is in beta, and the interface
@@ -160,10 +162,12 @@ interface PipelineConfig {
    */
   transformers?: DataTransformer[];
 }
-```
-
-(Do) Describe the experimental status and any future plans for the API.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Describe the experimental status and any future plans for the API." ;
+        cs:language "typescript" ;
+        cs:code """
 interface CacheConfig {
   /**
    * @experimental The distributed cache API is experimental and will be
@@ -171,46 +175,52 @@ interface CacheConfig {
    */
   distributed?: boolean;
 }
-```
-""" ;
-    cs:donts """
-(Don't) Use the @experimental tag without an explanation.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use the @experimental tag without an explanation." ;
+        cs:language "typescript" ;
+        cs:code """
 interface ProcessorConfig {
   /** @experimental */ // Bad: No context provided.
   streaming?: boolean;
 }
-```
-
-(Don't) Use the @experimental tag without describing what is experimental.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use the @experimental tag without describing what is experimental." ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * @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
+    cs:do [
+        cs:description "Start function names with an action verb" ;
+        cs:language "typescript" ;
+        cs:code """
 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Use descriptive verb prefixes that convey the operation" ;
+        cs:language "typescript" ;
+        cs:code """
 // Retrieval: get, fetch, find, resolve, load, read
 const getUser = (id: string): User => { /* ... */ };
 const fetchOrders = (): Promise<Order[]> => { /* ... */ };
@@ -232,11 +242,12 @@ 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Name functions as nouns or noun phrases — they read like values, not actions" ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: reads like a variable, not a function
 const pathToModule = (name: string): string => { /* ... */ };
 // Good: findPathToModule
@@ -246,35 +257,39 @@ const dataForUser = (userId: string): Promise<User> => { /* ... */ };
 
 const userPermissions = (user: User): Permission[] => { /* ... */ };
 // Good: getPermissions or listPermissions
-```
-
-(Don't) Use vague or non-descriptive verbs that don't convey meaning:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use vague or non-descriptive verbs that don't convey meaning" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    cs:do [
+        cs:description "Create a `constants.ts` file with named exports at the domain level" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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:
-```
+    """
+    ] ;
+    cs:do [
+        cs:description "Colocate `constants.ts` inside the domain folder it belongs to" ;
+        cs:code """
 features/
 ├── pricing/
 │   ├── constants.ts          # Domain constants live here
@@ -284,24 +299,30 @@ features/
 │   ├── constants.ts          # Auth-specific constants
 │   ├── validateToken.ts
 │   └── index.ts
-```
-
-(Do) Import constants directly from the owning domain's `constants.ts`:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Import constants directly from the owning domain's `constants.ts`" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Keep all exports in `constants.ts` as named exports with the same shape (plain values)" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Keep single-use constants inline in the file that uses them" ;
+        cs:language "typescript" ;
+        cs:code """
 // features/pricing/applyDiscount.ts
 const MAX_DISCOUNT_PERCENT = 50;
 
@@ -309,53 +330,61 @@ 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use a default export in a constants file" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Scatter constants across unrelated files instead of collecting them in `constants.ts`" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Place constants far from the domain that owns them" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix constants with functions, types, or other non-constant exports" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    cs:do [
+        cs:description "Create a `types.ts` file with named exports for types shared across the domain" ;
+        cs:language "typescript" ;
+        cs:code """
 // features/pricing/types.ts
 export type Currency = "USD" | "EUR" | "GBP";
 export interface PriceBreakdown {
@@ -364,10 +393,11 @@ export interface PriceBreakdown {
   total: number;
 }
 export type DiscountStrategy = "percentage" | "fixed";
-```
-
-(Do) Colocate `types.ts` inside the domain folder it belongs to:
-```
+    """
+    ] ;
+    cs:do [
+        cs:description "Colocate `types.ts` inside the domain folder it belongs to" ;
+        cs:code """
 features/
 ├── pricing/
 │   ├── types.ts              # Shared domain types live here
@@ -378,10 +408,12 @@ features/
 │   ├── types.ts              # Auth-specific types
 │   ├── validateToken.ts
 │   └── index.ts
-```
-
-(Do) Keep single-use types inline in the file that uses them:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Keep single-use types inline in the file that uses them" ;
+        cs:language "typescript" ;
+        cs:code """
 // features/pricing/applyDiscount.ts
 type DiscountResult = { discounted: number; savings: number };
 
@@ -389,49 +421,58 @@ export default function applyDiscount(price: number, rate: number): DiscountResu
   const savings = price * rate;
   return { discounted: price - savings, savings };
 }
-```
-
-(Do) Import shared types from the owning domain's `types.ts`:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Import shared types from the owning domain's `types.ts`" ;
+        cs:language "typescript" ;
+        cs:code """
 // features/pricing/calculatePrice.ts
 import type { Currency, PriceBreakdown } from "./types.js";
-```
-""" ;
-    cs:donts """
-(Don't) Use a default export in a types file:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use a default export in a types file" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Extract single-use types to `types.ts` when they are only used in one file" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Place types far from the domain that owns them" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix types with functions, constants, or other non-type exports" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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}`;
-```
-""" .
+    """
+    ] .