@grafema/cli 0.1.1-alpha

package/dist/commands/check.js

@@ -0,0 +1,295 @@
+/**
+ * Check command - Check invariants/guarantees
+ *
+ * Supports two modes:
+ * 1. Rule-based: Check YAML-defined guarantees (default)
+ * 2. Built-in validators: --guarantee=<name> (e.g., --guarantee=node-creation)
+ */
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend, GuaranteeManager, NodeCreationValidator, GraphFreshnessChecker, IncrementalReanalyzer } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+// Available built-in validators
+const BUILT_IN_VALIDATORS = {
+    'node-creation': {
+        name: 'NodeCreationValidator',
+        description: 'Validates that all nodes are created through NodeFactory'
+    }
+};
+export const checkCommand = new Command('check')
+    .description('Check invariants/guarantees')
+    .argument('[rule]', 'Specific rule ID to check (or "all" for all rules)')
+    .option('-p, --project <path>', 'Project path', '.')
+    .option('-f, --file <path>', 'Path to guarantees YAML file')
+    .option('-g, --guarantee <name>', 'Run a built-in guarantee validator (e.g., node-creation)')
+    .option('-j, --json', 'Output results as JSON')
+    .option('-q, --quiet', 'Only output failures')
+    .option('--list-guarantees', 'List available built-in guarantees')
+    .option('--skip-reanalysis', 'Skip automatic reanalysis of stale modules')
+    .option('--fail-on-stale', 'Exit with error if stale modules found (CI mode)')
+    .action(async (rule, options) => {
+    // List available guarantees
+    if (options.listGuarantees) {
+        console.log('Available built-in guarantees:');
+        console.log('');
+        for (const [key, info] of Object.entries(BUILT_IN_VALIDATORS)) {
+            console.log(`  ${key}`);
+            console.log(`    ${info.description}`);
+            console.log('');
+        }
+        return;
+    }
+    // Run built-in guarantee validator
+    if (options.guarantee) {
+        const validatorInfo = BUILT_IN_VALIDATORS[options.guarantee];
+        if (!validatorInfo) {
+            const available = Object.keys(BUILT_IN_VALIDATORS).join(', ');
+            exitWithError(`Unknown guarantee: ${options.guarantee}`, [
+                `Available: ${available}`
+            ]);
+        }
+        await runBuiltInValidator(options.guarantee, options.project, {
+            json: options.json,
+            quiet: options.quiet,
+            skipReanalysis: options.skipReanalysis,
+            failOnStale: options.failOnStale
+        });
+        return;
+    }
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+    if (!existsSync(dbPath)) {
+        exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+    // Check graph freshness
+    const freshnessChecker = new GraphFreshnessChecker();
+    const freshness = await freshnessChecker.checkFreshness(backend);
+    if (!freshness.isFresh) {
+        if (options.failOnStale) {
+            console.error(`✗ Graph is stale: ${freshness.staleCount} module(s) changed`);
+            for (const stale of freshness.staleModules.slice(0, 5)) {
+                console.error(`  ${stale.file} (${stale.reason})`);
+            }
+            if (freshness.staleModules.length > 5) {
+                console.error(`  ... and ${freshness.staleModules.length - 5} more`);
+            }
+            console.error('');
+            console.error('→ Run: grafema analyze');
+            await backend.close();
+            process.exit(1);
+        }
+        if (!options.skipReanalysis) {
+            console.log(`Reanalyzing ${freshness.staleCount} stale module(s)...`);
+            const reanalyzer = new IncrementalReanalyzer(backend, projectPath);
+            const result = await reanalyzer.reanalyze(freshness.staleModules);
+            console.log(`Reanalyzed ${result.modulesReanalyzed} module(s) in ${result.durationMs}ms`);
+            console.log('');
+        }
+        else {
+            console.warn(`Warning: ${freshness.staleCount} stale module(s) detected. Use --skip-reanalysis to suppress.`);
+            for (const stale of freshness.staleModules.slice(0, 5)) {
+                console.warn(`  - ${stale.file} (${stale.reason})`);
+            }
+            if (freshness.staleModules.length > 5) {
+                console.warn(`  ... and ${freshness.staleModules.length - 5} more`);
+            }
+            console.log('');
+        }
+    }
+    else if (!options.quiet) {
+        console.log('Graph is fresh');
+        console.log('');
+    }
+    try {
+        const guaranteeGraph = backend;
+        const manager = new GuaranteeManager(guaranteeGraph, projectPath);
+        // Load guarantees from file if specified
+        const guaranteesFile = options.file || join(grafemaDir, 'guarantees.yaml');
+        if (existsSync(guaranteesFile)) {
+            await manager.import(guaranteesFile);
+        }
+        // Get all guarantees
+        const guarantees = await manager.list();
+        if (guarantees.length === 0) {
+            console.log('No guarantees found.');
+            console.log('');
+            console.log('Create guarantees in .grafema/guarantees.yaml or use --file option.');
+            return;
+        }
+        // Filter to specific rule if requested
+        const toCheck = rule && rule !== 'all'
+            ? guarantees.filter((g) => g.id === rule || g.name === rule)
+            : guarantees;
+        if (toCheck.length === 0 && rule) {
+            const available = guarantees.map((g) => g.id).join(', ');
+            exitWithError(`Guarantee not found: ${rule}`, [
+                `Available: ${available}`
+            ]);
+        }
+        // Check all matching guarantees
+        const results = await manager.checkAll();
+        // Filter results to only requested rules
+        const filteredResults = rule && rule !== 'all'
+            ? {
+                ...results,
+                results: results.results.filter((r) => toCheck.some((g) => g.id === r.guaranteeId)),
+            }
+            : results;
+        if (options.json) {
+            console.log(JSON.stringify(filteredResults, null, 2));
+        }
+        else {
+            if (!options.quiet) {
+                console.log(`Checking ${filteredResults.results.length} guarantee(s)...`);
+                console.log('');
+            }
+            for (const result of filteredResults.results) {
+                if (options.quiet && result.passed)
+                    continue;
+                const status = result.passed ? '✓' : '✗';
+                const color = result.passed ? '\x1b[32m' : '\x1b[31m';
+                const reset = '\x1b[0m';
+                console.log(`${color}${status}${reset} ${result.guaranteeId}: ${result.name}`);
+                if (!result.passed && result.violations.length > 0) {
+                    console.log(`  Violations (${result.violationCount}):`);
+                    for (const v of result.violations.slice(0, 10)) {
+                        // Prefer nodeId (semantic ID) for queryability
+                        const identifier = v.nodeId || (v.file ? `${v.file}${v.line ? `:${v.line}` : ''}` : '(unknown)');
+                        console.log(`    - ${identifier}`);
+                        if (v.name || v.type) {
+                            console.log(`      ${v.name || ''} (${v.type || 'unknown'})`);
+                        }
+                    }
+                    if (result.violations.length > 10) {
+                        console.log(`    ... and ${result.violations.length - 10} more`);
+                    }
+                }
+                if (result.error) {
+                    console.log(`  Error: ${result.error}`);
+                }
+            }
+            console.log('');
+            console.log(`Summary: ${filteredResults.passed}/${filteredResults.total} passed`);
+            if (filteredResults.failed > 0) {
+                process.exit(1);
+            }
+        }
+    }
+    finally {
+        await backend.close();
+    }
+});
+/**
+ * Run a built-in validator
+ */
+async function runBuiltInValidator(guaranteeName, projectPath, options) {
+    const resolvedPath = resolve(projectPath);
+    const grafemaDir = join(resolvedPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+    if (!existsSync(dbPath)) {
+        exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+    // Check graph freshness
+    const freshnessChecker = new GraphFreshnessChecker();
+    const freshness = await freshnessChecker.checkFreshness(backend);
+    if (!freshness.isFresh) {
+        if (options.failOnStale) {
+            console.error(`✗ Graph is stale: ${freshness.staleCount} module(s) changed`);
+            for (const stale of freshness.staleModules.slice(0, 5)) {
+                console.error(`  ${stale.file} (${stale.reason})`);
+            }
+            if (freshness.staleModules.length > 5) {
+                console.error(`  ... and ${freshness.staleModules.length - 5} more`);
+            }
+            console.error('');
+            console.error('→ Run: grafema analyze');
+            await backend.close();
+            process.exit(1);
+        }
+        if (!options.skipReanalysis) {
+            console.log(`Reanalyzing ${freshness.staleCount} stale module(s)...`);
+            const reanalyzer = new IncrementalReanalyzer(backend, resolvedPath);
+            const result = await reanalyzer.reanalyze(freshness.staleModules);
+            console.log(`Reanalyzed ${result.modulesReanalyzed} module(s) in ${result.durationMs}ms`);
+            console.log('');
+        }
+        else {
+            console.warn(`Warning: ${freshness.staleCount} stale module(s) detected. Use --skip-reanalysis to suppress.`);
+            for (const stale of freshness.staleModules.slice(0, 5)) {
+                console.warn(`  - ${stale.file} (${stale.reason})`);
+            }
+            if (freshness.staleModules.length > 5) {
+                console.warn(`  ... and ${freshness.staleModules.length - 5} more`);
+            }
+            console.log('');
+        }
+    }
+    else if (!options.quiet) {
+        console.log('Graph is fresh');
+        console.log('');
+    }
+    try {
+        let validator;
+        let validatorName;
+        switch (guaranteeName) {
+            case 'node-creation':
+                validator = new NodeCreationValidator();
+                validatorName = 'NodeCreationValidator';
+                break;
+            default:
+                exitWithError(`Unknown guarantee: ${guaranteeName}`, [
+                    'Use --list-guarantees to see available options'
+                ]);
+        }
+        if (!options.quiet) {
+            console.log(`Running ${validatorName}...`);
+            console.log('');
+        }
+        const result = await validator.execute({
+            graph: backend,
+            projectPath: resolvedPath
+        });
+        const metadata = result.metadata;
+        if (options.json) {
+            console.log(JSON.stringify({
+                guarantee: guaranteeName,
+                passed: (metadata.summary?.totalViolations ?? 0) === 0,
+                ...metadata
+            }, null, 2));
+        }
+        else {
+            const violations = metadata.summary?.totalViolations ?? 0;
+            const issues = metadata.issues ?? [];
+            if (violations === 0) {
+                console.log('\x1b[32m✓\x1b[0m All checks passed');
+            }
+            else {
+                console.log(`\x1b[31m✗\x1b[0m Found ${violations} violation(s):`);
+                console.log('');
+                for (const issue of issues.slice(0, 10)) {
+                    const location = issue.file ? `${issue.file}${issue.line ? `:${issue.line}` : ''}` : '';
+                    console.log(`  \x1b[31m•\x1b[0m [${issue.type}] ${issue.message}`);
+                    if (issue.suggestion && !options.quiet) {
+                        console.log(`    Suggestion: ${issue.suggestion}`);
+                    }
+                }
+                if (issues.length > 10) {
+                    console.log(`  ... and ${issues.length - 10} more violations`);
+                }
+            }
+            console.log('');
+            if (violations > 0) {
+                process.exit(1);
+            }
+        }
+    }
+    finally {
+        await backend.close();
+    }
+}

package/dist/commands/coverage.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Coverage command - Show analysis coverage statistics
+ *
+ * Shows what percentage of the codebase has been analyzed:
+ * - Analyzed: Files in the graph as MODULE nodes
+ * - Unsupported: Files with extensions that no indexer handles
+ * - Unreachable: Files with supported extensions but not imported from entrypoints
+ */
+import { Command } from 'commander';
+export declare const coverageCommand: Command;
+//# sourceMappingURL=coverage.d.ts.map

package/dist/commands/coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage.d.ts","sourceRoot":"","sources":["../../src/commands/coverage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC,eAAO,MAAM,eAAe,SA6BxB,CAAC"}

package/dist/commands/coverage.js

@@ -0,0 +1,96 @@
+/**
+ * Coverage command - Show analysis coverage statistics
+ *
+ * Shows what percentage of the codebase has been analyzed:
+ * - Analyzed: Files in the graph as MODULE nodes
+ * - Unsupported: Files with extensions that no indexer handles
+ * - Unreachable: Files with supported extensions but not imported from entrypoints
+ */
+import { Command } from 'commander';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+import { RFDBServerBackend, CoverageAnalyzer } from '@grafema/core';
+import { exitWithError } from '../utils/errorFormatter.js';
+export const coverageCommand = new Command('coverage')
+    .description('Show analysis coverage statistics')
+    .option('-p, --project <path>', 'Project path', '.')
+    .option('-j, --json', 'Output as JSON')
+    .option('-v, --verbose', 'Show detailed file lists')
+    .action(async (options) => {
+    const projectPath = resolve(options.project);
+    const grafemaDir = join(projectPath, '.grafema');
+    const dbPath = join(grafemaDir, 'graph.rfdb');
+    if (!existsSync(dbPath)) {
+        exitWithError('No graph database found', ['Run: grafema analyze']);
+    }
+    const backend = new RFDBServerBackend({ dbPath });
+    await backend.connect();
+    try {
+        const analyzer = new CoverageAnalyzer(backend, projectPath);
+        const result = await analyzer.analyze();
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            printCoverageReport(result, options.verbose ?? false);
+        }
+    }
+    finally {
+        await backend.close();
+    }
+});
+/**
+ * Print human-readable coverage report
+ */
+function printCoverageReport(result, verbose) {
+    console.log('');
+    console.log('Analysis Coverage');
+    console.log('=================');
+    console.log('');
+    // Summary
+    console.log(`Project: ${result.projectPath}`);
+    console.log('');
+    // Main statistics
+    console.log('File breakdown:');
+    console.log(`  Total files:     ${result.total}`);
+    console.log(`  Analyzed:        ${result.analyzed.count} (${result.percentages.analyzed}%) - in graph`);
+    console.log(`  Unsupported:     ${result.unsupported.count} (${result.percentages.unsupported}%) - no indexer available`);
+    console.log(`  Unreachable:     ${result.unreachable.count} (${result.percentages.unreachable}%) - not imported from entrypoints`);
+    // Unsupported files breakdown
+    if (result.unsupported.count > 0) {
+        console.log('');
+        console.log('Unsupported files by extension:');
+        const sortedExtensions = Object.entries(result.unsupported.byExtension)
+            .sort((a, b) => b[1].length - a[1].length);
+        for (const [ext, files] of sortedExtensions) {
+            console.log(`  ${ext}: ${files.length} files`);
+            if (verbose) {
+                for (const file of files.slice(0, 10)) {
+                    console.log(`    - ${file}`);
+                }
+                if (files.length > 10) {
+                    console.log(`    ... and ${files.length - 10} more`);
+                }
+            }
+        }
+    }
+    // Unreachable files breakdown
+    if (result.unreachable.count > 0) {
+        console.log('');
+        console.log('Unreachable source files:');
+        const sortedExtensions = Object.entries(result.unreachable.byExtension)
+            .sort((a, b) => b[1].length - a[1].length);
+        for (const [ext, files] of sortedExtensions) {
+            console.log(`  ${ext}: ${files.length} files - not imported from entrypoints`);
+            if (verbose) {
+                for (const file of files.slice(0, 10)) {
+                    console.log(`    - ${file}`);
+                }
+                if (files.length > 10) {
+                    console.log(`    ... and ${files.length - 10} more`);
+                }
+            }
+        }
+    }
+    console.log('');
+}

package/dist/commands/explore.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Explore command - Interactive TUI for graph navigation
+ */
+import { Command } from 'commander';
+export declare const exploreCommand: Command;
+//# sourceMappingURL=explore.d.ts.map

package/dist/commands/explore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore.d.ts","sourceRoot":"","sources":["../../src/commands/explore.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2/BpC,eAAO,MAAM,cAAc,SAgCvB,CAAC"}