ts-knowledge-graph 0.1.2 → 0.1.6

package/dist/commands/report_command.js

@@ -0,0 +1,115 @@
+import { existsSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import chalk from 'chalk';
+import { GraphQuery } from '../query/graph_query.js';
+import { GraphReport } from '../report/graph_report.js';
+import { ReportData } from '../report/report_data.js';
+import { PdfRenderer, PdfUnavailableError } from '../report/pdf_renderer.js';
+import { KuzuStore } from '../store/kuzu_store.js';
+import { OutputFolder } from '../store/output_folder.js';
+import { CommandHelpers } from './command_helpers.js';
+const FORMATS = ['markdown', 'pdf', 'json'];
+const EXTENSION = { markdown: 'md', pdf: 'pdf', json: 'json' };
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+/**
+ * `report` command — gathers a {@link GraphReportData} from the loaded graph and
+ * writes a CODEBASE_BRIEF in the chosen format. `markdown` and `json` come
+ * straight from the pure {@link GraphReport} renderer; `pdf` renders the visual
+ * HTML and converts it through the optional {@link PdfRenderer}, falling back to
+ * the HTML when no engine is installed.
+ */
+export class ReportCommand {
+    static register(program) {
+        const command = program
+            .command('report')
+            .description('generate a CODEBASE_BRIEF summarising structure, impact, runtime, and boundary');
+        CommandHelpers.addOutputFolderOption(command)
+            .option('--format <format>', `output format: ${FORMATS.join(', ')}`, 'markdown')
+            .option('--output <file>', 'output file (default: <output-folder>/CODEBASE_BRIEF.<ext>)')
+            .option('--limit <n>', 'maximum rows per ranking', String(DEFAULT_LIMIT))
+            .option('--stdout', 'write to stdout instead of a file (markdown/json only)', false)
+            .action(async (options) => {
+            await ReportCommand.run(options);
+        });
+    }
+    static async run(options) {
+        if (FORMATS.includes(options.format) === false) {
+            console.error(chalk.red(`unknown format '${options.format}' — choose one of: ${FORMATS.join(', ')}`));
+            process.exitCode = 1;
+            return;
+        }
+        const format = options.format;
+        const folder = new OutputFolder(options.outputFolder);
+        if (existsSync(folder.dbPath) === false) {
+            console.error(chalk.red(`database not found at ${folder.dbPath} — run \`extract\` then \`load\` first`));
+            process.exitCode = 1;
+            return;
+        }
+        const data = await ReportCommand.gather(folder, options);
+        if (format === 'pdf') {
+            await ReportCommand.emitPdf(data, folder, options);
+            return;
+        }
+        const content = GraphReport.render(data, format);
+        if (options.stdout === true) {
+            console.log(content);
+            return;
+        }
+        const outPath = options.output ?? folder.reportPath(EXTENSION[format]);
+        await writeFile(outPath, content, 'utf8');
+        console.log(chalk.green(`✓ wrote ${outPath}`));
+    }
+    static async gather(folder, options) {
+        const store = new KuzuStore(folder.dbPath);
+        await store.initSchema();
+        try {
+            const query = new GraphQuery(store);
+            return await ReportData.gather(store, query, {
+                generatedAt: new Date().toISOString().slice(0, 10),
+                project: basename(folder.path),
+                outputFolder: options.outputFolder,
+                limit: ReportCommand.clampLimit(options.limit),
+            });
+        }
+        finally {
+            await store.close();
+        }
+    }
+    static async emitPdf(data, folder, options) {
+        if (options.stdout === true) {
+            console.error(chalk.red('--stdout is not supported for --format pdf — choose markdown or json, or drop --stdout'));
+            process.exitCode = 1;
+            return;
+        }
+        const outPath = options.output ?? folder.reportPath('pdf');
+        const html = GraphReport.renderVisualHtml(data);
+        try {
+            const pdf = await PdfRenderer.fromHtml(html);
+            await writeFile(outPath, pdf);
+            console.log(chalk.green(`✓ wrote ${outPath}`));
+        }
+        catch (error) {
+            if (error instanceof PdfUnavailableError === false) {
+                throw error;
+            }
+            const htmlPath = outPath.replace(/\.pdf$/, '.html');
+            await writeFile(htmlPath, html, 'utf8');
+            console.warn(chalk.yellow(`! ${error.message}`));
+            console.warn(chalk.yellow(`  wrote the HTML layout to ${htmlPath} — open it and print to PDF, or install the engine for direct PDF output.`));
+        }
+    }
+    static clampLimit(value) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed) === false) {
+            return DEFAULT_LIMIT;
+        }
+        const floored = Math.floor(parsed);
+        if (floored < 1) {
+            return DEFAULT_LIMIT;
+        }
+        return floored > MAX_LIMIT ? MAX_LIMIT : floored;
+    }
+}
+//# sourceMappingURL=report_command.js.map

package/dist/commands/report_command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report_command.js","sourceRoot":"","sources":["../../src/commands/report_command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAmB,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAItD,MAAM,OAAO,GAAmB,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;AAC5D,MAAM,SAAS,GAAiC,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC7F,MAAM,aAAa,GAAG,EAAE,CAAC;AACzB,MAAM,SAAS,GAAG,GAAG,CAAC;AAUtB;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IACzB,MAAM,CAAC,QAAQ,CAAC,OAAgB;QAC/B,MAAM,OAAO,GAAG,OAAO;aACrB,OAAO,CAAC,QAAQ,CAAC;aACjB,WAAW,CAAC,gFAAgF,CAAC,CAAC;QAChG,cAAc,CAAC,qBAAqB,CAAC,OAAO,CAAC;aAC3C,MAAM,CAAC,mBAAmB,EAAE,kBAAkB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,CAAC;aAC/E,MAAM,CAAC,iBAAiB,EAAE,6DAA6D,CAAC;aACxF,MAAM,CAAC,aAAa,EAAE,0BAA0B,EAAE,MAAM,CAAC,aAAa,CAAC,CAAC;aACxE,MAAM,CAAC,UAAU,EAAE,wDAAwD,EAAE,KAAK,CAAC;aACnF,MAAM,CAAC,KAAK,EAAE,OAA6B,EAAE,EAAE;YAC/C,MAAM,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,OAA6B;QACrD,IAAI,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAsB,CAAC,KAAK,KAAK,EAAE,CAAC;YAChE,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,mBAAmB,OAAO,CAAC,MAAM,sBAAsB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;YACtG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACR,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAsB,CAAC;QAC9C,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC;QACtD,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,KAAK,EAAE,CAAC;YACzC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,yBAAyB,MAAM,CAAC,MAAM,wCAAwC,CAAC,CAAC,CAAC;YACzG,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACR,CAAC;QAED,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACzD,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;YACtB,MAAM,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;YACnD,OAAO;QACR,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACjD,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC7B,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACrB,OAAO;QACR,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QACvE,MAAM,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC,CAAC;IAChD,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAoB,EAAE,OAA6B;QAC9E,MAAM,KAAK,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC3C,MAAM,KAAK,CAAC,UAAU,EAAE,CAAC;QACzB,IAAI,CAAC;YACJ,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;YACpC,OAAO,MAAM,UAAU,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE;gBAC5C,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;gBAClD,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC;gBAC9B,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC;aAC9C,CAAC,CAAC;QACJ,CAAC;gBAAS,CAAC;YACV,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,IAAqB,EAAE,MAAoB,EAAE,OAA6B;QACtG,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC7B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,wFAAwF,CAAC,CAAC,CAAC;YACnH,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACR,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAC3D,MAAM,IAAI,GAAG,WAAW,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAChD,IAAI,CAAC;YACJ,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC7C,MAAM,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YAC9B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,OAAO,EAAE,CAAC,CAAC,CAAC;QAChD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,KAAK,YAAY,mBAAmB,KAAK,KAAK,EAAE,CAAC;gBACpD,MAAM,KAAK,CAAC;YACb,CAAC;YACD,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YACpD,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACxC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YACjD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,8BAA8B,QAAQ,2EAA2E,CAAC,CAAC,CAAC;QAC/I,CAAC;IACF,CAAC;IAEO,MAAM,CAAC,UAAU,CAAC,KAAa;QACtC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,KAAK,EAAE,CAAC;YACvC,OAAO,aAAa,CAAC;QACtB,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YACjB,OAAO,aAAa,CAAC;QACtB,CAAC;QACD,OAAO,OAAO,GAAG,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;IAClD,CAAC;CACD"}

package/dist/commands/verify_command.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+export declare class VerifyCommand {
+    static register(program: Command): void;
+    private static print;
+    private static printCheck;
+    private static printFailureOutput;
+}
+//# sourceMappingURL=verify_command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify_command.d.ts","sourceRoot":"","sources":["../../src/commands/verify_command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,qBAAa,aAAa;IACzB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAuBvC,OAAO,CAAC,MAAM,CAAC,KAAK;IAapB,OAAO,CAAC,MAAM,CAAC,UAAU;IAUzB,OAAO,CAAC,MAAM,CAAC,kBAAkB;CASjC"}

package/dist/commands/verify_command.js

@@ -0,0 +1,57 @@
+import chalk from 'chalk';
+import { ProjectVerifier } from '../verify/project_verifier.js';
+export class VerifyCommand {
+    static register(program) {
+        program
+            .command('verify')
+            .description('run the project type-check + test gates and return one keep/revert verdict for an edit')
+            .option('-C, --cwd <path>', 'project directory whose package.json scripts are run', process.cwd())
+            .option('--typecheck-script <name>', 'npm script for the type-check gate', 'typecheck')
+            .option('--test-script <name>', 'npm script for the test gate', 'test')
+            .option('--skip-typecheck', 'skip the type-check gate', false)
+            .option('--skip-tests', 'skip the test gate (degrades to type-check-only)', false)
+            .option('--json', 'emit the verdict as JSON', false)
+            .action(async (options) => {
+            const report = await ProjectVerifier.verify({
+                cwd: options.cwd,
+                typecheckScript: options.typecheckScript,
+                testScript: options.testScript,
+                skipTypecheck: options.skipTypecheck === true,
+                skipTests: options.skipTests === true,
+            });
+            VerifyCommand.print(report, options.json === true);
+            process.exitCode = report.ok === true ? 0 : 1;
+        });
+    }
+    static print(report, json) {
+        if (json === true) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        for (const check of report.checks) {
+            VerifyCommand.printCheck(check);
+        }
+        const verdict = report.ok === true ? chalk.green('✓') : chalk.red('✗');
+        console.log(`\n${verdict} ${report.summary}`);
+        VerifyCommand.printFailureOutput(report);
+    }
+    static printCheck(check) {
+        if (check.status === 'skipped') {
+            console.log(`${chalk.yellow('•')} ${chalk.bold(check.name.padEnd(10))} ${chalk.yellow('skipped')}  ${chalk.gray(check.skippedReason ?? '')}`);
+            return;
+        }
+        const mark = check.status === 'pass' ? chalk.green('✓') : chalk.red('✗');
+        const timing = chalk.gray(`${(check.durationMs / 1000).toFixed(1)}s`);
+        console.log(`${mark} ${chalk.bold(check.name.padEnd(10))} ${chalk.gray(check.command ?? '')}  ${timing}`);
+    }
+    static printFailureOutput(report) {
+        if (report.ok === true) {
+            return;
+        }
+        for (const check of report.checks.filter((candidate) => candidate.status === 'fail')) {
+            console.log(chalk.bold(`\n— ${check.name} output (tail) —`));
+            console.log(check.output.trimEnd());
+        }
+    }
+}
+//# sourceMappingURL=verify_command.js.map

package/dist/commands/verify_command.js.map

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

package/dist/commands/web_command.d.ts

@@ -13,6 +13,33 @@ export declare class WebCommand {
      * `window.GRAPH_DATA` script the visualisation page loads on boot.
      */
     private static buildDataScript;
+    /**
+     * Decodes the JSON `metadata` column into a record so the visualisation can
+     * read `metadata.runtime`. A missing, empty (`{}`), or malformed value yields
+     * `undefined`, which `JSON.stringify` omits — keeping the payload small and
+     * letting un-enriched nodes simply carry no metadata.
+     */
+    private static decodeMetadata;
+    /**
+     * Renders the `window.GRAPH_SOURCE` script that lets the visualisation link
+     * file paths to GitHub. Returns an empty string when `sourceDir` is not a
+     * GitHub work tree, so the page falls back to plain-text file paths.
+     */
+    private static buildSourceScript;
+    /**
+     * Detects the GitHub repository, HEAD commit, and in-repo path prefix for the
+     * directory the graph was extracted from. Returns `undefined` when `sourceDir`
+     * is not a Git work tree, has no GitHub `origin` remote, or Git is unavailable.
+     */
+    private static detectGitHubSource;
+    /**
+     * Normalises a Git `origin` URL to its GitHub web base
+     * (`https://<host>/<owner>/<repo>`), or `undefined` for non-GitHub remotes.
+     * Handles the SCP-like (`git@host:owner/repo.git`), `https://`, `git://`, and
+     * `ssh://` forms, with or without a trailing `.git`. The host is kept as-is so
+     * GitHub Enterprise remotes resolve to their own domain.
+     */
+    static githubBaseUrl(remoteUrl: string): string | undefined;
     private static handle;
     private static notFound;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"web_command.d.ts","sourceRoot":"","sources":["../../src/commands/web_command.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA2BpC;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAWlB,GAAG;IAmBxB;;;OAGG;mBACkB,eAAe;mBAoCf,MAAM;IAwB3B,OAAO,CAAC,MAAM,CAAC,QAAQ;CAIvB"}
+{"version":3,"file":"web_command.d.ts","sourceRoot":"","sources":["../../src/commands/web_command.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4CpC;;;;;GAKG;AACH,qBAAa,UAAU;IACtB,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAYlB,GAAG;IAoBxB;;;OAGG;mBACkB,eAAe;IAsCpC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAe7B;;;;OAIG;mBACkB,iBAAiB;IAUtC;;;;OAIG;mBACkB,kBAAkB;IAsBvC;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;mBA8BtC,MAAM;IAwB3B,OAAO,CAAC,MAAM,CAAC,QAAQ;CAIvB"}

package/dist/commands/web_command.js

@@ -1,11 +1,14 @@
+import { execFile } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { extname, join, normalize, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { promisify } from 'node:util';
 import chalk from 'chalk';
 import { KuzuStore } from '../store/kuzu_store.js';
 import { DEFAULT_DB_PATH } from './command_helpers.js';
+const execFileAsync = promisify(execFile);
 /**
  * Static assets of the web visualisation, resolved relative to this module so
  * the same path works from `src/` (tsx) and from `dist/` (published package).
@@ -34,6 +37,7 @@ export class WebCommand {
             .description('serve the knowledge graph database in a web visualisation')
             .option('-d, --db <path>', 'Kùzu database path', DEFAULT_DB_PATH)
             .option('-p, --port <port>', 'HTTP port to listen on', DEFAULT_PORT)
+            .option('-s, --source <dir>', 'project root the graph was extracted from, used to link files to GitHub', '.')
             .action(async (options) => {
             await WebCommand.run(options);
         });
@@ -45,7 +49,8 @@ export class WebCommand {
             process.exitCode = 1;
             return;
         }
-        const dataScript = await WebCommand.buildDataScript(dbPath);
+        const sourceScript = await WebCommand.buildSourceScript(resolve(options.source));
+        const dataScript = sourceScript + await WebCommand.buildDataScript(dbPath);
         const server = createServer((request, response) => {
             void WebCommand.handle(request, response, dataScript);
         });
@@ -62,8 +67,8 @@ export class WebCommand {
         const store = new KuzuStore(dbPath);
         await store.initSchema();
         try {
-            const nodeRows = await store.run('MATCH (n:GraphNode) RETURN n.id AS id, n.kind AS kind, n.name AS name, n.filePath AS filePath, n.exported AS exported, n.startLine AS startLine, n.endLine AS endLine');
-            const edgeRows = await store.run('MATCH (f:GraphNode)-[e:Edge]->(t:GraphNode) RETURN f.id AS from, e.kind AS kind, t.id AS to');
+            const nodeRows = await store.run('MATCH (n:GraphNode) RETURN n.id AS id, n.kind AS kind, n.name AS name, n.filePath AS filePath, n.exported AS exported, n.startLine AS startLine, n.endLine AS endLine, n.metadata AS metadata');
+            const edgeRows = await store.run('MATCH (f:GraphNode)-[e:Edge]->(t:GraphNode) RETURN f.id AS from, e.kind AS kind, t.id AS to, e.metadata AS metadata');
             const nodes = nodeRows.map((row) => ({
                 id: String(row.id),
                 kind: String(row.kind),
@@ -76,12 +81,14 @@ export class WebCommand {
                     endLine: Number(row.endLine),
                     endColumn: 0,
                 },
+                metadata: WebCommand.decodeMetadata(row.metadata),
             }));
             const edges = edgeRows.map((row, index) => ({
                 id: `e${index}`,
                 kind: String(row.kind),
                 from: String(row.from),
                 to: String(row.to),
+                metadata: WebCommand.decodeMetadata(row.metadata),
             }));
             console.log(chalk.cyan(`loaded ${nodes.length} nodes, ${edges.length} edges from ${dbPath}`));
             return `window.GRAPH_DATA = ${JSON.stringify({ nodes, edges })};\n`;
@@ -90,6 +97,105 @@ export class WebCommand {
             await store.close();
         }
     }
+    /**
+     * Decodes the JSON `metadata` column into a record so the visualisation can
+     * read `metadata.runtime`. A missing, empty (`{}`), or malformed value yields
+     * `undefined`, which `JSON.stringify` omits — keeping the payload small and
+     * letting un-enriched nodes simply carry no metadata.
+     */
+    static decodeMetadata(value) {
+        if (typeof value !== 'string' || value.length === 0) {
+            return undefined;
+        }
+        try {
+            const parsed = JSON.parse(value);
+            if (typeof parsed === 'object' && parsed !== null && Object.keys(parsed).length > 0) {
+                return parsed;
+            }
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Renders the `window.GRAPH_SOURCE` script that lets the visualisation link
+     * file paths to GitHub. Returns an empty string when `sourceDir` is not a
+     * GitHub work tree, so the page falls back to plain-text file paths.
+     */
+    static async buildSourceScript(sourceDir) {
+        const github = await WebCommand.detectGitHubSource(sourceDir);
+        if (github === undefined) {
+            console.log(chalk.gray('no GitHub remote detected — file paths will not link to source'));
+            return '';
+        }
+        console.log(chalk.cyan(`linking files to ${github.baseUrl} @ ${github.commit.slice(0, 7)}`));
+        return `window.GRAPH_SOURCE = ${JSON.stringify({ github })};\n`;
+    }
+    /**
+     * Detects the GitHub repository, HEAD commit, and in-repo path prefix for the
+     * directory the graph was extracted from. Returns `undefined` when `sourceDir`
+     * is not a Git work tree, has no GitHub `origin` remote, or Git is unavailable.
+     */
+    static async detectGitHubSource(sourceDir) {
+        const git = async (...args) => {
+            try {
+                const { stdout } = await execFileAsync('git', ['-C', sourceDir, ...args]);
+                return stdout.trim();
+            }
+            catch {
+                return undefined;
+            }
+        };
+        if (await git('rev-parse', '--is-inside-work-tree') !== 'true') {
+            return undefined;
+        }
+        const remoteUrl = await git('remote', 'get-url', 'origin');
+        const commit = await git('rev-parse', 'HEAD');
+        const baseUrl = remoteUrl === undefined ? undefined : WebCommand.githubBaseUrl(remoteUrl);
+        if (baseUrl === undefined || commit === undefined) {
+            return undefined;
+        }
+        return { baseUrl, commit, prefix: await git('rev-parse', '--show-prefix') ?? '' };
+    }
+    /**
+     * Normalises a Git `origin` URL to its GitHub web base
+     * (`https://<host>/<owner>/<repo>`), or `undefined` for non-GitHub remotes.
+     * Handles the SCP-like (`git@host:owner/repo.git`), `https://`, `git://`, and
+     * `ssh://` forms, with or without a trailing `.git`. The host is kept as-is so
+     * GitHub Enterprise remotes resolve to their own domain.
+     */
+    static githubBaseUrl(remoteUrl) {
+        const trimmed = remoteUrl.trim();
+        let host;
+        let path;
+        if (trimmed.includes('://') === true) {
+            try {
+                const parsed = new URL(trimmed);
+                host = parsed.host;
+                path = parsed.pathname;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        else {
+            const scpMatch = trimmed.match(/^[^@]+@([^:]+):(.+)$/);
+            if (scpMatch === null) {
+                return undefined;
+            }
+            host = scpMatch[1];
+            path = scpMatch[2];
+        }
+        if (host.toLowerCase().includes('github') === false) {
+            return undefined;
+        }
+        const segments = path.replace(/\.git$/, '').split('/').filter((segment) => segment.length > 0);
+        if (segments.length < 2) {
+            return undefined;
+        }
+        return `https://${host}/${segments[0]}/${segments[1]}`;
+    }
     static async handle(request, response, dataScript) {
         const url = new URL(request.url ?? '/', 'http://localhost');
         const pathname = url.pathname === '/' ? '/index.html' : url.pathname;

package/dist/commands/web_command.js.map

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

package/dist/commands/webview_command.d.ts

@@ -0,0 +1,36 @@
+import { Command } from 'commander';
+/**
+ * `webview` command — serves the knowledge graph database in an interactive web
+ * visualisation. The graph is read from Kùzu once at startup and injected into
+ * the page as `/js_autogenerated/graph_data.js`; all other assets are served statically
+ * from the contribs/webview/web directory.
+ */
+export declare class WebviewCommand {
+    static register(program: Command): void;
+    private static run;
+    /**
+     * Reads every node and edge from the database and renders them as the
+     * `window.GRAPH_DATA` script the visualisation page loads on boot.
+     */
+    private static buildDataScript;
+    /**
+     * Decodes the JSON `metadata` column into a record so the visualisation can
+     * read `metadata.runtime`. A missing, empty (`{}`), or malformed value yields
+     * `undefined`, which `JSON.stringify` omits — keeping the payload small and
+     * letting un-enriched nodes simply carry no metadata.
+     */
+    private static decodeMetadata;
+    /**
+     * Resolves the GitHub source for the served graph. Prefers the provenance
+     * `extract` recorded in the database — it pins the exact commit and in-repo
+     * `prefix` that was parsed — and falls back to detecting it live from
+     * `sourceDir` for graphs built before provenance was captured. Returns
+     * `undefined` when neither is available, so the page shows plain-text paths.
+     */
+    private static resolveGitHubSource;
+    /** Reads the source provenance `load` stored in the database, or `undefined` when absent or malformed. */
+    private static readStoredSource;
+    private static handle;
+    private static notFound;
+}
+//# sourceMappingURL=webview_command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"webview_command.d.ts","sourceRoot":"","sources":["../../src/commands/webview_command.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA+BpC;;;;;GAKG;AACH,qBAAa,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;mBAYlB,GAAG;IAqBxB;;;OAGG;mBACkB,eAAe;IAsCpC;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAe7B;;;;;;OAMG;mBACkB,mBAAmB;IAexC,0GAA0G;mBACrF,gBAAgB;mBAehB,MAAM;IAwB3B,OAAO,CAAC,MAAM,CAAC,QAAQ;CAIvB"}