cargo-json-docs 0.5.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Carson
+
+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/dist/errors.d.ts

@@ -0,0 +1,23 @@
+/**
+ * An error that occurs when resolving an item path.
+ */
+export declare 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);
+}
+/**
+ * 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 declare class CargoFormatError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACtC;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;gBAEP,gBAAgB,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAK3D;AACD;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAG9B"}

package/dist/errors.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CargoFormatError = exports.ResolutionError = void 0;
+/**
+ * An error that occurs when resolving an item path.
+ */
+class ResolutionError extends Error {
+    constructor(last_good_parent, unresolved) {
+        super(`${last_good_parent}::${unresolved} does not exist or could not be resolved.`);
+        this.last_good_parent = last_good_parent;
+        this.unresolved = unresolved;
+    }
+}
+exports.ResolutionError = ResolutionError;
+/**
+ * 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.
+ */
+class CargoFormatError extends Error {
+    constructor(message) {
+        super(`JSON format unrecognized or invalid. Please open a GitHub issue if you see this message.\nDetails: ${message}`);
+    }
+}
+exports.CargoFormatError = CargoFormatError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AACA;;GAEG;AACH,MAAa,eAAgB,SAAQ,KAAK;IAWtC,YAAY,gBAAwB,EAAE,UAAkB;QACpD,KAAK,CAAC,GAAG,gBAAgB,KAAK,UAAU,2CAA2C,CAAC,CAAC;QACrF,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IACjC,CAAC;CACJ;AAhBD,0CAgBC;AACD;;;;GAIG;AACH,MAAa,gBAAiB,SAAQ,KAAK;IACvC,YAAY,OAAe;QACvB,KAAK,CAAC,sGAAsG,OAAO,EAAE,CAAC,CAAC;IAC3H,CAAC;CACJ;AAJD,4CAIC"}

package/dist/item.d.ts

@@ -0,0 +1,100 @@
+import type { IndexEntry, CrateEntry, PathEntry, DocumentedItem, ItemKind } from "./types";
+/**
+ * A node in the cargo item tree.
+ * Used for resolving item paths.
+ */
+declare class CargoItemNode {
+    id: number;
+    name: string;
+    kind: ItemKind;
+    parentKind: ItemKind;
+    children: Map<string, CargoItemNode>;
+    docs_md: string | null;
+    /** The full path to this node, populated during tree walks. */
+    path: string;
+    /** Whether the children of this node have been populated. */
+    childrenPopulated: boolean;
+    /** If true, start the path over from the given crate */
+    shouldJumpToCrate: string | null;
+    /** Whether to suppress presence in urls */
+    silent: boolean;
+    /** Creates a new CargoItemNode. */
+    constructor(id: number, name: string, kind: ItemKind, parentKind: ItemKind, path: string, docs_md?: string | null);
+    /** Adds a child node. */
+    addChild(child: CargoItemNode): void;
+    /** Gets a child node by name. */
+    childNamed(name: string): CargoItemNode | null;
+}
+/**
+ * Parses the cargo JSON documentation format into a clean graph structure.
+ */
+declare class CargoJsonParser {
+    index: Map<string, IndexEntry>;
+    crates: Map<string, CrateEntry>;
+    paths: Map<string, PathEntry>;
+    next_id: number;
+    lookup_tree: CargoItemNode;
+    /**
+     * Creates a new CrateDocs instance.
+     * @param name The name of the crate.
+     * @param docs_root The root URL for the crate's documentation.
+     * @param source The JSON source. You can get this from DocumentationSource.getJson().
+     * @returns A new CrateDocs instance.
+     */
+    constructor(name: string, docs_root: string, source: any);
+    /** Gets the URL component for a given CargoItemNode. */
+    urlComponentEncode(node: CargoItemNode): string;
+    /**
+     * Searches for a path entry by its path components
+     * If nothing is found, invents a module
+     */
+    private pathEntryByPath;
+    private pathEntry;
+    private indexEntryContents;
+    /**
+     * First we make sure the start is a crate name
+     * If not, append the current crate name
+     * If 'crate' replaced with current crate name
+     * If it's a crate that cannot be a root module only try that crate
+     * Else try current crate first, then other one
+     * @param path Path to fix
+     * @returns All viable candidate paths.
+     */
+    private fixPathCrate;
+    /** Populates the children of a given CargoItemNode. */
+    private populateChildren;
+    /**
+     * When going through paths, we may come across modules that are not directly represented in the index.
+     * This walks up the path to populate missing modules as needed.
+     */
+    private populateMissingPathModules;
+    /**
+     * Walks the item tree to find a node by path.
+     * @param path The path to walk.
+     * @returns The path to the found CargoItemNode.
+     * @throws ResolutionError if the path cannot be resolved.
+     */
+    walkTree(path: string[]): CargoItemNode[];
+    /** Gets the current crate name. */
+    ownCrateName(): string;
+}
+export declare class CrateDocs {
+    parser: CargoJsonParser;
+    /**
+     * Creates a new CrateDocs instance.
+     * @param name The name of the crate.
+     * @param docs_root The root URL for the crate's documentation.
+     * @param source The JSON source. You can get this from DocumentationSource.getJson().
+     * @returns A new CrateDocs instance.
+     */
+    constructor(name: string, docs_root: string, source: any);
+    /**
+     * Gets a documented item by its path.
+     * @param path The item path, e.g., "crate::module::Item" or "Item".
+     * @returns The documented item.
+     * @throws ResolutionError if the item cannot be found.
+     */
+    get(path: string): DocumentedItem;
+}
+export {};
+//# sourceMappingURL=item.d.ts.map

package/dist/item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item.d.ts","sourceRoot":"","sources":["../src/item.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAER,UAAU,EAAE,UAAU,EAAE,SAAS,EACjC,cAAc,EAAE,QAAQ,EAC3B,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,cAAM,aAAa;IACf,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,QAAQ,CAAC;IACrB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACrC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAEvB,+DAA+D;IACxD,IAAI,EAAE,MAAM,CAAC;IAEpB,6DAA6D;IACtD,iBAAiB,EAAE,OAAO,CAAS;IAE1C,wDAAwD;IACjD,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE/C,2CAA2C;IACpC,MAAM,EAAE,OAAO,CAAS;IAE/B,mCAAmC;gBACvB,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAM,GAAG,IAAW;IAUvH,yBAAyB;IACzB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI;IASpC,iCAAiC;IACjC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI;CAYjD;AAED;;GAEG;AACH,cAAM,eAAe;IACjB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAiC;IAC/D,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAiC;IAChE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAgC;IAE7D,OAAO,EAAE,MAAM,CAAK;IACpB,WAAW,EAAE,aAAa,CAAyD;IAEnF;;;;;;OAMG;gBACS,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG;IA4ExD,wDAAwD;IACjD,kBAAkB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM;IA8DtD;;;OAGG;IACH,OAAO,CAAC,eAAe;IAsDvB,OAAO,CAAC,SAAS;IAqEjB,OAAO,CAAC,kBAAkB;IAmI1B;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAqBpB,uDAAuD;IACvD,OAAO,CAAC,gBAAgB;IAgBxB;;;OAGG;IACH,OAAO,CAAC,0BAA0B;IAsBlC;;;;;OAKG;IACI,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,EAAE;IA6ChD,mCAAmC;IAC5B,YAAY,IAAI,MAAM;CAIhC;AAED,qBAAa,SAAS;IAClB,MAAM,EAAE,eAAe,CAAC;IAExB;;;;;;OAMG;gBACS,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG;IAIxD;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;CAwB3C"}