@astryxdesign/cli 0.6.3-canary.f22695a → 0.6.3

package/authoring/doctypes/namespace/parse.test.mjs

@@ -1,165 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, expect, it} from 'vitest';
-import {parseDoc, parseNamespace, parseReference} from '../../index.mjs';
-
-const namespaceDoc = {
-  type: 'namespace',
-  name: 'integrations',
-  title: 'Author integrations',
-  summary: 'Publish reusable Astryx packages.',
-  aliases: ['cli-integrations'],
-  placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
-  slots: {
-    contributions: {
-      title: 'What do you want to publish?',
-      accepts: {kinds: ['namespace']},
-    },
-    providerGuides: {
-      title: 'Provider guidance',
-      accepts: {providers: 'configured', kinds: ['generic', 'schema']},
-    },
-  },
-  adopts: [
-    {
-      source: {group: 'cli-api', kinds: ['function', 'schema', 'enum']},
-      into: 'contributions',
-      groupBy: 'kind',
-    },
-  ],
-  blocks: [
-    {
-      type: 'workflow',
-      title: 'Package lifecycle',
-      steps: [
-        {title: 'Add', references: ['command:integration-add']},
-        {
-          title: 'Validate',
-          references: ['command:doctor-integration-validate'],
-        },
-      ],
-    },
-    {
-      type: 'collection',
-      source: {slot: 'contributions'},
-      presentation: 'cards',
-    },
-    {
-      type: 'reference',
-      target: 'schema:integration',
-      projection: {fields: ['components', 'docs']},
-    },
-  ],
-};
-
-describe('NamespaceDoc', () => {
-  it('accepts the reviewed plain-object shape through both parsers', () => {
-    expect(parseNamespace(namespaceDoc)).toEqual(namespaceDoc);
-    expect(parseDoc(namespaceDoc)).toEqual(namespaceDoc);
-  });
-
-  it('reports stable nested field paths', () => {
-    expect(() =>
-      parseNamespace({
-        ...namespaceDoc,
-        blocks: [{type: 'workflow', steps: [{title: ''}]}],
-      }),
-    ).toThrow(/blocks\.0\.steps\.0\.title/u);
-  });
-
-  it.each(['choice', 'callout', 'checklist'])(
-    'rejects unsupported %s blocks',
-    type => {
-      expect(() => parseNamespace({...namespaceDoc, blocks: [{type}]})).toThrow(
-        /blocks\.0\.type/u,
-      );
-    },
-  );
-
-  it('rejects misspelled fields instead of silently dropping them', () => {
-    expect(() =>
-      parseNamespace({...namespaceDoc, summmary: 'misspelled'}),
-    ).toThrow(/summmary/u);
-  });
-
-  it('requires at least one declared slot', () => {
-    expect(() => parseNamespace({...namespaceDoc, slots: {}})).toThrow(
-      /at least one slot is required/u,
-    );
-  });
-
-  it('rejects a collection that names an undeclared slot', () => {
-    expect(() =>
-      parseNamespace({
-        ...namespaceDoc,
-        blocks: [{type: 'collection', source: {slot: 'missing'}}],
-      }),
-    ).toThrow(/blocks\.0\.source\.slot.*declared slot/u);
-  });
-
-  it('rejects an adoption rule that names an undeclared slot', () => {
-    expect(() =>
-      parseNamespace({
-        ...namespaceDoc,
-        adopts: [{source: {group: 'cli-api'}, into: 'missing'}],
-      }),
-    ).toThrow(/adopts\.0\.into.*declared slot/u);
-  });
-
-  it('rejects an adoption rule whose generated kind is not accepted', () => {
-    expect(() =>
-      parseNamespace({
-        ...namespaceDoc,
-        adopts: [
-          {
-            source: {group: 'cli-api', kinds: ['command']},
-            into: 'providerGuides',
-            groupBy: 'kind',
-          },
-        ],
-      }),
-    ).toThrow(/does not accept adopted kind "namespace"/u);
-
-    expect(() =>
-      parseNamespace({
-        ...namespaceDoc,
-        adopts: [
-          {
-            source: {group: 'cli-api', kinds: ['command']},
-            into: 'providerGuides',
-          },
-        ],
-      }),
-    ).toThrow(/does not accept adopted kind "command"/u);
-  });
-});
-
-describe('semantic blocks in existing docs', () => {
-  it('accepts workflow, collection, and reference in a ReferenceDoc section', () => {
-    const parsed = parseReference({
-      type: 'generic',
-      name: 'publishing',
-      title: 'Publishing',
-      description: 'Publish an integration.',
-      sections: [
-        {
-          id: 'start',
-          title: 'Start',
-          content: namespaceDoc.blocks,
-        },
-      ],
-    });
-    expect(parsed.sections[0].id).toBe('start');
-    expect(parsed.sections[0].content.map(block => block.type)).toEqual([
-      'workflow',
-      'collection',
-      'reference',
-    ]);
-  });
-
-  it('rejects an unknown stamped doc kind instead of treating it as legacy', () => {
-    expect(() => parseDoc({type: 'choice', name: 'x', props: []})).toThrow(
-      /unsupported type "choice"/u,
-    );
-  });
-});

package/authoring/doctypes/namespace/type.ts

@@ -1,71 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Namespace doc types. A namespace owns navigation slots and a
- * renderer-neutral layout over already-discovered docs. It never scans files
- * or copies child documents.
- */
-
-import type {AuthoredDocGraphFields, AuthoredDocKind} from '../base/type.js';
-import type {ReferenceContentBlock} from '../reference/type.js';
-
-/** Which providers may contribute appearances to a namespace slot. */
-export type NamespaceProviderScope = 'same' | 'configured';
-
-/** Constraints declared by the namespace that owns a slot. */
-export interface NamespaceSlotAcceptance {
-  /** Authored doc kinds accepted by this slot. */
-  kinds: AuthoredDocKind[];
-  /** Omit for the namespace provider; `configured` admits provider appearances. */
-  providers?: NamespaceProviderScope;
-}
-
-/** One named placement and collection target owned by a NamespaceDoc. */
-export interface NamespaceSlot {
-  /** Human-readable heading for children in this slot. */
-  title: string;
-  /** Which docs may be placed or shown in this slot. */
-  accepts: NamespaceSlotAcceptance;
-}
-
-/** One logical source group that a namespace may adopt. */
-export interface NamespaceAdoptionSource {
-  /** Provider-local discovery group, such as `cli-commands`. */
-  group: string;
-  /** Optional subset of authored kinds from the group. */
-  kinds?: AuthoredDocKind[];
-}
-
-/**
- * Assigns otherwise-unplaced docs from one provider-local source group to a
- * child namespace. Discovery defines groups; this rule never scans a folder.
- */
-export interface NamespaceAdoptionRule {
-  source: NamespaceAdoptionSource;
-  /** Slot owned by this namespace that becomes the canonical destination. */
-  into: string;
-  /** Generate one child namespace per authored kind. */
-  groupBy?: 'kind';
-}
-
-/**
- * An authored documentation namespace. Its ordered blocks control layout while
- * slots and adoption rules describe where already-discovered docs may appear.
- */
-export interface NamespaceDoc extends AuthoredDocGraphFields {
-  type: 'namespace';
-  /** Stable provider-local name. Navigation changes do not change this value. */
-  name: string;
-  /** Human-readable page title. */
-  title: string;
-  /** One-line summary shown in listings and search results. */
-  summary: string;
-  /** Search terms that are not already present in the title or summary. */
-  keywords?: string[];
-  /** Named child-placement and collection targets. */
-  slots: Record<string, NamespaceSlot>;
-  /** Optional source-adoption rules for otherwise-unplaced docs. */
-  adopts?: NamespaceAdoptionRule[];
-  /** Ordered renderer-neutral content and collection blocks. */
-  blocks?: ReferenceContentBlock[];
-}

package/authoring/identity/identity.doc.d.mts

@@ -1,9 +0,0 @@
-// @generated by scripts/sync-api-types.mjs from the JSDoc in authoring/**/*.mjs.
-// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
-
-/**
- * @file SchemaDoc for provider, artifact, and immutable instance identity.
- * @position packages/cli/authoring/identity — identity documentation
- */
-/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
-export const doc: import("@astryxdesign/cli/authoring").SchemaDoc;

package/authoring/identity/identity.doc.mjs

@@ -1,61 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file SchemaDoc for provider, artifact, and immutable instance identity.
- * @position packages/cli/authoring/identity — identity documentation
- */
-
-/** @type {import('@astryxdesign/cli/authoring').SchemaDoc} */
-export const doc = {
-  type: 'schema',
-  name: 'provider-identity',
-  displayName: 'Provider and artifact identity',
-  namespace: 'authoring',
-  description:
-    'Separates stable provider/artifact identity from package instances and runtime lifecycle state. providerId is in use today: an integration manifest may declare it, and Doctor and every command report two packages that claim one. The artifact, doc, instance, and compiler-input identities are defined for the docs graph, which is not built yet, and no command reads them.',
-  appliesTo:
-    'Integration manifests and provider conflicts today; the docs graph once it ships',
-  fields: [
-    {
-      name: 'ProviderId',
-      type: 'string',
-      description:
-        'Canonical logical provider ID. It defaults to the lowercase npm package name; Core uses the same model without publishing an integration manifest.',
-      required: true,
-    },
-    {
-      name: 'ArtifactId',
-      type: 'string',
-      description:
-        'Versioned serialization of provider ID, contribution kind, and stable artifact name. Every segment uses RFC 3986 escaping.',
-      required: true,
-    },
-    {
-      name: 'DocId',
-      type: 'ArtifactId',
-      description:
-        'Artifact ID restricted to one authored doc kind. Navigation changes do not change it.',
-      required: true,
-    },
-    {
-      name: 'ProviderInstance',
-      type: '{ id; providerId; packageName; packageVersion; sourceDigest }',
-      description:
-        'One immutable package version and source/content digest. Installed, configured, loaded, selected, and healthy state is a separate runtime overlay.',
-      required: true,
-    },
-    {
-      name: 'AuthoredDocEntry',
-      type: '{ id; provider; kind; stableName; source; authored }',
-      description:
-        'Normalized compiler input. Discovery supplies stableName independently from the authored display name, source paths remain package-relative, and provider provenance plus the authored snapshot are immutable.',
-      required: true,
-    },
-  ],
-  notes: [
-    {
-      type: 'prose',
-      text: 'Provider package renames require an explicit mapping: a ProviderInstance may retain its stable providerId while packageName changes. Silent identity changes are not inferred.',
-    },
-  ],
-};

package/authoring/identity/type.ts

@@ -1,132 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file Stable provider, artifact, and authored-doc entry contracts.
- *
- * Logical IDs exclude installed/configured/loaded/healthy state. A concrete
- * provider instance adds package version and a content digest, while an
- * artifact ID stays stable across those instances.
- */
-
-import type {AuthoredDocKind} from '../doctypes/base/type.js';
-import type {CommandDoc} from '../doctypes/command/type.js';
-import type {ComponentDoc} from '../doctypes/component/type.js';
-import type {EnumDoc} from '../doctypes/enum/type.js';
-import type {FunctionDoc} from '../doctypes/function/type.js';
-import type {HookDoc} from '../doctypes/hook/type.js';
-import type {NamespaceDoc} from '../doctypes/namespace/type.js';
-import type {ReferenceDoc} from '../doctypes/reference/type.js';
-import type {SchemaDoc} from '../doctypes/schema/type.js';
-import type {TemplateDoc} from '../doctypes/template/type.js';
-
-declare const providerIdBrand: unique symbol;
-declare const artifactIdBrand: unique symbol;
-declare const docIdBrand: unique symbol;
-declare const providerInstanceIdBrand: unique symbol;
-declare const contentDigestBrand: unique symbol;
-
-/** Canonical provider identity. It defaults to the normalized npm package name. */
-export type ProviderId = string & {readonly [providerIdBrand]: true};
-
-/** Stable provider + contribution kind + artifact-name identity. */
-export type ArtifactId = string & {readonly [artifactIdBrand]: true};
-
-/** ArtifactId narrowed to an authored documentation kind. */
-export type DocId = ArtifactId & {readonly [docIdBrand]: true};
-
-/** Immutable provider version + source/content digest identity. */
-export type ProviderInstanceId = string & {
-  readonly [providerInstanceIdBrand]: true;
-};
-
-/** Lowercase `sha256:<64 hex characters>` digest. */
-export type ContentDigest = string & {readonly [contentDigestBrand]: true};
-
-/** Every stable artifact kind owned by a provider. */
-export type ContributionKind =
-  AuthoredDocKind | 'theme' | 'codemod' | 'agent-doc';
-
-/** Stable logical identity for one provider-owned artifact. */
-export interface ArtifactIdentity {
-  readonly id: ArtifactId;
-  readonly providerId: ProviderId;
-  readonly kind: ContributionKind;
-  readonly name: string;
-}
-
-/** One immutable package instance. Runtime lifecycle state does not belong here. */
-export interface ProviderInstance {
-  readonly id: ProviderInstanceId;
-  readonly providerId: ProviderId;
-  readonly packageName: string;
-  readonly packageVersion: string;
-  readonly sourceDigest: ContentDigest;
-}
-
-/** Every authored value accepted by the documentation compiler boundary. */
-export type AuthoredDoc =
-  | ComponentDoc
-  | HookDoc
-  | FunctionDoc
-  | ReferenceDoc
-  | TemplateDoc
-  | SchemaDoc
-  | CommandDoc
-  | EnumDoc
-  | NamespaceDoc;
-
-/** Provenance attached by discovery before compilation. */
-export interface AuthoredDocSource {
-  /** Provider-local logical discovery group. */
-  readonly group: string;
-  /** Package-relative source path; excluded from compiled renderer data. */
-  readonly path: string;
-  /** Digest of the authored source bytes. */
-  readonly digest: ContentDigest;
-}
-
-/** Authored kind that corresponds to one public document type. */
-export type AuthoredDocKindOf<TDoc extends AuthoredDoc> =
-  TDoc extends ComponentDoc
-    ? 'component'
-    : TDoc extends HookDoc | FunctionDoc
-      ? 'function'
-      : TDoc extends ReferenceDoc
-        ? 'generic'
-        : TDoc extends TemplateDoc
-          ? TDoc['type']
-          : TDoc extends SchemaDoc
-            ? 'schema'
-            : TDoc extends CommandDoc
-              ? 'command'
-              : TDoc extends EnumDoc
-                ? 'enum'
-                : TDoc extends NamespaceDoc
-                  ? 'namespace'
-                  : never;
-
-type DeepReadonly<Value> = Value extends (...args: never[]) => unknown
-  ? Value
-  : Value extends readonly (infer Item)[]
-    ? readonly DeepReadonly<Item>[]
-    : Value extends object
-      ? {readonly [Key in keyof Value]: DeepReadonly<Value[Key]>}
-      : Value;
-
-/** Immutable authored-data snapshot stored in a compiler entry. */
-export type AuthoredDocSnapshot<TDoc extends AuthoredDoc = AuthoredDoc> =
-  DeepReadonly<TDoc>;
-
-/**
- * One normalized compiler input. Stable identity is provider + authored kind +
- * stable name; provider version and source bytes remain explicit provenance.
- */
-export interface AuthoredDocEntry<TDoc extends AuthoredDoc = AuthoredDoc> {
-  readonly id: DocId;
-  readonly provider: ProviderInstance;
-  readonly kind: AuthoredDocKindOf<TDoc>;
-  /** Stable provider-local key used in the DocId; it need not equal a display name. */
-  readonly stableName: string;
-  readonly source: AuthoredDocSource;
-  readonly authored: AuthoredDocSnapshot<TDoc>;
-}

package/foundation/discovery/authoring-self-docs.d.mts

@@ -1,69 +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.
-
-/**
- * Every `*.doc.mjs` under `root`, relative and sorted.
- * @param {string} [root]
- * @returns {string[]}
- */
-export function discoverAuthoringSelfDocSources(root?: string): string[];
-/**
- * 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 function loadAuthoringSelfDocs(sources?: string[], root?: string): Promise<{
-    loaded: {
-        source: string;
-        doc: any;
-    }[];
-    failed: {
-        source: string;
-        error: string;
-    }[];
-}>;
-/**
- * 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: any[]): import("../../authoring/doctypes/reference/type").ReferenceDoc;
-/**
- * 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 function buildAuthoringTopic(): Promise<import("../../authoring/doctypes/reference/type").ReferenceDoc>;
-/**
- * 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 function auditAuthoringSelfDocs({ root, sources, budget, }?: {
-    root?: string;
-    sources?: string[];
-    budget?: number;
-}): Promise<{
-    sections: number;
-    unreachable: string[];
-    failed: {
-        source: string;
-        error: string;
-    }[];
-    oversized: {
-        key: string;
-        title: string;
-        bytes: number;
-    }[];
-}>;
-/** The directory the self-docs live under. */
-export const AUTHORING_ROOT: string;
-/** Every authoring self-doc, relative to {@link AUTHORING_ROOT}, in reading order. */
-export const AUTHORING_SELF_DOCS: string[];