@astryxdesign/cli 0.7.2-canary.fe2c655 → 0.7.2

package/foundation/discovery/prop-drift.d.mts

@@ -0,0 +1,297 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Compare each documented prop table with the TypeScript props of the export
+ * it describes.
+ * @param {PropDriftTable[]} tables
+ * @param {{packageDir: string, resolveFrom: Array<string | null | undefined>}} options
+ * @returns {PropDriftReport}
+ */
+export function comparePropTables(tables: PropDriftTable[], options: {
+    packageDir: string;
+    resolveFrom: Array<string | null | undefined>;
+}): PropDriftReport;
+/**
+ * Compare documented props with each component's TypeScript props: find each
+ * doc's prop tables, then compare them (`comparePropTables`).
+ * @param {PropDriftComponent[]} components
+ * @param {{packageDir: string, resolveFrom: Array<string | null | undefined>, loadDoc?: (docPath: string) => Promise<any>}} options
+ * @returns {Promise<PropDriftReport>}
+ */
+export function comparePropDocs(components: PropDriftComponent[], options: {
+    packageDir: string;
+    resolveFrom: Array<string | null | undefined>;
+    loadDoc?: (docPath: string) => Promise<any>;
+}): Promise<PropDriftReport>;
+/**
+ * @typedef {'not_in_code' | 'not_in_doc' | 'required_mismatch' | 'type_mismatch' | 'default_mismatch'} PropDriftKind
+ */
+/**
+ * @typedef {object} PropDriftFinding
+ * @property {string} component the documented component (export) name
+ * @property {string} prop
+ * @property {PropDriftKind} kind
+ * @property {'warning'} severity
+ * @property {string} message
+ * @property {string} doc the doc file, relative to the package root
+ * @property {string} source the source file, relative to the package root
+ * @property {string} [docType] the documented type, as written
+ * @property {string} [codeType] the type as the source declares it
+ * @property {boolean} [docRequired]
+ * @property {boolean} [codeRequired]
+ * @property {string} [docDefault] the documented default, as written
+ * @property {string} [codeDefault] the literal default the code writes
+ * @property {string} [fix] what to change, ready to paste
+ */
+/**
+ * @typedef {object} PropDriftUnchecked
+ * @property {string} component
+ * @property {string} doc the doc file, relative to the package root
+ * @property {string} reason why its props could not be read
+ */
+/**
+ * @typedef {object} PropDriftTypesNotCompared
+ * @property {string} component
+ * @property {string} doc the doc file, relative to the package root
+ * @property {string} reason why: not a form the check judges exactly, a
+ *   field the prop's variants give different types, a standard prop
+ *   (`className`, `style`, …), a prop declared outside the package, or a
+ *   default that is not a literal on one side
+ * @property {string[]} props documented props whose types, or defaults, were
+ *   not compared
+ */
+/**
+ * @typedef {object} PropDriftReport
+ * @property {'checked' | 'skipped'} status `skipped` means nothing was
+ *   compared, and `reason` says why
+ * @property {string} [reason]
+ * @property {string} [typescript] the version of the compiler that read the props
+ * @property {number} components how many documented prop tables were compared
+ * @property {number} typesCompared how many documented prop types were judged
+ * @property {string} [typesSkipped] why no prop type was judged
+ * @property {PropDriftFinding[]} findings
+ * @property {PropDriftUnchecked[]} unchecked documented components whose props
+ *   could not be read from the source
+ * @property {Array<PropDriftUnchecked & {props: string[]}>} [propsNotChecked]
+ *   props a mapped type builds from keys the check can't trace, which a doc
+ *   leaving out draws no warning for
+ * @property {PropDriftTypesNotCompared[]} typesNotCompared every other
+ *   documented prop type, grouped by why it was not judged
+ */
+/**
+ * @typedef {object} PropDriftTable
+ * @property {string} doc the doc file, relative to the package root
+ * @property {string} name the export the table documents
+ * @property {any[]} props the table's entries
+ * @property {string[]} sources the files that may hold the export, in order
+ */
+/**
+ * @typedef {object} PropDriftComponent
+ * @property {string} name
+ * @property {string} docPath absolute path to the component's `.doc.*` file
+ * @property {string | null} sourcePath absolute path to its same-stem
+ *   source, or null when no file in the package declares it (a family member
+ *   only another folder or built output defines)
+ */
+/**
+ * Props a doc never needs to list: the internal and styling props the
+ * `ComponentPropDoc` authoring guidance says to skip, `ref`, which Core's
+ * docs also leave out, and `key`, which React keeps for itself.
+ */
+export const PROPS_NOT_DOCUMENTED: readonly string[];
+/** The line both surfaces print when the compiler is missing. */
+export const TYPESCRIPT_MISSING_REASON: "TypeScript is not installed in this project, so documented props were not compared with the code. On TypeScript 7, add its TypeScript 6 API package (`npm install -D @typescript/typescript6`); otherwise install TypeScript 5.0 through 6 (`npm install -D typescript@6`). Then run this check again.";
+export type CodeProp = {
+    name: string;
+    /**
+     * whether every caller must pass it: false
+     * when a member of the props type, an overload, or the package's
+     * `defaultProps` lets a caller leave it out
+     */
+    required: boolean;
+    /**
+     * declared in the package's own source, or built
+     * from keys it writes
+     */
+    own: boolean;
+    /**
+     * built from keys the check can't trace
+     */
+    untraced?: boolean | undefined;
+    /**
+     * its declaration carries an internal JSDoc tag
+     */
+    skipTagged: boolean;
+    /**
+     * the type as written, per own declaration
+     */
+    declared: string[];
+    /**
+     * the compiler's renderings, computed on demand
+     */
+    renderings: () => string[][];
+    /**
+     * the prop's type in each member of the props type
+     */
+    types: () => any[];
+    /**
+     * one member declares it more than once (an
+     * intersection), so no one declaration's text is its type
+     */
+    intersected: boolean;
+    /**
+     * the type an index signature gives
+     * the name in each member that lacks the prop; null when two signatures
+     * in one member take it
+     */
+    indexed: () => any[] | null;
+    /**
+     * where names in the prop's type resolve
+     */
+    location: any;
+};
+export type PropDriftKind = "not_in_code" | "not_in_doc" | "required_mismatch" | "type_mismatch" | "default_mismatch";
+export type PropDriftFinding = {
+    /**
+     * the documented component (export) name
+     */
+    component: string;
+    prop: string;
+    kind: PropDriftKind;
+    severity: "warning";
+    message: string;
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * the source file, relative to the package root
+     */
+    source: string;
+    /**
+     * the documented type, as written
+     */
+    docType?: string | undefined;
+    /**
+     * the type as the source declares it
+     */
+    codeType?: string | undefined;
+    docRequired?: boolean | undefined;
+    codeRequired?: boolean | undefined;
+    /**
+     * the documented default, as written
+     */
+    docDefault?: string | undefined;
+    /**
+     * the literal default the code writes
+     */
+    codeDefault?: string | undefined;
+    /**
+     * what to change, ready to paste
+     */
+    fix?: string | undefined;
+};
+export type PropDriftUnchecked = {
+    component: string;
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * why its props could not be read
+     */
+    reason: string;
+};
+export type PropDriftTypesNotCompared = {
+    component: string;
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * why: not a form the check judges exactly, a
+     * field the prop's variants give different types, a standard prop
+     * (`className`, `style`, …), a prop declared outside the package, or a
+     * default that is not a literal on one side
+     */
+    reason: string;
+    /**
+     * documented props whose types, or defaults, were
+     * not compared
+     */
+    props: string[];
+};
+export type PropDriftReport = {
+    /**
+     * `skipped` means nothing was
+     * compared, and `reason` says why
+     */
+    status: "checked" | "skipped";
+    reason?: string | undefined;
+    /**
+     * the version of the compiler that read the props
+     */
+    typescript?: string | undefined;
+    /**
+     * how many documented prop tables were compared
+     */
+    components: number;
+    /**
+     * how many documented prop types were judged
+     */
+    typesCompared: number;
+    /**
+     * why no prop type was judged
+     */
+    typesSkipped?: string | undefined;
+    findings: PropDriftFinding[];
+    /**
+     * documented components whose props
+     * could not be read from the source
+     */
+    unchecked: PropDriftUnchecked[];
+    /**
+     * props a mapped type builds from keys the check can't trace, which a doc
+     * leaving out draws no warning for
+     */
+    propsNotChecked?: (PropDriftUnchecked & {
+        props: string[];
+    })[] | undefined;
+    /**
+     * every other
+     * documented prop type, grouped by why it was not judged
+     */
+    typesNotCompared: PropDriftTypesNotCompared[];
+};
+export type PropDriftTable = {
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * the export the table documents
+     */
+    name: string;
+    /**
+     * the table's entries
+     */
+    props: any[];
+    /**
+     * the files that may hold the export, in order
+     */
+    sources: string[];
+};
+export type PropDriftComponent = {
+    name: string;
+    /**
+     * absolute path to the component's `.doc.*` file
+     */
+    docPath: string;
+    /**
+     * absolute path to its same-stem
+     * source, or null when no file in the package declares it (a family member
+     * only another folder or built output defines)
+     */
+    sourcePath: string | null;
+};