@canonical/webarchitect 0.10.0 → 0.12.0-experimental.0

package/README.md

@@ -1,22 +1,47 @@
 # Webarchitect
 
-A powerful command-line tool for validating project architecture and configuration consistency across development teams and organizations.
+Validates project architecture and configuration against rulesets. Run it to ensure packages follow organizational standards.
 
-## What is this tool for?
+```bash
+webarchitect library
+```
+
+## Built-in Rulesets
+
+Pragma uses three rulesets:
+
+| Ruleset | License | Use Case |
+|---------|---------|----------|
+| `library` | LGPL-3.0 | Packages consumed by other packages or applications |
+| `tool` | GPL-3.0 | Compiled CLI tools with a build step |
+| `tool-ts` | GPL-3.0 | TypeScript tools that run directly with Bun (no build) |
 
-Webarchitect helps development teams maintain consistent project structures and configuration standards. Think of it as a quality gate that ensures every project in your organization follows the same architectural patterns, uses the same build tools, and maintains the same configuration standards.
+Each ruleset validates package.json structure, required scripts, TypeScript configuration, Biome setup, and license compliance.
 
-### The Problem It Solves
+## Quick Example
 
-In large organizations with multiple development teams, projects tend to drift from established standards over time. One team might use different TypeScript configurations, another might have inconsistent package.json structures, and a third might be missing essential development scripts. This inconsistency creates several problems: developers waste time figuring out how each project works, code quality varies between teams, and maintaining projects becomes more difficult as each one follows slightly different patterns.
+A library package includes this in its check script:
+
+```json
+{
+  "scripts": {
+    "check:webarchitect": "webarchitect library"
+  }
+}
+```
 
-Webarchitect addresses this challenge by providing automated validation of project architecture. Instead of relying on documentation that might become outdated or manual code reviews that might miss configuration details, you can define your organization's standards as executable rulesets and validate projects automatically.
+Running `bun run check:webarchitect` validates that the package has correct exports, required fields, and LGPL-3.0 license.
 
-### How It Works
+## What It Validates
 
-The tool operates on the concept of "rulesets" - JSON Schema-based definitions that describe what files should exist in a project and what those files should contain. For example, a ruleset might specify that every package must have a `package.json` file with specific required fields, a `biome.json` file that extends your organization's linting configuration, and a TypeScript configuration that follows your team's standards.
+Webarchitect checks that:
+- `package.json` has required fields (name, version, type, module, types, exports)
+- `biome.json` extends `@canonical/biome-config`
+- `tsconfig.json` exists with proper configuration
+- License matches the ruleset requirement
+- Required scripts exist (build, check, test)
 
-When you run webarchitect against a project, it loads the specified ruleset, checks whether the required files exist, and validates that their contents match the expected structure and values. This approach gives you confidence that projects follow your established patterns without requiring manual inspection.
+When validation fails, you get specific error messages explaining what's wrong and what's expected.
 
 ## How to install and run?
 
@@ -249,3 +274,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.12.0-experimental.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": "0e56eee8b9ff804c676811e1fe55e2716d11db5b"
 }

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