@know-graph/cli 0.4.0

package/dist/commands/suggest.js

@@ -0,0 +1,79 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: CLI command that suggests the most impactful files to annotate next
+ * owner: knowgraph-cli
+ * status: experimental
+ * tags: [cli, command, suggest, prioritization]
+ * context:
+ *   business_goal: Help developers prioritize which files to annotate first
+ *   domain: cli
+ */
+import { resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import chalk from 'chalk';
+import { createDefaultRegistry, createSuggestionEngine } from '@know-graph/core';
+function formatTextOutput(result) {
+    const lines = [];
+    if (result.suggestions.length === 0) {
+        lines.push(chalk.green('No unannotated files found. Great job!'));
+        return lines.join('\n');
+    }
+    lines.push(chalk.bold(`${result.totalUnannotated} unannotated files found, showing top ${result.suggestions.length}`));
+    lines.push('');
+    for (let i = 0; i < result.suggestions.length; i++) {
+        const suggestion = result.suggestions[i];
+        const rank = chalk.cyan(`${i + 1}.`);
+        const filePath = chalk.white(suggestion.filePath);
+        const score = chalk.yellow(`(score: ${suggestion.score})`);
+        const reasons = chalk.gray(`- ${suggestion.reasons.join(', ')}`);
+        lines.push(`${rank} ${filePath} ${score} ${reasons}`);
+    }
+    return lines.join('\n');
+}
+function formatJsonOutput(result) {
+    return JSON.stringify(result, null, 2);
+}
+function runSuggest(targetPath, options) {
+    const absPath = resolve(targetPath);
+    try {
+        statSync(absPath);
+    }
+    catch {
+        console.error(chalk.red(`Error: Path not found: ${absPath}`));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const registry = createDefaultRegistry();
+        const engine = createSuggestionEngine(registry);
+        const limit = parseInt(options.limit, 10);
+        if (Number.isNaN(limit) || limit < 1) {
+            console.error(chalk.red('Error: --limit must be a positive integer'));
+            process.exitCode = 1;
+            return;
+        }
+        const result = engine.suggest({ rootDir: absPath, limit });
+        if (options.format === 'json') {
+            console.log(formatJsonOutput(result));
+        }
+        else {
+            console.log(formatTextOutput(result));
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+        process.exitCode = 1;
+    }
+}
+export function registerSuggestCommand(program) {
+    program
+        .command('suggest [path]')
+        .description('Suggest the most impactful files to annotate next')
+        .option('--limit <n>', 'Number of suggestions to show', '10')
+        .option('--format <format>', 'Output format (text|json)', 'text')
+        .action((path, options) => {
+        runSuggest(path ?? '.', options);
+    });
+}
+//# sourceMappingURL=suggest.js.map

package/dist/commands/suggest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"suggest.js","sourceRoot":"","sources":["../../src/commands/suggest.ts"],"names":[],"mappings":"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"}

package/dist/commands/sync.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from 'commander';
+import type { ConnectorSyncResult } from '@know-graph/core';
+export declare function formatResult(result: ConnectorSyncResult, verbose: boolean): string;
+export declare function registerSyncCommand(program: Command): void;
+//# sourceMappingURL=sync.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASzC,OAAO,KAAK,EAEV,mBAAmB,EACpB,MAAM,kBAAkB,CAAC;AAkB1B,wBAAgB,YAAY,CAC1B,MAAM,EAAE,mBAAmB,EAC3B,OAAO,EAAE,OAAO,GACf,MAAM,CAsBR;AA8JD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwB1D"}

package/dist/commands/sync.js

@@ -0,0 +1,151 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: CLI command that syncs external knowledge connectors (Notion, Jira) with the code graph
+ * owner: knowgraph-cli
+ * status: experimental
+ * tags: [cli, command, sync, connectors]
+ * context:
+ *   business_goal: Let developers enrich their code knowledge graph with external tool metadata
+ *   domain: cli
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { parse as parseYaml } from 'yaml';
+import { createDefaultConnectorRegistry, createDatabaseManager, ManifestSchema, } from '@know-graph/core';
+function loadManifest(configPath) {
+    const raw = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(raw);
+    return ManifestSchema.safeParse(parsed);
+}
+export function formatResult(result, verbose) {
+    const lines = [];
+    const hasErrors = result.errors.length > 0;
+    const icon = hasErrors ? chalk.yellow('!') : chalk.green('\u2714');
+    lines.push(`${icon} ${chalk.bold(result.connector)} connector`);
+    lines.push(`  Processed ${chalk.cyan(String(result.entitiesProcessed))} entities, ` +
+        `added ${chalk.cyan(String(result.linksAdded))} links, ` +
+        `updated ${chalk.cyan(String(result.linksUpdated))} links ` +
+        `(${result.duration}ms)`);
+    if (hasErrors && verbose) {
+        for (const err of result.errors) {
+            lines.push(chalk.yellow(`  Error: ${err.message}`));
+        }
+    }
+    else if (hasErrors) {
+        lines.push(chalk.yellow(`  ${result.errors.length} error(s) occurred`));
+    }
+    return lines.join('\n');
+}
+async function runSync(connectorNames, options) {
+    const configPath = resolve(options.config ?? '.knowgraph.yml');
+    if (!existsSync(configPath)) {
+        console.error(chalk.red(`Error: Config not found: ${configPath}\nRun ${chalk.cyan('knowgraph init')} to create one.`));
+        process.exitCode = 1;
+        return;
+    }
+    const manifestResult = loadManifest(configPath);
+    if (!manifestResult.success) {
+        console.error(chalk.red(`Error: Invalid config: ${manifestResult.error.message}`));
+        process.exitCode = 1;
+        return;
+    }
+    const manifest = manifestResult.data;
+    const connectorConfigs = manifest.connectors ?? {};
+    // Determine which connectors to sync
+    const availableConnectors = Object.entries(connectorConfigs)
+        .filter(([, config]) => config && 'enabled' in config)
+        .map(([name]) => name)
+        .filter((name) => name !== 'webhook');
+    const requestedConnectors = connectorNames.length > 0
+        ? connectorNames.filter((n) => availableConnectors.includes(n))
+        : availableConnectors;
+    if (requestedConnectors.length === 0) {
+        console.log(chalk.yellow('No connectors configured. Add connectors to your .knowgraph.yml:'));
+        console.log(chalk.dim(`\nconnectors:\n  notion:\n    enabled: true\n    api_key_env: NOTION_API_KEY\n  jira:\n    enabled: true\n    api_key_env: JIRA_API_KEY\n    base_url: https://your-team.atlassian.net`));
+        return;
+    }
+    // Load database
+    const outputDir = resolve(manifest.index?.output_dir ?? '.knowgraph');
+    const dbPath = join(outputDir, 'knowgraph.db');
+    if (!existsSync(dbPath)) {
+        console.error(chalk.red(`Error: Database not found at ${dbPath}\nRun ${chalk.cyan('knowgraph index')} first.`));
+        process.exitCode = 1;
+        return;
+    }
+    const dbManager = createDatabaseManager(dbPath);
+    dbManager.initialize();
+    const spinner = ora(options.dryRun ? 'Previewing sync (dry run)...' : 'Syncing connectors...').start();
+    try {
+        const registry = createDefaultConnectorRegistry();
+        // Build configs map — only include requested connectors
+        const configs = {};
+        for (const name of requestedConnectors) {
+            const raw = connectorConfigs[name];
+            if (raw) {
+                configs[name] = raw;
+            }
+        }
+        // Build entity filter
+        const entityFilter = options.owner || options.tags
+            ? {
+                owner: options.owner,
+                tags: options.tags
+                    ?.split(',')
+                    .map((t) => t.trim())
+                    .filter(Boolean),
+            }
+            : undefined;
+        const results = await registry.syncAll({
+            dbManager,
+            configs,
+            entityFilter,
+            dryRun: options.dryRun ?? false,
+            onProgress: (name, result) => {
+                spinner.text = `Syncing ${name}... (${result.entitiesProcessed} entities)`;
+            },
+        });
+        spinner.stop();
+        // Print results
+        const dryRunLabel = options.dryRun ? chalk.dim(' [dry run]') : '';
+        console.log('');
+        for (const result of results) {
+            console.log(formatResult(result, options.verbose ?? false));
+        }
+        // Summary
+        const totalAdded = results.reduce((sum, r) => sum + r.linksAdded, 0);
+        const totalUpdated = results.reduce((sum, r) => sum + r.linksUpdated, 0);
+        const totalErrors = results.reduce((sum, r) => sum + r.errors.length, 0);
+        console.log('');
+        if (totalErrors > 0) {
+            console.log(chalk.yellow(`Sync complete${dryRunLabel}: ${totalAdded} new links, ${totalUpdated} updated links, ${totalErrors} error(s)`));
+        }
+        else {
+            console.log(chalk.green(`\u2714 Sync complete!${dryRunLabel} ${totalAdded} new links, ${totalUpdated} updated links`));
+        }
+    }
+    catch (err) {
+        spinner.fail(chalk.red('Sync failed'));
+        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 1;
+    }
+    finally {
+        dbManager.close();
+    }
+}
+export function registerSyncCommand(program) {
+    program
+        .command('sync [connectors...]')
+        .description('Sync external knowledge connectors (e.g. Notion, Jira) with the code graph')
+        .option('--dry-run', 'Preview changes without writing to database')
+        .option('--owner <owner>', 'Only sync entities owned by this team/person')
+        .option('--tags <tags>', 'Only sync entities with these tags (comma-separated)')
+        .option('--verbose', 'Show detailed progress and errors')
+        .option('--config <path>', 'Path to .knowgraph.yml config file', '.knowgraph.yml')
+        .action(async (connectors, options) => {
+        await runSync(connectors, options);
+    });
+}
+//# sourceMappingURL=sync.js.map

package/dist/commands/sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.js","sourceRoot":"","sources":["../../src/commands/sync.ts"],"names":[],"mappings":"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"}

package/dist/commands/validate.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+export declare function registerValidateCommand(program: Command): void;
+//# sourceMappingURL=validate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsFzC,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAU9D"}

package/dist/commands/validate.js

@@ -0,0 +1,81 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: CLI command that validates knowgraph annotations and reports issues
+ * owner: knowgraph-cli
+ * status: experimental
+ * tags: [cli, command, validate, quality]
+ * context:
+ *   business_goal: Help developers find and fix annotation issues before committing
+ *   domain: cli
+ */
+import { resolve } from 'node:path';
+import { statSync } from 'node:fs';
+import chalk from 'chalk';
+import { createValidator } from '@know-graph/core';
+function formatIssueText(issue) {
+    const severity = issue.severity === 'error'
+        ? chalk.red('[ERROR]')
+        : chalk.yellow('[WARN]');
+    const location = chalk.cyan(`${issue.filePath}:${issue.line}`);
+    const ruleName = chalk.dim(issue.rule);
+    return `${location} ${severity} ${ruleName}: ${issue.message}`;
+}
+function printTextOutput(result, strict) {
+    for (const issue of result.issues) {
+        console.log(formatIssueText(issue));
+    }
+    console.log('');
+    const isFailure = strict
+        ? result.errorCount > 0 || result.warningCount > 0
+        : result.errorCount > 0;
+    const summaryColor = isFailure ? chalk.red : chalk.green;
+    console.log(summaryColor(`${result.errorCount} error(s), ${result.warningCount} warning(s) in ${result.fileCount} file(s)`));
+}
+function printJsonOutput(result) {
+    console.log(JSON.stringify(result, null, 2));
+}
+function runValidate(targetPath, options) {
+    const absPath = resolve(targetPath);
+    try {
+        statSync(absPath);
+    }
+    catch {
+        console.error(chalk.red(`Error: Path not found: ${absPath}`));
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const validator = createValidator();
+        const result = validator.validate(absPath, {
+            ruleName: options.rule,
+        });
+        if (options.format === 'json') {
+            printJsonOutput(result);
+        }
+        else {
+            printTextOutput(result, options.strict ?? false);
+        }
+        const hasErrors = result.errorCount > 0;
+        const hasWarnings = result.warningCount > 0;
+        if (hasErrors || (options.strict && hasWarnings)) {
+            process.exitCode = 1;
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(`Validation failed: ${err instanceof Error ? err.message : String(err)}`));
+        process.exitCode = 1;
+    }
+}
+export function registerValidateCommand(program) {
+    program
+        .command('validate [path]')
+        .description('Validate @knowgraph annotations for correctness')
+        .option('--strict', 'Treat warnings as errors')
+        .option('--format <format>', 'Output format (text|json)', 'text')
+        .option('--rule <name>', 'Run only a specific validation rule')
+        .action((path, options) => {
+        runValidate(path ?? '.', options);
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/commands/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/commands/validate.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * @knowgraph
+ * type: module
+ * description: CLI entrypoint that registers all commands and parses arguments
+ * owner: knowgraph-cli
+ * status: stable
+ * tags: [cli, entrypoint, commander]
+ * context:
+ *   business_goal: Provide the main knowgraph command-line interface
+ *   domain: cli
+ */
+import { Command } from 'commander';
+import { registerParseCommand, registerIndexCommand, registerQueryCommand, registerServeCommand, registerInitCommand, registerValidateCommand, registerCoverageCommand, registerSuggestCommand, registerHookCommand, registerExportCommand, registerSyncCommand, } from './commands/index.js';
+const program = new Command();
+program
+    .name('knowgraph')
+    .description('AI-navigable code documentation tool')
+    .version('0.4.0');
+registerParseCommand(program);
+registerIndexCommand(program);
+registerQueryCommand(program);
+registerServeCommand(program);
+registerInitCommand(program);
+registerValidateCommand(program);
+registerCoverageCommand(program);
+registerSuggestCommand(program);
+registerHookCommand(program);
+registerExportCommand(program);
+registerSyncCommand(program);
+program.parse();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,EACtB,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,WAAW,CAAC;KACjB,WAAW,CAAC,sCAAsC,CAAC;KACnD,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACjC,uBAAuB,CAAC,OAAO,CAAC,CAAC;AACjC,sBAAsB,CAAC,OAAO,CAAC,CAAC;AAChC,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAC7B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,mBAAmB,CAAC,OAAO,CAAC,CAAC;AAE7B,OAAO,CAAC,KAAK,EAAE,CAAC"}

package/dist/utils/detect.d.ts

@@ -0,0 +1,3 @@
+export declare function detectLanguages(dir: string): readonly string[];
+export declare function suggestFiles(dir: string): readonly string[];
+//# sourceMappingURL=detect.d.ts.map

package/dist/utils/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/utils/detect.ts"],"names":[],"mappings":"AAgFA,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAe9D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CA+D3D"}

package/dist/utils/detect.js

@@ -0,0 +1,153 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: Language detection and file suggestion utilities for project initialization
+ * owner: knowgraph-cli
+ * status: stable
+ * tags: [cli, detection, languages, init]
+ * context:
+ *   business_goal: Automatically detect project languages during setup
+ *   domain: cli
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+const EXTENSION_TO_LANGUAGE = {
+    '.py': 'python',
+    '.ts': 'typescript',
+    '.tsx': 'typescript',
+    '.js': 'javascript',
+    '.jsx': 'javascript',
+    '.java': 'java',
+    '.go': 'go',
+    '.rs': 'rust',
+    '.rb': 'ruby',
+    '.php': 'php',
+    '.cs': 'csharp',
+    '.cpp': 'cpp',
+    '.c': 'c',
+    '.swift': 'swift',
+    '.kt': 'kotlin',
+};
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.tox',
+    'coverage',
+    '.next',
+]);
+function scanDirectory(dir, extCounts, depth) {
+    if (depth > 4)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.') && depth > 0)
+            continue;
+        if (SKIP_DIRS.has(entry))
+            continue;
+        const fullPath = join(dir, entry);
+        try {
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                scanDirectory(fullPath, extCounts, depth + 1);
+            }
+            else if (stat.isFile()) {
+                const ext = extname(entry);
+                if (ext && EXTENSION_TO_LANGUAGE[ext]) {
+                    extCounts.set(ext, (extCounts.get(ext) ?? 0) + 1);
+                }
+            }
+        }
+        catch {
+            // Skip inaccessible files
+        }
+    }
+}
+export function detectLanguages(dir) {
+    const extCounts = new Map();
+    scanDirectory(dir, extCounts, 0);
+    const languageCounts = new Map();
+    for (const [ext, count] of extCounts) {
+        const lang = EXTENSION_TO_LANGUAGE[ext];
+        if (lang) {
+            languageCounts.set(lang, (languageCounts.get(lang) ?? 0) + count);
+        }
+    }
+    return [...languageCounts.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([lang]) => lang);
+}
+export function suggestFiles(dir) {
+    const suggestions = [];
+    const entryPointNames = new Set([
+        'index.ts',
+        'index.js',
+        'main.ts',
+        'main.js',
+        'app.ts',
+        'app.js',
+        'main.py',
+        'app.py',
+        '__init__.py',
+        'server.ts',
+        'server.js',
+    ]);
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry) || entry.startsWith('.'))
+            continue;
+        const fullPath = join(dir, entry);
+        try {
+            const stat = statSync(fullPath);
+            if (stat.isFile()) {
+                const ext = extname(entry);
+                if (EXTENSION_TO_LANGUAGE[ext]) {
+                    const isEntryPoint = entryPointNames.has(entry);
+                    const priority = isEntryPoint ? stat.size + 1_000_000 : stat.size;
+                    suggestions.push({ path: entry, size: priority });
+                }
+            }
+            else if (stat.isDirectory()) {
+                const subEntries = readdirSync(fullPath);
+                for (const sub of subEntries) {
+                    const subExt = extname(sub);
+                    if (EXTENSION_TO_LANGUAGE[subExt]) {
+                        const subPath = `${entry}/${sub}`;
+                        const subStat = statSync(join(fullPath, sub));
+                        if (subStat.isFile()) {
+                            const isEntryPoint = entryPointNames.has(sub);
+                            const priority = isEntryPoint
+                                ? subStat.size + 1_000_000
+                                : subStat.size;
+                            suggestions.push({ path: subPath, size: priority });
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Skip inaccessible
+        }
+    }
+    return suggestions
+        .sort((a, b) => b.size - a.size)
+        .slice(0, 10)
+        .map((s) => s.path);
+}
+//# sourceMappingURL=detect.js.map

package/dist/utils/detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.js","sourceRoot":"","sources":["../../src/utils/detect.ts"],"names":[],"mappings":"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"}

package/dist/utils/format.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @knowgraph
+ * type: module
+ * description: Output formatting utilities for table and JSON display of query results
+ * owner: knowgraph-cli
+ * status: stable
+ * tags: [cli, formatting, output, table]
+ * context:
+ *   business_goal: Present code graph data in human-readable formats
+ *   domain: cli
+ */
+import type { StoredEntity } from '@know-graph/core';
+export declare function truncate(str: string, maxLen: number): string;
+export declare function formatTable(entities: readonly StoredEntity[]): string;
+export declare function formatJson(data: unknown, pretty: boolean): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/utils/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5D;AAOD,wBAAgB,WAAW,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CA4BrE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAEjE"}

package/dist/utils/format.js

@@ -0,0 +1,37 @@
+export function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return `${str.slice(0, maxLen - 3)}...`;
+}
+function padRight(str, len) {
+    if (str.length >= len)
+        return str;
+    return str + ' '.repeat(len - str.length);
+}
+export function formatTable(entities) {
+    if (entities.length === 0) {
+        return 'No results found.';
+    }
+    const headers = ['Name', 'Type', 'Owner', 'File', 'Description'];
+    const rows = entities.map((e) => [
+        truncate(e.name, 30),
+        e.entityType,
+        e.owner ?? '-',
+        truncate(e.filePath, 40),
+        truncate(e.description, 50),
+    ]);
+    const colWidths = headers.map((h, i) => {
+        const maxData = rows.reduce((max, row) => Math.max(max, row[i].length), 0);
+        return Math.max(h.length, maxData);
+    });
+    const headerLine = headers
+        .map((h, i) => padRight(h, colWidths[i]))
+        .join('  ');
+    const separator = colWidths.map((w) => '-'.repeat(w)).join('  ');
+    const dataLines = rows.map((row) => row.map((cell, i) => padRight(cell, colWidths[i])).join('  '));
+    return [headerLine, separator, ...dataLines].join('\n');
+}
+export function formatJson(data, pretty) {
+    return pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,MAAc;IAClD,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM;QAAE,OAAO,GAAG,CAAC;IACrC,OAAO,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC;AAC1C,CAAC;AAED,SAAS,QAAQ,CAAC,GAAW,EAAE,GAAW;IACxC,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IAClC,OAAO,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAiC;IAC3D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,mBAAmB,CAAC;IAC7B,CAAC;IAED,MAAM,OAAO,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QAC/B,QAAQ,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACpB,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,KAAK,IAAI,GAAG;QACd,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC;QACxB,QAAQ,CAAC,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;KAC5B,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;QAC3E,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,MAAM,UAAU,GAAG,OAAO;SACvB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;SACxC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACjC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC9D,CAAC;IAEF,OAAO,CAAC,UAAU,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAa,EAAE,MAAe;IACvD,OAAO,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AACvE,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { formatTable, formatJson, truncate } from './format.js';
+export { detectLanguages, suggestFiles } from './detect.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC"}