@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/discovery/docs-section-key.mjs

@@ -0,0 +1,322 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stable section keys, section lookup, and the topic index.
+ *
+ * @input Reference-doc sections, each with an optional authored `id`.
+ * @output The key a section is addressed by (its `id`, else a kebab-case key
+ *   derived from its authored title), lookup by key or title, and the compact
+ *   index a topic-only docs read returns.
+ * @position Shared by docs discovery (which rejects colliding keys before a
+ *   reader sees them), the docs leaves (index, section, detail), and Doctor
+ *   (output budgets). Imports nothing from discovery, so both can use it.
+ */
+
+/** A stable key: lowercase letters and digits, joined by single hyphens. */
+export const SECTION_KEY_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** The longest summary an index entry carries, in characters. */
+export const SECTION_SUMMARY_MAX = 240;
+
+/**
+ * A section's authored title. A `--zh`/`--dense` overlay replaces the visible
+ * title, but extensions are written against the authored one and keys derive
+ * from it, so both stay the same in every language.
+ */
+const SOURCE_TITLE = Symbol('astryx.docs.sourceTitle');
+
+/**
+ * Record the authored title of a section whose visible title a translation
+ * overlay replaces.
+ * @template {object} T
+ * @param {T} section
+ * @param {string} title
+ * @returns {T}
+ */
+export function withSourceTitle(section, title) {
+  Object.defineProperty(section, SOURCE_TITLE, {
+    value: title,
+    configurable: true,
+  });
+  return section;
+}
+
+/**
+ * @param {any} section
+ * @returns {string}
+ */
+export function sourceTitle(section) {
+  return section?.[SOURCE_TITLE] ?? section?.title;
+}
+
+/**
+ * The key a title derives: accents folded, `&` spelled out, and every other
+ * run of non-alphanumerics collapsed to one hyphen. Empty when the title has
+ * no Latin letters or digits to derive from.
+ * @param {unknown} title
+ * @returns {string}
+ */
+export function sectionTitleKey(title) {
+  if (typeof title !== 'string') return '';
+  return title
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/&/g, ' and ')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * The key a section is addressed by: its authored `id`, else the key its
+ * authored title derives.
+ * @param {any} section
+ * @returns {string}
+ */
+export function sectionKey(section) {
+  return typeof section?.id === 'string'
+    ? section.id
+    : sectionTitleKey(sourceTitle(section));
+}
+
+/**
+ * The first section the 0.6.x title-substring lookup would return for a query.
+ * @param {any[]} sections
+ * @param {string} query
+ * @returns {number}
+ */
+function legacyTitleMatchIndex(sections, query) {
+  const lower = query.toLowerCase();
+  return sections.findIndex(section => {
+    const title = sourceTitle(section);
+    return typeof title === 'string' && title.toLowerCase().includes(lower);
+  });
+}
+
+/**
+ * A name as a docs-tree route segment: lowercase words joined by hyphens, so
+ * `integrationPackCheck` and `integration pack` both read naturally.
+ * @param {string} name
+ * @returns {string}
+ */
+export function routeSegment(name) {
+  return String(name)
+    .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+/**
+ * Fatal key problems: only an explicitly authored `id` can make a previously
+ * readable topic invalid. Derived-key collisions and titles with no Latin
+ * letters or digits are handled by {@link withSectionKeys} for 0.6.x
+ * compatibility.
+ * @param {any[]} sections
+ * @returns {string[]}
+ */
+export function sectionKeyErrors(sections) {
+  /** @type {string[]} */
+  const problems = [];
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  sections.forEach((section, s) => {
+    if (section?.id == null) return;
+    const at = `sections[${s}]`;
+    if (typeof section.id !== 'string' || !SECTION_KEY_RE.test(section.id)) {
+      problems.push(
+        `${at}.id: ${JSON.stringify(section.id)} is not a stable key. Use lowercase letters and digits joined by single hyphens.`,
+      );
+      return;
+    }
+    const first = seen.get(section.id);
+    if (first != null) {
+      problems.push(
+        `${at}: the key "${section.id}" is already used by sections[${first}]. Give one of them a distinct id.`,
+      );
+      return;
+    }
+    const legacyOwner = legacyTitleMatchIndex(sections, section.id);
+    if (legacyOwner !== -1 && legacyOwner !== s) {
+      problems.push(
+        `${at}.id: the key "${section.id}" is already a legacy title query for sections[${legacyOwner}]. Choose an id that resolves to this section.`,
+      );
+      return;
+    }
+    seen.set(section.id, s);
+  });
+  return problems;
+}
+
+/**
+ * Compatibility notices for section keys. These inputs loaded in 0.6.x, so
+ * readers keep accepting them and assign deterministic fallback keys.
+ * @param {any[]} sections
+ * @returns {string[]}
+ */
+export function sectionKeyProblems(sections) {
+  /** @type {string[]} */
+  const problems = [];
+  /** @type {Map<string, number>} */
+  const seen = new Map();
+  sections.forEach((section, s) => {
+    const at = `sections[${s}]`;
+    if (
+      section?.id == null &&
+      (typeof section?.title !== 'string' || section.title === '')
+    ) {
+      return;
+    }
+    if (
+      section?.id != null &&
+      (typeof section.id !== 'string' || !SECTION_KEY_RE.test(section.id))
+    ) {
+      problems.push(
+        `${at}.id: ${JSON.stringify(section.id)} is not a stable key. Use lowercase letters and digits joined by single hyphens.`,
+      );
+      return;
+    }
+    const key = sectionKey(section);
+    if (key === '') {
+      problems.push(
+        `${at}: no key derives from the title ${JSON.stringify(section?.title)}. A deterministic section-N compatibility key is used; add an explicit id.`,
+      );
+      return;
+    }
+    const first = seen.get(key);
+    if (first != null) {
+      problems.push(
+        `${at}: the key "${key}" is already used by sections[${first}]. A suffixed compatibility key is used for title-derived collisions; give one of them a distinct id or title.`,
+      );
+      return;
+    }
+    seen.set(key, s);
+  });
+  return problems;
+}
+
+/**
+ * Stamp every section with the key it is addressed by. Runs only after
+ * extensions merge: a derived key must never take part in merge matching.
+ * @template {{sections: any[]}} T
+ * @param {T} doc
+ * @returns {T}
+ */
+export function withSectionKeys(doc) {
+  const reserved = new Set(
+    doc.sections
+      .map(section => section?.id)
+      .filter(id => typeof id === 'string' && SECTION_KEY_RE.test(id)),
+  );
+  const used = new Set();
+  return {
+    ...doc,
+    sections: doc.sections.map((section, index) => {
+      if (section.id != null) {
+        used.add(section.id);
+        return section;
+      }
+      const base =
+        sectionTitleKey(sourceTitle(section)) || `section-${index + 1}`;
+      let key = base;
+      let suffix = 2;
+      while (
+        reserved.has(key) ||
+        used.has(key) ||
+        (legacyTitleMatchIndex(doc.sections, key) !== -1 &&
+          legacyTitleMatchIndex(doc.sections, key) !== index)
+      ) {
+        key = `${base}-${suffix}`;
+        suffix += 1;
+      }
+      used.add(key);
+      return withSourceTitle({...section, id: key}, sourceTitle(section));
+    }),
+  };
+}
+
+/**
+ * Find the section a reader asked for. The 0.6.x first-match title-substring
+ * lookup remains first in the authored-title view. In a localized view, an
+ * exact stable key resolves before translated title substrings because those
+ * translations cannot participate in language-stable key allocation. Generated
+ * keys avoid authored-title conflicts, and authored IDs that would shadow an
+ * authored legacy query are rejected.
+ * @param {any[]} sections
+ * @param {string} query
+ * @returns {{section: any | null, candidates: any[]}} `candidates` lists every
+ *   legacy title match when the query is ambiguous
+ */
+export function findDocSection(sections, query) {
+  const wanted = query.trim();
+  const byKey = sections.find(section => sectionKey(section) === wanted);
+  const hasLocalizedTitles = sections.some(
+    section => sourceTitle(section) !== section.title,
+  );
+  if (byKey && hasLocalizedTitles) {
+    return {section: byKey, candidates: []};
+  }
+
+  const lower = wanted.toLowerCase();
+  const legacy = sections.filter(section =>
+    section.title.toLowerCase().includes(lower),
+  );
+  if (legacy.length > 0) {
+    return {section: legacy[0], candidates: legacy.length > 1 ? legacy : []};
+  }
+
+  const byFallbackKey = sections.find(
+    section => sectionKey(section) === wanted,
+  );
+  if (byFallbackKey) return {section: byFallbackKey, candidates: []};
+
+  const derived = sectionTitleKey(wanted);
+  const byDerivedKey = sections.find(
+    section =>
+      derived !== '' && sectionTitleKey(sourceTitle(section)) === derived,
+  );
+  return {section: byDerivedKey ?? null, candidates: []};
+}
+
+/**
+ * One line that says what a section holds: its first prose or list text,
+ * whitespace collapsed, cut at a word boundary.
+ * @param {any} section
+ * @param {number} [max]
+ * @returns {string}
+ */
+export function sectionSummary(section, max = SECTION_SUMMARY_MAX) {
+  const first = (section?.content ?? []).find(
+    (/** @type {any} */ block) =>
+      (block?.type === 'prose' && typeof block.text === 'string') ||
+      (block?.type === 'list' && Array.isArray(block.items)),
+  );
+  const raw =
+    first == null ? '' : first.type === 'prose' ? first.text : first.items[0];
+  const text = String(raw ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max - 1);
+  const space = cut.lastIndexOf(' ');
+  return `${(space > max / 2 ? cut.slice(0, space) : cut).trimEnd()}…`;
+}
+
+/**
+ * The index a topic-only read returns: what the topic is, and one entry per
+ * section with the key to read it by.
+ * @param {{name: string, title: string, description: string, sections: any[]}} doc
+ * @returns {Omit<import('../../api/docs/docs.type.mjs').DocsIndex, 'links'>}
+ */
+export function buildDocsIndexData(doc) {
+  return {
+    name: doc.name,
+    title: doc.title,
+    description: doc.description,
+    sections: doc.sections.map(section => ({
+      id: sectionKey(section),
+      title: section.title,
+      summary: sectionSummary(section),
+    })),
+  };
+}

package/foundation/discovery/docs-section-key.test.mjs

@@ -0,0 +1,246 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  SECTION_KEY_RE,
+  SECTION_SUMMARY_MAX,
+  buildDocsIndexData,
+  findDocSection,
+  sectionKey,
+  sectionKeyErrors,
+  sectionKeyProblems,
+  sectionSummary,
+  sectionTitleKey,
+  sourceTitle,
+  withSectionKeys,
+  withSourceTitle,
+} from './docs-section-key.mjs';
+
+/** @param {string} title @param {object} [fields] */
+const section = (title, fields = {}) => ({title, content: [], ...fields});
+
+describe('sectionTitleKey', () => {
+  it.each([
+    ['Quick Start', 'quick-start'],
+    ['Light/Dark Mode', 'light-dark-mode'],
+    ["Do & Don't", 'do-and-don-t'],
+    ['  Café Crème  ', 'cafe-creme'],
+    ['useTheme()', 'usetheme'],
+    ['--- Tokens ---', 'tokens'],
+    ['亮/暗模式', ''],
+    ['', ''],
+  ])('%j derives %j', (title, key) => {
+    expect(sectionTitleKey(title)).toBe(key);
+  });
+
+  it('derives only stable keys', () => {
+    for (const title of ['A  B', 'x__y', 'Élan 2.0', 'a-b-', '-a']) {
+      expect(sectionTitleKey(title)).toMatch(SECTION_KEY_RE);
+    }
+  });
+
+  it('derives nothing from a non-string', () => {
+    expect(sectionTitleKey(undefined)).toBe('');
+    expect(sectionTitleKey(42)).toBe('');
+  });
+});
+
+describe('sectionKey', () => {
+  it('prefers the authored id', () => {
+    expect(sectionKey(section('Quick Start', {id: 'start'}))).toBe('start');
+  });
+
+  it('derives from the authored title, not a translated one', () => {
+    const translated = withSourceTitle(section('快速开始'), 'Quick Start');
+    expect(sectionKey(translated)).toBe('quick-start');
+  });
+});
+
+describe('sectionKeyProblems', () => {
+  it('accepts distinct keys', () => {
+    expect(
+      sectionKeyProblems([section('Install'), section('Usage', {id: 'use'})]),
+    ).toEqual([]);
+  });
+
+  it('rejects two sections that share a key', () => {
+    const problems = sectionKeyProblems([
+      section('Quick Start'),
+      section('Quick-start'),
+    ]);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]).toContain(
+      '"quick-start" is already used by sections[0]',
+    );
+  });
+
+  it('rejects an authored id that collides with a derived key', () => {
+    expect(
+      sectionKeyProblems([
+        section('Install'),
+        section('Setup', {id: 'install'}),
+      ]),
+    ).toHaveLength(1);
+  });
+
+  it('rejects an unsafe id and never suffixes one', () => {
+    for (const id of ['Quick Start', 'a_b', 'a--b', '-a', '', 7]) {
+      expect(sectionKeyProblems([section('Install', {id})])[0]).toContain(
+        'is not a stable key',
+      );
+    }
+  });
+
+  it('reports a title no key derives from', () => {
+    expect(sectionKeyProblems([section('亮/暗模式')])[0]).toContain(
+      'compatibility key is used',
+    );
+    expect(
+      sectionKeyProblems([section('亮/暗模式', {id: 'light-dark'})]),
+    ).toEqual([]);
+  });
+
+  it('leaves a missing title to the title check', () => {
+    expect(sectionKeyProblems([{content: []}, section('')])).toEqual([]);
+  });
+});
+
+describe('withSectionKeys', () => {
+  it('stamps derived keys and keeps authored ones', () => {
+    const doc = withSectionKeys({
+      sections: [section('Quick Start'), section('Usage', {id: 'use'})],
+    });
+    expect(doc.sections.map(s => s.id)).toEqual(['quick-start', 'use']);
+  });
+
+  it('keeps authored titles and keys stable for translated sections', () => {
+    const doc = withSectionKeys({
+      sections: [
+        withSourceTitle(section('高级安装'), 'Install advanced'),
+        withSourceTitle(section('安装'), 'Install'),
+      ],
+    });
+    expect(doc.sections.map(s => s.id)).toEqual([
+      'install-advanced',
+      'install-2',
+    ]);
+    for (const target of doc.sections) {
+      expect(findDocSection(doc.sections, target.id).section).toBe(target);
+    }
+    expect(sourceTitle(doc.sections[0])).toBe('Install advanced');
+  });
+});
+
+describe('findDocSection', () => {
+  const sections = withSectionKeys({
+    sections: [
+      section('Quick Start'),
+      section('Theme Props'),
+      section('Theme Tokens', {id: 'tokens'}),
+      section('Overview', {id: 'overview-a'}),
+      section('Overview', {id: 'overview-b'}),
+    ],
+  }).sections;
+
+  it('finds every emitted key without changing a legacy query', () => {
+    const colliding = withSectionKeys({
+      sections: [section('Install advanced'), section('Install')],
+    }).sections;
+    expect(findDocSection(colliding, 'install').section).toBe(colliding[0]);
+    for (const target of colliding) {
+      expect(findDocSection(colliding, target.id).section).toBe(target);
+    }
+    expect(findDocSection(sections, 'tokens').section.title).toBe(
+      'Theme Tokens',
+    );
+  });
+
+  it('finds a section by exact title, case-insensitively', () => {
+    expect(findDocSection(sections, 'quick start').section.id).toBe(
+      'quick-start',
+    );
+  });
+
+  it('finds a section by the key its query derives', () => {
+    expect(findDocSection(sections, 'Quick-Start!').section.id).toBe(
+      'quick-start',
+    );
+  });
+
+  it('finds a section by a unique part of its title', () => {
+    expect(findDocSection(sections, 'props').section.id).toBe('theme-props');
+  });
+
+  it('keeps the first ambiguous exact-title match and lists the candidates', () => {
+    const {section: match, candidates} = findDocSection(sections, 'Overview');
+    expect(match?.id).toBe('overview-a');
+    expect(candidates.map(s => s.id)).toEqual(['overview-a', 'overview-b']);
+  });
+
+  it('keeps the first ambiguous partial-title match', () => {
+    const {section: match, candidates} = findDocSection(sections, 'theme');
+    expect(match?.id).toBe('theme-props');
+    expect(candidates.map(s => s.id)).toEqual(['theme-props', 'tokens']);
+  });
+
+  it('returns nothing for no match', () => {
+    expect(findDocSection(sections, 'zzz')).toEqual({
+      section: null,
+      candidates: [],
+    });
+  });
+});
+
+describe('sectionSummary', () => {
+  it('uses the first prose or list text, whitespace collapsed', () => {
+    expect(
+      sectionSummary({
+        content: [
+          {type: 'code', lang: 'ts', code: 'x'},
+          {type: 'prose', text: 'Line one.\n\n  Line two.'},
+        ],
+      }),
+    ).toBe('Line one. Line two.');
+    expect(
+      sectionSummary({content: [{type: 'list', items: ['First', 'Second']}]}),
+    ).toBe('First');
+  });
+
+  it('is empty when the section has no text', () => {
+    expect(
+      sectionSummary({content: [{type: 'table', headers: [], rows: []}]}),
+    ).toBe('');
+  });
+
+  it('cuts a long summary at a word boundary', () => {
+    const summary = sectionSummary({
+      content: [{type: 'prose', text: 'word '.repeat(200)}],
+    });
+    expect(summary.length).toBeLessThanOrEqual(SECTION_SUMMARY_MAX);
+    expect(summary.endsWith('word…')).toBe(true);
+  });
+});
+
+describe('buildDocsIndexData', () => {
+  it('lists each section by key, title, and summary', () => {
+    expect(
+      buildDocsIndexData({
+        name: 'theme',
+        title: 'Theme',
+        description: 'Theming.',
+        sections: [
+          section('Quick Start', {content: [{type: 'prose', text: 'Start.'}]}),
+          section('Usage', {id: 'use'}),
+        ],
+      }),
+    ).toEqual({
+      name: 'theme',
+      title: 'Theme',
+      description: 'Theming.',
+      sections: [
+        {id: 'quick-start', title: 'Quick Start', summary: 'Start.'},
+        {id: 'use', title: 'Usage', summary: ''},
+      ],
+    });
+  });
+});