@0xsarwagya/ontoly-cache 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sarwagya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @0xsarwagya/ontoly-cache
+
+Local graph artifact persistence for Ontoly.
+
+This package is part of [Ontoly](https://github.com/0xsarwagya/ontoly), a TypeScript-native software intelligence engine that builds a deterministic Software Graph.
+
+## Installation
+
+```bash
+pnpm add @0xsarwagya/ontoly-cache
+```
+
+## Status
+
+Alpha package for Ontoly v0.1.0-alpha.1. The public API is versioned with the Software Graph and RFC process.
+
+## Links
+
+- [Repository](https://github.com/0xsarwagya/ontoly)
+- [Documentation](https://oss.sarwagya.wtf/ontoly)
+- [Issues](https://github.com/0xsarwagya/ontoly/issues)

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import type { SoftwareGraph } from "@0xsarwagya/ontoly-core";
+export interface GraphArtifactPaths {
+    readonly root: string;
+    readonly directory: string;
+    readonly graph: string;
+    readonly legacyGraph: string;
+    readonly diagnostics: string;
+    readonly metadata: string;
+    readonly indexes: string;
+    readonly statistics: string;
+    readonly cache: string;
+}
+export interface PersistGraphOptions {
+    readonly root: string;
+    readonly directory?: string | undefined;
+}
+export declare function getGraphArtifactPaths(options: PersistGraphOptions): GraphArtifactPaths;
+export declare function persistGraph(graph: SoftwareGraph, options: PersistGraphOptions): Promise<GraphArtifactPaths>;
+export declare function loadGraph(options: PersistGraphOptions): Promise<SoftwareGraph>;
+export declare function persistCompilerCache(options: PersistGraphOptions, cache: unknown): Promise<GraphArtifactPaths>;
+export declare function loadCompilerCache<T>(options: PersistGraphOptions, fallback: T): Promise<T>;
+//# 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":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7D,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,CActF;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,aAAa,EACpB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,kBAAkB,CAAC,CAc7B;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAIpF;AAED,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,kBAAkB,CAAC,CAK7B;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,CAAC,GACV,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/index.js

@@ -0,0 +1,99 @@
+// src/index.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+function getGraphArtifactPaths(options) {
+  const directory = join(options.root, options.directory ?? ".ontoly");
+  return {
+    root: options.root,
+    directory,
+    graph: join(directory, "SoftwareGraph.json"),
+    legacyGraph: join(directory, "graph.json"),
+    diagnostics: join(directory, "diagnostics.json"),
+    metadata: join(directory, "metadata.json"),
+    indexes: join(directory, "indexes.json"),
+    statistics: join(directory, "statistics.json"),
+    cache: join(directory, "cache.json")
+  };
+}
+async function persistGraph(graph, options) {
+  const paths = getGraphArtifactPaths(options);
+  await mkdir(paths.directory, { recursive: true });
+  await Promise.all([
+    writeJson(paths.graph, graph),
+    writeJson(paths.legacyGraph, graph),
+    writeJson(paths.diagnostics, graph.diagnostics),
+    writeJson(paths.metadata, graph.metadata),
+    writeJson(paths.indexes, graph.indexes),
+    writeJson(paths.statistics, createGraphStatistics(graph))
+  ]);
+  return paths;
+}
+async function loadGraph(options) {
+  const paths = getGraphArtifactPaths(options);
+  const contents = await readFirstExisting([paths.graph, paths.legacyGraph]);
+  return JSON.parse(contents);
+}
+async function persistCompilerCache(options, cache) {
+  const paths = getGraphArtifactPaths(options);
+  await mkdir(paths.directory, { recursive: true });
+  await writeJson(paths.cache, cache);
+  return paths;
+}
+async function loadCompilerCache(options, fallback) {
+  const paths = getGraphArtifactPaths(options);
+  try {
+    const contents = await readFile(paths.cache, "utf8");
+    return JSON.parse(contents);
+  } catch (error) {
+    if (isMissingFileError(error)) {
+      return fallback;
+    }
+    throw error;
+  }
+}
+async function writeJson(path, value) {
+  await writeFile(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
+async function readFirstExisting(paths) {
+  let lastError;
+  for (const path of paths) {
+    try {
+      return await readFile(path, "utf8");
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  throw lastError;
+}
+function createGraphStatistics(graph) {
+  return {
+    files: graph.metadata.fileCount,
+    nodes: graph.nodes.length,
+    edges: graph.edges.length,
+    diagnostics: graph.diagnostics.length,
+    nodesByType: countBy(graph.nodes.map((node) => node.type)),
+    edgesByType: countBy(graph.edges.map((edge) => edge.type)),
+    parserVersions: graph.metadata.parserVersions,
+    deterministicHash: graph.metadata.deterministicHash
+  };
+}
+function countBy(values) {
+  return Object.fromEntries(
+    [...values.reduce((counts, value) => {
+      counts.set(value, (counts.get(value) ?? 0) + 1);
+      return counts;
+    }, /* @__PURE__ */ new Map()).entries()].sort(([left], [right]) => left.localeCompare(right))
+  );
+}
+function isMissingFileError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+export {
+  getGraphArtifactPaths,
+  loadCompilerCache,
+  loadGraph,
+  persistCompilerCache,
+  persistGraph
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { SoftwareGraph } from \"@0xsarwagya/ontoly-core\";\n\nexport interface GraphArtifactPaths {\n  readonly root: string;\n  readonly directory: string;\n  readonly graph: string;\n  readonly legacyGraph: string;\n  readonly diagnostics: string;\n  readonly metadata: string;\n  readonly indexes: string;\n  readonly statistics: string;\n  readonly cache: string;\n}\n\nexport interface PersistGraphOptions {\n  readonly root: string;\n  readonly directory?: string | undefined;\n}\n\nexport function getGraphArtifactPaths(options: PersistGraphOptions): GraphArtifactPaths {\n  const directory = join(options.root, options.directory ?? \".ontoly\");\n\n  return {\n    root: options.root,\n    directory,\n    graph: join(directory, \"SoftwareGraph.json\"),\n    legacyGraph: join(directory, \"graph.json\"),\n    diagnostics: join(directory, \"diagnostics.json\"),\n    metadata: join(directory, \"metadata.json\"),\n    indexes: join(directory, \"indexes.json\"),\n    statistics: join(directory, \"statistics.json\"),\n    cache: join(directory, \"cache.json\"),\n  };\n}\n\nexport async function persistGraph(\n  graph: SoftwareGraph,\n  options: PersistGraphOptions,\n): Promise<GraphArtifactPaths> {\n  const paths = getGraphArtifactPaths(options);\n  await mkdir(paths.directory, { recursive: true });\n\n  await Promise.all([\n    writeJson(paths.graph, graph),\n    writeJson(paths.legacyGraph, graph),\n    writeJson(paths.diagnostics, graph.diagnostics),\n    writeJson(paths.metadata, graph.metadata),\n    writeJson(paths.indexes, graph.indexes),\n    writeJson(paths.statistics, createGraphStatistics(graph)),\n  ]);\n\n  return paths;\n}\n\nexport async function loadGraph(options: PersistGraphOptions): Promise<SoftwareGraph> {\n  const paths = getGraphArtifactPaths(options);\n  const contents = await readFirstExisting([paths.graph, paths.legacyGraph]);\n  return JSON.parse(contents) as SoftwareGraph;\n}\n\nexport async function persistCompilerCache(\n  options: PersistGraphOptions,\n  cache: unknown,\n): Promise<GraphArtifactPaths> {\n  const paths = getGraphArtifactPaths(options);\n  await mkdir(paths.directory, { recursive: true });\n  await writeJson(paths.cache, cache);\n  return paths;\n}\n\nexport async function loadCompilerCache<T>(\n  options: PersistGraphOptions,\n  fallback: T,\n): Promise<T> {\n  const paths = getGraphArtifactPaths(options);\n\n  try {\n    const contents = await readFile(paths.cache, \"utf8\");\n    return JSON.parse(contents) as T;\n  } catch (error) {\n    if (isMissingFileError(error)) {\n      return fallback;\n    }\n\n    throw error;\n  }\n}\n\nasync function writeJson(path: string, value: unknown): Promise<void> {\n  await writeFile(path, `${JSON.stringify(value, null, 2)}\\n`, \"utf8\");\n}\n\nasync function readFirstExisting(paths: readonly string[]): Promise<string> {\n  let lastError: unknown;\n\n  for (const path of paths) {\n    try {\n      return await readFile(path, \"utf8\");\n    } catch (error) {\n      lastError = error;\n    }\n  }\n\n  throw lastError;\n}\n\nfunction createGraphStatistics(graph: SoftwareGraph): Record<string, unknown> {\n  return {\n    files: graph.metadata.fileCount,\n    nodes: graph.nodes.length,\n    edges: graph.edges.length,\n    diagnostics: graph.diagnostics.length,\n    nodesByType: countBy(graph.nodes.map((node) => node.type)),\n    edgesByType: countBy(graph.edges.map((edge) => edge.type)),\n    parserVersions: graph.metadata.parserVersions,\n    deterministicHash: graph.metadata.deterministicHash,\n  };\n}\n\nfunction countBy(values: readonly string[]): Record<string, number> {\n  return Object.fromEntries(\n    [...values.reduce((counts, value) => {\n      counts.set(value, (counts.get(value) ?? 0) + 1);\n      return counts;\n    }, new Map<string, number>()).entries()].sort(([left], [right]) => left.localeCompare(right)),\n  );\n}\n\nfunction isMissingFileError(error: unknown): boolean {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"code\" in error &&\n    (error as { readonly code?: unknown }).code === \"ENOENT\"\n  );\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@0xsarwagya/ontoly-cache",
+  "version": "0.1.0-alpha.1",
+  "description": "Local graph artifact persistence for Ontoly.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xsarwagya/ontoly.git",
+    "directory": "packages/cache"
+  },
+  "homepage": "https://oss.sarwagya.wtf/ontoly",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@0xsarwagya/ontoly-core": "0.1.0-alpha.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsup": "^8.3.5",
+    "typescript": "5.9.2"
+  },
+  "bugs": {
+    "url": "https://github.com/0xsarwagya/ontoly/issues"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/0xsarwagya"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "pnpm": ">=11.0.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "keywords": [
+    "ontoly",
+    "software-graph",
+    "typescript",
+    "static-analysis",
+    "developer-tools",
+    "cache",
+    "artifacts",
+    "persistence"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit"
+  }
+}