@canonical/code-standards 0.1.0

package/docs/tsdoc.md

@@ -0,0 +1,213 @@
+# TSDoc Standards
+
+Standards for tsdoc development.
+
+## tsdoc/documentation-layers
+
+File-level and export-level TSDoc serve fundamentally different purposes. Export-level documentation describes *what the symbol does* — its API contract, parameters, return semantics, and side effects. File-level documentation describes *why this module exists* — its architectural role, the design invariants it upholds, and how its exports relate to each other. In single-export files the file exists solely to house that export, so file-level documentation is redundant; document only the exported symbol. In multi-export files, a file-level block is warranted when it explains the cohesion principle that binds the exports together — the reason they live in one file rather than separate ones.
+
+### Do
+
+(Do) 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. */
+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.
+```typescript
+// types.ts — multiple exports, file-level explains cohesion
+/**
+ * Shared types for diagnostic rule modules.
+ *
+ * Each diagnostic check receives one of these context objects,
+ * ensuring a uniform interface across per-usage and file-level rules.
+ */
+
+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.
+```typescript
+/**
+ * Check: css/missing-fallback — var() without a fallback on an unregistered property.
+ *
+ * Pushes a diagnostic when a var() usage has no fallback and the property
+ * is not registered via @property.
+ */
+export default function checkMissingFallback(ctx: UsageRuleContext, results: Diagnostic[]) {
+  // ...
+}
+```
+
+### Don't
+
+(Don't) 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. */
+
+/** Resolve definitions for CSS custom property usages. */
+export default function resolveDefinition() { /* ... */ }
+```
+
+(Don't) 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. */
+
+export default function buildCompletionItem(name: string) { /* ... */ }
+```
+
+(Don't) 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) { /* ... */ }
+export function isHoverRequest(req: WorkerRequest) { /* ... */ }
+export function isDiagnosticsRequest(req: WorkerRequest) { /* ... */ }
+```
+
+---
+
+## tsdoc/module-tag-location
+
+The `@module` TSDoc tag must appear only on barrel files such as `index.ts`. Ordinary source files must document their exported API directly and must not use file-level `@module` tags.
+
+### Do
+
+(Do) Use `@module` on a barrel file that defines a package or folder-level API.
+```typescript
+/**
+ * Public protocol API.
+ * @module protocol
+ */
+export { createRequest, matchResponse } from './index.js';
+```
+
+(Do) 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) {
+  // ...
+}
+```
+
+### Don't
+
+(Don't) Add `@module` to a single-purpose implementation file.
+```typescript
+/**
+ * Build a completion item.
+ * @module providers/completions/buildCompletionItem
+ */
+export default function buildCompletionItem(name: string) {
+  // ...
+}
+```
+
+(Don't) Use file-level `@module` tags as a substitute for export documentation.
+```typescript
+/** @module helpers/formatCurrency */
+export default function formatCurrency(value: number) {
+  return `$${value}`;
+}
+```
+
+---
+
+## tsdoc/self-contained
+
+TSDoc comments must be self-contained — a reader should fully understand the documented symbol from its comment alone. External links (public specs, RFCs, GitHub issues) are allowed as supplementary references, but the comment itself must never depend on them for comprehension. If an external concept drives the implementation, distill the essential information into the comment.
+
+### Do
+
+(Do) Explain the concept inline so the reader needs nothing else:
+```typescript
+/**
+ * Encode a string as a percent-encoded URI component.
+ *
+ * Replaces every character that is not an unreserved character
+ * (A-Z, a-z, 0-9, `-`, `.`, `_`, `~`) with its UTF-8 percent-encoded form.
+ */
+export function encodeComponent(value: string): string {
+  // ...
+}
+```
+
+(Do) Add an external link as a supplementary reference after a self-sufficient explanation:
+```typescript
+/**
+ * Compare two semantic version strings.
+ *
+ * Compares major, minor, and patch numerically in that order.
+ * Returns a negative number if `a < b`, zero if equal, or a positive number if `a > b`.
+ * Pre-release versions (e.g. `1.0.0-alpha`) sort before their release counterpart.
+ *
+ * @see https://semver.org
+ */
+export function compareVersions(a: string, b: string): number {
+  // ...
+}
+```
+
+(Do) Reference a GitHub issue for additional context when the comment already explains the behaviour:
+```typescript
+/**
+ * Truncate session tokens to 64 characters before storage.
+ *
+ * Tokens longer than 64 characters exceed the column width in the
+ * sessions table and would be silently truncated by the database,
+ * so we enforce the limit explicitly.
+ *
+ * @see https://github.com/acme/backend/issues/412
+ */
+export function truncateToken(token: string): string {
+  // ...
+}
+```
+
+### Don't
+
+(Don't) Point the reader to an external resource instead of explaining the behaviour:
+```typescript
+/**
+ * Encode a URI component.
+ *
+ * Implements RFC 3986 §2.1.
+ * @see https://datatracker.ietf.org/doc/html/rfc3986#section-2.1
+ */
+export function encodeComponent(value: string): string {
+  // ...
+}
+```
+
+(Don't) Reference a wiki or internal doc as a substitute for inline explanation:
+```typescript
+/**
+ * Truncate session tokens before storage.
+ *
+ * See the security review document for rationale:
+ * https://wiki.internal/security/session-token-length
+ */
+export function truncateToken(token: string): string {
+  // ...
+}
+```
+
+(Don't) Leave the reader unable to understand the symbol without following a link:
+```typescript
+/**
+ * Compare two semantic version strings.
+ *
+ * @see https://semver.org for the full specification.
+ */
+export function compareVersions(a: string, b: string): number {
+  // ...
+}
+```
+
+---

package/docs/turtle.md

@@ -0,0 +1,179 @@
+# Turtle Standards
+
+Standards for turtle development.
+
+## turtle/naming/local-name-casing
+
+Within a unified prefix namespace, differentiate between schema elements and instances using casing conventions for the local name (the part after the prefix colon):
+
+- **PascalCase** for classes (e.g., `ds:Component`, `ds:UIElement`)
+- **camelCase** for properties (e.g., `ds:name`, `ds:hasProperty`)
+- **lowercase** (often with dots or hyphens) for instances (e.g., `ds:global.component.button`)
+
+This convention allows a single prefix to serve both definitions and data, with the casing clearly indicating the type of resource.
+
+### Do
+
+(Do) 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.
+```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.
+```turtle
+ds:global.component.button a ds:Component .
+ds:global.modifier_family.importance a ds:ModifierFamily .
+```
+
+### Don't
+
+(Don't) Use lowercase for class names.
+```turtle
+# Bad: Class names should be PascalCase
+ds:component a owl:Class .
+```
+
+(Don't) 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.
+```turtle
+# Bad: Property names should be camelCase
+ds:HasProperty a owl:ObjectProperty .
+ds:NAME a owl:DatatypeProperty .
+```
+
+---
+
+## turtle/naming/unified-prefix
+
+When a package uses a single namespace for both ontology and data, use a unified prefix with casing to distinguish between classes, properties, and instances. This simplifies prefix management and makes the relationship between schema and data more apparent.
+
+The namespace URI should be a base URI without a fragment or trailing path segment for ontology vs data (e.g., `https://ds.canonical.com/` rather than separate `https://ds.canonical.com/ontology#` and `https://ds.canonical.com/data/`).
+
+### Do
+
+(Do) Use a single prefix for both definitions and data.
+```turtle
+# In both definitions/ and data/ files:
+@prefix ds: <https://ds.canonical.com/> .
+
+# Definitions use PascalCase/camelCase
+ds:Component a owl:Class .
+ds:name a owl:DatatypeProperty .
+
+# Data uses lowercase
+ds:global.component.button a ds:Component ;
+    ds:name "Button" .
+```
+
+### Don't
+
+(Don't) 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#> .
+@prefix ds: <https://ds.canonical.com/data/> .
+
+ds:global.component.button a dso:Component .
+```
+
+---
+
+## turtle/structure/definitions-vs-data
+
+Turtle files must be organized into two directories based on their content:
+
+- `definitions/` contains schema files (ontologies) with classes, properties, and datatypes
+- `data/` contains instance files with actual data conforming to the schema
+
+This separation allows tools to distinguish between schema and instance data, enables different validation rules, and makes the codebase easier to navigate.
+
+### Do
+
+(Do) Place ontology definitions (classes, properties, datatypes) in the `definitions/` directory.
+```turtle
+# definitions/ontology.ttl
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:Component a owl:Class ;
+    rdfs:label "Component" .
+
+ds:name a owl:DatatypeProperty ;
+    rdfs:domain ds:UIElement ;
+    rdfs:range xsd:string .
+```
+
+(Do) Place instance data in the `data/` directory.
+```turtle
+# data/global/component/button.ttl
+@prefix ds: <https://ds.canonical.com/> .
+
+ds:global.component.button a ds:Component ;
+    ds:name "Button" .
+```
+
+### Don't
+
+(Don't) 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.
+```
+# Bad: Data file in definitions
+definitions/
+  └── button.ttl  # Contains instance data
+```
+
+---
+
+## turtle/syntax/prefix-declaration
+
+Every Turtle file must declare all prefixes used within the file at the top of the file. Each prefix should be declared exactly once. Standard prefixes (rdf, rdfs, owl, xsd, skos) should be declared when used but are commonly understood.
+
+### Do
+
+(Do) 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#> .
+@prefix owl:   <http://www.w3.org/2002/07/owl#> .
+@prefix xsd:   <http://www.w3.org/2001/XMLSchema#> .
+@prefix ds:    <https://ds.canonical.com/> .
+
+ds:Component a owl:Class ;
+    rdfs:label "Component" .
+```
+
+### Don't
+
+(Don't) 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.
+```turtle
+# Bad: Missing prefix declaration for ds:
+ds:Component a owl:Class .
+```
+
+---

package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@canonical/code-standards",
+  "version": "0.1.0",
+  "description": "Code standards ontology and documentation generator",
+  "type": "module",
+  "scripts": {
+    "docs": "bun src/scripts/generate-docs.ts"
+  }
+}

package/skills/add-standard/SKILL.md

@@ -0,0 +1,288 @@
+# Add Standard
+
+Create and add a new code standard to the code-standards package.
+
+## When to Use
+
+Use this skill when:
+- "Add a standard for..."
+- "Create a coding standard..."
+- "Document a new convention..."
+- "Add guidance for..."
+
+## Workflow
+
+### 1. Check for Existing Standards
+
+Before creating a new standard, always check if one already exists:
+
+```sparql
+PREFIX cs: <http://pragma.canonical.com/codestandards#>
+
+SELECT ?standard ?name ?description WHERE {
+  ?standard a cs:CodeStandard ;
+            cs:name ?name ;
+            cs:description ?description .
+  FILTER(CONTAINS(LCASE(?name), "your-topic"))
+}
+```
+
+Or use lookup:
+```
+sem_lookup(type: "cs:CodeStandard", filters: {"cs:name": {"$contains": "your-topic"}})
+```
+
+### 2. Determine the Category
+
+List existing categories to find the right fit:
+
+```sparql
+PREFIX cs: <http://pragma.canonical.com/codestandards#>
+PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
+
+SELECT ?category ?label ?slug WHERE {
+  ?category a cs:Category ;
+            rdfs:label ?label ;
+            cs:slug ?slug .
+}
+```
+
+**Available Categories:**
+
+| Category | Slug | Description |
+|----------|------|-------------|
+| React | `react` | React component development |
+| CSS | `css` | CSS technical implementation |
+| Styling | `styling` | Design system styling patterns |
+| Code | `code` | General TypeScript standards |
+| Storybook | `storybook` | Storybook documentation |
+| Icons | `icons` | Icon implementation |
+
+If no existing category fits, create a new one (see Section 5).
+
+### 3. Design the Standard Name
+
+Standard names follow a hierarchical pattern: `{category}/{domain}/{topic}`
+
+**Pattern:** `^[a-z]+(/[a-z0-9-]+){2,}$`
+
+**Examples:**
+- `react/component/structure/folder`
+- `css/selectors/namespace`
+- `styling/tokens/creation`
+- `react/hooks/naming`
+
+**Guidelines:**
+- Use lowercase with hyphens for multi-word segments
+- Minimum 3 segments (category/domain/topic)
+- Be specific but not overly verbose
+- Follow existing naming patterns in the same category
+
+### 4. Write the Standard
+
+Create a new standard instance in the appropriate data file under `data/`.
+
+**Template:**
+
+```turtle
+cs:YourStandardName a cs:CodeStandard ;
+    cs:name "category/domain/topic" ;
+    cs:hasCategory cs:CategoryName ;
+    cs:description "Clear, concise description of what this standard covers and why it matters." ;
+    cs:dos """
+(Do) First recommended practice with example.
+```code
+// Example showing the correct approach
+```
+
+(Do) Second recommended practice.
+```code
+// Another example
+```
+""" ;
+    cs:donts """
+(Don't) First anti-pattern to avoid.
+```code
+// Example showing what NOT to do
+```
+
+(Don't) Second anti-pattern.
+```code
+// Another bad example
+```
+""" .
+```
+
+**Required Properties:**
+- `cs:name` - Hierarchical identifier (must match NamePattern)
+- `cs:hasCategory` - Reference to a Category instance
+- `cs:description` - What and why (plain text or markdown)
+- `cs:dos` - What TO do with examples
+- `cs:donts` - What NOT to do with examples
+
+**Optional Properties:**
+- `cs:extends` - Reference to a parent standard this builds upon
+
+### 5. Create a New Category (if needed)
+
+If your standard doesn't fit existing categories:
+
+```turtle
+cs:NewCategory a cs:Category ;
+    rdfs:label "Category Name"@en ;
+    rdfs:comment "Description of what this category covers"@en ;
+    cs:slug "slug-name" .
+```
+
+### 6. Extending Existing Standards
+
+When your standard builds on another:
+
+```turtle
+cs:SpecificStandard a cs:CodeStandard ;
+    cs:name "react/component/props/special-case" ;
+    cs:extends cs:ComponentProps ;  # Reference to parent
+    cs:hasCategory cs:ReactCategory ;
+    cs:description "Specific guidance that builds on the general props standard." ;
+    # ... dos and donts ...
+```
+
+Query to find potential parent standards:
+```sparql
+PREFIX cs: <http://pragma.canonical.com/codestandards#>
+
+SELECT ?standard ?name WHERE {
+  ?standard a cs:CodeStandard ;
+            cs:name ?name .
+  FILTER(STRSTARTS(?name, "react/component/props"))
+}
+```
+
+### 7. Validate Before Committing
+
+After writing the standard, validate the Turtle syntax:
+
+```bash
+sem check code-standards
+```
+
+Then verify the standard loads correctly:
+```
+sem_lookup(type: "cs:CodeStandard", filters: {"cs:name": "your/new/standard"})
+```
+
+## File Organization
+
+Standards are organized by category in `data/`:
+
+```
+code-standards/
+├── definitions/
+│   └── CodeStandard.ttl    # Ontology schema
+├── data/
+│   ├── react.ttl           # React standards
+│   ├── css.ttl             # CSS standards
+│   ├── styling.ttl         # Styling standards
+│   ├── code.ttl            # General code standards
+│   ├── storybook.ttl       # Storybook standards
+│   └── icons.ttl           # Icon standards
+└── skills/
+    └── standards-guide/
+        └── SKILL.md
+```
+
+Add new standards to the file matching their category.
+
+## Writing Quality Standards
+
+### Description Guidelines
+- Start with WHAT the standard covers
+- Explain WHY it matters
+- Keep it concise but complete
+- Use markdown for complex descriptions
+
+### Do's Guidelines
+- Start each item with `(Do)`
+- Provide concrete, runnable examples
+- Show the COMPLETE correct pattern
+- Explain the reasoning when not obvious
+
+### Don'ts Guidelines
+- Start each item with `(Don't)`
+- Show realistic mistakes developers make
+- Explain WHY it's problematic
+- Mirror the structure of the do's section
+
+### Example Quality Checklist
+- [ ] Examples are syntactically correct
+- [ ] Examples are self-contained (can be understood without context)
+- [ ] Examples use realistic code, not `foo`/`bar`
+- [ ] Examples include comments explaining key points
+- [ ] Both do's and don'ts cover the same scenarios
+
+## Complete Example
+
+Adding a new standard for React error boundaries:
+
+```turtle
+# In data/react.ttl
+
+cs:ErrorBoundaryUsage a cs:CodeStandard ;
+    cs:name "react/component/error-boundaries" ;
+    cs:hasCategory cs:ReactCategory ;
+    cs:description "Error boundaries must be used to catch JavaScript errors in component trees and display fallback UI. They should be placed strategically to isolate failures without breaking the entire application." ;
+    cs:dos """
+(Do) Wrap feature sections with error boundaries to isolate failures.
+```tsx
+const Dashboard = () => (
+  <div className="ds dashboard">
+    <ErrorBoundary fallback={<WidgetError />}>
+      <AnalyticsWidget />
+    </ErrorBoundary>
+    <ErrorBoundary fallback={<WidgetError />}>
+      <ActivityWidget />
+    </ErrorBoundary>
+  </div>
+);
+```
+
+(Do) Provide meaningful fallback UI that helps users understand and recover.
+```tsx
+const WidgetError = () => (
+  <div className="ds widget-error">
+    <p>This section couldn't load.</p>
+    <button onClick={() => window.location.reload()}>
+      Refresh page
+    </button>
+  </div>
+);
+```
+""" ;
+    cs:donts """
+(Don't) Wrap the entire application in a single error boundary.
+```tsx
+// Bad: One error anywhere crashes everything
+const App = () => (
+  <ErrorBoundary>
+    <Header />
+    <Main />
+    <Footer />
+  </ErrorBoundary>
+);
+```
+
+(Don't) Use generic or unhelpful fallback messages.
+```tsx
+// Bad: Doesn't help the user
+const fallback = <div>Something went wrong</div>;
+```
+""" .
+```
+
+## Tips
+
+1. **Check before creating**: Always search for existing standards first - you might need to extend rather than create new
+2. **Follow patterns**: Look at existing standards in the same category for style guidance
+3. **Be specific**: Vague standards are hard to follow - include concrete examples
+4. **Test your examples**: Make sure code examples actually work
+5. **Consider hierarchy**: Use `cs:extends` when your standard builds on another