@astryxdesign/cli 0.1.8-canary.0c4d8d7 → 0.1.8-canary.0db5dfd

package/{src → cli}/commands/validate-integration.mjs

@@ -14,37 +14,34 @@
  * an integration package is not a failure).
  */
 
-import {jsonOut, humanLog} from '../lib/json.mjs';
+import {jsonOut, humanLog} from '../../lib/json.mjs';
 import {
-  validateLocalIntegration,
-  validateInstalledIntegration,
+  validateIntegration,
   summarizeIssues,
-} from '../api/validate-integration.mjs';
+} from '../../api/integration/validate-integration.mjs';
 
 /**
  * Render a validation result for humans.
- * @param {import('../api/validate-integration.mjs').ValidateResult} result
+ * @param {import('../../types/validate-integration').ValidateIntegrationResponse['data']} data
  */
-function printHuman(result) {
+function printHuman(data) {
   const label =
-    result.version != null
-      ? `${result.name}@${result.version}`
-      : result.name;
+    data.version != null ? `${data.name}@${data.version}` : data.name;
   humanLog(`Validating integration: ${label}`);
 
-  if (result.issues.length === 0) {
+  if (data.issues.length === 0) {
     humanLog('\n\u2713 No issues found.');
     return;
   }
 
   humanLog('');
-  for (const issue of result.issues) {
+  for (const issue of data.issues) {
     humanLog(`  ${issue.severity} ${issue.code}: ${issue.message}`);
   }
 
-  const {errors, warnings} = summarizeIssues(result.issues);
+  const {errors, warnings} = summarizeIssues(data.issues);
   humanLog(
-    `\n${result.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
+    `\n${data.issues.length} issue(s): ${errors} error(s), ${warnings} warning(s)`,
   );
 }
 
@@ -74,35 +71,18 @@ export function registerValidateIntegration(program) {
     .action(async pkg => {
       const json = program.opts().json || false;
 
-      const result = pkg
-        ? await validateInstalledIntegration(pkg)
-        : await validateLocalIntegration();
-
-      // No-arg + no local manifest: guidance, not an error.
-      if (!result.found) {
-        if (json) {
-          jsonOut('integration.validate', {
-            name: null,
-            version: null,
-            issues: [],
-          });
-        } else {
-          humanLog(NO_MANIFEST_GUIDANCE);
-        }
-        return;
-      }
+      const result = await validateIntegration(pkg);
 
       if (json) {
-        jsonOut('integration.validate', {
-          name: result.name ?? null,
-          version: result.version ?? null,
-          issues: result.issues,
-        });
+        jsonOut(result.type, result.data);
+      } else if (result.data.name === null) {
+        // No-arg + no local manifest: guidance, not an error.
+        humanLog(NO_MANIFEST_GUIDANCE);
       } else {
-        printHuman(result);
+        printHuman(result.data);
       }
 
-      const {errors} = summarizeIssues(result.issues);
+      const {errors} = summarizeIssues(result.data.issues);
       if (errors > 0) {
         process.exitCode = 1;
       }

package/{src → cli}/index.mjs

@@ -11,15 +11,15 @@ import {Command, Option} from 'commander';
 import {fileURLToPath} from 'node:url';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {checkForUpdate} from './utils/update-check.mjs';
-import {getCliInvocation} from './utils/package-manager.mjs';
-import {API_VERSION, setJsonMode} from './lib/json.mjs';
-import {buildManifest} from './lib/manifest.mjs';
-import {cliError} from './lib/cli-error.mjs';
-import {ERROR_CODES} from './lib/error-codes.mjs';
-import {levenshteinDistance} from './lib/string-utils.mjs';
-import {installJsonShim} from './lib/json-shim.mjs';
-import {isAstryxInitialized} from './commands/agent-docs.mjs';
+import {checkForUpdate} from '../utils/update-check.mjs';
+import {getCliInvocation} from '../utils/package-manager.mjs';
+import {API_VERSION, setJsonMode} from '../lib/json.mjs';
+import {buildManifest} from '../lib/manifest.mjs';
+import {cliError} from '../lib/cli-error.mjs';
+import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {levenshteinDistance} from '../lib/string-utils.mjs';
+import {installJsonShim} from '../lib/json-shim.mjs';
+import {isAstryxInitialized} from '../lib/agent-docs/agent-docs.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -56,6 +56,7 @@ export const JSON_SUPPORTED = new Set([
   'docs',
   'discover',
   'search',
+  'build',
   'swizzle',
   'template',
   'hook',
@@ -102,7 +103,7 @@ program
     if (extras.length > 0) {
       const unknown = String(extras[0]);
       const known = (program.commands || [])
-        .filter((c) => !c._hidden && c.name() !== 'help')
+        .filter((c) => !(/** @type {any} */ (c)._hidden) && c.name() !== 'help')
         .map((c) => c.name());
       const close = known
         .map((name) => ({name, distance: levenshteinDistance(unknown.toLowerCase(), name.toLowerCase())}))
@@ -162,6 +163,7 @@ program
  */
 function fullCommandName(actionCommand) {
   const parts = [];
+  /** @type {import('commander').Command | null} */
   let cmd = actionCommand;
   while (cmd && cmd !== program) {
     parts.unshift(cmd.name());
@@ -307,10 +309,10 @@ for (const cmd of commands) {
     // Command fails to load but CLI still works
     program
       .command(cmd.name)
-      .description(`(failed to load: ${e.message})`)
+      .description(`(failed to load: ${/** @type {any} */ (e).message})`)
       .action(() => {
         console.error(`Command "${cmd.name}" failed to load:`);
-        console.error(e.message);
+        console.error(/** @type {any} */ (e).message);
         process.exit(1);
       });
   }
@@ -348,9 +350,9 @@ program
   .command('postinstall', {hidden: true})
   .action(() => {
     const r = getCliInvocation();
-    const pad = (s, len) => s + ' '.repeat(Math.max(0, len - s.length));
+    const pad = (/** @type {string} */ s, /** @type {number} */ len) => s + ' '.repeat(Math.max(0, len - s.length));
     const W = 49; // inner width of the box
-    const line = (s) => `  │ ${pad(s, W)}│`;
+    const line = (/** @type {string} */ s) => `  │ ${pad(s, W)}│`;
     console.log(`
   ╭${'─'.repeat(W + 2)}╮
 ${line('')}
@@ -376,5 +378,5 @@ ${line('')}
 // patch outputHelp on every command (root + subcommands). The shim
 // extends the --json contract to cover Commander's parse-time short
 // circuits (parse errors, unknown options, --help, unknown commands).
-// See packages/cli/src/lib/json-shim.mjs for the rationale.
+// See packages/cli/lib/json-shim.mjs for the rationale.
 installJsonShim(program);

package/{src/codemods → codemods}/ensure-jscodeshift.mjs

@@ -64,7 +64,7 @@ function installJscodeshift(silent = false) {
     log.success('jscodeshift installed.');
     return true;
   } catch (err) {
-    log.error(`Failed to install jscodeshift: ${err.message}`);
+    log.error(`Failed to install jscodeshift: ${/** @type {any} */ (err).message}`);
     return false;
   }
 }

package/{src/codemods → codemods}/integration-discovery.mjs

@@ -27,7 +27,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {loadModuleWithSchema} from '../lib/module-loader.mjs';
-import {CodemodEnvelopeSchema} from '../codemod.mjs';
+import {CodemodEnvelopeSchema} from '../authoring/codemod.mjs';
 import {semverCompare} from '../utils/semver.mjs';
 
 /** File extensions recognized as codemod modules. */
@@ -41,6 +41,7 @@ const CODEMOD_EXTENSIONS = ['.ts', '.mjs', '.js'];
  * @returns {Array<{id: string, file: string}>}
  */
 function collectCodemodFiles(versionDir) {
+  /** @type {Array<{id: string, file: string}>} */
   const out = [];
 
   /** @param {string} dir */
@@ -74,7 +75,7 @@ function collectCodemodFiles(versionDir) {
  *   for that version (across all integrations).
  */
 export async function discoverIntegrationCodemods(loadedIntegrations = []) {
-  /** @type {Map<string, Array<{id: string, type: string, codemod: object, package: string}>>} */
+  /** @type {Map<string, Array<{id: string, type: 'code'|'config', codemod: object, package: string}>>} */
   const byVersion = new Map();
 
   for (const integration of loadedIntegrations ?? []) {
@@ -158,10 +159,12 @@ export async function discoverIntegrationCodemods(loadedIntegrations = []) {
  */
 export function selectIntegrationCodemods(byVersion, from, to) {
   const versions = [...byVersion.keys()].sort(semverCompare);
+  /** @type {Array<{version: string, codemods: Array<object>}>} */
   const results = [];
   for (const version of versions) {
     if (semverCompare(version, from) > 0 && semverCompare(version, to) <= 0) {
-      results.push({version, codemods: byVersion.get(version)});
+      const codemods = byVersion.get(version);
+      if (codemods) results.push({version, codemods});
     }
   }
   return results;

package/{src/codemods → codemods}/integration-discovery.test.mjs

@@ -54,7 +54,7 @@ function scaffold(codemodFiles) {
 // from the vitest cwd (the repo root) instead.
 const codemodModulePath = path.resolve(
   process.cwd(),
-  'packages/cli/src/codemod.mjs',
+  'packages/cli/authoring/codemod.mjs',
 );
 const codemodModuleUrl = pathToFileURL(codemodModulePath).href;
 

package/{src/codemods → codemods}/integration-runner.mjs

@@ -31,15 +31,15 @@ import {
  * Optional codemods (isOptional) are skipped unless explicitly requested via
  * `codemod` (matched against the codemod id).
  *
- * @param {Array<{version: string, codemods: Array<object>}>} versionGroups
+ * @param {Array<{version: string, codemods: Array<import('../types/codemod').CodemodEntry>}>} versionGroups
  * @param {object} options
  * @param {boolean} options.apply
  * @param {string} options.path source directory to scan
  * @param {string} [options.codemod] run only this codemod id
  * @param {Set<string>} [options.skipCodemods] codemod ids to exclude
- * @param {Function} options.jscodeshift
+ * @param {import('../types/codemod').JscodeshiftFactory} options.jscodeshift
  * @param {boolean} [options.silent]
- * @returns {{totalFilesChanged: number, totalTransformsApplied: number, writtenFiles: string[], errors: Array, skippedOptional: Array}}
+ * @returns {{totalFilesChanged: number, totalTransformsApplied: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<import('../types/codemod').CodemodEntry>}}
  */
 export function runIntegrationCodemods(
   versionGroups,
@@ -49,12 +49,17 @@ export function runIntegrationCodemods(
 
   let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
+  /** @type {string[]} */
   const writtenFiles = [];
+  /** @type {Array<{file: string, codemod: string, error: string}>} */
   const errors = [];
+  /** @type {Array<import('../types/codemod').CodemodEntry>} */
   const skippedOptional = [];
 
   // Flatten and split by type, preserving version ordering.
+  /** @type {Array<import('../types/codemod').CodemodEntry>} */
   const configEntries = [];
+  /** @type {Array<import('../types/codemod').CodemodEntry>} */
   const codeEntries = [];
   for (const {version, codemods} of versionGroups) {
     for (const entry of codemods) {

package/{src/codemods → codemods}/registry.mjs

@@ -45,16 +45,18 @@ export const latestVersion = versions[versions.length - 1];
  *
  * @param {string} from - Current version (exclusive)
  * @param {string} to - Target version (inclusive)
- * @returns {Promise<Array<{version: string, transforms: Array<{name: string, module: Function}>}>>}
+ * @returns {Promise<Array<{version: string, transforms: Array<{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string}}>}>>}
  */
 export async function getTransformsBetween(from, to) {
   const applicable = versions.filter(
     v => semverCompare(v, from) > 0 && semverCompare(v, to) <= 0,
   );
+  /** @type {Array<{version: string, transforms: Array<{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string}}>}>} */
   const results = [];
 
   for (const version of applicable) {
     const loader = registry.get(version);
+    if (!loader) continue;
     const manifest = await loader();
     results.push({
       version,

package/{src/codemods → codemods}/run-codemod.mjs

@@ -49,7 +49,9 @@ const PARSEABLE_EXTENSIONS = ['.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs'];
  * @returns {string[]}
  */
 export function findSourceFiles(dir) {
+  /** @type {string[]} */
   const results = [];
+  /** @param {string} currentDir */
   function walk(currentDir) {
     let entries;
     try {
@@ -74,6 +76,7 @@ export function findSourceFiles(dir) {
 /**
  * No-op log surface for silent (`--json`) mode.
  * @param {boolean} silent
+ * @returns {import('../types/codemod').CliLog}
  */
 export function makeLog(silent) {
   return silent
@@ -84,9 +87,9 @@ export function makeLog(silent) {
 /**
  * Apply a config codemod to the consumer's astryx.config.* file.
  *
- * @param {object} entry normalized codemod entry {id, codemod, package}
- * @param {{apply: boolean, log: object, jscodeshift: Function}} ctx
- * @returns {{filesChanged: number, writtenFiles: string[], errors: Array}}
+ * @param {import('../types/codemod').CodemodEntry} entry normalized codemod entry {id, codemod, package}
+ * @param {{apply: boolean, log: import('../types/codemod').CliLog, jscodeshift: import('../types/codemod').JscodeshiftFactory}} ctx
+ * @returns {import('../types/codemod').CodemodRunResult}
  */
 export function runConfigCodemod(entry, {apply, log, jscodeshift}) {
   const {codemod, id, package: pkg} = entry;
@@ -135,11 +138,12 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {
       errors: [],
     };
   } catch (err) {
-    log.error(`    ✗ ${relativePath} — ${err.message}`);
+    const message = /** @type {any} */ (err).message;
+    log.error(`    ✗ ${relativePath} — ${message}`);
     return {
       filesChanged: 0,
       writtenFiles: [],
-      errors: [{file: relativePath, codemod: name, error: err.message}],
+      errors: [{file: relativePath, codemod: name, error: message}],
     };
   }
 }
@@ -147,10 +151,10 @@ export function runConfigCodemod(entry, {apply, log, jscodeshift}) {
 /**
  * Apply a code codemod to discovered source files.
  *
- * @param {object} entry normalized codemod entry {id, codemod, package}
+ * @param {import('../types/codemod').CodemodEntry} entry normalized codemod entry {id, codemod, package}
  * @param {string[]} files
- * @param {{apply: boolean, log: object, jscodeshift: Function}} ctx
- * @returns {{filesChanged: number, writtenFiles: string[], errors: Array}}
+ * @param {{apply: boolean, log: import('../types/codemod').CliLog, jscodeshift: import('../types/codemod').JscodeshiftFactory}} ctx
+ * @returns {import('../types/codemod').CodemodRunResult}
  */
 export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {
   const {codemod, id, package: pkg} = entry;
@@ -158,7 +162,9 @@ export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {
   const extensions = new Set(codemod.fileExtensions ?? DEFAULT_CODE_EXTENSIONS);
 
   let filesChanged = 0;
+  /** @type {string[]} */
   const writtenFiles = [];
+  /** @type {Array<{file: string, codemod: string, error: string}>} */
   const errors = [];
 
   for (const filePath of files) {
@@ -198,8 +204,9 @@ export function runCodeCodemod(entry, files, {apply, log, jscodeshift}) {
         log.warn(`    ~ ${relativePath} (would change)`);
       }
     } catch (err) {
-      log.error(`    ✗ ${relativePath} — ${err.message}`);
-      errors.push({file: relativePath, codemod: name, error: err.message});
+      const message = /** @type {any} */ (err).message;
+      log.error(`    ✗ ${relativePath} — ${message}`);
+      errors.push({file: relativePath, codemod: name, error: message});
     }
   }
 

package/{src/codemods → codemods}/runner.mjs

@@ -51,6 +51,7 @@ export function fixDirectiveCorruption(code) {
  * @returns {string[]}
  */
 function findSourceFiles(dir) {
+  /** @type {string[]} */
   const results = [];
   const extensions = new Set([
     '.tsx',
@@ -65,6 +66,7 @@ function findSourceFiles(dir) {
     '.less',
   ]);
 
+  /** @param {string} currentDir */
   function walk(currentDir) {
     let entries;
     try {
@@ -96,8 +98,9 @@ function findSourceFiles(dir) {
  *
  * @param {string} result - The transformed source code
  * @param {string} source - The original source code
- * @param {Function} j - jscodeshift instance (with parser configured)
- * @returns {{ valid: boolean, reason?: string }}
+ * @param {import('../types/codemod').JscodeshiftFactory} j - jscodeshift instance (with parser configured)
+ * @param {{parse?: boolean}} [options]
+ * @returns {{ valid: true } | { valid: false, reason: string }}
  */
 export function validateOutput(result, source, j, {parse = true} = {}) {
   // Check 1: Re-parse the output — catches syntax-breaking corruption
@@ -105,9 +108,10 @@ export function validateOutput(result, source, j, {parse = true} = {}) {
     try {
       j(result);
     } catch (parseError) {
+      const message = /** @type {any} */ (parseError).message;
       return {
         valid: false,
-        reason: `transform produced unparseable output: ${parseError.message}`,
+        reason: `transform produced unparseable output: ${message}`,
       };
     }
   }
@@ -147,9 +151,9 @@ export function validateOutput(result, source, j, {parse = true} = {}) {
  * with the same `(file, api) => string | null | undefined` contract used by
  * `createConfigCodemod`.
  *
- * @param {{name: string, transform: Function, meta: object, optional?: boolean}} transformEntry
+ * @param {{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, optional?: boolean}} transformEntry
  * @param {string} version
- * @returns {{id: string, type: 'code'|'config', codemod: object, package: string, version: string}}
+ * @returns {import('../types/codemod').CodemodEntry}
  */
 function toUnifiedEntry(transformEntry, version) {
   const {name, transform, meta, optional} = transformEntry;
@@ -171,14 +175,14 @@ function toUnifiedEntry(transformEntry, version) {
 /**
  * Run codemods against source files.
  *
- * @param {Array<{version: string, transforms: Array}>} versionManifests
+ * @param {Array<{version: string, transforms: Array<{name: string, transform: import('../types/codemod').CodemodTransform, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, optional?: boolean}>}>} versionManifests
  * @param {object} options
  * @param {boolean} options.apply - Write changes to disk
  * @param {string} options.path - Source directory to scan
  * @param {string|undefined} options.codemod - Run only this specific transform
  * @param {Set<string>} [options.skipCodemods] - Transform names to exclude
  * @param {boolean} [options.silent] - Suppress all human-facing output (for --json)
- * @returns {{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], errors: Array, skippedOptional: Array}}
+ * @returns {Promise<{totalFilesChanged: number, totalTransformsApplied: number, totalValidationBlocked: number, writtenFiles: string[], errors: Array<{file: string, codemod: string, error: string}>, skippedOptional: Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} | {ok: false, reason: string, resolvedPath: string}>}
  */
 export async function runCodemods(
   versionManifests,
@@ -208,11 +212,11 @@ export async function runCodemods(
     return {ok: false, reason: 'source_path_missing', resolvedPath};
   }
 
+  /** @type {string[]} */
   let files = [];
   if (sourcePathExists) {
     log.step(`Scanning ${resolvedPath} for source files...`);
     files = findSourceFiles(resolvedPath);
-
     if (files.length === 0) {
       log.warn('No source files found.');
     } else {
@@ -223,15 +227,20 @@ export async function runCodemods(
   }
 
   // Dynamically import jscodeshift
-  const jscodeshift = (await import('jscodeshift')).default;
+  const jscodeshift =
+    /** @type {import('../types/codemod').JscodeshiftFactory} */ (
+      (await import('jscodeshift')).default
+    );
 
   let totalFilesChanged = 0;
   let totalTransformsApplied = 0;
   let totalValidationBlocked = 0;
+  /** @type {Array<{file: string, codemod: string, error: string}>} */
   const errors = [];
+  /** @type {string[]} */
   const writtenFiles = [];
+  /** @type {Array<{name: string, meta: {title: string, description?: string, fileExtensions?: string[], codemodType?: string}, version: string}>} */
   const skippedOptional = [];
-
   for (const {version, transforms} of versionManifests) {
     log.step(`Applying v${version} codemods...`);
 
@@ -333,8 +342,9 @@ export async function runCodemods(
             }
           }
         } catch (err) {
-          log.error(`    ✗ ${relativePath} — ${err.message}`);
-          errors.push({file: relativePath, codemod: name, error: err.message});
+          const message = /** @type {any} */ (err).message;
+          log.error(`    ✗ ${relativePath} — ${message}`);
+          errors.push({file: relativePath, codemod: name, error: message});
         }
       }
 

package/{src/codemods → codemods}/transforms/v0.0.10/remove-size-props.mjs

@@ -32,6 +32,11 @@ export const meta = {
   pr: '#966',
 };
 
+/**
+ * @param {import('../../../types/codemod').AstryxCodemodFile} file
+ * @param {import('../../../types/codemod').CodemodTransformApi} api
+ * @returns {string | null | undefined}
+ */
 export default function transformer(file, api) {
   const j = api.jscodeshift;
   const root = j(file.source);
@@ -40,7 +45,7 @@ export default function transformer(file, api) {
   // 1. Remove size JSX prop from target components
   root
     .find(j.JSXOpeningElement)
-    .filter((path) => {
+    .filter((/** @type {any} */ path) => {
       const name = path.node.name;
       // Handle simple names like <XDSStatusDot>
       if (name.type === 'JSXIdentifier') {
@@ -48,10 +53,10 @@ export default function transformer(file, api) {
       }
       return false;
     })
-    .forEach((path) => {
+    .forEach((/** @type {any} */ path) => {
       const attrs = path.node.attributes;
       const sizeIdx = attrs.findIndex(
-        (attr) =>
+        (/** @type {any} */ attr) =>
           attr.type === 'JSXAttribute' &&
           attr.name &&
           attr.name.name === 'size',
@@ -63,7 +68,7 @@ export default function transformer(file, api) {
     });
 
   // 2. Remove size type imports (XDSStatusDotSize, XDSProgressBarSize)
-  root.find(j.ImportDeclaration).forEach((path) => {
+  root.find(j.ImportDeclaration).forEach((/** @type {any} */ path) => {
     const specifiers = path.node.specifiers;
     if (!specifiers) return;