@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db7b338

package/foundation/integrations/contribution-fixes.d.mts

@@ -0,0 +1,145 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Identify contribution metadata without importing it. Doctor scans files that
+ * the manifest does not declare, so executing those files would run code the
+ * package never asked Astryx to load.
+ *
+ * @param {string} file
+ * @param {boolean} templateOnly
+ * @returns {ContributionStamp | null} null when it is not contribution metadata
+ */
+export function readContributionStamp(file: string, templateOnly: boolean): ContributionStamp | null;
+/** @param {string} candidate @param {string} root */
+export function pathIsInside(candidate: string, root: string): boolean;
+/**
+ * @param {string} packageDir
+ * @param {{components?: string, templates?: string, codemods?: string, docs?: string, themes?: string, __manifestFile?: string}} integration
+ * @returns {FixContext}
+ */
+export function createFixContext(packageDir: string, integration: {
+    components?: string;
+    templates?: string;
+    codemods?: string;
+    docs?: string;
+    themes?: string;
+    __manifestFile?: string;
+}): FixContext;
+/**
+ * The static stamp of a candidate metadata file, read once per context.
+ * @param {FixContext} context
+ * @param {string} file
+ * @returns {ContributionStamp | null}
+ */
+export function stampOf(context: FixContext, file: string): ContributionStamp | null;
+/**
+ * The fix for every codemods entry when the codemods root also holds the rest
+ * of the package: it is the package root, or it holds another root. No
+ * per-entry move or rename helps then.
+ * @param {FixContext} context
+ * @param {string} [stray] a stray file's name, which may itself be a codemod
+ * @returns {string | null}
+ */
+export function sharedCodemodsRootFix(context: FixContext, stray?: string): string | null;
+/**
+ * The fix for a codemods folder that holds another root, which a rename would
+ * break.
+ * @param {FixContext} context
+ * @param {string} folder
+ * @returns {string | null}
+ */
+export function heldRootFix(context: FixContext, folder: string): string | null;
+/**
+ * The fix for contribution metadata that sits outside every declared root.
+ * @param {FixContext} context
+ * @param {string} file
+ * @param {ContributionStamp} stamp
+ * @returns {string}
+ */
+export function unreachableFix(context: FixContext, file: string, stamp: ContributionStamp): string;
+/**
+ * The step a component doc added to the components root also needs when
+ * another root reads that folder too, and would read the new doc as its own.
+ * @param {FixContext} context
+ * @returns {string} a sentence with a leading space, or ''
+ */
+export function newComponentDocNote(context: FixContext): string;
+/**
+ * The theme beside \`file\` whose source imports it, if any: such a file is
+ * part of that theme, not a codemod.
+ * @param {FixContext} context
+ * @param {string} file
+ * @returns {{doc: string, stamp: ContributionStamp, source: string} | null}
+ */
+export function themeImporting(context: FixContext, file: string): {
+    doc: string;
+    stamp: ContributionStamp;
+    source: string;
+} | null;
+/**
+ * The fix for contribution metadata at the top of the codemods root, which
+ * the codemod checks read as a stray codemod. `source` names that doc's theme
+ * source when the stray file is the source rather than the doc.
+ * @param {FixContext} context
+ * @param {string} file the metadata doc
+ * @param {ContributionStamp} stamp
+ * @param {string} [source]
+ * @param {string} [stray] a file that source imports, when the stray file is
+ *   that one
+ * @returns {string}
+ */
+export function notACodemodFix(context: FixContext, file: string, stamp: ContributionStamp, source?: string, stray?: string): string;
+/**
+ * The fix for a doc that the components root reads although its type says it
+ * is another kind of metadata.
+ * @param {FixContext} context
+ * @param {string} file
+ * @param {ContributionStamp} stamp a stamp whose type is not `component`
+ * @returns {string}
+ */
+export function notAComponentFix(context: FixContext, file: string, stamp: ContributionStamp): string;
+/** @typedef {'components' | 'templates' | 'docs' | 'themes'} MetadataRoot */
+/**
+ * @typedef {object} ContributionStamp
+ * @property {string} type
+ * @property {string | null} name the static `name`, when it has one
+ */
+/**
+ * @typedef {object} FixContext
+ * @property {string} packageDir
+ * @property {string} manifest file name of the package's manifest
+ * @property {Partial<Record<MetadataRoot | 'codemods', string>>} roots
+ *   declared roots, absolute
+ * @property {Map<string, ContributionStamp | null>} stamps
+ * @property {Map<string, string[] | null>} candidates
+ */
+export const DOC_CANDIDATE_RE: RegExp;
+export const TEMPLATE_CANDIDATE_RE: RegExp;
+/** Stray-codemod and version-folder rules, shared with the codemod checks. */
+export const CODEMOD_FILE_RE: RegExp;
+export const CODEMOD_TEST_RE: RegExp;
+export const CODEMOD_SKIP_DIRS: Set<string>;
+/** The manifest root that reads each kind of contribution metadata. */
+export const ROOT_FOR_TYPE: Record<string, MetadataRoot>;
+export type MetadataRoot = "components" | "templates" | "docs" | "themes";
+export type ContributionStamp = {
+    type: string;
+    /**
+     * the static `name`, when it has one
+     */
+    name: string | null;
+};
+export type FixContext = {
+    packageDir: string;
+    /**
+     * file name of the package's manifest
+     */
+    manifest: string;
+    /**
+     *   declared roots, absolute
+     */
+    roots: Partial<Record<MetadataRoot | "codemods", string>>;
+    stamps: Map<string, ContributionStamp | null>;
+    candidates: Map<string, string[] | null>;
+};