@toolbaux/guardian 0.1.0

package/dist/extract/runtime.js

@@ -0,0 +1,193 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { createIgnoreMatcher } from "./ignore.js";
+function toPosix(p) {
+    return p.split(path.sep).join("/");
+}
+function isDockerfile(name) {
+    return name === "Dockerfile" || name.startsWith("Dockerfile.");
+}
+function isComposeFile(name) {
+    return (name === "docker-compose.yml" ||
+        name === "docker-compose.yaml" ||
+        name === "compose.yml" ||
+        name === "compose.yaml");
+}
+async function listFiles(root, ignore) {
+    const entries = await fs.readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        const fullPath = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            if (ignore.isIgnoredDir(entry.name, fullPath)) {
+                continue;
+            }
+            files.push(...(await listFiles(fullPath, ignore)));
+            continue;
+        }
+        if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function normalizeEnvironment(env) {
+    if (!env) {
+        return undefined;
+    }
+    if (Array.isArray(env)) {
+        return env.map((entry) => String(entry));
+    }
+    if (typeof env === "object") {
+        return Object.entries(env).map(([key, value]) => `${key}=${String(value)}`);
+    }
+    return undefined;
+}
+function normalizeArray(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => String(entry));
+    }
+    return undefined;
+}
+function parseComposeServices(doc, source) {
+    if (!doc || typeof doc !== "object") {
+        return [];
+    }
+    const services = doc.services;
+    if (!services || typeof services !== "object") {
+        return [];
+    }
+    const result = [];
+    for (const [name, raw] of Object.entries(services)) {
+        if (!raw || typeof raw !== "object") {
+            continue;
+        }
+        const service = raw;
+        const entry = {
+            name,
+            source,
+            image: typeof service.image === "string" ? service.image : undefined,
+            build: typeof service.build === "string" ? service.build : undefined,
+            ports: normalizeArray(service.ports),
+            environment: normalizeEnvironment(service.environment),
+            depends_on: normalizeArray(service.depends_on)
+        };
+        result.push(entry);
+    }
+    return result;
+}
+export async function analyzeRuntime(projectRoot, config) {
+    const root = path.resolve(projectRoot);
+    const ignore = createIgnoreMatcher(config, root);
+    const files = await listFiles(root, ignore);
+    const dockerfiles = [];
+    const services = [];
+    const manifests = [];
+    const shell_scripts = [];
+    for (const file of files) {
+        const name = path.basename(file);
+        const relative = toPosix(path.relative(root, file));
+        if (name.endsWith(".sh") || name.endsWith(".bash") || name.endsWith(".zsh") || name.endsWith(".bat") || name.endsWith(".ps1")) {
+            shell_scripts.push(relative);
+            continue;
+        }
+        const isRoot = !relative.includes("/");
+        const explicitConfigs = new Set([
+            "package.json", "pyproject.toml", "requirements.txt", "go.mod", "go.sum",
+            "pom.xml", "build.gradle", "Makefile", "makefile", "tslint.json",
+            "eslint.config.js", "tsconfig.json", ".npmrc", "yarn.lock", "package-lock.json"
+        ]);
+        if (explicitConfigs.has(name) ||
+            (relative.startsWith(".github/") && (name.endsWith(".yml") || name.endsWith(".yaml"))) ||
+            (isRoot && (name.endsWith(".json") || name.endsWith(".yaml") || name.endsWith(".yml") || name.endsWith(".md") || name.endsWith(".toml")))) {
+            if (!isComposeFile(name)) {
+                const manifest = await parseManifest(file, relative, name);
+                if (manifest) {
+                    manifests.push(manifest);
+                }
+            }
+        }
+        if (isDockerfile(name)) {
+            dockerfiles.push(relative);
+            continue;
+        }
+        if (isComposeFile(name)) {
+            try {
+                const raw = await fs.readFile(file, "utf8");
+                const doc = yaml.load(raw);
+                services.push(...parseComposeServices(doc, relative));
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    dockerfiles.sort((a, b) => a.localeCompare(b));
+    manifests.sort((a, b) => a.file.localeCompare(b.file));
+    shell_scripts.sort((a, b) => a.localeCompare(b));
+    services.sort((a, b) => {
+        const nameCmp = a.name.localeCompare(b.name);
+        if (nameCmp !== 0)
+            return nameCmp;
+        return a.source.localeCompare(b.source);
+    });
+    return {
+        dockerfiles,
+        services,
+        manifests,
+        shell_scripts
+    };
+}
+async function parseManifest(file, relative, name) {
+    try {
+        const raw = await fs.readFile(file, "utf8");
+        if (name === "package.json") {
+            const parsed = JSON.parse(raw);
+            const commands = parsed.scripts ? Object.keys(parsed.scripts) : [];
+            const dependencies = parsed.dependencies ? Object.keys(parsed.dependencies) : [];
+            const dev_dependencies = parsed.devDependencies ? Object.keys(parsed.devDependencies) : [];
+            return { file: relative, kind: "npm", commands, dependencies, dev_dependencies };
+        }
+        if (name === "Makefile" || name === "makefile") {
+            const commands = [];
+            const regex = /^([a-zA-Z0-9_-]+):/gm;
+            let match;
+            while ((match = regex.exec(raw)) !== null) {
+                if (match[1] && match[1] !== ".PHONY")
+                    commands.push(match[1]);
+            }
+            return { file: relative, kind: "makefile", commands };
+        }
+        if (relative.startsWith(".github/") && (name.endsWith(".yml") || name.endsWith(".yaml"))) {
+            const doc = yaml.load(raw);
+            if (doc && typeof doc === "object") {
+                const description = doc.name || undefined;
+                let commands = [];
+                if (doc.jobs && typeof doc.jobs === "object") {
+                    commands = Object.keys(doc.jobs);
+                }
+                return { file: relative, kind: "github-action", description, commands };
+            }
+        }
+        if (name === "pyproject.toml") {
+            return { file: relative, kind: "poetry" };
+        }
+        if (name === "go.mod" || name === "go.sum") {
+            return { file: relative, kind: "go" };
+        }
+        if (name === "pom.xml" || name === "build.gradle") {
+            return { file: relative, kind: "maven" };
+        }
+        if (name.endsWith(".md")) {
+            return { file: relative, kind: "doc" };
+        }
+        return { file: relative, kind: "unknown" };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/extract/schema-evolution-validator.js

@@ -0,0 +1,35 @@
+import { analyzeBackend } from "./analyzers/backend.js";
+export async function validateSchemaEvolution(backendRoot, previousSchemas) {
+    const backendAnalysis = await analyzeBackend(backendRoot, {});
+    const currentSchemas = backendAnalysis.endpoints.map((endpoint) => ({
+        path: endpoint.path,
+        method: endpoint.method,
+        request_schema: endpoint.request_schema,
+        response_schema: endpoint.response_schema
+    }));
+    const validationResults = [];
+    for (const currentSchema of currentSchemas) {
+        const previousSchema = previousSchemas.find((schema) => schema.path === currentSchema.path && schema.method === currentSchema.method);
+        const validationResult = {
+            endpoint: `${currentSchema.method} ${currentSchema.path}`,
+            compatible: true,
+            issues: []
+        };
+        if (!previousSchema) {
+            validationResult.compatible = false;
+            validationResult.issues.push("New endpoint detected.");
+        }
+        else {
+            if (JSON.stringify(currentSchema.request_schema) !== JSON.stringify(previousSchema.request_schema)) {
+                validationResult.compatible = false;
+                validationResult.issues.push("Request schema changed.");
+            }
+            if (JSON.stringify(currentSchema.response_schema) !== JSON.stringify(previousSchema.response_schema)) {
+                validationResult.compatible = false;
+                validationResult.issues.push("Response schema changed.");
+            }
+        }
+        validationResults.push(validationResult);
+    }
+    return validationResults;
+}

package/dist/extract/test-gap-analyzer.js

@@ -0,0 +1,20 @@
+import { analyzeBackend } from "./analyzers/backend.js";
+import { analyzeTests } from "./analyzers/tests.js";
+export async function analyzeTestGaps(backendRoot, testRoot) {
+    const backendAnalysis = await analyzeBackend(backendRoot, {});
+    const testAnalysis = await analyzeTests(testRoot, {});
+    const untestedEndpoints = backendAnalysis.endpoints.filter((endpoint) => {
+        return !testAnalysis.testedEndpoints.some((tested) => tested.path === endpoint.path && tested.method === endpoint.method);
+    });
+    const testStubs = untestedEndpoints.map((endpoint) => {
+        return {
+            testFile: `${testRoot}/generated/${endpoint.method}_${endpoint.path.replace(/\//g, "_")}.test.ts`,
+            content: `describe('${endpoint.method} ${endpoint.path}', () => {
+  it('should handle ${endpoint.method} requests', async () => {
+    // TODO: Implement test logic
+  });
+});`
+        };
+    });
+    return testStubs;
+}

package/dist/extract/tests.js

@@ -0,0 +1,74 @@
+import path from "node:path";
+export function computeTestCoverage(files) {
+    const testFiles = new Set();
+    const sourceFiles = new Set();
+    for (const file of files) {
+        const isTest = file.includes(".test.") ||
+            file.includes(".spec.") ||
+            file.includes("_test.") ||
+            file.includes("test_") ||
+            file.startsWith("tests/") ||
+            file.includes("/tests/");
+        if (isTest) {
+            testFiles.add(file);
+        }
+        else {
+            sourceFiles.add(file);
+        }
+    }
+    const coverageMap = [];
+    const coveredSourceFiles = new Set();
+    for (const testFile of testFiles) {
+        const basename = path.basename(testFile);
+        let potentialSourceName = basename
+            .replace(/\.test\./, ".")
+            .replace(/\.spec\./, ".")
+            .replace(/_test\./, ".")
+            .replace(/^test_/, "");
+        // Search for an exact match in sourceFiles
+        let exactMatch = null;
+        let implicitMatch = null;
+        for (const sourceFile of sourceFiles) {
+            if (path.basename(sourceFile) === potentialSourceName) {
+                // If they share exactly the same dirname logic, it's exact
+                // Otherwise, it's an implicit match
+                if (path.dirname(testFile).replace(/\/tests?(\/|$)/, "/") === path.dirname(sourceFile)) {
+                    exactMatch = sourceFile;
+                    break;
+                }
+                else {
+                    implicitMatch = sourceFile;
+                }
+            }
+        }
+        const match = exactMatch ?? implicitMatch;
+        if (match) {
+            coveredSourceFiles.add(match);
+            coverageMap.push({
+                test_file: testFile,
+                source_file: match,
+                match_type: exactMatch ? "exact" : "implicit"
+            });
+        }
+        else {
+            coverageMap.push({
+                test_file: testFile,
+                source_file: null,
+                match_type: "none"
+            });
+        }
+    }
+    const untestedSourceFiles = Array.from(sourceFiles)
+        .filter((file) => !coveredSourceFiles.has(file))
+        .sort((a, b) => a.localeCompare(b));
+    const testFilesMissingSource = coverageMap
+        .filter((cov) => cov.match_type === "none")
+        .map((cov) => cov.test_file)
+        .sort((a, b) => a.localeCompare(b));
+    coverageMap.sort((a, b) => a.test_file.localeCompare(b.test_file));
+    return {
+        untested_source_files: untestedSourceFiles,
+        test_files_missing_source: testFilesMissingSource,
+        coverage_map: coverageMap
+    };
+}

package/dist/extract/types.js

@@ -0,0 +1 @@
+export {};

package/dist/extract/validate-backend.js

@@ -0,0 +1,30 @@
+import { analyzeBackend } from "./analyzers/backend.js";
+export async function validateBackendEndpoints(backendRoot, expectedContracts) {
+    const backendAnalysis = await analyzeBackend(backendRoot, {});
+    const validationResults = [];
+    for (const endpoint of backendAnalysis.endpoints) {
+        const validationResult = {
+            endpoint: `${endpoint.method} ${endpoint.path}`,
+            valid: true,
+            issues: []
+        };
+        const expectedContract = expectedContracts.find((contract) => contract.path === endpoint.path && contract.method === endpoint.method);
+        if (!expectedContract) {
+            validationResult.valid = false;
+            validationResult.issues.push("No matching contract found.");
+        }
+        else {
+            // Validate request and response schemas
+            if (JSON.stringify(endpoint.request_schema) !== JSON.stringify(expectedContract.request_schema)) {
+                validationResult.valid = false;
+                validationResult.issues.push("Request schema mismatch.");
+            }
+            if (JSON.stringify(endpoint.response_schema) !== JSON.stringify(expectedContract.response_schema)) {
+                validationResult.valid = false;
+                validationResult.issues.push("Response schema mismatch.");
+            }
+        }
+        validationResults.push(validationResult);
+    }
+    return validationResults;
+}

package/dist/extract/writer.js

@@ -0,0 +1,11 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+export async function writeSnapshots(outputDir, architecture, ux) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const architecturePath = path.join(outputDir, "architecture.snapshot.yaml");
+    const uxPath = path.join(outputDir, "ux.snapshot.yaml");
+    await fs.writeFile(architecturePath, yaml.dump(architecture, { noRefs: true, lineWidth: 120 }));
+    await fs.writeFile(uxPath, yaml.dump(ux, { noRefs: true, lineWidth: 120 }));
+    return { architecturePath, uxPath };
+}

package/dist/output-layout.js

@@ -0,0 +1,37 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+export function getOutputLayout(outputRoot, internalDir = "internal") {
+    const rootDir = path.resolve(outputRoot);
+    const machineDir = path.join(rootDir, "machine");
+    return {
+        rootDir,
+        machineDir,
+        machineDocsDir: path.join(machineDir, "docs"),
+        machineInternalDir: path.join(machineDir, "docs", internalDir),
+        humanDir: path.join(rootDir, "human")
+    };
+}
+export async function resolveMachineInputDir(input) {
+    const resolved = path.resolve(input || "specs-out");
+    const directSnapshot = await hasMachineSnapshots(resolved);
+    if (directSnapshot) {
+        return resolved;
+    }
+    const machineDir = path.join(resolved, "machine");
+    if (await hasMachineSnapshots(machineDir)) {
+        return machineDir;
+    }
+    return machineDir;
+}
+async function hasMachineSnapshots(dir) {
+    try {
+        await Promise.all([
+            fs.stat(path.join(dir, "architecture.snapshot.yaml")),
+            fs.stat(path.join(dir, "ux.snapshot.yaml"))
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}