@friehub/blueprint 0.1.0

package/dist/core/parse-document.js

@@ -0,0 +1,114 @@
+import { SECTION_DEFINITIONS } from "./sections.js";
+import { scanDocument } from "./scanner.js";
+import { collectFunctions, collectTypes, collectTextSections, collectProviders, extractDependencies, extractCoreInherits, groupSections, extractSummary, extractVersion, issue, } from "./collectors.js";
+export function parseDocument(file, text, mode) {
+    const scanned = scanDocument(file, text);
+    const issues = [];
+    if (scanned.envelope.kind === "module") {
+        const result = parseModuleDocument(scanned.envelope, scanned.preamble?.content ?? null, scanned.sections, mode);
+        issues.push(...result.issues);
+        if (mode === "strict" && issues.some((issue) => issue.severity === "error")) {
+            return { value: null, issues };
+        }
+        return { value: result.value, issues };
+    }
+    const result = parseCoreDocument(scanned.envelope, scanned.preamble?.content ?? null, scanned.sections, mode);
+    issues.push(...result.issues);
+    if (mode === "strict" && issues.some((issue) => issue.severity === "error")) {
+        return { value: null, issues };
+    }
+    return { value: result.value, issues };
+}
+export function parseCatalogFromDocuments(documents, mode) {
+    const modules = [];
+    const core = [];
+    const issues = [];
+    for (const document of documents) {
+        const result = parseDocument(document.file, document.text, mode);
+        issues.push(...result.issues);
+        if (!result.value)
+            continue;
+        if (result.value.profile === "module-v1") {
+            modules.push(result.value);
+        }
+        else {
+            core.push(result.value);
+        }
+    }
+    if (mode === "strict" && issues.some((issue) => issue.severity === "error")) {
+        return { value: null, issues };
+    }
+    return { value: { modules, core }, issues };
+}
+function parseModuleDocument(envelope, preamble, sections, mode) {
+    const issues = [];
+    const summary = extractSummary(preamble);
+    const version = extractVersion(preamble);
+    const grouped = groupSections(sections);
+    const required = SECTION_DEFINITIONS.filter((definition) => definition.requiredForModule).map((definition) => definition.name);
+    for (const sectionName of required) {
+        if (!grouped.has(sectionName)) {
+            issues.push(issue(envelope.source.file, sectionName, 1, 1, `Missing required section: ${sectionName}`, "MISSING_SECTION", mode));
+        }
+    }
+    const title = envelope.name;
+    const name = envelope.name;
+    const functionResult = collectFunctions(envelope.source.file, grouped.get("functions") ?? [], mode);
+    const typeResult = collectTypes(envelope.source.file, grouped.get("types") ?? [], mode);
+    issues.push(...functionResult.issues, ...typeResult.issues);
+    const functions = functionResult.items;
+    const types = typeResult.items;
+    const invariants = collectTextSections(grouped.get("invariants") ?? [], "invariants");
+    const providers = collectProviders(grouped.get("providers") ?? []);
+    const integrations = collectTextSections(grouped.get("system-integrations") ?? [], "system-integrations");
+    const { hardDeps, softDeps } = extractDependencies(grouped.get("system-integrations") ?? []);
+    const coreInherits = extractCoreInherits(grouped.get("system-integrations") ?? []);
+    const rawSections = sections;
+    for (const [sectionName, groupedSections] of grouped.entries()) {
+        if (groupedSections.length > 1) {
+            const first = groupedSections[0];
+            const last = groupedSections[groupedSections.length - 1];
+            issues.push(issue(envelope.source.file, sectionName, first.startLine, last.endLine, `Duplicate section: ${sectionName}`, "DUPLICATE_SECTION", mode));
+        }
+    }
+    return {
+        value: {
+            name,
+            title,
+            version,
+            summary,
+            functions,
+            types,
+            invariants,
+            providers,
+            integrations,
+            hardDeps,
+            softDeps,
+            coreInherits,
+            rawSections,
+            profile: "module-v1",
+            source: { file: envelope.source.file, startLine: 1, endLine: Math.max(1, sections.at(-1)?.endLine ?? 1) },
+        },
+        issues,
+    };
+}
+const IMPLICIT_CORE_NAMES = new Set(["global_standards", "runtime_standards"]);
+function parseCoreDocument(envelope, preamble, sections, _mode) {
+    const summary = extractSummary(preamble);
+    const version = extractVersion(preamble);
+    const title = envelope.title;
+    return {
+        value: {
+            name: envelope.name,
+            title,
+            version,
+            summary,
+            sections,
+            rawSections: sections,
+            implicit: IMPLICIT_CORE_NAMES.has(envelope.name),
+            profile: "core-v1",
+            source: { file: envelope.source.file, startLine: 1, endLine: Math.max(1, sections.at(-1)?.endLine ?? 1) },
+        },
+        issues: [],
+    };
+}

package/dist/core/parse-document.test.js

@@ -0,0 +1,104 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { loadCatalogFromRoot, parseDocument } from "./index.js";
+import { implicitCores } from "./catalog.js";
+const ROOT = fileURLToPath(new URL("../../", import.meta.url));
+describe("contract parser against real corpus files", () => {
+    it("parses a legacy module doc with runtime integrations", async () => {
+        const file = join(ROOT, "contracts", "billing.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.equal(result.issues.some((issue) => issue.severity === "error"), false);
+        assert.notEqual(result.value, null);
+        assert.equal(result.value?.profile, "module-v1");
+        assert.ok((result.value && "functions" in result.value ? result.value.functions.length : 0) > 0);
+        assert.ok((result.value && "providers" in result.value ? result.value.providers.length : 0) > 0);
+        assert.ok((result.value && "rawSections" in result.value ? result.value.rawSections.length : 0) > 0);
+    });
+    it("parses a module doc with inline provider text", async () => {
+        const file = join(ROOT, "contracts", "feature_flags.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.equal(result.issues.some((issue) => issue.severity === "error"), false);
+        assert.notEqual(result.value, null);
+        assert.equal(result.value?.profile, "module-v1");
+        assert.ok((result.value && "functions" in result.value ? result.value.functions.length : 0) > 0);
+        assert.ok((result.value && "providers" in result.value ? result.value.providers.length : 0) > 0);
+    });
+    it("parses a core doc with H3 section structure", async () => {
+        const file = join(ROOT, "contracts", "core", "sagas.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.equal(result.issues.some((issue) => issue.severity === "error"), false);
+        assert.notEqual(result.value, null);
+        assert.equal(result.value?.profile, "core-v1");
+        assert.ok((result.value && "rawSections" in result.value ? result.value.rawSections.length : 0) > 0);
+    });
+    it("loads the full catalog from the repository root", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "strict");
+        assert.equal(result.issues.some((issue) => issue.severity === "error"), false);
+        assert.notEqual(result.value, null);
+        assert.ok((result.value?.modules.length ?? 0) > 0);
+        assert.ok((result.value?.core.length ?? 0) > 0);
+    });
+    it("marks global_standards and runtime_standards as implicit", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const implicit = implicitCores(result.value);
+        const implicitNames = implicit.map((c) => c.name);
+        assert.ok(implicitNames.includes("global_standards"), "global_standards should be implicit");
+        assert.ok(implicitNames.includes("runtime_standards"), "runtime_standards should be implicit");
+        assert.ok(!implicitNames.includes("sagas"), "sagas should not be implicit");
+        assert.equal(implicit.length, 2, "exactly 2 implicit cores");
+    });
+    it("extracts hardDeps and softDeps from billing", async () => {
+        const file = join(ROOT, "contracts", "billing.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.notEqual(result.value, null);
+        assert.equal(result.value?.profile, "module-v1");
+        const mod = result.value;
+        assert.deepEqual(mod.hardDeps, ["payments", "users"]);
+        assert.deepEqual(mod.softDeps, ["notifications", "audit_log", "usage_metering"]);
+    });
+    it("returns empty hardDeps for users (none)", async () => {
+        const file = join(ROOT, "contracts", "users.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.notEqual(result.value, null);
+        const mod = result.value;
+        assert.deepEqual(mod.hardDeps, []);
+        assert.deepEqual(mod.softDeps, ["audit_log", "notifications", "permissions"]);
+    });
+    it("strips parenthetical notes from deps in cart", async () => {
+        const file = join(ROOT, "contracts", "cart.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.notEqual(result.value, null);
+        const mod = result.value;
+        assert.deepEqual(mod.hardDeps, ["catalog", "inventory", "promotions"]);
+        assert.deepEqual(mod.softDeps, ["caching"]);
+    });
+    it("extracts coreInherits from assignments", async () => {
+        const file = join(ROOT, "contracts", "assignments.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.notEqual(result.value, null);
+        const mod = result.value;
+        assert.ok(mod.coreInherits.includes("runtime_standards"), "assignments should inherit runtime_standards");
+    });
+    it("parses all modules and extracts coreInherits", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const withInherits = result.value.modules.filter((m) => m.coreInherits.length > 0);
+        assert.ok(withInherits.length > 0, "some modules should have coreInherits");
+        for (const mod of withInherits) {
+            for (const name of mod.coreInherits) {
+                assert.ok(["runtime_standards", "global_standards"].includes(name), `coreInherits should be a known core contract: ${name}`);
+            }
+        }
+    });
+});

package/dist/core/parser.js

@@ -0,0 +1,6 @@
+export function isModuleContract(value) {
+    return value.profile === "module-v1";
+}
+export function isCoreContract(value) {
+    return value.profile === "core-v1";
+}

package/dist/core/parser.test.js

@@ -0,0 +1,134 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { loadCatalogFromRoot, parseDocument } from "./index.js";
+const ROOT = fileURLToPath(new URL("../../", import.meta.url));
+describe("parser accuracy", () => {
+    it("parses all 108 contracts without errors", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        assert.equal(result.value.modules.length, 108);
+        assert.equal(result.issues.filter((i) => i.severity === "error").length, 0);
+    });
+    it("parses all 3 core contracts", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        assert.equal(result.value.core.length, 3);
+    });
+    it("extracts functions from every module", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        for (const mod of result.value.modules) {
+            assert.ok(mod.functions.length > 0, `${mod.name} has no functions`);
+        }
+    });
+    it("extracts hardDeps from every module that has them", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const modulesWithDeps = ["billing", "orders", "auth", "cart", "subscriptions"];
+        for (const name of modulesWithDeps) {
+            const mod = result.value.modules.find((m) => m.name === name);
+            assert.ok(mod, `${name} exists`);
+            assert.ok(mod.hardDeps.length > 0, `${name} has hardDeps`);
+        }
+    });
+    it("extracts softDeps from every module that has them", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const modulesWithSoftDeps = ["billing", "orders", "auth", "users"];
+        for (const name of modulesWithSoftDeps) {
+            const mod = result.value.modules.find((m) => m.name === name);
+            assert.ok(mod, `${name} exists`);
+            assert.ok(mod.softDeps.length > 0, `${name} has softDeps`);
+        }
+    });
+    it("extracts coreInherits from modules that reference runtime_standards", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const modulesWithInherits = result.value.modules.filter((m) => m.coreInherits.length > 0);
+        assert.ok(modulesWithInherits.length > 10, "multiple modules inherit core");
+    });
+    it("parses multi-line type definitions", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const ab_testing = result.value.modules.find((m) => m.name === "ab_testing");
+        assert.ok(ab_testing, "ab_testing exists");
+        const variant = ab_testing.types.find((t) => t.name === "Variant");
+        assert.ok(variant, "Variant type exists");
+        assert.ok(variant.raw.length > 50, "Variant type has full definition");
+    });
+    it("parses shorthand type definitions", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const billing = result.value.modules.find((m) => m.name === "billing");
+        assert.ok(billing, "billing exists");
+        const subscription = billing.types.find((t) => t.name === "Subscription");
+        assert.ok(subscription, "Subscription type exists");
+        assert.ok(subscription.raw.includes("id"), "Subscription has id field");
+    });
+});
+describe("parser consistency", () => {
+    it("produces same output on multiple runs", async () => {
+        const result1 = await loadCatalogFromRoot(ROOT, "loose");
+        const result2 = await loadCatalogFromRoot(ROOT, "loose");
+        assert.equal(result1.value.modules.length, result2.value.modules.length);
+        assert.equal(result1.value.core.length, result2.value.core.length);
+        for (let i = 0; i < result1.value.modules.length; i++) {
+            const mod1 = result1.value.modules[i];
+            const mod2 = result2.value.modules[i];
+            assert.equal(mod1.name, mod2.name);
+            assert.equal(mod1.functions.length, mod2.functions.length);
+            assert.equal(mod1.hardDeps.length, mod2.hardDeps.length);
+        }
+    });
+    it("preserves line numbers for all extracted items", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        for (const mod of result.value.modules) {
+            for (const fn of mod.functions) {
+                assert.ok(fn.source.startLine > 0, `${mod.name}.${fn.name} has valid startLine`);
+                assert.ok(fn.source.endLine >= fn.source.startLine, `${mod.name}.${fn.name} has valid endLine`);
+            }
+        }
+    });
+});
+describe("specific contract accuracy", () => {
+    it("billing has correct functions", async () => {
+        const file = join(ROOT, "contracts", "billing.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.equal(result.issues.length, 0);
+        const mod = result.value;
+        const fnNames = mod.functions.map((f) => f.name);
+        assert.ok(fnNames.includes("createSubscription"));
+        assert.ok(fnNames.includes("getSubscription"));
+        assert.ok(fnNames.includes("cancelSubscription"));
+        assert.ok(fnNames.includes("getInvoices"));
+    });
+    it("orders has correct functions", async () => {
+        const file = join(ROOT, "contracts", "orders.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.equal(result.issues.length, 0);
+        const mod = result.value;
+        const fnNames = mod.functions.map((f) => f.name);
+        assert.ok(fnNames.includes("createOrder"));
+        assert.ok(fnNames.includes("getOrder"));
+        assert.ok(fnNames.includes("transitionOrderStatus"));
+        assert.ok(fnNames.includes("cancelOrder"));
+    });
+    it("auth has correct functions", async () => {
+        const file = join(ROOT, "contracts", "auth.md");
+        const text = await readFile(file, "utf8");
+        const result = parseDocument(file, text, "strict");
+        assert.equal(result.issues.length, 0);
+        const mod = result.value;
+        const fnNames = mod.functions.map((f) => f.name);
+        assert.ok(fnNames.includes("signUp"));
+        assert.ok(fnNames.includes("signIn"));
+        assert.ok(fnNames.includes("signOut"));
+        assert.ok(fnNames.includes("verifyToken"));
+    });
+});

package/dist/core/resolve.js

@@ -0,0 +1,119 @@
+import { implicitCores } from "./catalog.js";
+export function detectCycles(catalog) {
+    const moduleByName = new Map();
+    for (const mod of catalog.modules) {
+        moduleByName.set(mod.name, mod);
+    }
+    const cycles = [];
+    const visited = new Set();
+    const inStack = new Set();
+    const path = [];
+    function dfs(name) {
+        if (inStack.has(name)) {
+            const cycleStart = path.indexOf(name);
+            cycles.push(path.slice(cycleStart).concat(name));
+            return;
+        }
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        inStack.add(name);
+        path.push(name);
+        const mod = moduleByName.get(name);
+        if (mod) {
+            for (const dep of mod.hardDeps) {
+                if (moduleByName.has(dep)) {
+                    dfs(dep);
+                }
+            }
+        }
+        path.pop();
+        inStack.delete(name);
+    }
+    for (const mod of catalog.modules) {
+        dfs(mod.name);
+    }
+    return cycles;
+}
+export function resolve(catalog, requestedModules) {
+    const moduleByName = new Map();
+    for (const mod of catalog.modules) {
+        moduleByName.set(mod.name, mod);
+    }
+    const resolved = new Map();
+    const errors = [];
+    const warnings = [];
+    for (const name of requestedModules) {
+        if (!moduleByName.has(name)) {
+            errors.push(`Module not found in catalog: ${name}`);
+            continue;
+        }
+        resolved.set(name, { name, source: "explicit" });
+    }
+    const queue = requestedModules
+        .filter((name) => moduleByName.has(name))
+        .map((name) => ({ name, via: "explicit" }));
+    const inQueue = new Set(queue.map((q) => q.name));
+    while (queue.length > 0) {
+        const current = queue.shift();
+        inQueue.delete(current.name);
+        const mod = moduleByName.get(current.name);
+        if (!mod)
+            continue;
+        for (const dep of mod.hardDeps) {
+            if (resolved.has(dep))
+                continue;
+            if (!moduleByName.has(dep)) {
+                errors.push(`Hard dependency not found in catalog: ${dep} (required by ${current.name})`);
+                continue;
+            }
+            resolved.set(dep, { name: dep, source: "hard-dep" });
+            if (!inQueue.has(dep)) {
+                queue.push({ name: dep, via: "hard-dep" });
+                inQueue.add(dep);
+            }
+        }
+        if (current.via === "explicit") {
+            for (const dep of mod.softDeps) {
+                if (resolved.has(dep))
+                    continue;
+                if (!moduleByName.has(dep))
+                    continue;
+                resolved.set(dep, { name: dep, source: "soft-dep" });
+            }
+        }
+    }
+    const resolvedModules = [...resolved.values()].map((entry) => {
+        const mod = moduleByName.get(entry.name);
+        return {
+            name: entry.name,
+            source: entry.source,
+            hardDeps: mod.hardDeps,
+            softDeps: mod.softDeps,
+        };
+    });
+    resolvedModules.sort((a, b) => {
+        const order = { explicit: 0, "hard-dep": 1, "soft-dep": 2 };
+        return (order[a.source] ?? 3) - (order[b.source] ?? 3) || a.name.localeCompare(b.name);
+    });
+    const implicitCore = implicitCores(catalog);
+    const coreByName = new Map();
+    for (const c of implicitCore) {
+        coreByName.set(c.name, c);
+    }
+    for (const entry of resolved.values()) {
+        const mod = moduleByName.get(entry.name);
+        if (!mod)
+            continue;
+        for (const coreName of mod.coreInherits) {
+            if (coreByName.has(coreName))
+                continue;
+            const coreContract = catalog.core.find((c) => c.name === coreName);
+            if (coreContract) {
+                coreByName.set(coreName, coreContract);
+            }
+        }
+    }
+    const core = [...coreByName.values()];
+    return { modules: resolvedModules, core, errors, warnings };
+}

package/dist/core/resolve.test.js

@@ -0,0 +1,108 @@
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+import { loadCatalogFromRoot } from "./index.js";
+import { resolve, detectCycles } from "./resolve.js";
+import { fileURLToPath } from "node:url";
+const ROOT = fileURLToPath(new URL("../../", import.meta.url));
+function renderList(catalog) {
+    const lines = [];
+    lines.push("Modules:");
+    for (const mod of catalog.modules.sort((a, b) => a.name.localeCompare(b.name))) {
+        const deps = mod.hardDeps.length > 0 ? mod.hardDeps.join(", ") : "(none)";
+        const soft = mod.softDeps.length > 0 ? mod.softDeps.join(", ") : "(none)";
+        const summary = mod.summary ? ` - ${mod.summary}` : "";
+        lines.push(`  ${mod.name}${summary}`);
+        lines.push(`    deps: ${deps}`);
+        lines.push(`    recommends: ${soft}`);
+    }
+    lines.push("");
+    lines.push("Core contracts:");
+    for (const c of catalog.core.sort((a, b) => a.name.localeCompare(b.name))) {
+        lines.push(`  ${c.name}${c.implicit ? " (implicit)" : ""}`);
+    }
+    return lines.join("\n");
+}
+describe("resolver", () => {
+    it("resolves a module with no deps", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["users"]);
+        assert.equal(resolved.warnings.length, 0);
+        assert.ok(resolved.modules.some((m) => m.name === "users" && m.source === "explicit"));
+        assert.ok(resolved.core.length > 0, "should include implicit cores");
+        assert.ok(resolved.core.every((c) => c.implicit), "all cores should be implicit");
+    });
+    it("resolves hard deps transitively", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["billing"]);
+        const names = resolved.modules.map((m) => m.name);
+        assert.ok(names.includes("billing"), "explicit module present");
+        assert.ok(names.includes("payments"), "hard dep of billing");
+        assert.ok(names.includes("users"), "hard dep of billing");
+        assert.ok(resolved.modules.find((m) => m.name === "payments")?.source === "hard-dep");
+        assert.ok(resolved.modules.find((m) => m.name === "users")?.source === "hard-dep");
+    });
+    it("includes soft deps of explicitly requested modules", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["billing"]);
+        const softDeps = resolved.modules.filter((m) => m.source === "soft-dep").map((m) => m.name);
+        assert.ok(softDeps.includes("notifications"), "soft dep of billing");
+        assert.ok(softDeps.includes("audit_log"), "soft dep of billing");
+    });
+    it("does not include soft deps of hard-dep modules", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["billing"]);
+        const names = resolved.modules.map((m) => m.name);
+        assert.ok(!names.includes("fraud_detection"), "fraud_detection is a soft dep of payments (hard-dep), should not be pulled");
+    });
+    it("errors on unknown module names", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["nonexistent"]);
+        assert.ok(resolved.errors.some((e) => e.includes("nonexistent")));
+        assert.equal(resolved.modules.length, 0);
+    });
+    it("always includes implicit core contracts", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["catalog"]);
+        const coreNames = resolved.core.map((c) => c.name);
+        assert.ok(coreNames.includes("global_standards"));
+        assert.ok(coreNames.includes("runtime_standards"));
+    });
+    it("includes core contracts inherited by resolved modules", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["assignments"]);
+        const coreNames = resolved.core.map((c) => c.name);
+        assert.ok(coreNames.includes("runtime_standards"), "assignments inherits runtime_standards");
+    });
+    it("sorts explicit before hard-dep before soft-dep", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const resolved = resolve(result.value, ["billing"]);
+        const sources = resolved.modules.map((m) => m.source);
+        const explicitIdx = sources.indexOf("explicit");
+        const hardIdx = sources.indexOf("hard-dep");
+        const softIdx = sources.indexOf("soft-dep");
+        assert.ok(explicitIdx < hardIdx, "explicit comes before hard-dep");
+        assert.ok(hardIdx < softIdx, "hard-dep comes before soft-dep");
+    });
+    it("detects no cycles in the real corpus", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const cycles = detectCycles(result.value);
+        assert.equal(cycles.length, 0, "no cycles expected in the real corpus");
+    });
+    it("list command output contains module names", async () => {
+        const result = await loadCatalogFromRoot(ROOT, "loose");
+        assert.notEqual(result.value, null);
+        const output = renderList(result.value);
+        assert.ok(output.includes("billing"), "should list billing");
+        assert.ok(output.includes("users"), "should list users");
+        assert.ok(output.includes("Core contracts:"), "should list core section");
+    });
+});