@canonical/code-standards 0.1.0 → 0.1.2

package/skills/add-standard/SKILL.md

@@ -89,36 +89,51 @@ 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
+    cs:do [
+        cs:description "First recommended practice." ;
+        cs:language "typescript" ;
+        cs:code """
 // Example showing the correct approach
-```
-
-(Do) Second recommended practice.
-```code
-// Another example
-```
-""" ;
-    cs:donts """
-(Don't) First anti-pattern to avoid.
-```code
+const good = true;
+    """
+    ] ;
+    cs:do [
+        cs:description "Second recommended practice." ;
+        cs:language "typescript" ;
+        cs:code """
+// Another correct example
+const alsoGood = true;
+    """
+    ] ;
+    cs:dont [
+        cs:description "First anti-pattern to avoid." ;
+        cs:language "typescript" ;
+        cs:code """
 // Example showing what NOT to do
-```
-
-(Don't) Second anti-pattern.
-```code
+const bad = true;
+    """
+    ] ;
+    cs:dont [
+        cs:description "Second anti-pattern." ;
+        cs:language "typescript" ;
+        cs:code """
 // Another bad example
+const alsoBad = true;
+    """
+    ] .
 ```
-""" .
-```
+
+Each `cs:do` and `cs:dont` is a blank node (`cs:Example`) with structured fields:
+- `cs:description` — What the example demonstrates (required)
+- `cs:language` — Language of the code block, e.g. `"typescript"`, `"rust"`, `"css"`, `"bash"`, `"svg"` (optional, omit when no code)
+- `cs:code` — The code content (optional, omit for description-only examples)
 
 **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
+- `cs:do` - One or more positive examples (blank nodes)
+- `cs:dont` - One or more negative examples (blank nodes)
 
 **Optional Properties:**
 - `cs:extends` - Reference to a parent standard this builds upon
@@ -144,7 +159,20 @@ cs:SpecificStandard a cs:CodeStandard ;
     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 ...
+    cs:do [
+        cs:description "Example of the specific pattern." ;
+        cs:language "typescript" ;
+        cs:code """
+// ...
+    """
+    ] ;
+    cs:dont [
+        cs:description "Anti-pattern to avoid." ;
+        cs:language "typescript" ;
+        cs:code """
+// ...
+    """
+    ] .
 ```
 
 Query to find potential parent standards:
@@ -201,17 +229,19 @@ Add new standards to the file matching their category.
 - Keep it concise but complete
 - Use markdown for complex descriptions
 
-### Do's Guidelines
-- Start each item with `(Do)`
+### Do Examples Guidelines
+- Each `cs:do` blank node is one discrete positive example
+- `cs:description` explains what the example demonstrates
+- `cs:language` must match the code block language (e.g. `"typescript"`, `"css"`, `"rust"`)
+- `cs:code` contains the actual code — no markdown fences needed
 - Provide concrete, runnable examples
 - Show the COMPLETE correct pattern
-- Explain the reasoning when not obvious
 
-### Don'ts Guidelines
-- Start each item with `(Don't)`
+### Don't Examples Guidelines
+- Each `cs:dont` blank node is one discrete negative example
 - Show realistic mistakes developers make
-- Explain WHY it's problematic
-- Mirror the structure of the do's section
+- `cs:description` should explain WHY it's problematic
+- Mirror the structure of the do examples where possible
 
 ### Example Quality Checklist
 - [ ] Examples are syntactically correct
@@ -231,9 +261,10 @@ 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
+    cs:do [
+        cs:description "Wrap feature sections with error boundaries to isolate failures." ;
+        cs:language "tsx" ;
+        cs:code """
 const Dashboard = () => (
   <div className="ds dashboard">
     <ErrorBoundary fallback={<WidgetError />}>
@@ -244,10 +275,12 @@ const Dashboard = () => (
     </ErrorBoundary>
   </div>
 );
-```
-
-(Do) Provide meaningful fallback UI that helps users understand and recover.
-```tsx
+    """
+    ] ;
+    cs:do [
+        cs:description "Provide meaningful fallback UI that helps users understand and recover." ;
+        cs:language "tsx" ;
+        cs:code """
 const WidgetError = () => (
   <div className="ds widget-error">
     <p>This section couldn't load.</p>
@@ -256,11 +289,12 @@ const WidgetError = () => (
     </button>
   </div>
 );
-```
-""" ;
-    cs:donts """
-(Don't) Wrap the entire application in a single error boundary.
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Wrap the entire application in a single error boundary." ;
+        cs:language "tsx" ;
+        cs:code """
 // Bad: One error anywhere crashes everything
 const App = () => (
   <ErrorBoundary>
@@ -269,14 +303,16 @@ const App = () => (
     <Footer />
   </ErrorBoundary>
 );
-```
-
-(Don't) Use generic or unhelpful fallback messages.
-```tsx
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use generic or unhelpful fallback messages." ;
+        cs:language "tsx" ;
+        cs:code """
 // Bad: Doesn't help the user
 const fallback = <div>Something went wrong</div>;
-```
-""" .
+    """
+    ] .
 ```
 
 ## Tips

package/src/scripts/generate-docs.ts

@@ -4,17 +4,23 @@
  * Usage: bun src/scripts/generate-docs.ts [output-dir]
  */
 
-import { readFileSync, writeFileSync, mkdirSync, readdirSync } from "fs";
-import { join, basename } from "path";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
 
 const DATA_DIR = join(import.meta.dir, "../../data");
 const DEFAULT_OUTPUT = "./docs";
 
+interface Example {
+  description: string;
+  language: string;
+  code: string;
+}
+
 interface Standard {
   name: string;
   description: string;
-  dos: string;
-  donts: string;
+  dos: Example[];
+  donts: Example[];
 }
 
 interface Category {
@@ -23,15 +29,15 @@ interface Category {
   standards: Standard[];
 }
 
-// Minimal TTL parser - extracts string literals
+// Extract a single string literal (single-line or triple-quoted)
 function extractLiteral(content: string, predicate: string): string {
   const regex = new RegExp(`${predicate}\\s+"""([\\s\\S]*?)"""`, "g");
   const match = regex.exec(content);
-  if (match) return match[1].trim();
+  if (match?.[1]) return match[1].trim();
 
   const singleLine = new RegExp(`${predicate}\\s+"([^"]*)"`, "g");
   const singleMatch = singleLine.exec(content);
-  return singleMatch ? singleMatch[1].trim() : "";
+  return singleMatch?.[1]?.trim() ?? "";
 }
 
 function parseCategory(content: string): { label: string; slug: string } {
@@ -43,6 +49,61 @@ function parseCategory(content: string): { label: string; slug: string } {
   return { label, slug };
 }
 
+/**
+ * Parse blank node examples from a standard block for a given predicate (cs:do or cs:dont).
+ */
+function parseExamples(
+  block: string,
+  predicate: "cs:do" | "cs:dont",
+): Example[] {
+  const examples: Example[] = [];
+
+  // Match blank node patterns: predicate [ ... ]
+  // We need to handle nested triple-quoted strings inside the blank node
+  const escapedPred = predicate.replace(".", "\\.");
+  const regex = new RegExp(`${escapedPred}\\s*\\[`, "g");
+  let match = regex.exec(block);
+
+  while (match !== null) {
+    const startIdx = match.index + match[0].length;
+
+    // Find the matching closing bracket, accounting for nested triple-quoted strings
+    let depth = 1;
+    let i = startIdx;
+    let inTripleQuote = false;
+
+    while (i < block.length && depth > 0) {
+      if (!inTripleQuote) {
+        if (block.slice(i, i + 3) === '"""') {
+          inTripleQuote = true;
+          i += 3;
+          continue;
+        }
+        if (block[i] === "[") depth++;
+        if (block[i] === "]") depth--;
+      } else {
+        if (block.slice(i, i + 3) === '"""') {
+          inTripleQuote = false;
+          i += 3;
+          continue;
+        }
+      }
+      i++;
+    }
+
+    const blankNodeContent = block.slice(startIdx, i - 1);
+
+    const description = extractLiteral(blankNodeContent, "cs:description");
+    const language = extractLiteral(blankNodeContent, "cs:language");
+    const code = extractLiteral(blankNodeContent, "cs:code");
+
+    examples.push({ description, language, code });
+    match = regex.exec(block);
+  }
+
+  return examples;
+}
+
 function parseStandards(content: string): Standard[] {
   // Split by standard definitions
   const blocks = content.split(/\n(?=\w+:\w+\s+a\s+cs:CodeStandard)/);
@@ -53,8 +114,8 @@ function parseStandards(content: string): Standard[] {
 
     const name = extractLiteral(block, "cs:name");
     const description = extractLiteral(block, "cs:description");
-    const dos = extractLiteral(block, "cs:dos");
-    const donts = extractLiteral(block, "cs:donts");
+    const dos = parseExamples(block, "cs:do");
+    const donts = parseExamples(block, "cs:dont");
 
     if (name) {
       standards.push({ name, description, dos, donts });
@@ -64,6 +125,21 @@ function parseStandards(content: string): Standard[] {
   return standards.sort((a, b) => a.name.localeCompare(b.name));
 }
 
+function renderExample(example: Example): string {
+  const parts: string[] = [];
+
+  if (example.description) {
+    parts.push(example.description);
+  }
+
+  if (example.code) {
+    const lang = example.language || "";
+    parts.push(`\`\`\`${lang}\n${example.code}\n\`\`\``);
+  }
+
+  return parts.join("\n");
+}
+
 function generateMarkdown(category: Category): string {
   const lines: string[] = [
     `# ${category.label} Standards`,
@@ -75,11 +151,17 @@ function generateMarkdown(category: Category): string {
   for (const std of category.standards) {
     lines.push(`## ${std.name}`, "", std.description, "");
 
-    if (std.dos) {
-      lines.push("### Do", "", std.dos, "");
+    if (std.dos.length > 0) {
+      lines.push("### Do", "");
+      for (const ex of std.dos) {
+        lines.push(renderExample(ex), "");
+      }
     }
-    if (std.donts) {
-      lines.push("### Don't", "", std.donts, "");
+    if (std.donts.length > 0) {
+      lines.push("### Don't", "");
+      for (const ex of std.donts) {
+        lines.push(renderExample(ex), "");
+      }
     }
     lines.push("---", "");
   }

package/src/scripts/index.ts

@@ -9,11 +9,13 @@ const command = process.argv[2];
 switch (command) {
   case "docs":
   case "generate-docs":
-    await import("./generate-docs.ts");
+    await import("./generate-docs.js");
     break;
   default:
     console.log("Usage: bun src/scripts/index.ts <command>");
     console.log("");
     console.log("Commands:");
-    console.log("  docs [output-dir]  Generate markdown docs (default: ./docs)");
+    console.log(
+      "  docs [output-dir]  Generate markdown docs (default: ./docs)",
+    );
 }

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "@canonical/typescript-config",
+  "compilerOptions": {
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}