cargo-json-docs 0.5.0

package/src/json.ts

@@ -0,0 +1,274 @@
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+
+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 function getCargoMeta(cargoTomlPath: string): CrateMetaData | null {
+    if (!fs.existsSync(cargoTomlPath)) {
+        return null;
+    }
+
+    const cargoTomlContent = fs.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: CrateMetaData = { 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: string): Date {
+    let latestModTime = new Date(0);
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+
+    for (const entry of entries) {
+        const fullPath = path.join(dirPath, entry.name);
+        const stats = fs.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: string | null = null;
+export function getCargoBinPath(): string | null {
+    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 = 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.join(process.env.HOME || process.env.USERPROFILE || '', '.cargo');
+    const cargoBin = path.join(cargoHome, 'bin', isWindows ? 'cargo.exe' : 'cargo');
+    if (fs.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.
+ */
+export class DocumentationSource {
+    /**
+     * The path to the crate source.
+     */
+    public path: string;
+
+    /**
+     * The name of the crate.
+     */
+    public name: string;
+
+    /** 
+     * The root URL for the crate's documentation.
+     */
+    public 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) {
+        this.path = crate_path;
+
+        const cargoTomlPath = path.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(): Date {
+        let cargoTomlStat = fs.statSync(path.join(this.path, 'Cargo.toml'));
+        let srcDirStat = fs.statSync(path.join(this.path, 'src'));
+
+        let lastModified = cargoTomlStat.mtime;
+        let srcLastModified = walkDirForLatestModTime(path.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(): Date | null {
+        let file = this.getJsonPath();
+        if (file === null) return null;
+
+        let stat = fs.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(): boolean {
+        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(): string {
+        // Check for CARGO_TARGET_DIR environment variable
+        let cargoTargetDir = process.env.CARGO_TARGET_DIR;
+        let docDir: string = path.join(this.path, 'target', 'doc');
+        if (cargoTargetDir) {
+            docDir = path.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(): string | null {
+        let docDir = this.getDocPath();
+        if (!fs.existsSync(docDir)) {
+            return null;
+        }
+
+        let files = fs.readdirSync(docDir);
+        let jsonFiles = files.filter((f: string) => f == `${this.name}.json`);
+        if (jsonFiles.length === 0) {
+            return null;
+        }
+
+        return path.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: string[]): number {
+        let bin = getCargoBinPath();
+        if (bin === null) {
+            throw new Error('Cargo binary not found.');
+        }
+
+        let result = 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(): void {
+        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(): any {
+        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.readFileSync(jsonPath, 'utf-8');
+        return JSON.parse(jsonData);
+    }
+}

package/src/lib.ts

@@ -0,0 +1,30 @@
+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 function loadCrate(path: string): CrateDocs {
+    const docSource = new DocumentationSource(path);
+    const jsonSource = docSource.getJson();
+    return new 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.
+ */
+export function loadCrateFromJson(name: string, docs_root: string, json: string): CrateDocs {
+    const source = JSON.parse(json);
+    return new CrateDocs(name, docs_root, source);
+}

package/src/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Rust documentation JSON types.
+ */
+export type ItemKind = 'crate' | 'module' | 'struct' | 'enum' | 'function' | 'functiontype' | 'trait' | 'macro' | 'variant' | 'struct_field' | 'impl' | 'use' | 'assoc_type' | 'assoc_const' | 'constant' | 'type_alias';
+
+/**
+ * A documented item in Rust documentation JSON.
+ */
+export interface DocumentedItem {
+    /**
+     * The name of the item.
+     */
+    name: string;
+    /**
+     * The full path to the item (e.g., module::SubModule::ItemName).
+     */
+    path: string;
+    /**
+     * Markdown documentation for the item, or null if none.
+     */
+    docs: string | null;
+    /**
+     * The kind of item (e.g., struct, enum, function). See ItemKind.
+     */
+    kind: ItemKind;
+    /**
+     * The URL to the item's documentation page.
+     */
+    url: string;
+}
+
+export interface ModuleProps {
+    is_crate: boolean;
+    items: number[];
+}
+
+export interface UseProps {
+    name: string;
+    id: number;
+    is_glob: boolean;
+}
+
+export interface StructProps {
+    impls: number[];
+    kind: any;
+}
+
+export interface EnumProps {
+    variants: number[];
+    impls: number[];
+}
+
+export interface FunctionProps {
+    has_body: boolean;
+}
+
+export interface TraitProps {
+    items: number[];
+}
+
+export interface IndexEntry {
+    id: number;
+    is_crate: boolean;
+    crate_id: number;
+    name: string;
+    kind: ItemKind;
+    docs: string | null;
+    silent: boolean;
+    inner: any;
+}
+
+export interface CrateEntry {
+    id: string;
+    name: string;
+    html_root_url: string;
+    could_be_root_module: boolean;
+}
+
+export interface PathEntry {
+    crate_id: number;
+    path: string[];
+    kind: ItemKind;
+    silent: boolean;
+}

package/test/item.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=item.test.d.ts.map

package/test/item.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"item.test.d.ts","sourceRoot":"","sources":["item.test.ts"],"names":[],"mappings":""}

package/test/item.test.js

@@ -0,0 +1,107 @@
+import { test, expect, afterAll } from 'vitest';
+import fs from 'fs';
+import fetch from 'node-fetch';
+import { loadCrate } from '../src/lib';
+import { DocumentationSource } from '../src/json';
+const crateDocs = loadCrate('test/test_crate');
+let testSet = {
+    'functions': [
+        { path: 'add', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/fn.add.html' },
+        { path: 'test_crate::add', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/fn.add.html' }
+    ],
+    'external': [
+        { path: 'Serialize', kind: 'trait', url: 'https://docs.rs/crate/test_crate/latest/test_crate/trait.Serialize.html' }
+    ],
+    'structures': [
+        { path: 'TestStructPlain', kind: 'struct', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructPlain.html' },
+        { path: 'TestStructPlain::new', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructPlain.html#method.new' },
+        { path: 'TestStructPlain::field1', kind: 'struct_field', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructPlain.html#structfield.field1' },
+        { path: 'TestStructTuple::0', kind: 'struct_field', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructTuple.html#structfield.0' }
+    ],
+    'enums': [
+        { path: 'TestEnum', kind: 'enum', url: 'https://docs.rs/crate/test_crate/latest/test_crate/enum.TestEnum.html' },
+        { path: 'TestEnum::VariantThree', kind: 'variant', url: 'https://docs.rs/crate/test_crate/latest/test_crate/enum.TestEnum.html#variant.VariantThree' },
+        { path: 'TestEnum::describe', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/enum.TestEnum.html#method.describe' }
+    ],
+    'modules': [
+        { path: 'module_b', kind: 'module', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/index.html' },
+        { path: 'module_b::inner_b', kind: 'module', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/index.html' }
+    ],
+    'traits': [
+        { path: 'module_b::inner_b::InnerBTrait', kind: 'trait', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html' },
+        { path: 'module_b::inner_b::InnerBTrait::AssociatedType', kind: 'assoc_type', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#associatedtype.AssociatedType' },
+        { path: 'module_b::inner_b::InnerBTrait::ASSOCIATED_CONST', kind: 'assoc_const', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#associatedconstant.ASSOCIATED_CONST' },
+        { path: 'module_b::inner_b::InnerBTrait::inner_method', kind: 'functiontype', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#tymethod.inner_method' },
+        { path: 'module_b::inner_b::InnerBTrait::provided_method', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#method.provided_method' }
+    ],
+    'constants': [
+        { path: 'TEST_CONST', kind: 'constant', url: 'https://docs.rs/crate/test_crate/latest/test_crate/constant.TEST_CONST.html' }
+    ],
+    'types': [
+        { path: 'TestTypeAlias', kind: 'type_alias', url: 'https://docs.rs/crate/test_crate/latest/test_crate/type.TestTypeAlias.html' }
+    ],
+    'macros': [
+        { path: 'test_macro', kind: 'macro', url: 'https://docs.rs/crate/test_crate/latest/test_crate/macro.test_macro.html' }
+    ]
+};
+function testItem(itemPath, expectedKind, expectedUrl) {
+    let expectedName = itemPath.includes("::") ? itemPath.split("::").pop() : itemPath;
+    const item = crateDocs.get(itemPath);
+    expect(item).toBeDefined();
+    expect(item.name).toBe(expectedName);
+    expect(item.kind).toBe(expectedKind);
+    expect(item.url).toBe(expectedUrl);
+}
+function testItems(testCases) {
+    for (const testCase of testCases) {
+        testItem(testCase.path, testCase.kind, testCase.url);
+    }
+}
+test('can get functions', () => testItems(testSet.functions));
+test('can get external items', () => testItems(testSet.external));
+test('can get structures', () => testItems(testSet.structures));
+test('can get enums', () => testItems(testSet.enums));
+test('can get modules', () => testItems(testSet.modules));
+test('can get traits', () => testItems(testSet.traits));
+test('can get constants', () => testItems(testSet.constants));
+test('can get types', () => testItems(testSet.types));
+test('can get macros', () => testItems(testSet.macros));
+// After all tests, verify that the URLs actually exist
+afterAll(() => {
+    const source = new DocumentationSource('test/test_crate');
+    let result = source.callCargo(['doc', '--no-deps', '--document-private-items', '--lib', '--quiet']);
+    expect(result).toBe(0);
+    let docPath = source.getDocPath();
+    for (const suite in testSet) {
+        for (const testCase of testSet[suite]) {
+            let url = testCase.url;
+            let item = crateDocs.get(testCase.path);
+            expect(item).toBeDefined();
+            let crate = item.path.split("::")[0];
+            if (crate == source.name) {
+                // Verify the file exists locally
+                let relativePath = url.replace(`https://docs.rs/crate/${source.name}/latest/`, `${docPath}/`);
+                let hash = relativePath.split('#')[1] || '';
+                if (hash.length > 0) {
+                    relativePath = relativePath.replace(`#${hash}`, '');
+                }
+                expect(fs.existsSync(relativePath), `[${suite}] File does not exist: ${relativePath}`).toBe(true);
+                // Should contain the hash if applicable
+                if (hash.length > 0) {
+                    let fileContents = fs.readFileSync(relativePath, 'utf-8');
+                    expect(fileContents.includes(`id="${hash}"`), `[${suite}] File does not contain id="${hash}": ${relativePath}`).toBe(true);
+                }
+            }
+            else {
+                // Fetch the URL to ensure it exists remotely
+                let url = item.url;
+                fetch(url).then(response => {
+                    expect(response.status, `[${suite}] Failed to fetch ${url}`).toBe(200);
+                }).catch(err => {
+                    throw new Error(`Failed to fetch ${url}: ${err}`);
+                });
+            }
+        }
+    }
+});
+//# sourceMappingURL=item.test.js.map

package/test/item.test.js.map

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

package/test/item.test.ts

@@ -0,0 +1,128 @@
+import { test, expect, afterAll } from 'vitest';
+import fs from 'fs';
+import fetch from 'node-fetch';
+
+import { loadCrate } from '../src/lib';
+import { DocumentationSource } from '../src/json';
+
+const crateDocs = loadCrate('test/test_crate');
+
+let testSet = {
+    'functions': [
+        { path: 'add', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/fn.add.html' },
+        { path: 'test_crate::add', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/fn.add.html' }
+    ],
+
+    'external': [
+        { path: 'Serialize', kind: 'trait', url: 'https://docs.rs/crate/test_crate/latest/test_crate/trait.Serialize.html' }
+    ],
+
+    'structures': [
+        { path: 'TestStructPlain', kind: 'struct', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructPlain.html' },
+        { path: 'TestStructPlain::new', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructPlain.html#method.new' },
+        { path: 'TestStructPlain::field1', kind: 'struct_field', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructPlain.html#structfield.field1' },
+        { path: 'TestStructTuple::0', kind: 'struct_field', url: 'https://docs.rs/crate/test_crate/latest/test_crate/struct.TestStructTuple.html#structfield.0' }
+    ],
+
+    'enums': [
+        { path: 'TestEnum', kind: 'enum', url: 'https://docs.rs/crate/test_crate/latest/test_crate/enum.TestEnum.html' },
+        { path: 'TestEnum::VariantThree', kind: 'variant', url: 'https://docs.rs/crate/test_crate/latest/test_crate/enum.TestEnum.html#variant.VariantThree' },
+        { path: 'TestEnum::describe', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/enum.TestEnum.html#method.describe' }
+    ],
+
+    'modules': [
+        { path: 'module_b', kind: 'module', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/index.html' },
+        { path: 'module_b::inner_b', kind: 'module', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/index.html' }
+    ],
+
+    'traits': [
+        { path: 'module_b::inner_b::InnerBTrait', kind: 'trait', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html' },
+        { path: 'module_b::inner_b::InnerBTrait::AssociatedType', kind: 'assoc_type', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#associatedtype.AssociatedType' },
+        { path: 'module_b::inner_b::InnerBTrait::ASSOCIATED_CONST', kind: 'assoc_const', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#associatedconstant.ASSOCIATED_CONST' },
+        { path: 'module_b::inner_b::InnerBTrait::inner_method', kind: 'functiontype', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#tymethod.inner_method' },
+        { path: 'module_b::inner_b::InnerBTrait::provided_method', kind: 'function', url: 'https://docs.rs/crate/test_crate/latest/test_crate/module_b/inner_b/trait.InnerBTrait.html#method.provided_method' }
+    ],
+
+    'constants': [
+        { path: 'TEST_CONST', kind: 'constant', url: 'https://docs.rs/crate/test_crate/latest/test_crate/constant.TEST_CONST.html' }
+    ],
+
+    'types': [
+        { path: 'TestTypeAlias', kind: 'type_alias', url: 'https://docs.rs/crate/test_crate/latest/test_crate/type.TestTypeAlias.html' }
+    ],
+
+    'macros': [
+        { path: 'test_macro', kind: 'macro', url: 'https://docs.rs/crate/test_crate/latest/test_crate/macro.test_macro.html' }
+    ]
+}
+
+function testItem(itemPath: string, expectedKind: string, expectedUrl: string) {
+    let expectedName = itemPath.includes("::") ? itemPath.split("::").pop()! : itemPath;
+    const item = crateDocs.get(itemPath);
+
+    expect(item).toBeDefined();
+    expect(item.name).toBe(expectedName);
+    expect(item.kind).toBe(expectedKind);
+    expect(item.url).toBe(expectedUrl);
+}
+
+function testItems(testCases: Array<{ path: string, kind: string, url: string }>) {
+    for (const testCase of testCases) {
+        testItem(testCase.path, testCase.kind, testCase.url);
+    }
+}
+
+test('can get functions', () => testItems(testSet.functions));
+test('can get external items', () => testItems(testSet.external));
+test('can get structures', () => testItems(testSet.structures));
+test('can get enums', () => testItems(testSet.enums));
+test('can get modules', () => testItems(testSet.modules));
+test('can get traits', () => testItems(testSet.traits));
+test('can get constants', () => testItems(testSet.constants));
+test('can get types', () => testItems(testSet.types));
+test('can get macros', () => testItems(testSet.macros));
+
+// After all tests, verify that the URLs actually exist
+afterAll(async () => {
+    const source = new DocumentationSource('test/test_crate');
+    let result = source.callCargo(['doc', '--no-deps', '--document-private-items', '--lib', '--quiet']);
+    expect(result).toBe(0);
+
+    let docPath = source.getDocPath();
+
+    for (const suite in testSet) {
+        for (const testCase of (testSet as any)[suite]) {
+            let url = testCase.url;
+            let item = crateDocs.get(testCase.path);
+            expect(item).toBeDefined();
+
+            let crate = item.path.split("::")[0];
+            if (crate == source.name) {
+                // Verify the file exists locally
+                let relativePath = url.replace(`https://docs.rs/crate/${source.name}/latest/`, `${docPath}/`);
+
+                let hash = relativePath.split('#')[1] || '';
+                if (hash.length > 0) {
+                    relativePath = relativePath.replace(`#${hash}`, '');
+                }
+
+                expect(fs.existsSync(relativePath), `[${suite}] File does not exist: ${relativePath}`).toBe(true);
+
+                // Should contain the hash if applicable
+                if (hash.length > 0) {
+                    let fileContents = fs.readFileSync(relativePath, 'utf-8');
+                    expect(fileContents.includes(`id="${hash}"`), `[${suite}] File does not contain id="${hash}": ${relativePath}`).toBe(true);
+                }
+
+            } else {
+                // Fetch the URL to ensure it exists remotely
+                let url = item.url;
+                await fetch(url).then(response => {
+                    expect(response.status, `[${suite}] Failed to fetch ${url}`).toBe(200);
+                }).catch(err => {
+                    throw new Error(`Failed to fetch ${url}: ${err}`);
+                });
+            }
+        }
+    }
+});

package/test/json.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=json.test.d.ts.map

package/test/json.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.test.d.ts","sourceRoot":"","sources":["json.test.ts"],"names":[],"mappings":""}