@canonical/webarchitect 0.26.0 → 0.27.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/webarchitect",
   "description": "A tool to test the compliance with architecture specifications for packages and applications.",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "type": "module",
   "module": "src/index.ts",
   "types": "src/index.ts",
@@ -33,21 +33,22 @@
     "check:biome": "biome check",
     "check:biome:fix": "biome check --write",
     "check:ts": "tsc --noEmit",
-    "test": "echo 'No tests defined yet'",
+    "test": "vitest run",
     "check:webarchitect": "bun run src/cli.ts tool-ts"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.9",
-    "@canonical/biome-config": "^0.26.0",
-    "@canonical/typescript-config": "^0.26.0",
+    "@canonical/biome-config": "^0.27.0",
+    "@canonical/typescript-config": "^0.27.0",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^24.12.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "dependencies": {
     "ajv": "^8.18.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.3"
   },
-  "gitHead": "55fece1380dba8dcd3a88af443dd509d9aaaccb2"
+  "gitHead": "5df5709bf7cb6f2016be2f6eba8391637e2e2a0c"
 }

package/src/constants.test.ts

@@ -0,0 +1,40 @@
+import { readdir } from "node:fs/promises";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { BUNDLED_RULESETS_DIR } from "./constants.js";
+
+describe("constants", () => {
+  beforeEach(() => {
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    vi.doUnmock("node:fs");
+  });
+
+  it("resolves to srcPath when srcPath exists", async () => {
+    vi.doMock("node:fs", () => ({
+      existsSync: vi.fn().mockReturnValue(true),
+    }));
+    const { BUNDLED_RULESETS_DIR: dir } = await import("./constants.js");
+    // srcPath is join(dirname, "../rulesets") — one level up
+    expect(dir).toMatch(/rulesets$/);
+    expect(dir).toBe(BUNDLED_RULESETS_DIR);
+  });
+
+  it("resolves to distPath when srcPath does not exist", async () => {
+    vi.doMock("node:fs", () => ({
+      existsSync: vi.fn().mockReturnValue(false),
+    }));
+    const { BUNDLED_RULESETS_DIR: dir } = await import("./constants.js");
+    // distPath is join(dirname, "../../rulesets") — two levels up, different from srcPath
+    expect(dir).toMatch(/rulesets$/);
+    expect(dir).not.toBe(BUNDLED_RULESETS_DIR);
+  });
+
+  it("resolved directory contains bundled ruleset files", async () => {
+    const files = await readdir(BUNDLED_RULESETS_DIR);
+    const rulesets = files.filter((f) => f.endsWith(".ruleset.json"));
+    expect(rulesets.length).toBeGreaterThan(0);
+    expect(rulesets).toContain("base.ruleset.json");
+  });
+});

package/src/lib/ajv.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import ajv from "./ajv.js";
+
+describe("ajv", () => {
+  it("validates regex format with valid regex", () => {
+    const validate = ajv.compile({
+      type: "string",
+      format: "regex",
+    });
+    expect(validate("^foo$")).toBe(true);
+  });
+
+  it("rejects invalid regex", () => {
+    const validate = ajv.compile({
+      type: "string",
+      format: "regex",
+    });
+    expect(validate("[invalid")).toBe(false);
+  });
+
+  it("validates email format", () => {
+    const validate = ajv.compile({
+      type: "string",
+      format: "email",
+    });
+    expect(validate("test@example.com")).toBe(true);
+    expect(validate("notanemail")).toBe(false);
+  });
+
+  it("validates uri format", () => {
+    const validate = ajv.compile({
+      type: "string",
+      format: "uri",
+    });
+    expect(validate("https://example.com")).toBe(true);
+  });
+});

package/src/lib/describeSchema.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import describeSchema from "./describeSchema.js";
+
+describe("describeSchema", () => {
+  it("returns type description for string type", () => {
+    expect(describeSchema({ type: "object" })).toBe("must be object");
+  });
+
+  it("returns type description for array type", () => {
+    expect(describeSchema({ type: ["string", "number"] })).toBe(
+      "must be one of: string, number",
+    );
+  });
+
+  it("returns const description", () => {
+    expect(describeSchema({ const: "module" })).toBe('must equal "module"');
+  });
+
+  it("returns pattern description", () => {
+    expect(describeSchema({ pattern: "^@canonical/" })).toBe(
+      "must match pattern /^@canonical//",
+    );
+  });
+
+  it("returns required properties description", () => {
+    expect(describeSchema({ required: ["name", "version"] })).toBe(
+      "must have properties: name, version",
+    );
+  });
+
+  it("returns properties description for <=3 properties", () => {
+    expect(
+      describeSchema({
+        properties: { name: {}, version: {} },
+      }),
+    ).toBe("expected properties: name, version");
+  });
+
+  it("returns count for >3 properties", () => {
+    expect(
+      describeSchema({
+        properties: { a: {}, b: {}, c: {}, d: {} },
+      }),
+    ).toBe("validates 4 properties");
+  });
+
+  it("ignores non-string non-array type", () => {
+    // type as a non-standard value (neither string nor array) — falls through both if/else-if
+    expect(describeSchema({ type: 42 } as any)).toBe(
+      "validates file content structure",
+    );
+  });
+
+  it("returns default description for empty schema", () => {
+    expect(describeSchema({})).toBe("validates file content structure");
+  });
+
+  it("combines multiple descriptions", () => {
+    const result = describeSchema({
+      type: "object",
+      required: ["name"],
+      properties: { name: {} },
+    });
+    expect(result).toBe(
+      "must be object, must have properties: name, expected properties: name",
+    );
+  });
+});

package/src/lib/discoverAllRulesets.test.ts

@@ -0,0 +1,35 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import discoverAllRulesets from "./discoverAllRulesets.js";
+
+describe("discoverAllRulesets", () => {
+  it("finds bundled rulesets including 'base'", async () => {
+    const result = await discoverAllRulesets();
+    expect(result.bundled.length).toBeGreaterThan(0);
+    expect(result.bundled.some((r) => r.name === "base")).toBe(true);
+    expect(result.bundled.every((r) => r.type === "bundled")).toBe(true);
+    expect(result.bundled.every((r) => r.path.endsWith(".ruleset.json"))).toBe(
+      true,
+    );
+  });
+
+  it("discovers local rulesets from current working directory", async () => {
+    const tmp = join(tmpdir(), `webarchitect-discover-all-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(
+      join(tmp, "custom.ruleset.json"),
+      JSON.stringify({ name: "custom" }),
+    );
+    const cwdSpy = vi.spyOn(process, "cwd").mockReturnValue(tmp);
+    try {
+      const result = await discoverAllRulesets();
+      expect(result.local.some((r) => r.name === "custom")).toBe(true);
+      expect(result.local.find((r) => r.name === "custom")?.type).toBe("local");
+    } finally {
+      cwdSpy.mockRestore();
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/src/lib/discoverRulesetsInDir.test.ts

@@ -0,0 +1,61 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import discoverRulesetsInDir from "./discoverRulesetsInDir.js";
+
+describe("discoverRulesetsInDir", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-discover-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("discovers .ruleset.json files as bundled", async () => {
+    writeFileSync(
+      join(tmp, "test.ruleset.json"),
+      JSON.stringify({ name: "test" }),
+    );
+    const results = await discoverRulesetsInDir(tmp, "bundled");
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe("test");
+    expect(results[0].type).toBe("bundled");
+    expect(results[0].path).toBe(join(tmp, "test.ruleset.json"));
+  });
+
+  it("discovers local rulesets with JSON validation", async () => {
+    writeFileSync(
+      join(tmp, "valid.ruleset.json"),
+      JSON.stringify({ name: "valid" }),
+    );
+    writeFileSync(join(tmp, "invalid.ruleset.json"), "not json{");
+    const results = await discoverRulesetsInDir(tmp, "local");
+    expect(results).toHaveLength(1);
+    expect(results[0].name).toBe("valid");
+  });
+
+  it("skips non-ruleset files", async () => {
+    writeFileSync(join(tmp, "readme.md"), "# docs");
+    writeFileSync(join(tmp, "config.json"), "{}");
+    const results = await discoverRulesetsInDir(tmp, "bundled");
+    expect(results).toEqual([]);
+  });
+
+  it("returns empty array for non-existent directory", async () => {
+    const results = await discoverRulesetsInDir(
+      join(tmp, "nonexistent"),
+      "bundled",
+    );
+    expect(results).toEqual([]);
+  });
+
+  it("returns empty array for empty directory", async () => {
+    const results = await discoverRulesetsInDir(tmp, "bundled");
+    expect(results).toEqual([]);
+  });
+});

package/src/lib/executeValidationRules.test.ts

@@ -0,0 +1,88 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { Schema } from "../types.js";
+import executeValidationRules from "./executeValidationRules.js";
+
+describe("executeValidationRules", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-exec-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("skips meta-properties ($schema, name, extends)", async () => {
+    const schema: Schema = {
+      $schema: "http://example.com",
+      name: "test-schema",
+      extends: ["base"],
+    };
+    const results = await executeValidationRules(tmp, schema);
+    expect(results).toEqual([]);
+  });
+
+  it("skips non-rule values", async () => {
+    const schema = {
+      name: "test",
+      notARule: "string-value",
+      alsoNotARule: 42,
+    } as unknown as Schema;
+    const results = await executeValidationRules(tmp, schema);
+    expect(results).toEqual([]);
+  });
+
+  it("executes file rules", async () => {
+    writeFileSync(join(tmp, "pkg.json"), JSON.stringify({ name: "x" }));
+    const schema: Schema = {
+      name: "test",
+      "pkg-check": {
+        file: {
+          name: "pkg.json",
+          contains: {
+            type: "object",
+            required: ["name"],
+            properties: { name: { type: "string" } },
+          },
+        },
+      },
+    };
+    const results = await executeValidationRules(tmp, schema);
+    expect(results).toHaveLength(1);
+    expect(results[0].passed).toBe(true);
+    expect(results[0].rule).toBe("pkg-check");
+  });
+
+  it("executes multiple rules in parallel", async () => {
+    writeFileSync(join(tmp, "a.json"), JSON.stringify({ v: 1 }));
+    writeFileSync(join(tmp, "b.json"), JSON.stringify({ v: 2 }));
+    const schema: Schema = {
+      name: "multi",
+      "rule-a": { file: { name: "a.json", contains: { type: "object" } } },
+      "rule-b": { file: { name: "b.json", contains: { type: "object" } } },
+    };
+    const results = await executeValidationRules(tmp, schema);
+    expect(results).toHaveLength(2);
+    expect(results.every((r) => r.passed)).toBe(true);
+  });
+
+  it("flattens nested results from directory rules", async () => {
+    mkdirSync(join(tmp, "src"));
+    writeFileSync(join(tmp, "src", "index.ts"), "");
+    const schema: Schema = {
+      name: "nested",
+      "src-structure": {
+        directory: { name: "src" },
+      },
+    };
+    const results = await executeValidationRules(tmp, schema);
+    expect(results).toHaveLength(1);
+    expect(results[0].rule).toBe("src-structure");
+    expect(results[0].passed).toBe(true);
+  });
+});

package/src/lib/listDirectory.test.ts

@@ -0,0 +1,42 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import listDirectory from "./listDirectory.js";
+
+describe("listDirectory", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-test-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("separates files and directories", async () => {
+    writeFileSync(join(tmp, "file.txt"), "");
+    mkdirSync(join(tmp, "subdir"));
+    const result = await listDirectory(tmp);
+    expect(result.files).toEqual(["file.txt"]);
+    expect(result.directories).toEqual(["subdir"]);
+  });
+
+  it("returns empty arrays for empty directory", async () => {
+    const result = await listDirectory(tmp);
+    expect(result.files).toEqual([]);
+    expect(result.directories).toEqual([]);
+  });
+
+  it("handles multiple entries", async () => {
+    writeFileSync(join(tmp, "a.json"), "");
+    writeFileSync(join(tmp, "b.txt"), "");
+    mkdirSync(join(tmp, "src"));
+    mkdirSync(join(tmp, "dist"));
+    const result = await listDirectory(tmp);
+    expect(result.files.sort()).toEqual(["a.json", "b.txt"]);
+    expect(result.directories.sort()).toEqual(["dist", "src"]);
+  });
+});

package/src/lib/loadFullSchema.test.ts

@@ -0,0 +1,137 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import loadFullSchema from "./loadFullSchema.js";
+
+describe("loadFullSchema", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-schema-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("loads a schema without extends", async () => {
+    const schema = {
+      name: "simple",
+      "my-rule": {
+        file: { name: "test.json", contains: { type: "object" } },
+      },
+    };
+    const schemaPath = join(tmp, "simple.ruleset.json");
+    writeFileSync(schemaPath, JSON.stringify(schema));
+
+    const result = await loadFullSchema(schemaPath);
+    expect(result.name).toBe("simple");
+    const rule = result["my-rule"] as { file: { name: string } };
+    expect(rule.file.name).toBe("test.json");
+  });
+
+  it("merges rules from extended schemas", async () => {
+    const baseSchema = {
+      name: "base",
+      "base-rule": {
+        file: { name: "base.json", contains: { type: "object" } },
+      },
+    };
+    const childSchema = {
+      name: "child",
+      extends: [join(tmp, "base.ruleset.json")],
+      "child-rule": {
+        file: { name: "child.json", contains: { type: "string" } },
+      },
+    };
+
+    writeFileSync(join(tmp, "base.ruleset.json"), JSON.stringify(baseSchema));
+    writeFileSync(join(tmp, "child.ruleset.json"), JSON.stringify(childSchema));
+
+    const result = await loadFullSchema(join(tmp, "child.ruleset.json"));
+    expect(result.name).toBe("child");
+    const base = result["base-rule"] as { file: { name: string } };
+    const child = result["child-rule"] as { file: { name: string } };
+    expect(base.file.name).toBe("base.json");
+    expect(child.file.name).toBe("child.json");
+  });
+
+  it("child rules override parent rules with same name", async () => {
+    const parent = {
+      name: "parent",
+      "shared-rule": {
+        file: { name: "parent.json", contains: { type: "string" } },
+      },
+    };
+    const child = {
+      name: "child",
+      extends: [join(tmp, "parent.ruleset.json")],
+      "shared-rule": {
+        file: { name: "child.json", contains: { type: "number" } },
+      },
+    };
+
+    writeFileSync(join(tmp, "parent.ruleset.json"), JSON.stringify(parent));
+    writeFileSync(join(tmp, "child.ruleset.json"), JSON.stringify(child));
+
+    const result = await loadFullSchema(join(tmp, "child.ruleset.json"));
+    const rule = result["shared-rule"] as { file: { name: string } };
+    expect(rule.file.name).toBe("child.json");
+  });
+
+  it("preserves $schema and name from child, strips extends", async () => {
+    const parent = {
+      $schema: "parent-schema",
+      name: "parent",
+    };
+    const child = {
+      $schema: "child-schema",
+      name: "child",
+      extends: [join(tmp, "parent.ruleset.json")],
+    };
+
+    writeFileSync(join(tmp, "parent.ruleset.json"), JSON.stringify(parent));
+    writeFileSync(join(tmp, "child.ruleset.json"), JSON.stringify(child));
+
+    const result = await loadFullSchema(join(tmp, "child.ruleset.json"));
+    expect(result.$schema).toBe("child-schema");
+    expect(result.name).toBe("child");
+    expect(result.extends).toBeUndefined();
+  });
+
+  it("handles multiple extends", async () => {
+    const base1 = {
+      name: "base1",
+      rule1: {
+        file: { name: "a.json", contains: { type: "object" } },
+      },
+    };
+    const base2 = {
+      name: "base2",
+      rule2: {
+        file: { name: "b.json", contains: { type: "object" } },
+      },
+    };
+    const child = {
+      name: "child",
+      extends: [
+        join(tmp, "base1.ruleset.json"),
+        join(tmp, "base2.ruleset.json"),
+      ],
+    };
+
+    writeFileSync(join(tmp, "base1.ruleset.json"), JSON.stringify(base1));
+    writeFileSync(join(tmp, "base2.ruleset.json"), JSON.stringify(base2));
+    writeFileSync(join(tmp, "child.ruleset.json"), JSON.stringify(child));
+
+    const result = await loadFullSchema(join(tmp, "child.ruleset.json"));
+    const r1 = result.rule1 as { file: { name: string } };
+    const r2 = result.rule2 as { file: { name: string } };
+    expect(r1.file.name).toBe("a.json");
+    expect(r2.file.name).toBe("b.json");
+  });
+});

package/src/lib/resolveSchema.test.ts

@@ -0,0 +1,135 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import resolveSchema from "./resolveSchema.js";
+
+describe("resolveSchema", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-resolve-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("loads schema from local .ruleset.json file", async () => {
+    const schema = { name: "test-local" };
+    const path = join(tmp, "local.ruleset.json");
+    writeFileSync(path, JSON.stringify(schema));
+    const result = await resolveSchema(path);
+    expect(result.name).toBe("test-local");
+  });
+
+  it("loads schema from local .json file", async () => {
+    const schema = { name: "test-json" };
+    const path = join(tmp, "local.json");
+    writeFileSync(path, JSON.stringify(schema));
+    const result = await resolveSchema(path);
+    expect(result.name).toBe("test-json");
+  });
+
+  it("appends .ruleset.json when no extension", async () => {
+    const schema = { name: "test-no-ext" };
+    writeFileSync(join(tmp, "myschema.ruleset.json"), JSON.stringify(schema));
+    const result = await resolveSchema(join(tmp, "myschema"));
+    expect(result.name).toBe("test-no-ext");
+  });
+
+  it("falls back to bundled rulesets", async () => {
+    const result = await resolveSchema("base");
+    expect(result.name).toBe("base");
+  });
+
+  it("throws when schema not found locally or bundled", async () => {
+    await expect(
+      resolveSchema("nonexistent-schema-that-does-not-exist"),
+    ).rejects.toThrow("Could not find ruleset");
+  });
+
+  it("throws when schema fails validation", async () => {
+    // Write a file that is valid JSON but not a valid schema
+    const path = join(tmp, "invalid.ruleset.json");
+    writeFileSync(path, JSON.stringify({ notAValidSchema: true }));
+    await expect(resolveSchema(path)).rejects.toThrow("Invalid ruleset");
+  });
+
+  it("loads schema from URL", async () => {
+    const schema = { name: "remote" };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        json: () => Promise.resolve(schema),
+      }),
+    );
+    const result = await resolveSchema("https://example.com/schema.json");
+    expect(result.name).toBe("remote");
+  });
+
+  it("loads schema from http URL", async () => {
+    const schema = { name: "http-remote" };
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        json: () => Promise.resolve(schema),
+      }),
+    );
+    const result = await resolveSchema("http://example.com/schema.json");
+    expect(result.name).toBe("http-remote");
+  });
+
+  it("error message includes available bundled rulesets", async () => {
+    await expect(resolveSchema("nonexistent-schema-xyz-abc")).rejects.toThrow(
+      /Could not find ruleset.*Available bundled rulesets/s,
+    );
+  });
+});
+
+describe("resolveSchema validation edge cases (mocked ajv)", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-resolve-edge-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    vi.resetModules();
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    vi.doUnmock("./ajv.js");
+    vi.restoreAllMocks();
+  });
+
+  it("uses fallback message when AJV error has no message", async () => {
+    const mockValidate = Object.assign(() => false, {
+      errors: [{ instancePath: "/bad", message: undefined }],
+    });
+    vi.doMock("./ajv.js", () => ({
+      default: { compile: vi.fn().mockReturnValue(mockValidate) },
+    }));
+    const schemaPath = join(tmp, "edge.ruleset.json");
+    writeFileSync(schemaPath, JSON.stringify({ name: "edge" }));
+    const { default: fn } = await import("./resolveSchema.js");
+    await expect(fn(schemaPath)).rejects.toThrow("validation failed");
+  });
+
+  it("handles null validateSchema.errors gracefully", async () => {
+    const mockValidate = Object.assign(() => false, {
+      errors: null,
+    });
+    vi.doMock("./ajv.js", () => ({
+      default: { compile: vi.fn().mockReturnValue(mockValidate) },
+    }));
+    const schemaPath = join(tmp, "null-errors.ruleset.json");
+    writeFileSync(schemaPath, JSON.stringify({ name: "null-errors" }));
+    const { default: fn } = await import("./resolveSchema.js");
+    await expect(fn(schemaPath)).rejects.toThrow("Invalid ruleset");
+  });
+});

package/src/lib/validateDirectoryRule.test.ts

@@ -0,0 +1,258 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type MockInstance,
+  vi,
+} from "vitest";
+import validateDirectoryRule from "./validateDirectoryRule.js";
+
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  return { ...actual, stat: vi.fn().mockImplementation(actual.stat) };
+});
+
+const mockStat = stat as unknown as MockInstance;
+
+describe("validateDirectoryRule", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-dir-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("passes when directory exists and has no rules", async () => {
+    mkdirSync(join(tmp, "src"));
+    const results = await validateDirectoryRule(
+      tmp,
+      { name: "src" },
+      "src-dir",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].rule).toBe("src-dir");
+    expect(results[0].passed).toBe(true);
+  });
+
+  it("soft-fails when directory not found", async () => {
+    const results = await validateDirectoryRule(
+      tmp,
+      { name: "missing" },
+      "missing-dir",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].passed).toBe(false);
+    expect(results[0].message).toContain("Directory not found");
+  });
+
+  it("soft-fails when path is a file instead of directory", async () => {
+    writeFileSync(join(tmp, "notadir"), "content");
+    const results = await validateDirectoryRule(
+      tmp,
+      { name: "notadir" },
+      "file-as-dir",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].passed).toBe(false);
+    expect(results[0].message).toContain("Expected directory but found file");
+  });
+
+  it("validates contained files", async () => {
+    mkdirSync(join(tmp, "pkg"));
+    writeFileSync(
+      join(tmp, "pkg", "package.json"),
+      JSON.stringify({ name: "test" }),
+    );
+    const results = await validateDirectoryRule(
+      tmp,
+      {
+        name: "pkg",
+        contains: {
+          files: [
+            {
+              name: "package.json",
+              contains: {
+                type: "object",
+                required: ["name"],
+                properties: { name: { type: "string" } },
+              },
+            },
+          ],
+        },
+      },
+      "pkg-dir",
+    );
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.every((r) => r.passed)).toBe(true);
+  });
+
+  it("validates contained subdirectories recursively", async () => {
+    mkdirSync(join(tmp, "root", "sub"), { recursive: true });
+    const results = await validateDirectoryRule(
+      tmp,
+      {
+        name: "root",
+        contains: {
+          directories: [{ name: "sub" }],
+        },
+      },
+      "recursive",
+    );
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.every((r) => r.passed)).toBe(true);
+  });
+
+  it("strict mode detects extra files", async () => {
+    mkdirSync(join(tmp, "strict"));
+    writeFileSync(join(tmp, "strict", "expected.json"), "{}");
+    writeFileSync(join(tmp, "strict", "extra.txt"), "");
+    const results = await validateDirectoryRule(
+      tmp,
+      {
+        name: "strict",
+        strict: true,
+        contains: {
+          files: [{ name: "expected.json", contains: { type: "object" } }],
+        },
+      },
+      "strict-dir",
+    );
+    const strictResult = results.find((r) =>
+      r.message?.includes("extra files"),
+    );
+    expect(strictResult).toBeDefined();
+    expect(strictResult?.passed).toBe(false);
+    expect(strictResult?.message).toContain("extra.txt");
+  });
+
+  it("strict mode detects extra directories", async () => {
+    mkdirSync(join(tmp, "strict2"));
+    mkdirSync(join(tmp, "strict2", "unexpected"));
+    const results = await validateDirectoryRule(
+      tmp,
+      {
+        name: "strict2",
+        strict: true,
+      },
+      "strict2-dir",
+    );
+    const strictResult = results.find((r) =>
+      r.message?.includes("extra directories"),
+    );
+    expect(strictResult).toBeDefined();
+    expect(strictResult?.passed).toBe(false);
+  });
+
+  it("strict mode detects both extra files and directories", async () => {
+    mkdirSync(join(tmp, "strict3"));
+    writeFileSync(join(tmp, "strict3", "extra.txt"), "");
+    mkdirSync(join(tmp, "strict3", "extradir"));
+    const results = await validateDirectoryRule(
+      tmp,
+      { name: "strict3", strict: true },
+      "strict3-dir",
+    );
+    const strictResult = results.find((r) =>
+      r.message?.includes("extra files"),
+    );
+    expect(strictResult).toBeDefined();
+    expect(strictResult?.message).toContain("extra directories");
+  });
+
+  it("strict mode passes when no extra entries", async () => {
+    mkdirSync(join(tmp, "clean"));
+    writeFileSync(join(tmp, "clean", "expected.json"), "{}");
+    const results = await validateDirectoryRule(
+      tmp,
+      {
+        name: "clean",
+        strict: true,
+        contains: {
+          files: [{ name: "expected.json", contains: { type: "object" } }],
+        },
+      },
+      "clean-dir",
+    );
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.every((r) => r.passed)).toBe(true);
+  });
+
+  it("strict mode with only extra dirs (no extra files)", async () => {
+    mkdirSync(join(tmp, "onlydirs"));
+    mkdirSync(join(tmp, "onlydirs", "extra"));
+    const results = await validateDirectoryRule(
+      tmp,
+      {
+        name: "onlydirs",
+        strict: true,
+        contains: {},
+      },
+      "onlydirs",
+    );
+    const strictResult = results.find((r) =>
+      r.message?.includes("extra directories"),
+    );
+    expect(strictResult).toBeDefined();
+    expect(strictResult?.message).not.toContain("extra files");
+  });
+
+  it("strict mode with expected directories passes", async () => {
+    mkdirSync(join(tmp, "withsub"));
+    mkdirSync(join(tmp, "withsub", "expected"));
+    const results = await validateDirectoryRule(
+      tmp,
+      {
+        name: "withsub",
+        strict: true,
+        contains: {
+          directories: [{ name: "expected" }],
+        },
+      },
+      "withsub-dir",
+    );
+    expect(results.length).toBeGreaterThan(0);
+    expect(results.every((r) => r.passed)).toBe(true);
+  });
+
+  it("includes context with directory type", async () => {
+    mkdirSync(join(tmp, "ctx"));
+    const results = await validateDirectoryRule(
+      tmp,
+      { name: "ctx" },
+      "ctx-dir",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].context?.type).toBe("directory");
+    expect(results[0].context?.target).toBe(join(tmp, "ctx"));
+  });
+});
+
+describe("validateDirectoryRule error paths", () => {
+  it("throws permission denied for EACCES on stat", async () => {
+    mockStat.mockRejectedValueOnce(
+      Object.assign(new Error("EACCES"), { code: "EACCES" }),
+    );
+    await expect(
+      validateDirectoryRule("/project", { name: "restricted" }, "perm"),
+    ).rejects.toThrow("Permission denied accessing directory");
+  });
+
+  it("throws generic error for unknown stat error", async () => {
+    mockStat.mockRejectedValueOnce(
+      Object.assign(new Error("Disk failure"), { code: "EIO" }),
+    );
+    await expect(
+      validateDirectoryRule("/project", { name: "broken" }, "io"),
+    ).rejects.toThrow("Error accessing directory");
+  });
+});

package/src/lib/validateDirectoryRule.ts

@@ -72,7 +72,6 @@ export default async function validateDirectoryRule(
       ];
     }
 
-    // Hard fail: permission denied, I/O errors, etc. with informative message
     const errorCode = (e as NodeJS.ErrnoException).code;
     const errorMessage =
       errorCode === "EACCES"

package/src/lib/validateFileRule.test.ts

@@ -0,0 +1,146 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  type MockInstance,
+  vi,
+} from "vitest";
+import validateFileRule from "./validateFileRule.js";
+
+vi.mock("node:fs/promises", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs/promises")>();
+  return { ...actual, readFile: vi.fn().mockImplementation(actual.readFile) };
+});
+
+const mockReadFile = readFile as unknown as MockInstance;
+
+describe("validateFileRule", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-file-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("passes when file matches schema", async () => {
+    writeFileSync(
+      join(tmp, "package.json"),
+      JSON.stringify({ name: "test", version: "1.0.0" }),
+    );
+    const results = await validateFileRule(
+      tmp,
+      {
+        name: "package.json",
+        contains: {
+          type: "object",
+          required: ["name"],
+          properties: { name: { type: "string" } },
+        },
+      },
+      "pkg",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].passed).toBe(true);
+  });
+
+  it("fails when file content violates schema", async () => {
+    writeFileSync(join(tmp, "config.json"), JSON.stringify({ name: 42 }));
+    const results = await validateFileRule(
+      tmp,
+      {
+        name: "config.json",
+        contains: {
+          type: "object",
+          properties: { name: { type: "string" } },
+        },
+      },
+      "cfg",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].passed).toBe(false);
+    expect(results[0].message).toContain("Validation failed");
+  });
+
+  it("soft-fails when file not found", async () => {
+    const results = await validateFileRule(
+      tmp,
+      { name: "missing.json", contains: { type: "object" } },
+      "missing",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].passed).toBe(false);
+    expect(results[0].message).toContain("File not found");
+  });
+
+  it("throws on invalid JSON", async () => {
+    writeFileSync(join(tmp, "bad.json"), "not json{");
+    await expect(
+      validateFileRule(
+        tmp,
+        { name: "bad.json", contains: { type: "object" } },
+        "bad",
+      ),
+    ).rejects.toThrow("Invalid JSON");
+  });
+
+  it("throws on directory instead of file", async () => {
+    mkdirSync(join(tmp, "adir"));
+    await expect(
+      validateFileRule(
+        tmp,
+        { name: "adir", contains: { type: "object" } },
+        "dir-as-file",
+      ),
+    ).rejects.toThrow("Expected file but found directory");
+  });
+
+  it("includes context in result", async () => {
+    writeFileSync(join(tmp, "data.json"), JSON.stringify({ ok: true }));
+    const results = await validateFileRule(
+      tmp,
+      { name: "data.json", contains: { type: "object" } },
+      "data",
+    );
+    expect(results[0].context?.type).toBe("file");
+    expect(results[0].context?.target).toBe(join(tmp, "data.json"));
+    expect(results[0].context?.value).toEqual({ ok: true });
+  });
+});
+
+describe("validateFileRule error paths", () => {
+  it("throws permission denied for EACCES", async () => {
+    mockReadFile.mockRejectedValueOnce(
+      Object.assign(new Error("EACCES"), { code: "EACCES" }),
+    );
+    await expect(
+      validateFileRule(
+        "/project",
+        { name: "secret.json", contains: { type: "object" } },
+        "perm",
+      ),
+    ).rejects.toThrow("Permission denied accessing");
+  });
+
+  it("throws generic error for unknown error code", async () => {
+    mockReadFile.mockRejectedValueOnce(
+      Object.assign(new Error("Disk failure"), { code: "EIO" }),
+    );
+    await expect(
+      validateFileRule(
+        "/project",
+        { name: "broken.json", contains: { type: "object" } },
+        "io",
+      ),
+    ).rejects.toThrow("Error reading file");
+  });
+});

package/src/lib/validateFileRule.ts

@@ -91,7 +91,6 @@ export default async function validateFileRule(
       ];
     }
 
-    // Hard fail: permission denied, I/O errors, etc. with informative message
     const errorCode = (readError as NodeJS.ErrnoException).code;
     const errorMessage =
       errorCode === "EACCES"

package/src/lib/validateRule.test.ts

@@ -0,0 +1,47 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import validateRule from "./validateRule.js";
+
+describe("validateRule", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-rule-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it("dispatches file rules to validateFileRule", async () => {
+    writeFileSync(join(tmp, "test.json"), JSON.stringify({ ok: true }));
+    const results = await validateRule(
+      tmp,
+      { file: { name: "test.json", contains: { type: "object" } } },
+      "file-rule",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].passed).toBe(true);
+  });
+
+  it("dispatches directory rules to validateDirectoryRule", async () => {
+    mkdirSync(join(tmp, "src"));
+    const results = await validateRule(
+      tmp,
+      { directory: { name: "src" } },
+      "dir-rule",
+    );
+    expect(results).toHaveLength(1);
+    expect(results[0].rule).toBe("dir-rule");
+    expect(results[0].passed).toBe(true);
+  });
+
+  it("throws for invalid rule type", async () => {
+    await expect(validateRule(tmp, {} as any, "bad-rule")).rejects.toThrow(
+      "Invalid rule type",
+    );
+  });
+});

package/src/validate.test.ts

@@ -0,0 +1,79 @@
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import validate from "./validate.js";
+
+describe("validate", () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = join(tmpdir(), `webarchitect-validate-${Date.now()}`);
+    mkdirSync(tmp, { recursive: true });
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("validates a project against a schema", async () => {
+    // Create a minimal project matching the base schema
+    writeFileSync(
+      join(tmp, "package.json"),
+      JSON.stringify({
+        name: "@canonical/test",
+        version: "1.0.0",
+        type: "module",
+        license: "LGPL-3.0",
+        scripts: {},
+        author: { name: "Test", email: "test@test.com" },
+        repository: { type: "git", url: "https://github.com/test/test" },
+      }),
+    );
+
+    // Create a minimal schema that checks for package.json
+    const schema = {
+      name: "test-schema",
+      "pkg-exists": {
+        file: {
+          name: "package.json",
+          contains: {
+            type: "object",
+            required: ["name"],
+            properties: { name: { type: "string" } },
+          },
+        },
+      },
+    };
+    const schemaPath = join(tmp, "test.ruleset.json");
+    writeFileSync(schemaPath, JSON.stringify(schema));
+
+    const results = await validate(tmp, schemaPath);
+    expect(results).toHaveLength(1);
+    expect(results[0].rule).toBe("pkg-exists");
+    expect(results[0].passed).toBe(true);
+  });
+
+  it("returns failure results for invalid project", async () => {
+    // Empty project with no package.json
+    const schema = {
+      name: "test-schema",
+      "pkg-check": {
+        file: {
+          name: "package.json",
+          contains: { type: "object" },
+        },
+      },
+    };
+    const schemaPath = join(tmp, "test.ruleset.json");
+    writeFileSync(schemaPath, JSON.stringify(schema));
+
+    const results = await validate(tmp, schemaPath);
+    expect(results).toHaveLength(1);
+    expect(results[0].rule).toBe("pkg-check");
+    expect(results[0].passed).toBe(false);
+    expect(results[0].message).toContain("File not found");
+  });
+});