@moxn/kb-migrate 0.4.38 → 0.4.40

package/dist/client.d.ts

@@ -1,6 +1,7 @@
 /**
  * API client for Moxn KB
  */
+/// <reference types="node" resolution-mode="require"/>
 import type { ExtractedDocument, MigrationOptions, MigrationResult, DocumentListItem, DocumentDetail, ExportOptions } from './types.js';
 import type { DateFilter } from './date-filter.js';
 /**
@@ -27,6 +28,11 @@ export interface ImportMarkdownResult {
     name?: string;
     /** True when a front-matter block was present but NOT applied (no name → body-only import). */
     frontMatterIgnored?: boolean;
+    /**
+     * Set when strict YAML parsing of the front-matter block failed, even if the
+     * lenient fallback recovered the name. Carries the js-yaml error message.
+     */
+    frontMatterError?: string;
 }
 export declare class MoxnClient {
     private apiUrl;

package/dist/import-local.js

@@ -100,13 +100,16 @@ export async function runLocalGrammarMigration(source, options) {
     const client = new MoxnClient(options);
     let processed = 0;
     let consecutiveFailures = 0;
+    let fmIgnoredOrDegraded = 0;
     const MAX_CONSECUTIVE_FAILURES = 10;
     for await (const file of source.extractGrammarFiles()) {
         processed++;
         const progress = totalCount ? ` (${processed}/${totalCount})` : '';
         console.log(`Processing: ${file.sourcePath}${progress}`);
-        const result = await migrateGrammarFile(client, file, options);
+        const { result, hadFmWarning } = await migrateGrammarFile(client, file, options);
         results.push(result);
+        if (hadFmWarning)
+            fmIgnoredOrDegraded++;
         if (result.status === 'failed') {
             consecutiveFailures++;
         }
@@ -138,6 +141,7 @@ export async function runLocalGrammarMigration(source, options) {
         skipped: results.filter((r) => r.status === 'skipped').length,
         failed: results.filter((r) => r.status === 'failed').length,
         duration: Date.now() - startTime,
+        ...(fmIgnoredOrDegraded > 0 ? { fmIgnoredOrDegraded } : {}),
     };
     return {
         timestamp: new Date().toISOString(),
@@ -155,10 +159,13 @@ async function migrateGrammarFile(client, file, options) {
     const documentPath = joinKbPath(options.basePath, file.kbPath);
     if (options.dryRun) {
         return {
-            sourcePath: file.sourcePath,
-            documentPath,
-            status: 'skipped',
-            duration: Date.now() - startTime,
+            result: {
+                sourcePath: file.sourcePath,
+                documentPath,
+                status: 'skipped',
+                duration: Date.now() - startTime,
+            },
+            hadFmWarning: false,
         };
     }
     try {
@@ -175,11 +182,18 @@ async function migrateGrammarFile(client, file, options) {
             onConflict: options.onConflict,
         });
         // Surface a non-fatal warning when the file carried a front-matter block
-        // that wasn't applied (no `name` → body-only import): tags/description/etc.
-        // declared in it were ignored.
+        // that wasn't applied (no `name` → body-only import), OR when strict YAML
+        // parsing failed (even if the lenient fallback recovered the name, some
+        // metadata like tags/properties may have been lost).
+        let hadFmWarning = false;
         if (res.frontMatterIgnored) {
+            hadFmWarning = true;
             console.warn(`  ⚠ front-matter present but not applied (no \`name\`) — imported body only: ${file.sourcePath}`);
         }
+        else if (res.frontMatterError) {
+            hadFmWarning = true;
+            console.warn(`  ⚠ front-matter YAML parse error (tags/properties may be missing): ${res.frontMatterError} — ${file.sourcePath}`);
+        }
         // Map import_markdown outcome → migration status.
         const status = res.outcome === 'created'
             ? 'created'
@@ -187,20 +201,26 @@ async function migrateGrammarFile(client, file, options) {
                 ? 'updated'
                 : 'skipped';
         return {
-            sourcePath: file.sourcePath,
-            documentPath: res.path || documentPath,
-            status,
-            documentId: res.id,
-            duration: Date.now() - startTime,
+            result: {
+                sourcePath: file.sourcePath,
+                documentPath: res.path || documentPath,
+                status,
+                documentId: res.id,
+                duration: Date.now() - startTime,
+            },
+            hadFmWarning,
         };
     }
     catch (error) {
         return {
-            sourcePath: file.sourcePath,
-            documentPath,
-            status: 'failed',
-            error: error instanceof Error ? error.message : 'Unknown error',
-            duration: Date.now() - startTime,
+            result: {
+                sourcePath: file.sourcePath,
+                documentPath,
+                status: 'failed',
+                error: error instanceof Error ? error.message : 'Unknown error',
+                duration: Date.now() - startTime,
+            },
+            hadFmWarning: false,
         };
     }
 }

package/dist/import-local.test.js

@@ -1,5 +1,9 @@
-import { describe, it, expect } from 'vitest';
-import { joinKbPath } from './import-local.js';
+import { describe, it, expect, vi, afterEach, beforeEach, } from 'vitest';
+import { joinKbPath, runLocalGrammarMigration } from './import-local.js';
+// Mock fs/promises at module level so readFile is consistently stubable.
+vi.mock('fs/promises', () => ({
+    readFile: vi.fn().mockResolvedValue('---\nname: test-doc\n---\n\n## Body\n\ncontent'),
+}));
 describe('joinKbPath', () => {
     it('prefixes the relative KB path under a base path', () => {
         expect(joinKbPath('/imported', 'subdir/doc')).toBe('/imported/subdir/doc');
@@ -17,3 +21,99 @@ describe('joinKbPath', () => {
         expect(joinKbPath('base', 'doc')).toBe('/base/doc');
     });
 });
+// ─────────────────────────────────────────────────────────────────────────────
+// FM warning + summary count tests
+// ─────────────────────────────────────────────────────────────────────────────
+const BASE_OPTIONS = {
+    apiUrl: 'http://test-api',
+    apiKey: 'test-key',
+    basePath: '/imported',
+    onConflict: 'update',
+    dryRun: false,
+};
+function mockResponse(status, body) {
+    return {
+        ok: status >= 200 && status < 300,
+        status,
+        json: async () => body,
+    };
+}
+function fakeSource(kbPath = 'my-doc.md') {
+    return {
+        sourceType: 'local',
+        sourceLocation: '/fake',
+        validate: async () => { },
+        getDocumentCount: async () => 1,
+        async *extractGrammarFiles() {
+            yield {
+                fullPath: '/fake/my-doc.md',
+                sourcePath: 'my-doc.md',
+                kbPath,
+            };
+        },
+    };
+}
+describe('runLocalGrammarMigration — FM warning surface + summary count', () => {
+    let warnSpy;
+    let logSpy;
+    let fetchSpy;
+    beforeEach(() => {
+        warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        logSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
+        fetchSpy = vi.spyOn(globalThis, 'fetch');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('includes frontMatterError text in the console warning when server returns it', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-1',
+                path: '/imported/test',
+                outcome: 'created',
+                existed: false,
+                name: 'test',
+                frontMatterIgnored: false,
+                frontMatterError: 'strict YAML parse failed (bad indentation of a mapping entry); recovered name/description via lenient fallback',
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), BASE_OPTIONS);
+        // Warning must be emitted and include the frontMatterError message
+        expect(warnSpy).toHaveBeenCalledOnce();
+        const warnMsg = String(warnSpy.mock.calls[0][0]);
+        expect(warnMsg).toMatch(/YAML parse error|frontMatterError|bad indentation/i);
+        // Summary must carry the count
+        expect(log.summary.fmIgnoredOrDegraded).toBe(1);
+        void logSpy; // suppress unused warning
+    });
+    it('includes frontMatterIgnored warning when server returns frontMatterIgnored (no frontMatterError)', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-2',
+                path: '/imported/my-doc',
+                outcome: 'created',
+                existed: false,
+                name: 'my-doc',
+                frontMatterIgnored: true,
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), BASE_OPTIONS);
+        expect(warnSpy).toHaveBeenCalledOnce();
+        expect(log.summary.fmIgnoredOrDegraded).toBe(1);
+    });
+    it('fmIgnoredOrDegraded is absent from summary when no FM issues occurred', async () => {
+        fetchSpy.mockResolvedValue(mockResponse(200, {
+            result: {
+                id: 'doc-3',
+                path: '/imported/clean',
+                outcome: 'created',
+                existed: false,
+                name: 'clean',
+                frontMatterIgnored: false,
+            },
+        }));
+        const log = await runLocalGrammarMigration(fakeSource(), BASE_OPTIONS);
+        expect(warnSpy).not.toHaveBeenCalled();
+        expect(log.summary.fmIgnoredOrDegraded).toBeUndefined();
+    });
+});

package/dist/index.js

@@ -142,6 +142,9 @@ function printSummary(log) {
     console.log(`Updated: ${log.summary.updated}`);
     console.log(`Skipped: ${log.summary.skipped}`);
     console.log(`Failed:  ${log.summary.failed}`);
+    if (log.summary.fmIgnoredOrDegraded) {
+        console.log(`FM ignored: ${log.summary.fmIgnoredOrDegraded} (see warnings above)`);
+    }
     if (log.options.dryRun) {
         console.log('\n(Dry run - no changes made)');
     }

package/dist/sources/local.js

@@ -7,7 +7,9 @@ import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import * as path from 'path';
 import { glob } from 'glob';
-import { unified } from 'unified';
+// unified@9 is CJS with a default-function export — a named import fails both
+// tsc (TS2595 under esModuleInterop) and runtime ESM loading under tsx.
+import unified from 'unified';
 import remarkParse from 'remark-parse';
 import { MigrationSource } from './base.js';
 /**

package/dist/sources/notion-blocks.js

@@ -323,7 +323,7 @@ function convertImage(block) {
                 blockType: 'image',
                 type: 'url',
                 url: img.image.external.url,
-                mediaType: 'image/png', // Generic — Moxn will detect actual type
+                mediaType: 'image/png',
                 alt: caption || undefined,
             },
         ];

package/dist/sources/notion.d.ts

@@ -150,7 +150,7 @@ export declare function slugify(title: string): string;
  * so a second same-titled sibling was rejected by that assert (audit finding D).
  * Mutates `siblingSlugCounts` (keyed on the BASE slug) the way the builder expects.
  */
-export declare function disambiguateSibling(title: string, siblingSlugCounts: Map<string, number>): {
+export declare function disambiguateSibling(title: string, siblingSlugCounts: Map<string, number>, slugifyFn?: (s: string) => string): {
     name: string;
     slug: string;
 };

package/dist/sources/notion.js

@@ -13,7 +13,7 @@ import { blocksToSections, getPageTitle, normalizeId, } from './notion-blocks.js
 import { NotionMediaDownloader } from './notion-media.js';
 import { parseDatabaseSchema, parseEntryValues, renderPropertiesSection, } from './notion-databases.js';
 import { resolveNotionReferences } from './notion-references.js';
-const MAX_DOCUMENT_COUNT = 10_000;
+const MAX_DOCUMENT_COUNT = 10000;
 // ============================================
 // Source
 // ============================================
@@ -632,12 +632,12 @@ export function slugify(title) {
  * so a second same-titled sibling was rejected by that assert (audit finding D).
  * Mutates `siblingSlugCounts` (keyed on the BASE slug) the way the builder expects.
  */
-export function disambiguateSibling(title, siblingSlugCounts) {
-    const baseSlug = slugify(title);
+export function disambiguateSibling(title, siblingSlugCounts, slugifyFn = slugify) {
+    const baseSlug = slugifyFn(title);
     const existing = siblingSlugCounts.get(baseSlug) ?? 0;
     siblingSlugCounts.set(baseSlug, existing + 1);
     if (existing === 0)
         return { name: title, slug: baseSlug };
     const name = `${title} ${existing + 1}`;
-    return { name, slug: slugify(name) };
+    return { name, slug: slugifyFn(name) };
 }

package/dist/sources/notion.test.js

@@ -68,3 +68,16 @@ describe('disambiguateSibling (D — dedup name AND path together)', () => {
         expect(disambiguateSibling('Beta', counts).slug).toBe('beta');
     });
 });
+describe('disambiguateSibling — custom slugify (OneNote uses slugifyPathSegment)', () => {
+    const upperSlug = (s) => s.toUpperCase().replace(/ /g, '_');
+    it('derives the slug with the provided function, keeping the bijection', () => {
+        const counts = new Map();
+        expect(disambiguateSibling('My Page', counts, upperSlug)).toEqual({
+            name: 'My Page',
+            slug: 'MY_PAGE',
+        });
+        const second = disambiguateSibling('My Page', counts, upperSlug);
+        expect(second).toEqual({ name: 'My Page 2', slug: 'MY_PAGE_2' });
+        expect(upperSlug(second.name)).toBe(second.slug);
+    });
+});

package/dist/sources/onenote/onenote-api.d.ts

@@ -6,6 +6,7 @@
  * are simple enough that a hand-rolled client is cheaper than the SDK and
  * gives us precise control over 429 handling.
  */
+/// <reference types="node" resolution-mode="require"/>
 import type { OneNoteNotebook, OneNotePage, OneNoteSection, OneNoteSectionGroup } from './types.js';
 export interface OneNoteApiClientOptions {
     /** Alternate base URL — for testing only. */

package/dist/sources/onenote/onenote-tree.js

@@ -11,6 +11,7 @@
  * own ID or any ancestor's ID is in the set. If the set is empty, every
  * page is included.
  */
+import { disambiguateSibling } from '../notion.js';
 const MAX_GROUP_DEPTH = 4;
 /**
  * Normalize any human text into a ltree-safe slug segment.
@@ -96,12 +97,22 @@ async function walkSection(client, section, pathSegs, ctx, ancestorSelected, sel
         createdBefore: opts.createdBefore,
     });
     const sectionSeg = slugifyPathSegment(section.displayName);
+    // Dedup same-titled sibling pages within a section — suffix the title AND the
+    // path segment together so slugify(name) === pathTail (the server's hard
+    // bijection assert) and two pages never collide on one path. Without this,
+    // two "Untitled" pages produce the same kbPath → the second silently clobbers
+    // or skips the first on import. (Notion finding D; OneNote had no dedup at all.)
+    const pageSlugCounts = new Map();
     for (const page of pages) {
         const pageSelected = ancestorSelected || (!!sel && sel.has(page.id));
         if (!pageSelected)
             continue;
-        const pageSeg = slugifyPathSegment(page.title ?? 'untitled');
-        out.push(toDiscovered(page, section, [...pathSegs, sectionSeg, pageSeg], ctx));
+        const { name: dedupTitle, slug: pageSeg } = disambiguateSibling(page.title ?? 'untitled', pageSlugCounts, slugifyPathSegment);
+        out.push(toDiscovered({ ...page, title: dedupTitle }, section, [
+            ...pathSegs,
+            sectionSeg,
+            pageSeg,
+        ], ctx));
     }
 }
 function toDiscovered(page, section, segs, ctx) {

package/dist/types.d.ts

@@ -176,6 +176,12 @@ export interface MigrationLog {
         discovered?: number;
         /** Pages skipped during extraction (empty, no content, errors). */
         skippedDuringExtraction?: number;
+        /**
+         * Number of files where front-matter was ignored (no name) or degraded
+         * (strict YAML failed but lenient fallback recovered a name). Non-zero means
+         * some files lost tags/description/properties declared in the front-matter.
+         */
+        fmIgnoredOrDegraded?: number;
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxn/kb-migrate",
-  "version": "0.4.38",
+  "version": "0.4.40",
   "description": "Migration tool for importing documents into Moxn Knowledge Base from local files, Notion, Google Docs, and more",
   "type": "module",
   "main": "dist/index.js",