@unerr-ai/unerr 0.1.0 → 0.1.2

package/dist/__tests__/architecture-guard.test.js

@@ -0,0 +1,122 @@
+/**
+ * BA-3.4: Architecture Boundary Guard tests.
+ *
+ * Verifies:
+ *   - Cross-community imports blocked
+ *   - Type imports allowed (configurable)
+ *   - Override comment works
+ *   - Auto-bridge after 3+ overrides
+ *   - Non-edit tools ignored
+ *   - Non-relative imports ignored
+ */
+import { describe, expect, it } from "vitest";
+import { ArchitectureBoundaryGuard } from "../behaviors/architecture-guard.js";
+function makeCtx(overrides = {}) {
+    return {
+        toolName: "edit_file",
+        args: {},
+        sessionId: "test-session",
+        ...overrides,
+    };
+}
+describe("Architecture Boundary Guard (BA-3.1)", () => {
+    describe("Behavior Identity", () => {
+        it("has correct id, hooks, and default level", () => {
+            const guard = new ArchitectureBoundaryGuard();
+            expect(guard.id).toBe("architecture_boundary");
+            expect(guard.hooks).toContain("pre_tool_use");
+            expect(guard.defaultLevel).toBe("enforcement");
+        });
+    });
+    describe("Import Parsing", () => {
+        it("returns null for non-edit tools", async () => {
+            const guard = new ArchitectureBoundaryGuard();
+            const ctx = makeCtx({ toolName: "get_entity" });
+            expect(await guard.onPreToolUse(ctx)).toBeNull();
+        });
+        it("returns null for non-code files", async () => {
+            const guard = new ArchitectureBoundaryGuard();
+            const ctx = makeCtx({
+                args: {
+                    path: "README.md",
+                    content: "import { foo } from './bar'",
+                },
+            });
+            expect(await guard.onPreToolUse(ctx)).toBeNull();
+        });
+        it("returns null when no graph attached", async () => {
+            const guard = new ArchitectureBoundaryGuard();
+            const ctx = makeCtx({
+                filePath: "src/proxy/handler.ts",
+                args: {
+                    path: "src/proxy/handler.ts",
+                    content: `import { ShadowLedger } from '../../tracking/shadow-ledger'`,
+                },
+            });
+            expect(await guard.onPreToolUse(ctx)).toBeNull();
+        });
+        it("ignores non-relative imports (npm packages)", async () => {
+            const guard = new ArchitectureBoundaryGuard();
+            const ctx = makeCtx({
+                filePath: "src/proxy/handler.ts",
+                args: {
+                    path: "src/proxy/handler.ts",
+                    content: `import { Server } from "@modelcontextprotocol/sdk/server/index.js"`,
+                },
+            });
+            expect(await guard.onPreToolUse(ctx)).toBeNull();
+        });
+    });
+    describe("Type Import Allowance", () => {
+        it("allows type imports by default", () => {
+            const guard = new ArchitectureBoundaryGuard();
+            expect(guard.getSessionStats().typeImportsAllowed).toBe(0);
+        });
+        it("can disable type import allowance via config", () => {
+            const guard = new ArchitectureBoundaryGuard({ allowTypeImports: false });
+            expect(guard.enabled).toBe(true);
+        });
+    });
+    describe("Override Comment", () => {
+        it("records overrides from @unerr-allow comments", () => {
+            const guard = new ArchitectureBoundaryGuard();
+            const stats = guard.getSessionStats();
+            expect(stats.overridesRecorded).toBe(0);
+        });
+    });
+    describe("Auto-Bridge", () => {
+        it("starts with no auto-bridges", () => {
+            const guard = new ArchitectureBoundaryGuard();
+            expect(guard.getSessionStats().autoBridges).toBe(0);
+        });
+        it("bridge threshold is 3 by default", () => {
+            const guard = new ArchitectureBoundaryGuard();
+            expect(guard.getBridges().size).toBe(0);
+        });
+        it("accepts custom bridge threshold", () => {
+            const guard = new ArchitectureBoundaryGuard({ bridgeThreshold: 5 });
+            expect(guard.enabled).toBe(true);
+        });
+    });
+    describe("Session Stats", () => {
+        it("starts with clean stats", () => {
+            const guard = new ArchitectureBoundaryGuard();
+            const stats = guard.getSessionStats();
+            expect(stats.violationsBlocked).toBe(0);
+            expect(stats.typeImportsAllowed).toBe(0);
+            expect(stats.overridesRecorded).toBe(0);
+            expect(stats.autoBridges).toBe(0);
+        });
+    });
+    describe("Learning Loop", () => {
+        it("tracks feedback correctly", () => {
+            const guard = new ArchitectureBoundaryGuard();
+            guard.recordFeedback("accepted");
+            guard.recordFeedback("overridden");
+            const stats = guard.getLearningStats();
+            expect(stats.accepted).toBe(1);
+            expect(stats.overridden).toBe(1);
+            expect(stats.confidence).toBeCloseTo(0.5, 2);
+        });
+    });
+});

package/dist/__tests__/arg-validator.test.js

@@ -0,0 +1,205 @@
+/**
+ * Boundary validation tests — guard against the silent-failure regression
+ * where missing required params or aliased param names reached handlers,
+ * ran queries with undefined filters, and returned empty results agents
+ * mistook for "graph has no data".
+ */
+import { describe, expect, it } from "vitest";
+import { aliasAndValidate, normalizeArgAliases, validateRequiredArgs, } from "../proxy/arg-validator.js";
+const GET_REFERENCES_DEF = {
+    name: "get_references",
+    inputSchema: {
+        type: "object",
+        properties: {
+            key: { type: "string", description: "Entity key" },
+            entity_name: { type: "string", description: "Alias for key" },
+            direction: { type: "string" },
+            limit: { type: "number" },
+        },
+        required: ["key"],
+    },
+};
+const RECALL_FACTS_DEF = {
+    name: "recall_facts",
+    inputSchema: {
+        type: "object",
+        properties: {
+            scope: { type: "string", description: "Scope filter" },
+            fact_type: { type: "string" },
+        },
+        required: ["scope"],
+    },
+};
+const SEARCH_CODE_DEF = {
+    name: "search_code",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: { type: "string", description: "Search query" },
+            limit: { type: "number" },
+        },
+        required: ["query"],
+    },
+};
+const GET_PROJECT_STATS_DEF = {
+    name: "get_project_stats",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+const GET_IMPORTS_DEF = {
+    name: "get_imports",
+    inputSchema: {
+        type: "object",
+        properties: {
+            file_path: { type: "string", description: "File path" },
+        },
+        required: ["file_path"],
+    },
+};
+describe("normalizeArgAliases — entity_name / entity → key", () => {
+    it("rewrites entity_name to key when key is missing", () => {
+        const args = {
+            entity_name: "compressShellOutput",
+        };
+        normalizeArgAliases(GET_REFERENCES_DEF, args);
+        expect(args.key).toBe("compressShellOutput");
+    });
+    it("rewrites bare `entity` alias to key", () => {
+        const args = { entity: "QueryRouter" };
+        normalizeArgAliases(GET_REFERENCES_DEF, args);
+        expect(args.key).toBe("QueryRouter");
+    });
+    it("does NOT overwrite key when already present", () => {
+        const args = {
+            key: "canonical",
+            entity_name: "alias-loser",
+        };
+        normalizeArgAliases(GET_REFERENCES_DEF, args);
+        expect(args.key).toBe("canonical");
+    });
+    it("does NOT add key when tool schema doesn't declare key", () => {
+        const args = { entity_name: "foo" };
+        normalizeArgAliases(SEARCH_CODE_DEF, args);
+        expect(args.key).toBeUndefined();
+    });
+    it("treats empty-string key as missing for alias purposes", () => {
+        const args = {
+            key: "",
+            entity_name: "real-name",
+        };
+        normalizeArgAliases(GET_REFERENCES_DEF, args);
+        expect(args.key).toBe("real-name");
+    });
+    it("treats whitespace-only alias as absent (does NOT set key)", () => {
+        const args = { entity_name: "   " };
+        normalizeArgAliases(GET_REFERENCES_DEF, args);
+        expect(args.key).toBeUndefined();
+    });
+});
+describe("normalizeArgAliases — file / path → file_path", () => {
+    it("rewrites `file` alias to file_path", () => {
+        const args = { file: "src/foo.ts" };
+        normalizeArgAliases(GET_IMPORTS_DEF, args);
+        expect(args.file_path).toBe("src/foo.ts");
+    });
+    it("rewrites `path` alias to file_path", () => {
+        const args = { path: "src/bar.ts" };
+        normalizeArgAliases(GET_IMPORTS_DEF, args);
+        expect(args.file_path).toBe("src/bar.ts");
+    });
+});
+describe("validateRequiredArgs — missing fields fail loudly", () => {
+    it("returns failure when required key is missing", () => {
+        const failure = validateRequiredArgs(GET_REFERENCES_DEF, {
+            direction: "callers",
+        });
+        expect(failure).not.toBeNull();
+        expect(failure?.error).toContain("get_references");
+        expect(failure?.error).toContain("key");
+        expect(failure?.required).toEqual(["key"]);
+        expect(failure?.details).toContain("Entity key");
+    });
+    it("returns failure when required scope is missing (recall_facts)", () => {
+        const failure = validateRequiredArgs(RECALL_FACTS_DEF, { limit: 5 });
+        expect(failure).not.toBeNull();
+        expect(failure?.error).toContain("scope");
+        expect(failure?.required).toEqual(["scope"]);
+    });
+    it("returns failure when required field is empty string", () => {
+        const failure = validateRequiredArgs(RECALL_FACTS_DEF, { scope: "" });
+        expect(failure).not.toBeNull();
+        expect(failure?.required).toEqual(["scope"]);
+    });
+    it("returns failure when required field is whitespace only", () => {
+        const failure = validateRequiredArgs(RECALL_FACTS_DEF, { scope: "   " });
+        expect(failure).not.toBeNull();
+        expect(failure?.required).toEqual(["scope"]);
+    });
+    it("returns failure when required field is null", () => {
+        const failure = validateRequiredArgs(SEARCH_CODE_DEF, { query: null });
+        expect(failure).not.toBeNull();
+    });
+    it("returns null (success) when all required fields present", () => {
+        const failure = validateRequiredArgs(GET_REFERENCES_DEF, {
+            key: "compressShellOutput",
+        });
+        expect(failure).toBeNull();
+    });
+    it("returns null for tools with no required fields", () => {
+        const failure = validateRequiredArgs(GET_PROJECT_STATS_DEF, {});
+        expect(failure).toBeNull();
+    });
+    it("lists multiple missing fields when several are absent", () => {
+        const def = {
+            name: "test_tool",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    a: { type: "string", description: "first" },
+                    b: { type: "string", description: "second" },
+                    c: { type: "string", description: "third" },
+                },
+                required: ["a", "b", "c"],
+            },
+        };
+        const failure = validateRequiredArgs(def, { a: "x" });
+        expect(failure?.required).toEqual(["b", "c"]);
+    });
+});
+describe("aliasAndValidate — composed boundary check", () => {
+    it("passes when entity_name supplies the canonical key", () => {
+        const args = {
+            entity_name: "compressShellOutput",
+        };
+        const failure = aliasAndValidate(GET_REFERENCES_DEF, args);
+        expect(failure).toBeNull();
+        expect(args.key).toBe("compressShellOutput");
+    });
+    it("fails when neither key nor any alias is set", () => {
+        const args = { direction: "callers" };
+        const failure = aliasAndValidate(GET_REFERENCES_DEF, args);
+        expect(failure).not.toBeNull();
+        expect(failure?.required).toEqual(["key"]);
+    });
+    it("reproduces the recall_facts({}) silent-failure case as a hard error", () => {
+        const args = {};
+        const failure = aliasAndValidate(RECALL_FACTS_DEF, args);
+        expect(failure).not.toBeNull();
+        expect(failure?.error).toMatch(/recall_facts.*scope/);
+        expect(failure?.details).toContain("Scope filter");
+    });
+    it("reproduces the get_references({entity_name:...}) silent-failure case as a pass", () => {
+        // Before the fix: entity_name was ignored, args.key was undefined,
+        // resolveKeyArg returned undefined, getCallersOf(undefined) returned
+        // []. After the fix: alias is rewritten, validation passes.
+        const args = {
+            entity_name: "compressShellOutput",
+            direction: "callers",
+        };
+        const failure = aliasAndValidate(GET_REFERENCES_DEF, args);
+        expect(failure).toBeNull();
+        expect(args.key).toBe("compressShellOutput");
+    });
+});

package/dist/__tests__/ast-extractor.test.js

@@ -0,0 +1,203 @@
+/**
+ * P10-TEST-03: AST extractor tests — entity extraction from source files.
+ */
+import { describe, expect, it } from "vitest";
+import { detectLanguage, entityKey, extractEntities, } from "../intelligence/ast-extractor.js";
+// ── Language Detection ──────────────────────────────────────────
+describe("detectLanguage", () => {
+    it("detects TypeScript files", () => {
+        expect(detectLanguage("src/index.ts")).toBe("typescript");
+        expect(detectLanguage("components/Button.tsx")).toBe("typescript");
+    });
+    it("detects JavaScript files", () => {
+        expect(detectLanguage("index.js")).toBe("javascript");
+        expect(detectLanguage("config.mjs")).toBe("javascript");
+        expect(detectLanguage("server.cjs")).toBe("javascript");
+    });
+    it("detects Python files", () => {
+        expect(detectLanguage("main.py")).toBe("python");
+    });
+    it("detects Go files", () => {
+        expect(detectLanguage("main.go")).toBe("go");
+    });
+    it("detects Java files", () => {
+        expect(detectLanguage("App.java")).toBe("java");
+    });
+    it("detects Rust files", () => {
+        expect(detectLanguage("main.rs")).toBe("rust");
+    });
+    it("detects C/C++ files", () => {
+        expect(detectLanguage("main.c")).toBe("c");
+        expect(detectLanguage("main.h")).toBe("c");
+        expect(detectLanguage("main.cpp")).toBe("cpp");
+        expect(detectLanguage("main.hpp")).toBe("cpp");
+    });
+    it("returns null for unsupported languages", () => {
+        expect(detectLanguage("data.json")).toBeNull();
+        expect(detectLanguage("style.css")).toBeNull();
+        expect(detectLanguage("readme.md")).toBeNull();
+        expect(detectLanguage("Makefile")).toBeNull();
+    });
+});
+// ── TypeScript/JavaScript Extraction ────────────────────────────
+describe("extractEntities — TypeScript", () => {
+    it("extracts exported functions", () => {
+        const code = `export function processPayment(amount: number): boolean {
+  if (amount <= 0) return false
+  return true
+}`;
+        const entities = extractEntities(code, "src/billing.ts");
+        expect(entities).toHaveLength(1);
+        expect(entities[0]?.name).toBe("processPayment");
+        expect(entities[0]?.kind).toBe("function");
+        expect(entities[0]?.signature).toBe("(amount: number)");
+        expect(entities[0]?.line_start).toBe(1);
+        expect(entities[0]?.line_end).toBe(4);
+    });
+    it("extracts async functions", () => {
+        const code = `export async function fetchData(url: string) {
+  return await fetch(url)
+}`;
+        const entities = extractEntities(code, "src/api.ts");
+        expect(entities).toHaveLength(1);
+        expect(entities[0]?.name).toBe("fetchData");
+        expect(entities[0]?.kind).toBe("function");
+    });
+    it("extracts classes", () => {
+        const code = `export class UserService {
+  private db: Database
+
+  getUser(id: string) {
+    return this.db.find(id)
+  }
+}`;
+        const entities = extractEntities(code, "src/user.ts");
+        expect(entities.length).toBeGreaterThanOrEqual(1);
+        const classEntity = entities.find((e) => e.kind === "class");
+        expect(classEntity).toBeDefined();
+        expect(classEntity?.name).toBe("UserService");
+    });
+    it("extracts interfaces", () => {
+        const code = `export interface ApiResponse {
+  data: unknown
+  error?: string
+}`;
+        const entities = extractEntities(code, "src/types.ts");
+        expect(entities).toHaveLength(1);
+        expect(entities[0]?.name).toBe("ApiResponse");
+        expect(entities[0]?.kind).toBe("interface");
+    });
+    it("extracts arrow functions assigned to const", () => {
+        const code = `export const validate = (input: string) => {
+  return input.length > 0
+}`;
+        const entities = extractEntities(code, "src/validate.ts");
+        expect(entities).toHaveLength(1);
+        expect(entities[0]?.name).toBe("validate");
+        expect(entities[0]?.kind).toBe("function");
+    });
+    it("generates content hash for each entity", () => {
+        const code = `function hello() {
+  console.log("hello")
+}`;
+        const entities = extractEntities(code, "src/greet.ts");
+        expect(entities).toHaveLength(1);
+        expect(entities[0]?.content_hash).toBeDefined();
+        expect(entities[0]?.content_hash.length).toBe(16);
+    });
+    it("different content produces different hashes", () => {
+        const code1 = `function hello() {
+  console.log("hello")
+}`;
+        const code2 = `function hello() {
+  console.log("goodbye")
+}`;
+        const e1 = extractEntities(code1, "a.ts");
+        const e2 = extractEntities(code2, "a.ts");
+        expect(e1[0]?.content_hash).not.toBe(e2[0]?.content_hash);
+    });
+});
+// ── Python Extraction ───────────────────────────────────────────
+describe("extractEntities — Python", () => {
+    it("extracts functions and classes", () => {
+        const code = `def process(data):
+    return data.strip()
+
+class DataProcessor:
+    def run(self):
+        pass
+`;
+        const entities = extractEntities(code, "main.py");
+        expect(entities.length).toBeGreaterThanOrEqual(2);
+        const fn = entities.find((e) => e.name === "process");
+        expect(fn).toBeDefined();
+        expect(fn?.kind).toBe("function");
+        const cls = entities.find((e) => e.name === "DataProcessor");
+        expect(cls).toBeDefined();
+        expect(cls?.kind).toBe("class");
+    });
+});
+// ── Go Extraction ───────────────────────────────────────────────
+describe("extractEntities — Go", () => {
+    it("extracts functions and methods", () => {
+        const code = `func main() {
+	fmt.Println("hello")
+}
+
+func (s *Server) Start(port int) error {
+	return s.listen(port)
+}
+
+type Server struct {
+	port int
+}
+`;
+        const entities = extractEntities(code, "main.go");
+        const fn = entities.find((e) => e.name === "main");
+        expect(fn).toBeDefined();
+        expect(fn?.kind).toBe("function");
+        const method = entities.find((e) => e.name === "Start");
+        expect(method).toBeDefined();
+        expect(method?.kind).toBe("method");
+        const cls = entities.find((e) => e.name === "Server");
+        expect(cls).toBeDefined();
+        expect(cls?.kind).toBe("class");
+    });
+});
+// ── Unsupported Languages ───────────────────────────────────────
+describe("extractEntities — unsupported", () => {
+    it("returns empty array for JSON files", () => {
+        expect(extractEntities('{"key": "value"}', "config.json")).toEqual([]);
+    });
+    it("returns empty array for CSS files", () => {
+        expect(extractEntities(".class { color: red; }", "style.css")).toEqual([]);
+    });
+    it("never throws for any input", () => {
+        expect(() => extractEntities("", "test.ts")).not.toThrow();
+        expect(() => extractEntities("random garbage !@#$%", "test.py")).not.toThrow();
+        expect(() => extractEntities("{{{}", "test.go")).not.toThrow();
+    });
+});
+// ── Entity Key Hashing ──────────────────────────────────────────
+describe("entityKey", () => {
+    it("produces 16-char hex string", () => {
+        const key = entityKey("repo1", "src/index.ts", "function", "main");
+        expect(key).toHaveLength(16);
+        expect(/^[a-f0-9]+$/.test(key)).toBe(true);
+    });
+    it("is deterministic", () => {
+        const a = entityKey("repo1", "src/index.ts", "function", "main");
+        const b = entityKey("repo1", "src/index.ts", "function", "main");
+        expect(a).toBe(b);
+    });
+    it("different inputs produce different keys", () => {
+        const a = entityKey("repo1", "src/a.ts", "function", "foo");
+        const b = entityKey("repo1", "src/b.ts", "function", "foo");
+        expect(a).not.toBe(b);
+    });
+    it("includes signature in hash when provided", () => {
+        const a = entityKey("repo1", "src/a.ts", "function", "foo", "(x: number)");
+        const b = entityKey("repo1", "src/a.ts", "function", "foo", "(x: string)");
+        expect(a).not.toBe(b);
+    });
+});