@webneat/codewiki 0.0.3 → 0.0.6

package/dist/bin.js

@@ -5,15 +5,21 @@ var __export = (target, all3) => {
     __defProp(target, name, { get: all3[name], enumerable: true });
 };
 
+// ../../node_modules/.pnpm/tsup@8.5.0_postcss@8.5.6_tsx@4.20.6_typescript@5.9.3_yaml@2.8.1/node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var getFilename = () => fileURLToPath(import.meta.url);
+var getDirname = () => path.dirname(getFilename());
+var __dirname = /* @__PURE__ */ getDirname();
+
 // src/cli/env.ts
 import { existsSync } from "fs";
 
 // src/internals/context.ts
 import ts from "typescript";
-import { fileURLToPath } from "url";
 import Database from "better-sqlite3";
 import { readFile as readFile2 } from "fs/promises";
-import path, { dirname, join as join2 } from "path";
+import path2, { join as join2 } from "path";
 import { drizzle } from "drizzle-orm/better-sqlite3";
 
 // ../errors/dist/index.js
@@ -77,6 +83,7 @@ var index_default = errors;
 var err = index_default({
   file_outside_project_path: (data) => `File "${data.file_path}" is outside project path "${data.project_path}"`,
   file_not_found: (data) => `File not found: ${data.path}`,
+  file_stat_error: (data) => `Could not get file stats for ${data.path}: ${data.reason}`,
   db_error: (data) => `Database error in ${data.operation}: ${data.reason}`,
   symbol_meta_parse_error: (data) => `Failed to parse symbol metadata for symbol ${data.symbol_id}: ${data.reason}`,
   exported_symbol_not_found: (data) => `Exported symbol "${data.name}" not found in file with id ${data.file_id}`,
@@ -89,6 +96,8 @@ var err = index_default({
   symbol_node_not_found: (data) => `Symbol node not found for ${data.name} in ${data.file_path}`,
   symbol_not_found: (data) => `Symbol "${data.name}" not found in file "${data.path}"`,
   describe_dependency_failed: (data) => `Failed to describe ${data.package}#${data.name}: ${data.reason}`,
+  could_not_describe_files_due_to_pending_symbols: (data) => `Cannot start describing files before describing all symbols; ${data.count} symbols are still pending`,
+  could_not_describe_directories_due_to_pending_files: (data) => `Cannot start describing directories before describing all files; ${data.count} files are still pending`,
   // CLI errors
   could_not_read_file: (data) => `Could not read file ${data.path}: ${data.reason}`,
   invalid_json: (data) => `Invalid JSON: ${data.reason}`,
@@ -441,7 +450,7 @@ __export(configs_exports, {
 import { eq as eq2, sql as sql3 } from "drizzle-orm";
 
 // src/db/common.ts
-import { eq, like, or, and, asc, desc } from "drizzle-orm";
+import { eq, like, or, and, asc, desc, count } from "drizzle-orm";
 function safe_query(operation, fn) {
   return err.safe(fn, (reason, ...args) => err.new("db_error", { operation, args: args.slice(1), reason }));
 }
@@ -449,6 +458,9 @@ function do_search(db6, table, options) {
   if (!options.select.includes("id")) options.select.push("id");
   return db6.select(fields(table, options.select)).from(table).where(conditions(table, options.where)).orderBy(order(table, options.order_by)).offset(options.offset).limit(options.limit).all();
 }
+function do_count(db6, table, options) {
+  return db6.select({ count: count() }).from(table).where(conditions(table, options)).get()?.count ?? 0;
+}
 function fields(table, fields2) {
   const res = {};
   for (const field of fields2) res[field] = table[field];
@@ -500,8 +512,10 @@ __export(files_exports, {
   by_directory_path: () => by_directory_path,
   by_id: () => by_id,
   by_id_and_state: () => by_id_and_state,
+  by_ids: () => by_ids,
   by_path: () => by_path,
   by_state: () => by_state,
+  count: () => count2,
   del: () => del,
   del_by_dir: () => del_by_dir,
   get_directory_ids: () => get_directory_ids,
@@ -515,48 +529,6 @@ __export(files_exports, {
 });
 import { eq as eq3, and as and2, inArray, or as or2, like as like2 } from "drizzle-orm";
 
-// src/internals/utils.ts
-import { readFileSync } from "fs";
-var parse_json = err.safe(JSON.parse, (reason, text2) => err.new("invalid_json", { reason, text: text2 }));
-var read_file = err.safe(
-  (path6) => readFileSync(path6, "utf-8"),
-  (reason, path6) => err.new("could_not_read_file", { path: path6, reason })
-);
-function group_by_unique(items, key) {
-  const groups = {};
-  for (const item of items) {
-    groups[key(item)] = item;
-  }
-  return groups;
-}
-function expand({ items, get_children, get_key }) {
-  const visited = /* @__PURE__ */ new Set();
-  const result = [];
-  const queue = [...items];
-  while (queue.length > 0) {
-    const item = queue.shift();
-    const key = get_key(item);
-    if (err.any(key)) return key;
-    if (visited.has(key)) continue;
-    visited.add(key);
-    result.push(item);
-    const children3 = get_children(item);
-    if (err.any(children3)) return children3;
-    queue.push(...children3);
-  }
-  return result;
-}
-function uniq(items) {
-  return [...new Set(items)];
-}
-function merge(a, b) {
-  const res = { ...a };
-  for (const key of Object.keys(b)) {
-    if (b[key] !== void 0) res[key] = b[key];
-  }
-  return res;
-}
-
 // src/db/defaults.ts
 var files2 = {
   select: ["id", "directory_id", "path", "state", "error"],
@@ -580,7 +552,35 @@ var symbols2 = {
   where: {}
 };
 var external_dependencies2 = {
-  select: ["id", "package", "subpath", "name", "state", "error"],
+  select: ["id", "package", "subpath", "name", "is_builtin", "state", "error"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
+var imports2 = {
+  select: ["id", "exporter_file_id", "importer_file_id", "symbol_id", "name", "alias", "is_dynamic", "state", "error"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
+var external_imports2 = {
+  select: ["id", "file_id", "external_dependency_id", "alias", "is_dynamic"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
+var symbol_internal_links2 = {
+  select: ["id", "from_file_id", "to_file_id", "from_symbol_id", "to_symbol_id", "state", "error"],
+  order_by: ["id", "asc"],
+  limit: 20,
+  offset: 0,
+  where: {}
+};
+var symbol_external_links2 = {
+  select: ["id", "symbol_id", "external_import_id"],
   order_by: ["id", "asc"],
   limit: 20,
   offset: 0,
@@ -593,15 +593,23 @@ var all = safe_query("files.all", (ctx) => ctx.db.select().from(files).all());
 var search = safe_query("files.search", (ctx, options = {}) => {
   return do_search(ctx.db, files, merge(files2, options));
 });
+var count2 = safe_query("files.count", (ctx, where = {}) => {
+  return do_count(ctx.db, files, where);
+});
 var by_id = safe_query("files.by_id", (ctx, id) => ctx.db.select().from(files).where(eq3(files.id, id)).get());
+var by_ids = safe_query(
+  "files.by_ids",
+  (ctx, ids) => ctx.db.select().from(files).where(inArray(files.id, ids)).all()
+);
 var by_path = safe_query(
   "files.by_path",
-  (ctx, path6) => ctx.db.select().from(files).where(eq3(files.path, path6)).get()
-);
-var by_state = safe_query(
-  "files.by_state",
-  (ctx, state) => ctx.db.select().from(files).where(eq3(files.state, state)).all()
+  (ctx, path7) => ctx.db.select().from(files).where(eq3(files.path, path7)).get()
 );
+var by_state = safe_query("files.by_state", (ctx, state, limit) => {
+  let query = ctx.db.select().from(files).where(eq3(files.state, state));
+  if (limit) query = query.limit(limit);
+  return query.all();
+});
 var insert = safe_query("files.insert", (ctx, values) => ctx.db.insert(files).values(values).run());
 var update = safe_query(
   "files.update",
@@ -643,8 +651,8 @@ var using_dependency = safe_query(
   "files.using_dependency",
   (ctx, external_dependency_id, fields_to_select = default_select_fields) => {
     if (!fields_to_select.includes("id")) fields_to_select.push("id");
-    const imports2 = ctx.db.select({ file_id: external_imports.file_id }).from(external_imports).where(eq3(external_imports.external_dependency_id, external_dependency_id)).all();
-    const file_ids = uniq(imports2.map((i) => i.file_id));
+    const imports4 = ctx.db.select({ file_id: external_imports.file_id }).from(external_imports).where(eq3(external_imports.external_dependency_id, external_dependency_id)).all();
+    const file_ids = uniq(imports4.map((i) => i.file_id));
     if (file_ids.length === 0) return [];
     return ctx.db.select(fields(files, fields_to_select)).from(files).where(inArray(files.id, file_ids)).all();
   }
@@ -675,8 +683,10 @@ var directories_exports = {};
 __export(directories_exports, {
   by_id: () => by_id2,
   by_id_and_state: () => by_id_and_state2,
+  by_ids: () => by_ids2,
   by_path: () => by_path2,
   by_state: () => by_state2,
+  count: () => count3,
   insert: () => insert2,
   search: () => search2,
   update: () => update2,
@@ -687,9 +697,13 @@ var by_id2 = safe_query(
   "directories.by_id",
   (ctx, id) => ctx.db.select().from(directories).where(eq4(directories.id, id)).get()
 );
+var by_ids2 = safe_query(
+  "directories.by_ids",
+  (ctx, ids) => ctx.db.select().from(directories).where(inArray2(directories.id, ids)).all()
+);
 var by_path2 = safe_query(
   "directories.by_path",
-  (ctx, path6) => ctx.db.select().from(directories).where(eq4(directories.path, path6)).get()
+  (ctx, path7) => ctx.db.select().from(directories).where(eq4(directories.path, path7)).get()
 );
 var by_state2 = safe_query(
   "directories.by_state",
@@ -714,6 +728,9 @@ var by_id_and_state2 = safe_query(
 var search2 = safe_query("directories.search", (ctx, options = {}) => {
   return do_search(ctx.db, directories, merge(directories2, options));
 });
+var count3 = safe_query("directories.count", (ctx, where = {}) => {
+  return do_count(ctx.db, directories, where);
+});
 
 // src/db/imports.ts
 var imports_exports = {};
@@ -721,11 +738,23 @@ __export(imports_exports, {
   by_exporter_file: () => by_exporter_file,
   by_importer_file: () => by_importer_file,
   by_state: () => by_state3,
+  count: () => count4,
+  count_pending_symbols: () => count_pending_symbols,
   del_by_importer_file: () => del_by_importer_file,
   insert_many: () => insert_many,
+  search: () => search3,
   update: () => update3
 });
-import { eq as eq5 } from "drizzle-orm";
+import { eq as eq5, ne, and as and4, count as countFn } from "drizzle-orm";
+var search3 = safe_query("imports.search", (ctx, options = {}) => {
+  return do_search(ctx.db, imports, merge(imports2, options));
+});
+var count4 = safe_query("imports.count", (ctx, where = {}) => {
+  return do_count(ctx.db, imports, where);
+});
+var count_pending_symbols = safe_query("imports.count_pending_symbols", (ctx, file_id) => {
+  return ctx.db.select({ count: countFn() }).from(imports).innerJoin(symbols, eq5(imports.symbol_id, symbols.id)).where(and4(eq5(imports.importer_file_id, file_id), ne(symbols.state, "ready"))).get()?.count ?? 0;
+});
 var by_exporter_file = safe_query(
   "imports.by_exporter_file",
   (ctx, exporter_file_id) => ctx.db.select().from(imports).where(eq5(imports.exporter_file_id, exporter_file_id)).all()
@@ -755,17 +784,67 @@ __export(symbols_exports, {
   by_file_and_name: () => by_file_and_name,
   by_id: () => by_id3,
   by_id_and_state: () => by_id_and_state3,
+  by_ids: () => by_ids3,
   by_state: () => by_state4,
+  count: () => count5,
   del_by_file: () => del_by_file,
   insert_many: () => insert_many2,
   meta: () => meta,
   referenced_by: () => referenced_by,
   referencing: () => referencing,
-  search: () => search3,
+  search: () => search4,
   update: () => update4,
   using_dependency: () => using_dependency2
 });
-import { eq as eq6, and as and4, inArray as inArray3 } from "drizzle-orm";
+import { eq as eq6, and as and5, inArray as inArray3 } from "drizzle-orm";
+
+// src/internals/utils.ts
+import { readFileSync, statSync } from "fs";
+var parse_json = err.safe(JSON.parse, (reason, text2) => err.new("invalid_json", { reason, text: text2 }));
+var read_file = err.safe(
+  (path7) => readFileSync(path7, "utf-8"),
+  (reason, path7) => err.new("could_not_read_file", { path: path7, reason })
+);
+var file_stat = err.safe(
+  (path7) => statSync(path7),
+  (reason, path7) => err.new("file_stat_error", { path: path7, reason })
+);
+function group_by_unique(items, key) {
+  const groups = {};
+  for (const item of items) {
+    groups[key(item)] = item;
+  }
+  return groups;
+}
+function expand({ items, get_children, get_key }) {
+  const visited = /* @__PURE__ */ new Set();
+  const result = [];
+  const queue = [...items];
+  while (queue.length > 0) {
+    const item = queue.shift();
+    const key = get_key(item);
+    if (err.any(key)) return key;
+    if (visited.has(key)) continue;
+    visited.add(key);
+    result.push(item);
+    const children3 = get_children(item);
+    if (err.any(children3)) return children3;
+    queue.push(...children3);
+  }
+  return result;
+}
+function uniq(items) {
+  return [...new Set(items)];
+}
+function merge(a, b) {
+  const res = { ...a };
+  for (const key of Object.keys(b)) {
+    if (b[key] !== void 0) res[key] = b[key];
+  }
+  return res;
+}
+
+// src/db/symbols.ts
 var insert_many2 = safe_query("symbols.insert_many", (ctx, values) => ctx.db.insert(symbols).values(values).run());
 var del_by_file = safe_query(
   "symbols.delete_by_file",
@@ -773,7 +852,7 @@ var del_by_file = safe_query(
 );
 var by_file_and_name = safe_query(
   "symbols.by_file_and_name",
-  (ctx, params) => ctx.db.select().from(symbols).where(and4(eq6(symbols.file_id, params.file_id), eq6(symbols.name, params.name), eq6(symbols.is_exported, params.is_exported))).get()
+  (ctx, params) => ctx.db.select().from(symbols).where(and5(eq6(symbols.file_id, params.file_id), eq6(symbols.name, params.name), eq6(symbols.is_exported, params.is_exported))).get()
 );
 var by_state4 = safe_query(
   "symbols.by_state",
@@ -788,9 +867,13 @@ var update4 = safe_query(
   (ctx, id, data) => ctx.db.update(symbols).set(data).where(eq6(symbols.id, id)).run()
 );
 var by_id3 = safe_query("symbols.by_id", (ctx, id) => ctx.db.select().from(symbols).where(eq6(symbols.id, id)).get());
+var by_ids3 = safe_query(
+  "symbols.by_ids",
+  (ctx, ids) => ctx.db.select().from(symbols).where(inArray3(symbols.id, ids)).all()
+);
 var by_id_and_state3 = safe_query(
   "symbols.by_id_and_state",
-  (ctx, params) => ctx.db.select().from(symbols).where(and4(eq6(symbols.id, params.id), eq6(symbols.state, params.state))).get()
+  (ctx, params) => ctx.db.select().from(symbols).where(and5(eq6(symbols.id, params.id), eq6(symbols.state, params.state))).get()
 );
 function meta(symbol) {
   return err.catch(
@@ -798,8 +881,12 @@ function meta(symbol) {
     (reason) => err.new("symbol_meta_parse_error", { reason, symbol_id: symbol.id, meta: symbol.meta })
   );
 }
-var search3 = safe_query("symbols.search", (ctx, options = {}) => {
-  return do_search(ctx.db, symbols, merge(symbols2, options));
+var search4 = safe_query(
+  "symbols.search",
+  (ctx, options = {}) => do_search(ctx.db, symbols, merge(symbols2, options))
+);
+var count5 = safe_query("symbols.count", (ctx, where = {}) => {
+  return do_count(ctx.db, symbols, where);
 });
 var referenced_by = safe_query(
   "symbols.referenced_by",
@@ -837,20 +924,26 @@ var external_dependencies_exports = {};
 __export(external_dependencies_exports, {
   all: () => all2,
   by_id: () => by_id4,
+  by_ids: () => by_ids4,
   by_package_subpath_and_name: () => by_package_subpath_and_name,
   by_state: () => by_state5,
+  count: () => count6,
   get_or_create: () => get_or_create,
   insert: () => insert3,
-  search: () => search4,
+  search: () => search5,
   update: () => update5,
   used_by_file: () => used_by_file,
   used_by_symbol: () => used_by_symbol
 });
-import { eq as eq7, and as and5, sql as sql4, inArray as inArray4 } from "drizzle-orm";
+import { eq as eq7, and as and6, sql as sql4, inArray as inArray4 } from "drizzle-orm";
 var by_id4 = safe_query(
   "external_dependencies.by_id",
   (ctx, id) => ctx.db.select().from(external_dependencies).where(eq7(external_dependencies.id, id)).get()
 );
+var by_ids4 = safe_query(
+  "external_dependencies.by_ids",
+  (ctx, ids) => ctx.db.select().from(external_dependencies).where(inArray4(external_dependencies.id, ids)).all()
+);
 var by_state5 = safe_query(
   "external_dependencies.by_state",
   (ctx, state) => ctx.db.select().from(external_dependencies).where(eq7(external_dependencies.state, state)).all()
@@ -858,7 +951,7 @@ var by_state5 = safe_query(
 var by_package_subpath_and_name = safe_query(
   "external_dependencies.by_package_subpath_and_name",
   (ctx, params) => ctx.db.select().from(external_dependencies).where(
-    and5(
+    and6(
       eq7(external_dependencies.package, params.package),
       params.subpath === null ? sql4`${external_dependencies.subpath} IS NULL` : eq7(external_dependencies.subpath, params.subpath),
       params.name === null ? sql4`${external_dependencies.name} IS NULL` : eq7(external_dependencies.name, params.name)
@@ -880,11 +973,13 @@ function get_or_create(ctx, value) {
     (existing) => existing || insert3(ctx, value)
   );
 }
-var search4 = safe_query(
+var search5 = safe_query(
   "external_dependencies.search",
-  (ctx, options = {}) => {
-    return do_search(ctx.db, external_dependencies, merge(external_dependencies2, options));
-  }
+  (ctx, options = {}) => do_search(ctx.db, external_dependencies, merge(external_dependencies2, options))
+);
+var count6 = safe_query(
+  "external_dependencies.count",
+  (ctx, where = {}) => do_count(ctx.db, external_dependencies, where)
 );
 var used_by_file = safe_query(
   "external_dependencies.used_by_file",
@@ -916,10 +1011,22 @@ __export(external_imports_exports, {
   by_external_dependency: () => by_external_dependency,
   by_file: () => by_file2,
   by_symbol: () => by_symbol,
+  count: () => count7,
+  count_pending_dependencies: () => count_pending_dependencies,
   del_by_file: () => del_by_file2,
-  insert_many: () => insert_many3
+  insert_many: () => insert_many3,
+  search: () => search6
+});
+import { eq as eq8, ne as ne2, and as and7, count as countFn2 } from "drizzle-orm";
+var search6 = safe_query("external_imports.search", (ctx, options = {}) => {
+  return do_search(ctx.db, external_imports, merge(external_imports2, options));
+});
+var count7 = safe_query("external_imports.count", (ctx, where = {}) => {
+  return do_count(ctx.db, external_imports, where);
+});
+var count_pending_dependencies = safe_query("external_imports.count_pending_dependencies", (ctx, file_id) => {
+  return ctx.db.select({ count: countFn2() }).from(external_imports).innerJoin(external_dependencies, eq8(external_imports.external_dependency_id, external_dependencies.id)).where(and7(eq8(external_imports.file_id, file_id), ne2(external_dependencies.state, "ready"))).get()?.count ?? 0;
 });
-import { eq as eq8 } from "drizzle-orm";
 var insert_many3 = safe_query(
   "external_imports.insert_many",
   (ctx, values) => ctx.db.insert(external_imports).values(values).run()
@@ -954,11 +1061,20 @@ var by_symbol = safe_query(
 var symbol_internal_links_exports = {};
 __export(symbol_internal_links_exports, {
   by_from_symbol: () => by_from_symbol,
+  count: () => count8,
   del_by_from_symbol: () => del_by_from_symbol,
   exists: () => exists,
-  insert: () => insert4
+  insert: () => insert4,
+  search: () => search7,
+  update_state_by_to_symbol: () => update_state_by_to_symbol
+});
+import { and as and8, eq as eq9 } from "drizzle-orm";
+var search7 = safe_query("symbol_internal_links.search", (ctx, options = {}) => {
+  return do_search(ctx.db, symbol_internal_links, merge(symbol_internal_links2, options));
+});
+var count8 = safe_query("symbol_internal_links.count", (ctx, where = {}) => {
+  return do_count(ctx.db, symbol_internal_links, where);
 });
-import { and as and6, eq as eq9 } from "drizzle-orm";
 var by_from_symbol = safe_query(
   "symbol_internal_links.by_from_symbol",
   (ctx, from_symbol_id) => ctx.db.query.symbol_internal_links.findMany({
@@ -978,23 +1094,43 @@ var insert4 = safe_query(
 );
 var exists = safe_query(
   "symbol_internal_links.exists",
-  (ctx, params) => ctx.db.select({ id: symbol_internal_links.id }).from(symbol_internal_links).where(and6(eq9(symbol_internal_links.from_symbol_id, params.from_symbol_id), eq9(symbol_internal_links.to_symbol_id, params.to_symbol_id))).get()
+  (ctx, params) => ctx.db.select({ id: symbol_internal_links.id }).from(symbol_internal_links).where(and8(eq9(symbol_internal_links.from_symbol_id, params.from_symbol_id), eq9(symbol_internal_links.to_symbol_id, params.to_symbol_id))).get()
 );
 var del_by_from_symbol = safe_query(
   "symbol_internal_links.del_by_from_symbol",
   (ctx, from_symbol_id) => ctx.db.delete(symbol_internal_links).where(eq9(symbol_internal_links.from_symbol_id, from_symbol_id)).run()
 );
+var update_state_by_to_symbol = safe_query(
+  "symbol_internal_links.update_state_by_to_symbol",
+  (ctx, to_symbol_id, state) => ctx.db.update(symbol_internal_links).set({ state }).where(eq9(symbol_internal_links.to_symbol_id, to_symbol_id)).run()
+);
 
 // src/db/symbol_external_links.ts
 var symbol_external_links_exports = {};
 __export(symbol_external_links_exports, {
   by_external_import: () => by_external_import,
   by_symbol: () => by_symbol2,
+  count: () => count9,
+  count_by_dependency: () => count_by_dependency,
+  count_pending_deps: () => count_pending_deps,
   del_by_symbol: () => del_by_symbol,
   exists: () => exists2,
-  insert: () => insert5
+  insert: () => insert5,
+  search: () => search8
+});
+import { and as and9, eq as eq10, ne as ne3, count as countFn3 } from "drizzle-orm";
+var search8 = safe_query("symbol_external_links.search", (ctx, options = {}) => {
+  return do_search(ctx.db, symbol_external_links, merge(symbol_external_links2, options));
+});
+var count9 = safe_query("symbol_external_links.count", (ctx, where = {}) => {
+  return do_count(ctx.db, symbol_external_links, where);
+});
+var count_by_dependency = safe_query("symbol_external_links.count_by_dependency", (ctx, dependency_id) => {
+  return ctx.db.select({ count: countFn3() }).from(symbol_external_links).innerJoin(external_imports, eq10(symbol_external_links.external_import_id, external_imports.id)).where(eq10(external_imports.external_dependency_id, dependency_id)).get()?.count ?? 0;
+});
+var count_pending_deps = safe_query("symbol_external_links.count_pending_deps", (ctx, symbol_id) => {
+  return ctx.db.select({ count: countFn3() }).from(symbol_external_links).innerJoin(external_imports, eq10(symbol_external_links.external_import_id, external_imports.id)).innerJoin(external_dependencies, eq10(external_imports.external_dependency_id, external_dependencies.id)).where(and9(eq10(symbol_external_links.symbol_id, symbol_id), ne3(external_dependencies.state, "ready"))).get()?.count ?? 0;
 });
-import { and as and7, eq as eq10 } from "drizzle-orm";
 var by_symbol2 = safe_query(
   "symbol_external_links.by_symbol",
   (ctx, symbol_id) => ctx.db.select().from(symbol_external_links).where(eq10(symbol_external_links.symbol_id, symbol_id)).all()
@@ -1009,7 +1145,7 @@ var by_external_import = safe_query(
 );
 var exists2 = safe_query(
   "symbol_external_links.exists",
-  (ctx, params) => ctx.db.select({ id: symbol_external_links.id }).from(symbol_external_links).where(and7(eq10(symbol_external_links.symbol_id, params.symbol_id), eq10(symbol_external_links.external_import_id, params.external_import_id))).get()
+  (ctx, params) => ctx.db.select({ id: symbol_external_links.id }).from(symbol_external_links).where(and9(eq10(symbol_external_links.symbol_id, params.symbol_id), eq10(symbol_external_links.external_import_id, params.external_import_id))).get()
 );
 var del_by_symbol = safe_query(
   "symbol_external_links.del_by_symbol",
@@ -1018,8 +1154,8 @@ var del_by_symbol = safe_query(
 
 // src/internals/context.ts
 async function create_context(sqlite, db6, config) {
-  const project_path = path.resolve(config.project_path);
-  const currentDir = dirname(fileURLToPath(import.meta.url));
+  const project_path = path2.resolve(config.project_path);
+  const currentDir = __dirname;
   const migrations_path = currentDir.includes("/dist") ? join2(currentDir, "../migrations") : join2(currentDir, "../../migrations");
   const tsconfig_path = join2(project_path, "tsconfig.json");
   if (!ts.sys.fileExists(tsconfig_path)) {
@@ -1027,8 +1163,8 @@ async function create_context(sqlite, db6, config) {
   }
   const tsconfig = ts.parseJsonConfigFileContent(ts.readConfigFile(tsconfig_path, ts.sys.readFile).config, ts.sys, project_path);
   const program = ts.createProgram({ rootNames: tsconfig.fileNames, options: tsconfig.options });
-  const package_json_path = config.package_json_path ?? path.join(project_path, "package.json");
-  const node_modules_paths = config.node_modules_paths ?? [path.join(project_path, "node_modules")];
+  const package_json_path = config.package_json_path ?? path2.join(project_path, "package.json");
+  const node_modules_paths = config.node_modules_paths ?? [path2.join(project_path, "node_modules")];
   const dependencies2 = await get_dependencies(package_json_path, node_modules_paths);
   const ctx = { db: db6, sqlite, migrations_path, project_path, program, dependencies: dependencies2 };
   await migrate(ctx);
@@ -1087,7 +1223,7 @@ async function get_dependencies(package_json_path, node_modules_paths) {
 async function get_github_repo(node_modules_paths, package_name) {
   for (const node_modules_path of node_modules_paths) {
     try {
-      const package_json_path = path.join(node_modules_path, package_name, "package.json");
+      const package_json_path = path2.join(node_modules_path, package_name, "package.json");
       const package_json = JSON.parse(await readFile2(package_json_path, "utf-8"));
       const url = package_json.repository?.url || package_json.repository;
       if (typeof url === "string") {
@@ -1104,7 +1240,7 @@ async function get_github_repo(node_modules_paths, package_name) {
 // src/cli/env.ts
 var env = {
   read_file,
-  file_exists: (path6) => existsSync(path6),
+  file_exists: (path7) => existsSync(path7),
   argv: () => process.argv,
   log: (...args) => console.log(...args),
   error: (...args) => console.error(...args),
@@ -1234,7 +1370,7 @@ var DependencySelectOptions = z.object({
 });
 
 // src/update/track_changes.ts
-import path2 from "path";
+import path3 from "path";
 import "typescript";
 import { stat } from "fs/promises";
 
@@ -1245,9 +1381,9 @@ function file_updated(ctx, file_id) {
       items: [file_id],
       get_key: (id) => id,
       get_children: (id) => {
-        const imports2 = imports_exports.by_exporter_file(ctx, id);
-        if (err.any(imports2)) return imports2;
-        return imports2.map((x) => x.importer_file_id);
+        const imports4 = imports_exports.by_exporter_file(ctx, id);
+        if (err.any(imports4)) return imports4;
+        return imports4.map((x) => x.importer_file_id);
       }
     })
   );
@@ -1280,7 +1416,7 @@ function get_source_files(ctx) {
   for (const file of ctx.program.getSourceFiles()) {
     if (ctx.program.isSourceFileDefaultLibrary(file)) continue;
     if (ctx.program.isSourceFileFromExternalLibrary(file)) continue;
-    if (!path2.resolve(file.fileName).startsWith(ctx.project_path)) continue;
+    if (!path3.resolve(file.fileName).startsWith(ctx.project_path)) continue;
     src_files.push(file);
   }
   return src_files;
@@ -1328,7 +1464,7 @@ async function changes(ctx, source_files, db_files) {
   return { created, updated, deleted };
 }
 function get_file_path(ctx, file) {
-  const absolute_path = path2.resolve(file.fileName);
+  const absolute_path = path3.resolve(file.fileName);
   if (absolute_path.startsWith(ctx.project_path)) return absolute_path.slice(ctx.project_path.length);
   return err.new("file_outside_project_path", { file_path: absolute_path, project_path: ctx.project_path });
 }
@@ -1336,10 +1472,10 @@ function get_parents_paths(ctx, file) {
   const file_path = get_file_path(ctx, file);
   if (err.any(file_path)) return file_path;
   const dirs = [];
-  let current = path2.dirname(file_path);
-  while (current !== path2.sep) {
+  let current = path3.dirname(file_path);
+  while (current !== path3.sep) {
     dirs.push(current);
-    current = path2.dirname(current);
+    current = path3.dirname(current);
   }
   dirs.push(current);
   return dirs.reverse();
@@ -1373,19 +1509,19 @@ async function sync_external_dependencies(ctx) {
 }
 
 // src/update/scan_files/scan_files.ts
-import path4 from "path";
+import path5 from "path";
 import ts10 from "typescript";
 
 // src/update/scan_files/imports.ts
 import ts4 from "typescript";
 
 // src/update/scan_files/common.ts
-import path3 from "path";
+import path4 from "path";
 import ts3 from "typescript";
 function is_external_module(ctx, source_file, module_path) {
   const resolved = ts3.resolveModuleName(module_path, source_file.fileName, ctx.program.getCompilerOptions(), ts3.sys);
   if (!resolved.resolvedModule) return true;
-  const resolved_path = path3.resolve(resolved.resolvedModule.resolvedFileName);
+  const resolved_path = path4.resolve(resolved.resolvedModule.resolvedFileName);
   return !resolved_path.startsWith(ctx.project_path);
 }
 function has_export_modifier(node) {
@@ -1494,13 +1630,13 @@ function is_import(ctx, source_file, node) {
   return !is_external_module(ctx, source_file, node.moduleSpecifier.text);
 }
 function extract_import(ctx, source_file, node, file_id) {
-  const imports2 = [];
+  const imports4 = [];
   const clause = node.importClause;
-  if (!clause || !node.moduleSpecifier || !ts4.isStringLiteral(node.moduleSpecifier)) return imports2;
+  if (!clause || !node.moduleSpecifier || !ts4.isStringLiteral(node.moduleSpecifier)) return imports4;
   const exporter_file_id = resolve_exporter_file(ctx, source_file, node.moduleSpecifier.text);
-  if (err.any(exporter_file_id)) return imports2;
+  if (err.any(exporter_file_id)) return imports4;
   if (clause.name) {
-    imports2.push({
+    imports4.push({
       importer_file_id: file_id,
       exporter_file_id,
       name: "default",
@@ -1510,7 +1646,7 @@ function extract_import(ctx, source_file, node, file_id) {
   }
   if (clause.namedBindings && ts4.isNamedImports(clause.namedBindings)) {
     for (const element of clause.namedBindings.elements) {
-      imports2.push({
+      imports4.push({
         importer_file_id: file_id,
         exporter_file_id,
         name: (element.propertyName || element.name).text,
@@ -1520,7 +1656,7 @@ function extract_import(ctx, source_file, node, file_id) {
     }
   }
   if (clause.namedBindings && ts4.isNamespaceImport(clause.namedBindings)) {
-    imports2.push({
+    imports4.push({
       importer_file_id: file_id,
       exporter_file_id,
       name: "*",
@@ -1528,7 +1664,7 @@ function extract_import(ctx, source_file, node, file_id) {
       state: "to_link"
     });
   }
-  return imports2;
+  return imports4;
 }
 function extract_dynamic_import(ctx, source_file, node, file_id) {
   const arg = node.arguments[0];
@@ -1640,7 +1776,7 @@ function extract_external_import_info(node) {
 }
 function extract_external_import(ctx, node, file_id) {
   const infos = extract_external_import_info(node);
-  const external_imports2 = [];
+  const external_imports3 = [];
   for (const info of infos) {
     const dep_meta = Object.values(ctx.dependencies).find((dep) => info.package.startsWith(dep.name));
     const dependency = external_dependencies_exports.get_or_create(ctx, {
@@ -1653,9 +1789,9 @@ function extract_external_import(ctx, node, file_id) {
       state: "to_describe"
     });
     if (err.any(dependency)) return dependency;
-    external_imports2.push({ file_id, external_dependency_id: dependency.id, alias: info.alias, is_dynamic: false });
+    external_imports3.push({ file_id, external_dependency_id: dependency.id, alias: info.alias, is_dynamic: false });
   }
-  return external_imports2;
+  return external_imports3;
 }
 function extract_external_dynamic_import(ctx, node, file_id) {
   const arg = node.arguments[0];
@@ -1960,32 +2096,32 @@ function scan_file(ctx, file) {
     () => external_imports_exports.del_by_file(ctx, file.id),
     () => get_source_file(ctx, file.path),
     (source_file) => parse_file(ctx, source_file, file.id),
-    ({ imports: imports2, symbols: symbols4, external_imports: external_imports2 }) => err.pipe(
-      () => external_imports2.length && external_imports_exports.insert_many(ctx, external_imports2),
-      () => imports2.length && imports_exports.insert_many(ctx, imports2),
+    ({ imports: imports4, symbols: symbols4, external_imports: external_imports3 }) => err.pipe(
+      () => external_imports3.length && external_imports_exports.insert_many(ctx, external_imports3),
+      () => imports4.length && imports_exports.insert_many(ctx, imports4),
       () => symbols4.length && symbols_exports.insert_many(ctx, symbols4)
     )
   );
 }
 function get_source_file(ctx, file_path) {
-  const source_file = ctx.program.getSourceFile(path4.join(ctx.project_path, file_path));
+  const source_file = ctx.program.getSourceFile(path5.join(ctx.project_path, file_path));
   if (!source_file) return err.new("file_not_found", { path: file_path });
   return source_file;
 }
 function parse_file(ctx, source_file, file_id) {
-  const imports2 = [];
+  const imports4 = [];
   const symbols4 = [];
-  const external_imports2 = [];
+  const external_imports3 = [];
   function find_dynamic_imports(node) {
     if (is_dynamic_import(node)) {
       const arg = node.arguments[0];
       if (is_external_module(ctx, source_file, arg.text)) {
         const result = extract_external_dynamic_import(ctx, node, file_id);
         if (err.any(result)) return result;
-        external_imports2.push(result);
+        external_imports3.push(result);
       } else {
         const result = extract_dynamic_import(ctx, source_file, node, file_id);
-        if (result) imports2.push(result);
+        if (result) imports4.push(result);
       }
     }
     ts10.forEachChild(node, find_dynamic_imports);
@@ -1998,24 +2134,24 @@ function parse_file(ctx, source_file, file_id) {
       error = res;
       return;
     }
-    imports2.push(...res.imports);
+    imports4.push(...res.imports);
     symbols4.push(...res.symbols);
-    external_imports2.push(...res.external_imports);
+    external_imports3.push(...res.external_imports);
     error = find_dynamic_imports(statement);
   });
   if (error) return error;
-  return { imports: imports2, symbols: symbols4, external_imports: external_imports2 };
+  return { imports: imports4, symbols: symbols4, external_imports: external_imports3 };
 }
 function parse_node(ctx, source_file, node, file_id) {
-  const imports2 = [];
+  const imports4 = [];
   const symbols4 = [];
-  const external_imports2 = [];
+  const external_imports3 = [];
   if (is_external_import(ctx, source_file, node)) {
     const result = extract_external_import(ctx, node, file_id);
     if (err.any(result)) return result;
-    external_imports2.push(...result);
+    external_imports3.push(...result);
   } else if (is_import(ctx, source_file, node)) {
-    imports2.push(...extract_import(ctx, source_file, node, file_id));
+    imports4.push(...extract_import(ctx, source_file, node, file_id));
   } else if (ts10.isExportAssignment(node) && !node.isExportEquals) {
     symbols4.push({
       file_id,
@@ -2057,14 +2193,14 @@ function parse_node(ctx, source_file, node, file_id) {
     symbols4.push(extract_class_symbol(node, file_id, source_file));
     symbols4.push(...extract_class_fields(node, file_id, source_file));
   }
-  return { imports: imports2, symbols: symbols4, external_imports: external_imports2 };
+  return { imports: imports4, symbols: symbols4, external_imports: external_imports3 };
 }
 
 // src/update/link_imports.ts
 async function link_imports(ctx) {
-  const imports2 = err.or_throw(imports_exports.by_state(ctx, "to_link"));
+  const imports4 = err.or_throw(imports_exports.by_state(ctx, "to_link"));
   let i = 0;
-  for (const import_ of imports2) {
+  for (const import_ of imports4) {
     const res = link_import(ctx, import_);
     if (err.any(res)) err.or_throw(imports_exports.update(ctx, import_.id, { error: String(res) }));
   }
@@ -2080,7 +2216,7 @@ function link_import(ctx, import_) {
 }
 
 // src/update/link_symbols.ts
-import path5 from "path";
+import path6 from "path";
 import ts11 from "typescript";
 async function link_symbols(ctx) {
   const symbols4 = err.or_throw(symbols_exports.by_state(ctx, "to_link"));
@@ -2106,7 +2242,7 @@ function find_symbol_references(ctx, symbol) {
   const file = files_exports.by_id(ctx, symbol.file_id);
   if (err.any(file)) return file;
   if (!file) return err.new("file_not_found", { path: `file_id=${symbol.file_id}` });
-  const file_path = path5.join(ctx.project_path, file.path);
+  const file_path = path6.join(ctx.project_path, file.path);
   const source_file = ctx.program.getSourceFile(file_path);
   if (!source_file) return err.new("file_not_found", { path: file_path });
   const symbol_node = find_symbol_node(source_file, symbol);
@@ -2330,19 +2466,19 @@ async function update6(ctx) {
 }
 
 // src/counts.ts
-import { count } from "drizzle-orm";
-var counts = safe_query("counts", (ctx) => {
-  const symbol_counts = ctx.db.select({ state: symbols.state, count: count() }).from(symbols).groupBy(symbols.state).all();
-  const file_counts = ctx.db.select({ state: files.state, count: count() }).from(files).groupBy(files.state).all();
-  const dir_counts = ctx.db.select({ state: directories.state, count: count() }).from(directories).groupBy(directories.state).all();
-  const dep_counts = ctx.db.select({ state: external_dependencies.state, count: count() }).from(external_dependencies).groupBy(external_dependencies.state).all();
+import { count as count10 } from "drizzle-orm";
+function counts(ctx) {
+  const symbol_counts = ctx.db.select({ state: symbols.state, count: count10() }).from(symbols).groupBy(symbols.state).all();
+  const file_counts = ctx.db.select({ state: files.state, count: count10() }).from(files).groupBy(files.state).all();
+  const dir_counts = ctx.db.select({ state: directories.state, count: count10() }).from(directories).groupBy(directories.state).all();
+  const dep_counts = ctx.db.select({ state: external_dependencies.state, count: count10() }).from(external_dependencies).groupBy(external_dependencies.state).all();
   return {
     symbols: get_groups(symbol_counts, ["to_link", "to_describe", "ready"]),
     files: get_groups(file_counts, ["to_scan", "to_describe", "ready"]),
     directories: get_groups(dir_counts, ["to_describe", "ready"]),
     dependencies: get_groups(dep_counts, ["to_describe", "ready"])
   };
-});
+}
 function get_groups(items, states) {
   const groups = { total: 0 };
   for (const state of states) groups[state] = 0;
@@ -2358,7 +2494,7 @@ function get_groups(items, states) {
 function files_wiki(ctx) {
   return {
     get: (id) => get2(ctx, id),
-    search: (options) => search5(ctx, options),
+    search: (options) => search9(ctx, options),
     set_description: (id, description) => set_description(ctx, id, description),
     imported_by_file: (file_id, options) => imported_by_file(ctx, file_id, options),
     importing_file: (file_id, options) => importing_file(ctx, file_id, options),
@@ -2368,11 +2504,11 @@ function files_wiki(ctx) {
 function get2(ctx, id) {
   return err.or_throw(files_exports.by_id(ctx, id)) ?? null;
 }
-function search5(ctx, options) {
+function search9(ctx, options) {
   return err.or_throw(files_exports.search(ctx, options));
 }
 function set_description(ctx, id, description) {
-  err.or_throw(files_exports.update(ctx, id, { description }));
+  err.or_throw(files_exports.update(ctx, id, { description, state: "ready", error: null }));
 }
 function imported_by_file(ctx, file_id, options = {}) {
   let imported_files = err.or_throw(files_exports.imported_by(ctx, file_id, options.select));
@@ -2424,7 +2560,7 @@ function importing_dependency(ctx, dependency_id, options = {}) {
 function symbols_wiki(ctx) {
   return {
     get: (id) => get3(ctx, id),
-    search: (options) => search6(ctx, options),
+    search: (options) => search10(ctx, options),
     set_description: (id, description) => set_description2(ctx, id, description),
     referencing_symbol: (symbol_id, options) => referencing_symbol(ctx, symbol_id, options),
     referenced_by_symbol: (symbol_id, options) => referenced_by_symbol(ctx, symbol_id, options),
@@ -2434,11 +2570,12 @@ function symbols_wiki(ctx) {
 function get3(ctx, id) {
   return err.or_throw(symbols_exports.by_id(ctx, id)) ?? null;
 }
-function search6(ctx, options) {
+function search10(ctx, options) {
   return err.or_throw(symbols_exports.search(ctx, options));
 }
 function set_description2(ctx, id, description) {
-  err.or_throw(symbols_exports.update(ctx, id, { description }));
+  err.or_throw(symbols_exports.update(ctx, id, { description, state: "ready", error: null }));
+  err.or_throw(symbol_internal_links_exports.update_state_by_to_symbol(ctx, id, "ready"));
 }
 function referenced_by_symbol(ctx, symbol_id, options = {}) {
   let referenced_symbols = err.or_throw(symbols_exports.referenced_by(ctx, symbol_id, options.select));
@@ -2490,7 +2627,7 @@ function using_dependency3(ctx, dependency_id, options = {}) {
 function directories_wiki(ctx) {
   return {
     get: (id) => get4(ctx, id),
-    search: (options) => search7(ctx, options),
+    search: (options) => search11(ctx, options),
     set_description: (id, description) => set_description3(ctx, id, description),
     children: (parent_id, options) => children(ctx, parent_id, options),
     files: (directory_id, options) => directory_files(ctx, directory_id, options)
@@ -2499,11 +2636,11 @@ function directories_wiki(ctx) {
 function get4(ctx, id) {
   return err.or_throw(directories_exports.by_id(ctx, id)) ?? null;
 }
-function search7(ctx, options) {
+function search11(ctx, options) {
   return err.or_throw(directories_exports.search(ctx, options));
 }
 function set_description3(ctx, id, description) {
-  err.or_throw(directories_exports.update(ctx, id, { description }));
+  err.or_throw(directories_exports.update(ctx, id, { description, state: "ready", error: null }));
 }
 function children(ctx, parent_id, options = {}) {
   let child_directories = err.or_throw(directories_exports.search(ctx, { select: options.select, where: { parent_id }, limit: 1e4 }));
@@ -2546,7 +2683,7 @@ function directory_files(ctx, directory_id, options = {}) {
 function dependencies_wiki(ctx) {
   return {
     get: (id) => get5(ctx, id),
-    search: (options) => search8(ctx, options),
+    search: (options) => search12(ctx, options),
     set_description: (id, description) => set_description4(ctx, id, description),
     used_by_file: (file_id, options) => used_by_file2(ctx, file_id, options),
     used_by_symbol: (symbol_id, options) => used_by_symbol2(ctx, symbol_id, options)
@@ -2555,7 +2692,7 @@ function dependencies_wiki(ctx) {
 function get5(ctx, id) {
   return err.or_throw(external_dependencies_exports.by_id(ctx, id)) ?? null;
 }
-function search8(ctx, options) {
+function search12(ctx, options) {
   return err.or_throw(external_dependencies_exports.search(ctx, options));
 }
 function set_description4(ctx, id, description) {
@@ -2568,13 +2705,88 @@ function used_by_symbol2(ctx, symbol_id, options) {
   return err.or_throw(external_dependencies_exports.used_by_symbol(ctx, symbol_id, options?.select));
 }
 
+// src/to_describe.ts
+function to_describe(ctx, limit) {
+  const dependencies_count = err.or_throw(external_dependencies_exports.count(ctx, { state: "to_describe" }));
+  if (dependencies_count > 0) return { type: "dependencies", items: dependencies_to_describe(ctx, limit) };
+  const symbols_count = err.or_throw(symbols_exports.count(ctx, { state: "to_describe" }));
+  if (symbols_count > 0) return { type: "symbols", items: symbols_to_describe(ctx, limit) };
+  const pending_symbols_count = err.or_throw(symbols_exports.count(ctx, { state: "to_link" }));
+  if (pending_symbols_count > 0) throw err.new("could_not_describe_files_due_to_pending_symbols", { count: pending_symbols_count });
+  const files_count = err.or_throw(files_exports.count(ctx, { state: "to_describe" }));
+  if (files_count > 0) return { type: "files", items: files_to_describe(ctx, limit) };
+  const pending_files_count = err.or_throw(files_exports.count(ctx, { state: "to_scan" }));
+  if (pending_files_count > 0) throw err.new("could_not_describe_directories_due_to_pending_files", { count: pending_files_count });
+  const directories_count = err.or_throw(directories_exports.count(ctx, { state: "to_describe" }));
+  if (directories_count > 0) return { type: "directories", items: directories_to_describe(ctx, limit) };
+  return { type: "none" };
+}
+function dependencies_to_describe(ctx, limit) {
+  const candidates = err.or_throw(
+    external_dependencies_exports.search(ctx, {
+      where: { state: "to_describe" },
+      select: ["id", "package", "name"],
+      limit: 1e5
+    })
+  );
+  candidates.sort((a, b) => {
+    if (a.package !== b.package) return a.package.localeCompare(b.package);
+    return (a.name || "").localeCompare(b.name || "");
+  });
+  const ids = candidates.slice(0, limit).map((dep) => dep.id);
+  const items = err.or_throw(external_dependencies_exports.by_ids(ctx, ids));
+  const by_id5 = new Map(items.map((item) => [item.id, item]));
+  return ids.map((id) => by_id5.get(id)).filter((item) => !!item);
+}
+function symbols_to_describe(ctx, limit) {
+  const candidates = err.or_throw(symbols_exports.search(ctx, { where: { state: "to_describe" }, select: ["id", "text"], limit: 1e5 }));
+  const counts2 = {};
+  for (const symbol of candidates) {
+    counts2[symbol.id] = {
+      length: symbol.text?.length ?? 0,
+      missing_external: err.or_throw(symbol_external_links_exports.count_pending_deps(ctx, symbol.id)),
+      missing_internal: err.or_throw(symbol_internal_links_exports.count(ctx, { from_symbol_id: symbol.id, state: "pending" }))
+    };
+  }
+  candidates.sort((x, y) => {
+    const a = counts2[x.id];
+    const b = counts2[y.id];
+    if (!a || !b) return 0;
+    if (a.missing_internal !== b.missing_internal) return a.missing_internal - b.missing_internal;
+    if (a.missing_external !== b.missing_external) return a.missing_external - b.missing_external;
+    return a.length - b.length;
+  });
+  const ids = candidates.slice(0, limit).map((symbol) => symbol.id);
+  const items = err.or_throw(symbols_exports.by_ids(ctx, ids));
+  const by_id5 = new Map(items.map((item) => [item.id, item]));
+  return ids.map((id) => by_id5.get(id)).filter((item) => !!item);
+}
+function files_to_describe(ctx, limit) {
+  return err.or_throw(files_exports.by_state(ctx, "to_describe", limit));
+}
+function directories_to_describe(ctx, limit) {
+  const candidates = err.or_throw(
+    directories_exports.search(ctx, {
+      where: { state: "to_describe" },
+      select: ["id", "path"],
+      limit: 1e5
+    })
+  );
+  candidates.sort((a, b) => b.path.split("/").length - a.path.split("/").length);
+  const ids = candidates.slice(0, limit).map((dir) => dir.id);
+  const items = err.or_throw(directories_exports.by_ids(ctx, ids));
+  const by_id5 = new Map(items.map((item) => [item.id, item]));
+  return ids.map((id) => by_id5.get(id)).filter((item) => !!item);
+}
+
 // src/index.ts
 async function create(config) {
   const ctx = await context_from_config(config);
   return {
     config,
     update: () => update6(ctx),
-    counts: () => err.or_throw(counts(ctx)),
+    counts: () => counts(ctx),
+    to_describe: (limit) => to_describe(ctx, limit),
     files: files_wiki(ctx),
     symbols: symbols_wiki(ctx),
     directories: directories_wiki(ctx),
@@ -2594,7 +2806,8 @@ async function load(db_path) {
   return {
     config,
     update: () => update6(ctx),
-    counts: () => err.or_throw(counts(ctx)),
+    counts: () => counts(ctx),
+    to_describe: (limit) => to_describe(ctx, limit),
     files: files_wiki(ctx),
     symbols: symbols_wiki(ctx),
     directories: directories_wiki(ctx),
@@ -2643,8 +2856,8 @@ function parse_options(options_json, schema, context) {
     env.log(`Error: Invalid options format in ${context}`);
     env.log("");
     for (const issue of validation_result.error.issues) {
-      const path6 = issue.path.length > 0 ? issue.path.join(".") : "root";
-      env.log(`  \u2022 ${path6}: ${issue.message}`);
+      const path7 = issue.path.length > 0 ? issue.path.join(".") : "root";
+      env.log(`  \u2022 ${path7}: ${issue.message}`);
     }
     env.log("");
     env.log(`Run 'codewiki ${context.split(" ")[0]} --help' for usage information`);
@@ -2700,12 +2913,23 @@ var describe = new Command3("describe");
 describe.description("Show the next item to describe");
 describe.action(async () => {
   const wiki = await load_wiki();
-  const next = get_next_to_describe(wiki);
-  if (!next) return env.log("All items are described!");
-  if (next.type === "dependency") return describe_dependency(next.entity);
-  env.log(
-    `All external dependencies are described, and we don't support describing other items yet (we are implementing the right order ...). You are done for now!`
-  );
+  const result = wiki.to_describe(1);
+  if (result.type === "none") {
+    return env.log("All items are described!");
+  }
+  if (result.type === "dependencies" && result.items.length > 0) {
+    return describe_dependency(result.items[0]);
+  }
+  if (result.type === "symbols" && result.items.length > 0) {
+    return describe_symbol(wiki, result.items[0]);
+  }
+  if (result.type === "files" && result.items.length > 0) {
+    return describe_file(result.items[0]);
+  }
+  if (result.type === "directories" && result.items.length > 0) {
+    return describe_directory(result.items[0]);
+  }
+  env.log("No items to describe.");
 });
 function describe_dependency(dep) {
   env.log(dedent2`
@@ -2721,40 +2945,42 @@ function describe_dependency(dep) {
       \`codewiki dependencies set-description ${dep.id} <markdown-file>\`
   `);
 }
-function get_next_to_describe(wiki) {
-  const deps = wiki.dependencies.search({
-    where: { state: "to_describe" },
-    limit: 1,
-    select: ["id", "package", "subpath", "name", "version", "github_repo"]
-  });
-  if (deps.length > 0) {
-    return { type: "dependency", entity: deps[0] };
-  }
-  const symbols4 = wiki.symbols.search({
-    where: { state: "to_describe" },
-    limit: 1,
-    select: ["id", "name", "type", "file_id", "is_exported"]
-  });
-  if (symbols4.length > 0) {
-    return { type: "symbol", entity: symbols4[0] };
-  }
-  const files5 = wiki.files.search({
-    where: { state: "to_describe" },
-    limit: 1,
-    select: ["id", "path"]
-  });
-  if (files5.length > 0) {
-    return { type: "file", entity: files5[0] };
-  }
-  const directories4 = wiki.directories.search({
-    where: { state: "to_describe" },
-    limit: 1,
-    select: ["id", "path"]
-  });
-  if (directories4.length > 0) {
-    return { type: "directory", entity: directories4[0] };
-  }
-  return null;
+function describe_symbol(wiki, sym) {
+  const file = wiki.files.get(sym.file_id);
+  env.log(dedent2`
+    Your task is to describe the following symbol:
+
+    name: ${sym.name}
+    type: ${sym.type}
+    file: ${file?.path || "unknown"}
+    exported: ${sym.is_exported}
+
+    Write a concise developer documentation for this ${sym.type} into a markdown file, then run:
+
+    codewiki symbols set-description ${sym.id} <markdown-file>
+  `);
+}
+function describe_file(file) {
+  env.log(dedent2`
+    Your task is to describe the following file:
+
+    path: ${file.path}
+
+    Write a concise description of this file's purpose and contents into a markdown file, then run:
+
+    codewiki files set-description ${file.id} <markdown-file>
+  `);
+}
+function describe_directory(dir) {
+  env.log(dedent2`
+    Your task is to describe the following directory:
+
+    path: ${dir.path}
+
+    Write a concise description of this directory's purpose and contents into a markdown file, then run:
+
+    codewiki directories set-description ${dir.id} <markdown-file>
+  `);
 }
 
 // src/cli/commands/files/index.ts
@@ -2774,10 +3000,10 @@ get6.action(async (id) => {
 
 // src/cli/commands/files/search.ts
 import { Command as Command5 } from "commander";
-var search9 = new Command5("search");
-search9.description("Search files with JSON options");
-search9.argument("<options>", "JSON options for search");
-search9.action(async (options_json) => {
+var search13 = new Command5("search");
+search13.description("Search files with JSON options");
+search13.argument("<options>", "JSON options for search");
+search13.action(async (options_json) => {
   const wiki = await load_wiki();
   const options = parse_options(options_json, FileSearchOptions, "files search");
   const results = wiki.files.search(options);
@@ -2846,7 +3072,7 @@ importing_dependency2.action(async (dep_id, options_json) => {
 var files3 = new Command10("files");
 files3.description("Explore files");
 files3.addCommand(get6);
-files3.addCommand(search9);
+files3.addCommand(search13);
 files3.addCommand(set_description5);
 files3.addCommand(imported_by_file2);
 files3.addCommand(importing_file2);
@@ -2897,10 +3123,10 @@ get7.action(async (id) => {
 
 // src/cli/commands/symbols/search.ts
 import { Command as Command12 } from "commander";
-var search10 = new Command12("search");
-search10.description("Search symbols with JSON options");
-search10.argument("<options>", "JSON options");
-search10.action(async (options_json) => {
+var search14 = new Command12("search");
+search14.description("Search symbols with JSON options");
+search14.argument("<options>", "JSON options");
+search14.action(async (options_json) => {
   const wiki = await load_wiki();
   const options = parse_options(options_json, SymbolSearchOptions, "symbols search");
   const results = wiki.symbols.search(options);
@@ -2969,7 +3195,7 @@ using_dependency4.action(async (dep_id, options_json) => {
 var symbols3 = new Command17("symbols");
 symbols3.description("Explore symbols");
 symbols3.addCommand(get7);
-symbols3.addCommand(search10);
+symbols3.addCommand(search14);
 symbols3.addCommand(set_description6);
 symbols3.addCommand(referencing_symbol2);
 symbols3.addCommand(referenced_by_symbol2);
@@ -3020,10 +3246,10 @@ get8.action(async (id) => {
 
 // src/cli/commands/directories/search.ts
 import { Command as Command19 } from "commander";
-var search11 = new Command19("search");
-search11.description("Search directories with JSON options");
-search11.argument("<options>", "JSON options");
-search11.action(async (options_json) => {
+var search15 = new Command19("search");
+search15.description("Search directories with JSON options");
+search15.argument("<options>", "JSON options");
+search15.action(async (options_json) => {
   const wiki = await load_wiki();
   const options = parse_options(options_json, DirectorySearchOptions, "directories search");
   const results = wiki.directories.search(options);
@@ -3079,7 +3305,7 @@ files4.action(async (directory_id, options_json) => {
 var directories3 = new Command23("directories");
 directories3.description("Explore directories");
 directories3.addCommand(get8);
-directories3.addCommand(search11);
+directories3.addCommand(search15);
 directories3.addCommand(set_description7);
 directories3.addCommand(children2);
 directories3.addCommand(files4);
@@ -3129,10 +3355,10 @@ get9.action(async (id) => {
 
 // src/cli/commands/dependencies/search.ts
 import { Command as Command25 } from "commander";
-var search12 = new Command25("search");
-search12.description("Search dependencies with JSON options");
-search12.argument("<options>", "JSON options");
-search12.action(async (options_json) => {
+var search16 = new Command25("search");
+search16.description("Search dependencies with JSON options");
+search16.argument("<options>", "JSON options");
+search16.action(async (options_json) => {
   const wiki = await load_wiki();
   const options = parse_options(options_json, DependencySearchOptions, "dependencies search");
   const results = wiki.dependencies.search(options);
@@ -3188,7 +3414,7 @@ used_by_symbol3.action(async (symbol_id, options_json) => {
 var dependencies = new Command29("dependencies");
 dependencies.description("Explore dependencies");
 dependencies.addCommand(get9);
-dependencies.addCommand(search12);
+dependencies.addCommand(search16);
 dependencies.addCommand(set_description8);
 dependencies.addCommand(used_by_file3);
 dependencies.addCommand(used_by_symbol3);