@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

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

@@ -1,221 +0,0 @@
-// 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));
-}
-
-/**
- * Problems with the keys of a topic's sections: an authored id that is not a
- * stable key, a title no key derives from, and two sections sharing a key.
- * Keys are never suffixed to make them unique, because readers link to them.
- * @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}]`;
-    // A missing title is reported where titles are checked; no key to judge.
-    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)}. Give the section an id.`,
-      );
-      return;
-    }
-    const first = seen.get(key);
-    if (first != null) {
-      problems.push(
-        `${at}: the key "${key}" is already used by sections[${first}]. 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) {
-  return {
-    ...doc,
-    sections: doc.sections.map(section =>
-      section.id != null
-        ? section
-        : withSourceTitle(
-            {...section, id: sectionKey(section)},
-            sourceTitle(section),
-          ),
-    ),
-  };
-}
-
-/**
- * Find the section a reader asked for: by key, then by exact title (or the
- * key the query derives), then by a title that contains the query. More than
- * one match is refused rather than guessed.
- * @param {any[]} sections
- * @param {string} query
- * @returns {{section: any | null, candidates: any[]}} `candidates` lists the
- *   matches when the query is ambiguous, and is empty when nothing matches
- */
-export function findDocSection(sections, query) {
-  const wanted = query.trim();
-  const byKey = sections.find(section => sectionKey(section) === wanted);
-  if (byKey) return {section: byKey, candidates: []};
-
-  const lower = wanted.toLowerCase();
-  const derived = sectionTitleKey(wanted);
-  const exact = sections.filter(
-    section =>
-      section.title.toLowerCase() === lower ||
-      (derived !== '' && sectionTitleKey(sourceTitle(section)) === derived),
-  );
-  if (exact.length === 1) return {section: exact[0], candidates: []};
-  if (exact.length > 1) return {section: null, candidates: exact};
-
-  const partial = sections.filter(section =>
-    section.title.toLowerCase().includes(lower),
-  );
-  if (partial.length === 1) return {section: partial[0], candidates: []};
-  return {section: null, candidates: partial};
-}
-
-/**
- * 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 {import('../../api/docs/docs.type.mjs').DocsIndex}
- */
-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

@@ -1,224 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, it} from 'vitest';
-import {
-  SECTION_KEY_RE,
-  SECTION_SUMMARY_MAX,
-  buildDocsIndexData,
-  findDocSection,
-  sectionKey,
-  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('rejects a title no key derives from', () => {
-    expect(sectionKeyProblems([section('亮/暗模式')])[0]).toContain(
-      'Give the section an id',
-    );
-    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 the authored title of a translated section', () => {
-    const doc = withSectionKeys({
-      sections: [withSourceTitle(section('快速开始'), 'Quick Start')],
-    });
-    expect(doc.sections[0].id).toBe('quick-start');
-    expect(sourceTitle(doc.sections[0])).toBe('Quick Start');
-  });
-});
-
-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 a section by key first', () => {
-    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('refuses an ambiguous exact title and lists the candidates', () => {
-    const {section: match, candidates} = findDocSection(sections, 'Overview');
-    expect(match).toBeNull();
-    expect(candidates.map(s => s.id)).toEqual(['overview-a', 'overview-b']);
-  });
-
-  it('refuses an ambiguous partial title', () => {
-    const {section: match, candidates} = findDocSection(sections, 'theme');
-    expect(match).toBeNull();
-    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: ''},
-      ],
-    });
-  });
-});

package/foundation/doc-compiler/compile.d.mts

@@ -1,162 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * One authored file, as discovery loaded it.
- * @typedef {object} AuthoredFile
- * @property {string} file the file's name, for messages only
- * @property {any} [doc] the parsed doc, when it loaded
- * @property {unknown} [error] why it did not load or parse
- * @property {any} [overlay] the language overlay's export, when one applies
- * @property {unknown} [overlayError] why the overlay did not load
- */
-/**
- * @typedef {object} ReferenceTopicInput
- * @property {string} id the topic's name in the catalog
- * @property {string} provider the package that owns the topic
- * @property {string | null} replaces the topic it took the place of
- * @property {string | null} lang the overlay language, or null for authored text
- * @property {AuthoredFile} base
- * @property {Array<AuthoredFile & {provider: string}>} extensions in merge order
- */
-/**
- * A token reference after linking: the target section's content, or why it
- * has none.
- * @typedef {{status: 'resolved', topic: string, section: string, previewType?: string, content: any[]}
- *   | {status: 'unknown-topic'}
- *   | {status: 'unknown-section'}} TokenRefResolution
- */
-/**
- * @typedef {object} CompiledReferenceNode
- * @property {number} schemaVersion
- * @property {'reference'} kind
- * @property {'lowered' | 'linked'} stage `linked` once every token reference
- *   carries its resolution; a lowered node carries none
- * @property {string} id the topic's name in the catalog
- * @property {string | null} lang
- * @property {{provider: string, replaces: string | null, extensions: string[]}} provenance
- * @property {Record<string, string>} sourceTitles section key -> authored title
- * @property {any} doc the topic: authored fields in authored order, every
- *   section keyed; a linked node's token references carry `resolved`
- */
-/**
- * Lower one topic: overlay each file, merge the extensions in order, and stamp
- * every section with its key.
- * @param {ReferenceTopicInput} input
- * @returns {CompiledReferenceNode}
- */
-export function lowerReferenceTopic(input: ReferenceTopicInput): CompiledReferenceNode;
-/**
- * Link every section of a lowered node.
- * @param {CompiledReferenceNode} node
- * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
- *   the lowered node a reference names, or null when no topic has that name
- * @returns {Promise<CompiledReferenceNode>}
- */
-export function linkReferenceTopic(node: CompiledReferenceNode, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<CompiledReferenceNode>;
-/**
- * Resolve the token references in one section. A section with none comes back
- * as it went in.
- * @template {{content: any[]}} S
- * @param {S} section
- * @param {(topic: string) => Promise<CompiledReferenceNode | null>} lowerTarget
- * @returns {Promise<S>}
- */
-export function linkReferenceSection<S extends {
-    content: any[];
-}>(section: S, lowerTarget: (topic: string) => Promise<CompiledReferenceNode | null>): Promise<S>;
-/** Bumped whenever the shape of a compiled node changes. */
-export const COMPILED_DOC_SCHEMA_VERSION: 1;
-/**
- * One authored file, as discovery loaded it.
- */
-export type AuthoredFile = {
-    /**
-     * the file's name, for messages only
-     */
-    file: string;
-    /**
-     * the parsed doc, when it loaded
-     */
-    doc?: any;
-    /**
-     * why it did not load or parse
-     */
-    error?: unknown;
-    /**
-     * the language overlay's export, when one applies
-     */
-    overlay?: any;
-    /**
-     * why the overlay did not load
-     */
-    overlayError?: unknown;
-};
-export type ReferenceTopicInput = {
-    /**
-     * the topic's name in the catalog
-     */
-    id: string;
-    /**
-     * the package that owns the topic
-     */
-    provider: string;
-    /**
-     * the topic it took the place of
-     */
-    replaces: string | null;
-    /**
-     * the overlay language, or null for authored text
-     */
-    lang: string | null;
-    base: AuthoredFile;
-    /**
-     * in merge order
-     */
-    extensions: Array<AuthoredFile & {
-        provider: string;
-    }>;
-};
-/**
- * A token reference after linking: the target section's content, or why it
- * has none.
- */
-export type TokenRefResolution = {
-    status: "resolved";
-    topic: string;
-    section: string;
-    previewType?: string;
-    content: any[];
-} | {
-    status: "unknown-topic";
-} | {
-    status: "unknown-section";
-};
-export type CompiledReferenceNode = {
-    schemaVersion: number;
-    kind: "reference";
-    /**
-     * `linked` once every token reference
-     * carries its resolution; a lowered node carries none
-     */
-    stage: "lowered" | "linked";
-    /**
-     * the topic's name in the catalog
-     */
-    id: string;
-    lang: string | null;
-    provenance: {
-        provider: string;
-        replaces: string | null;
-        extensions: string[];
-    };
-    /**
-     * section key -> authored title
-     */
-    sourceTitles: Record<string, string>;
-    /**
-     * the topic: authored fields in authored order, every
-     * section keyed; a linked node's token references carry `resolved`
-     */
-    doc: any;
-};