@bendyline/gezel-knowledge 1.2.1 → 1.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -1052,7 +1052,7 @@ declare function createProfileEmbedder(profile: KnowledgeEmbeddingProfile, opts?
1052
1052
  * files, never the disk, so an outline can be checked in a test without a
1053
1053
  * tree on disk.
1054
1054
  */
1055
- type TableOfContentsFormat = 'folders' | 'hugo' | 'gitbook' | 'mkdocs' | 'jupyter-book';
1055
+ type TableOfContentsFormat = 'folders' | 'hugo' | 'gitbook' | 'mkdocs' | 'jupyter-book' | 'docfx';
1056
1056
  type OutlineFormat = Exclude<TableOfContentsFormat, 'folders' | 'hugo'>;
1057
1057
  interface OutlineEntry {
1058
1058
  /** Root-relative POSIX path of the Markdown file, extension included. */
@@ -1131,10 +1131,11 @@ declare function parseJupyterBookToc(doc: unknown, tocDir: string, files: readon
1131
1131
  * gets the single root topic the compiler demands.
1132
1132
  *
1133
1133
  * A tree that already carries an outline keeps it: GitBook's `SUMMARY.md`,
1134
- * an `mkdocs.yml` nav and Jupyter Book's `_toc.yml` are read into the same
1135
- * topic tree (`outline.ts`), and Hugo's conventions — `_index.md` section
1136
- * pages, `weight`, `draft` — are honored on top of the folders. A file an
1137
- * outline omits stays in its folder, with a warning, so nothing is lost.
1134
+ * an `mkdocs.yml` nav, Jupyter Book's `_toc.yml` and docfx's per-folder
1135
+ * `toc.yml` files are read into the same topic tree (`outline.ts`,
1136
+ * `docfx.ts`), and Hugo's conventions — `_index.md` section pages,
1137
+ * `weight`, `draft` — are honored on top of the folders. A file an outline
1138
+ * omits stays in its folder, with a warning, so nothing is lost.
1138
1139
  *
1139
1140
  * Front matter carries what a documentation tree knows about itself: the
1140
1141
  * title and summary, an explicit `id`, an `order` (the listing ordinal), a
@@ -1166,7 +1167,10 @@ interface TableOfContentsOptions {
1166
1167
  /**
1167
1168
  * The outline file for `gitbook` (`SUMMARY.md`), `mkdocs` (`mkdocs.yml`)
1168
1169
  * and `jupyter-book` (`_toc.yml`), absolute or relative to the root. By
1169
- * default the root is searched, and for mkdocs its parent as well.
1170
+ * default the root is searched, and for mkdocs its parent as well. For
1171
+ * `docfx` it is the entry TOC (a breadcrumb such as `bread/toc.yml`, or a
1172
+ * root `toc.yml`); by default docfx.json's `breadcrumb_path`, else the
1173
+ * root `toc.yml`.
1170
1174
  */
1171
1175
  path?: string;
1172
1176
  }
@@ -1192,7 +1196,7 @@ interface LoadMarkdownCatalogOptions {
1192
1196
  publisherId: string;
1193
1197
  catalogId: string;
1194
1198
  };
1195
- /** What to do with an image link whose file is missing (default `error`). */
1199
+ /** What to do with an image link whose file is missing (default `error`; `warn` for docfx). */
1196
1200
  missingAssets?: 'error' | 'warn';
1197
1201
  onWarning?: (message: string) => void;
1198
1202
  }
@@ -1201,8 +1205,9 @@ declare function readMkdocsDocsDir(mkdocsPath: string): Promise<string>;
1201
1205
  /**
1202
1206
  * Which outline a tree carries: GitBook's `SUMMARY.md` or Jupyter Book's
1203
1207
  * `_toc.yml` at the root, an `mkdocs.yml` at the root, the project folder
1204
- * or the root's parent, Hugo's `_index.md` section pages anywhere in the
1205
- * tree — else the folders themselves.
1208
+ * or the root's parent, a docfx project (`docfx.json` or a `toc.yml` at the
1209
+ * root), Hugo's `_index.md` section pages anywhere in the tree — else the
1210
+ * folders themselves.
1206
1211
  */
1207
1212
  declare function detectTableOfContents(rootDir: string, projectDir?: string): Promise<TableOfContentsOptions>;
1208
1213
  /**
package/dist/index.js CHANGED
@@ -3817,52 +3817,19 @@ async function createProfileEmbedder(profile, opts = {}) {
3817
3817
  // src/markdown-adapter/load.ts
3818
3818
  import { existsSync } from "fs";
3819
3819
  import { readFile as readFile3, readdir } from "fs/promises";
3820
- import { basename, dirname as dirname3, isAbsolute as isAbsolute3, join as join6, posix as posix2, relative as relative3, resolve as resolve4, sep } from "path";
3820
+ import { basename, dirname as dirname3, isAbsolute as isAbsolute3, join as join6, posix as posix3, relative as relative3, resolve as resolve4, sep } from "path";
3821
3821
  import {
3822
3822
  CatalogDocumentSchema,
3823
3823
  KnowledgeDocumentIdSchema,
3824
3824
  KnowledgeOrdinalSchema,
3825
+ MAX_KNOWLEDGE_TOPIC_DEPTH as MAX_KNOWLEDGE_TOPIC_DEPTH2,
3825
3826
  assetExtension as assetExtension3,
3826
3827
  formatKnowledgeUri,
3827
3828
  topicSortKeyForOrder
3828
3829
  } from "@bendyline/gezk";
3829
3830
 
3830
- // src/markdown-adapter/frontmatter.ts
3831
- import { parseDocument } from "yaml";
3832
- var FRONTMATTER_MAX_BYTES = 64 * 1024;
3833
- var OUTLINE_MAX_BYTES = 1024 * 1024;
3834
- function parseYaml(text, opts) {
3835
- const maxBytes = opts.maxBytes ?? FRONTMATTER_MAX_BYTES;
3836
- if (Buffer.byteLength(text, "utf8") > maxBytes) {
3837
- throw new Error(`${opts.what} exceeds ${maxBytes} bytes`);
3838
- }
3839
- const doc = parseDocument(text, {
3840
- version: "1.2",
3841
- schema: "core",
3842
- uniqueKeys: true,
3843
- logLevel: "silent"
3844
- });
3845
- const problem = doc.errors[0] ?? (opts.tolerateUnknownTags ? void 0 : doc.warnings[0]);
3846
- if (problem) throw new Error(`${opts.what}: ${problem.message.split("\n")[0]}`);
3847
- return doc.toJS({ maxAliasCount: opts.maxAliasCount ?? 0 });
3848
- }
3849
- var OPEN = /^---[ \t]*\r?\n/;
3850
- var CLOSE = /^(?:---|\.\.\.)[ \t]*$/;
3851
- function parseMarkdownFrontMatter(source) {
3852
- const open = OPEN.exec(source);
3853
- if (!open) return { data: {}, body: source };
3854
- const lines = source.slice(open[0].length).split(/\r?\n/);
3855
- const closeAt = lines.findIndex((line) => CLOSE.test(line));
3856
- if (closeAt === -1) throw new Error("front matter is not closed with ---");
3857
- const yamlText = lines.slice(0, closeAt).join("\n");
3858
- const body = lines.slice(closeAt + 1).join("\n");
3859
- const parsed = parseYaml(yamlText, { what: "front matter" });
3860
- if (parsed === null || parsed === void 0) return { data: {}, body };
3861
- if (typeof parsed !== "object" || Array.isArray(parsed)) {
3862
- throw new Error("front matter must be a mapping");
3863
- }
3864
- return { data: parsed, body };
3865
- }
3831
+ // src/markdown-adapter/docfx.ts
3832
+ import { posix as posix2 } from "path";
3866
3833
 
3867
3834
  // src/markdown-adapter/outline.ts
3868
3835
  import { posix } from "path";
@@ -4159,14 +4126,400 @@ function parseJupyterBookToc(doc, tocDir, files, tocFile = "_toc.yml") {
4159
4126
  return outline;
4160
4127
  }
4161
4128
 
4129
+ // src/markdown-adapter/docfx.ts
4130
+ var HAS_SCHEME2 = /^[a-z][a-z0-9+.-]*:/i;
4131
+ var MARKDOWN_EXT2 = /\.(md|markdown)$/i;
4132
+ var TOC_FILE = /^toc\.(ya?ml|json|md)$/i;
4133
+ var LANDING_PAGE = /(^|\/)index\.(ya?ml|md)$/i;
4134
+ var WARNING_EXAMPLES = 5;
4135
+ function isRecord2(value) {
4136
+ return typeof value === "object" && value !== null && !Array.isArray(value);
4137
+ }
4138
+ function normalizeFolder(value) {
4139
+ if (typeof value !== "string") return "";
4140
+ const cleaned = posix2.normalize(value.replace(/\\/g, "/")).replace(/^\.?\/+|\/+$/g, "");
4141
+ return cleaned === "." ? "" : cleaned;
4142
+ }
4143
+ function dirOf(file) {
4144
+ const dir = posix2.dirname(file);
4145
+ return dir === "." ? "" : dir;
4146
+ }
4147
+ function parentOf(dir) {
4148
+ return dir === "" ? null : dirOf(dir);
4149
+ }
4150
+ function isUnder(file, dir) {
4151
+ return dir === "" || file.startsWith(`${dir}/`);
4152
+ }
4153
+ function escapeRegExp(text) {
4154
+ return text.replace(/[.+^$()|[\]\\]/g, "\\$&");
4155
+ }
4156
+ function docfxGlob(pattern) {
4157
+ const p = pattern.replace(/\\/g, "/").replace(/^\.\//, "");
4158
+ let source = "";
4159
+ for (let i = 0; i < p.length; i++) {
4160
+ const ch = p[i];
4161
+ if (ch === "*") {
4162
+ if (p[i + 1] === "*") {
4163
+ if (p[i + 2] === "/") {
4164
+ source += "(?:.*/)?";
4165
+ i += 2;
4166
+ } else {
4167
+ source += ".*";
4168
+ i += 1;
4169
+ }
4170
+ } else source += "[^/]*";
4171
+ } else if (ch === "?") {
4172
+ source += "[^/]";
4173
+ } else if (ch === "{" && p.indexOf("}", i) > i) {
4174
+ const close = p.indexOf("}", i);
4175
+ source += `(?:${p.slice(i + 1, close).split(",").map(escapeRegExp).join("|")})`;
4176
+ i = close;
4177
+ } else {
4178
+ source += escapeRegExp(ch);
4179
+ }
4180
+ }
4181
+ return new RegExp(`^${source}$`, "i");
4182
+ }
4183
+ function globList(value) {
4184
+ const list = typeof value === "string" ? [value] : Array.isArray(value) ? value : [];
4185
+ return list.filter((g) => typeof g === "string" && g.trim() !== "").map(docfxGlob);
4186
+ }
4187
+ function parseDocfxJson(config, configFile = "docfx.json") {
4188
+ if (!isRecord2(config)) throw new Error(`${configFile}: not a JSON object`);
4189
+ const build = isRecord2(config.build) ? config.build : {};
4190
+ const content = [];
4191
+ for (const group of Array.isArray(build.content) ? build.content : []) {
4192
+ if (!isRecord2(group)) continue;
4193
+ const include = globList(group.files);
4194
+ if (include.length === 0) continue;
4195
+ content.push({
4196
+ src: normalizeFolder(group.src),
4197
+ dest: normalizeFolder(group.dest),
4198
+ include,
4199
+ exclude: globList(group.exclude)
4200
+ });
4201
+ }
4202
+ const meta = isRecord2(build.globalMetadata) ? build.globalMetadata : {};
4203
+ const breadcrumb = meta.breadcrumb_path;
4204
+ return {
4205
+ content,
4206
+ ...typeof breadcrumb === "string" && breadcrumb.trim() ? { breadcrumbPath: breadcrumb.trim() } : {}
4207
+ };
4208
+ }
4209
+ function docfxPublishes(project, file) {
4210
+ if (project.content.length === 0) return true;
4211
+ return project.content.some((group) => {
4212
+ if (!isUnder(file, group.src)) return false;
4213
+ const rel = group.src === "" ? file : file.slice(group.src.length + 1);
4214
+ return group.include.some((r) => r.test(rel)) && !group.exclude.some((r) => r.test(rel));
4215
+ });
4216
+ }
4217
+ function tocItems(doc) {
4218
+ if (Array.isArray(doc)) return doc;
4219
+ if (isRecord2(doc) && Array.isArray(doc.items)) return doc.items;
4220
+ return [];
4221
+ }
4222
+ function isBreadcrumbToc(doc) {
4223
+ let tocHref = false;
4224
+ const visit = (items) => {
4225
+ for (const item of items) {
4226
+ if (!isRecord2(item)) continue;
4227
+ if (typeof item.href === "string") return false;
4228
+ if (typeof item.tocHref === "string") tocHref = true;
4229
+ if (Array.isArray(item.items) && !visit(item.items)) return false;
4230
+ }
4231
+ return true;
4232
+ };
4233
+ return visit(tocItems(doc)) && tocHref;
4234
+ }
4235
+ function basePrefixes(url) {
4236
+ const segments = url.split("/").filter(Boolean);
4237
+ const out = ["/"];
4238
+ for (let i = 1; i < segments.length; i++) out.push(`/${segments.slice(0, i).join("/")}/`);
4239
+ return out;
4240
+ }
4241
+ function parseDocfxToc(input) {
4242
+ const outline = {
4243
+ format: "docfx",
4244
+ root: newOutlineTopic(""),
4245
+ consumed: input.files.filter((file) => TOC_FILE.test(posix2.basename(file))),
4246
+ warnings: []
4247
+ };
4248
+ const known = new Set(input.files.map((file) => file.normalize("NFC")));
4249
+ const groups = input.project?.content.length ? [...input.project.content].sort((a, b) => b.dest.length - a.dest.length) : [{ src: "", dest: "", include: [], exclude: [] }];
4250
+ const tocByDir = /* @__PURE__ */ new Map();
4251
+ for (const file of [...input.tocs.keys()].sort()) {
4252
+ if (/\.ya?ml$/i.test(file) && !tocByDir.has(dirOf(file))) tocByDir.set(dirOf(file), file);
4253
+ }
4254
+ const sourcesOf = (sitePath) => {
4255
+ const out = [];
4256
+ for (const group of groups) {
4257
+ if (group.dest !== "" && sitePath !== group.dest && !sitePath.startsWith(`${group.dest}/`))
4258
+ continue;
4259
+ const rest = sitePath.slice(group.dest.length).replace(/^\/+/, "");
4260
+ out.push(group.src && rest ? `${group.src}/${rest}` : group.src || rest);
4261
+ }
4262
+ return out;
4263
+ };
4264
+ const tocAt = (path) => {
4265
+ const trimmed = path.replace(/\/+$/, "");
4266
+ return TOC_FILE.test(posix2.basename(trimmed)) ? tocByDir.get(dirOf(trimmed)) : tocByDir.get(trimmed);
4267
+ };
4268
+ const pageAt = (path) => {
4269
+ const candidates = path === "" || path.endsWith("/") ? [`${path}index.md`] : MARKDOWN_EXT2.test(path) ? [path] : [`${path}.md`, `${path}/index.md`];
4270
+ return candidates.find((candidate) => known.has(candidate.normalize("NFC")));
4271
+ };
4272
+ const resolveSite = (url, base2) => {
4273
+ const path = url.replace(/[?#].*$/, "");
4274
+ let below;
4275
+ if (`${path}/` === base2) below = "";
4276
+ else if (path.startsWith(base2)) below = path.slice(base2.length);
4277
+ else return null;
4278
+ for (const source of sourcesOf(below)) {
4279
+ const page = pageAt(source);
4280
+ if (page) return { kind: "page", file: page };
4281
+ const toc = tocAt(source);
4282
+ if (toc) return { kind: "toc", file: toc };
4283
+ }
4284
+ return null;
4285
+ };
4286
+ let entry = input.entry;
4287
+ let base;
4288
+ const breadcrumb = input.project?.breadcrumbPath;
4289
+ if (!entry && breadcrumb) {
4290
+ for (const candidate of basePrefixes(breadcrumb)) {
4291
+ const target = resolveSite(breadcrumb, candidate);
4292
+ if (target?.kind === "toc") {
4293
+ entry = target.file;
4294
+ base = candidate;
4295
+ break;
4296
+ }
4297
+ }
4298
+ if (!entry) {
4299
+ outline.warnings.push(
4300
+ `docfx.json: breadcrumb_path '${breadcrumb}' names no toc.yml in the tree; ignored`
4301
+ );
4302
+ }
4303
+ }
4304
+ entry ??= tocByDir.get("");
4305
+ if (entry && base === void 0) {
4306
+ const urls = [];
4307
+ const collect = (items) => {
4308
+ for (const item of items) {
4309
+ if (!isRecord2(item)) continue;
4310
+ for (const key of ["tocHref", "topicHref", "href"]) {
4311
+ const value = item[key];
4312
+ if (typeof value === "string" && value.startsWith("/") && !value.startsWith("//")) {
4313
+ urls.push(value);
4314
+ }
4315
+ }
4316
+ if (Array.isArray(item.items)) collect(item.items);
4317
+ }
4318
+ };
4319
+ collect(tocItems(input.tocs.get(entry)));
4320
+ let best = { base: "/", hits: 0 };
4321
+ for (const candidate of [...new Set(urls.flatMap(basePrefixes))].sort(
4322
+ (a, b) => a.length - b.length
4323
+ )) {
4324
+ const hits = urls.filter((url) => resolveSite(url, candidate) !== null).length;
4325
+ if (hits > best.hits) best = { base: candidate, hits };
4326
+ }
4327
+ base = best.base;
4328
+ }
4329
+ const siteBase = base ?? "/";
4330
+ const classify = (href, tocDir) => {
4331
+ const value = href.trim();
4332
+ if (value === "" || value.startsWith("#") || HAS_SCHEME2.test(value) || value.startsWith("//"))
4333
+ return null;
4334
+ if (value.startsWith("/")) return resolveSite(value, siteBase);
4335
+ const path = resolveOutlinePath(tocDir, value);
4336
+ if (path === null) return null;
4337
+ if (MARKDOWN_EXT2.test(path)) return { kind: "page", file: path };
4338
+ const toc = tocAt(path);
4339
+ return toc ? { kind: "toc", file: toc } : null;
4340
+ };
4341
+ const crossLinks = /* @__PURE__ */ new WeakSet();
4342
+ const included = /* @__PURE__ */ new Set();
4343
+ const homes = /* @__PURE__ */ new Map();
4344
+ const pageEntry = (file, tocDir) => {
4345
+ const entry2 = { file };
4346
+ if (!isUnder(file, tocDir)) crossLinks.add(entry2);
4347
+ return entry2;
4348
+ };
4349
+ const walkItems = (items, tocFile, container, followTocHref) => {
4350
+ const tocDir = dirOf(tocFile);
4351
+ for (const item of items) {
4352
+ if (!isRecord2(item)) continue;
4353
+ const name = typeof item.name === "string" ? item.name.trim() : "";
4354
+ const href = typeof item.href === "string" ? classify(item.href, tocDir) : null;
4355
+ const topicHref = typeof item.topicHref === "string" ? classify(item.topicHref, tocDir) : null;
4356
+ const tocHref = followTocHref && typeof item.tocHref === "string" ? classify(item.tocHref, tocDir) : null;
4357
+ const page = [href, topicHref].find((target) => target?.kind === "page");
4358
+ const nested = [href, tocHref].find(
4359
+ (target) => target?.kind === "toc" && !included.has(target.file)
4360
+ );
4361
+ const children = Array.isArray(item.items) && item.items.length > 0 ? item.items : null;
4362
+ if (!nested && !children) {
4363
+ if (page) container.entries.push(pageEntry(page.file, tocDir));
4364
+ continue;
4365
+ }
4366
+ const topic = newOutlineTopic(
4367
+ name || (nested ? titleFromFolderName(posix2.basename(dirOf(nested.file))) : "Untitled")
4368
+ );
4369
+ if (!name && page) topic.titleFromFile = page.file;
4370
+ if (page) topic.entries.push(pageEntry(page.file, tocDir));
4371
+ if (nested) includeToc(nested.file, topic, false);
4372
+ if (children) walkItems(children, tocFile, topic, followTocHref);
4373
+ container.children.push(topic);
4374
+ }
4375
+ };
4376
+ const includeToc = (file, container, followTocHref) => {
4377
+ if (included.has(file)) return;
4378
+ included.add(file);
4379
+ const dir = dirOf(file);
4380
+ if (container !== outline.root && !homes.has(dir)) homes.set(dir, container);
4381
+ walkItems(tocItems(input.tocs.get(file)), file, container, followTocHref);
4382
+ };
4383
+ const homeOf = (dir) => {
4384
+ for (let d = dir; d !== null; d = parentOf(d)) {
4385
+ const home = homes.get(d);
4386
+ if (home) return home;
4387
+ }
4388
+ return void 0;
4389
+ };
4390
+ if (entry) {
4391
+ outline.entry = entry;
4392
+ includeToc(entry, outline.root, true);
4393
+ }
4394
+ const lone = outline.root.entries.length === 0 && outline.root.children.length === 1 ? outline.root.children[0] : void 0;
4395
+ const top = lone ?? outline.root;
4396
+ const orphans = [...input.tocs.keys()].filter((file) => !included.has(file) && /\.ya?ml$/i.test(file)).sort((a, b) => a.split("/").length - b.split("/").length || (a < b ? -1 : a > b ? 1 : 0));
4397
+ for (const file of orphans) {
4398
+ if (included.has(file)) continue;
4399
+ const doc = input.tocs.get(file);
4400
+ if (isBreadcrumbToc(doc)) continue;
4401
+ const parent = parentOf(dirOf(file));
4402
+ const topic = newOutlineTopic(orphanTopicName(file, doc));
4403
+ ((parent === null ? void 0 : homeOf(parent)) ?? top).children.push(topic);
4404
+ includeToc(file, topic, false);
4405
+ }
4406
+ const listed = /* @__PURE__ */ new Set();
4407
+ const collectListed = (topic) => {
4408
+ for (const entry2 of topic.entries) {
4409
+ if (!crossLinks.has(entry2)) listed.add(entry2.file.normalize("NFC"));
4410
+ }
4411
+ topic.children.forEach(collectListed);
4412
+ };
4413
+ collectListed(outline.root);
4414
+ const placed = /* @__PURE__ */ new Set();
4415
+ const missing = [];
4416
+ const duplicates = [];
4417
+ const settle = (topic) => {
4418
+ topic.entries = topic.entries.filter((entry2) => {
4419
+ const key = entry2.file.normalize("NFC");
4420
+ if (!known.has(key)) {
4421
+ missing.push(entry2.file);
4422
+ return false;
4423
+ }
4424
+ if (crossLinks.has(entry2) && listed.has(key)) return false;
4425
+ if (placed.has(key)) {
4426
+ if (!crossLinks.has(entry2)) duplicates.push(entry2.file);
4427
+ return false;
4428
+ }
4429
+ placed.add(key);
4430
+ return true;
4431
+ });
4432
+ topic.children.forEach(settle);
4433
+ };
4434
+ settle(outline.root);
4435
+ const consumed = new Set(outline.consumed.map((file) => file.normalize("NFC")));
4436
+ const homed = [];
4437
+ for (const file of input.files) {
4438
+ const key = file.normalize("NFC");
4439
+ if (placed.has(key) || consumed.has(key)) continue;
4440
+ const home = homeOf(dirOf(file));
4441
+ if (!home) continue;
4442
+ home.entries.push({ file });
4443
+ homed.push(file);
4444
+ }
4445
+ if (lone) {
4446
+ outline.root.entries = lone.entries;
4447
+ outline.root.children = lone.children;
4448
+ }
4449
+ assignOutlineOrders(outline.root);
4450
+ const report = (files, what) => {
4451
+ if (files.length === 0) return;
4452
+ const named = files.slice(0, WARNING_EXAMPLES).join(", ");
4453
+ const more = files.length > WARNING_EXAMPLES ? `, and ${files.length - WARNING_EXAMPLES} more` : "";
4454
+ outline.warnings.push(`${files.length} ${what}: ${named}${more}`);
4455
+ };
4456
+ report(
4457
+ [...new Set(missing)],
4458
+ "pages named by a toc.yml are not among the published Markdown files"
4459
+ );
4460
+ report([...new Set(duplicates)], "pages are listed more than once; the first place wins");
4461
+ report(homed, "pages are in no toc.yml; filed with their folder's section");
4462
+ return outline;
4463
+ }
4464
+ function orphanTopicName(file, doc) {
4465
+ for (const item of tocItems(doc)) {
4466
+ if (!isRecord2(item) || typeof item.name !== "string" || typeof item.href !== "string") continue;
4467
+ if (!LANDING_PAGE.test(item.href.replace(/[?#].*$/, ""))) continue;
4468
+ const name = item.name.trim().replace(/\s+(documentation|docs)$/i, "").trim();
4469
+ if (name) return name;
4470
+ }
4471
+ const folder = posix2.basename(dirOf(file));
4472
+ return folder ? titleFromFolderName(folder) : "Documentation";
4473
+ }
4474
+
4475
+ // src/markdown-adapter/frontmatter.ts
4476
+ import { parseDocument } from "yaml";
4477
+ var FRONTMATTER_MAX_BYTES = 64 * 1024;
4478
+ var OUTLINE_MAX_BYTES = 1024 * 1024;
4479
+ function parseYaml(text, opts) {
4480
+ const maxBytes = opts.maxBytes ?? FRONTMATTER_MAX_BYTES;
4481
+ if (Buffer.byteLength(text, "utf8") > maxBytes) {
4482
+ throw new Error(`${opts.what} exceeds ${maxBytes} bytes`);
4483
+ }
4484
+ const doc = parseDocument(text, {
4485
+ version: "1.2",
4486
+ schema: "core",
4487
+ uniqueKeys: true,
4488
+ logLevel: "silent"
4489
+ });
4490
+ const problem = doc.errors[0] ?? (opts.tolerateUnknownTags ? void 0 : doc.warnings[0]);
4491
+ if (problem) throw new Error(`${opts.what}: ${problem.message.split("\n")[0]}`);
4492
+ return doc.toJS({ maxAliasCount: opts.maxAliasCount ?? 0 });
4493
+ }
4494
+ var OPEN = /^---[ \t]*\r?\n/;
4495
+ var CLOSE = /^(?:---|\.\.\.)[ \t]*$/;
4496
+ function parseMarkdownFrontMatter(source) {
4497
+ const open = OPEN.exec(source);
4498
+ if (!open) return { data: {}, body: source };
4499
+ const lines = source.slice(open[0].length).split(/\r?\n/);
4500
+ const closeAt = lines.findIndex((line) => CLOSE.test(line));
4501
+ if (closeAt === -1) throw new Error("front matter is not closed with ---");
4502
+ const yamlText = lines.slice(0, closeAt).join("\n");
4503
+ const body = lines.slice(closeAt + 1).join("\n");
4504
+ const parsed = parseYaml(yamlText, { what: "front matter" });
4505
+ if (parsed === null || parsed === void 0) return { data: {}, body };
4506
+ if (typeof parsed !== "object" || Array.isArray(parsed)) {
4507
+ throw new Error("front matter must be a mapping");
4508
+ }
4509
+ return { data: parsed, body };
4510
+ }
4511
+
4162
4512
  // src/markdown-adapter/load.ts
4163
4513
  var ROOT_TOPIC_ID = "general";
4164
4514
  var SUMMARY_MAX_CHARS = 280;
4165
4515
  var TOPIC_SIDECAR = "_topic.yaml";
4166
4516
  var HUGO_SECTION_PAGE = "_index";
4517
+ var DOCFX_JSON = "docfx.json";
4518
+ var WARNING_EXAMPLES2 = 20;
4167
4519
  var SECTION_PAGE_ORDINAL = -2147483648;
4168
4520
  var RESERVED_KEYS = /* @__PURE__ */ new Set(["title", "summary", "aliases", "id", "order", "subcategory"]);
4169
- function readFrontMatter(raw, file, hugo) {
4521
+ function readFrontMatter(raw, file, conventions) {
4522
+ const { hugo } = conventions;
4170
4523
  let data;
4171
4524
  let body;
4172
4525
  try {
@@ -4231,8 +4584,8 @@ function readFrontMatter(raw, file, hugo) {
4231
4584
  if (!weight.success) throw new Error(`${file}: front matter 'weight' must be an int32`);
4232
4585
  if (weight.data > 0) out.weight = weight.data;
4233
4586
  }
4234
- out.description = str("description");
4235
4587
  }
4588
+ if (conventions.description) out.description = str("description");
4236
4589
  for (const [key, value] of Object.entries(data)) {
4237
4590
  if (RESERVED_KEYS.has(key) || value === void 0) continue;
4238
4591
  out.meta[key] = value;
@@ -4261,7 +4614,7 @@ function topicIdFor(name, taken) {
4261
4614
  taken.add(id);
4262
4615
  return id;
4263
4616
  }
4264
- async function walkMarkdownFiles(root) {
4617
+ async function walkFiles(root, matches) {
4265
4618
  const out = [];
4266
4619
  const visit = async (dir) => {
4267
4620
  const entries = (await readdir(dir, { withFileTypes: true })).sort(
@@ -4271,13 +4624,20 @@ async function walkMarkdownFiles(root) {
4271
4624
  if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
4272
4625
  const abs = join6(dir, entry.name);
4273
4626
  if (entry.isDirectory()) await visit(abs);
4274
- else if (entry.isFile() && /\.(md|markdown)$/i.test(entry.name)) out.push(abs);
4627
+ else if (entry.isFile() && matches(entry.name)) out.push(abs);
4275
4628
  }
4276
4629
  };
4277
4630
  await visit(root);
4278
4631
  return out;
4279
4632
  }
4280
- function isRecord2(value) {
4633
+ function walkMarkdownFiles(root) {
4634
+ return walkFiles(root, (name) => /\.(md|markdown)$/i.test(name));
4635
+ }
4636
+ function warnCapped(warn, items, each, rest) {
4637
+ for (const item of items.slice(0, WARNING_EXAMPLES2)) warn(each(item));
4638
+ if (items.length > WARNING_EXAMPLES2) warn(rest(items.length - WARNING_EXAMPLES2));
4639
+ }
4640
+ function isRecord3(value) {
4281
4641
  return typeof value === "object" && value !== null && !Array.isArray(value);
4282
4642
  }
4283
4643
  async function readTopicSidecar(dir) {
@@ -4286,7 +4646,7 @@ async function readTopicSidecar(dir) {
4286
4646
  const raw = (await readFile3(path, "utf8")).replace(/^\uFEFF/, "");
4287
4647
  const data = parseYaml(raw, { what: path });
4288
4648
  if (data === null || data === void 0) return {};
4289
- if (!isRecord2(data)) throw new Error(`${path}: must be a mapping`);
4649
+ if (!isRecord3(data)) throw new Error(`${path}: must be a mapping`);
4290
4650
  const out = {};
4291
4651
  if (typeof data.name === "string" && data.name.trim()) out.name = data.name.trim();
4292
4652
  if (typeof data.description === "string" && data.description.trim()) {
@@ -4320,7 +4680,7 @@ async function readMkdocsDocsDir(mkdocsPath) {
4320
4680
  tolerateUnknownTags: true,
4321
4681
  maxAliasCount: 100
4322
4682
  });
4323
- const docsDir = isRecord2(config) && typeof config.docs_dir === "string" ? config.docs_dir : "docs";
4683
+ const docsDir = isRecord3(config) && typeof config.docs_dir === "string" ? config.docs_dir : "docs";
4324
4684
  return resolve4(dirname3(mkdocsPath), docsDir);
4325
4685
  }
4326
4686
  async function detectTableOfContents(rootDir, projectDir = rootDir) {
@@ -4335,6 +4695,10 @@ async function detectTableOfContents(rootDir, projectDir = rootDir) {
4335
4695
  ])
4336
4696
  );
4337
4697
  if (mkdocs) return { format: "mkdocs", path: mkdocs };
4698
+ const docfx = firstExisting(
4699
+ [DOCFX_JSON, "toc.yml", "TOC.yml", "toc.yaml"].map((name) => join6(rootDir, name))
4700
+ );
4701
+ if (docfx) return { format: "docfx" };
4338
4702
  const files = await walkMarkdownFiles(rootDir);
4339
4703
  if (files.some((file) => basename(file).replace(/\.(md|markdown)$/i, "") === HUGO_SECTION_PAGE)) {
4340
4704
  return { format: "hugo" };
@@ -4354,6 +4718,7 @@ async function loadOutline(rootDir, toc, files) {
4354
4718
  if (explicit && !existsSync(explicit)) {
4355
4719
  throw new Error(`${toc.format} table of contents not found: ${explicit}`);
4356
4720
  }
4721
+ if (toc.format === "docfx") return loadDocfxOutline(rootDir, explicit, files);
4357
4722
  if (toc.format === "gitbook") {
4358
4723
  const path2 = explicit ?? join6(rootDir, "SUMMARY.md");
4359
4724
  const rel = insideRoot(rootDir, path2);
@@ -4396,16 +4761,68 @@ async function loadOutline(rootDir, toc, files) {
4396
4761
  });
4397
4762
  return { outline: parseJupyterBookToc(doc, tocDir, files, basename(path)), path };
4398
4763
  }
4764
+ async function loadDocfxOutline(rootDir, explicit, files) {
4765
+ const configPath = join6(rootDir, DOCFX_JSON);
4766
+ let project;
4767
+ if (existsSync(configPath)) {
4768
+ let config;
4769
+ try {
4770
+ config = JSON.parse(await readOutlineText(configPath));
4771
+ } catch (error) {
4772
+ throw new Error(`${DOCFX_JSON}: ${error instanceof Error ? error.message : String(error)}`);
4773
+ }
4774
+ project = parseDocfxJson(config, DOCFX_JSON);
4775
+ }
4776
+ const entry = explicit === void 0 ? void 0 : insideRoot(rootDir, explicit);
4777
+ if (entry === null) {
4778
+ throw new Error(`${basename(explicit)} must live inside the content root ${rootDir}`);
4779
+ }
4780
+ const readToc = async (abs, rel) => parseYaml(await readOutlineText(abs), {
4781
+ what: rel,
4782
+ maxBytes: OUTLINE_MAX_BYTES,
4783
+ tolerateUnknownTags: true,
4784
+ maxAliasCount: 100
4785
+ });
4786
+ const tocs = /* @__PURE__ */ new Map();
4787
+ const warnings = [];
4788
+ for (const abs of await walkFiles(rootDir, (name) => /^toc\.ya?ml$/i.test(name))) {
4789
+ const rel = insideRoot(rootDir, abs);
4790
+ try {
4791
+ tocs.set(rel, await readToc(abs, rel));
4792
+ } catch (error) {
4793
+ if (rel === entry) throw error;
4794
+ warnings.push(`${rel}: ${error instanceof Error ? error.message : String(error)}; skipped`);
4795
+ }
4796
+ }
4797
+ if (entry !== void 0 && explicit !== void 0 && !tocs.has(entry)) {
4798
+ tocs.set(entry, await readToc(explicit, entry));
4799
+ }
4800
+ const publishes = project ? (file) => docfxPublishes(project, file) : void 0;
4801
+ const outline = parseDocfxToc({
4802
+ tocs,
4803
+ files: publishes ? files.filter(publishes) : files,
4804
+ ...project ? { project } : {},
4805
+ ...entry !== void 0 ? { entry } : {}
4806
+ });
4807
+ outline.warnings.unshift(...warnings);
4808
+ const path = outline.entry ? join6(rootDir, ...outline.entry.split("/")) : void 0;
4809
+ return {
4810
+ outline,
4811
+ ...path ? { path } : project ? { path: configPath } : {},
4812
+ ...publishes ? { publishes } : {}
4813
+ };
4814
+ }
4399
4815
  var INLINE_LINK = /(!?)\[([^\]]*)\]\(\s*(<[^>]*>|[^)\s]+)((?:\s+"[^"]*")?)\s*\)/g;
4400
- var HAS_SCHEME2 = /^[a-z][a-z0-9+.-]*:/i;
4816
+ var HAS_SCHEME3 = /^[a-z][a-z0-9+.-]*:/i;
4401
4817
  function resolveInTree(ctx, target) {
4402
- const resolved = posix2.normalize(posix2.join(ctx.docDir, target));
4403
- if (resolved === ".." || resolved.startsWith("../") || posix2.isAbsolute(resolved)) return null;
4818
+ const fromRoot = ctx.tildeIsRoot && target.startsWith("~/");
4819
+ const resolved = posix3.normalize(fromRoot ? target.slice(2) : posix3.join(ctx.docDir, target));
4820
+ if (resolved === ".." || resolved.startsWith("../") || posix3.isAbsolute(resolved)) return null;
4404
4821
  return resolved === "." ? "" : resolved;
4405
4822
  }
4406
4823
  function rewriteTarget(ctx, isImage, rawTarget) {
4407
4824
  const target = rawTarget.startsWith("<") ? rawTarget.slice(1, -1) : rawTarget;
4408
- if (target === "" || HAS_SCHEME2.test(target) || target.startsWith("//") || target.startsWith("#") || target.startsWith("/")) {
4825
+ if (target === "" || HAS_SCHEME3.test(target) || target.startsWith("//") || target.startsWith("#") || target.startsWith("/")) {
4409
4826
  return null;
4410
4827
  }
4411
4828
  const hashAt = target.search(/[#?]/);
@@ -4479,11 +4896,18 @@ async function loadMarkdownCatalog(rootDir, opts) {
4479
4896
  });
4480
4897
  const toc = opts.toc ?? { format: "folders" };
4481
4898
  const hugo = toc.format === "hugo";
4899
+ const docfx = toc.format === "docfx";
4900
+ const conventions = { hugo, description: hugo || docfx };
4482
4901
  const ignore = new Set(opts.ignore ?? []);
4483
4902
  const relOf = (abs) => relative3(rootDir, abs).split(sep).join("/");
4484
4903
  let files = (await walkMarkdownFiles(rootDir)).filter((abs) => !ignore.has(relOf(abs)));
4485
- const { outline, path: outlinePath } = await loadOutline(rootDir, toc, files.map(relOf));
4904
+ const {
4905
+ outline,
4906
+ path: outlinePath,
4907
+ publishes
4908
+ } = await loadOutline(rootDir, toc, files.map(relOf));
4486
4909
  for (const message of outline?.warnings ?? []) warn(message);
4910
+ if (publishes) files = files.filter((abs) => publishes(relOf(abs)));
4487
4911
  if (outline) {
4488
4912
  const consumed = new Set(outline.consumed.map((file) => file.normalize("NFC")));
4489
4913
  files = files.filter((abs) => !consumed.has(relOf(abs).normalize("NFC")));
@@ -4531,29 +4955,33 @@ async function loadMarkdownCatalog(rootDir, opts) {
4531
4955
  };
4532
4956
  const placements = /* @__PURE__ */ new Map();
4533
4957
  if (outline) {
4958
+ const duplicates = [];
4534
4959
  const walk = (topic, chain) => {
4535
4960
  for (const entry of topic.entries) {
4536
4961
  const key = entry.file.normalize("NFC");
4537
- if (placements.has(key)) {
4538
- warn(
4539
- `${entry.file}: listed more than once in the table of contents; the first place wins`
4540
- );
4541
- } else {
4542
- placements.set(key, { chain, entry });
4543
- }
4962
+ if (placements.has(key)) duplicates.push(entry.file);
4963
+ else placements.set(key, { chain, entry });
4544
4964
  }
4545
4965
  for (const child of topic.children) walk(child, [...chain, child]);
4546
4966
  };
4547
4967
  walk(outline.root, []);
4968
+ warnCapped(
4969
+ warn,
4970
+ duplicates,
4971
+ (file) => `${file}: listed more than once in the table of contents; the first place wins`,
4972
+ (more) => `${more} more files are listed more than once in the table of contents`
4973
+ );
4548
4974
  }
4549
4975
  const outlineTopicIds = /* @__PURE__ */ new Map();
4976
+ let outlineTooDeep = false;
4550
4977
  const ensureOutlineChain = (chain) => {
4551
4978
  if (chain.length === 0) {
4552
4979
  rootTopicUsed = true;
4553
4980
  return [rootTopicId];
4554
4981
  }
4982
+ if (chain.length > MAX_KNOWLEDGE_TOPIC_DEPTH2 - 1) outlineTooDeep = true;
4555
4983
  const ids = [];
4556
- for (const node of chain) {
4984
+ for (const node of chain.slice(0, MAX_KNOWLEDGE_TOPIC_DEPTH2 - 1)) {
4557
4985
  let id = outlineTopicIds.get(node);
4558
4986
  if (!id) {
4559
4987
  id = topicIdFor(node.name, takenTopicIds);
@@ -4594,12 +5022,13 @@ async function loadMarkdownCatalog(rootDir, opts) {
4594
5022
  const fileById = /* @__PURE__ */ new Map();
4595
5023
  const idByRel = /* @__PURE__ */ new Map();
4596
5024
  const seenRel = /* @__PURE__ */ new Set();
5025
+ const unlisted = [];
4597
5026
  for (const abs of files) {
4598
5027
  const rel = relOf(abs);
4599
5028
  const relDir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
4600
5029
  const relNoExt = rel.replace(/\.(md|markdown)$/i, "").normalize("NFC");
4601
5030
  const raw = (await readFile3(abs, "utf8")).replace(/^\uFEFF/, "");
4602
- const fm = readFrontMatter(raw, rel, hugo);
5031
+ const fm = readFrontMatter(raw, rel, conventions);
4603
5032
  if (fm.unpublished) {
4604
5033
  warn(`${rel}: skipped, ${fm.unpublished} page`);
4605
5034
  continue;
@@ -4613,7 +5042,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
4613
5042
  fileById.set(id, rel);
4614
5043
  idByRel.set(relNoExt, id);
4615
5044
  const stem2 = rel.slice(rel.lastIndexOf("/") + 1).replace(/\.(md|markdown)$/i, "");
4616
- let title = fm.title ?? firstHeading(fm.body) ?? stem2;
5045
+ let title = docfx ? firstHeading(fm.body) ?? fm.title ?? stem2 : fm.title ?? firstHeading(fm.body) ?? stem2;
4617
5046
  let ordinal = fm.order;
4618
5047
  let topicPath;
4619
5048
  const placement = placements.get(rel.normalize("NFC"));
@@ -4622,8 +5051,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
4622
5051
  if (placement.entry.title) title = placement.entry.title;
4623
5052
  if (placement.entry.order !== void 0) ordinal = placement.entry.order;
4624
5053
  } else {
4625
- if (outline)
4626
- warn(`${rel}: not in the ${outline.format} table of contents; filed under its folder`);
5054
+ if (outline) unlisted.push(rel);
4627
5055
  topicPath = await ensureTopicChain(relDir);
4628
5056
  if (hugo && ordinal === void 0) ordinal = fm.weight;
4629
5057
  }
@@ -4647,7 +5075,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
4647
5075
  const parentId = topicPath[topicPath.length - 1];
4648
5076
  topicPath = [...topicPath, ensureShelf(parentId, fm.subcategory, rel)];
4649
5077
  }
4650
- const summary = fm.summary ?? (hugo ? fm.description : void 0) ?? firstParagraph(fm.body);
5078
+ const summary = fm.summary ?? fm.description ?? firstParagraph(fm.body);
4651
5079
  loaded.push({
4652
5080
  rel,
4653
5081
  file: rel,
@@ -4679,12 +5107,22 @@ async function loadMarkdownCatalog(rootDir, opts) {
4679
5107
  }
4680
5108
  };
4681
5109
  nameFromPages(outline.root);
4682
- for (const [file, placement] of placements) {
4683
- if (!seenRel.has(file)) {
4684
- warn(
4685
- `${placement.entry.file}: named by the table of contents but not found among the Markdown files`
4686
- );
4687
- }
5110
+ warnCapped(
5111
+ warn,
5112
+ unlisted,
5113
+ (file) => `${file}: not in the ${outline.format} table of contents; filed under its folder`,
5114
+ (more) => `${more} more files are not in the ${outline.format} table of contents; filed under their folders`
5115
+ );
5116
+ warnCapped(
5117
+ warn,
5118
+ [...placements].filter(([file]) => !seenRel.has(file)).map(([, p]) => p.entry.file),
5119
+ (file) => `${file}: named by the table of contents but not found among the Markdown files`,
5120
+ (more) => `${more} more files named by the table of contents are not among the Markdown files`
5121
+ );
5122
+ if (outlineTooDeep) {
5123
+ warn(
5124
+ `the table of contents nests deeper than ${MAX_KNOWLEDGE_TOPIC_DEPTH2 - 1} levels; deeper sections are folded into their ancestors`
5125
+ );
4688
5126
  }
4689
5127
  }
4690
5128
  if (rootTopicUsed) {
@@ -4702,6 +5140,7 @@ async function loadMarkdownCatalog(rootDir, opts) {
4702
5140
  }
4703
5141
  const assets = /* @__PURE__ */ new Map();
4704
5142
  const documents = [];
5143
+ const linkWarnings = [];
4705
5144
  for (const entry of loaded) {
4706
5145
  const ctx = {
4707
5146
  rootDir,
@@ -4710,8 +5149,11 @@ async function loadMarkdownCatalog(rootDir, opts) {
4710
5149
  idByRel,
4711
5150
  uri: opts.uri,
4712
5151
  assets,
4713
- missingAssets: opts.missingAssets ?? "error",
4714
- warn
5152
+ // A docfx docset draws on dependent repositories (`~/reusable-content`)
5153
+ // that a checkout never holds, so a missing image is expected there.
5154
+ missingAssets: opts.missingAssets ?? (docfx ? "warn" : "error"),
5155
+ tildeIsRoot: docfx,
5156
+ warn: (message) => linkWarnings.push(message)
4715
5157
  };
4716
5158
  documents.push(
4717
5159
  CatalogDocumentSchema.parse({
@@ -4720,6 +5162,12 @@ async function loadMarkdownCatalog(rootDir, opts) {
4720
5162
  })
4721
5163
  );
4722
5164
  }
5165
+ warnCapped(
5166
+ warn,
5167
+ linkWarnings,
5168
+ (message) => message,
5169
+ (more) => `${more} more link and image warnings`
5170
+ );
4723
5171
  return {
4724
5172
  topics,
4725
5173
  documents,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bendyline/gezel-knowledge",
3
- "version": "1.2.1",
3
+ "version": "1.2.2",
4
4
  "description": "Gezel knowledge catalogs: the .gezk compiler, archive safety, read-only reader, routing, and signatures.",
5
5
  "license": "MIT",
6
6
  "keywords": [