feat: docnodes v2 format (#786)

Author: crowlKats

Cargo.lock

@@ -18,6 +18,7 @@ deno_graph = { version = "0.107.0", default-features = false, features = [
 deno_ast = { version = "0.53.0" }
 import_map = "0.25.0"
 serde = { version = "1.0.204", features = ["derive"] }
+serde_json = { version = "1.0.122", features = ["preserve_order"] }
 
 [lib]
 name = "deno_doc"
@@ -36,7 +37,7 @@ indexmap = "2.3.0"
 lazy_static = "1.5.0"
 regex = "1.10.6"
 serde.workspace = true
-serde_json = { version = "1.0.122", features = ["preserve_order"] }
+serde_json.workspace = true
 termcolor = "1.4.1"
 itoa = "1.0.14"
 deno_path_util = "0.6.4"

Cargo.toml

@@ -10,7 +10,11 @@
   "workspace": ["js"],
   "exclude": ["target", "benches/fixtures"],
   "fmt": {
-    "exclude": ["**/*.gen.css", "generated_docs"]
+    "exclude": [
+      "**/*.gen.css",
+      "generated_docs",
+      "tests/testdata/@zod_zod_4.3.6_raw.json"
+    ]
   },
   "lint": {
     "exclude": ["src/html", "tests/testdata"]

deno.json

@@ -13,7 +13,6 @@ use deno_doc::html::HrefResolver;
 use deno_doc::html::UrlResolveKind;
 use deno_doc::html::UsageComposer;
 use deno_doc::html::UsageComposerEntry;
-use deno_doc::node::DocNodeDef;
 use deno_graph::BuildOptions;
 use deno_graph::GraphKind;
 use deno_graph::ModuleGraph;
@@ -190,7 +189,7 @@ async fn run() -> anyhow::Result<()> {
       filter,
       private,
     } => {
-      let doc_nodes_by_url = if json_input {
+      let mut doc_nodes_by_url = if json_input {
         assert_eq!(files.len(), 1);
         serde_json::from_reader(std::fs::File::open(&files[0])?)?
       } else {
@@ -210,21 +209,26 @@ async fn run() -> anyhow::Result<()> {
         return Ok(());
       }
 
-      let mut doc_nodes =
-        doc_nodes_by_url.into_values().flatten().collect::<Vec<_>>();
-
-      doc_nodes
-        .retain(|doc_node| !matches!(doc_node.def, DocNodeDef::Import { .. }));
-
-      if let Some(filter) = filter {
-        doc_nodes = find_nodes_by_name_recursively(doc_nodes, &filter);
+      for (_, doc) in &mut doc_nodes_by_url {
+        if let Some(filter) = &filter {
+          let symbols = std::mem::take(&mut doc.symbols);
+          doc.symbols = find_nodes_by_name_recursively(symbols, filter);
+        }
       }
 
       if json {
-        serde_json::to_writer_pretty(std::io::stdout(), &doc_nodes)?;
+        serde_json::to_writer_pretty(std::io::stdout(), &doc_nodes_by_url)?;
         println!();
       } else {
-        let result = DocPrinter::new(&doc_nodes, true, false);
+        let mut merged_doc = deno_doc::Document::default();
+        for doc in doc_nodes_by_url.into_values() {
+          if merged_doc.module_doc.is_empty() {
+            merged_doc.module_doc = doc.module_doc;
+          }
+          merged_doc.symbols.extend(doc.symbols);
+        }
+
+        let result = DocPrinter::new(&merged_doc, true, false);
         println!("{result}");
       }
     }
@@ -378,7 +382,7 @@ fn generate_docs_directory(
   package_name: Option<String>,
   output_dir: PathBuf,
   main_entrypoint: Option<ModuleSpecifier>,
-  doc_nodes_by_url: IndexMap<ModuleSpecifier, Vec<deno_doc::DocNode>>,
+  doc_nodes_by_url: IndexMap<ModuleSpecifier, deno_doc::Document>,
 ) -> Result<(), anyhow::Error> {
   let cwd = current_dir().unwrap();
   let output_dir_resolved = cwd.join(output_dir);

examples/ddoc/main.rs

@@ -1,7 +1,7 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
 import { instantiate } from "./deno_doc_wasm.generated.js";
-import type { DocNode, Location } from "./types.d.ts";
+import type { Document, Location } from "./types.d.ts";
 import type { Page } from "./html_types.d.ts";
 import { createCache } from "@deno/cache-dir";
 import type { CacheSetting, LoadResponse } from "@deno/graph";
@@ -87,7 +87,7 @@ export interface DocOptions {
 export async function doc(
   specifiers: string[],
   options: DocOptions = {},
-): Promise<Record<string, Array<DocNode>>> {
+): Promise<Record<string, Document>> {
   const {
     load = createCache().load,
     includeAll = false,
@@ -128,6 +128,18 @@ export async function doc(
   );
 }
 
+/**
+ * Convert a v1 doc nodes array (flat array of doc nodes) to the v2
+ * {@linkcode Document} format.
+ */
+export async function docnodesV1ToV2(
+  // deno-lint-ignore no-explicit-any
+  v1Nodes: any[],
+): Promise<Document> {
+  const wasm = await instantiate();
+  return wasm.docnodes_v1_to_v2(v1Nodes);
+}
+
 export interface ShortPath {
   /** Name identifier for the path. */
   path: string;
@@ -303,12 +315,12 @@ const defaultUsageComposer: UsageComposer = {
 };
 
 /**
- * Generate HTML files for provided {@linkcode DocNode}s.
+ * Generate HTML files for provided {@linkcode Document}s.
  * @param docNodesByUrl DocNodes keyed by their absolute URL.
  * @param options Options for the generation.
  */
 export async function generateHtml(
-  docNodesByUrl: Record<string, Array<DocNode>>,
+  docNodesByUrl: Record<string, Document>,
   options: GenerateOptions,
 ): Promise<Record<string, string>> {
   const {
@@ -346,7 +358,7 @@ export async function generateHtml(
  * @param options Options for the generation.
  */
 export async function generateHtmlAsJSON(
-  docNodesByUrl: Record<string, Array<DocNode>>,
+  docNodesByUrl: Record<string, Document>,
   options: GenerateOptions,
 ): Promise<Record<string, Page>> {
   const {

js/mod.ts

@@ -9,22 +9,24 @@ Deno.test({
     const records = await doc(
       ["https://deno.land/std@0.104.0/fmt/colors.ts"],
     );
-    const entries = records["https://deno.land/std@0.104.0/fmt/colors.ts"];
-    assertEquals(entries.length, 49);
-    const fnStripColor = entries.find((n) =>
-      n.kind === "function" && n.name === "stripColor"
+    const document = records["https://deno.land/std@0.104.0/fmt/colors.ts"];
+    assertEquals(document.symbols.length, 49);
+    const fnStripColor = document.symbols.find((n) =>
+      n.declarations.some((d) => d.kind === "function") &&
+      n.name === "stripColor"
     );
     assert(fnStripColor, "unable to locate specific node");
-    assert(fnStripColor.kind === "function");
-    assert(fnStripColor.functionDef);
-    assertEquals(fnStripColor.functionDef.params, [{
+    const decl = fnStripColor.declarations[0];
+    assert(decl.kind === "function");
+    assert(decl.def);
+    assertEquals(decl.def.params, [{
       kind: "identifier",
       name: "string",
       optional: false,
       tsType: {
         repr: "string",
         kind: "keyword",
-        keyword: "string",
+        value: "string",
       },
     }]);
   },
@@ -59,7 +61,7 @@ Deno.test({
 Deno.test({
   name: "doc() - with headers",
   async fn() {
-    const entries = await doc(["https://example.com/a"], {
+    const documents = await doc(["https://example.com/a"], {
       load(specifier) {
         return Promise.resolve({
           kind: "module",
@@ -73,7 +75,7 @@ Deno.test({
         });
       },
     });
-    assertEquals(Object.values(entries)[0].length, 1);
+    assertEquals(Object.values(documents)[0].symbols.length, 1);
   },
 });
 
@@ -119,10 +121,10 @@ Deno.test({
         });
       },
     });
-    const entries = Object.values(records)[0];
-    assertEquals(entries.length, 1);
-    assertEquals(entries[0].kind, "class");
-    assertEquals(entries[0].name, "B");
+    const document = Object.values(records)[0];
+    assertEquals(document.symbols.length, 1);
+    assertEquals(document.symbols[0].declarations[0].kind, "class");
+    assertEquals(document.symbols[0].name, "B");
   },
 });