@canonical/code-standards 0.1.0 → 0.1.1

package/docs/storybook.md

@@ -8,9 +8,8 @@ Component documentation must primarily come from TSDoc comments on the component
 
 ### Do
 
-(Do) Use TSDoc comments for primary documentation.
+Use TSDoc comments for primary documentation.
 ```typescript
-
 // ContextualMenu/types.ts
 export interface ContextualMenuProps extends HTMLAttributes<HTMLDivElement> {
   /** The element that triggers the contextual menu */
@@ -34,7 +33,7 @@ const ContextualMenu = ({
 
 ### Don't
 
-(Don't) Add documentation in Storybook parameters when TSDoc is sufficient.
+Add documentation in Storybook parameters when TSDoc is sufficient.
 ```typescript
 export const Default: Story = {
   parameters: {
@@ -55,9 +54,8 @@ Decorators must be used to wrap stories in common context providers or layout el
 
 ### Do
 
-(Do) Use decorators for static context or layout wrapping.
+Use decorators for static context or layout wrapping.
 ```typescript
-
 // storybook/decorators.tsx
 
 export const theme = (Story: StoryFn<typeof Component>) => (
@@ -92,7 +90,7 @@ export default meta;
 
 ### Don't
 
-(Don't) Use function-based stories for static wrapping that could be done with decorators.
+Use function-based stories for static wrapping that could be done with decorators.
 ```typescript
 // Bad: Using function-based story for static wrapping
 export const WithTheme = (args: ComponentProps) => (
@@ -110,7 +108,7 @@ Story documentation must focus on usage patterns and variations, not implementat
 
 ### Do
 
-(Do) Document usage patterns and variations.
+Document usage patterns and variations.
 ```typescript
 export const WithCustomTrigger: Story = {
   args: {
@@ -128,7 +126,7 @@ export const WithCustomTrigger: Story = {
 
 ### Don't
 
-(Don't) Document implementation details or internal behavior.
+Document implementation details or internal behavior.
 ```typescript
 export const Default: Story = {
   parameters: {
@@ -152,7 +150,7 @@ Stories must use one of three formats, each serving specific needs:
 
 ### Do
 
-(Do) Use the format that matches your specific use case.
+Use the format that matches your specific use case.
 ```typescript
 // CSF3: For standard component variations through args
 type Story = StoryObj<typeof meta>;
@@ -191,7 +189,7 @@ Primary.args = { variant: "primary" };
 
 ### Don't
 
-(Don't) Use a format that doesn't match your use case.
+Use a format that doesn't match your use case.
 ```typescript
 // Bad: Using function format for simple args variation
 export const SimpleButton = () => (
@@ -219,7 +217,7 @@ Stories must import their component as 'Component' to maintain a consistent, gen
 
 ### Do
 
-(Do) Import the component generically as 'Component'.
+Import the component generically as 'Component'.
 ```typescript
 import Component from "./SkipLink.js";
 
@@ -237,7 +235,7 @@ export const Default: Story = {
 
 ### Don't
 
-(Don't) Import the component using its specific name.
+Import the component using its specific name.
 ```typescript
 import SkipLink from "./SkipLink.js";
 
@@ -255,7 +253,7 @@ Story names must be descriptive and follow a consistent pattern. Use PascalCase
 
 ### Do
 
-(Do) Use clear, descriptive names that indicate the variation.
+Use clear, descriptive names that indicate the variation.
 ```typescript
 export const WithCustomStyles: Story = {
   args: {
@@ -274,7 +272,7 @@ export const WithCustomStyles: Story = {
 
 ### Don't
 
-(Don't) Use technical or implementation-focused names.
+Use technical or implementation-focused names.
 ```typescript
 export const TestCase1: Story = {  // Bad: Non-descriptive name
   args: {
@@ -292,7 +290,7 @@ Stories must be organized into logical groups that demonstrate related features
 
 ### Do
 
-(Do) Group related features with clear, descriptive names.
+Group related features with clear, descriptive names.
 ```typescript
 // Basic usage
 export const Default: Story = {
@@ -321,7 +319,7 @@ export const CustomText: Story = {
 
 ### Don't
 
-(Don't) Use unclear names or mix unrelated features in a single story.
+Use unclear names or mix unrelated features in a single story.
 ```typescript
 // Bad: Unclear what this story demonstrates
 export const Variant1: Story = {
@@ -343,7 +341,7 @@ Stories that test component behavior must use the `play` function to simulate us
 
 ### Do
 
-(Do) Use play functions to test interactive behavior.
+Use play functions to test interactive behavior.
 ```typescript
 export const InteractionTest: Story = {
   args: {
@@ -360,7 +358,7 @@ export const InteractionTest: Story = {
 
 ### Don't
 
-(Don't) Test implementation details or internal state.
+Test implementation details or internal state.
 ```typescript
 export const InternalTest: Story = {
   play: async ({ component }) => {
@@ -378,7 +376,7 @@ Stories that exist solely for testing or visual coverage but don't represent val
 
 ### Do
 
-(Do) Hide test-only stories that don't represent valid usage.
+Hide test-only stories that don't represent valid usage.
 ```typescript
 export const FocusedState: Story = {
   args: {
@@ -395,7 +393,7 @@ export const FocusedState: Story = {
 
 ### Don't
 
-(Don't) Show implementation details or test states in documentation.
+Show implementation details or test states in documentation.
 ```typescript
 export const InternalTestState: Story = {
   args: {

package/docs/styling.md

@@ -8,7 +8,7 @@ Themes are collections of semantic tokens that provide consistent styling across
 
 ### Do
 
-(Do) Define a theme as a complete set of semantic tokens.
+Define a theme as a complete set of semantic tokens.
 ```
 {
   "theme": {
@@ -28,7 +28,7 @@ Themes are collections of semantic tokens that provide consistent styling across
 
 ### Don't
 
-(Don't) Mix implementation details into theme definitions.
+Mix implementation details into theme definitions.
 ```
 {
   "theme": {
@@ -48,7 +48,7 @@ Design tokens must be created for all design decisions in a component. See css/p
 
 ### Do
 
-(Do) Create component tokens that reference semantic tokens for design decisions.
+Create component tokens that reference semantic tokens for design decisions.
 ```
 {
   "button": {
@@ -62,7 +62,7 @@ Design tokens must be created for all design decisions in a component. See css/p
 
 ### Don't
 
-(Don't) Use raw values for design decisions.
+Use raw values for design decisions.
 ```
 {
   "button": {
@@ -85,7 +85,7 @@ Design tokens must be scoped according to their type:
 
 ### Do
 
-(Do) Define primitive tokens in global scope.
+Define primitive tokens in global scope.
 ```
 {
   "color": {
@@ -101,7 +101,7 @@ Design tokens must be scoped according to their type:
 
 ### Don't
 
-(Don't) Define primitive tokens in theme scope.
+Define primitive tokens in theme scope.
 ```
 {
   "theme": {
@@ -130,7 +130,7 @@ Design tokens follow a strict hierarchy:
 
 ### Do
 
-(Do) Define semantic tokens that map to primitive tokens.
+Define semantic tokens that map to primitive tokens.
 ```
 {
   "color": {
@@ -146,7 +146,7 @@ Design tokens follow a strict hierarchy:
 
 ### Don't
 
-(Don't) Skip the semantic layer by mapping component tokens directly to primitives.
+Skip the semantic layer by mapping component tokens directly to primitives.
 ```
 {
   "button": {

package/docs/tsdoc.md

@@ -8,7 +8,7 @@ File-level and export-level TSDoc serve fundamentally different purposes. Export
 
 ### Do
 
-(Do) In single-export files, document only at the export level — the API contract belongs on the symbol.
+In single-export files, document only at the export level — the API contract belongs on the symbol.
 ```typescript
 // resolveDefinition.ts — single export, no file-level block needed
 /** Resolve definition locations for a CSS custom property. */
@@ -17,7 +17,7 @@ export default function resolveDefinition(cssVar: string, graph: TokenGraph) {
 }
 ```
 
-(Do) In multi-export files, use a file-level block to explain the module's architectural purpose — why these exports are grouped.
+In multi-export files, use a file-level block to explain the module's architectural purpose — why these exports are grouped.
 ```typescript
 // types.ts — multiple exports, file-level explains cohesion
 /**
@@ -31,7 +31,7 @@ export interface UsageRuleContext { /* ... */ }
 export interface FileRuleContext { /* ... */ }
 ```
 
-(Do) Use export-level TSDoc to describe the API contract: what the symbol does, its parameters, return value, and any side effects.
+Use export-level TSDoc to describe the API contract: what the symbol does, its parameters, return value, and any side effects.
 ```typescript
 /**
  * Check: css/missing-fallback — var() without a fallback on an unregistered property.
@@ -46,7 +46,7 @@ export default function checkMissingFallback(ctx: UsageRuleContext, results: Dia
 
 ### Don't
 
-(Don't) Add a file-level block in a single-export file that restates what the export-level doc already says.
+Add a file-level block in a single-export file that restates what the export-level doc already says.
 ```typescript
 // Bad: file-level repeats the export's own description
 /** Resolve definitions for CSS custom property usages. */
@@ -55,7 +55,7 @@ export default function checkMissingFallback(ctx: UsageRuleContext, results: Dia
 export default function resolveDefinition() { /* ... */ }
 ```
 
-(Don't) Use file-level docs to describe *what* an export does — that belongs on the export itself.
+Use file-level docs to describe *what* an export does — that belongs on the export itself.
 ```typescript
 // Bad: file-level describes the function instead of the module's role
 /** Build a completion item for a CSS variable. */
@@ -63,7 +63,7 @@ export default function resolveDefinition() { /* ... */ }
 export default function buildCompletionItem(name: string) { /* ... */ }
 ```
 
-(Don't) Omit file-level docs on multi-export modules where the grouping rationale is non-obvious.
+Omit file-level docs on multi-export modules where the grouping rationale is non-obvious.
 ```typescript
 // Bad: reader cannot tell why these live together
 export function isCompletionRequest(req: WorkerRequest) { /* ... */ }
@@ -79,7 +79,7 @@ The `@module` TSDoc tag must appear only on barrel files such as `index.ts`. Ord
 
 ### Do
 
-(Do) Use `@module` on a barrel file that defines a package or folder-level API.
+Use `@module` on a barrel file that defines a package or folder-level API.
 ```typescript
 /**
  * Public protocol API.
@@ -88,7 +88,7 @@ The `@module` TSDoc tag must appear only on barrel files such as `index.ts`. Ord
 export { createRequest, matchResponse } from './index.js';
 ```
 
-(Do) Document an ordinary source file at the exported symbol instead of using `@module`.
+Document an ordinary source file at the exported symbol instead of using `@module`.
 ```typescript
 /** Build a completion item for a CSS variable. */
 export default function buildCompletionItem(name: string) {
@@ -98,7 +98,7 @@ export default function buildCompletionItem(name: string) {
 
 ### Don't
 
-(Don't) Add `@module` to a single-purpose implementation file.
+Add `@module` to a single-purpose implementation file.
 ```typescript
 /**
  * Build a completion item.
@@ -109,7 +109,7 @@ export default function buildCompletionItem(name: string) {
 }
 ```
 
-(Don't) Use file-level `@module` tags as a substitute for export documentation.
+Use file-level `@module` tags as a substitute for export documentation.
 ```typescript
 /** @module helpers/formatCurrency */
 export default function formatCurrency(value: number) {
@@ -125,7 +125,7 @@ TSDoc comments must be self-contained — a reader should fully understand the d
 
 ### Do
 
-(Do) Explain the concept inline so the reader needs nothing else:
+Explain the concept inline so the reader needs nothing else
 ```typescript
 /**
  * Encode a string as a percent-encoded URI component.
@@ -138,7 +138,7 @@ export function encodeComponent(value: string): string {
 }
 ```
 
-(Do) Add an external link as a supplementary reference after a self-sufficient explanation:
+Add an external link as a supplementary reference after a self-sufficient explanation
 ```typescript
 /**
  * Compare two semantic version strings.
@@ -154,7 +154,7 @@ export function compareVersions(a: string, b: string): number {
 }
 ```
 
-(Do) Reference a GitHub issue for additional context when the comment already explains the behaviour:
+Reference a GitHub issue for additional context when the comment already explains the behaviour
 ```typescript
 /**
  * Truncate session tokens to 64 characters before storage.
@@ -172,7 +172,7 @@ export function truncateToken(token: string): string {
 
 ### Don't
 
-(Don't) Point the reader to an external resource instead of explaining the behaviour:
+Point the reader to an external resource instead of explaining the behaviour
 ```typescript
 /**
  * Encode a URI component.
@@ -185,7 +185,7 @@ export function encodeComponent(value: string): string {
 }
 ```
 
-(Don't) Reference a wiki or internal doc as a substitute for inline explanation:
+Reference a wiki or internal doc as a substitute for inline explanation
 ```typescript
 /**
  * Truncate session tokens before storage.
@@ -198,7 +198,7 @@ export function truncateToken(token: string): string {
 }
 ```
 
-(Don't) Leave the reader unable to understand the symbol without following a link:
+Leave the reader unable to understand the symbol without following a link
 ```typescript
 /**
  * Compare two semantic version strings.

package/docs/turtle.md

@@ -14,21 +14,21 @@ This convention allows a single prefix to serve both definitions and data, with
 
 ### Do
 
-(Do) Use PascalCase for class names.
+Use PascalCase for class names.
 ```turtle
 ds:Component a owl:Class .
 ds:UIBlock a owl:Class .
 ds:ModifierFamily a owl:Class .
 ```
 
-(Do) Use camelCase for property names.
+Use camelCase for property names.
 ```turtle
 ds:name a owl:DatatypeProperty .
 ds:hasProperty a owl:ObjectProperty .
 ds:parentComponent a owl:ObjectProperty .
 ```
 
-(Do) Use lowercase (with dots or hyphens as separators) for instance identifiers.
+Use lowercase (with dots or hyphens as separators) for instance identifiers.
 ```turtle
 ds:global.component.button a ds:Component .
 ds:global.modifier_family.importance a ds:ModifierFamily .
@@ -36,19 +36,19 @@ ds:global.modifier_family.importance a ds:ModifierFamily .
 
 ### Don't
 
-(Don't) Use lowercase for class names.
+Use lowercase for class names.
 ```turtle
 # Bad: Class names should be PascalCase
 ds:component a owl:Class .
 ```
 
-(Don't) Use PascalCase for instance identifiers.
+Use PascalCase for instance identifiers.
 ```turtle
 # Bad: Instance names should be lowercase
 ds:GlobalComponentButton a ds:Component .
 ```
 
-(Don't) Use PascalCase or uppercase for property names.
+Use PascalCase or uppercase for property names.
 ```turtle
 # Bad: Property names should be camelCase
 ds:HasProperty a owl:ObjectProperty .
@@ -65,7 +65,7 @@ The namespace URI should be a base URI without a fragment or trailing path segme
 
 ### Do
 
-(Do) Use a single prefix for both definitions and data.
+Use a single prefix for both definitions and data.
 ```turtle
 # In both definitions/ and data/ files:
 @prefix ds: <https://ds.canonical.com/> .
@@ -81,7 +81,7 @@ ds:global.component.button a ds:Component ;
 
 ### Don't
 
-(Don't) Use separate prefixes for ontology and data when a unified prefix is preferred.
+Use separate prefixes for ontology and data when a unified prefix is preferred.
 ```turtle
 # Bad: Unnecessarily complex when unified prefix suffices
 @prefix dso: <https://ds.canonical.com/ontology#> .
@@ -103,7 +103,7 @@ This separation allows tools to distinguish between schema and instance data, en
 
 ### Do
 
-(Do) Place ontology definitions (classes, properties, datatypes) in the `definitions/` directory.
+Place ontology definitions (classes, properties, datatypes) in the `definitions/` directory.
 ```turtle
 # definitions/ontology.ttl
 @prefix ds: <https://ds.canonical.com/> .
@@ -116,7 +116,7 @@ ds:name a owl:DatatypeProperty ;
     rdfs:range xsd:string .
 ```
 
-(Do) Place instance data in the `data/` directory.
+Place instance data in the `data/` directory.
 ```turtle
 # data/global/component/button.ttl
 @prefix ds: <https://ds.canonical.com/> .
@@ -127,14 +127,14 @@ ds:global.component.button a ds:Component ;
 
 ### Don't
 
-(Don't) Mix class definitions and instance data in the same file.
+Mix class definitions and instance data in the same file.
 ```turtle
 # Bad: Mixing schema and data
 ds:Component a owl:Class .
 ds:global.component.button a ds:Component .
 ```
 
-(Don't) Place instance data in the `definitions/` directory.
+Place instance data in the `definitions/` directory.
 ```
 # Bad: Data file in definitions
 definitions/
@@ -149,7 +149,7 @@ Every Turtle file must declare all prefixes used within the file at the top of t
 
 ### Do
 
-(Do) Declare all prefixes at the top of the file.
+Declare all prefixes at the top of the file.
 ```turtle
 @prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .
@@ -163,14 +163,14 @@ ds:Component a owl:Class ;
 
 ### Don't
 
-(Don't) Declare the same prefix multiple times.
+Declare the same prefix multiple times.
 ```turtle
 # Bad: Duplicate prefix declaration
 @prefix ds: <https://ds.canonical.com/> .
 @prefix ds: <https://ds.canonical.com/> .
 ```
 
-(Don't) Use prefixes without declaring them.
+Use prefixes without declaring them.
 ```turtle
 # Bad: Missing prefix declaration for ds:
 ds:Component a owl:Class .

package/package.json

@@ -1,9 +1,23 @@
 {
   "name": "@canonical/code-standards",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Code standards ontology and documentation generator",
   "type": "module",
   "scripts": {
-    "docs": "bun src/scripts/generate-docs.ts"
+    "build": "echo 'No build step yet' && exit 0",
+    "check": "biome check && tsc --noEmit",
+    "check:fix": "biome check --write",
+    "check:ts": "tsc --noEmit",
+    "test": "vitest run",
+    "docs": "bun src/scripts/generate-docs.ts",
+    "docs:check": "bun run docs && git diff --exit-code docs/"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@canonical/biome-config": "^0.17.1",
+    "@canonical/typescript-config": "^0.17.1",
+    "@types/bun": "latest",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }