@canonical/code-standards 0.1.0

package/data/packaging.ttl

@@ -0,0 +1,464 @@
+@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#> .
+
+# Packaging Category
+cs:PackagingCategory a cs:Category ;
+    rdfs:label "Packaging"@en ;
+    rdfs:comment "Standards for structuring TypeScript/JavaScript packages — archetype classification, folder layout, export shape, barrel files, and file naming"@en ;
+    cs:slug "packaging" .
+
+# Application Package Structure
+cs:ApplicationPackage a cs:CodeStandard ;
+    cs:name "packaging/application/structure" ;
+    cs:hasCategory cs:PackagingCategory ;
+    cs:description "Application packages (CLIs, servers, MCP tools, build scripts, workers) execute behavior through entry points. They are not imported as dependencies by other packages. Their internal code must be organized around execution domains (commands, routes, tools, operations) rather than library conventions like `src/lib/` or barrel re-exports. Each domain folder must have its own barrel file (`index.ts`) that defines the domain's internal API — sibling domains import through the barrel, never from individual files." ;
+    cs:dos """
+(Do) Recognise an application package by its `package.json` signals — `bin` field, `private: true`, no `main`/`exports`:
+```json
+{
+  "name": "@scope/my-cli",
+  "private": true,
+  "bin": { "my-cli": "./dist/index.js" }
+}
+```
+
+(Do) Organize code around execution domains. Each domain folder gets its own barrel (`index.ts`) that exposes the domain's internal API to sibling domains:
+```
+packages/my-cli/
+├── src/
+│   ├── commands/              # CLI command handlers
+│   │   ├── build.ts
+│   │   ├── deploy.ts
+│   │   └── index.ts           # Barrel: exports all commands
+│   ├── operations/            # Shared internal logic across commands
+│   │   ├── resolveConfig.ts
+│   │   ├── runValidation.ts
+│   │   └── index.ts           # Barrel: exports shared operations
+│   ├── utils/                 # Internal helpers
+│   │   ├── formatOutput.ts
+│   │   └── index.ts           # Barrel: exports utilities
+│   └── index.ts               # Entry point (bootstraps CLI)
+└── package.json
+```
+
+(Do) Import from sibling domains through their barrel, not from individual files:
+```typescript
+// src/commands/deploy.ts
+import { resolveConfig, runValidation } from "../operations/index.js";
+import { formatOutput } from "../utils/index.js";
+```
+
+(Do) Use domain-appropriate folder names that reflect what the code does — `commands/`, `tools/`, `routes/`, `operations/`, `handlers/`:
+```
+packages/my-mcp/
+├── src/
+│   ├── tools/                 # MCP tool handlers
+│   │   ├── query.ts
+│   │   ├── mutate.ts
+│   │   └── index.ts           # Barrel: exports tool handlers
+│   ├── operations/            # Shared internal logic
+│   │   ├── executeQuery.ts
+│   │   └── index.ts           # Barrel: exports shared operations
+│   └── index.ts               # MCP server entry point
+└── package.json
+```
+
+(Do) For **hybrid** packages (primarily application but exporting a small reusable surface), isolate the exported surface in `src/lib/` following library rules while keeping the rest as application structure:
+```
+packages/my-mcp/
+├── src/
+│   ├── lib/                   # Only the reusable exported surface
+│   │   ├── types.ts
+│   │   └── index.ts           # Barrel: public API for external consumers
+│   ├── tools/                 # MCP tool handlers (not exported)
+│   │   ├── query.ts
+│   │   ├── mutate.ts
+│   │   └── index.ts           # Barrel: exports tool handlers
+│   ├── operations/            # Shared internal logic
+│   │   ├── executeQuery.ts
+│   │   └── index.ts           # Barrel: exports shared operations
+│   └── index.ts               # MCP server entry point
+└── package.json
+```
+""" ;
+    cs:donts """
+(Don't) Apply library structure (`src/lib/`, barrel re-exports) to application packages:
+```
+// Bad: CLI tool forced into library layout
+packages/my-cli/
+├── src/
+│   ├── lib/               # Wrong: this is a CLI, not a library
+│   │   ├── commands/
+│   │   └── index.ts       # Barrel re-export — nobody imports this
+│   └── index.ts
+```
+
+(Don't) Create a `src/lib/` folder for internal shared operations. Use domain-appropriate names instead:
+```
+// Bad: "lib" implies external consumption
+packages/my-cli/
+├── src/
+│   ├── lib/
+│   │   └── resolveConfig.ts   # Only used internally
+
+// Good: "operations" or "shared" makes intent clear
+packages/my-cli/
+├── src/
+│   ├── operations/
+│   │   └── resolveConfig.ts   # Internal shared logic
+```
+
+(Don't) Import directly from files inside a sibling domain — always go through the domain barrel:
+```typescript
+// Bad: reaching into a sibling domain's internals
+import { resolveConfig } from "../operations/resolveConfig.js";
+import { formatOutput } from "../utils/formatOutput.js";
+
+// Good: import through the domain barrel
+import { resolveConfig } from "../operations/index.js";
+import { formatOutput } from "../utils/index.js";
+```
+
+(Don't) Omit barrels from domain folders:
+```
+// Bad: no barrels — every consumer imports individual files
+packages/my-cli/
+├── src/
+│   ├── commands/
+│   │   ├── build.ts
+│   │   └── deploy.ts       # No index.ts — siblings must know file names
+│   ├── operations/
+│   │   ├── resolveConfig.ts
+│   │   └── runValidation.ts # No index.ts — fragile cross-domain imports
+```
+
+(Don't) Default to library structure just because the package lives in a monorepo:
+```
+// Bad: reflexively adding lib/ to a build script package
+packages/build-tools/
+├── src/
+│   ├── lib/               # This is a build script, not a library
+│   │   └── runBuild.ts
+│   └── index.ts
+```
+""" .
+
+# Library Package Structure
+cs:LibraryPackage a cs:CodeStandard ;
+    cs:name "packaging/library/structure" ;
+    cs:hasCategory cs:PackagingCategory ;
+    cs:description "Library packages export reusable code (components, utilities, hooks, types) for consumption by other packages. They must organize their exportable code in a `src/lib/` folder and re-export through a root barrel. This convention ensures consistency across the monorepo and clearly separates public API code from non-exported concerns like storybook configuration or test utilities. Each domain folder within `lib/` must have its own barrel (`index.ts`)." ;
+    cs:dos """
+(Do) Recognise a library package by its `package.json` signals — `main`/`exports` field, publishable, no `bin`:
+```json
+{
+  "name": "@scope/design-system",
+  "main": "./dist/index.js",
+  "exports": { ".": "./dist/index.js" }
+}
+```
+
+(Do) Place all reusable/exportable code in `src/lib/`, with a barrel in each domain folder:
+```
+packages/my-package/
+├── src/
+│   ├── lib/
+│   │   ├── Button/
+│   │   │   ├── Button.tsx
+│   │   │   ├── Button.tests.tsx
+│   │   │   ├── types.ts
+│   │   │   └── index.ts       # Barrel: exports Button public API
+│   │   ├── hooks/
+│   │   │   ├── useToggle.ts
+│   │   │   └── index.ts       # Barrel: exports hooks
+│   │   ├── types/
+│   │   │   └── index.ts       # Barrel: exports shared types
+│   │   └── index.ts           # Barrel: lib public API
+│   ├── 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 barrel to compose the package's public API from domain barrels:
+```typescript
+// src/lib/index.ts
+export * from "./Button/index.js";
+export * from "./hooks/index.js";
+export type * from "./types/index.js";
+```
+""" ;
+    cs:donts """
+(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
+```
+
+(Don't) Omit barrels from domain folders within lib:
+```
+// Bad: no barrels — consumers must know individual file paths
+packages/my-package/
+├── src/
+│   ├── lib/
+│   │   ├── Button/
+│   │   │   ├── Button.tsx
+│   │   │   └── types.ts    # No index.ts — fragile imports
+│   │   ├── hooks/
+│   │   │   └── useToggle.ts # No index.ts
+│   │   └── index.ts
+```
+""" .
+
+# Export Shape Standard
+cs:ExportShape a cs:CodeStandard ;
+    cs:name "packaging/export/shape" ;
+    cs:hasCategory cs:PackagingCategory ;
+    cs:description "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." ;
+    cs:dos """
+(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) => {};
+```
+""" ;
+    cs:donts """
+(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 };
+```
+""" .
+
+# Barrel File Standard
+cs:BarrelPublicApi a cs:CodeStandard ;
+    cs:name "packaging/export/barrel" ;
+    cs:hasCategory cs:PackagingCategory ;
+    cs:description "Every domain folder must have a barrel file (`index.ts`) that defines its API surface. In library packages, barrels define the public API for external consumers. In application packages, barrels define the internal API between sibling domains. Within a domain, implementation files import from siblings directly; cross-domain imports always go through the barrel." ;
+    cs:dos """
+(Do) Use a barrel at the package entry point to define the public API (library packages):
+```typescript
+// src/index.ts
+export { Button } from "./components/Button.js";
+export type { ButtonProps } from "./components/Button.types.js";
+```
+
+(Do) Use a barrel at each domain folder to define the domain's API (application packages):
+```typescript
+// src/operations/index.ts
+export { resolveConfig } from "./resolveConfig.js";
+export { runValidation } from "./runValidation.js";
+```
+
+(Do) Import internal implementation code within a domain from the owning file directly:
+```typescript
+// src/build/buildTheme.ts — same domain, import the file
+import { computeDeltas } from "./computeDeltas.js";
+import { recoverPrimitiveRef } from "./recoverPrimitiveRef.js";
+```
+
+(Do) Import cross-domain code through the sibling domain's barrel:
+```typescript
+// src/commands/deploy.ts — different domain, import through barrel
+import { resolveConfig } from "../operations/index.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";
+```
+""" ;
+    cs:donts """
+(Don't) Route internal same-domain code through its own barrel:
+```typescript
+// Bad: internal implementation depends on its own barrel
+// src/build/applyTheme.ts
+import { computeDeltas, recoverPrimitiveRef } from "./index.js";
+```
+
+(Don't) Import cross-domain code by reaching into individual files:
+```typescript
+// Bad: bypassing the domain barrel
+import { resolveConfig } from "../operations/resolveConfig.js";
+
+// Good: through the barrel
+import { resolveConfig } from "../operations/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) Omit the barrel from a domain folder:
+```
+// Bad: no index.ts — consumers must know internal file names
+src/operations/
+├── resolveConfig.ts
+└── runValidation.ts
+```
+""" .
+
+# Single Export File Naming Standard
+cs:SingleExportFileNaming a cs:CodeStandard ;
+    cs:name "packaging/naming/single-export-file" ;
+    cs:hasCategory cs:PackagingCategory ;
+    cs:description "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)." ;
+    cs:dos """
+(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;
+```
+""" ;
+    cs:donts """
+(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;
+}
+```
+""" .