@stackweld/core 0.2.0

package/dist/types/project.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Project Instance — A stack materialized on disk.
+ * Created by the Scaffold Orchestrator.
+ */
+export interface ProjectInstance {
+  id: string;
+  stackId: string;
+  name: string;
+  path: string;
+  createdAt: string;
+  lastOpenedAt?: string;
+  templateId?: string;
+}
+/**
+ * Runtime State — Live state of a running project.
+ * Containers, ports, health checks, processes.
+ */
+export interface ServiceStatus {
+  name: string;
+  technologyId: string;
+  containerId?: string;
+  status: "running" | "healthy" | "unhealthy" | "exited" | "stopped" | "not_started";
+  port?: number;
+  healthCheck?: "passing" | "failing" | "none";
+  uptime?: number;
+}
+export interface RuntimeState {
+  projectId: string;
+  services: ServiceStatus[];
+  composePath?: string;
+  lastChecked: string;
+}
+//# sourceMappingURL=project.d.ts.map

package/dist/types/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/types/project.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AAEH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,CAAC;IACnF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/types/project.js

@@ -0,0 +1,6 @@
+/**
+ * Project Instance — A stack materialized on disk.
+ * Created by the Scaffold Orchestrator.
+ */
+export {};
+//# sourceMappingURL=project.js.map

package/dist/types/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/types/project.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/stack.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Stack Definition — Abstract definition of a development stack.
+ * Not yet a project on disk.
+ */
+export interface StackTechnology {
+  technologyId: string;
+  version: string;
+  port?: number;
+  config?: Record<string, unknown>;
+}
+export type StackProfile = "rapid" | "standard" | "production" | "enterprise" | "lightweight";
+export interface StackDefinition {
+  id: string;
+  name: string;
+  description: string;
+  profile: StackProfile;
+  technologies: StackTechnology[];
+  createdAt: string;
+  updatedAt: string;
+  version: number;
+  tags: string[];
+}
+export interface StackVersion {
+  version: number;
+  timestamp: string;
+  changelog: string;
+  snapshot: StackDefinition;
+}
+//# sourceMappingURL=stack.d.ts.map

package/dist/types/stack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.d.ts","sourceRoot":"","sources":["../../src/types/stack.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,CAAC;AAE9F,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,YAAY,CAAC;IACtB,YAAY,EAAE,eAAe,EAAE,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,eAAe,CAAC;CAC3B"}

package/dist/types/stack.js

@@ -0,0 +1,6 @@
+/**
+ * Stack Definition — Abstract definition of a development stack.
+ * Not yet a project on disk.
+ */
+export {};
+//# sourceMappingURL=stack.js.map

package/dist/types/stack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack.js","sourceRoot":"","sources":["../../src/types/stack.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/technology.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Technology — Atomic unit of the registry catalog.
+ * Each technology is deeply modeled with versions, ports, rules, and metadata.
+ */
+export type TechnologyCategory =
+  | "runtime"
+  | "frontend"
+  | "backend"
+  | "database"
+  | "orm"
+  | "auth"
+  | "styling"
+  | "service"
+  | "devops";
+export interface TechnologyVersion {
+  version: string;
+  eol?: string;
+  lts?: boolean;
+}
+export interface HealthCheckConfig {
+  command?: string;
+  endpoint?: string;
+  interval?: string;
+  timeout?: string;
+  retries?: number;
+}
+export interface Technology {
+  id: string;
+  name: string;
+  category: TechnologyCategory;
+  description: string;
+  website: string;
+  versions: TechnologyVersion[];
+  defaultVersion: string;
+  defaultPort?: number;
+  requires: string[];
+  incompatibleWith: string[];
+  suggestedWith: string[];
+  officialScaffold?: string;
+  dockerImage?: string;
+  healthCheck?: HealthCheckConfig;
+  envVars: Record<string, string>;
+  configFiles: string[];
+  lastVerified: string;
+  tags: string[];
+}
+//# sourceMappingURL=technology.d.ts.map

package/dist/types/technology.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"technology.d.ts","sourceRoot":"","sources":["../../src/types/technology.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,UAAU,GACV,SAAS,GACT,UAAU,GACV,KAAK,GACL,MAAM,GACN,SAAS,GACT,SAAS,GACT,QAAQ,CAAC;AAEb,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,aAAa,EAAE,MAAM,EAAE,CAAC;IAGxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAGhC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,WAAW,EAAE,MAAM,EAAE,CAAC;IAGtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB"}

package/dist/types/technology.js

@@ -0,0 +1,6 @@
+/**
+ * Technology — Atomic unit of the registry catalog.
+ * Each technology is deeply modeled with versions, ports, rules, and metadata.
+ */
+export {};
+//# sourceMappingURL=technology.js.map

package/dist/types/technology.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"technology.js","sourceRoot":"","sources":["../../src/types/technology.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/template.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Template / Blueprint — Preconfigured recipe based on a stack.
+ * Templates delegate to official tools and only fill gaps.
+ */
+export interface ScaffoldStep {
+  name: string;
+  command: string;
+  workingDir?: string;
+  condition?: string;
+}
+export interface TemplateOverride {
+  path: string;
+  content: string;
+  condition?: string;
+}
+export interface TemplateHook {
+  timing: "pre-scaffold" | "post-scaffold" | "pre-up" | "post-up";
+  name: string;
+  command: string;
+  description: string;
+  requiresConfirmation: boolean;
+}
+export interface Template {
+  id: string;
+  name: string;
+  description: string;
+  technologyIds: string[];
+  profile: string;
+  scaffoldSteps: ScaffoldStep[];
+  overrides: TemplateOverride[];
+  hooks: TemplateHook[];
+  variables: Record<string, string>;
+}
+//# sourceMappingURL=template.d.ts.map

package/dist/types/template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.d.ts","sourceRoot":"","sources":["../../src/types/template.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,cAAc,GAAG,eAAe,GAAG,QAAQ,GAAG,SAAS,CAAC;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC"}

package/dist/types/template.js

@@ -0,0 +1,6 @@
+/**
+ * Template / Blueprint — Preconfigured recipe based on a stack.
+ * Templates delegate to official tools and only fill gaps.
+ */
+export {};
+//# sourceMappingURL=template.js.map

package/dist/types/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../src/types/template.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/types/validation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Validation — Results from the rules engine.
+ */
+export type ValidationSeverity = "error" | "warning" | "info";
+export interface ValidationIssue {
+  severity: ValidationSeverity;
+  code: string;
+  message: string;
+  technologyId?: string;
+  relatedTechnologyId?: string;
+  autoFixable: boolean;
+  suggestedFix?: string;
+}
+export interface ValidationResult {
+  valid: boolean;
+  issues: ValidationIssue[];
+  resolvedDependencies: string[];
+  portAssignments: Record<string, number>;
+}
+//# sourceMappingURL=validation.d.ts.map

package/dist/types/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/types/validation.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC"}

package/dist/types/validation.js

@@ -0,0 +1,5 @@
+/**
+ * Validation — Results from the rules engine.
+ */
+export {};
+//# sourceMappingURL=validation.js.map

package/dist/types/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/types/validation.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@stackweld/core",
+  "version": "0.2.0",
+  "description": "Core engine for Stackweld — rules, scaffold orchestrator, runtime manager, tech installer, and SQLite persistence.",
+  "license": "MIT",
+  "author": "Orlando Fernandez <hello@xplustechnologies.com>",
+  "homepage": "https://github.com/mundowise/Stackweld",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mundowise/Stackweld.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./*": "./dist/*.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "better-sqlite3": "^11.0.0",
+    "yaml": "^2.7.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.0.0",
+    "@types/better-sqlite3": "^7.6.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.2"
+  }
+}

package/src/__tests__/compatibility-scorer.test.ts

@@ -0,0 +1,264 @@
+import { describe, expect, it } from "vitest";
+import { scoreCompatibility, scoreStack } from "../engine/compatibility-scorer.js";
+import type { Technology } from "../types/index.js";
+
+// ─── Test fixtures ────────────────────────────────────
+
+function makeTech(
+  overrides: Partial<Technology> & Pick<Technology, "id" | "name" | "category">,
+): Technology {
+  return {
+    description: "",
+    website: "",
+    versions: [{ version: "1" }],
+    defaultVersion: "1",
+    requires: [],
+    incompatibleWith: [],
+    suggestedWith: [],
+    envVars: {},
+    configFiles: [],
+    lastVerified: "2026-03-22",
+    tags: [],
+    ...overrides,
+  };
+}
+
+const nodejs = makeTech({
+  id: "nodejs",
+  name: "Node.js",
+  category: "runtime",
+  defaultPort: 3000,
+  suggestedWith: ["typescript"],
+});
+
+const nextjs = makeTech({
+  id: "nextjs",
+  name: "Next.js",
+  category: "frontend",
+  defaultPort: 3000,
+  requires: ["nodejs", "react"],
+  incompatibleWith: ["nuxt", "sveltekit", "remix", "astro", "angular", "qwik", "solidjs"],
+  suggestedWith: ["typescript", "tailwindcss", "prisma"],
+});
+
+const nuxt = makeTech({
+  id: "nuxt",
+  name: "Nuxt",
+  category: "frontend",
+  defaultPort: 3000,
+  requires: ["nodejs"],
+  incompatibleWith: ["nextjs"],
+});
+
+const react = makeTech({
+  id: "react",
+  name: "React",
+  category: "frontend",
+  defaultPort: 3000,
+  requires: ["nodejs"],
+  suggestedWith: ["tailwindcss"],
+});
+
+const tailwindcss = makeTech({
+  id: "tailwindcss",
+  name: "Tailwind CSS",
+  category: "styling",
+  requires: ["nodejs"],
+  suggestedWith: ["react", "nextjs", "vue"],
+});
+
+const prisma = makeTech({
+  id: "prisma",
+  name: "Prisma ORM",
+  category: "orm",
+  requires: ["nodejs"],
+  incompatibleWith: ["typeorm", "drizzle", "mongoose"],
+  suggestedWith: ["postgresql", "nextjs", "typescript"],
+});
+
+const express = makeTech({
+  id: "express",
+  name: "Express",
+  category: "backend",
+  defaultPort: 3001,
+  requires: ["nodejs"],
+  incompatibleWith: ["nestjs", "hono", "fastify"],
+  suggestedWith: ["typescript", "postgresql"],
+});
+
+const fastify = makeTech({
+  id: "fastify",
+  name: "Fastify",
+  category: "backend",
+  defaultPort: 3001,
+  requires: ["nodejs"],
+  incompatibleWith: ["nestjs", "hono", "express"],
+  suggestedWith: ["typescript", "postgresql", "prisma"],
+});
+
+const postgresql = makeTech({
+  id: "postgresql",
+  name: "PostgreSQL",
+  category: "database",
+  defaultPort: 5432,
+  suggestedWith: ["prisma", "drizzle", "sqlalchemy"],
+});
+
+const redis = makeTech({
+  id: "redis",
+  name: "Redis",
+  category: "database",
+  defaultPort: 6379,
+});
+
+const typescript = makeTech({
+  id: "typescript",
+  name: "TypeScript",
+  category: "devops",
+  requires: [],
+});
+
+// ─── Tests ────────────────────────────────────────────
+
+describe("scoreCompatibility", () => {
+  it("scores nextjs + prisma high (suggested pairing, shared runtime, complementary)", () => {
+    const result = scoreCompatibility(nextjs, prisma);
+    // +25 suggested (nextjs suggests prisma OR prisma suggests nextjs)
+    // +15 shared runtime (both require nodejs)
+    // +10 complementary (frontend + orm)
+    expect(result.score).toBeGreaterThanOrEqual(75);
+    expect(["S", "A"]).toContain(result.grade);
+    expect(result.factors.some((f) => f.label === "Suggested pairing")).toBe(true);
+    expect(result.factors.some((f) => f.label === "Shared runtime")).toBe(true);
+    expect(result.factors.some((f) => f.label === "Complementary categories")).toBe(true);
+  });
+
+  it("scores nextjs + nuxt as 0 (incompatible)", () => {
+    const result = scoreCompatibility(nextjs, nuxt);
+    expect(result.score).toBe(0);
+    expect(result.grade).toBe("F");
+    expect(result.factors.some((f) => f.label === "Incompatible")).toBe(true);
+    expect(result.recommendation).toContain("Incompatible");
+  });
+
+  it("scores react + tailwindcss high (suggested, complementary)", () => {
+    const result = scoreCompatibility(react, tailwindcss);
+    // +25 suggested (both suggest each other)
+    // +15 shared runtime (both require nodejs)
+    // +10 complementary (frontend + styling)
+    expect(result.score).toBeGreaterThanOrEqual(75);
+    expect(["S", "A"]).toContain(result.grade);
+    expect(result.factors.some((f) => f.label === "Suggested pairing")).toBe(true);
+  });
+
+  it("scores express + fastify low (incompatible, same category, same runtime, same port)", () => {
+    const result = scoreCompatibility(express, fastify);
+    // -50 incompatible, -15 same category+runtime, -5 same port
+    expect(result.score).toBe(0); // clamped to 0
+    expect(result.grade).toBe("F");
+    expect(result.factors.some((f) => f.label === "Incompatible")).toBe(true);
+    expect(result.factors.some((f) => f.label === "Same category and runtime")).toBe(true);
+    expect(result.factors.some((f) => f.label === "Port conflict")).toBe(true);
+  });
+
+  it("scores postgresql + redis as neutral (both databases, different ports, no runtime overlap)", () => {
+    const result = scoreCompatibility(postgresql, redis);
+    // baseline 50, no shared runtime (neither requires a runtime), no suggested
+    // no incompatibility, no same runtime => no -15 penalty
+    expect(result.score).toBe(50);
+    expect(result.grade).toBe("C");
+  });
+
+  it("never exceeds 100", () => {
+    // Artificial case: two techs that suggest each other, share runtime, complementary
+    const techA = makeTech({
+      id: "superA",
+      name: "Super A",
+      category: "frontend",
+      requires: ["nodejs"],
+      suggestedWith: ["superB"],
+    });
+    const techB = makeTech({
+      id: "superB",
+      name: "Super B",
+      category: "backend",
+      requires: ["nodejs"],
+      suggestedWith: ["superA"],
+    });
+    const result = scoreCompatibility(techA, techB);
+    // 50 + 25 + 15 + 10 = 100
+    expect(result.score).toBeLessThanOrEqual(100);
+    expect(result.score).toBe(100);
+    expect(result.grade).toBe("S");
+  });
+
+  it("never goes below 0", () => {
+    const result = scoreCompatibility(express, fastify);
+    expect(result.score).toBeGreaterThanOrEqual(0);
+  });
+
+  it("returns correct grade boundaries", () => {
+    // S: 90-100 — test with a score of exactly 90
+    // We use nextjs + prisma which should give 50+25+15+10 = 100
+    const sResult = scoreCompatibility(nextjs, prisma);
+    expect(sResult.score).toBeGreaterThanOrEqual(90);
+    expect(sResult.grade).toBe("S");
+  });
+
+  it("includes a human-readable recommendation", () => {
+    const result = scoreCompatibility(nextjs, prisma);
+    expect(typeof result.recommendation).toBe("string");
+    expect(result.recommendation.length).toBeGreaterThan(0);
+  });
+});
+
+describe("scoreStack", () => {
+  it("returns perfect score for single technology", () => {
+    const result = scoreStack([nextjs]);
+    expect(result.overall).toBe(100);
+    expect(result.grade).toBe("S");
+    expect(result.pairs).toHaveLength(0);
+  });
+
+  it("scores a full stack with 5+ technologies", () => {
+    const stack = [nodejs, nextjs, prisma, postgresql, tailwindcss, typescript];
+    const result = scoreStack(stack);
+
+    // Should produce C(6,2) = 15 pairs
+    expect(result.pairs).toHaveLength(15);
+
+    // Overall should be the average of all pair scores
+    const expectedAvg = Math.round(
+      result.pairs.reduce((s, p) => s + p.score, 0) / result.pairs.length,
+    );
+    expect(result.overall).toBe(expectedAvg);
+
+    // Should have a valid grade
+    expect(["S", "A", "B", "C", "D", "F"]).toContain(result.grade);
+  });
+
+  it("reflects bad pairings in overall score", () => {
+    // Include incompatible pair: nextjs + nuxt
+    const stack = [nodejs, nextjs, nuxt, postgresql];
+    const result = scoreStack(stack);
+
+    // The nextjs+nuxt pair should drag down the overall
+    const badPair = result.pairs.find(
+      (p) => (p.a === "nextjs" && p.b === "nuxt") || (p.a === "nuxt" && p.b === "nextjs"),
+    );
+    expect(badPair).toBeDefined();
+    expect(badPair?.score).toBe(0);
+
+    // Overall should be lower than a stack without incompatible techs
+    const goodStack = [nodejs, nextjs, postgresql];
+    const goodResult = scoreStack(goodStack);
+    expect(goodResult.overall).toBeGreaterThan(result.overall);
+  });
+
+  it("pair entries contain correct tech IDs", () => {
+    const result = scoreStack([express, postgresql]);
+    expect(result.pairs).toHaveLength(1);
+    expect(result.pairs[0].a).toBe("express");
+    expect(result.pairs[0].b).toBe("postgresql");
+  });
+});