@canonical/code-standards 0.1.0

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "sem": {
+      "command": "sem",
+      "args": ["mcp"]
+    }
+  }
+}

package/README.md

@@ -0,0 +1,297 @@
+# Code Standards Ontology
+
+An OWL ontology for codifying software development standards as structured, queryable knowledge graphs. Standards become machine-readable, versionable, and programmatically accessible to both humans and AI agents.
+
+**Core Philosophy:** Code standards are institutional knowledge. By modeling them ontologically, we transform tribal wisdom into queryable data—enabling automated linting context, AI-assisted code review, and consistent onboarding across teams.
+
+---
+
+## Quick Start
+
+### 1. Core Concepts
+
+Each code standard is a structured record with:
+
+```
+CodeStandard
+├── name         - Domain path (e.g., "react/component/folder-structure")
+├── description  - What and why
+├── dos          - Correct examples with code
+├── donts        - Incorrect examples with explanation
+├── hasCategory  - Grouping (React, CSS, Storybook...)
+└── extends      - Parent standard (optional)
+```
+
+Standards are organized by **Categories** (technology domains) and can **extend** other standards for specialization.
+
+### 2. Defining a Standard
+
+```turtle
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
+@prefix cs:  <http://pragma.canonical.com/codestandards#> .
+
+cs:ComponentFolderStructure a cs:CodeStandard ;
+    cs:name "react/component/structure/folder" ;
+    cs:hasCategory cs:ReactCategory ;
+    cs:description "Each component must reside in its own folder containing all related files." ;
+    cs:dos """
+(Do) Place all component-related files within a single folder.
+```bash
+Button/
+  ├── Button.tsx
+  ├── Button.stories.tsx
+  ├── Button.test.tsx
+  ├── index.ts
+  ├── styles.css
+  └── types.ts
+```
+""" ;
+    cs:donts """
+(Don't) Scatter component files across different directories.
+```bash
+# Bad: Files are not co-located
+components/Button.tsx
+stories/Button.stories.tsx
+styles/Button.css
+```
+""" .
+
+
+### 3. Name Convention
+
+Standard names follow a domain path pattern:
+
+```
+{category}/{domain}/{subdomain}
+```
+
+| Pattern | Example |
+|---------|---------|
+| `react/component/folder-structure` | React component folder layout |
+| `css/selector/nesting` | CSS selector nesting rules |
+| `storybook/story/naming` | Storybook story naming conventions |
+| `rust/error/result-type` | Rust error handling with Result |
+
+---
+
+## Categories
+
+Standards are grouped by technology domain:
+
+| Category | Slug | Standards | Focus |
+|----------|------|-----------|-------|
+| **React** | `react` | 20+ | Component structure, hooks, patterns |
+| **CSS** | `css` | 8+ | Selectors, nesting, custom properties |
+| **Storybook** | `storybook` | 10+ | Stories, documentation, controls |
+| **Code** | `code` | 12+ | General TypeScript/JavaScript |
+| **Styling** | `styling` | 6+ | Design system styling patterns |
+| **Icons** | `icons` | 4+ | SVG icon implementation |
+| **Rust** | `rust` | 15+ | Idiomatic Rust, monadic composition |
+| **Turtle** | `turtle` | 5+ | RDF/Turtle file authoring |
+
+---
+
+## How-To Guides
+
+### How to Add a New Standard
+
+1. Identify the category (React, CSS, etc.)
+2. Determine the domain path name
+3. Create or edit the category's `.ttl` file in `data/`
+4. Define required properties
+
+```turtle
+cs:MyNewStandard a cs:CodeStandard ;
+    cs:name "react/hooks/use-effect-cleanup" ;
+    cs:hasCategory cs:ReactCategory ;
+    cs:description """
+useEffect hooks that create subscriptions, timers, or listeners must
+return a cleanup function to prevent memory leaks.
+""" ;
+    cs:dos """
+(Do) Return a cleanup function for subscriptions.
+```typescript
+useEffect(() => {
+  const subscription = source.subscribe(handler);
+  return () => subscription.unsubscribe();
+}, [source]);
+```
+""" ;
+    cs:donts """
+(Don't) Forget cleanup for resources that persist.
+```typescript
+// Bad: Timer never cleared
+useEffect(() => {
+  setInterval(poll, 1000);
+}, []);
+```
+""" .
+
+
+### Writing Effective Do's and Don'ts
+
+**Do's should:**
+- Start with "(Do)" for parsing consistency
+- Include realistic, copy-pasteable code
+- Show the pattern in context
+
+**Don'ts should:**
+- Start with "(Don't)" for parsing consistency
+- Explain *why* the pattern is problematic
+- Show realistic mistakes developers actually make
+
+### How to Extend a Standard
+
+Use `cs:extends` when a standard builds on or specializes another:
+
+```turtle
+cs:ComponentContextStructure a cs:CodeStandard ;
+    cs:name "react/component/structure/context" ;
+    cs:extends cs:ComponentFolderStructure ;
+    cs:hasCategory cs:ReactCategory ;
+    cs:description """
+Context provider components follow the standard folder structure with
+additional files for the context definition and hook.
+""" ;
+    cs:dos """
+(Do) Include Context.tsx and useContext hook.
+```bash
+AuthProvider/
+  ├── AuthProvider.tsx      # Provider component
+  ├── Context.tsx           # Context definition
+  ├── useAuth.ts            # Consumer hook
+  ├── index.ts
+  └── types.ts
+```
+""" .
+
+The `extends` relationship enables:
+- Inheritance queries (find all folder structure variants)
+- Hierarchical documentation
+- Progressive specificity
+
+
+## Reference
+
+### Classes
+
+| Class | Description | Instances |
+|-------|-------------|-----------|
+| `CodeStandard` | A coding guideline with do's and don'ts | 64 |
+| `Category` | Grouping for related standards | 8 |
+
+### CodeStandard Properties
+
+| Property | Range | Description |
+|----------|-------|-------------|
+| `name` | NamePattern | Domain path identifier (e.g., `react/component/folder`) |
+| `description` | string | What the standard requires and why |
+| `dos` | string | Correct examples with code blocks |
+| `donts` | string | Incorrect examples with explanations |
+| `hasCategory` | Category | Technology domain classification |
+| `extends` | CodeStandard | Parent standard for specialization |
+
+### Category Properties
+
+| Property | Range | Description |
+|----------|-------|-------------|
+| `slug` | string | Short identifier (e.g., `react`, `css`) |
+| `label` | string | Display name |
+| `comment` | string | Category description |
+
+### Name Pattern
+
+Standard names must match:
+
+```regex
+^[a-z]+(/[a-z0-9-]+){2,}$
+```
+
+Valid: `react/component/folder-structure`, `css/selector/nesting`
+Invalid: `React/Component`, `component-structure`
+
+---
+
+## Architecture
+
+```
+code-standards/
+├── definitions/
+│   └── CodeStandard.ttl    # TBox: Classes, properties, constraints
+├── data/
+│   ├── react.ttl           # React standards
+│   ├── css.ttl             # CSS standards
+│   ├── storybook.ttl       # Storybook standards
+│   ├── code.ttl            # General code standards
+│   ├── styling.ttl         # Styling standards
+│   ├── icons.ttl           # Icon standards
+│   ├── rust.ttl            # Rust standards
+│   └── turtle.ttl          # Turtle authoring standards
+├── skills/
+│   └── audit/              # Standard compliance checking skill
+├── sem.toml                # Package manifest
+└── README.md
+```
+
+### Namespaces
+
+```turtle
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
+```
+
+### Dependencies
+
+- **skos** — Category as SKOS Concept
+
+---
+
+## Integration
+
+### AI Code Review
+
+Standards are designed for AI consumption. When reviewing code, AI assistants can:
+
+1. Query relevant standards for the code being reviewed
+2. Apply the structured do's/don'ts to evaluate the diff
+3. Generate precise feedback based on standard violations
+
+The structured format enables consistent, actionable code review feedback.
+
+### IDE Integration
+
+Standards can power:
+- Real-time linting hints
+- Autocomplete suggestions
+- Documentation popups
+- Refactoring recommendations
+
+### Onboarding
+
+New team members can query standards by domain:
+
+```
+# "What are the React component rules?"
+"Show me all standards for React components"
+```
+
+### Design System Ontology
+
+Code standards complement the [Design System Ontology](https://github.com/canonical/design-system):
+
+| Ontology | Focus |
+|----------|-------|
+| Design System | What to build (components, patterns, modifiers) |
+| Code Standards | How to build (structure, patterns, conventions) |
+
+
+---
+
+## Version
+
+0.1.0 — Initial release with React, CSS, Storybook, and general code standards
+
+## Links
+
+- [Source](https://github.com/canonical/code-standards)
+- [Design System Ontology](https://github.com/canonical/design-system)
+- [Pragma Monorepo](https://github.com/canonical/pragma)