@canonical/code-standards 0.1.0 → 0.1.2

package/data/packaging.ttl

@@ -15,18 +15,20 @@ 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
+    cs:do [
+        cs:description "Recognise an application package by its `package.json` signals — `bin` field, `private: true`, no `main`/`exports`" ;
+        cs:language "json" ;
+        cs:code """
 {
   "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:
-```
+    """
+    ] ;
+    cs:do [
+        cs:description "Organize code around execution domains. Each domain folder gets its own barrel (`index.ts`) that exposes the domain's internal API to sibling domains" ;
+        cs:code """
 packages/my-cli/
 ├── src/
 │   ├── commands/              # CLI command handlers
@@ -42,17 +44,20 @@ packages/my-cli/
 │   │   └── 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Import from sibling domains through their barrel, not from individual files" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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/`:
-```
+    """
+    ] ;
+    cs:do [
+        cs:description "Use domain-appropriate folder names that reflect what the code does — `commands/`, `tools/`, `routes/`, `operations/`, `handlers/`" ;
+        cs:code """
 packages/my-mcp/
 ├── src/
 │   ├── tools/                 # MCP tool handlers
@@ -64,10 +69,11 @@ packages/my-mcp/
 │   │   └── 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:
-```
+    """
+    ] ;
+    cs:do [
+        cs:description "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" ;
+        cs:code """
 packages/my-mcp/
 ├── src/
 │   ├── lib/                   # Only the reusable exported surface
@@ -82,11 +88,11 @@ packages/my-mcp/
 │   │   └── 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Apply library structure (`src/lib/`, barrel re-exports) to application packages" ;
+        cs:code """
 // Bad: CLI tool forced into library layout
 packages/my-cli/
 ├── src/
@@ -94,10 +100,11 @@ packages/my-cli/
 │   │   ├── 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create a `src/lib/` folder for internal shared operations. Use domain-appropriate names instead" ;
+        cs:code """
 // Bad: "lib" implies external consumption
 packages/my-cli/
 ├── src/
@@ -109,10 +116,12 @@ 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Import directly from files inside a sibling domain — always go through the domain barrel" ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: reaching into a sibling domain's internals
 import { resolveConfig } from "../operations/resolveConfig.js";
 import { formatOutput } from "../utils/formatOutput.js";
@@ -120,10 +129,11 @@ 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Omit barrels from domain folders" ;
+        cs:code """
 // Bad: no barrels — every consumer imports individual files
 packages/my-cli/
 ├── src/
@@ -133,36 +143,39 @@ packages/my-cli/
 │   ├── 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Default to library structure just because the package lives in a monorepo" ;
+        cs:code """
 // 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
+    cs:do [
+        cs:description "Recognise a library package by its `package.json` signals — `main`/`exports` field, publishable, no `bin`" ;
+        cs:language "json" ;
+        cs:code """
 {
   "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:
-```
+    """
+    ] ;
+    cs:do [
+        cs:description "Place all reusable/exportable code in `src/lib/`, with a barrel in each domain folder" ;
+        cs:code """
 packages/my-package/
 ├── src/
 │   ├── lib/
@@ -180,54 +193,61 @@ packages/my-package/
 │   ├── 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Re-export from the lib folder in the package entry point" ;
+        cs:language "typescript" ;
+        cs:code """
 // src/index.ts
 export * from "./lib/index.js";
-```
-
-(Do) Use the lib barrel to compose the package's public API from domain barrels:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Use the lib barrel to compose the package's public API from domain barrels" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use alternative folder names like `ui`, `components`, or `utils` for exportable code at the package level" ;
+        cs:code """
 // 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix exportable and non-exportable code at the same level" ;
+        cs:code """
 // 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Create deeply nested lib-like structures; keep lib at the top level of src" ;
+        cs:code """
 // 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Omit barrels from domain folders within lib" ;
+        cs:code """
 // Bad: no barrels — consumers must know individual file paths
 packages/my-package/
 ├── src/
@@ -238,23 +258,26 @@ packages/my-package/
 │   │   ├── 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
+    cs:do [
+        cs:description "Use a single default export for files implementing a single component or function" ;
+        cs:language "typescript" ;
+        cs:code """
 // ComponentName.tsx
 export default ComponentName;
-```
-
-(Do) Name atomic function files after the function they export:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Name atomic function files after the function they export" ;
+        cs:language "typescript" ;
+        cs:code """
 // assignElement.ts
 export default function assignElement(target: Element, source: Partial<Element>) {
   // ...
@@ -264,10 +287,12 @@ export default function assignElement(target: Element, source: Partial<Element>)
 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Use multiple named exports for files providing a public API or a collection of related items, and ensure all exports have the same type" ;
+        cs:language "typescript" ;
+        cs:code """
 // index.ts
 export { ComponentA, ComponentB };
 
@@ -279,17 +304,20 @@ export type TypeB = { ... };
 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix default and unrelated named exports in a way that confuses the file's purpose" ;
+        cs:language "typescript" ;
+        cs:code """
 export default ComponentName;
 export const helper = () => {};
-```
-
-(Don't) Name an atomic function file with a name that doesn't match its exported function:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Name an atomic function file with a name that doesn't match its exported function" ;
+        cs:language "typescript" ;
+        cs:code """
 // helpers.ts — wrong: generic name instead of function name
 export default function assignElement(target: Element, source: Partial<Element>) {
   // ...
@@ -299,104 +327,209 @@ export default function assignElement(target: Element, source: Partial<Element>)
 export default function formatCurrency(value: number) {
   // ...
 }
-```
-
-(Don't) Provide multiple unrelated exports from a file meant for a single domain:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Provide multiple unrelated exports from a file meant for a single domain" ;
+        cs:language "typescript" ;
+        cs:code """
 export default debounce;
 export const throttle = () => {};
 export const logger = () => {};
-```
-
-(Don't) Export objects of different types or shapes from the same file:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Export objects of different types or shapes from the same file" ;
+        cs:language "typescript" ;
+        cs:code """
 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
+    cs:do [
+        cs:description "Use a barrel at the package entry point to define the public API (library packages)" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Use a barrel at each domain folder to define the domain's API (application packages)" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Import internal implementation code within a domain from the owning file directly" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Import cross-domain code through the sibling domain's barrel" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:do [
+        cs:description "Keep compatibility barrels thin and documented as public facades" ;
+        cs:language "typescript" ;
+        cs:code """
 /** 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Route internal same-domain code through its own barrel" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Import cross-domain code by reaching into individual files" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Hide domain ownership behind convenience barrels" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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:
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Omit the barrel from a domain folder" ;
+        cs:code """
 // Bad: no index.ts — consumers must know internal file names
 src/operations/
 ├── resolveConfig.ts
 └── runValidation.ts
-```
-""" .
+    """
+    ] .
+
+# Export Declaration Location
+cs:ExportDeclarationLocation a cs:CodeStandard ;
+    cs:name "packaging/export/declaration" ;
+    cs:hasCategory cs:PackagingCategory ;
+    cs:description "Exports must be declared on the definition itself (e.g. `export default function` or `export const`), not gathered at the end of the file. When a wrapper (HOC, decorator, middleware) is applied, declare the unwrapped binding with `const`, then export the wrapped result as default on a separate line." ;
+    cs:do [
+        cs:description "Declare the export directly on the function or class definition" ;
+        cs:language "typescript" ;
+        cs:code """
+// formatCurrency.ts
+export default function formatCurrency(value: number): string {
+  return `$${value.toFixed(2)}`;
+}
+    """
+    ] ;
+    cs:do [
+        cs:description "Declare the export directly on a named constant" ;
+        cs:language "typescript" ;
+        cs:code """
+// MAX_RETRIES.ts
+export const MAX_RETRIES = 3;
+    """
+    ] ;
+    cs:do [
+        cs:description "When a wrapper is involved, declare the raw binding with `const`, then export the wrapped result as default" ;
+        cs:language "typescript" ;
+        cs:code """
+// UserProfile.tsx
+const UserProfile = ({ user }: UserProfileProps) => {
+  return <div>{user.name}</div>;
+};
+
+export default memo(UserProfile);
+    """
+    ] ;
+    cs:do [
+        cs:description "Apply the same pattern for higher-order functions and middleware" ;
+        cs:language "typescript" ;
+        cs:code """
+// connectDatabase.ts
+const connectDatabase = (config: DbConfig): Connection => {
+  return new Connection(config);
+};
+
+export default withRetry(connectDatabase);
+    """
+    ] ;
+    cs:dont [
+        cs:description "Define a symbol and then export it at the end of the file" ;
+        cs:language "typescript" ;
+        cs:code """
+// Bad: export is separated from definition
+function formatCurrency(value: number): string {
+  return `$${value.toFixed(2)}`;
+}
+
+export default formatCurrency;
+    """
+    ] ;
+    cs:dont [
+        cs:description "Gather multiple exports at the bottom of the file" ;
+        cs:language "typescript" ;
+        cs:code """
+// Bad: exports collected at the end
+const helperA = () => {};
+const helperB = () => {};
+
+export { helperA, helperB };
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use `export default` on the raw binding when a wrapper is needed" ;
+        cs:language "typescript" ;
+        cs:code """
+// Bad: exports the unwrapped version, then wraps elsewhere
+export default function UserProfile({ user }: UserProfileProps) {
+  return <div>{user.name}</div>;
+}
+
+// consumer.ts — has to wrap it themselves
+import UserProfile from "./UserProfile.js";
+const Memoized = memo(UserProfile);
+    """
+    ] .
 
 # 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
+    cs:do [
+        cs:description "Name files after the single function they export" ;
+        cs:language "typescript" ;
+        cs:code """
 // isAccepted.ts
 export const isAccepted = (status: string): boolean => {
   return status === "accepted";
@@ -406,10 +539,12 @@ export const isAccepted = (status: string): boolean => {
 export default function formatCurrency(value: number): string {
   return `$${value.toFixed(2)}`;
 }
-```
-
-(Do) Name files after the single type or interface they export:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Name files after the single type or interface they export" ;
+        cs:language "typescript" ;
+        cs:code """
 // ConnectionConfig.ts
 export interface ConnectionConfig {
   host: string;
@@ -418,25 +553,30 @@ export interface ConnectionConfig {
 
 // UserRole.ts
 export type UserRole = "admin" | "editor" | "viewer";
-```
-
-(Do) Name files after the single class they export:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Name files after the single class they export" ;
+        cs:language "typescript" ;
+        cs:code """
 // EventEmitter.ts
 export class EventEmitter {
   // ...
 }
-```
-
-(Do) Name files after the single constant they export:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Name files after the single constant they export" ;
+        cs:language "typescript" ;
+        cs:code """
 // 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
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use generic names like `helpers.ts`, `utils.ts`, or `types.ts` for files with a single export" ;
+        cs:language "typescript" ;
+        cs:code """
 // helpers.ts — wrong: should be isAccepted.ts
 export const isAccepted = (status: string): boolean => {
   return status === "accepted";
@@ -446,10 +586,12 @@ export const isAccepted = (status: string): boolean => {
 export default function formatCurrency(value: number): string {
   return `$${value.toFixed(2)}`;
 }
-```
-
-(Don't) Use names that describe the domain instead of the export:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use names that describe the domain instead of the export" ;
+        cs:language "typescript" ;
+        cs:code """
 // validation.ts — wrong: should be isAccepted.ts
 export const isAccepted = (status: string): boolean => {
   return status === "accepted";
@@ -460,5 +602,121 @@ export interface ConnectionConfig {
   host: string;
   port: number;
 }
-```
-""" .
+    """
+    ] .
+
+# Intra-Package Cross-Domain Imports
+cs:IntraPackageCrossDomainImports a cs:CodeStandard ;
+    cs:name "packaging/import/cross-domain" ;
+    cs:hasCategory cs:PackagingCategory ;
+    cs:description """Intra-package cross-domain imports must use Node.js subpath imports (the `imports` field in `package.json`) with the `#` prefix convention. Each `#` alias points directly to the domain's barrel file — no wildcard splats, no path suffixes, no extension mapping. With `moduleResolution: "nodenext"` (or `"node16"`), bare specifiers like `error/index.js` are treated as package names, not path-relative imports. The `paths` compiler option is a manual alias table — brittle and verbose. Subpath imports are the official Node.js mechanism, work natively with Node, Bun, vitest, and tsc, and require no plugins. TypeScript resolves them when `resolvePackageJsonImports` is enabled (on by default with `moduleResolution` set to `node16`, `nodenext`, or `bundler`).""" ;
+    cs:do [
+        cs:description "Map each `#` alias directly to the domain barrel in `package.json` — no wildcards, no path suffixes" ;
+        cs:language "json" ;
+        cs:code """
+{
+  "imports": {
+    "#config": "./src/config/index.ts",
+    "#error": "./src/error/index.ts",
+    "#pipeline": "./src/pipeline/index.ts",
+    "#package-manager": "./src/package-manager/index.ts",
+    "#constants": "./src/constants.ts"
+  }
+}
+    """
+    ] ;
+    cs:do [
+        cs:description "Import cross-domain modules using the `#` alias — clean, no path suffixes" ;
+        cs:language "typescript" ;
+        cs:code """
+// src/pipeline/runPipeline.ts
+import { PragmaError } from "#error";
+import { resolveConfig } from "#config";
+    """
+    ] ;
+    cs:do [
+        cs:description """Use `moduleResolution: "nodenext"` (or `"node16"` / `"bundler"`) in `tsconfig.json` so TypeScript resolves subpath imports via `resolvePackageJsonImports` (enabled by default with these settings)""" ;
+        cs:language "json" ;
+        cs:code """
+{
+  "compilerOptions": {
+    "moduleResolution": "nodenext"
+  }
+}
+    """
+    ] ;
+    cs:do [
+        cs:description "Use conditional subpath imports when you need different resolutions for different environments" ;
+        cs:language "json" ;
+        cs:code """
+{
+  "imports": {
+    "#db": {
+      "development": "./src/db/mock.ts",
+      "default": "./src/db/real.ts"
+    }
+  }
+}
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use wildcard splats or path suffixes in `#` aliases — point directly to the barrel instead" ;
+        cs:language "json" ;
+        cs:code """
+// Bad: wildcard mapping forces consumers to know internal file structure
+{
+  "imports": {
+    "#config/*": "./src/config/*",
+    "#error/*": "./src/error/*"
+  }
+}
+
+// Bad: path suffix leaks barrel structure into every import site
+import { PragmaError } from "#error/index.js";
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use bare specifiers without the `#` prefix for intra-package imports — they resolve as package names under `nodenext`" ;
+        cs:language "typescript" ;
+        cs:code """
+// Bad: "error/index.js" resolves as the npm package "error", not ./src/error/
+import { PragmaError } from "error/index.js";
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use `paths` in `tsconfig.json` as a substitute for subpath imports — it's a manual alias table that doesn't participate in Node.js resolution" ;
+        cs:language "json" ;
+        cs:code """
+// Bad: brittle, verbose, requires a bundler or ts-patch to work at runtime
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@error/*": ["src/error/*"],
+      "@config/*": ["src/config/*"],
+      "@pipeline/*": ["src/pipeline/*"]
+    }
+  }
+}
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use deep relative paths to reach across domains — they break when folders move and obscure the dependency graph" ;
+        cs:language "typescript" ;
+        cs:code """
+// Bad: fragile, hard to refactor
+import { PragmaError } from "../../error/PragmaError.js";
+import { resolveConfig } from "../../../config/resolveConfig.js";
+    """
+    ] ;
+    cs:dont [
+        cs:description "Import specific files through the `#` alias — go through the barrel instead" ;
+        cs:language "typescript" ;
+        cs:code """
+// Bad: bypasses the barrel, couples to internal file structure
+import { readConfig } from "#config/readConfig.js";
+
+// Good: import through the barrel
+import { readConfig } from "#config";
+    """
+    ] .