@astryxdesign/cli 0.6.5-canary.0cc31e9 → 0.6.5-canary.115f3e9

package/README.md

@@ -69,7 +69,7 @@ Results for "button" (20 of 239):
 
 Options:
 
-- `--type <component|hook|doc|template|theme>`: restrict to a single domain (`doc` and `theme` work outside an app too)
+- `--type <component|hook|doc|template>`: restrict to a single domain
 - `--limit <n>`: cap the number of results (default 20)
 - `--verbose`: also print each result's match score and reason
 - `--json`: typed `{ apiVersion, type: 'search', data: { query, matchCount, results } }` envelope — `matchCount` is how many candidates matched in total, `results` the slice `--limit` allowed
@@ -91,7 +91,7 @@ Options:
 | `init`        | Initialize the design system in your project                                                  |
 | `integration` | Author and verify an Astryx integration package                                               |
 | `layout`      | Generate XDS layouts from compressed expressions (XLE/XLO)                                    |
-| `search`      | Search components, hooks, docs, templates, and themes in one ranked list                      |
+| `search`      | Search components, hooks, docs, and templates in one ranked list                              |
 | `swizzle`     | Copy component source for customization                                                       |
 | `template`    | List, show, or scaffold page and block templates                                              |
 | `theme`       | Create and build themes: add a shipped one, compile to CSS, or list what a theme can override |

package/api/build/_adapter.d.mts

@@ -40,20 +40,6 @@ export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
  * @returns {Promise<ComponentWords[]>}
  */
 export function loadComponents(cwd: string): Promise<ComponentWords[]>;
-/**
- * The matcher weights checked in beside the kit (`kit/weights.json`), read
- * once; null when the file is absent or unreadable.
- * @returns {import('./kit/weights.mjs').WeightsFile | null}
- */
-export function loadWeights(): import("./kit/weights.mjs").WeightsFile | null;
-/**
- * Whether a parsed weights file has the shape the kit reads: every row has a
- * weight per candidate, every bias a number per candidate, and three blend
- * numbers per member (the tables plus the ranker) and one for the shell.
- * @param {any} file
- * @returns {file is import('./kit/weights.mjs').WeightsFile}
- */
-export function isWeightsFile(file: any): file is import("./kit/weights.mjs").WeightsFile;
 /**
  * A page template the kit can recommend starting from.
  */

package/api/build/_adapter.mjs

@@ -2,7 +2,7 @@
 
 /**
  * @file The build subject's environment access: the page templates a project
- * can scaffold, the components it can use, and the checked-in matcher weights.
+ * can scaffold, and the components it can use.
  *
  * @input Template and component discovery for `cwd` — the CLI's own templates
  *   and Core's components, plus any that the project's configured integrations
@@ -16,8 +16,6 @@
  *   from the template subject's, components from search's.
  */
 
-import fs from 'node:fs';
-
 import {discoverTemplates} from '../template/template.mjs';
 import {componentKeywords} from '../search/search.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
@@ -91,58 +89,3 @@ export async function loadComponents(cwd) {
     return [];
   }
 }
-
-/** @type {import('./kit/weights.mjs').WeightsFile | null | undefined} */
-let weights;
-
-/**
- * The matcher weights checked in beside the kit (`kit/weights.json`), read
- * once; null when the file is absent or unreadable.
- * @returns {import('./kit/weights.mjs').WeightsFile | null}
- */
-export function loadWeights() {
-  if (weights === undefined) {
-    try {
-      const file = JSON.parse(
-        fs.readFileSync(new URL('./kit/weights.json', import.meta.url), 'utf8'),
-      );
-      weights = isWeightsFile(file) ? file : null;
-    } catch {
-      weights = null;
-    }
-  }
-  return weights ?? null;
-}
-
-/**
- * Whether a parsed weights file has the shape the kit reads: every row has a
- * weight per candidate, every bias a number per candidate, and three blend
- * numbers per member (the tables plus the ranker) and one for the shell.
- * @param {any} file
- * @returns {file is import('./kit/weights.mjs').WeightsFile}
- */
-export function isWeightsFile(file) {
-  const n = Array.isArray(file?.candidates) ? file.candidates.length : 0;
-  return (
-    n > 0 &&
-    Array.isArray(file.tables) &&
-    file.tables.length > 0 &&
-    file.tables.every(
-      (/** @type {any} */ t) =>
-        Array.isArray(t?.words) &&
-        Array.isArray(t.rows) &&
-        t.rows.length === t.words.length &&
-        t.rows.every(
-          (/** @type {any} */ r) => typeof r === 'string' && r.length === n,
-        ) &&
-        Array.isArray(t.bias) &&
-        t.bias.length === n &&
-        t.bias.every((/** @type {any} */ b) => Number.isFinite(b)) &&
-        Number.isFinite(t.clip) &&
-        Number.isFinite(t.step),
-    ) &&
-    Array.isArray(file.blend) &&
-    file.blend.length === 3 * (file.tables.length + 1) + 1 &&
-    file.blend.every((/** @type {any} */ x) => Number.isFinite(x))
-  );
-}

package/api/build/build.test.mjs

@@ -269,7 +269,7 @@ describe('build kit — a thin kit says what to try next', () => {
     // A skeleton is a 35-line excerpt: a reader who studies it and composes
     // the rest loses the spacing the template exists to carry. A loose match
     // is still the best start there is, so `start` scaffolds it.
-    const r = await build('weekly business review with targets', {cwd: REPO});
+    const r = await build('quarterly business review', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     expect(r.data.directMatch).toBe(false);
@@ -477,79 +477,6 @@ describe('build kit — every page starts from a template', () => {
     expect(r.data.pages.map(p => p.name)).not.toContain('side-gallery');
   });
 
-  it('names a direct match the start does not use, and calls the start direct only when it is', async () => {
-    for (const idea of ['a login form', 'a docs site for our API', 'contact form']) {
-      const r = await build(idea, {cwd: REPO});
-      if (r.type !== 'build.kit') throw new Error(r.type);
-      expect(r.data.directMatch).toBe(true);
-      const match = r.data.pages[0].name;
-      if (r.data.start?.name === match) {
-        expect(r.data.start?.basis).toBe('direct');
-      } else {
-        expect(['closest', 'fallback']).toContain(r.data.start?.basis);
-        expect(r.data.start?.reason).toContain(`\`${match}\``);
-      }
-    }
-  });
-
-  it('keeps a template search matched directly rather than the app shell', async () => {
-    for (const [idea, name] of [
-      ['a login screen', 'login'],
-      ['a checkout wizard', 'checkout-wizard'],
-    ]) {
-      const r = await build(idea, {cwd: REPO});
-      if (r.type !== 'build.kit') throw new Error(r.type);
-      expect(r.data.directMatch).toBe(true);
-      expect(r.data.start?.name).toBe(name);
-    }
-  });
-
-  it('lets the weights choose another template over a direct match', async () => {
-    const r = await build('a login form', {cwd: REPO});
-    if (r.type !== 'build.kit') throw new Error(r.type);
-    expect(r.data.directMatch).toBe(true);
-    const match = r.data.pages[0].name;
-    expect(r.data.start?.name).not.toBe('shell-top-nav');
-    expect(r.data.start?.name).not.toBe(match);
-    expect(r.data.start?.reason).toContain(`\`${match}\``);
-  });
-
-  it('starts a part that names no page from the app shell', async () => {
-    for (const idea of ['a kanban card', 'a date range picker']) {
-      const r = await build(idea, {cwd: REPO});
-      if (r.type !== 'build.kit') throw new Error(r.type);
-      expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
-      expect(r.data.start?.reason).toMatch(/part of a page/);
-    }
-  });
-
-  it('does not keep a loose match over the app shell', async () => {
-    // Search matches no template directly, so the ranker's closest page does
-    // not override the shell the weights choose.
-    const r = await build('quarterly business review', {cwd: REPO});
-    if (r.type !== 'build.kit') throw new Error(r.type);
-    expect(r.data.directMatch).toBe(false);
-    expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
-    expect(r.data.start?.reason).toMatch(/closest/);
-  });
-
-  it('starts a new page with no matching template from the app shell', async () => {
-    const r = await build('a new page', {cwd: REPO});
-    if (r.type !== 'build.kit') throw new Error(r.type);
-    expect(r.data.start?.name).toBe('shell-top-nav');
-  });
-
-  it('starts a page the words describe from its template', async () => {
-    for (const [idea, name] of [
-      ['a weekly report of sales by region', 'dashboard-scorecard'],
-      ['a pricing page with three plans and a comparison table', 'table-page'],
-    ]) {
-      const r = await build(idea, {cwd: REPO});
-      if (r.type !== 'build.kit') throw new Error(r.type);
-      expect(r.data.start?.name).toBe(name);
-    }
-  });
-
   it('starts a component in a container from a template with that frame', async () => {
     // "in a modal": the modal is the frame, so the dialog template leads
     // instead of the app shell.

package/api/build/kit/kit.mjs

@@ -32,15 +32,8 @@ import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {getResultCoverage} from '../../search/coverage.mjs';
-import {loadComponents, loadPageTemplates, loadWeights} from '../_adapter.mjs';
-import {
-  asksForNewPage,
-  ideaKind,
-  pickAlternatives,
-  pickStart,
-  rankPages,
-} from './rank.mjs';
-import {weighStart} from './weights.mjs';
+import {loadComponents, loadPageTemplates} from '../_adapter.mjs';
+import {ideaKind, pickAlternatives, pickStart, rankPages} from './rank.mjs';
 
 /** A page at/above this score is a confident direct match. */
 const PAGE_DIRECT = 95;
@@ -158,10 +151,9 @@ function placement(kind, inPage) {
  * @param {SearchResultEntry[]} pages
  * @param {boolean} directMatch
  * @param {PageTemplate[]} catalog
- * @param {string} idea
  * @returns {Omit<BuildStart, 'alternatives'> | null}
  */
-function chooseStart(ranked, kind, pages, directMatch, catalog, idea) {
+function chooseStart(ranked, kind, pages, directMatch, catalog) {
   const direct = directMatch ? pages[0].name : null;
   const unready =
     direct && !catalog.some(t => t.name === direct) ? direct : null;
@@ -178,27 +170,7 @@ function chooseStart(ranked, kind, pages, directMatch, catalog, idea) {
     direct && direct !== startName
       ? `Search matched \`${direct}\` by name, but ${place}`
       : place[0].toUpperCase() + place.slice(1);
-  const proposed = pickStart(ranked, kind);
-  // The checked-in word weights (weights.mjs), blended with the ranker's
-  // scores, decide the start of a whole page. A part or an edit starts where
-  // the ranker's placement rules put it (spec:AST-048/FR3).
-  const weighed =
-    kind === 'page'
-      ? weighStart(idea, ranked, proposed, catalog, {
-          weights: loadWeights(),
-          newPage: asksForNewPage(idea, catalog),
-        })
-      : undefined;
-  // A shell start keeps the shell the ranker named, if any, and never replaces
-  // the template the ranker chose for a page search matched directly.
-  const pick =
-    weighed === undefined
-      ? proposed
-      : weighed === null
-        ? proposed?.family === 'Shell' || (proposed && direct && !unready)
-          ? proposed
-          : null
-        : (ranked.find(r => r.name === weighed) ?? proposed);
+  const pick = pickStart(ranked, kind);
   const closest = pick && catalog.find(t => t.name === pick.name);
   if (pick && closest) {
     const agrees = closest.name === direct;
@@ -222,9 +194,7 @@ function chooseStart(ranked, kind, pages, directMatch, catalog, idea) {
     if (shell) {
       // The shell can also be the ranker's best guess without the evidence to
       // lead ("horizontal site navigation"); say so rather than "no match".
-      const nearest =
-        (ranked[0]?.name === shell.name && ranked[0].hits > 0) ||
-        (weighed === null && !!proposed && proposed.family !== 'Shell');
+      const nearest = ranked[0]?.name === shell.name && ranked[0].hits > 0;
       const place = placement(kind, false);
       return {
         ...asTemplate(shell),
@@ -234,9 +204,7 @@ function chooseStart(ranked, kind, pages, directMatch, catalog, idea) {
           : place
             ? placed(place, shell.name)
             : direct
-              ? weighed === null
-                ? `Search matched \`${direct}\` by name, but the app shell is the closer start.`
-                : `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
+              ? `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
               : nearest
                 ? 'No template is a clear match; the app shell is the closest.'
                 : loose
@@ -378,7 +346,7 @@ export async function buildKit(query, options = {}) {
       )
     : 'page';
   const chosen = wantsPages
-    ? chooseStart(ranked, kind, matchedPages, directMatch, catalog, query)
+    ? chooseStart(ranked, kind, matchedPages, directMatch, catalog)
     : null;
   // Name the ranker's next two templates beside the start: the reader judges
   // meaning better than keywords do, and an acceptable template is in these

package/api/build/kit/rank.d.mts

@@ -21,14 +21,6 @@ export function rankPages(query: string, pages: PageTemplate[]): RankedPage[];
  * @returns {IdeaKind}
  */
 export function ideaKind(query: string, pages: PageTemplate[], components: ComponentWords[]): IdeaKind;
-/**
- * Whether an idea asks for a new page (see `asksNewPage`), from the idea and
- * the project's page templates.
- * @param {string} query
- * @param {PageTemplate[]} pages
- * @returns {boolean}
- */
-export function asksForNewPage(query: string, pages: PageTemplate[]): boolean;
 /**
  * The next closest templates after the start, best first: the ones a reader
  * should check the idea against when the start's shape is wrong. Each matched

package/api/build/kit/rank.mjs

@@ -543,20 +543,6 @@ function asksNewPage(phrases, familyWords) {
   });
 }
 
-/**
- * Whether an idea asks for a new page (see `asksNewPage`), from the idea and
- * the project's page templates.
- * @param {string} query
- * @param {PageTemplate[]} pages
- * @returns {boolean}
- */
-export function asksForNewPage(query, pages) {
-  return asksNewPage(
-    String(query).toLowerCase().split(PHRASE_END),
-    familyWordsOf(pages),
-  );
-}
-
 /**
  * The words of a component's name: "DateRangeInput" is date, range, input.
  * @param {ComponentWords} component

package/api/docs/docs.d.mts

@@ -10,10 +10,6 @@
  * @param {boolean} [options.dense]
  * @param {boolean} [options.index] return the topic's section index instead of
  *   the whole doc
- * @param {number | 'all'} [options.depth] how many levels below a docs-tree
- *   namespace to read; a doc with nothing below it reads the same at any depth
- * @param {'brief' | 'compact' | 'full'} [options.detail] how much of each doc
- *   below the named one a depth read returns (brief by default)
  * @param {string} [options.cwd]
  * @returns {Promise<
  *   import('./docs.type.mjs').DocsListResponse |
@@ -28,8 +24,6 @@ export function docs(topic?: string, section?: string, options?: {
     zh?: boolean | undefined;
     dense?: boolean | undefined;
     index?: boolean | undefined;
-    depth?: number | "all" | undefined;
-    detail?: "compact" | "full" | "brief" | undefined;
     cwd?: string | undefined;
 }): Promise<import("./docs.type.mjs").DocsListResponse | import("./docs.type.mjs").DocsIndexResponse | import("./docs.type.mjs").DocsDetailResponse | import("./docs.type.mjs").DocsDetailSectionResponse | import("./docs.type.mjs").DocsNodeResponse>;
 import { list } from './list/list.mjs';

package/api/docs/docs.doc.mjs

@@ -25,8 +25,7 @@ export const doc = {
     'ones the project\'s configured integrations contribute, including any ' +
     'topic an integration replaces or extends, so it depends on the cwd. ' +
     'A route opens a node of the docs tree instead: a namespace such as ' +
-    '`cli/api` returns its children one level down (`depth` reads as many ' +
-    'levels as asked, and `detail` how much of each doc below), a typed doc such as ' +
+    "`cli/api` returns its children one level down, a typed doc such as " +
     "`cli/api/functions/search` returns its content, and a guide the tree " +
     'places (`cli/integrations/quick-start`) reads like any topic. ' +
     'Every read but the list carries `links`, the commands that move from it: ' +
@@ -83,18 +82,6 @@ export const doc = {
       description:
         "Return the topic's section index (each section's key, title, and summary), even for a topic with one section.",
     },
-    {
-      name: 'options.depth',
-      type: "number | 'all'",
-      description:
-        "How many levels below a docs-tree namespace to read: 0 for the namespace alone, 1 for its children (the default), 'all' for every level. Where a read stops, a child with docs below it carries childCount. A doc with nothing below it reads the same at any depth.",
-    },
-    {
-      name: 'options.detail',
-      type: "'brief' | 'compact' | 'full'",
-      description:
-        "How much of each doc below the named one a depth read returns: brief (the default) is its identity; compact and full add its text (a guide's sections, a namespace's or typed doc's content). Given alone, it reads one level down.",
-    },
     {
       name: 'options.cwd',
       type: 'string',
@@ -126,18 +113,10 @@ export const doc = {
     {
       type: 'docs.node',
       description:
-        "A namespace or typed doc in the docs tree, read by its route: {id, route, kind, package, title, summary, breadcrumb, slots, content}. A namespace lists each slot's children one level down, or as deep as depth asks, each child carrying its own slots, childCount where the read stops, and its text at compact or full detail; a typed doc carries its content.",
+        "A namespace or typed doc in the docs tree, read by its route: {id, route, kind, package, title, summary, breadcrumb, slots, content}. A namespace lists each slot's children one level down; a typed doc carries its content.",
     },
   ],
   throws: [
-    {
-      code: 'ERR_INVALID_ARGUMENT',
-      when: "depth is not a whole number of levels or 'all'",
-    },
-    {
-      code: 'ERR_INVALID_DETAIL',
-      when: 'detail is not brief, compact, or full',
-    },
     {
       code: 'ERR_UNKNOWN_TOPIC',
       when: 'the topic is not a string, or matches no topic and no docs-tree route',
@@ -155,14 +134,6 @@ export const doc = {
       code: "await docs('principles', undefined, {index: true});",
     },
     {label: 'A docs-tree namespace', code: "await docs('cli/api');"},
-    {
-      label: 'Every doc below a namespace, one entry each',
-      code: "await docs('cli', undefined, {depth: 'all'});",
-    },
-    {
-      label: 'A namespace and everything below it, in full',
-      code: "await docs('cli/integrations', undefined, {depth: 'all', detail: 'full'});",
-    },
     {label: 'One API function', code: "await docs('cli/api/functions/search');"},
     {
       label: 'A whole guide from the docs tree',

package/api/docs/docs.mjs

@@ -11,7 +11,6 @@
  *   docs(topic, undefined, {index: true}) -> index   -> docs.index
  *   docs(topic, section)                  -> section -> docs.detail.section
  *   docs(route)                           -> node    -> docs.node
- *   docs(route, undefined, {depth: 2})    -> node    -> docs.node, two levels
  *
  * A topic read returns the whole doc, as it always has; `index` returns its
  * sections, so a reader can open one by its key (spec:AST-047). The CLI's text
@@ -34,43 +33,6 @@ import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 
 export {list, index, detail, sectionLeaf as section, nodeLeaf as node};
 
-const DETAILS = ['brief', 'compact', 'full'];
-
-/**
- * How far a docs-tree read goes, from the options: `depth` levels below the
- * node, or every level for `'all'`, and `detail` for each doc below it (brief
- * by default). `detail` alone reads one level down. Neither: the plain read.
- * @param {import('./docs.type.mjs').DocsOptions} options
- * @returns {import('./node/node.mjs').DepthRead | undefined}
- */
-function depthRead(options) {
-  const {depth, detail} = options;
-  if (detail != null && !DETAILS.includes(detail)) {
-    throw new AstryxError(
-      `detail is brief, compact, or full, not ${JSON.stringify(detail)}.`,
-      undefined,
-      ERROR_CODES.ERR_INVALID_DETAIL,
-    );
-  }
-  if (
-    depth != null &&
-    depth !== 'all' &&
-    !(Number.isInteger(depth) && /** @type {number} */ (depth) >= 0)
-  ) {
-    throw new AstryxError(
-      `depth is a number of levels (0, 1, 2, ...) or "all", not ${JSON.stringify(depth)}.`,
-      undefined,
-      ERROR_CODES.ERR_INVALID_ARGUMENT,
-    );
-  }
-  if (depth == null && detail == null) return undefined;
-  return {
-    depth: depth === 'all' ? Infinity : (depth ?? 1),
-    detail: /** @type {'brief' | 'compact' | 'full'} */ (detail ?? 'brief'),
-    lang: options.lang || (options.dense ? 'dense' : options.zh ? 'zh' : null),
-  };
-}
-
 /**
  * @param {string} [topic]
  * @param {string} [section]
@@ -80,10 +42,6 @@ function depthRead(options) {
  * @param {boolean} [options.dense]
  * @param {boolean} [options.index] return the topic's section index instead of
  *   the whole doc
- * @param {number | 'all'} [options.depth] how many levels below a docs-tree
- *   namespace to read; a doc with nothing below it reads the same at any depth
- * @param {'brief' | 'compact' | 'full'} [options.detail] how much of each doc
- *   below the named one a depth read returns (brief by default)
  * @param {string} [options.cwd]
  * @returns {Promise<
  *   import('./docs.type.mjs').DocsListResponse |
@@ -94,7 +52,6 @@ function depthRead(options) {
  * >}
  */
 export async function docs(topic, section, options = {}) {
-  const read = depthRead(options);
   if (!topic) return list(options);
   const found = await resolveDocsArgument(topic, options);
   if (found.kind === 'node') {
@@ -120,7 +77,7 @@ export async function docs(topic, section, options = {}) {
     }
     return {
       type: 'docs.node',
-      data: await nodeView(found.catalog, found.tree, found.node, read),
+      data: await nodeView(found.catalog, found.tree, found.node),
     };
   }
   if (section) return sectionLeaf(topic, section, options);

package/api/docs/docs.type.d.mts

@@ -205,14 +205,9 @@ export type DocsNode = {
     breadcrumb: DocsNodeLink[];
     /**
      * a namespace's slots that hold children, in
-     * order; empty for a typed doc, and for a depth read of 0
+     * order; empty for a typed doc
      */
     slots: DocsNodeSlot[];
-    /**
-     * with a depth read of 0, how many docs sit
-     * right below the namespace
-     */
-    childCount?: number | undefined;
     /**
      *   a typed doc's content; empty for a namespace
      */
@@ -251,26 +246,6 @@ export type DocsNodeChild = {
     kind: string;
     title: string;
     summary: string;
-    /**
-     * with a depth read, its own slots, while
-     * the read goes deeper
-     */
-    slots?: DocsNodeSlot[] | undefined;
-    /**
-     * with a depth read, how many docs sit right
-     * below it where the read stops
-     */
-    childCount?: number | undefined;
-    /**
-     * with a depth read at compact or full detail: a namespace's intro or a typed
-     * doc's content
-     */
-    content?: import("@astryxdesign/cli/authoring").ReferenceContentBlock[] | undefined;
-    /**
-     * with a depth read at compact or full
-     * detail: a guide's sections
-     */
-    sections?: DocsReadSection[] | undefined;
 };
 /**
  * Options for `docs()`.
@@ -284,18 +259,6 @@ export type DocsOptions = {
      * whole doc
      */
     index?: boolean | undefined;
-    /**
-     * how many levels below a docs-tree
-     * namespace to read: 0 for the namespace alone, 1 for its children (the
-     * default), 'all' for every level
-     */
-    depth?: number | "all" | undefined;
-    /**
-     * how much of each doc below
-     * the named one a depth read returns: brief (the default) is its identity,
-     * compact and full add its text
-     */
-    detail?: "compact" | "full" | "brief" | undefined;
     /**
      * project directory whose configured integrations
      * contribute topics; defaults to process.cwd()

package/api/docs/docs.type.mjs

@@ -153,9 +153,7 @@
  * @property {string} summary
  * @property {DocsNodeLink[]} breadcrumb the namespaces above it, top first
  * @property {DocsNodeSlot[]} slots a namespace's slots that hold children, in
- *   order; empty for a typed doc, and for a depth read of 0
- * @property {number} [childCount] with a depth read of 0, how many docs sit
- *   right below the namespace
+ *   order; empty for a typed doc
  * @property {import('@astryxdesign/cli/authoring').ReferenceContentBlock[]} content
  *   a typed doc's content; empty for a namespace
  * @property {DocsLinks} links the moves from the node: up to its parent (the
@@ -183,15 +181,6 @@
  * @property {string} kind
  * @property {string} title
  * @property {string} summary
- * @property {DocsNodeSlot[]} [slots] with a depth read, its own slots, while
- *   the read goes deeper
- * @property {number} [childCount] with a depth read, how many docs sit right
- *   below it where the read stops
- * @property {import('@astryxdesign/cli/authoring').ReferenceContentBlock[]} [content]
- *   with a depth read at compact or full detail: a namespace's intro or a typed
- *   doc's content
- * @property {DocsReadSection[]} [sections] with a depth read at compact or full
- *   detail: a guide's sections
  */
 
 /**
@@ -202,12 +191,6 @@
  * @property {boolean} [dense]
  * @property {boolean} [index] return a topic's section index instead of its
  *   whole doc
- * @property {number | 'all'} [depth] how many levels below a docs-tree
- *   namespace to read: 0 for the namespace alone, 1 for its children (the
- *   default), 'all' for every level
- * @property {'brief' | 'compact' | 'full'} [detail] how much of each doc below
- *   the named one a depth read returns: brief (the default) is its identity,
- *   compact and full add its text
  * @property {string} [cwd] project directory whose configured integrations
  *   contribute topics; defaults to process.cwd()
  */

package/api/docs/node/node.d.mts

@@ -4,28 +4,15 @@
 /**
  * @typedef {import('../../../foundation/doc-compiler/tree.mjs').DocsTree} DocsTree
  * @typedef {import('../../../foundation/doc-compiler/tree.mjs').TreeNode} TreeNode
- * @typedef {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} DocsCatalog
  */
 /**
- * How far a read goes below the node it names, and how much of each doc below
- * it shows: `depth` levels (Infinity for every level), and `detail` brief (its
- * identity), or compact or full (with its text: a namespace's intro, a guide's
- * sections, a typed doc's content). `lang` selects the guides' language.
- * @typedef {object} DepthRead
- * @property {number} depth
- * @property {'brief' | 'compact' | 'full'} detail
- * @property {string | null} lang
- */
-/**
- * The docs.node view of one tree node. Without a depth read, a namespace lists
- * its children one level down.
- * @param {DocsCatalog} catalog
+ * The docs.node view of one tree node.
+ * @param {import('../../../foundation/discovery/docs-discovery.mjs').DocsCatalog} catalog
  * @param {DocsTree} tree
  * @param {TreeNode} node
- * @param {DepthRead} [read] how far down to go, and how much of each doc below
  * @returns {Promise<import('../docs.type.mjs').DocsNode>}
  */
-export function nodeView(catalog: DocsCatalog, tree: DocsTree, node: TreeNode, read?: DepthRead): Promise<import("../docs.type.mjs").DocsNode>;
+export function nodeView(catalog: import("../../../foundation/discovery/docs-discovery.mjs").DocsCatalog, tree: DocsTree, node: TreeNode): Promise<import("../docs.type.mjs").DocsNode>;
 /**
  * The typed edges a doc declares (spec:AST-047 FR5), resolved to routes: a
  * function doc's `command` and `related`, and a command doc's `fn` and
@@ -54,15 +41,3 @@ export function node(route: string, options?: {
 }): Promise<import("../docs.type.mjs").DocsNodeResponse>;
 export type DocsTree = import("../../../foundation/doc-compiler/tree.mjs").DocsTree;
 export type TreeNode = import("../../../foundation/doc-compiler/tree.mjs").TreeNode;
-export type DocsCatalog = import("../../../foundation/discovery/docs-discovery.mjs").DocsCatalog;
-/**
- * How far a read goes below the node it names, and how much of each doc below
- * it shows: `depth` levels (Infinity for every level), and `detail` brief (its
- * identity), or compact or full (with its text: a namespace's intro, a guide's
- * sections, a typed doc's content). `lang` selects the guides' language.
- */
-export type DepthRead = {
-    depth: number;
-    detail: "brief" | "compact" | "full";
-    lang: string | null;
-};