cargo-json-docs 0.5.0

package/src/item.ts

@@ -0,0 +1,658 @@
+import { ResolutionError, CargoFormatError } from "./errors";
+import type { 
+    ModuleProps, StructProps, EnumProps, FunctionProps, TraitProps, UseProps,
+    IndexEntry, CrateEntry, PathEntry, 
+    DocumentedItem, ItemKind,
+} from "./types";
+
+/**
+ * A node in the cargo item tree.
+ * Used for resolving item paths.
+ */
+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. */
+    public path: string;
+
+    /** Whether the children of this node have been populated. */
+    public childrenPopulated: boolean = false;
+
+    /** If true, start the path over from the given crate */
+    public shouldJumpToCrate: string | null = null;
+
+    /** Whether to suppress presence in urls */
+    public silent: boolean = false;
+
+    /** Creates a new CargoItemNode. */
+    constructor(id: number, name: string, kind: ItemKind, parentKind: ItemKind, path: string, docs_md: string | null = null) {
+        this.id = id;
+        this.name = name;
+        this.kind = kind;
+        this.parentKind = parentKind;
+        this.children = new Map<string, CargoItemNode>();
+        this.docs_md = docs_md;
+        this.path = path;
+    }
+
+    /** Adds a child node. */
+    addChild(child: CargoItemNode): void {
+        if (child.name === undefined || child.name === null || child.name.length === 0) {
+            throw new Error(`Cannot add child with empty name to node ${this.name}`);
+        }
+
+        this.children.set(child.name, child);
+        this.childrenPopulated = true;
+    }
+
+    /** Gets a child node by name. */
+    childNamed(name: string): CargoItemNode | null {
+        let child = this.children.get(name);
+        if (child) return child;
+
+        // Check for a path ending in the name
+        for (let [childName, childNode] of this.children) {
+            if (childName.endsWith('::' + name)) {
+                return childNode;
+            }
+        }
+        return null;
+    }
+}
+
+/**
+ * Parses the cargo JSON documentation format into a clean graph structure.
+ */
+class CargoJsonParser {
+    index: Map<string, IndexEntry> = new Map<string, IndexEntry>();
+    crates: Map<string, CrateEntry> = new Map<string, CrateEntry>();
+    paths: Map<string, PathEntry> = new Map<string, PathEntry>();
+    
+    next_id: number = 0;
+    lookup_tree: CargoItemNode = new CargoItemNode(-1, 'root', 'module', 'module', '');
+    
+    /**
+     * 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) {
+        if (!docs_root.endsWith('/')) {
+            docs_root += '/';
+        }
+
+        //
+        // Get the crate root entry, to find the top-level items
+        let rootEntry = source.index[source.root.toString()].inner['module'] as ModuleProps;
+        let rootEntries: Set<string> = new Set<string>();
+        for (let itemId of rootEntry.items) {
+            let item = source.index[itemId.toString()];
+            if (item.name) rootEntries.add(item.name);
+        }
+
+        //
+        // First the current crate will be added to the crate registry and as a root node
+        this.lookup_tree.addChild(new CargoItemNode(source.root, name, 'crate', 'module', name));
+        this.crates.set(name, {
+            id: source.root.toString(),
+            name: name,
+            html_root_url: docs_root,
+            could_be_root_module: rootEntries.has(name),
+        });
+        if (source.root > this.next_id) this.next_id = source.root + 1;
+
+        //
+        // Do the same with the external crates
+        for (let id in source.external_crates) {
+            let item = source.external_crates[id];
+            item.id = id;
+
+            let crateId = parseInt(id);
+            if (crateId > this.next_id) this.next_id = crateId + 1;
+
+            if (!item.html_root_url.endsWith('/')) {
+                item.html_root_url += '/';
+            }
+            
+            this.lookup_tree.addChild(new CargoItemNode(crateId, item.name, 'crate', 'module', item.name));
+            this.crates.set(item.name, item);
+        }
+
+        //
+        // Next we build the index
+        for (let id in source.index) {
+            let item = source.index[id];
+
+            let indexId = parseInt(id);
+            if (indexId > this.next_id) this.next_id = indexId + 1;
+
+            // The first key in `inner` is the kind
+            let kindKey = Object.keys(item.inner)[0];
+            item.kind = kindKey as unknown as ItemKind;
+
+            if (item.kind == 'module') {
+                item.is_crate = item.inner['module'].is_crate;
+            } else {
+                item.is_crate = false;
+            }
+
+            this.index.set(id, item);
+        }
+
+        //
+        // Next we build the paths
+        this.paths = new Map<string, PathEntry>();
+        for (let id in source.paths) {
+            let item = source.paths[id];
+
+            let pathId = parseInt(id);
+            if (pathId > this.next_id) this.next_id = pathId + 1;
+
+            this.paths.set(id, item);
+        }
+    }
+
+    /** Gets the URL component for a given CargoItemNode. */
+    public urlComponentEncode(node: CargoItemNode): string {
+        if (node.silent) return '';
+
+        switch (node.kind) {
+            case 'crate': {
+                return this.crates.get(node.name)!.html_root_url + node.name + '/';
+            }
+
+            case 'module': {
+                return `${node.name}/`;
+            }
+
+            case 'function': {
+                if (node.parentKind === 'module' || node.parentKind === 'crate') {
+                    return `fn.${node.name}.html`;
+                } else {
+                    return `#method.${node.name}`;
+                }
+            }
+
+            case 'functiontype': {
+                if (node.parentKind === 'module' || node.parentKind === 'crate') {
+                    return `fn.${node.name}.html`;
+                } else {
+                    return `#tymethod.${node.name}`;
+                }
+            }
+
+            case 'variant': {
+                return `#variant.${node.name}`;
+            }
+
+            case 'struct_field': {
+                return `#structfield.${node.name}`;
+            }
+
+            case 'assoc_type': {
+                return `#associatedtype.${node.name}`;
+            }
+
+            case 'assoc_const': {
+                return `#associatedconstant.${node.name}`;
+            }
+
+            case 'type_alias': {
+                return `type.${node.name}.html`;
+            }
+
+            case 'constant':
+            case 'macro':
+            case 'struct':
+            case 'enum':
+            case 'trait':
+            case 'impl': {
+                return `${node.kind}.${node.name}.html`;
+            }
+
+            default:
+                throw new CargoFormatError(`Unhandled item kind for URL encoding: ${node.kind} (name = ${node.name})`);
+        }
+    }
+
+    /** 
+     * Searches for a path entry by its path components
+     * If nothing is found, invents a module
+     */
+    private pathEntryByPath(path: string[]) {
+        path = path.slice(); // Clone
+
+        for (let [id, entry] of this.paths) {
+            let entryPath = entry.path;
+            if (entryPath.length != path.length) continue;
+
+            let matches = true;
+            for (let i=0; i < path.length; i++) {
+                if (entryPath[i] !== path[i]) {
+                    matches = false;
+                    break;
+                }
+            }
+
+            if (matches) {
+                return;
+            }
+        }
+
+        // Not found - invent a module
+        let id = this.next_id++;
+        let crate = this.crates.get(path[0]!)!;
+        this.paths.set(id.toString(), {
+            crate_id: parseInt(this.crates.get(path[0]!)!.id),
+            path: path,
+            kind: 'module',
+            silent: true,
+        });
+
+        // If the parent is a module in the index, add this to its items
+        if (path.length > 1) {
+            let node = this.walkTree(path.slice(0, path.length - 1));
+            let parentNode = node[node.length - 1]!;
+            let parentEntry = this.index.get(parentNode.id.toString());
+            if (parentEntry && parentEntry.kind == 'module') {
+                let moduleInner = parentEntry.inner['module'] as ModuleProps;
+                moduleInner.items.push(id);
+
+                this.populateChildren(parentNode);
+                let child = new CargoItemNode(
+                    id, path[path.length - 1]!, 'module', 'module', path.join('::')
+                );
+                child.silent = true;
+                parentNode.addChild(child);
+            }
+        }
+
+        let entry = this.pathEntry(id)!;
+        entry.name = path[path.length - 1]!;
+        if (path.length > 1) entry.is_crate = false;
+        return;
+    }
+
+    private pathEntry(id: number|string): IndexEntry | null {
+        id = id.toString();
+        let containerPath = this.paths.get(id);
+        if (!containerPath) {
+            for (let crate of this.crates.values()) {
+                if (crate.id === id) containerPath = {
+                    crate_id: parseInt(crate.id),
+                    path: [crate.name],
+                    kind: 'crate',
+                    silent: false,
+                }
+            }
+        }
+        if (!containerPath) return null;
+
+        let children: number[] = [];
+        for (let pathId of this.paths.keys()) {
+            let item = this.paths.get(pathId.toString());
+            if (!item || item.path.length != containerPath.path.length + 1) continue;
+
+            let matches = true;
+            for (let i=0; i < containerPath.path.length; i++) {
+                if (item.path[i] !== containerPath.path[i]) {
+                    matches = false;
+                    break;
+                }
+            }
+
+            if (matches) {
+                children.push(parseInt(pathId));
+            }
+        }
+        
+        let inner: any = {};
+        switch (containerPath.kind) {
+            case 'crate':
+            case 'module': {
+                inner['items'] = children;
+            } break;
+
+            case 'struct': {
+                inner['tuple'] = children;
+            } break;
+
+            case 'enum': {
+                inner['variants'] = children;
+            } break;
+
+            case 'trait': {
+                inner['items'] = children;
+            } break;
+        }
+
+        inner = { [containerPath.kind]: inner };
+        let name = containerPath.path.join('::');
+        let entry: IndexEntry = {
+            id: parseInt(id),
+            crate_id: containerPath.crate_id,
+            is_crate: false,
+            name: name,
+            kind: containerPath.kind,
+            docs: null,
+            silent: containerPath.silent,
+            inner: inner,
+        }
+
+        return entry;
+    }
+
+    private indexEntryContents(id: number|string, is_extern_crate: boolean = false): IndexEntry[] | null {
+        id = id.toString();
+        let parentEntry = null;
+        if (!is_extern_crate) parentEntry = this.index.get(id);
+        if (!parentEntry) {
+            let pathEntry = this.pathEntry(id);
+            if (pathEntry) parentEntry = pathEntry;
+            else return null;
+        }
+
+        switch (parentEntry.kind) {
+            case 'crate':
+            case 'module': {
+                let moduleInner = parentEntry.inner[parentEntry.kind] as ModuleProps;
+
+                let entries: IndexEntry[] = [];
+                for (let itemId of moduleInner.items) {
+                    let entry = this.index.get(itemId.toString())!;
+                    if (!entry) {
+                        // try path entry
+                        let pathEntry = this.pathEntry(itemId);
+                        if (pathEntry) {
+                            // This is always a fake module we invented - strip the path
+                            let name = pathEntry.name.split('::').pop()!;
+                            pathEntry.name = name;
+-
+                            entries.push(pathEntry);
+                        }
+
+                        continue;
+                    }
+
+                    if (entry.kind == 'use') {
+                        let useInner = entry.inner['use'] as UseProps;
+                        let pathEntry = this.pathEntry(useInner.id);
+
+                        if (pathEntry) {
+                            entries.push(pathEntry);
+                        } else if (useInner.is_glob) {
+                            let usedModule = this.index.get(useInner.id.toString())?.inner['module'] as ModuleProps;
+                            for (let usedItemId of usedModule.items) {
+                                let usedEntry = this.index.get(usedItemId.toString());
+                                if (usedEntry) entries.push(usedEntry);
+                            }
+                        } else {
+                            let useEntry = this.index.get(useInner.id.toString());
+                            if (useEntry) entries.push(useEntry);
+                        }
+                    } else {
+                        entries.push(entry);
+                    }
+                }
+
+                return entries;
+            }
+            
+            case 'struct': {
+                let structInner = parentEntry.inner['struct'] as StructProps;
+
+                let ownImpls: IndexEntry[] = [];
+                for (let itemId of structInner.impls) {
+                    let entry = this.index.get(itemId.toString());
+                    let implInner = entry?.inner['impl'];
+                    if (implInner.trait !== null) continue;
+                    
+                    for (let itemId of implInner.items) {
+                        let item = this.index.get(itemId.toString());
+                        if (item) ownImpls.push(item);
+                    }
+                }
+
+                let fields: IndexEntry[] = [];
+                if (structInner.kind['plain']) {
+                    for (let fieldId of structInner.kind['plain']['fields']) {
+                        let field = this.index.get(fieldId.toString());
+                        if (field) fields.push(field);
+                    }
+                } else if (structInner.kind['tuple']) {
+                    for (let fieldId of structInner.kind['tuple']) {
+                        let field = this.index.get(fieldId.toString());
+                        if (field) fields.push(field);
+                    }
+                }
+
+                return ownImpls.concat(fields);
+            }
+
+            case 'enum': {
+                let enumInner = parentEntry.inner['enum'] as EnumProps;
+                let variants = enumInner.variants.map(id => this.index.get(id.toString())).filter((item): item is IndexEntry => item !== undefined);
+
+                let ownImpls: IndexEntry[] = [];
+                for (let itemId of enumInner.impls) {
+                    let entry = this.index.get(itemId.toString());
+                    let implInner = entry?.inner['impl'];
+                    if (implInner.trait !== null) continue;
+                    
+                    for (let itemId of implInner.items) {
+                        let item = this.index.get(itemId.toString());
+                        if (item) ownImpls.push(item);
+                    }
+                }
+
+                return variants.concat(ownImpls);
+            }
+            
+            case 'trait': {
+                let traitInner = parentEntry.inner['trait'] as TraitProps;
+
+                let items: IndexEntry[] = [];
+                for (let itemId of traitInner.items) {
+                    let item = this.index.get(itemId.toString());
+                    if (!item) continue;
+
+                    if (item.kind == 'function') {
+                        let funcInner = item.inner['function'] as FunctionProps;
+                        if (!funcInner.has_body) {
+                            item.kind = 'functiontype'
+                        }
+                    }
+
+                    items.push(item);
+                }
+                return items;
+            }
+
+            default:
+                throw new CargoFormatError(`Unhandled parent kind: ${parentEntry.kind} (name = ${parentEntry.name}, id = ${parentEntry.id})`); 
+        }
+    }
+
+    /**
+     * 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(path: string[]): string[][] {
+        let crateName = path[0]!;
+        if (crateName == 'crate') crateName = this.ownCrateName();
+        let crateDetails = this.crates.get(crateName);
+        let paths: string[][] = [];
+        if (crateDetails) {
+            if (crateDetails.could_be_root_module) {
+                // Try current crate first
+                let newPath = [this.ownCrateName()].concat(path);
+                let result = this.walkTree(newPath);
+                if (result) paths.push(newPath);
+            }
+        } else {
+            crateName = this.ownCrateName();
+            path = [crateName].concat(path);
+        }
+        
+        paths.push(path);
+        return paths;
+    }
+
+    /** Populates the children of a given CargoItemNode. */
+    private populateChildren(node: CargoItemNode, is_extern_crate: boolean = false) {
+        if (!node.childrenPopulated) {
+            // Load the children for this node
+            let children = this.indexEntryContents(node.id, is_extern_crate) || [];
+
+            for (let childEntry of children) {
+                let path = node.path + '::' + childEntry.name;
+                let childNode = new CargoItemNode(
+                    childEntry.id, childEntry.name, childEntry.kind, node.kind, path, childEntry.docs
+                );
+                if (childEntry.is_crate) childNode.shouldJumpToCrate = childEntry.name;
+                node.addChild(childNode);
+            }
+        }
+    }
+
+    /**
+     * 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(path: string[]) {
+        let currentNode: CargoItemNode = this.lookup_tree;
+        path = path.slice(); // Clone
+        if (path.length === 0) throw new Error("Cannot walk empty path");
+
+
+        let remainingPath = path.reverse();
+        let crateName = remainingPath.pop()!;
+        currentNode = currentNode.childNamed(crateName)!;
+
+        let shortestPath = [crateName];
+        while (remainingPath.length > 0) {
+            let nextName = remainingPath.pop()!;
+            shortestPath.push(nextName);
+
+            this.pathEntryByPath(shortestPath);
+            this.populateChildren(currentNode, shortestPath.length == 2);
+            currentNode = currentNode.childNamed(nextName)!;
+            if (!currentNode) throw new ResolutionError(shortestPath.slice(0, -1).join('::'), nextName);
+        }
+    }
+
+    /**
+     * 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.
+     */
+    public walkTree(path: string[]): CargoItemNode[] {
+        let currentNode: CargoItemNode = this.lookup_tree;
+        path = path.slice(); // Clone
+        if (path.length === 0) throw new Error("Cannot walk empty path");
+
+        //
+        // Fix the crate prefix
+        let paths = this.fixPathCrate(path);
+        if (paths.length > 1) {
+            for (let p of paths.slice(1)) {
+                try {
+                    return this.walkTree(p);
+                } catch (e) { }
+            }
+        }
+        path = paths[0]!;
+
+        let remainingPath = path.reverse();
+        currentNode = currentNode.childNamed(remainingPath.pop()!)!;
+
+        let shortestPath = [currentNode];
+        while (remainingPath.length > 0) {
+            this.populateChildren(currentNode);
+
+            let nextName = remainingPath.pop()!;
+            let nextNode = currentNode.childNamed(nextName);
+            if (!nextNode) throw new ResolutionError(currentNode.name, nextName);
+
+
+            if (nextNode.shouldJumpToCrate) {
+                let newPath = nextNode.shouldJumpToCrate.split('::').concat(remainingPath.reverse());
+                this.populateMissingPathModules(newPath);``
+                return this.walkTree(newPath);
+            }
+
+            currentNode = nextNode;
+
+            let returnedNode = JSON.parse(JSON.stringify(currentNode));
+            returnedNode.name = returnedNode.name.split('::').pop();
+            shortestPath.push(returnedNode);
+        }
+
+        return shortestPath;
+    }
+
+    /** Gets the current crate name. */
+    public ownCrateName(): string {
+        // It's the first crate in the registry
+        return Array.from(this.crates.keys())[0]!;
+    }
+}
+
+export 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) {
+        this.parser = new CargoJsonParser(name, docs_root, source);
+    }
+
+    /**
+     * 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.
+     */
+    public get(path: string): DocumentedItem {
+        let pathParts = path.split('::');
+        let nodes = this.parser.walkTree(pathParts);
+        let targetNode = nodes[nodes.length - 1]!;
+
+        let urlParts: string[] = [];
+        for (let node of nodes) {
+            let part = this.parser.urlComponentEncode(node);
+            urlParts.push(part);
+        }
+
+        let url = urlParts.join('');
+        if (url.endsWith('/')) {
+            url += 'index.html';
+        }
+
+        return {
+            name: targetNode.name,
+            path: targetNode.path,
+            kind: targetNode.kind,
+            url: url,
+            docs: targetNode.docs_md,
+        };
+    }
+}