@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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

@@ -0,0 +1,174 @@
+// 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 docs tree', () => {
+  it('marks exactly the fields the docs tree does not read yet', () => {
+    const notReadYet = graphFieldsDoc.fields
+      .filter(field =>
+        /^Reserved: .*Nothing reads it today/.test(field.description),
+      )
+      .map(field => field.name);
+    // The tree reads `placement` for every guide (spec:AST-046); the other
+    // graph fields are still refused by every topic reader.
+    expect(notReadYet.sort()).toEqual(
+      GRAPH_ONLY_FIELDS.filter(field => field !== 'placement').sort(),
+    );
+    for (const field of graphFieldsDoc.fields) {
+      if (GRAPH_ONLY_FIELDS.includes(field.name)) {
+        expect(field.description).toMatch(/fails to load/);
+      }
+    }
+    const placement = graphFieldsDoc.fields.find(f => f.name === 'placement');
+    expect(placement.description).toMatch(
+      /Read for every guide, the CLI's and each integration's/,
+    );
+    expect(graphFieldsDoc.description).toMatch(
+      /Nothing reads `aliases` or `audience` today/,
+    );
+  });
+
+  it('keeps graph blocks behind the separate GraphContentBlock type, and a section takes a reference block', () => {
+    const content = referenceDoc.fields
+      .flatMap(field => [field, ...(field.fields ?? [])])
+      .find(field => field.name === 'sections[].content');
+    expect(content.type).toBe('(ReferenceContentBlock | ReferenceDocBlock)[]');
+    expect(content.description).toContain('GraphContentBlock');
+    for (const type of GRAPH_BLOCK_TYPES) {
+      expect(content.description).toContain(type);
+    }
+    // A section's reference block reads as the doc it includes.
+    expect(GRAPH_BLOCK_TYPES.has('reference')).toBe(false);
+    expect(content.description).toMatch(
+      /A `reference` block .* includes another doc/,
+    );
+  });
+
+  it('says where namespace docs live: the CLI tree, and each integration', () => {
+    expect(namespaceDoc.description).toMatch(
+      /an integration ships its own in its docs directory/,
+    );
+    expect(
+      problemsInTopic({
+        ...namespaceDoc.examples?.[0],
+        type: 'namespace',
+        name: 'x',
+      }),
+    ).toEqual([
+      '"x" is a namespace doc, which the docs tree reads, not the topic list. The CLI keeps its own in assets/docs/tree; an integration ships its namespace docs in its 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/authoring-surface.d.mts

@@ -0,0 +1,74 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Every type `@astryxdesign/cli/authoring` exports, in the order index.d.ts
+ * lists them, each traced to the module that declares it. A value export that
+ * traces to a JavaScript module (a parser) is not a type and is left out;
+ * anything else that cannot be traced is reported, never dropped.
+ * @param {string} [root]
+ * @returns {{
+ *   types: {name: string, module: string}[],
+ *   untraced: {name: string, reason: string}[],
+ * }} `module` is relative to `root`
+ */
+export function tracePublicAuthoringTypes(root?: string): {
+    types: {
+        name: string;
+        module: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+};
+/**
+ * What stands between each type `@astryxdesign/cli/authoring` exports and a
+ * reader of `astryx docs authoring`. A type is readable when a self-doc beside
+ * the module that declares it is listed in AUTHORING_SELF_DOCS, loads, and
+ * renders a section the topic's index lists. A registered self-doc must
+ * document something public: a public type declared beside it, and, when its
+ * title is the name of a type declared beside it, that type.
+ * @param {{root?: string, sources?: string[], topicKeys?: Set<string> | null}} [options]
+ *   `topicKeys` are the keys `astryx docs authoring --index` lists; null skips
+ *   that comparison.
+ * @returns {Promise<{
+ *   types: number,
+ *   unreadable: {module: string, names: string[], reason: UnreadableReason, source?: string, key?: string}[],
+ *   untraced: {name: string, reason: string}[],
+ *   unmatched: {source: string, key?: string, subject?: string}[],
+ * }>}
+ */
+export function auditAuthoringSurface({ root, sources, topicKeys, }?: {
+    root?: string;
+    sources?: string[];
+    topicKeys?: Set<string> | null;
+}): Promise<{
+    types: number;
+    unreadable: {
+        module: string;
+        names: string[];
+        reason: UnreadableReason;
+        source?: string;
+        key?: string;
+    }[];
+    untraced: {
+        name: string;
+        reason: string;
+    }[];
+    unmatched: {
+        source: string;
+        key?: string;
+        subject?: string;
+    }[];
+}>;
+/** The barrel the `types` condition of `@astryxdesign/cli/authoring` names. */
+export const AUTHORING_SURFACE: "index.d.ts";
+export type Tracer = {
+    root: string;
+    /**
+     * top-level statements by absolute path
+     */
+    parsed: Map<string, any[]>;
+};
+export type UnreadableReason = "no-self-doc" | "unregistered" | "failed" | "missing-section";