cargo-json-docs 0.5.0

package/dist/json.d.ts

@@ -0,0 +1,81 @@
+export interface CrateMetaData {
+    name: string;
+    version: string;
+    documentation: string;
+}
+/**
+ * Reads the Cargo.toml file to get the crate metadata.
+ * @param cargoTomlPath The path to the Cargo.toml file.
+ * @returns The crate metadata, or null if not found.
+ */
+export declare function getCargoMeta(cargoTomlPath: string): CrateMetaData | null;
+export declare function getCargoBinPath(): string | null;
+/**
+ * Represents a source of documentation for a Rust crate.
+ *
+ * Note: Crate - not workspace. I don't currently support workspaces.
+ * PRs welcome to add this feature.
+ */
+export declare class DocumentationSource {
+    /**
+     * The path to the crate source.
+     */
+    path: string;
+    /**
+     * The name of the crate.
+     */
+    name: string;
+    /**
+     * The root URL for the crate's documentation.
+     */
+    docs_root: string;
+    /**
+     * Creates a new DocumentationSource instance.
+     * @param crate_path The path to the crate source directory (where Cargo.toml is located).
+     */
+    constructor(crate_path: string);
+    /**
+     * Gets the date and time the crate was last modified.
+     * Checks Cargo.toml and the src/ directory.
+     * @returns The last modification date.
+     */
+    lastModified(): Date;
+    /**
+     * Gets the date and time the documentation JSON was last modified.
+     * Checks for a *.json file in the doc directory.
+     * @returns The last modification date, or null if no JSON file found.
+     */
+    jsonModified(): Date | null;
+    /**
+     * Determines if the documentation JSON should be regenerated.
+     * Compares the last modified time of the crate source and the JSON file.
+     * @returns True if the JSON should be regenerated, false otherwise.
+     */
+    shouldGenerate(): boolean;
+    /**
+     * Gets the path to the documentation directory.
+     * @returns The path to the documentation directory.
+     */
+    getDocPath(): string;
+    /**
+     * Gets the path to the documentation JSON file.
+     * @returns The path to the JSON file, or null if not found.
+     */
+    getJsonPath(): string | null;
+    /**
+     * Calls the cargo binary with the specified arguments.
+     * @param args The arguments to pass to cargo.
+     * @returns The exit code of the cargo process.
+     */
+    callCargo(args: string[]): number;
+    /**
+     * Generates the documentation JSON using `cargo +nighly rustdoc --lub -- -Z unstable-options --output-format json`.
+     */
+    generateJson(): void;
+    /**
+     * Gets the documentation JSON, generating it if necessary.
+     * @returns The parsed JSON object.
+     */
+    getJson(): any;
+}
+//# sourceMappingURL=json.d.ts.map

package/dist/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,aAAa;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CA0BxE;AAqCD,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAuB/C;AAID;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC5B;;OAEG;IACI,IAAI,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACI,IAAI,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACI,SAAS,EAAE,MAAM,CAAC;IAEzB;;;OAGG;gBACS,UAAU,EAAE,MAAM;IAa9B;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAcpB;;;;OAIG;IACH,YAAY,IAAI,IAAI,GAAG,IAAI;IAS3B;;;;OAIG;IACH,cAAc,IAAI,OAAO;IAUzB;;;OAGG;IACH,UAAU,IAAI,MAAM;IAWpB;;;OAGG;IACH,WAAW,IAAI,MAAM,GAAG,IAAI;IAe5B;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM;IAcjC;;OAEG;IACH,YAAY,IAAI,IAAI;IAQpB;;;OAGG;IACH,OAAO,IAAI,GAAG;CAajB"}

package/dist/json.js

@@ -0,0 +1,226 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentationSource = void 0;
+exports.getCargoMeta = getCargoMeta;
+exports.getCargoBinPath = getCargoBinPath;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+/**
+ * Reads the Cargo.toml file to get the crate metadata.
+ * @param cargoTomlPath The path to the Cargo.toml file.
+ * @returns The crate metadata, or null if not found.
+ */
+function getCargoMeta(cargoTomlPath) {
+    if (!fs_1.default.existsSync(cargoTomlPath)) {
+        return null;
+    }
+    const cargoTomlContent = fs_1.default.readFileSync(cargoTomlPath, 'utf-8');
+    const packageSection = cargoTomlContent.match(/\[package\]([\s\S]*?)(\n\[|$)/);
+    if (!packageSection)
+        return null;
+    const section = packageSection[1];
+    const nameMatch = section.match(/^\s*name\s*=\s*["']([^"']+)["']/m);
+    if (!nameMatch) {
+        return null;
+    }
+    const name = nameMatch[1];
+    const versionMatch = section.match(/^\s*version\s*=\s*["']([^"']+)["']/m);
+    const version = versionMatch ? versionMatch[1] : '0.0.0';
+    const documentationMatch = section.match(/^\s*documentation\s*=\s*["']([^"']+)["']/m);
+    const documentation = documentationMatch ? documentationMatch[1] : `https://docs.rs/crate/${name}/latest`;
+    let meta = { name, version, documentation };
+    return meta;
+}
+/**
+ * Recursively walks a directory to find the latest modification time among all files and subdirectories.
+ * @param dirPath The directory path to walk.
+ * @returns The latest modification date found.
+ */
+function walkDirForLatestModTime(dirPath) {
+    let latestModTime = new Date(0);
+    const entries = fs_1.default.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path_1.default.join(dirPath, entry.name);
+        const stats = fs_1.default.statSync(fullPath);
+        if (stats.isSymbolicLink())
+            continue;
+        if (stats.mtime > latestModTime) {
+            latestModTime = stats.mtime;
+        }
+        if (entry.isDirectory()) {
+            const dirModTime = walkDirForLatestModTime(fullPath);
+            if (dirModTime > latestModTime) {
+                latestModTime = dirModTime;
+            }
+        }
+    }
+    return latestModTime;
+}
+/**
+ * Gets the path to the cargo binary.
+ * Checks CARGO_HOME environment variable, defaults to ~/.cargo/bin/cargo.
+ * @returns The path to the cargo binary, or null if not found.
+ */
+let cachedCargoPath = null;
+function getCargoBinPath() {
+    if (cachedCargoPath !== null) {
+        return cachedCargoPath;
+    }
+    // First run the command 'where cargo' (Windows) or 'which cargo' (Unix)
+    const isWindows = process.platform === 'win32';
+    const command = isWindows ? 'where' : 'which';
+    const result = (0, child_process_1.spawnSync)(command, ['cargo'], { encoding: 'utf-8' });
+    if (result.status === 0) {
+        const cargoPath = result.stdout.split('\n')[0].trim();
+        return cargoPath;
+    }
+    // Fallback to CARGO_HOME or default path
+    const cargoHome = process.env.CARGO_HOME || path_1.default.join(process.env.HOME || process.env.USERPROFILE || '', '.cargo');
+    const cargoBin = path_1.default.join(cargoHome, 'bin', isWindows ? 'cargo.exe' : 'cargo');
+    if (fs_1.default.existsSync(cargoBin)) {
+        cachedCargoPath = cargoBin;
+        return cargoBin;
+    }
+    return null;
+}
+// Cache exe path
+/**
+ * Represents a source of documentation for a Rust crate.
+ *
+ * Note: Crate - not workspace. I don't currently support workspaces.
+ * PRs welcome to add this feature.
+ */
+class DocumentationSource {
+    /**
+     * Creates a new DocumentationSource instance.
+     * @param crate_path The path to the crate source directory (where Cargo.toml is located).
+     */
+    constructor(crate_path) {
+        this.path = crate_path;
+        const cargoTomlPath = path_1.default.join(this.path, 'Cargo.toml');
+        const metadata = getCargoMeta(cargoTomlPath);
+        if (metadata === null) {
+            throw new Error(`Could not determine crate name from ${cargoTomlPath}`);
+        }
+        this.name = metadata.name;
+        this.docs_root = metadata.documentation;
+    }
+    /**
+     * Gets the date and time the crate was last modified.
+     * Checks Cargo.toml and the src/ directory.
+     * @returns The last modification date.
+     */
+    lastModified() {
+        let cargoTomlStat = fs_1.default.statSync(path_1.default.join(this.path, 'Cargo.toml'));
+        let srcDirStat = fs_1.default.statSync(path_1.default.join(this.path, 'src'));
+        let lastModified = cargoTomlStat.mtime;
+        let srcLastModified = walkDirForLatestModTime(path_1.default.join(this.path, 'src'));
+        if (srcLastModified > lastModified) {
+            lastModified = srcLastModified;
+        }
+        return lastModified;
+    }
+    /**
+     * Gets the date and time the documentation JSON was last modified.
+     * Checks for a *.json file in the doc directory.
+     * @returns The last modification date, or null if no JSON file found.
+     */
+    jsonModified() {
+        let file = this.getJsonPath();
+        if (file === null)
+            return null;
+        let stat = fs_1.default.statSync(file);
+        if (!stat)
+            return null;
+        return stat.mtime;
+    }
+    /**
+     * Determines if the documentation JSON should be regenerated.
+     * Compares the last modified time of the crate source and the JSON file.
+     * @returns True if the JSON should be regenerated, false otherwise.
+     */
+    shouldGenerate() {
+        let jsonMod = this.jsonModified();
+        if (jsonMod === null) {
+            return true;
+        }
+        let lastMod = this.lastModified();
+        return lastMod > jsonMod;
+    }
+    /**
+     * Gets the path to the documentation directory.
+     * @returns The path to the documentation directory.
+     */
+    getDocPath() {
+        // Check for CARGO_TARGET_DIR environment variable
+        let cargoTargetDir = process.env.CARGO_TARGET_DIR;
+        let docDir = path_1.default.join(this.path, 'target', 'doc');
+        if (cargoTargetDir) {
+            docDir = path_1.default.join(cargoTargetDir, 'doc');
+        }
+        return docDir;
+    }
+    /**
+     * Gets the path to the documentation JSON file.
+     * @returns The path to the JSON file, or null if not found.
+     */
+    getJsonPath() {
+        let docDir = this.getDocPath();
+        if (!fs_1.default.existsSync(docDir)) {
+            return null;
+        }
+        let files = fs_1.default.readdirSync(docDir);
+        let jsonFiles = files.filter((f) => f == `${this.name}.json`);
+        if (jsonFiles.length === 0) {
+            return null;
+        }
+        return path_1.default.join(docDir, jsonFiles[0]);
+    }
+    /**
+     * Calls the cargo binary with the specified arguments.
+     * @param args The arguments to pass to cargo.
+     * @returns The exit code of the cargo process.
+     */
+    callCargo(args) {
+        let bin = getCargoBinPath();
+        if (bin === null) {
+            throw new Error('Cargo binary not found.');
+        }
+        let result = (0, child_process_1.spawnSync)(bin, args, {
+            cwd: this.path,
+            stdio: 'inherit',
+        });
+        return result.status || 0;
+    }
+    /**
+     * Generates the documentation JSON using `cargo +nighly rustdoc --lub -- -Z unstable-options --output-format json`.
+     */
+    generateJson() {
+        let result = this.callCargo(['+nightly', 'rustdoc', '--lib', '--', '-Z', 'unstable-options', '--output-format', 'json']);
+        console.log(`Cargo rustdoc exited with code ${result}`);
+        if (result !== 0) {
+            throw new Error('Failed to generate documentation JSON.');
+        }
+    }
+    /**
+     * Gets the documentation JSON, generating it if necessary.
+     * @returns The parsed JSON object.
+     */
+    getJson() {
+        if (this.shouldGenerate()) {
+            this.generateJson();
+        }
+        let jsonPath = this.getJsonPath();
+        if (jsonPath === null) {
+            throw new Error('Documentation JSON file not found after generation.');
+        }
+        let jsonData = fs_1.default.readFileSync(jsonPath, 'utf-8');
+        return JSON.parse(jsonData);
+    }
+}
+exports.DocumentationSource = DocumentationSource;
+//# sourceMappingURL=json.js.map

package/dist/json.js.map

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

package/dist/lib.d.ts

@@ -0,0 +1,21 @@
+import { DocumentationSource } from "./json";
+import { CrateDocs } from "./item";
+import { ResolutionError, CargoFormatError } from "./errors";
+export { DocumentationSource, CrateDocs, ResolutionError, CargoFormatError };
+/**
+ * Loads a crate's documentation from source.
+ * @param name The name of the crate.
+ * @param docs_root The root URL for the crate's documentation.
+ * @param path The path to the crate's source directory (e.g., the directory containing Cargo.toml).
+ * @returns The loaded CrateDocs object.
+ */
+export declare function loadCrate(path: string): CrateDocs;
+/**
+ * Loads a crate's documentation from a JSON string.
+ * @param name The name of the crate.
+ * @param docs_root The root URL for the crate's documentation.
+ * @param json The JSON string containing the documentation data.
+ * @returns The loaded CrateDocs object.
+ */
+export declare function loadCrateFromJson(name: string, docs_root: string, json: string): CrateDocs;
+//# sourceMappingURL=lib.d.ts.map

package/dist/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAE7D,OAAO,EAAE,mBAAmB,EAAE,SAAS,EAAE,eAAe,EAAE,gBAAgB,EAAE,CAAC;AAE7E;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAIjD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAG1F"}

package/dist/lib.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CargoFormatError = exports.ResolutionError = exports.CrateDocs = exports.DocumentationSource = void 0;
+exports.loadCrate = loadCrate;
+exports.loadCrateFromJson = loadCrateFromJson;
+const json_1 = require("./json");
+Object.defineProperty(exports, "DocumentationSource", { enumerable: true, get: function () { return json_1.DocumentationSource; } });
+const item_1 = require("./item");
+Object.defineProperty(exports, "CrateDocs", { enumerable: true, get: function () { return item_1.CrateDocs; } });
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "ResolutionError", { enumerable: true, get: function () { return errors_1.ResolutionError; } });
+Object.defineProperty(exports, "CargoFormatError", { enumerable: true, get: function () { return errors_1.CargoFormatError; } });
+/**
+ * Loads a crate's documentation from source.
+ * @param name The name of the crate.
+ * @param docs_root The root URL for the crate's documentation.
+ * @param path The path to the crate's source directory (e.g., the directory containing Cargo.toml).
+ * @returns The loaded CrateDocs object.
+ */
+function loadCrate(path) {
+    const docSource = new json_1.DocumentationSource(path);
+    const jsonSource = docSource.getJson();
+    return new item_1.CrateDocs(docSource.name, docSource.docs_root, jsonSource);
+}
+/**
+ * Loads a crate's documentation from a JSON string.
+ * @param name The name of the crate.
+ * @param docs_root The root URL for the crate's documentation.
+ * @param json The JSON string containing the documentation data.
+ * @returns The loaded CrateDocs object.
+ */
+function loadCrateFromJson(name, docs_root, json) {
+    const source = JSON.parse(json);
+    return new item_1.CrateDocs(name, docs_root, source);
+}
+//# sourceMappingURL=lib.js.map

package/dist/lib.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":";;;AAaA,8BAIC;AASD,8CAGC;AA7BD,iCAA6C;AAIpC,oGAJA,0BAAmB,OAIA;AAH5B,iCAAmC;AAGL,0FAHrB,gBAAS,OAGqB;AAFvC,qCAA6D;AAEpB,gGAFhC,wBAAe,OAEgC;AAAE,iGAFhC,yBAAgB,OAEgC;AAE1E;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,IAAY;IAClC,MAAM,SAAS,GAAG,IAAI,0BAAmB,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,EAAE,CAAC;IACvC,OAAO,IAAI,gBAAS,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,iBAAiB,CAAC,IAAY,EAAE,SAAiB,EAAE,IAAY;IAC3E,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,IAAI,gBAAS,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;AAClD,CAAC"}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "cargo-json-docs",
+  "version": "0.5.0",
+  "description": "Programmatic access to Rust crate documentation via cargo JSON output",
+  "license": "MIT",
+  "author": "Richard Carson",
+  "repository": "https://github.com/rscarson/cargo-json-docs",
+  "readme": "readme.md",
+  "type": "module",
+  "main": "dist/lib.js",
+  "types": "dist/types.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.0.3",
+    "jest": "^30.2.0",
+    "node-fetch": "^3.3.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  }
+}

package/readme.md

@@ -0,0 +1,95 @@
+# cargo-json-docs
+## Programmatic access to Rust crate documentation via cargo JSON output
+
+Gives you access to a rust crate's documentation (functions, structs, enums, traits, constants, type aliases, macros, and modules) by their Rust path. Documentation can be loaded from a local crate source directory, or from pre-generated rustdoc JSON.
+
+The `docs.rs` documentation URL for each item is also provided for easy linking.
+
+## Installation
+
+```bash
+npm install cargo-json-docs
+```
+
+## Usage
+
+### `loadCrate(path: string): CrateDocs`
+
+Loads documentation from a local crate source directory (must contain `Cargo.toml`).
+
+```ts
+import { loadCrate } from 'cargo-json-docs';
+
+const docs = loadCrate('path/to/crate');
+const item = docs.get('module::Type::method');
+console.log(item.url);
+```
+
+### `loadCrateFromJson(name: string, docs_root: string, json: string): CrateDocs`
+
+Loads documentation from a JSON string (pre-generated rustdoc JSON).
+
+```ts
+import { loadCrateFromJson } from 'cargo-json-docs';
+
+const jsonString = fs.readFileSync('crate.json', 'utf-8');
+const docs = loadCrateFromJson('crate_name', 'https://docs.rs/crate_name/latest/', jsonString);
+```
+
+### `DocumentationSource`
+
+Represents the source of a crate’s documentation. Handles:
+
+* Cargo doc generation
+* JSON generation and caching
+* Stale JSON detection by file modification time
+
+Methods:
+
+* `lastModified(): Date` — Returns last modification timestamp
+* `shouldGenerate(): boolean` — True if JSON generation is needed
+* `generateJson(): void` — Generates rustdoc JSON
+* `getJson(): any` — Retrieves the JSON object
+* `callCargo(args: string[]): number` — Runs cargo commands
+
+### `CrateDocs`
+
+Provides lookup of documented items by path:
+
+* `get(path: string): DocumentedItem | undefined` — Retrieves item metadata
+* `DocumentedItem` fields:
+
+  * `name: string`
+  * `path: string`
+  * `kind: ItemKind`
+  * `url: string`
+
+### Errors
+
+* `ResolutionError` — Path lookup failure
+* `CargoFormatError` — Cargo JSON generation failure. This usually indicates a change in the JSON format used by rustdoc - please open a GitHub issue if you encounter this error.
+
+---
+
+## Example
+
+```ts
+import { loadCrate } from 'cargo-json-docs';
+
+const docs = loadCrate('test/test_crate');
+const addFn = docs.get('add');
+
+if (addFn) {
+  console.log(addFn.kind); // 'function'
+  console.log(addFn.url);  // 'https://docs.rs/crate/test_crate/latest/test_crate/fn.add.html'
+}
+```
+
+---
+
+## Assumptions & Limitations
+
+* Cargo needs to be installed and in PATH somewhere
+* Rust crate must build locally; `cargo doc` required
+* It will attempt to call the nighlty toolchain, since json output is only supported there
+* There's likely to be edge cases that aren't handled yet - please open issues as needed!

package/src/errors.ts

@@ -0,0 +1,31 @@
+
+/**
+ * An error that occurs when resolving an item path.
+ */
+export class ResolutionError extends Error {
+    /**
+     * The last successfully resolved parent path.
+     */
+    last_good_parent: string;
+
+    /**
+     * The unresolved item name.
+     */
+    unresolved: string;
+
+    constructor(last_good_parent: string, unresolved: string) {
+        super(`${last_good_parent}::${unresolved} does not exist or could not be resolved.`);
+        this.last_good_parent = last_good_parent;
+        this.unresolved = unresolved;
+    }
+}
+/**
+ * An error that occurs when the documentation JSON format is not as expected.
+ * Usually means the format has changed for the version of Rust used to generate the docs.
+ * Open a GitHub issue if you encounter this error.
+ */
+export class CargoFormatError extends Error {
+    constructor(message: string) {
+        super(`JSON format unrecognized or invalid. Please open a GitHub issue if you see this message.\nDetails: ${message}`);
+    }
+}