@shrkcrft/graph 0.1.0-alpha.10

package/dist/schema/node-kind.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Node kinds in the code graph.
+ *
+ * MVP ships File / Symbol / Package. Bridge kinds are reserved but emitted
+ * by the rule-graph package (Wave 2), not by graph itself.
+ */
+export declare enum NodeKind {
+    File = "file",
+    Symbol = "symbol",
+    Package = "package",
+    Rule = "rule",
+    Path = "path",
+    Template = "template",
+    Pipeline = "pipeline",
+    Preset = "preset",
+    Pack = "pack",
+    Boundary = "boundary",
+    Knowledge = "knowledge",
+    FrameworkEntity = "framework-entity"
+}
+//# sourceMappingURL=node-kind.d.ts.map

package/dist/schema/node-kind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-kind.d.ts","sourceRoot":"","sources":["../../src/schema/node-kind.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,oBAAY,QAAQ;IAClB,IAAI,SAAS;IACb,MAAM,WAAW;IACjB,OAAO,YAAY;IAInB,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,QAAQ,aAAa;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,QAAQ,aAAa;IACrB,SAAS,cAAc;IAMvB,eAAe,qBAAqB;CACrC"}

package/dist/schema/node-kind.js

@@ -0,0 +1,27 @@
+/**
+ * Node kinds in the code graph.
+ *
+ * MVP ships File / Symbol / Package. Bridge kinds are reserved but emitted
+ * by the rule-graph package (Wave 2), not by graph itself.
+ */
+export var NodeKind;
+(function (NodeKind) {
+    NodeKind["File"] = "file";
+    NodeKind["Symbol"] = "symbol";
+    NodeKind["Package"] = "package";
+    // Reserved for @shrkcrft/rule-graph (Wave 2). Listed here so node ids stay
+    // globally namespaced and the union surface is stable.
+    NodeKind["Rule"] = "rule";
+    NodeKind["Path"] = "path";
+    NodeKind["Template"] = "template";
+    NodeKind["Pipeline"] = "pipeline";
+    NodeKind["Preset"] = "preset";
+    NodeKind["Pack"] = "pack";
+    NodeKind["Boundary"] = "boundary";
+    NodeKind["Knowledge"] = "knowledge";
+    // Framework-aware entities (Wave 7). The `data.framework` and
+    // `data.subtype` fields distinguish nestjs:controller vs
+    // react:component vs express:route. Single kind keeps the NodeKind
+    // enum tight; consumers filter on data.
+    NodeKind["FrameworkEntity"] = "framework-entity";
+})(NodeKind || (NodeKind = {}));

package/dist/schema/node.d.ts

@@ -0,0 +1,26 @@
+import type { NodeKind } from './node-kind.js';
+/**
+ * A node in the code graph.
+ *
+ * `id` is namespaced by kind: `file:packages/foo/src/bar.ts`,
+ * `symbol:packages/foo/src/bar.ts#fooFn`, `package:@shrkcrft/foo`.
+ *
+ * `data` holds kind-specific structured payload — typed at write via
+ * the helper builders in `indexer/` rather than enforced via a
+ * discriminated union here (the union would balloon and gain little).
+ */
+export interface INode {
+    id: string;
+    kind: NodeKind;
+    /** Short, deterministic display label. */
+    label: string;
+    /** Project-relative path for File / Symbol; undefined otherwise. */
+    path?: string;
+    /** 1-based line number for Symbol nodes; undefined otherwise. */
+    line?: number;
+    /** Free-form, sorted, deduped tags. */
+    tags?: readonly string[];
+    /** Kind-specific structured payload. */
+    data?: Readonly<Record<string, unknown>>;
+}
+//# sourceMappingURL=node.d.ts.map

package/dist/schema/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/schema/node.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,WAAW,KAAK;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,wCAAwC;IACxC,IAAI,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC1C"}

package/dist/schema/node.js

@@ -0,0 +1 @@
+export {};

package/dist/schema/schema-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Schema version for the on-disk code graph.
+ *
+ * Every payload written to `.sharkcraft/graph/` and every JSON response
+ * carries this constant. A change here is a breaking change and requires
+ * a migration in the store.
+ */
+export declare const GRAPH_SCHEMA: "sharkcraft.graph/v1";
+export type GraphSchemaVersion = typeof GRAPH_SCHEMA;
+//# sourceMappingURL=schema-version.d.ts.map

package/dist/schema/schema-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-version.d.ts","sourceRoot":"","sources":["../../src/schema/schema-version.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,EAAG,qBAA8B,CAAC;AAE3D,MAAM,MAAM,kBAAkB,GAAG,OAAO,YAAY,CAAC"}

package/dist/schema/schema-version.js

@@ -0,0 +1,8 @@
+/**
+ * Schema version for the on-disk code graph.
+ *
+ * Every payload written to `.sharkcraft/graph/` and every JSON response
+ * carries this constant. A change here is a breaking change and requires
+ * a migration in the store.
+ */
+export const GRAPH_SCHEMA = 'sharkcraft.graph/v1';

package/dist/store/file-fingerprint.d.ts

@@ -0,0 +1,8 @@
+import type { IFileFingerprint } from '../schema/file-fingerprint.js';
+/**
+ * Compute a fingerprint for a file. Reads the file once; callers that
+ * already have the contents should use `fingerprintFromContent` instead.
+ */
+export declare function fingerprintFile(absPath: string, projectRoot: string): IFileFingerprint;
+export declare function fingerprintFromBuffer(buf: Buffer, absPath: string, projectRoot: string, mtimeMs: number, sizeBytes: number): IFileFingerprint;
+//# sourceMappingURL=file-fingerprint.d.ts.map

package/dist/store/file-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-fingerprint.d.ts","sourceRoot":"","sources":["../../src/store/file-fingerprint.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA2BtE;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAIlB;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAWlB"}

package/dist/store/file-fingerprint.js

@@ -0,0 +1,64 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const JS_EXTS = new Set(['.js', '.jsx', '.mjs', '.cjs']);
+function languageOf(absPath) {
+    const ext = nodePath.extname(absPath).toLowerCase();
+    if (TS_EXTS.has(ext))
+        return 'typescript';
+    if (JS_EXTS.has(ext))
+        return 'javascript';
+    if (ext === '.vue')
+        return 'vue';
+    if (ext === '.svelte')
+        return 'svelte';
+    if (ext === '.astro')
+        return 'astro';
+    if (ext === '.py')
+        return 'python';
+    if (ext === '.go')
+        return 'go';
+    if (ext === '.java')
+        return 'java';
+    if (ext === '.rs')
+        return 'rust';
+    if (ext === '.kt' || ext === '.kts')
+        return 'kotlin';
+    if (ext === '.rb')
+        return 'ruby';
+    if (ext === '.cs' || ext === '.csx')
+        return 'csharp';
+    if (ext === '.ex' || ext === '.exs')
+        return 'elixir';
+    if (ext === '.php')
+        return 'php';
+    if (ext === '.dart')
+        return 'dart';
+    if (ext === '.swift')
+        return 'swift';
+    if (ext === '.graphql' || ext === '.gql')
+        return 'graphql';
+    return 'unknown';
+}
+/**
+ * Compute a fingerprint for a file. Reads the file once; callers that
+ * already have the contents should use `fingerprintFromContent` instead.
+ */
+export function fingerprintFile(absPath, projectRoot) {
+    const st = statSync(absPath);
+    const buf = readFileSync(absPath);
+    return fingerprintFromBuffer(buf, absPath, projectRoot, st.mtimeMs, st.size);
+}
+export function fingerprintFromBuffer(buf, absPath, projectRoot, mtimeMs, sizeBytes) {
+    const sha1 = createHash('sha1').update(buf).digest('hex');
+    const rel = nodePath.relative(projectRoot, absPath);
+    return {
+        path: rel.split(nodePath.sep).join('/'),
+        mtime: Math.floor(mtimeMs),
+        sha1,
+        sizeBytes,
+        language: languageOf(absPath),
+        nodeId: `file:${rel.split(nodePath.sep).join('/')}`,
+    };
+}

package/dist/store/graph-store.d.ts

@@ -0,0 +1,48 @@
+import type { IEdge } from '../schema/edge.js';
+import type { IFileFingerprint } from '../schema/file-fingerprint.js';
+import type { IGraphManifest } from '../schema/manifest.js';
+import type { INode } from '../schema/node.js';
+import type { IGraphSnapshot } from '../schema/graph-snapshot.js';
+/**
+ * On-disk JSONL graph store under `<root>/.sharkcraft/graph/`.
+ *
+ * Layout (MVP):
+ *   meta.json            manifest, schema version
+ *   files.json           { path: IFileFingerprint }
+ *   nodes/<kind>.jsonl   one row per node, sorted by id
+ *   edges/<kind>.jsonl   one row per edge, sorted by id
+ *
+ * The store is the only writer; callers go through `writeSnapshot` for a
+ * full rewrite or `appendNodes` / `appendEdges` for surgical updates (R64).
+ *
+ * `loadSnapshot` reads everything into memory. For SharkCraft-sized
+ * repos that's a few MB at most; SQLite swap is not on the MVP path
+ * (see code-intelligence.md §6.3 upgrade triggers).
+ */
+export declare class GraphStore {
+    private readonly projectRoot;
+    readonly storeDir: string;
+    constructor(projectRoot: string);
+    exists(): boolean;
+    clear(): void;
+    /**
+     * Write a full snapshot. Overwrites any existing store. Manifest digest
+     * is computed from the resulting JSONL files.
+     */
+    writeSnapshot(nodes: readonly INode[], edges: readonly IEdge[], files: readonly IFileFingerprint[], partial: Omit<IGraphManifest, 'schema' | 'digest'>): IGraphManifest;
+    /**
+     * Load the full store into memory. Throws if the store is missing or
+     * malformed — callers should check `exists()` first or wrap in a try.
+     */
+    loadSnapshot(): IGraphSnapshot;
+    /**
+     * Recompute the digest from disk and verify it matches the manifest.
+     * Used by `shrk graph status` and as a sanity check before queries.
+     */
+    verifyDigest(): {
+        ok: boolean;
+        expected: string;
+        actual: string;
+    };
+}
+//# sourceMappingURL=graph-store.d.ts.map

package/dist/store/graph-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-store.d.ts","sourceRoot":"","sources":["../../src/store/graph-store.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAOlE;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,UAAU;IAGT,OAAO,CAAC,QAAQ,CAAC,WAAW;IAFxC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAEJ,WAAW,EAAE,MAAM;IAIhD,MAAM,IAAI,OAAO;IAIjB,KAAK,IAAI,IAAI;IAMb;;;OAGG;IACH,aAAa,CACX,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,KAAK,EAAE,SAAS,KAAK,EAAE,EACvB,KAAK,EAAE,SAAS,gBAAgB,EAAE,EAClC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,QAAQ,GAAG,QAAQ,CAAC,GACjD,cAAc;IA6CjB;;;OAGG;IACH,YAAY,IAAI,cAAc;IAwC9B;;;OAGG;IACH,YAAY,IAAI;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;CAMlE"}

package/dist/store/graph-store.js

@@ -0,0 +1,194 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+import { GRAPH_SCHEMA } from "../schema/schema-version.js";
+const NODES_DIR = 'nodes';
+const EDGES_DIR = 'edges';
+const META_FILE = 'meta.json';
+const FILES_FILE = 'files.json';
+/**
+ * On-disk JSONL graph store under `<root>/.sharkcraft/graph/`.
+ *
+ * Layout (MVP):
+ *   meta.json            manifest, schema version
+ *   files.json           { path: IFileFingerprint }
+ *   nodes/<kind>.jsonl   one row per node, sorted by id
+ *   edges/<kind>.jsonl   one row per edge, sorted by id
+ *
+ * The store is the only writer; callers go through `writeSnapshot` for a
+ * full rewrite or `appendNodes` / `appendEdges` for surgical updates (R64).
+ *
+ * `loadSnapshot` reads everything into memory. For SharkCraft-sized
+ * repos that's a few MB at most; SQLite swap is not on the MVP path
+ * (see code-intelligence.md §6.3 upgrade triggers).
+ */
+export class GraphStore {
+    projectRoot;
+    storeDir;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.storeDir = nodePath.join(projectRoot, '.sharkcraft', 'graph');
+    }
+    exists() {
+        return existsSync(nodePath.join(this.storeDir, META_FILE));
+    }
+    clear() {
+        if (existsSync(this.storeDir)) {
+            rmSync(this.storeDir, { recursive: true, force: true });
+        }
+    }
+    /**
+     * Write a full snapshot. Overwrites any existing store. Manifest digest
+     * is computed from the resulting JSONL files.
+     */
+    writeSnapshot(nodes, edges, files, partial) {
+        // Clear stale per-kind JSONL files so kinds that became empty
+        // (e.g. PackageDependsOn after a delete) don't survive across
+        // writes. This is the simplest correctness guarantee — the store
+        // is small enough that the cost is negligible.
+        const nodesDir = nodePath.join(this.storeDir, NODES_DIR);
+        const edgesDir = nodePath.join(this.storeDir, EDGES_DIR);
+        if (existsSync(nodesDir))
+            rmSync(nodesDir, { recursive: true, force: true });
+        if (existsSync(edgesDir))
+            rmSync(edgesDir, { recursive: true, force: true });
+        mkdirSync(nodesDir, { recursive: true });
+        mkdirSync(edgesDir, { recursive: true });
+        const nodesByKind = bucketBy(nodes, (n) => n.kind);
+        const edgesByKind = bucketBy(edges, (e) => e.kind);
+        const nodeCounts = {};
+        const edgeCounts = {};
+        for (const [kind, list] of Object.entries(nodesByKind)) {
+            list.sort((a, b) => a.id.localeCompare(b.id));
+            writeJsonl(nodePath.join(this.storeDir, NODES_DIR, `${kind}.jsonl`), list);
+            nodeCounts[kind] = list.length;
+        }
+        for (const [kind, list] of Object.entries(edgesByKind)) {
+            list.sort((a, b) => a.id.localeCompare(b.id));
+            writeJsonl(nodePath.join(this.storeDir, EDGES_DIR, `${kind}.jsonl`), list);
+            edgeCounts[kind] = list.length;
+        }
+        writeJson(nodePath.join(this.storeDir, FILES_FILE), Object.fromEntries([...files].sort((a, b) => a.path.localeCompare(b.path)).map((f) => [f.path, f])));
+        const digest = computeStoreDigest(this.storeDir);
+        const manifest = {
+            schema: GRAPH_SCHEMA,
+            digest,
+            ...partial,
+            nodesByKind: nodeCounts,
+            edgesByKind: edgeCounts,
+        };
+        writeJson(nodePath.join(this.storeDir, META_FILE), manifest);
+        return manifest;
+    }
+    /**
+     * Load the full store into memory. Throws if the store is missing or
+     * malformed — callers should check `exists()` first or wrap in a try.
+     */
+    loadSnapshot() {
+        if (!this.exists()) {
+            throw new Error(`code-graph store not found under ${this.storeDir}. Run 'shrk graph index' to build it.`);
+        }
+        const manifest = readJson(nodePath.join(this.storeDir, META_FILE));
+        if (manifest.schema !== GRAPH_SCHEMA) {
+            throw new Error(`code-graph schema mismatch: store=${manifest.schema}, expected=${GRAPH_SCHEMA}. Rebuild with 'shrk graph index'.`);
+        }
+        const filesRaw = readJson(nodePath.join(this.storeDir, FILES_FILE));
+        const files = new Map(Object.entries(filesRaw));
+        const nodes = new Map();
+        const nodesDir = nodePath.join(this.storeDir, NODES_DIR);
+        if (existsSync(nodesDir)) {
+            for (const fname of readdirSync(nodesDir)) {
+                if (!fname.endsWith('.jsonl'))
+                    continue;
+                for (const row of readJsonl(nodePath.join(nodesDir, fname))) {
+                    nodes.set(row.id, row);
+                }
+            }
+        }
+        const edges = new Map();
+        const edgesDir = nodePath.join(this.storeDir, EDGES_DIR);
+        if (existsSync(edgesDir)) {
+            for (const fname of readdirSync(edgesDir)) {
+                if (!fname.endsWith('.jsonl'))
+                    continue;
+                for (const row of readJsonl(nodePath.join(edgesDir, fname))) {
+                    edges.set(row.id, row);
+                }
+            }
+        }
+        return { manifest, nodes, edges, files };
+    }
+    /**
+     * Recompute the digest from disk and verify it matches the manifest.
+     * Used by `shrk graph status` and as a sanity check before queries.
+     */
+    verifyDigest() {
+        if (!this.exists())
+            return { ok: false, expected: '', actual: '' };
+        const manifest = readJson(nodePath.join(this.storeDir, META_FILE));
+        const actual = computeStoreDigest(this.storeDir);
+        return { ok: actual === manifest.digest, expected: manifest.digest, actual };
+    }
+}
+function bucketBy(list, key) {
+    const out = {};
+    for (const item of list) {
+        const k = key(item);
+        if (!out[k])
+            out[k] = [];
+        out[k].push(item);
+    }
+    return out;
+}
+function writeJsonl(path, rows) {
+    const body = rows.map((r) => JSON.stringify(r)).join('\n');
+    writeFileSync(path, body.length > 0 ? body + '\n' : '');
+}
+function readJsonl(path) {
+    const raw = readFileSync(path, 'utf8');
+    if (!raw)
+        return [];
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        out.push(JSON.parse(trimmed));
+    }
+    return out;
+}
+function writeJson(path, value) {
+    writeFileSync(path, JSON.stringify(value, null, 2));
+}
+function readJson(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+/**
+ * SHA-256 over the concatenation of all JSONL files (alphabetical) plus
+ * files.json. meta.json itself is excluded — it holds the digest.
+ */
+function computeStoreDigest(storeDir) {
+    const hash = createHash('sha256');
+    const targets = [];
+    const filesJson = nodePath.join(storeDir, FILES_FILE);
+    if (existsSync(filesJson))
+        targets.push(filesJson);
+    for (const sub of [NODES_DIR, EDGES_DIR]) {
+        const dir = nodePath.join(storeDir, sub);
+        if (!existsSync(dir))
+            continue;
+        for (const fname of readdirSync(dir).sort()) {
+            if (!fname.endsWith('.jsonl'))
+                continue;
+            targets.push(nodePath.join(dir, fname));
+        }
+    }
+    targets.sort();
+    for (const t of targets) {
+        hash.update(nodePath.relative(storeDir, t));
+        hash.update('\0');
+        hash.update(readFileSync(t));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@shrkcrft/graph",
+  "version": "0.1.0-alpha.10",
+  "description": "SharkCraft code intelligence graph: files, symbols, packages, imports and exports. Persistent JSONL store; on-disk index queried by every other code-intelligence package.",
+  "license": "MIT",
+  "author": "SharkCraft contributors",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sharkcraft/sharkcraft.git",
+    "directory": "packages/graph"
+  },
+  "homepage": "https://github.com/sharkcraft/sharkcraft",
+  "bugs": {
+    "url": "https://github.com/sharkcraft/sharkcraft/issues"
+  },
+  "keywords": [
+    "sharkcraft",
+    "graph",
+    "code-intelligence",
+    "import-graph",
+    "symbol-graph",
+    "monorepo"
+  ],
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=18"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@shrkcrft/core": "^0.1.0-alpha.10",
+    "@shrkcrft/boundaries": "^0.1.0-alpha.10",
+    "@shrkcrft/inspector": "^0.1.0-alpha.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}