@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

package/foundation/discovery/authoring-self-docs.mjs

@@ -1,214 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file The authoring self-docs, and the `authoring` topic built from them.
- *
- * @input The SchemaDoc each authoring module colocates as `*.doc.mjs` under
- *   packages/cli/authoring.
- * @output {@link AUTHORING_SELF_DOCS} (every self-doc, in reading order), the
- *   `authoring` reference topic with one section per self-doc, and an audit
- *   naming any self-doc the topic cannot reach, any that fails to load, and any
- *   section over the docs output budget.
- * @position Read by assets/docs/authoring.doc.mjs (the topic) and by Doctor
- *   (the audit). Lives in foundation because authoring/ holds only contracts.
- *   A new `*.doc.mjs` under authoring/ must be added to the list, or Doctor and
- *   the self-doc tests fail.
- */
-
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {pathToFileURL} from 'node:url';
-import {CLI_ROOT} from '../fs/paths.mjs';
-import {
-  DOC_OUTPUT_BUDGET_BYTES,
-  oversizedDocSections,
-} from './docs-output-budget.mjs';
-
-/** The directory the self-docs live under. */
-export const AUTHORING_ROOT = path.join(CLI_ROOT, 'authoring');
-
-/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
-export const AUTHORING_SELF_DOCS = [
-  'integration/integration.doc.mjs',
-  'config/config.doc.mjs',
-  'codemod/codemod.doc.mjs',
-  'identity/identity.doc.mjs',
-  'doctypes/base/graph-fields.doc.mjs',
-  'doctypes/component/component.doc.mjs',
-  'doctypes/hook/hook.doc.mjs',
-  'doctypes/function/function.doc.mjs',
-  'doctypes/command/command.doc.mjs',
-  'doctypes/enum/enum.doc.mjs',
-  'doctypes/namespace/namespace.doc.mjs',
-  'doctypes/reference/reference.doc.mjs',
-  'doctypes/schema/schema.doc.mjs',
-  'doctypes/template/template.doc.mjs',
-];
-
-/** Blocks a self-doc note may carry that a topic section can render. */
-const TOPIC_BLOCKS = new Set(['prose', 'list', 'code', 'heading', 'table']);
-
-/**
- * Every `*.doc.mjs` under `root`, relative and sorted.
- * @param {string} [root]
- * @returns {string[]}
- */
-export function discoverAuthoringSelfDocSources(root = AUTHORING_ROOT) {
-  /** @type {string[]} */
-  const found = [];
-  /** @param {string} dir */
-  const walk = dir => {
-    for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
-      if (entry.name === 'node_modules' || entry.name.startsWith('__')) continue;
-      const full = path.join(dir, entry.name);
-      if (entry.isDirectory()) walk(full);
-      else if (entry.name.endsWith('.doc.mjs')) {
-        found.push(path.relative(root, full).split(path.sep).join('/'));
-      }
-    }
-  };
-  walk(root);
-  return found.sort();
-}
-
-/**
- * Import each self-doc. One that fails is reported, never thrown, so one bad
- * file cannot take the rest of the topic down with it.
- * @param {string[]} [sources]
- * @param {string} [root]
- * @returns {Promise<{loaded: {source: string, doc: any}[], failed: {source: string, error: string}[]}>}
- */
-export async function loadAuthoringSelfDocs(
-  sources = AUTHORING_SELF_DOCS,
-  root = AUTHORING_ROOT,
-) {
-  const loaded = [];
-  const failed = [];
-  for (const source of sources) {
-    try {
-      const mod = await import(pathToFileURL(path.join(root, source)).href);
-      const doc = mod.doc ?? mod.docs ?? mod.default;
-      if (typeof doc?.name !== 'string' || typeof doc?.description !== 'string') {
-        throw new Error('exports no doc with a name and a description');
-      }
-      loaded.push({source, doc});
-    } catch (error) {
-      failed.push({
-        source,
-        error: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-  return {loaded, failed};
-}
-
-/**
- * @param {any[]} fields
- * @returns {string[][]}
- */
-function fieldRows(fields) {
-  return fields.flatMap(field => [
-    [
-      String(field.name),
-      String(field.type ?? ''),
-      field.required ? 'yes' : 'no',
-      [
-        field.description,
-        field.default != null ? `Default: ${field.default}.` : null,
-        field.example != null ? `Example: ${field.example}.` : null,
-      ]
-        .filter(Boolean)
-        .join(' '),
-    ],
-    ...fieldRows(field.fields ?? []),
-  ]);
-}
-
-/**
- * One self-doc as a topic section, keyed by the doc's own name.
- * @param {any} doc
- * @returns {import('../../authoring/doctypes/reference/type').ReferenceSection}
- */
-function selfDocSection(doc) {
-  /** @type {any[]} */
-  const content = [{type: 'prose', text: doc.description}];
-  if (doc.appliesTo) {
-    content.push({type: 'prose', text: `Applies to: ${doc.appliesTo}`});
-  }
-  const rows = fieldRows(doc.fields ?? []);
-  if (rows.length > 0) {
-    content.push({
-      type: 'table',
-      headers: ['Field', 'Type', 'Required', 'Description'],
-      rows,
-    });
-  }
-  for (const example of doc.examples ?? []) {
-    if (typeof example?.code !== 'string' || example.code.trim() === '') continue;
-    content.push({
-      type: 'code',
-      lang: example.lang ?? 'js',
-      ...(example.label ? {label: example.label} : {}),
-      code: example.code,
-    });
-  }
-  for (const note of doc.notes ?? []) {
-    if (TOPIC_BLOCKS.has(note?.type)) content.push(note);
-  }
-  return {id: doc.name, title: doc.displayName ?? doc.name, content};
-}
-
-/**
- * The `authoring` topic: one section per self-doc, in the order given.
- * @param {any[]} docs
- * @returns {import('../../authoring/doctypes/reference/type').ReferenceDoc}
- */
-export function buildAuthoringReferenceDoc(docs) {
-  return /** @type {any} */ ({
-    name: 'authoring',
-    title: 'Authoring Reference',
-    category: 'guide',
-    description:
-      'Every file an integration author writes, field by field: the integration manifest, astryx.config, codemods, identity, and each doc type.',
-    sections: docs.map(selfDocSection),
-  });
-}
-
-/**
- * The `authoring` topic from every self-doc that loads. One that fails is left
- * out here and reported by {@link auditAuthoringSelfDocs}.
- * @returns {Promise<import('../../authoring/doctypes/reference/type').ReferenceDoc>}
- */
-export async function buildAuthoringTopic() {
-  const {loaded} = await loadAuthoringSelfDocs();
-  return buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
-}
-
-/**
- * What stands between a self-doc and a reader of `astryx docs authoring`.
- * @param {{root?: string, sources?: string[], budget?: number}} [options]
- * @returns {Promise<{
- *   sections: number,
- *   unreachable: string[],
- *   failed: {source: string, error: string}[],
- *   oversized: {key: string, title: string, bytes: number}[],
- * }>}
- */
-export async function auditAuthoringSelfDocs({
-  root = AUTHORING_ROOT,
-  sources = AUTHORING_SELF_DOCS,
-  budget = DOC_OUTPUT_BUDGET_BYTES,
-} = {}) {
-  const listed = new Set(sources);
-  const unreachable = discoverAuthoringSelfDocSources(root).filter(
-    source => !listed.has(source),
-  );
-  const {loaded, failed} = await loadAuthoringSelfDocs(sources, root);
-  const topic = buildAuthoringReferenceDoc(loaded.map(entry => entry.doc));
-  return {
-    sections: topic.sections.length,
-    unreachable,
-    failed,
-    oversized: oversizedDocSections(topic.sections, budget),
-  };
-}

package/foundation/discovery/authoring-self-docs.test.mjs

@@ -1,154 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {afterEach, beforeEach, describe, expect, it} from 'vitest';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import {
-  AUTHORING_SELF_DOCS,
-  auditAuthoringSelfDocs,
-  buildAuthoringTopic,
-  discoverAuthoringSelfDocSources,
-} from './authoring-self-docs.mjs';
-import {
-  GRAPH_BLOCK_TYPES,
-  GRAPH_ONLY_FIELDS,
-  problemsInTopic,
-} from './docs-discovery.mjs';
-import {doc as graphFieldsDoc} from '../../authoring/doctypes/base/graph-fields.doc.mjs';
-import {doc as namespaceDoc} from '../../authoring/doctypes/namespace/namespace.doc.mjs';
-import {doc as referenceDoc} from '../../authoring/doctypes/reference/reference.doc.mjs';
-import {docs} from '../../api/docs/docs.mjs';
-
-const SLOW = 60_000;
-
-describe('authoring self-docs', () => {
-  it('lists every self-doc on disk exactly once', () => {
-    expect([...AUTHORING_SELF_DOCS].sort()).toEqual(
-      discoverAuthoringSelfDocSources(),
-    );
-    expect(new Set(AUTHORING_SELF_DOCS).size).toBe(AUTHORING_SELF_DOCS.length);
-  });
-
-  it('audits clean: every self-doc loads, is reachable, and fits one read', async () => {
-    expect(await auditAuthoringSelfDocs()).toEqual({
-      sections: AUTHORING_SELF_DOCS.length,
-      unreachable: [],
-      failed: [],
-      oversized: [],
-    });
-  });
-
-  it('builds a valid topic with one section per self-doc', async () => {
-    const topic = await buildAuthoringTopic();
-    expect(problemsInTopic(topic)).toEqual([]);
-    expect(topic.sections).toHaveLength(AUTHORING_SELF_DOCS.length);
-  });
-
-  it(
-    'is readable progressively through the docs API',
-    async () => {
-      const index = await docs('authoring', undefined, {index: true});
-      expect(index.type).toBe('docs.index');
-      expect(index.data.sections.map(s => s.id)).toContain('integration');
-      const section = await docs('authoring', 'integration');
-      expect(section.data.title).toBe('Astryx Integration');
-      expect(section.data.content.some(block => block.type === 'table')).toBe(
-        true,
-      );
-    },
-    SLOW,
-  );
-});
-
-describe('what the authoring docs say about the unbuilt docs graph', () => {
-  it('marks exactly the fields topic loading rejects as not read yet', () => {
-    const notReadYet = graphFieldsDoc.fields
-      .filter(field => /Not read yet/.test(field.description))
-      .map(field => field.name);
-    expect(notReadYet.sort()).toEqual([...GRAPH_ONLY_FIELDS].sort());
-    for (const field of graphFieldsDoc.fields) {
-      if (notReadYet.includes(field.name)) {
-        expect(field.description).toMatch(/fails to load/);
-      }
-    }
-    expect(graphFieldsDoc.description).toMatch(/not built yet/);
-  });
-
-  it('says a topic using a graph block fails to load', () => {
-    const content = referenceDoc.fields
-      .flatMap(field => [field, ...(field.fields ?? [])])
-      .find(field => field.name === 'sections[].content');
-    for (const type of GRAPH_BLOCK_TYPES) {
-      expect(content.description).toContain(type);
-    }
-    expect(content.description).toMatch(/fails to load/);
-  });
-
-  it('says namespace docs are not loaded yet', () => {
-    expect(namespaceDoc.description).toMatch(/Not loaded yet/);
-    expect(
-      problemsInTopic({
-        ...namespaceDoc.examples?.[0],
-        type: 'namespace',
-        name: 'x',
-      }),
-    ).toEqual([
-      '"x" is a namespace doc. Only the docs graph reads namespace docs, and it is not built yet; remove this file from the docs directory.',
-    ]);
-  });
-});
-
-describe('auditAuthoringSelfDocs', () => {
-  let root;
-
-  beforeEach(() => {
-    root = fs.mkdtempSync(path.join(process.cwd(), '.astryx-self-docs-'));
-    fs.mkdirSync(path.join(root, 'kept'));
-    fs.writeFileSync(
-      path.join(root, 'kept', 'kept.doc.mjs'),
-      "export const doc = {type: 'schema', name: 'kept', displayName: 'Kept', description: 'Listed.', fields: []};\n",
-    );
-  });
-
-  afterEach(() => {
-    fs.rmSync(root, {recursive: true, force: true});
-  });
-
-  it('names a self-doc on disk that the list leaves out', async () => {
-    fs.writeFileSync(
-      path.join(root, 'kept', 'forgotten.doc.mjs'),
-      "export const doc = {name: 'forgotten', description: 'Not listed.'};\n",
-    );
-    const audit = await auditAuthoringSelfDocs({
-      root,
-      sources: ['kept/kept.doc.mjs'],
-    });
-    expect(audit.unreachable).toEqual(['kept/forgotten.doc.mjs']);
-  });
-
-  it('reports a self-doc that fails to load instead of throwing', async () => {
-    fs.writeFileSync(
-      path.join(root, 'kept', 'broken.doc.mjs'),
-      'export const doc = {;\n',
-    );
-    const audit = await auditAuthoringSelfDocs({
-      root,
-      sources: ['kept/kept.doc.mjs', 'kept/broken.doc.mjs'],
-    });
-    expect(audit.failed.map(entry => entry.source)).toEqual([
-      'kept/broken.doc.mjs',
-    ]);
-    expect(audit.sections).toBe(1);
-  });
-
-  it('names a section over the budget', async () => {
-    const audit = await auditAuthoringSelfDocs({
-      root,
-      sources: ['kept/kept.doc.mjs'],
-      budget: 10,
-    });
-    expect(audit.oversized).toEqual([
-      expect.objectContaining({key: 'kept', title: 'Kept'}),
-    ]);
-  });
-});

package/foundation/discovery/docs-output-budget.d.mts

@@ -1,28 +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.
-
-/**
- * A payload's size as `--json` prints it: the envelope data, two-space
- * indented, in UTF-8 bytes.
- * @param {unknown} payload
- * @returns {number}
- */
-export function docPayloadBytes(payload: unknown): number;
-/**
- * @param {import('../../api/docs/docs.type.mjs').DocsIndex} index
- * @returns {number}
- */
-export function docsIndexBytes(index: import("../../api/docs/docs.type.mjs").DocsIndex): number;
-/**
- * The sections a single read would return more than `budget` bytes for.
- * @param {any[]} sections
- * @param {number} [budget]
- * @returns {{key: string, title: string, bytes: number}[]}
- */
-export function oversizedDocSections(sections: any[], budget?: number): {
-    key: string;
-    title: string;
-    bytes: number;
-}[];
-/** The most one index or one section read may return, in bytes. */
-export const DOC_OUTPUT_BUDGET_BYTES: number;

package/foundation/discovery/docs-output-budget.mjs

@@ -1,50 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file The most one progressive docs read may return.
- *
- * @input Docs payloads: one topic's section index, or one section.
- * @output Their size in bytes as `--json` prints them, and the sections over
- *   the budget.
- * @position Shared by Doctor's docs checks and the authoring self-doc audit, so
- *   both hold every read to the same limit.
- */
-
-import {sectionKey} from './docs-section-key.mjs';
-
-/** The most one index or one section read may return, in bytes. */
-export const DOC_OUTPUT_BUDGET_BYTES = 32 * 1024;
-
-/**
- * A payload's size as `--json` prints it: the envelope data, two-space
- * indented, in UTF-8 bytes.
- * @param {unknown} payload
- * @returns {number}
- */
-export function docPayloadBytes(payload) {
-  return Buffer.byteLength(JSON.stringify(payload, null, 2), 'utf8');
-}
-
-/**
- * @param {import('../../api/docs/docs.type.mjs').DocsIndex} index
- * @returns {number}
- */
-export function docsIndexBytes(index) {
-  return docPayloadBytes({type: 'docs.index', data: index});
-}
-
-/**
- * The sections a single read would return more than `budget` bytes for.
- * @param {any[]} sections
- * @param {number} [budget]
- * @returns {{key: string, title: string, bytes: number}[]}
- */
-export function oversizedDocSections(sections, budget = DOC_OUTPUT_BUDGET_BYTES) {
-  return sections
-    .map(section => ({
-      key: sectionKey(section),
-      title: section.title,
-      bytes: docPayloadBytes({type: 'docs.detail.section', data: section}),
-    }))
-    .filter(entry => entry.bytes > budget);
-}

package/foundation/discovery/docs-section-key.d.mts

@@ -1,98 +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.
-
-/**
- * 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<T extends object>(section: T, title: string): T;
-/**
- * @param {any} section
- * @returns {string}
- */
-export function sourceTitle(section: any): string;
-/**
- * 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: unknown): string;
-/**
- * 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: any): string;
-/**
- * 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: any[]): string[];
-/**
- * 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<T extends {
-    sections: any[];
-}>(doc: T): T;
-/**
- * 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: any[], query: string): {
-    section: any | null;
-    candidates: any[];
-};
-/**
- * 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: any, max?: number): string;
-/**
- * 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: {
-    name: string;
-    title: string;
-    description: string;
-    sections: any[];
-}): import("../../api/docs/docs.type.mjs").DocsIndex;
-/**
- * @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: RegExp;
-/** The longest summary an index entry carries, in characters. */
-export const SECTION_SUMMARY_MAX: 240;