@astryxdesign/cli 0.7.2-canary.db3a2e7 → 0.7.2-canary.e26723d

package/foundation/discovery/project-typescript.mjs

@@ -0,0 +1,61 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Find the project's own TypeScript compiler.
+ *
+ * @input Directories to resolve `typescript` from, in order.
+ * @output The compiler module and its version; or, when the only TypeScript
+ *   installed has no JavaScript compiler API to read types with, its version
+ *   alone; or null when none is installed.
+ * @position Shared by the author checks that read source with the project's
+ *   compiler, so each finds it, and says why it cannot use it, the same way.
+ */
+
+import * as path from 'node:path';
+import {createRequire} from 'node:module';
+
+/**
+ * Resolve the project's own `typescript`, trying each directory in order.
+ * @param {Array<string | null | undefined>} dirs
+ * @returns {{ts: any, version: string} | {ts: null, version: string} | null}
+ *   `ts: null` when a TypeScript is installed but has no `createProgram`
+ */
+export function resolveProjectTypeScript(dirs) {
+  /** @type {string | null} */
+  let unusable = null;
+  for (const dir of dirs) {
+    if (!dir) continue;
+    const require = createRequire(path.join(path.resolve(dir), 'package.json'));
+    /** The version of the `typescript` package installed here, or null. */
+    const installed = () => {
+      try {
+        const {version} = require('typescript/package.json');
+        return typeof version === 'string' && version !== '' ? version : null;
+      } catch {
+        return null;
+      }
+    };
+    try {
+      const ts = require('typescript');
+      if (ts && typeof ts.createProgram === 'function') {
+        return {ts, version: String(ts.version)};
+      }
+      unusable ??= installed();
+    } catch {
+      // Not installed from here, or installed without an entry this CLI can
+      // load; try the next directory.
+      unusable ??= installed();
+    }
+  }
+  return unusable ? {ts: null, version: unusable} : null;
+}
+
+/**
+ * Why a check that needs the compiler did not run, when the TypeScript
+ * installed has no JavaScript compiler API.
+ * @param {string} version
+ * @param {string} outcome what was not done, such as `docs were not checked`
+ */
+export function unusableTypeScriptReason(version, outcome) {
+  return `TypeScript ${version} is installed in this project, but it has no JavaScript compiler API (\`createProgram\`) to read types with, so ${outcome}.`;
+}

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

@@ -0,0 +1,220 @@
+// @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'} 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]
+ */
+/**
+ * @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} 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 {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
+ */
+/**
+ * @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. Install typescript and 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[];
+};
+export type PropDriftKind = "not_in_code" | "not_in_doc" | "required_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;
+};
+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 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;
+    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;
+};
+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;
+};