@toolbaux/guardian 0.1.0

package/dist/commands/init.js

@@ -0,0 +1,209 @@
+/**
+ * `guardian init` — initialize guardian for a project.
+ *
+ * Creates:
+ *   1. guardian.config.json (if missing)
+ *   2. .specs/ directory
+ *   3. Pre-commit hook that auto-runs extract + context injection
+ *   4. Injects guardian context block into CLAUDE.md
+ *   5. Adds .specs/ to .gitignore exclusion (tracked by default)
+ *
+ * Safe to run multiple times — only creates what's missing.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_CONFIG = {
+    project: {
+        backendRoot: "./backend",
+        frontendRoot: "./frontend",
+    },
+    docs: {
+        mode: "full",
+    },
+};
+const HOOK_SCRIPT = `#!/bin/sh
+# guardian pre-commit hook — keeps architecture context fresh
+# Installed by: guardian init
+
+# Only run if guardian is available
+if ! command -v guardian >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Run extract + ai-context generation (fast, ~2-5s)
+guardian extract --output .specs 2>/dev/null
+guardian generate --ai-context --output .specs 2>/dev/null
+
+# Inject context into CLAUDE.md if it exists
+if [ -f CLAUDE.md ]; then
+  guardian context --input .specs --output CLAUDE.md 2>/dev/null
+fi
+
+# Auto-stage the updated files
+git add .specs/machine/architecture-context.md 2>/dev/null
+git add CLAUDE.md 2>/dev/null
+
+exit 0
+`;
+export async function runInit(options) {
+    const root = path.resolve(options.projectRoot || process.cwd());
+    const specsDir = path.join(root, options.output || ".specs");
+    console.log(`Initializing Guardian in ${root}\n`);
+    // 1. Create .specs/ directory
+    await fs.mkdir(path.join(specsDir, "machine", "docs"), { recursive: true });
+    await fs.mkdir(path.join(specsDir, "human", "docs"), { recursive: true });
+    console.log("  ✓ Created .specs/ directory");
+    // 2. Create guardian.config.json if missing
+    const configPath = path.join(root, "guardian.config.json");
+    if (!(await fileExists(configPath))) {
+        const config = { ...DEFAULT_CONFIG };
+        // Auto-detect roots
+        if (options.backendRoot) {
+            config.project.backendRoot = options.backendRoot;
+        }
+        else {
+            for (const candidate of ["./backend", "./server", "./api", "./src"]) {
+                if (await dirExists(path.join(root, candidate))) {
+                    config.project.backendRoot = candidate;
+                    break;
+                }
+            }
+        }
+        if (options.frontendRoot) {
+            config.project.frontendRoot = options.frontendRoot;
+        }
+        else {
+            for (const candidate of ["./frontend", "./client", "./web", "./app"]) {
+                if (await dirExists(path.join(root, candidate))) {
+                    config.project.frontendRoot = candidate;
+                    break;
+                }
+            }
+        }
+        await fs.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+        console.log(`  ✓ Created guardian.config.json (backend: ${config.project.backendRoot}, frontend: ${config.project.frontendRoot})`);
+    }
+    else {
+        console.log("  · guardian.config.json already exists");
+    }
+    // 3. Install pre-commit hook
+    if (!options.skipHook) {
+        const gitDir = path.join(root, ".git");
+        if (await dirExists(gitDir)) {
+            const hooksDir = path.join(gitDir, "hooks");
+            await fs.mkdir(hooksDir, { recursive: true });
+            const hookPath = path.join(hooksDir, "pre-commit");
+            let shouldInstall = true;
+            if (await fileExists(hookPath)) {
+                const existing = await fs.readFile(hookPath, "utf8");
+                if (existing.includes("guardian")) {
+                    console.log("  · Pre-commit hook already has guardian");
+                    shouldInstall = false;
+                }
+                else {
+                    // Append to existing hook
+                    const appended = existing.trimEnd() + "\n\n" + HOOK_SCRIPT.split("\n").slice(1).join("\n");
+                    await fs.writeFile(hookPath, appended, "utf8");
+                    await fs.chmod(hookPath, 0o755);
+                    console.log("  ✓ Appended guardian to existing pre-commit hook");
+                    shouldInstall = false;
+                }
+            }
+            if (shouldInstall) {
+                await fs.writeFile(hookPath, HOOK_SCRIPT, "utf8");
+                await fs.chmod(hookPath, 0o755);
+                console.log("  ✓ Installed pre-commit hook (.git/hooks/pre-commit)");
+            }
+        }
+        else {
+            console.log("  · No .git directory found — skipping hook installation");
+        }
+    }
+    // 4. Inject context block into CLAUDE.md
+    const claudeMdPath = path.join(root, "CLAUDE.md");
+    if (await fileExists(claudeMdPath)) {
+        const existing = await fs.readFile(claudeMdPath, "utf8");
+        if (!existing.includes("guardian:auto-context")) {
+            const block = [
+                "",
+                "<!-- guardian:auto-context -->",
+                "<!-- This block is auto-updated by guardian. Do not edit manually. -->",
+                `<!-- Run: guardian extract --output .specs && guardian context --input .specs --output CLAUDE.md -->`,
+                "<!-- /guardian:auto-context -->",
+                "",
+            ].join("\n");
+            await fs.writeFile(claudeMdPath, existing.trimEnd() + "\n" + block, "utf8");
+            console.log("  ✓ Added guardian placeholder to CLAUDE.md");
+        }
+        else {
+            console.log("  · CLAUDE.md already has guardian context block");
+        }
+    }
+    else {
+        // Create minimal CLAUDE.md
+        const projectName = path.basename(root);
+        const content = [
+            `# ${projectName}`,
+            "",
+            "## SpecGuard Architecture Context",
+            "",
+            "<!-- guardian:auto-context -->",
+            "<!-- This block is auto-updated by guardian. Do not edit manually. -->",
+            `<!-- Run: guardian extract --output .specs && guardian context --input .specs --output CLAUDE.md -->`,
+            "<!-- /guardian:auto-context -->",
+            "",
+        ].join("\n");
+        await fs.writeFile(claudeMdPath, content, "utf8");
+        console.log("  ✓ Created CLAUDE.md with guardian context block");
+    }
+    // 5. Run initial extract + context injection
+    console.log("\n  Running initial extraction...");
+    try {
+        const { runExtract } = await import("./extract.js");
+        await runExtract({
+            projectRoot: root,
+            backendRoot: options.backendRoot,
+            frontendRoot: options.frontendRoot,
+            output: specsDir,
+            includeFileGraph: true,
+        });
+        const { runGenerate } = await import("./generate.js");
+        await runGenerate({
+            projectRoot: root,
+            backendRoot: options.backendRoot,
+            frontendRoot: options.frontendRoot,
+            output: specsDir,
+            aiContext: true,
+        });
+        // Inject context into CLAUDE.md
+        const { runContext } = await import("./context.js");
+        await runContext({
+            input: specsDir,
+            output: claudeMdPath,
+        });
+        console.log("\n✓ SpecGuard initialized. Architecture context is in CLAUDE.md and .specs/");
+        console.log("  Pre-commit hook will keep it fresh on every commit.");
+    }
+    catch (err) {
+        console.error(`\n  ⚠ Initial extraction failed: ${err.message}`);
+        console.log("  Run manually: guardian extract --output .specs");
+    }
+}
+async function fileExists(p) {
+    try {
+        const stat = await fs.stat(p);
+        return stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function dirExists(p) {
+    try {
+        const stat = await fs.stat(p);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/commands/intel.js

@@ -0,0 +1,20 @@
+/**
+ * `specguard intel` — build codebase-intelligence.json from existing snapshots.
+ *
+ * Reads:  specs-out/machine/architecture.snapshot.yaml + ux.snapshot.yaml
+ * Writes: specs-out/machine/codebase-intelligence.json
+ *
+ * Also auto-runs at the end of `specguard extract`.
+ */
+import path from "node:path";
+import { writeCodebaseIntelligence } from "../extract/codebase-intel.js";
+import { getOutputLayout } from "../output-layout.js";
+export async function runIntel(options) {
+    const specsDir = path.resolve(options.specs);
+    const layout = getOutputLayout(specsDir);
+    const outputPath = options.output
+        ? path.resolve(options.output)
+        : path.join(layout.machineDir, "codebase-intelligence.json");
+    await writeCodebaseIntelligence(specsDir, outputPath);
+    console.log(`Wrote ${outputPath}`);
+}

package/dist/commands/license-dependency-auditor.js

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import path from 'path';
+export async function run() {
+    const root = process.cwd();
+    const pkgPath = path.join(root, 'package.json');
+    let pkg = {};
+    try {
+        pkg = JSON.parse(await fs.promises.readFile(pkgPath, 'utf8'));
+    }
+    catch (_) { }
+    const deps = Object.keys(Object.assign({}, pkg.dependencies || {}, pkg.devDependencies || {}));
+    const results = [];
+    for (const d of deps) {
+        try {
+            const p = path.join(root, 'node_modules', d, 'package.json');
+            const text = await fs.promises.readFile(p, 'utf8');
+            const pj = JSON.parse(text);
+            results.push({ name: d, license: pj.license || pj.licenses && pj.licenses[0] && pj.licenses[0].type });
+        }
+        catch (_) {
+            results.push({ name: d, license: 'UNKNOWN' });
+        }
+    }
+    const out = path.join(root, 'out', 'license-audit.json');
+    await fs.promises.mkdir(path.dirname(out), { recursive: true });
+    await fs.promises.writeFile(out, JSON.stringify(results, null, 2), 'utf8');
+    console.log('Wrote license audit to', out);
+    return results;
+}
+const _isMain = (typeof require !== 'undefined' && (require.main === module)) || (process.argv[1] && process.argv[1].endsWith('license-dependency-auditor.ts'));
+if (_isMain) {
+    run().catch(err => { console.error(err); process.exit(1); });
+}

package/dist/commands/performance-hotspot-profiler.js

@@ -0,0 +1,42 @@
+import fs from 'fs';
+import path from 'path';
+async function readDirRecursive(dir) {
+    try {
+        const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+        const files = [];
+        for (const e of entries) {
+            const res = path.join(dir, e.name);
+            if (e.isDirectory())
+                files.push(...await readDirRecursive(res));
+            else
+                files.push(res);
+        }
+        return files;
+    }
+    catch (err) {
+        return [];
+    }
+}
+export async function run() {
+    const root = process.cwd();
+    const srcDir = path.join(root, 'src');
+    const files = await readDirRecursive(srcDir);
+    const candidates = [];
+    for (const f of files) {
+        if (!f.endsWith('.ts') && !f.endsWith('.js'))
+            continue;
+        const text = await fs.promises.readFile(f, 'utf8');
+        const ln = text.split('\n').length;
+        if (ln > 200)
+            candidates.push({ file: path.relative(root, f), lines: ln });
+    }
+    const out = path.join(root, 'out', 'perf-hotspots.json');
+    await fs.promises.mkdir(path.dirname(out), { recursive: true });
+    await fs.promises.writeFile(out, JSON.stringify(candidates, null, 2), 'utf8');
+    console.log('Wrote performance hotspots to', out);
+    return candidates;
+}
+const _isMain = (typeof require !== 'undefined' && (require.main === module)) || (process.argv[1] && process.argv[1].endsWith('performance-hotspot-profiler.ts'));
+if (_isMain) {
+    run().catch(err => { console.error(err); process.exit(1); });
+}

package/dist/commands/search.js

@@ -0,0 +1,314 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import yaml from "js-yaml";
+import { loadHeatmap } from "../extract/compress.js";
+import { resolveMachineInputDir } from "../output-layout.js";
+export async function runSearch(options) {
+    const inputDir = await resolveMachineInputDir(options.input || "specs-out");
+    const { architecture, ux } = await loadSnapshots(inputDir);
+    const heatmap = await loadHeatmap(inputDir);
+    const types = normalizeTypes(options.types);
+    const matches = searchSnapshots({
+        architecture,
+        ux,
+        query: options.query,
+        types,
+        heatmap
+    });
+    const content = renderSearchMarkdown(options.query, matches);
+    if (options.output) {
+        const outputPath = path.resolve(options.output);
+        await fs.mkdir(path.dirname(outputPath), { recursive: true });
+        await fs.writeFile(outputPath, content, "utf8");
+        console.log(`Wrote ${outputPath}`);
+        return;
+    }
+    console.log(content);
+}
+async function loadSnapshots(inputDir) {
+    const architecturePath = path.join(inputDir, "architecture.snapshot.yaml");
+    const uxPath = path.join(inputDir, "ux.snapshot.yaml");
+    let architectureRaw;
+    let uxRaw;
+    try {
+        [architectureRaw, uxRaw] = await Promise.all([
+            fs.readFile(architecturePath, "utf8"),
+            fs.readFile(uxPath, "utf8")
+        ]);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error(`Could not find snapshots in ${inputDir}. Run \`specguard extract\` first.`);
+        }
+        throw error;
+    }
+    return {
+        architecture: yaml.load(architectureRaw),
+        ux: yaml.load(uxRaw)
+    };
+}
+function normalizeTypes(types) {
+    if (!types || types.length === 0) {
+        return new Set(["models", "endpoints", "components", "modules", "tasks"]);
+    }
+    const normalized = new Set();
+    for (const entry of types) {
+        for (const part of entry.split(",").map((value) => value.trim().toLowerCase())) {
+            if (part === "models" ||
+                part === "endpoints" ||
+                part === "components" ||
+                part === "modules" ||
+                part === "tasks") {
+                normalized.add(part);
+            }
+        }
+    }
+    return normalized.size > 0
+        ? normalized
+        : new Set(["models", "endpoints", "components", "modules", "tasks"]);
+}
+function tokenize(value) {
+    return value
+        .toLowerCase()
+        .split(/[^a-z0-9_/.{}-]+/)
+        .map((token) => token.trim())
+        .filter(Boolean);
+}
+function scoreItem(queryTokens, item) {
+    if (queryTokens.length === 0) {
+        return 0;
+    }
+    const normalizedName = item.name.toLowerCase();
+    const normalizedFile = (item.file ?? "").toLowerCase();
+    const normalizedText = item.text
+        .filter((entry) => typeof entry === "string")
+        .map((entry) => entry.toLowerCase());
+    let total = 0;
+    for (const token of queryTokens) {
+        if (normalizedName === token) {
+            total += 1;
+            continue;
+        }
+        if (normalizedName.includes(token)) {
+            total += 0.7;
+            continue;
+        }
+        if (normalizedText.some((entry) => entry.includes(token))) {
+            total += 0.4;
+            continue;
+        }
+        if (normalizedFile.includes(token)) {
+            total += 0.2;
+            continue;
+        }
+    }
+    const phrase = queryTokens.join(" ");
+    if (phrase && normalizedName.includes(phrase)) {
+        total += 0.15;
+    }
+    return Math.min(1, total / queryTokens.length);
+}
+function searchSnapshots(params) {
+    const { architecture, ux, query, types, heatmap } = params;
+    const queryTokens = tokenize(query);
+    const matches = [];
+    const pageUsage = buildComponentPageUsage(ux);
+    const moduleHeatmap = new Map((heatmap?.levels.find((level) => level.level === "module")?.entries ?? []).map((entry) => [
+        entry.id,
+        entry.score
+    ]));
+    if (types.has("models")) {
+        for (const model of architecture.data_models) {
+            const score = scoreItem(queryTokens, {
+                name: model.name,
+                file: model.file,
+                text: [...model.fields, ...model.relationships, model.framework]
+            });
+            if (score <= 0) {
+                continue;
+            }
+            matches.push({
+                type: "models",
+                name: model.name,
+                score,
+                markdown: [
+                    `**${model.name}** · ${model.file}`,
+                    `Fields: ${formatList(model.fields, 8)}`,
+                    `Relations: ${formatList(model.relationships, 8)}`
+                ]
+            });
+        }
+    }
+    if (types.has("endpoints")) {
+        for (const endpoint of architecture.endpoints) {
+            const score = scoreItem(queryTokens, {
+                name: `${endpoint.method} ${endpoint.path}`,
+                file: endpoint.file,
+                text: [
+                    endpoint.handler,
+                    endpoint.module,
+                    endpoint.request_schema ?? "",
+                    endpoint.response_schema ?? "",
+                    ...endpoint.service_calls
+                ]
+            });
+            if (score <= 0) {
+                continue;
+            }
+            matches.push({
+                type: "endpoints",
+                name: `${endpoint.method} ${endpoint.path}`,
+                score,
+                markdown: [
+                    `${endpoint.method.padEnd(4, " ")} ${endpoint.path} → ${endpoint.handler} (${endpoint.file})`,
+                    `Module: ${endpoint.module} · Request: ${endpoint.request_schema ?? "none"} · Response: ${endpoint.response_schema ?? "none"}`
+                ]
+            });
+        }
+    }
+    if (types.has("components")) {
+        for (const component of ux.components) {
+            const score = scoreItem(queryTokens, {
+                name: component.name,
+                file: component.file,
+                text: [
+                    component.kind,
+                    component.export_kind,
+                    ...(component.props ?? []).map((prop) => `${prop.name}:${prop.type}`)
+                ]
+            });
+            if (score <= 0) {
+                continue;
+            }
+            matches.push({
+                type: "components",
+                name: component.name,
+                score,
+                markdown: [
+                    `**${component.name}** · ${component.file} · import: ${component.export_kind ?? "unknown"}`,
+                    `Props: ${formatProps(component.props)}`,
+                    `Used by: ${formatList(pageUsage.get(component.id) ?? [], 4)}`
+                ]
+            });
+        }
+    }
+    if (types.has("modules")) {
+        for (const module of architecture.modules) {
+            const score = scoreItem(queryTokens, {
+                name: module.id,
+                file: module.path,
+                text: [...module.files, ...module.endpoints, ...module.imports]
+            });
+            if (score <= 0) {
+                continue;
+            }
+            const couplingScore = moduleHeatmap.get(module.id);
+            matches.push({
+                type: "modules",
+                name: module.id,
+                score,
+                markdown: [
+                    `**${module.id}** · ${module.path} · ${module.files.length} files${typeof couplingScore === "number"
+                        ? ` · coupling score: ${couplingScore.toFixed(2)}`
+                        : ""}`,
+                    `Contains: ${formatList(module.files, 4)}`
+                ]
+            });
+        }
+    }
+    if (types.has("tasks")) {
+        for (const task of architecture.tasks) {
+            const score = scoreItem(queryTokens, {
+                name: task.name,
+                file: task.file,
+                text: [task.kind, task.queue ?? "", task.schedule ?? ""]
+            });
+            if (score <= 0) {
+                continue;
+            }
+            matches.push({
+                type: "tasks",
+                name: task.name,
+                score,
+                markdown: [
+                    `**${task.name}** · ${task.file}`,
+                    `Kind: ${task.kind}${task.queue ? ` · Queue: ${task.queue}` : ""}${task.schedule ? ` · Schedule: ${task.schedule}` : ""}`
+                ]
+            });
+        }
+    }
+    return matches.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+}
+function buildComponentPageUsage(ux) {
+    const usage = new Map();
+    for (const page of ux.pages) {
+        const pageLabel = `${page.component} (${page.path})`;
+        const ids = new Set([
+            page.component_id,
+            ...page.components_direct_ids,
+            ...page.components_descendants_ids
+        ]);
+        for (const id of ids) {
+            const entry = usage.get(id) ?? new Set();
+            entry.add(pageLabel);
+            usage.set(id, entry);
+        }
+    }
+    return new Map(Array.from(usage.entries()).map(([id, pages]) => [
+        id,
+        Array.from(pages).sort((a, b) => a.localeCompare(b))
+    ]));
+}
+function formatList(items, limit) {
+    if (!items || items.length === 0) {
+        return "none";
+    }
+    if (items.length <= limit) {
+        return items.join(", ");
+    }
+    return `${items.slice(0, limit).join(", ")} +${items.length - limit} more`;
+}
+function formatProps(props) {
+    if (!props || props.length === 0) {
+        return "none";
+    }
+    return props
+        .slice(0, 6)
+        .map((prop) => `${prop.name}${prop.optional ? "?" : ""}: ${prop.type}`)
+        .join(", ");
+}
+function renderSearchMarkdown(query, matches) {
+    const grouped = new Map();
+    for (const match of matches) {
+        const entry = grouped.get(match.type) ?? [];
+        entry.push(match);
+        grouped.set(match.type, entry);
+    }
+    const labels = [
+        ["models", "Data Models"],
+        ["endpoints", "Endpoints"],
+        ["components", "Components"],
+        ["modules", "Modules"],
+        ["tasks", "Tasks"]
+    ];
+    const lines = [];
+    lines.push(`# Search: "${query}" - ${matches.length} matches`);
+    lines.push("");
+    if (matches.length === 0) {
+        lines.push("*No matches found.*");
+        return lines.join("\n");
+    }
+    for (const [type, label] of labels) {
+        const entries = grouped.get(type) ?? [];
+        if (entries.length === 0) {
+            continue;
+        }
+        lines.push(`## ${label} (${entries.length})`);
+        lines.push("");
+        for (const entry of entries.slice(0, 8)) {
+            lines.push(...entry.markdown);
+            lines.push("");
+        }
+    }
+    return lines.join("\n").trimEnd();
+}