@canonical/code-standards 0.1.0

package/data/tsdoc.ttl

@@ -0,0 +1,216 @@
+@prefix cso: <http://pragma.canonical.com/codestandards#> .
+@prefix cs: <http://pragma.canonical.com/codestandards/instances#> .
+@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#> .
+
+# TSDoc Category
+cs:TSDocCategory a cso:Category ;
+    rdfs:label "TSDoc"@en ;
+    rdfs:comment "Standards for TypeScript documentation comments — placement, layering, and tag usage."@en ;
+    cso:slug "tsdoc" .
+
+# Module Tag Location
+cs:TSDocModuleTagLocation a cso:CodeStandard ;
+    cso:name "tsdoc/module-tag-location" ;
+    cso:hasCategory cs:TSDocCategory ;
+    cso:description "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." ;
+    cso:dos """
+(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) {
+  // ...
+}
+```
+""" ;
+    cso:donts """
+(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}`;
+}
+```
+""" .
+
+# Documentation Layers
+cs:TSDocDocumentationLayers a cso:CodeStandard ;
+    cso:name "tsdoc/documentation-layers" ;
+    cso:hasCategory cs:TSDocCategory ;
+    cso:description "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." ;
+    cso:dos """
+(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[]) {
+  // ...
+}
+```
+""" ;
+    cso:donts """
+(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) { /* ... */ }
+```
+""" .
+
+# Self-Contained Documentation
+cs:TSDocSelfContained a cso:CodeStandard ;
+    cso:name "tsdoc/self-contained" ;
+    cso:hasCategory cs:TSDocCategory ;
+    cso:description "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." ;
+    cso:dos """
+(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 {
+  // ...
+}
+```
+""" ;
+    cso:donts """
+(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/data/turtle.ttl

@@ -0,0 +1,179 @@
+@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#> .
+
+# Turtle Category
+cs:TurtleCategory a cs:Category ;
+    rdfs:label "Turtle"@en ;
+    rdfs:comment "Standards specific to Turtle (RDF) file authoring"@en ;
+    cs:slug "turtle" .
+
+# Definitions vs Data Files Standard
+cs:DefinitionsVsData a cs:CodeStandard ;
+    cs:name "turtle/structure/definitions-vs-data" ;
+    cs:hasCategory cs:TurtleCategory ;
+    cs:description """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.""" ;
+    cs:dos """
+(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" .
+```
+""" ;
+    cs:donts """
+(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
+```
+""" .
+
+# Local Name Casing Convention Standard
+cs:LocalNameCasing a cs:CodeStandard ;
+    cs:name "turtle/naming/local-name-casing" ;
+    cs:hasCategory cs:TurtleCategory ;
+    cs:description """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.""" ;
+    cs:dos """
+(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 .
+```
+""" ;
+    cs:donts """
+(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 .
+```
+""" .
+
+# Unified Prefix Standard
+cs:UnifiedPrefix a cs:CodeStandard ;
+    cs:name "turtle/naming/unified-prefix" ;
+    cs:hasCategory cs:TurtleCategory ;
+    cs:description """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/`).""" ;
+    cs:dos """
+(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" .
+```
+""" ;
+    cs:donts """
+(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 .
+```
+""" .
+
+# Prefix Declaration Standard
+cs:PrefixDeclaration a cs:CodeStandard ;
+    cs:name "turtle/syntax/prefix-declaration" ;
+    cs:hasCategory cs:TurtleCategory ;
+    cs:description """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.""" ;
+    cs:dos """
+(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" .
+```
+""" ;
+    cs:donts """
+(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/definitions/CodeStandard.ttl

@@ -0,0 +1,80 @@
+@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#> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+
+# Ontology Declaration
+cs: a owl:Ontology ;
+    rdfs:label "Code Standards Ontology"@en ;
+    rdfs:comment "An ontology for describing software development code standards and best practices. This ontology provides a structured way to document coding standards including categories, descriptions, do's and don'ts."@en ;
+    owl:versionInfo "1.0.0" .
+
+# Classes
+cs:CodeStandard a owl:Class ;
+                rdfs:label "Code Standard"@en ;
+                rdfs:comment "A coding standard or best practice guideline for software development"@en .
+
+cs:Category a owl:Class ;
+            rdfs:label "Category"@en ;
+            rdfs:comment "A category for grouping related code standards (e.g., testing, components, react, typescript)"@en ;
+            rdfs:subClassOf skos:Concept .
+
+# Datatype properties
+cs:slug a owl:DatatypeProperty ;
+    rdfs:label "slug"@en ;
+    rdfs:comment "A short identifier for the category or standard, used for domain annotation."@en ;
+    rdfs:domain cs:Category ;
+    rdfs:range xsd:string .
+
+# Datatypes
+cs:NamePattern a owl:Datatype ;
+    owl:onDatatype xsd:string ;
+    owl:withRestrictions (
+        [ xsd:pattern "^[a-z]+(/[a-z0-9-]+){2,}$" ]
+    ) .
+
+# Object Properties
+cs:hasCategory a owl:ObjectProperty ;
+               rdfs:label "has category"@en ;
+               rdfs:comment "Associates a code standard with its category"@en ;
+               rdfs:domain cs:CodeStandard ;
+               rdfs:range cs:Category .
+
+cs:extends a owl:ObjectProperty ;
+              rdfs:label "extends"@en ;
+              rdfs:comment "Associates a code standard with another standard that it extends or adds further context to"@en ;
+              rdfs:domain cs:CodeStandard ;
+              rdfs:range cs:CodeStandard .
+
+
+cs:name a owl:DatatypeProperty ;
+        rdfs:label "name"@en ;
+        rdfs:comment "The domain-based identifier name of the code standard (e.g., 'react/component/folder-structure')."@en ;
+        rdfs:domain cs:CodeStandard ;
+        rdfs:range cs:NamePattern .
+
+cs:description a owl:DatatypeProperty ;
+               rdfs:label "description"@en ;
+               rdfs:comment "A general description of the code standard in markdown format"@en ;
+               rdfs:domain cs:CodeStandard ;
+               rdfs:range xsd:string .
+
+cs:dos a owl:DatatypeProperty ;
+       rdfs:label "do's"@en ;
+       rdfs:comment "Examples of what should be done, in markdown format"@en ;
+       rdfs:domain cs:CodeStandard ;
+       rdfs:range xsd:string .
+
+cs:donts a owl:DatatypeProperty ;
+         rdfs:label "don'ts"@en ;
+         rdfs:comment "Examples of what should not be done, in markdown format"@en ;
+         rdfs:domain cs:CodeStandard ;
+         rdfs:range xsd:string .
+
+cs:slug a owl:DatatypeProperty ;
+    rdfs:label "slug"@en ;
+    rdfs:comment "A short identifier for the category or standard, used for domain annotation."@en ;
+    rdfs:domain cs:Category ;
+    rdfs:range xsd:string .