@canonical/webarchitect 0.10.0 → 0.11.0

package/README.md

@@ -249,3 +249,4 @@ The programmatic API makes it easy to integrate webarchitect into existing build
 - **IDE Integration** - No real-time validation feedback is available yet in code editors. Developers must run webarchitect manually or through build scripts to see validation results. Real-time diagnostics would require Language Server Protocol implementation or editor-specific plugins.
 - **Svelte support** - No svelte-specific ruleset has been developed yet.
 - **Error Code Granularity** - All validation failures return the same exit code (1) regardless of failure type. Missing files, invalid JSON syntax, and schema validation failures are not distinguished programmatically. This limits automated error handling and reporting capabilities.
+ 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@canonical/webarchitect",
   "description": "A tool to test the compliance with architecture specifications for packages and applications.",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
-  "module": "dist/esm/index.js",
-  "types": "dist/types/index.d.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
   "bin": {
-    "webarchitect": "dist/esm/cli.js"
+    "webarchitect": "src/cli.ts"
   },
   "files": [
-    "dist",
+    "src",
     "rulesets"
   ],
   "author": {
@@ -26,25 +26,27 @@
   },
   "homepage": "https://github.com/canonical/ds25#readme",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "check": "bun run check:biome && bun run check:ts",
+    "build": "echo 'No build needed - runs directly from TypeScript'",
+    "build:all": "bun run build",
+    "check": "bun run check:biome && bun run check:ts && bun run check:webarchitect",
     "check:fix": "bun run check:biome:fix && bun run check:ts",
     "check:biome": "biome check",
     "check:biome:fix": "biome check --write",
     "check:ts": "tsc --noEmit",
-    "test": "echo 'No tests defined yet'"
+    "test": "echo 'No tests defined yet'",
+    "check:webarchitect": "webarchitect tool-ts"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.2.4",
-    "@canonical/biome-config": "^0.10.0",
-    "@canonical/typescript-config-base": "^0.10.0",
+    "@biomejs/biome": "2.3.11",
+    "@canonical/biome-config": "^0.11.0",
+    "@canonical/typescript-config-base": "^0.11.0",
     "@types/json-schema": "^7.0.15",
-    "typescript": "^5.8.2"
+    "typescript": "^5.9.3"
   },
   "dependencies": {
     "ajv": "^8.17.1",
-    "chalk": "^5.4.1",
-    "commander": "^14.0.0"
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2"
   },
-  "gitHead": "49cd1f8973f269cc6ced61c27c137e379ccb032c"
+  "gitHead": "29125736059d1880b3d0fc277b218a63a2574f28"
 }

package/rulesets/library.ruleset.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://github.com/webarchitect/schemas/main/schema.json",
+  "name": "library",
+  "extends": ["package"],
+  "package-license": {
+    "file": {
+      "name": "package.json",
+      "contains": {
+        "type": "object",
+        "properties": {
+          "license": {
+            "const": "LGPL-3.0"
+          }
+        },
+        "required": ["license"]
+      }
+    }
+  }
+}

package/rulesets/package.ruleset.json

@@ -34,7 +34,7 @@
       }
     }
   },
-  "package": {
+  "package-structure": {
     "file": {
       "name": "package.json",
       "contains": {
@@ -60,9 +60,6 @@
             "type": "array",
             "contains": { "const": "dist" }
           },
-          "license": {
-            "const": "GPL-3.0"
-          },
           "scripts": {
             "type": "object",
             "properties": {
@@ -88,7 +85,6 @@
           "module",
           "types",
           "files",
-          "license",
           "scripts"
         ]
       }

package/rulesets/tool-ts.ruleset.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://github.com/webarchitect/schemas/main/schema.json",
+  "name": "tool-ts",
+  "extends": ["base"],
+  "biome": {
+    "file": {
+      "name": "biome.json",
+      "contains": {
+        "type": "object",
+        "properties": {
+          "$schema": {
+            "type": "string"
+          },
+          "extends": {
+            "type": "array",
+            "items": { "const": "@canonical/biome-config" },
+            "minItems": 1,
+            "maxItems": 1
+          },
+          "files": {
+            "type": "object",
+            "properties": {
+              "includes": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            },
+            "additionalProperties": false,
+            "description": "File inclusion patterns only"
+          }
+        },
+        "required": ["extends"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "package-structure": {
+    "file": {
+      "name": "package.json",
+      "contains": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "pattern": "^@canonical/"
+          },
+          "version": {
+            "type": "string"
+          },
+          "type": {
+            "const": "module"
+          },
+          "module": {
+            "const": "src/index.ts"
+          },
+          "types": {
+            "const": "src/index.ts"
+          },
+          "files": {
+            "type": "array",
+            "contains": { "const": "src" }
+          },
+          "scripts": {
+            "type": "object",
+            "properties": {
+              "build": {
+                "type": "string",
+                "description": "Build command (can be no-op for TS-only packages)"
+              },
+              "test": {
+                "type": "string",
+                "description": "Test command (implementation flexible)"
+              },
+              "check:ts": {
+                "const": "tsc --noEmit"
+              }
+            },
+            "required": ["build", "test", "check:ts"]
+          }
+        },
+        "required": [
+          "name",
+          "version",
+          "type",
+          "module",
+          "types",
+          "files",
+          "scripts"
+        ]
+      }
+    }
+  },
+  "package-license": {
+    "file": {
+      "name": "package.json",
+      "contains": {
+        "type": "object",
+        "properties": {
+          "license": {
+            "const": "GPL-3.0"
+          }
+        },
+        "required": ["license"]
+      }
+    }
+  }
+}

package/rulesets/tool.ruleset.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://github.com/webarchitect/schemas/main/schema.json",
+  "name": "tool",
+  "extends": ["package"],
+  "package-license": {
+    "file": {
+      "name": "package.json",
+      "contains": {
+        "type": "object",
+        "properties": {
+          "license": {
+            "const": "GPL-3.0"
+          }
+        },
+        "required": ["license"]
+      }
+    }
+  }
+}

package/src/cli.ts

@@ -0,0 +1,322 @@
+#!/usr/bin/env bun
+import type { ErrorObject } from "ajv";
+import chalk from "chalk";
+import { Command } from "commander";
+import { discoverAllRulesets } from "./lib/index.js";
+import type { ValidationResult } from "./types.js";
+import validate from "./validate.js";
+
+const program = new Command();
+
+/**
+ * Formats AJV validation errors into human-readable messages.
+ * Groups errors by their property path and removes duplicate messages.
+ *
+ * @param errorsJson - JSON string containing an array of AJV ErrorObject instances
+ * @returns Array of formatted error messages, one per property path
+ *
+ * @example
+ * ```typescript
+ * const errors = '[{"instancePath": "/name", "message": "must be string"}]';
+ * const formatted = formatAjvErrors(errors);
+ * // Returns: ["name: must be string"]
+ * ```
+ */
+function formatAjvErrors(errorsJson: string): string[] {
+  try {
+    const errors = JSON.parse(errorsJson) as ErrorObject[];
+    const errorsByPath = new Map<string, Set<string>>();
+
+    for (const error of errors) {
+      const path = error.instancePath || "root";
+      const message = error.message || "validation failed";
+
+      if (!errorsByPath.has(path)) {
+        errorsByPath.set(path, new Set());
+      }
+      // Use optional chaining for safety
+      errorsByPath.get(path)?.add(message);
+    }
+
+    return Array.from(errorsByPath.entries()).map(([path, messages]) => {
+      const property = path === "root" ? "file" : path.replace("/", "");
+      const messageList = Array.from(messages).join(", ");
+      return `${property}: ${messageList}`;
+    });
+  } catch {
+    // Fallback if JSON parsing fails
+    return [errorsJson];
+  }
+}
+
+/**
+ * Formats validation results for terminal output with color coding.
+ * Displays failed validations first, followed by passed validations,
+ * and ends with a summary. In verbose mode, shows additional context
+ * including file contents and validation rules.
+ *
+ * @param results - Array of validation results to format
+ * @param verbose - Whether to show detailed information including file contents and rules
+ *
+ * @example
+ * ```typescript
+ * const results = [
+ *   { rule: "package.json", passed: true },
+ *   { rule: "biome.json", passed: false, message: "File not found" }
+ * ];
+ * formatTerminalOutput(results, true);
+ * ```
+ */
+function formatTerminalOutput(
+  results: ValidationResult[],
+  verbose = false,
+): void {
+  console.log(); // Empty line for spacing
+
+  const passedResults = results.filter((r) => r.passed);
+  const failedResults = results.filter((r) => !r.passed);
+
+  if (failedResults.length > 0) {
+    console.log(chalk.red.bold("✗ FAILED VALIDATIONS"));
+    console.log(chalk.gray("─".repeat(50)));
+
+    for (const result of failedResults) {
+      console.log(chalk.red(`✗ ${result.rule}`));
+
+      if (verbose && result.context) {
+        console.log(chalk.gray(`  Target: ${result.context.target}`));
+        if (result.context.description) {
+          console.log(chalk.gray(`  Rule: ${result.context.description}`));
+        }
+      }
+
+      if (result.message) {
+        // Check if message contains JSON (AJV errors)
+        if (result.message.includes("Validation failed: [")) {
+          const jsonStart = result.message.indexOf("[");
+          const prefix = result.message.substring(0, jsonStart).trim();
+          const jsonPart = result.message.substring(jsonStart);
+
+          if (prefix) {
+            console.log(chalk.gray(`  ${prefix}`));
+          }
+
+          const formattedErrors = formatAjvErrors(jsonPart);
+          for (const error of formattedErrors) {
+            console.log(chalk.gray(`  • ${error}`));
+          }
+        } else {
+          console.log(chalk.gray(`  ${result.message}`));
+        }
+      }
+
+      if (
+        verbose &&
+        result.context?.value &&
+        result.context.value !== "[File not found]"
+      ) {
+        // Use regular string instead of template literal where no interpolation needed
+        console.log(chalk.gray("  Found:"));
+        if (typeof result.context.value === "object") {
+          const preview = JSON.stringify(result.context.value, null, 2)
+            .split("\n")
+            .slice(0, 10) // Show first 10 lines
+            .map((line) => `    ${line}`)
+            .join("\n");
+          console.log(chalk.gray(preview));
+          if (JSON.stringify(result.context.value).split("\n").length > 10) {
+            console.log(chalk.gray("    ... (truncated)"));
+          }
+        } else {
+          console.log(chalk.gray(`    ${result.context.value}`));
+        }
+      }
+      console.log(); // Empty line between failures
+    }
+  }
+
+  if (passedResults.length > 0) {
+    console.log(chalk.green.bold("✓ PASSED VALIDATIONS"));
+    console.log(chalk.gray("─".repeat(50)));
+
+    for (const result of passedResults) {
+      console.log(chalk.green(`✓ ${result.rule}`));
+
+      if (verbose && result.context) {
+        console.log(chalk.gray(`  Target: ${result.context.target}`));
+        if (result.context.description) {
+          console.log(chalk.gray(`  Rule: ${result.context.description}`));
+        }
+
+        if (result.context.value && typeof result.context.value === "object") {
+          // Use regular string instead of template literal
+          console.log(chalk.gray("  Validated content:"));
+          const preview = JSON.stringify(result.context.value, null, 2)
+            .split("\n")
+            .slice(0, 5) // Show fewer lines for passed validations
+            .map((line) => `    ${line}`)
+            .join("\n");
+          console.log(chalk.gray(preview));
+          if (JSON.stringify(result.context.value).split("\n").length > 5) {
+            console.log(chalk.gray("    ... (content validated successfully)"));
+          }
+        }
+      }
+    }
+    console.log();
+  }
+
+  // Summary
+  const total = results.length;
+  const failed = failedResults.length;
+  const passed = passedResults.length;
+
+  if (failed > 0) {
+    console.log(
+      chalk.red.bold(
+        `Summary: ${failed}/${total} validations failed (${passed} passed)`,
+      ),
+    );
+  } else {
+    console.log(chalk.green.bold(`Summary: All ${total} validations passed`));
+  }
+}
+
+/**
+ * Formats validation results as JSON for programmatic consumption.
+ * Outputs a structured object with summary statistics and detailed results.
+ *
+ * @param results - Array of validation results to format
+ *
+ * @example
+ * ```typescript
+ * const results = [
+ *   { rule: "package.json", passed: true },
+ *   { rule: "biome.json", passed: false, message: "File not found" }
+ * ];
+ * formatJsonOutput(results);
+ * // Outputs: {
+ * //   "summary": { "total": 2, "passed": 1, "failed": 1 },
+ * //   "results": [...]
+ * // }
+ * ```
+ */
+function formatJsonOutput(results: ValidationResult[]): void {
+  const output = {
+    summary: {
+      total: results.length,
+      passed: results.filter((r) => r.passed).length,
+      failed: results.filter((r) => !r.passed).length,
+    },
+    results: results.map((result) => ({
+      rule: result.rule,
+      passed: result.passed,
+      ...(result.message && { message: result.message }),
+    })),
+  };
+
+  console.log(JSON.stringify(output, null, 2));
+}
+
+/**
+ * Displays available rulesets in a tree-like format.
+ * Groups rulesets by their location (bundled vs current directory).
+ */
+async function displayRulesetTree(): Promise<void> {
+  const { bundled, local } = await discoverAllRulesets();
+
+  if (bundled.length === 0 && local.length === 0) {
+    console.log(chalk.yellow("No rulesets found"));
+    return;
+  }
+
+  console.log(chalk.bold("\nAvailable Webarchitect Rulesets:"));
+  console.log(chalk.gray("─".repeat(50)));
+
+  // Display bundled rulesets
+  if (bundled.length > 0) {
+    console.log(chalk.cyan("Bundled Rulesets:"));
+    console.log(chalk.gray(`└── ${bundled[0].path.replace(/\/[^/]+$/, "")}/`));
+    for (let i = 0; i < bundled.length; i++) {
+      const isLast = i === bundled.length - 1;
+      const prefix = isLast ? "└──" : "├──";
+      const filename = `${bundled[i].name}.ruleset.json`;
+      console.log(
+        `    ${prefix} ${chalk.bold(bundled[i].name)} ${chalk.gray(`(${filename})`)}`,
+      );
+    }
+  }
+
+  // Display current directory rulesets
+  if (bundled.length > 0) console.log(); // Add spacing between sections
+  console.log(chalk.green("Current Directory:"));
+  console.log(chalk.gray(`└── ${process.cwd()}/`));
+  if (local.length > 0) {
+    for (let i = 0; i < local.length; i++) {
+      const isLast = i === local.length - 1;
+      const prefix = isLast ? "└──" : "├──";
+      const filename = `${local[i].name}.ruleset.json`;
+      console.log(
+        `    ${prefix} ${chalk.bold(local[i].name)} ${chalk.gray(`(${filename})`)}`,
+      );
+    }
+  } else {
+    console.log(chalk.gray(`    └── (no rulesets found at this path)`));
+  }
+}
+
+program
+  .name("webarchitect")
+  .argument("[ruleset]", "ruleset identifier, local path, or URL")
+  .option("-v, --verbose", "show all validation results")
+  .option("--json", "output results in JSON format")
+  .option("--list", "list all available rulesets")
+  .action(async (schemaArg, options) => {
+    // Handle --list option
+    if (options.list) {
+      await displayRulesetTree();
+      return;
+    }
+
+    // Require ruleset argument if not listing
+    if (!schemaArg) {
+      console.error(chalk.red("Error: Missing required argument 'ruleset'"));
+      console.error(
+        chalk.gray("Use 'webarchitect --list' to see available rulesets"),
+      );
+      process.exit(1);
+    }
+    try {
+      const results = await validate(process.cwd(), schemaArg);
+
+      if (options.json) {
+        formatJsonOutput(results);
+      } else {
+        formatTerminalOutput(results, options.verbose);
+
+        // Exit with error code if any validations failed
+        const hasFailures = results.some((r) => !r.passed);
+        if (hasFailures) {
+          process.exit(1);
+        }
+      }
+    } catch (e) {
+      if (options.json) {
+        console.log(
+          JSON.stringify(
+            {
+              error: (e as Error).message,
+              success: false,
+            },
+            null,
+            2,
+          ),
+        );
+      } else {
+        console.error(chalk.red(`Error: ${(e as Error).message}`));
+      }
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/constants.ts

@@ -0,0 +1,8 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+// Handle both source (src/) and built (dist/esm/) paths
+const srcPath = join(import.meta.dirname, "../rulesets");
+const distPath = join(import.meta.dirname, "../../rulesets");
+
+export const BUNDLED_RULESETS_DIR = existsSync(srcPath) ? srcPath : distPath;

package/{dist/esm/index.js → src/index.ts}

@@ -1,2 +1 @@
 export { default as validate } from "./validate.js";
-//# sourceMappingURL=index.js.map

package/{dist/esm/lib/ajv.js → src/lib/ajv.ts}

@@ -1,42 +1,66 @@
 import ajvPackage from "ajv";
 import draft202012 from "../schemas/draft-2020-12.json" with { type: "json" };
 import metaApplicator from "../schemas/meta/applicator.json" with {
-    type: "json"
+  type: "json",
 };
 import metaContent from "../schemas/meta/content.json" with { type: "json" };
 import metaCore from "../schemas/meta/core.json" with { type: "json" };
 import metaFormatAnnotation from "../schemas/meta/format-annotation.json" with {
-    type: "json"
+  type: "json",
 };
 import metaMetaData from "../schemas/meta/meta-data.json" with { type: "json" };
 import metaUnevaluated from "../schemas/meta/unevaluated.json" with {
-    type: "json"
+  type: "json",
 };
 import metaValidation from "../schemas/meta/validation.json" with {
-    type: "json"
+  type: "json",
 };
+
 const Ajv = ajvPackage.default;
+
 // Create AJV instance with configuration optimized for our use case
 const ajv = new Ajv({
-    strict: false, // Allow unknown keywords without throwing errors
-    allErrors: true, // Collect all validation errors, not just the first one
-    validateSchema: false, // Temporarily disable automatic schema validation during setup
+  strict: false, // Allow unknown keywords without throwing errors
+  allErrors: true, // Collect all validation errors, not just the first one
+  validateSchema: false, // Temporarily disable automatic schema validation during setup
 });
+
 // Step 1: Register all the foundational meta-schemas first
 // These are the building blocks that the main Draft 2020-12 schema depends on
 ajv.addSchema(metaCore, "https://json-schema.org/draft/2020-12/meta/core");
-ajv.addSchema(metaApplicator, "https://json-schema.org/draft/2020-12/meta/applicator");
-ajv.addSchema(metaUnevaluated, "https://json-schema.org/draft/2020-12/meta/unevaluated");
-ajv.addSchema(metaValidation, "https://json-schema.org/draft/2020-12/meta/validation");
-ajv.addSchema(metaMetaData, "https://json-schema.org/draft/2020-12/meta/meta-data");
-ajv.addSchema(metaFormatAnnotation, "https://json-schema.org/draft/2020-12/meta/format-annotation");
-ajv.addSchema(metaContent, "https://json-schema.org/draft/2020-12/meta/content");
+ajv.addSchema(
+  metaApplicator,
+  "https://json-schema.org/draft/2020-12/meta/applicator",
+);
+ajv.addSchema(
+  metaUnevaluated,
+  "https://json-schema.org/draft/2020-12/meta/unevaluated",
+);
+ajv.addSchema(
+  metaValidation,
+  "https://json-schema.org/draft/2020-12/meta/validation",
+);
+ajv.addSchema(
+  metaMetaData,
+  "https://json-schema.org/draft/2020-12/meta/meta-data",
+);
+ajv.addSchema(
+  metaFormatAnnotation,
+  "https://json-schema.org/draft/2020-12/meta/format-annotation",
+);
+ajv.addSchema(
+  metaContent,
+  "https://json-schema.org/draft/2020-12/meta/content",
+);
+
 // Step 2: Now register the main Draft 2020-12 schema
 // This schema composes all the meta-schemas above into the complete specification
 ajv.addSchema(draft202012, "https://json-schema.org/draft/2020-12/schema");
 ajv.addSchema(draft202012, "http://json-schema.org/draft/2020-12/schema");
+
 // Step 3: Re-enable schema validation now that all pieces are in place
 ajv.opts.validateSchema = true;
+
 // Step 4: Add format validation support manually to avoid type issues
 // Instead of using ajv-formats, we'll add the most common formats we need
 ajv.addFormat("email", /^[^\s@]+@[^\s@]+\.[^\s@]+$/);
@@ -44,16 +68,15 @@ ajv.addFormat("uri", /^https?:\/\/[^\s]+$/);
 ajv.addFormat("uri-reference", /^[^\s]*$/);
 // Add regex format validation - validates that a string is a valid regular expression
 ajv.addFormat("regex", {
-    type: "string",
-    validate: (data) => {
-        try {
-            new RegExp(data);
-            return true;
-        }
-        catch {
-            return false;
-        }
-    },
+  type: "string",
+  validate: (data: string) => {
+    try {
+      new RegExp(data);
+      return true;
+    } catch {
+      return false;
+    }
+  },
 });
+
 export default ajv;
-//# sourceMappingURL=ajv.js.map