@astryxdesign/cli 0.7.2-canary.ebcc404 → 0.7.2-canary.f8f7cf1

package/foundation/discovery/doc-types.d.mts

@@ -0,0 +1,157 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Check each doc file's values against the published authoring types.
+ * @param {DocFile[]} files
+ * @param {{packageDir: string, resolveFrom: Array<string | null | undefined>, core?: boolean}} options
+ *   `core`: the docs are Core's own, so templates are held to TemplateDoc
+ * @returns {Promise<DocTypesReport>}
+ */
+export function checkDocTypes(files: DocFile[], options: {
+    packageDir: string;
+    resolveFrom: Array<string | null | undefined>;
+    core?: boolean;
+}): Promise<DocTypesReport>;
+/**
+ * @typedef {'components' | 'hooks' | 'templates' | 'docs' | 'docs-overlay' | 'themes'} DocRoot
+ */
+/**
+ * @typedef {object} DocFile
+ * @property {string} path absolute path to the doc file
+ * @property {DocRoot} root the contribution root it was found in
+ */
+/**
+ * @typedef {'unknown_field' | 'missing_field' | 'wrong_type'} DocTypeProblem
+ */
+/**
+ * @typedef {object} DocTypeFinding
+ * @property {string} doc the doc file, relative to the package root
+ * @property {number} line 1-based line of the field (or of the doc value)
+ * @property {string} export the export checked (`default`, `docs`, `docsZh`, …)
+ * @property {string} type the authoring type it was checked against
+ * @property {string} field the field's path in the doc, such as
+ *   `usage.bestPractices[2].guidance`; empty for the doc value as a whole
+ * @property {DocTypeProblem} problem
+ * @property {'warning'} severity
+ * @property {string} message what TypeScript reports, shortened
+ * @property {string} fix what to change
+ */
+/**
+ * @typedef {object} DocTypesUnchecked
+ * @property {string} doc the doc file, relative to the package root
+ * @property {string} reason why it was not checked
+ */
+/**
+ * @typedef {object} DocTypesReport
+ * @property {'checked' | 'skipped'} status `skipped` means nothing was checked,
+ *   and `reason` says why
+ * @property {string} [reason]
+ * @property {string} [typescript] the version of the compiler that checked
+ * @property {number} docs how many doc values were checked
+ * @property {DocTypeFinding[]} findings
+ * @property {DocTypesUnchecked[]} unchecked doc files with nothing to check,
+ *   or not fully checked
+ */
+/** The line both surfaces print when the compiler is missing. */
+export const DOC_TYPES_TYPESCRIPT_MISSING_REASON: "TypeScript is not installed in this project, so docs were not checked against the authoring types. Install typescript and run this check again.";
+export type DocRoot = "components" | "hooks" | "templates" | "docs" | "docs-overlay" | "themes";
+export type DocFile = {
+    /**
+     * absolute path to the doc file
+     */
+    path: string;
+    /**
+     * the contribution root it was found in
+     */
+    root: DocRoot;
+};
+export type DocTypeProblem = "unknown_field" | "missing_field" | "wrong_type";
+export type DocTypeFinding = {
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * 1-based line of the field (or of the doc value)
+     */
+    line: number;
+    /**
+     * the export checked (`default`, `docs`, `docsZh`, …)
+     */
+    export: string;
+    /**
+     * the authoring type it was checked against
+     */
+    type: string;
+    /**
+     * the field's path in the doc, such as
+     * `usage.bestPractices[2].guidance`; empty for the doc value as a whole
+     */
+    field: string;
+    problem: DocTypeProblem;
+    severity: "warning";
+    /**
+     * what TypeScript reports, shortened
+     */
+    message: string;
+    /**
+     * what to change
+     */
+    fix: string;
+};
+export type DocTypesUnchecked = {
+    /**
+     * the doc file, relative to the package root
+     */
+    doc: string;
+    /**
+     * why it was not checked
+     */
+    reason: string;
+};
+export type DocTypesReport = {
+    /**
+     * `skipped` means nothing was checked,
+     * and `reason` says why
+     */
+    status: "checked" | "skipped";
+    reason?: string | undefined;
+    /**
+     * the version of the compiler that checked
+     */
+    typescript?: string | undefined;
+    /**
+     * how many doc values were checked
+     */
+    docs: number;
+    findings: DocTypeFinding[];
+    /**
+     * doc files with nothing to check,
+     * or not fully checked
+     */
+    unchecked: DocTypesUnchecked[];
+};
+export type Target = {
+    exportName: string;
+    /**
+     * the doc value's expression
+     */
+    node: any;
+    /**
+     * the authoring type, as a type expression
+     */
+    typeExpr: string;
+    /**
+     * how findings name that type
+     */
+    typeName: string;
+    /**
+     * nodes whose leading JSDoc annotations are blanked
+     */
+    blank: any[];
+    /**
+     * source ranges to blank
+     */
+    blankRanges: Array<[number, number]>;
+};