@nutin/cli 2.1.1 → 3.0.0

package/templates/features/markdown/src/app/markdown/markdown-guards.test.js.hbs

@@ -0,0 +1,63 @@
+import { MarkdownGuards } from '#root/dist/src/app/markdown/markdown-guards.js';
+import { MarkdownManifestsService } from '#root/dist/src/app/markdown/markdown-manifests.service.js';
+
+const PAGES = { a: { slug: 'a', section: 'api' }, b: { slug: 'b', section: 'tools' } };
+const SECTIONS = { api: { id: 'api' }, tools: { id: 'tools' } };
+
+function fakeManifest({ hasPages = true } = {}) {
+  return {
+    hasPages,
+    firstSlug: hasPages ? 'a' : undefined,
+    getPage: (slug) => (hasPages ? PAGES[slug] : undefined),
+    getSection: (id) => (hasPages ? SECTIONS[id] : undefined),
+  };
+}
+
+describe('MarkdownGuards', () => {
+  let loadSpy;
+  let manifest;
+
+  beforeEach(() => {
+    manifest = fakeManifest();
+    loadSpy = spyOn(MarkdownManifestsService, 'load').andCallFake(() => Promise.resolve(manifest));
+  });
+
+  afterEach(() => {
+    loadSpy.restore();
+  });
+
+  it('pageExists loads the manifest, then allows known slugs and the bare route', async () => {
+    const guard = MarkdownGuards.pageExists('docs');
+    expect(await guard({ slug: 'a' })).toBe(true);
+    expect(await guard({})).toBe(true);
+    expect(loadSpy.lastCall[0]).toBe('docs');
+  });
+
+  it('pageExists sends unknown slugs to /404', async () => {
+    expect(await MarkdownGuards.pageExists('docs')({ slug: 'nope' })).toBe('/404');
+  });
+
+  it('both guards let an empty or failed manifest through, for the empty or error state', async () => {
+    manifest = fakeManifest({ hasPages: false });
+    expect(await MarkdownGuards.pageExists('docs')({ slug: 'a' })).toBe(true);
+    expect(await MarkdownGuards.sectionPageExists('docs')({ section: 'api', slug: 'a' })).toBe(true);
+  });
+
+  it('sectionPageExists allows the bare route, a known section, and a page of that section', async () => {
+    const guard = MarkdownGuards.sectionPageExists('docs');
+    expect(await guard({})).toBe(true);
+    expect(await guard({ section: 'api' })).toBe(true);
+    expect(await guard({ section: 'api', slug: 'a' })).toBe(true);
+  });
+
+  it('sectionPageExists sends a page of another section, or an unknown section, to /404', async () => {
+    const guard = MarkdownGuards.sectionPageExists('docs');
+    expect(await guard({ section: 'api', slug: 'b' })).toBe('/404');
+    expect(await guard({ section: 'nope', slug: 'a' })).toBe('/404');
+    expect(await guard({ section: 'nope' })).toBe('/404');
+  });
+
+  it('sectionPageExists redirects a section-less /<id>/<slug> to the page in its section', async () => {
+    expect(await MarkdownGuards.sectionPageExists('docs')({ section: 'b' })).toBe('/docs/tools/b');
+  });
+});

package/templates/features/markdown/src/app/markdown/markdown-guards.ts.hbs

@@ -0,0 +1,31 @@
+import { MarkdownManifestsService } from './markdown-manifests.service.js';
+
+// Both guards load the source's manifest (once) before the page renders.
+export const MarkdownGuards = {
+  // For '/<id>/:slug?' routes. A bare '/<id>' renders the first page.
+  pageExists: (id: string): Nutin.RouteGuard => {
+    return async (params) => {
+      const manifest = await MarkdownManifestsService.load(id);
+      if (!manifest.hasPages) return true;
+      const slug = params.slug || manifest.firstSlug;
+      return (!!slug && !!manifest.getPage(slug)) || '/404';
+    };
+  },
+
+  // For '/<id>/:section?/:slug?' routes ("sectionInPath: true").
+  // A bare '/<id>/<slug>' redirects to that page's section.
+  sectionPageExists: (id: string): Nutin.RouteGuard => {
+    return async (params) => {
+      const manifest = await MarkdownManifestsService.load(id);
+      if (!manifest.hasPages || !params.section) return true;
+
+      if (manifest.getSection(params.section)) {
+        if (!params.slug) return true;
+        return manifest.getPage(params.slug)?.section === params.section || '/404';
+      }
+
+      const page = !params.slug ? manifest.getPage(params.section) : undefined;
+      return page ? `/${id}/${page.section}/${page.slug}` : '/404';
+    };
+  },
+};

package/templates/features/markdown/src/app/markdown/markdown-i18n.test.js.hbs

@@ -0,0 +1,78 @@
+import nutinConfig from '#root/dist/nutin.config.js';
+import { I18nService } from '#root/dist/src/core/index.js';
+import { markdownLanguage, markdownText, onMarkdownLanguageChange } from '#root/dist/src/app/markdown/markdown-i18n.js';
+
+describe('markdown-i18n', () => {
+  let hadDefine;
+  let savedDefine;
+
+  beforeEach(() => {
+    hadDefine = '__NUTIN_I18N__' in globalThis;
+    savedDefine = globalThis.__NUTIN_I18N__;
+  });
+
+  afterEach(() => {
+    if (hadDefine) globalThis.__NUTIN_I18N__ = savedDefine;
+    else delete globalThis.__NUTIN_I18N__;
+  });
+
+  it('markdownLanguage returns the current language with i18n, null without', () => {
+    globalThis.__NUTIN_I18N__ = true;
+    expect(markdownLanguage()).toBe(I18nService.currentLanguage);
+    globalThis.__NUTIN_I18N__ = false;
+    expect(markdownLanguage()).toBe(null);
+  });
+
+  it('markdownLanguage follows nutin.config.js "i18n" when the builder define is missing', () => {
+    delete globalThis.__NUTIN_I18N__;
+    expect(markdownLanguage()).toBe(nutinConfig.i18n ? I18nService.currentLanguage : null);
+  });
+
+  it('markdownText translates a "markdown." key with i18n, passing the fallback', () => {
+    globalThis.__NUTIN_I18N__ = true;
+    const translateSpy = spyOn(I18nService, 'translate').andCallFake(() => 'Sommaire');
+    try {
+      expect(markdownText('toc', 'Contents')).toBe('Sommaire');
+      expect(translateSpy.lastCall).toEqual(['markdown.toc', 'Contents']);
+    } finally {
+      translateSpy.restore();
+    }
+  });
+
+  it('markdownText returns the fallback without i18n, without translating', () => {
+    globalThis.__NUTIN_I18N__ = false;
+    const translateSpy = spyOn(I18nService, 'translate');
+    try {
+      expect(markdownText('toc', 'Contents')).toBe('Contents');
+      expect(translateSpy.callCount).toBe(0);
+    } finally {
+      translateSpy.restore();
+    }
+  });
+
+  it('onMarkdownLanguageChange subscribes to language changes with i18n and returns their unsubscribe', () => {
+    globalThis.__NUTIN_I18N__ = true;
+    const unsubscribe = () => {};
+    const callback = () => {};
+    const subscribeSpy = spyOn(I18nService, 'onLanguageChange').andCallFake(() => unsubscribe);
+    try {
+      expect(onMarkdownLanguageChange(callback)).toBe(unsubscribe);
+      expect(subscribeSpy.lastCall).toEqual([callback]);
+    } finally {
+      subscribeSpy.restore();
+    }
+  });
+
+  it('onMarkdownLanguageChange returns a no-op without i18n, without subscribing', () => {
+    globalThis.__NUTIN_I18N__ = false;
+    const subscribeSpy = spyOn(I18nService, 'onLanguageChange');
+    try {
+      const unsubscribe = onMarkdownLanguageChange(() => {});
+      expect(typeof unsubscribe).toBe('function');
+      expect(unsubscribe()).toBe(undefined);
+      expect(subscribeSpy.callCount).toBe(0);
+    } finally {
+      subscribeSpy.restore();
+    }
+  });
+});

package/templates/features/markdown/src/app/markdown/markdown-i18n.ts.hbs

@@ -0,0 +1,31 @@
+import nutinConfig from '../../../nutin.config.js';
+import { I18nService } from '../../core/index.js';
+
+// i18n hooks of the markdown feature. Each I18nService use sits behind core's guard
+// (`globalThis.__NUTIN_I18N__` is set by the builder), so bundles without i18n drop it.
+// A block rather than an early return: esbuild only drops a constant-false block.
+
+// The current language, or null without i18n (one manifest per source then).
+export function markdownLanguage(): string | null {
+  if (globalThis.__NUTIN_I18N__ ?? nutinConfig.i18n) {
+    return I18nService.currentLanguage;
+  }
+  return null;
+}
+
+// A UI string from the "markdown" translations (src/app/markdown/locales/<lang>.json),
+// or `fallback` without i18n or without a translation.
+export function markdownText(key: string, fallback: string): string {
+  if (globalThis.__NUTIN_I18N__ ?? nutinConfig.i18n) {
+    return I18nService.translate(`markdown.${key}`, fallback);
+  }
+  return fallback;
+}
+
+// Calls `callback` after each language change; returns the unsubscribe function.
+export function onMarkdownLanguageChange(callback: () => void): () => void {
+  if (globalThis.__NUTIN_I18N__ ?? nutinConfig.i18n) {
+    return I18nService.onLanguageChange(callback);
+  }
+  return () => {};
+}

package/templates/features/markdown/src/app/markdown/markdown-manifest.test.js.hbs

@@ -0,0 +1,98 @@
+import { MarkdownManifest } from '#root/dist/src/app/markdown/markdown-manifest.js';
+
+const MANIFEST = {
+  sections: [
+    { id: 'api', title: 'API', description: '', groups: [{ id: 'views', title: 'Views', pages: ['create-a-view'] }] },
+    { id: 'tools', title: 'Tools', description: '', pages: ['builder'] },
+  ],
+  pages: {
+    'create-a-view': { slug: 'create-a-view', title: 'Create a view', section: 'api' },
+    builder: { slug: 'builder', title: 'Builder', section: 'tools' },
+  },
+};
+
+// Single-language behavior, whatever the project's i18n setting.
+const noLanguage = () => null;
+
+let originalFetch;
+let calls;
+
+function mockFetch(...responses) {
+  calls = [];
+  global.fetch = (url) => {
+    calls.push(url);
+    const response = responses.shift();
+    return Promise.resolve(response);
+  };
+}
+
+const ok = (data) => ({ ok: true, status: 200, json: () => Promise.resolve(data) });
+const notFound = () => ({ ok: false, status: 404, json: () => Promise.reject(new Error('HTTP 404')) });
+
+describe('MarkdownManifest', () => {
+  beforeEach(() => {
+    originalFetch = global.fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it('fetches /generated/<id>.json once, even with concurrent loads', async () => {
+    mockFetch(ok(MANIFEST));
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: true }, noLanguage);
+
+    await Promise.all([manifest.load(), manifest.load()]);
+    await manifest.load();
+
+    expect(calls).toEqual(['/generated/docs.json']);
+    expect(manifest.loaded).toBe(true);
+    expect(manifest.sectionInPath).toBe(true);
+  });
+
+  it('exposes pages and sections', async () => {
+    mockFetch(ok(MANIFEST));
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: true }, noLanguage);
+    await manifest.load();
+
+    expect(manifest.hasPages).toBe(true);
+    expect(manifest.firstSlug).toBe('create-a-view');
+    expect(manifest.firstSlugOf(manifest.getSection('tools'))).toBe('builder');
+    expect(manifest.getPage('builder').title).toBe('Builder');
+    expect(manifest.getPage('nope')).toBeUndefined();
+  });
+
+  it('stays empty and flags loadFailed after a failed load, and retries on the next one', async () => {
+    mockFetch(notFound(), ok(MANIFEST));
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: false }, noLanguage);
+
+    await silenceConsole('error', () => manifest.load());
+    expect(manifest.loaded).toBe(false);
+    expect(manifest.loadFailed).toBe(true);
+    expect(manifest.hasPages).toBe(false);
+    expect(manifest.firstSlug).toBeUndefined();
+
+    await manifest.load();
+    expect(calls.length).toBe(2);
+    expect(manifest.loaded).toBe(true);
+    expect(manifest.loadFailed).toBe(false);
+  });
+
+  it('with a language, fetches /generated/<id>.<lang>.json and reads the current language', async () => {
+    const page = (title) => ({ sections: [{ id: 'index', title: 'x', description: '', pages: ['a'] }], pages: { a: { slug: 'a', title, section: 'index' } } });
+    mockFetch(ok(page('Hello')), ok(page('Bonjour')));
+    let lang = 'en';
+    const manifest = new MarkdownManifest({ id: 'docs', sectionInPath: false }, () => lang);
+
+    await manifest.load();
+    lang = 'fr';
+    expect(manifest.loaded).toBe(false);
+    await manifest.load();
+
+    expect(manifest.getPage('a').title).toBe('Bonjour');
+    lang = 'en';
+    expect(manifest.getPage('a').title).toBe('Hello');
+    await manifest.load();
+    expect(calls).toEqual(['/generated/docs.en.json', '/generated/docs.fr.json']);
+  });
+});

package/templates/features/markdown/src/app/markdown/markdown-manifest.ts.hbs

@@ -0,0 +1,157 @@
+import { markdownLanguage } from './markdown-i18n.js';
+
+export interface IMarkdownHeading {
+  depth: number;
+  text: string;
+  id: string;
+}
+
+export interface IMarkdownPage {
+  slug: string;
+  title: string;
+  description: string;
+  section: string;
+  group: string | null;
+  order: number;
+  source: string;
+  headings: IMarkdownHeading[];
+  html: string;
+  ogImage?: string;
+  // With i18n: no translation exists, this is the default language's page.
+  fallback?: boolean;
+}
+
+export interface IMarkdownGroup {
+  id: string | null;
+  title: string | null;
+  pages: string[];
+}
+
+export interface IMarkdownSection {
+  id: string;
+  title: string;
+  description: string;
+  groups?: IMarkdownGroup[];
+  pages?: string[];
+}
+
+// Compiled from a folder's "landing" option: the index shown on its bare route.
+export interface IMarkdownLanding {
+  title: string;
+  description: string;
+}
+
+export interface IMarkdownSource {
+  id: string;
+  sectionInPath: boolean;
+}
+
+interface IMarkdownManifestData {
+  sections: IMarkdownSection[];
+  pages: Record<string, IMarkdownPage>;
+  landing?: IMarkdownLanding;
+}
+
+const EMPTY_MANIFEST: IMarkdownManifestData = { sections: [], pages: {} };
+
+// One compiled "markdownSources" folder (/generated/<id>.json, written at build time by
+// tools/builder/core/markdown — or /generated/<id>.<lang>.json per language with i18n, where
+// every getter reads the current language's data). Instances are owned by MarkdownManifestsService.
+export class MarkdownManifest {
+  public readonly id: string;
+  public readonly sectionInPath: boolean;
+  private readonly getLanguage: () => string | null;
+  private readonly _data = new Map<string, IMarkdownManifestData>();
+  private readonly _loading = new Map<string, Promise<void>>();
+  private readonly _failed = new Set<string>();
+
+  // getLanguage: the current language, or null without i18n (overridable for tests).
+  constructor({ id, sectionInPath }: IMarkdownSource, getLanguage: () => string | null = markdownLanguage) {
+    this.id = id;
+    this.sectionInPath = sectionInPath;
+    this.getLanguage = getLanguage;
+  }
+
+  private get lang(): string {
+    return this.getLanguage() ?? '';
+  }
+
+  private urlFor(lang: string): string {
+    return lang ? `/generated/${this.id}.${lang}.json` : `/generated/${this.id}.json`;
+  }
+
+  public get url(): string {
+    return this.urlFor(this.lang);
+  }
+
+  public get loaded(): boolean {
+    return this._data.has(this.lang);
+  }
+
+  // True when the last load for the current language failed: the manifest is empty because of
+  // an error, not because the folder has no pages.
+  public get loadFailed(): boolean {
+    return this._failed.has(this.lang);
+  }
+
+  // Fetched once per language. A failed load keeps it empty, sets loadFailed, and is retried on the next call.
+  public load(): Promise<void> {
+    const lang = this.lang;
+    let loading = this._loading.get(lang);
+    if (!loading) {
+      loading = this.fetchManifest(lang);
+      this._loading.set(lang, loading);
+    }
+    return loading;
+  }
+
+  private async fetchManifest(lang: string): Promise<void> {
+    const url = this.urlFor(lang);
+    try {
+      const response = await fetch(url);
+      if (!response.ok) throw new Error(`HTTP ${response.status}`);
+      this._data.set(lang, await response.json());
+      this._failed.delete(lang);
+    } catch (error) {
+      this._loading.delete(lang);
+      this._failed.add(lang);
+      console.error(`Markdown manifest load error (${url}):`, error);
+    }
+  }
+
+  private get data(): IMarkdownManifestData {
+    return this._data.get(this.lang) ?? EMPTY_MANIFEST;
+  }
+
+  // Set when the folder has a "landing": its bare route shows an index instead of the first page.
+  public get landing(): IMarkdownLanding | undefined {
+    return this.data.landing;
+  }
+
+  public get sections(): IMarkdownSection[] {
+    return this.data.sections;
+  }
+
+  public getPage(slug: string): IMarkdownPage | undefined {
+    return this.data.pages[slug];
+  }
+
+  public getSection(id: string): IMarkdownSection | undefined {
+    return this.data.sections.find((section) => section.id === id);
+  }
+
+  public get firstSlug(): string | undefined {
+    return this.firstSlugOf(this.data.sections[0]);
+  }
+
+  public firstSlugOf(section: IMarkdownSection | undefined): string | undefined {
+    const pages = section?.groups?.[0]?.pages ?? section?.pages;
+    return pages?.[0];
+  }
+
+  public get hasPages(): boolean {
+    return this.data.sections.some((section) =>
+      section.groups ? section.groups.some((group) => group.pages.length > 0) : (section.pages?.length ?? 0) > 0
+    );
+  }
+}

package/templates/features/markdown/src/app/markdown/markdown-manifests.service.test.js.hbs

@@ -0,0 +1,87 @@
+import nutinConfig from '#root/nutin.config.js';
+import distConfig from '#root/dist/nutin.config.js';
+import { MarkdownManifests, MarkdownManifestsService } from '#root/dist/src/app/markdown/markdown-manifests.service.js';
+import { resolveMarkdownSources } from '#root/dist/src/app/markdown/markdown-sources.js';
+
+// Builds a separate instance (the exported MarkdownManifestsService is left as it is),
+// then drops it from the registry.
+function freshManifests() {
+  MarkdownManifests.testingReset();
+  try {
+    return MarkdownManifests.getInstance();
+  } finally {
+    MarkdownManifests.testingReset();
+  }
+}
+
+describe('MarkdownManifestsService', () => {
+  let loadSpies = [];
+
+  afterEach(() => {
+    loadSpies.forEach((spy) => spy.restore());
+    loadSpies = [];
+    delete globalThis.__NUTIN_MARKDOWN_SOURCES__;
+  });
+
+  it('has one manifest per nutin.config.js "markdownSources" folder', () => {
+    const expected = resolveMarkdownSources(nutinConfig.markdownSources);
+    expect(MarkdownManifestsService.ids).toEqual(expected.map((source) => source.id));
+    expect(MarkdownManifestsService.all.map(({ id, sectionInPath }) => ({ id, sectionInPath }))).toEqual(expected);
+  });
+
+  it('returns the same manifest instance for an id', () => {
+    for (const id of MarkdownManifestsService.ids) {
+      expect(MarkdownManifestsService.get(id)).toBe(MarkdownManifestsService.get(id));
+    }
+  });
+
+  it('throws on an unknown id, listing the known ones', () => {
+    expect(() => MarkdownManifestsService.get('__unknown__')).toThrow('Unknown Markdown source "__unknown__"');
+    expect(() => MarkdownManifestsService.get('__unknown__')).toThrow(`known: ${MarkdownManifestsService.ids.join(', ')}`);
+  });
+
+  it('load() loads the manifest of an id and resolves to it', async () => {
+    const [id] = MarkdownManifestsService.ids;
+    const manifest = MarkdownManifestsService.get(id);
+    const loadSpy = spyOn(manifest, 'load').andCallFake(() => Promise.resolve());
+    loadSpies.push(loadSpy);
+    expect(await MarkdownManifestsService.load(id)).toBe(manifest);
+    expect(loadSpy.callCount).toBe(1);
+  });
+
+  it('load() rejects on an unknown id without loading anything', async () => {
+    let error;
+    try {
+      await MarkdownManifestsService.load('__unknown__');
+    } catch (e) {
+      error = e;
+    }
+    expect(error.message).toContain('Unknown Markdown source "__unknown__"');
+  });
+
+  it('loadAll() loads every manifest', async () => {
+    loadSpies = MarkdownManifestsService.all.map((manifest) => spyOn(manifest, 'load').andCallFake(() => Promise.resolve()));
+    await MarkdownManifestsService.loadAll();
+    loadSpies.forEach((spy) => expect(spy.callCount).toBe(1));
+  });
+
+  it('reads the folders from the builder define when bundled', () => {
+    globalThis.__NUTIN_MARKDOWN_SOURCES__ = JSON.stringify(['guides', { folder: 'content/api-docs/', routePrefix: 'api', sectionInPath: true }]);
+    const manifests = freshManifests();
+    expect(manifests.ids).toEqual(['guides', 'api']);
+    expect(manifests.get('api').sectionInPath).toBe(true);
+  });
+
+  it('has no manifests without "markdownSources", and says so for an unknown id', () => {
+    const saved = distConfig.markdownSources;
+    delete distConfig.markdownSources;
+    try {
+      const manifests = freshManifests();
+      expect(manifests.ids).toEqual([]);
+      expect(manifests.all).toEqual([]);
+      expect(() => manifests.get('docs')).toThrow('known: none');
+    } finally {
+      distConfig.markdownSources = saved;
+    }
+  });
+});

package/templates/features/markdown/src/app/markdown/markdown-manifests.service.ts.hbs

@@ -0,0 +1,50 @@
+import nutinConfig from '../../../nutin.config.js';
+import { Service } from '../../core/index.js';
+import { MarkdownManifest } from './markdown-manifest.js';
+import { IMarkdownSourcesConfig, MarkdownSourceEntry, resolveMarkdownSources } from './markdown-sources.js';
+
+// Every folder listed in nutin.config.js "markdownSources", by id (its routePrefix,
+// defaulting to the folder name). Manifests load on demand: MarkdownGuards load theirs
+// before a page renders; call loadAll() at startup to have them all available upfront.
+export class MarkdownManifests extends Service<MarkdownManifests> {
+  private readonly manifests = new Map<string, MarkdownManifest>();
+
+  constructor() {
+    super();
+    // Bundled builds get the folders from the builder's define; test runs on tsc output read the config itself.
+    // Used directly in `??` so esbuild folds the fallback away.
+    const sourceFolders: MarkdownSourceEntry[] = JSON.parse(globalThis.__NUTIN_MARKDOWN_SOURCES__
+      ?? JSON.stringify((nutinConfig.markdownSources as IMarkdownSourcesConfig | undefined)?.sourceFolders ?? []));
+    for (const source of resolveMarkdownSources({ sourceFolders })) {
+      this.manifests.set(source.id, new MarkdownManifest(source));
+    }
+  }
+
+  public get ids(): string[] {
+    return [...this.manifests.keys()];
+  }
+
+  public get all(): MarkdownManifest[] {
+    return [...this.manifests.values()];
+  }
+
+  public get(id: string): MarkdownManifest {
+    const manifest = this.manifests.get(id);
+    if (!manifest) {
+      throw new Error(`Unknown Markdown source "${id}" — known: ${this.ids.join(', ') || 'none'} (nutin.config.js "markdownSources")`);
+    }
+    return manifest;
+  }
+
+  public async load(id: string): Promise<MarkdownManifest> {
+    const manifest = this.get(id);
+    await manifest.load();
+    return manifest;
+  }
+
+  public async loadAll(): Promise<void> {
+    await Promise.all(this.all.map((manifest) => manifest.load()));
+  }
+}
+
+export const MarkdownManifestsService = /* @__PURE__ */ MarkdownManifests.getInstance();

package/templates/features/markdown/src/app/markdown/markdown-routes.test.js.hbs

@@ -0,0 +1,74 @@
+import { View } from '#root/dist/src/core/index.js';
+import { markdownRoutes } from '#root/dist/src/app/markdown/markdown-routes.js';
+import { MarkdownGuards } from '#root/dist/src/app/markdown/markdown-guards.js';
+import { MarkdownView } from '#root/dist/src/app/markdown/view/markdown.view.js';
+import { MarkdownManifestsService } from '#root/dist/src/app/markdown/markdown-manifests.service.js';
+
+// Swaps the configured folders for these, on the shared instance markdownRoutes() reads.
+function useSources(sources) {
+  Object.defineProperty(MarkdownManifestsService, 'all', { value: sources, configurable: true });
+}
+
+describe('markdownRoutes', () => {
+  afterEach(() => {
+    delete MarkdownManifestsService.all;
+  });
+
+  it('registers one guarded route per folder, with its section in the path when configured, lazy by default', async () => {
+    const routes = markdownRoutes();
+    const expected = MarkdownManifestsService.all.map(({ id, sectionInPath }) => (sectionInPath ? `/${id}/:section?/:slug?` : `/${id}/:slug?`));
+    expect(Object.keys(routes)).toEqual(expected);
+    for (const route of Object.values(routes)) {
+      expect(route.guards.length).toBe(1);
+      const view = route.view();
+      expect(typeof view.then).toBe('function');
+      expect(await view).toBeInstanceOf(MarkdownView);
+    }
+  });
+
+  it('builds each view with the "view" option, given the folder id', () => {
+    const ids = [];
+    class CustomView extends View {
+      constructor() { super({ viewName: 'custom' }); }
+    }
+    const routes = markdownRoutes({ view: (id) => { ids.push(id); return new CustomView(); } });
+    for (const route of Object.values(routes)) expect(route.view()).toBeInstanceOf(CustomView);
+    expect(ids).toEqual(MarkdownManifestsService.ids);
+  });
+
+  it('guards a plain folder with pageExists and a "sectionInPath" folder with sectionPageExists', () => {
+    useSources([{ id: 'guides', sectionInPath: false }, { id: 'api', sectionInPath: true }]);
+    const pageGuard = () => true;
+    const sectionGuard = () => true;
+    const pageSpy = spyOn(MarkdownGuards, 'pageExists').andCallFake(() => pageGuard);
+    const sectionSpy = spyOn(MarkdownGuards, 'sectionPageExists').andCallFake(() => sectionGuard);
+    try {
+      const routes = markdownRoutes({ view: () => new MarkdownView({ id: 'guides' }) });
+      expect(Object.keys(routes)).toEqual(['/guides/:slug?', '/api/:section?/:slug?']);
+      expect(routes['/guides/:slug?'].guards).toEqual([pageGuard]);
+      expect(routes['/api/:section?/:slug?'].guards).toEqual([sectionGuard]);
+      expect(pageSpy.calls).toEqual([['guides']]);
+      expect(sectionSpy.calls).toEqual([['api']]);
+    } finally {
+      pageSpy.restore();
+      sectionSpy.restore();
+    }
+  });
+
+  it('passes the folder id to the default lazy view, for "sectionInPath" folders too', async () => {
+    useSources([{ id: 'api', sectionInPath: true }]);
+    const getSpy = spyOn(MarkdownManifestsService, 'get').andCallFake(() => ({ id: 'api', sectionInPath: true }));
+    try {
+      const view = await markdownRoutes()['/api/:section?/:slug?'].view();
+      expect(view).toBeInstanceOf(MarkdownView);
+      expect(getSpy.lastCall).toEqual(['api']);
+    } finally {
+      getSpy.restore();
+    }
+  });
+
+  it('returns no routes without folders', () => {
+    useSources([]);
+    expect(markdownRoutes()).toEqual({});
+  });
+});