@toolbaux/guardian 0.1.0

package/dist/config.js

@@ -0,0 +1,441 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_CONFIG = {
+    project: {
+        root: "",
+        backendRoot: "",
+        frontendRoot: "",
+        discovery: {
+            enabled: true
+        },
+        description: "",
+        readmePath: ""
+    },
+    ignore: {
+        directories: [
+            ".git",
+            "node_modules",
+            "dist",
+            "build",
+            ".next",
+            ".venv",
+            "venv",
+            "__pycache__",
+            ".pytest_cache",
+            ".mypy_cache",
+            "coverage",
+            "htmlcov",
+            "logs",
+            "log",
+            "tmp",
+            "cache",
+            "specs-out",
+            "ghost-out"
+        ],
+        paths: []
+    },
+    python: {
+        absoluteImportRoots: []
+    },
+    frontend: {
+        routeDirs: ["src/routes", "src/pages", "routes", "pages"],
+        aliases: {},
+        tsconfigPath: ""
+    },
+    drift: {
+        graphLevel: "module",
+        scales: ["module", "file", "function"],
+        weights: {
+            entropy: 0.4,
+            crossLayer: 0.3,
+            cycles: 0.2,
+            modularity: 0.1
+        },
+        layers: {},
+        domains: {},
+        capacity: {
+            layers: {},
+            total: 0,
+            warningRatio: 0.85,
+            criticalRatio: 1.0
+        },
+        growth: {
+            maxEdgesPerHour: 0,
+            maxEdgesPerDay: 0,
+            maxEdgeGrowthRatio: 0
+        },
+        baselinePath: "",
+        historyPath: "",
+        criticalDelta: 0.25
+    },
+    guard: {
+        mode: "soft"
+    },
+    llm: {
+        command: "",
+        args: [],
+        timeoutMs: 120000,
+        promptTemplate: ""
+    },
+    docs: {
+        mode: "lean",
+        internalDir: "internal"
+    }
+};
+export async function loadSpecGuardConfig(options) {
+    const configPath = await resolveConfigPath(options);
+    if (!configPath) {
+        return DEFAULT_CONFIG;
+    }
+    let parsed = {};
+    try {
+        const raw = await fs.readFile(configPath, "utf8");
+        parsed = normalizeConfig(JSON.parse(raw), path.dirname(configPath));
+    }
+    catch (error) {
+        throw new Error(`Failed to read config at ${configPath}: ${String(error)}`);
+    }
+    return mergeConfig(DEFAULT_CONFIG, parsed);
+}
+function normalizeConfig(input, configDir) {
+    const normalized = { ...input };
+    if (input.project) {
+        const project = { ...input.project };
+        if (!project.backendRoot && typeof project.backend_root !== "undefined") {
+            project.backendRoot = project.backend_root;
+        }
+        delete project.backend_root;
+        if (!project.frontendRoot && typeof project.frontend_root !== "undefined") {
+            project.frontendRoot = project.frontend_root;
+        }
+        delete project.frontend_root;
+        if (project.discovery && typeof project.discovery === "object") {
+            const discovery = { ...project.discovery };
+            if (typeof discovery.enabled === "undefined" &&
+                typeof discovery.auto_detect !== "undefined") {
+                discovery.enabled = discovery.auto_detect;
+            }
+            delete discovery.auto_detect;
+            project.discovery = discovery;
+        }
+        const resolveMaybe = (value) => {
+            if (typeof value !== "string" || value.trim().length === 0) {
+                return undefined;
+            }
+            return configDir ? path.resolve(configDir, value) : value;
+        };
+        project.root = resolveMaybe(project.root) ?? "";
+        project.backendRoot = resolveMaybe(project.backendRoot) ?? "";
+        project.frontendRoot = resolveMaybe(project.frontendRoot) ?? "";
+        normalized.project = project;
+    }
+    if (input.python) {
+        const python = { ...input.python };
+        if (!python.absoluteImportRoots && typeof python.absolute_import_roots !== "undefined") {
+            python.absoluteImportRoots = python.absolute_import_roots;
+        }
+        delete python.absolute_import_roots;
+        normalized.python = python;
+    }
+    if (input.frontend) {
+        const frontend = { ...input.frontend };
+        if (!frontend.routeDirs && typeof frontend.route_dirs !== "undefined") {
+            frontend.routeDirs = frontend.route_dirs;
+        }
+        delete frontend.route_dirs;
+        if (!frontend.tsconfigPath && typeof frontend.tsconfig_path !== "undefined") {
+            frontend.tsconfigPath = frontend.tsconfig_path;
+        }
+        delete frontend.tsconfig_path;
+        normalized.frontend = frontend;
+    }
+    if (input.drift) {
+        const drift = { ...input.drift };
+        if (!drift.graphLevel && typeof drift.graph_level !== "undefined") {
+            drift.graphLevel = drift.graph_level;
+        }
+        delete drift.graph_level;
+        if (!drift.scales && typeof drift.scale_levels !== "undefined") {
+            drift.scales = drift.scale_levels;
+        }
+        delete drift.scale_levels;
+        if (!drift.baselinePath && typeof drift.baseline_path !== "undefined") {
+            drift.baselinePath = drift.baseline_path;
+        }
+        delete drift.baseline_path;
+        if (!drift.historyPath && typeof drift.history_path !== "undefined") {
+            drift.historyPath = drift.history_path;
+        }
+        delete drift.history_path;
+        if (!drift.domains && typeof drift.domain_map !== "undefined") {
+            drift.domains = drift.domain_map;
+        }
+        delete drift.domain_map;
+        if (drift.capacity && typeof drift.capacity === "object") {
+            const capacity = { ...drift.capacity };
+            if (!capacity.warningRatio && typeof capacity.warning_ratio !== "undefined") {
+                capacity.warningRatio = capacity.warning_ratio;
+            }
+            delete capacity.warning_ratio;
+            if (!capacity.criticalRatio && typeof capacity.critical_ratio !== "undefined") {
+                capacity.criticalRatio = capacity.critical_ratio;
+            }
+            delete capacity.critical_ratio;
+            if (!capacity.total && typeof capacity.total_edges !== "undefined") {
+                capacity.total = capacity.total_edges;
+            }
+            delete capacity.total_edges;
+            drift.capacity = capacity;
+        }
+        if (drift.growth && typeof drift.growth === "object") {
+            const growth = { ...drift.growth };
+            if (!growth.maxEdgesPerHour && typeof growth.max_edges_per_hour !== "undefined") {
+                growth.maxEdgesPerHour = growth.max_edges_per_hour;
+            }
+            delete growth.max_edges_per_hour;
+            if (!growth.maxEdgesPerDay && typeof growth.max_edges_per_day !== "undefined") {
+                growth.maxEdgesPerDay = growth.max_edges_per_day;
+            }
+            delete growth.max_edges_per_day;
+            if (!growth.maxEdgeGrowthRatio && typeof growth.max_edge_growth_ratio !== "undefined") {
+                growth.maxEdgeGrowthRatio = growth.max_edge_growth_ratio;
+            }
+            delete growth.max_edge_growth_ratio;
+            drift.growth = growth;
+        }
+        if (!drift.criticalDelta && typeof drift.critical_delta !== "undefined") {
+            drift.criticalDelta = drift.critical_delta;
+        }
+        delete drift.critical_delta;
+        if (drift.weights && typeof drift.weights === "object") {
+            const weights = { ...drift.weights };
+            if (!weights.crossLayer && typeof weights.cross_layer !== "undefined") {
+                weights.crossLayer = weights.cross_layer;
+            }
+            delete weights.cross_layer;
+            drift.weights = weights;
+        }
+        normalized.drift = drift;
+    }
+    if (input.guard) {
+        const guard = { ...input.guard };
+        if (!guard.mode && typeof guard.guard_mode !== "undefined") {
+            guard.mode = guard.guard_mode;
+        }
+        delete guard.guard_mode;
+        normalized.guard = guard;
+    }
+    if (input.llm) {
+        const llm = { ...input.llm };
+        if (!llm.timeoutMs && typeof llm.timeout_ms !== "undefined") {
+            llm.timeoutMs = llm.timeout_ms;
+        }
+        delete llm.timeout_ms;
+        if (!llm.promptTemplate && typeof llm.prompt_template !== "undefined") {
+            llm.promptTemplate = llm.prompt_template;
+        }
+        delete llm.prompt_template;
+        if (!llm.args && typeof llm.arguments !== "undefined") {
+            llm.args = llm.arguments;
+        }
+        delete llm.arguments;
+        normalized.llm = llm;
+    }
+    if (input.docs) {
+        const docs = { ...input.docs };
+        if (!docs.mode && typeof docs.docs_mode !== "undefined") {
+            docs.mode = docs.docs_mode;
+        }
+        delete docs.docs_mode;
+        if (!docs.internalDir && typeof docs.internal_dir !== "undefined") {
+            docs.internalDir = docs.internal_dir;
+        }
+        delete docs.internal_dir;
+        normalized.docs = docs;
+    }
+    return normalized;
+}
+function mergeConfig(base, override) {
+    return {
+        project: {
+            root: override.project?.root ?? base.project?.root ?? "",
+            backendRoot: override.project?.backendRoot ?? base.project?.backendRoot ?? "",
+            frontendRoot: override.project?.frontendRoot ?? base.project?.frontendRoot ?? "",
+            discovery: {
+                enabled: override.project?.discovery?.enabled ??
+                    base.project?.discovery?.enabled ??
+                    true
+            },
+            description: override.project?.description ?? base.project?.description ?? "",
+            readmePath: override.project?.readmePath ?? base.project?.readmePath ?? ""
+        },
+        ignore: {
+            directories: mergeArrays(base.ignore?.directories, override.ignore?.directories),
+            paths: mergeArrays(base.ignore?.paths, override.ignore?.paths)
+        },
+        python: {
+            absoluteImportRoots: mergeArrays(base.python?.absoluteImportRoots, override.python?.absoluteImportRoots)
+        },
+        frontend: {
+            routeDirs: mergeArrays(base.frontend?.routeDirs, override.frontend?.routeDirs),
+            aliases: {
+                ...(base.frontend?.aliases ?? {}),
+                ...(override.frontend?.aliases ?? {})
+            },
+            tsconfigPath: override.frontend?.tsconfigPath || base.frontend?.tsconfigPath || ""
+        },
+        drift: {
+            graphLevel: override.drift?.graphLevel || base.drift?.graphLevel || "module",
+            scales: mergeArrays(base.drift?.scales, override.drift?.scales),
+            weights: {
+                entropy: override.drift?.weights?.entropy ?? base.drift?.weights?.entropy ?? 0.4,
+                crossLayer: override.drift?.weights?.crossLayer ?? base.drift?.weights?.crossLayer ?? 0.3,
+                cycles: override.drift?.weights?.cycles ?? base.drift?.weights?.cycles ?? 0.2,
+                modularity: override.drift?.weights?.modularity ?? base.drift?.weights?.modularity ?? 0.1
+            },
+            layers: {
+                ...(base.drift?.layers ?? {}),
+                ...(override.drift?.layers ?? {})
+            },
+            domains: {
+                ...(base.drift?.domains ?? {}),
+                ...(override.drift?.domains ?? {})
+            },
+            capacity: {
+                layers: {
+                    ...(base.drift?.capacity?.layers ?? {}),
+                    ...(override.drift?.capacity?.layers ?? {})
+                },
+                total: override.drift?.capacity?.total ?? base.drift?.capacity?.total ?? 0,
+                warningRatio: override.drift?.capacity?.warningRatio ??
+                    base.drift?.capacity?.warningRatio ??
+                    0.85,
+                criticalRatio: override.drift?.capacity?.criticalRatio ??
+                    base.drift?.capacity?.criticalRatio ??
+                    1.0
+            },
+            growth: {
+                maxEdgesPerHour: override.drift?.growth?.maxEdgesPerHour ??
+                    base.drift?.growth?.maxEdgesPerHour ??
+                    0,
+                maxEdgesPerDay: override.drift?.growth?.maxEdgesPerDay ??
+                    base.drift?.growth?.maxEdgesPerDay ??
+                    0,
+                maxEdgeGrowthRatio: override.drift?.growth?.maxEdgeGrowthRatio ??
+                    base.drift?.growth?.maxEdgeGrowthRatio ??
+                    0
+            },
+            baselinePath: override.drift?.baselinePath || base.drift?.baselinePath || "",
+            historyPath: override.drift?.historyPath || base.drift?.historyPath || "",
+            criticalDelta: override.drift?.criticalDelta ?? base.drift?.criticalDelta ?? 0.25
+        },
+        guard: {
+            mode: override.guard?.mode || base.guard?.mode || "soft"
+        },
+        llm: {
+            command: override.llm?.command ?? base.llm?.command ?? "",
+            args: mergeArrays(base.llm?.args, override.llm?.args),
+            timeoutMs: override.llm?.timeoutMs ?? base.llm?.timeoutMs ?? 120000,
+            promptTemplate: override.llm?.promptTemplate ?? base.llm?.promptTemplate ?? ""
+        },
+        docs: {
+            mode: override.docs?.mode ?? base.docs?.mode ?? "lean",
+            internalDir: override.docs?.internalDir ?? base.docs?.internalDir ?? "internal"
+        }
+    };
+}
+function mergeArrays(base, override) {
+    const result = new Set();
+    for (const entry of base ?? []) {
+        result.add(entry);
+    }
+    for (const entry of override ?? []) {
+        result.add(entry);
+    }
+    return Array.from(result);
+}
+async function resolveConfigPath(options) {
+    if (options.configPath) {
+        const resolved = path.resolve(options.configPath);
+        const stat = await safeStat(resolved);
+        if (stat?.isDirectory()) {
+            for (const name of ["guardian.config.json", "specguard.config.json"]) {
+                const candidate = path.join(resolved, name);
+                if (await fileExists(candidate)) {
+                    return candidate;
+                }
+            }
+            throw new Error(`guardian.config.json not found in ${resolved}`);
+        }
+        if (stat?.isFile()) {
+            return resolved;
+        }
+        throw new Error(`Config path not found: ${resolved}`);
+    }
+    const roots = uniquePaths([
+        options.projectRoot,
+        options.backendRoot,
+        options.frontendRoot
+    ].filter((entry) => typeof entry === "string" && entry.length > 0));
+    const commonRoot = roots.length > 0 ? findCommonRoot(roots) : process.cwd();
+    // Check guardian.config.json first, fall back to specguard.config.json
+    const guardianCandidate = path.join(commonRoot, "guardian.config.json");
+    if (await fileExists(guardianCandidate)) {
+        return guardianCandidate;
+    }
+    const specguardCandidate = path.join(commonRoot, "specguard.config.json");
+    if (await fileExists(specguardCandidate)) {
+        return specguardCandidate;
+    }
+    return null;
+}
+function findCommonRoot(paths) {
+    if (paths.length === 0) {
+        return process.cwd();
+    }
+    const splitPaths = paths.map((p) => path.resolve(p).split(path.sep));
+    const minLength = Math.min(...splitPaths.map((parts) => parts.length));
+    const shared = [];
+    for (let i = 0; i < minLength; i += 1) {
+        const segment = splitPaths[0][i];
+        if (splitPaths.every((parts) => parts[i] === segment)) {
+            shared.push(segment);
+        }
+        else {
+            break;
+        }
+    }
+    if (shared.length === 0) {
+        return path.parse(paths[0]).root;
+    }
+    return shared.join(path.sep);
+}
+function uniquePaths(paths) {
+    const seen = new Set();
+    const result = [];
+    for (const entry of paths) {
+        const resolved = path.resolve(entry);
+        if (!seen.has(resolved)) {
+            seen.add(resolved);
+            result.push(resolved);
+        }
+    }
+    return result;
+}
+async function fileExists(filePath) {
+    try {
+        const stat = await fs.stat(filePath);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function safeStat(filePath) {
+    try {
+        return await fs.stat(filePath);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/extract/ai-context-hints.js

@@ -0,0 +1,107 @@
+/**
+ * Small utilities that treat architecture-context.md as the planning surface.
+ * Used to validate how far compact AI context can carry implementation work.
+ */
+const COUPLING_LINE = /^-\s+(.+?)\s+\(score\s+([\d.]+)\)\s*$/;
+function tokenizeQuery(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9/_-]+/i)
+        .filter((t) => t.length > 0);
+}
+/** Strip leading "<package>/" so paths match the in-repo layout. */
+export function toRepoRelativePath(absoluteFromContext, packageName) {
+    const prefix = `${packageName}/`;
+    return absoluteFromContext.startsWith(prefix)
+        ? absoluteFromContext.slice(prefix.length)
+        : absoluteFromContext;
+}
+export function parseArchitectureContext(markdown) {
+    const projectMatch = markdown.match(/Project:\s+\*\*([^*]+)\*\*/);
+    const workspaceMatch = markdown.match(/Workspace:\s+`([^`]+)`/);
+    const backendMatch = markdown.match(/^Backend:\s+`([^`]+)`/m);
+    const frontendMatch = markdown.match(/^Frontend:\s+`([^`]+)`/m);
+    const backendSummaryMatch = markdown.match(/^\*\*Backend:\*\*\s*(.+)$/m);
+    const siMatch = markdown.match(/^-\s+scripts:\s*(.+)$/m);
+    const generatedMatch = markdown.match(/generated=(\d{4}-\d{2}-\d{2}T[^Z]+Z)/);
+    const highCoupling = [];
+    for (const line of markdown.split("\n")) {
+        const m = line.match(COUPLING_LINE);
+        if (m) {
+            highCoupling.push({ path: m[1].trim(), score: Number(m[2]) });
+        }
+    }
+    const behavioralTests = [];
+    const testRe = /`([^`]+\.test\.ts)`/g;
+    let tm;
+    while ((tm = testRe.exec(markdown)) !== null) {
+        behavioralTests.push(tm[1]);
+    }
+    let generatedAt = null;
+    if (generatedMatch) {
+        const d = new Date(generatedMatch[1]);
+        generatedAt = Number.isNaN(d.getTime()) ? null : d;
+    }
+    return {
+        projectName: projectMatch?.[1].trim() ?? null,
+        workspace: workspaceMatch?.[1] ?? null,
+        backendRoot: backendMatch?.[1] ?? null,
+        frontendRoot: frontendMatch?.[1] ?? null,
+        backendSummaryLine: backendSummaryMatch?.[1].trim() ?? null,
+        structuralIntelligenceLine: siMatch?.[1].trim() ?? null,
+        highCoupling,
+        behavioralTests,
+        generatedAt
+    };
+}
+/**
+ * Rank high-coupling files by overlap between query tokens and path segments.
+ */
+export function suggestImplementationFiles(parsed, query, limit = 6) {
+    const pkg = parsed.projectName ?? "specguard";
+    const terms = tokenizeQuery(query);
+    const scored = parsed.highCoupling.map((c) => {
+        const rel = toRepoRelativePath(c.path, pkg);
+        const hay = `${c.path} ${rel}`.toLowerCase();
+        const overlap = terms.filter((t) => hay.includes(t)).length;
+        const rank = overlap * 100 + c.score * 10;
+        return { rel, rank };
+    });
+    scored.sort((a, b) => b.rank - a.rank);
+    const out = [];
+    const seen = new Set();
+    for (const { rel } of scored) {
+        if (seen.has(rel))
+            continue;
+        seen.add(rel);
+        out.push(rel);
+        if (out.length >= limit)
+            break;
+    }
+    return out;
+}
+/**
+ * Point at behavioral tests whose paths mention query tokens.
+ */
+export function suggestBehavioralTests(parsed, query, limit = 6) {
+    const pkg = parsed.projectName ?? "specguard";
+    const terms = tokenizeQuery(query);
+    const hits = [];
+    for (const raw of parsed.behavioralTests) {
+        const rel = toRepoRelativePath(raw, pkg);
+        const hay = `${raw} ${rel}`.toLowerCase();
+        if (terms.some((t) => hay.includes(t))) {
+            hits.push(rel);
+        }
+    }
+    return hits.slice(0, limit);
+}
+/** Very rough tokenizer proxy (benchmark-style char/4 heuristic). */
+export function estimateTokensApprox(text) {
+    return Math.ceil(text.length / 4);
+}
+export function isContextStale(generatedAt, maxAgeMs, nowMs = Date.now()) {
+    if (!generatedAt)
+        return true;
+    return nowMs - generatedAt.getTime() > maxAgeMs;
+}