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

package/{src/lib → lib}/project.mjs

@@ -44,19 +44,42 @@ import {findCoreDir} from '../utils/paths.mjs';
 import {
   discoverTemplates,
   discoverIntegrationTemplatesForOne,
-} from '../api/template.mjs';
+} from '../api/template/template.mjs';
 import {getTransformsBetween} from '../codemods/registry.mjs';
 import {
   discoverIntegrationCodemods,
   selectIntegrationCodemods,
 } from '../codemods/integration-discovery.mjs';
-import {validateLoadedIntegration} from '../api/validate-integration.mjs';
+import {validateLoadedIntegration} from '../api/integration/validate-integration.mjs';
 import {
   InMemoryConfigCache,
   cacheKey,
   configContentHash,
 } from './config-cache.mjs';
 
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ * Reproduces the historical `err?.message ?? String(err)` behavior in a
+ * strict-checkJs-safe way: prefer a non-nullish `.message` (covers Error
+ * instances and error-like objects thrown by integration code), else `String()`.
+ * @param {unknown} err
+ * @returns {string}
+ */
+function errorMessage(err) {
+  const message =
+    err && typeof err === 'object' && 'message' in err
+      ? /** @type {{message: unknown}} */ (err).message
+      : undefined;
+  return message == null ? String(err) : String(message);
+}
+
+/**
+ * An integration issue tagged with the owner package. The base
+ * {@link import('../types/integration').AstryxIntegrationIssue} fields plus the
+ * `package` that produced it, which Project tracks for routing/dedup.
+ * @typedef {import('../types/integration').AstryxIntegrationIssue & {package: string}} ProjectIntegrationIssue
+ */
+
 /** Conventional config basenames, in load-precedence order. */
 export const CONFIG_BASENAMES = [
   'astryx.config.ts',
@@ -117,13 +140,13 @@ export class Project {
   #config;
   /** @type {string[]} */
   #integrations;
-  /** @type {Array<object>} */
+  /** @type {import('./integrations.mjs').LoadedIntegration[]} */
   #loadedIntegrations;
   /** @type {import('./config-cache.mjs').ConfigCache} */
   #cache;
   /** @type {string} */
   #hash;
-  /** @type {import('../types/integration').AstryxIntegrationIssue[]} */
+  /** @type {ProjectIntegrationIssue[]} */
   #issues = [];
   /**
    * Package names of integrations whose issues have already been collected
@@ -137,9 +160,9 @@ export class Project {
    * @param {object} init
    * @param {string} init.cwd
    * @param {string|null} init.configPath
-   * @param {object} init.config validated AstryxConfig surface
+   * @param {import('../types/config').AstryxConfig} init.config validated AstryxConfig surface
    * @param {string[]} init.integrations
-   * @param {Array<object>} init.loadedIntegrations
+   * @param {import('./integrations.mjs').LoadedIntegration[]} init.loadedIntegrations
    * @param {import('./config-cache.mjs').ConfigCache} init.cache
    * @param {string} init.hash config content hash
    */
@@ -175,8 +198,11 @@ export class Project {
     const configPath = findConfigPath(cwd);
     const hash = configContentHash(configPath);
 
+    /** @type {import('../types/config').AstryxConfig} */
     let config = {integrations: []};
+    /** @type {string[]} */
     let integrations = [];
+    /** @type {import('./integrations.mjs').LoadedIntegration[]} */
     let loadedIntegrations = [];
 
     if (configPath) {
@@ -204,7 +230,7 @@ export class Project {
   /**
    * The validated config surface (same data loadConfig returned, minus the
    * resolved `loadedIntegrations` which is exposed separately).
-   * @returns {{integrations?: string[], issuesUrl?: string, hooks?: object, experimental?: object}}
+   * @returns {import('../types/config').AstryxConfig}
    */
   get config() {
     return this.#config;
@@ -215,7 +241,7 @@ export class Project {
     return this.#integrations;
   }
 
-  /** Resolved loaded integrations (lib/integrations.mjs shape). @returns {Array<object>} */
+  /** Resolved loaded integrations (lib/integrations.mjs shape). @returns {import('./integrations.mjs').LoadedIntegration[]} */
   get loadedIntegrations() {
     return this.#loadedIntegrations;
   }
@@ -245,7 +271,7 @@ export class Project {
    */
   async #memo(kind, produce) {
     const key = cacheKey(this.#hash, this.#cwd, kind);
-    const hit = this.#cache.get(key);
+    const hit = /** @type {{value: T} | undefined} */ (this.#cache.get(key));
     if (hit !== undefined) return hit.value;
     const value = await produce();
     this.#cache.set(key, {value});
@@ -272,7 +298,10 @@ export class Project {
     });
   }
 
-  /** Package label for a loaded integration. */
+  /** Package label for a loaded integration.
+   * @param {import('./integrations.mjs').LoadedIntegration} integration
+   * @returns {string}
+   */
   #pkgLabel(integration) {
     return integration?.name ?? integration?.__spec ?? '(integration)';
   }
@@ -281,7 +310,7 @@ export class Project {
    * Validate one loaded integration and collect any issues. Marks the
    * integration visited so issues() won't redo the work. Best-effort: a
    * validator throwing is itself recorded as an issue, never propagated.
-   * @param {object} integration
+   * @param {import('./integrations.mjs').LoadedIntegration} integration
    */
   async #collectIssues(integration) {
     const pkg = this.#pkgLabel(integration);
@@ -294,7 +323,7 @@ export class Project {
       this.#pushIssue(pkg, {
         code: 'integration_error',
         severity: 'error',
-        message: err?.message ?? String(err),
+        message: errorMessage(err),
       });
     }
   }
@@ -311,7 +340,7 @@ export class Project {
   async components() {
     return this.#memo('components', async () => {
       const coreDir = findCoreDir(this.#cwd);
-      /** @type {Array<object>} */
+      /** @type {Array<{name: string, package: string, group: string|null, docPath: string|null, sourcePath: string|null, issuesUrl: string|undefined}>} */
       const records = [];
 
       // Core records (no integrations) — never integration-broken.
@@ -343,7 +372,7 @@ export class Project {
           this.#pushIssue(pkg, {
             code: 'invalid_component',
             severity: 'error',
-            message: err?.message ?? String(err),
+            message: errorMessage(err),
           });
         }
       }
@@ -362,7 +391,7 @@ export class Project {
    */
   async templates() {
     return this.#memo('templates', async () => {
-      /** @type {Array<object>} */
+      /** @type {any[]} */
       const templates = [];
 
       // Core + external-package templates (discoverTemplates internally also
@@ -371,7 +400,7 @@ export class Project {
       // path so the skip+warn policy and issue collection apply, then dedupe).
       try {
         const core = await discoverTemplates(this.#cwd);
-        for (const t of core) {
+        for (const t of /** @type {any[]} */ (core)) {
           // Skip integration-owned templates here; they are re-added (and
           // issue-collected) per integration below to honor skip+warn.
           if (t.package && t.package !== CORE_PACKAGE) continue;
@@ -405,7 +434,7 @@ export class Project {
           this.#pushIssue(pkg, {
             code: 'invalid_template',
             severity: 'error',
-            message: err?.message ?? String(err),
+            message: errorMessage(err),
           });
         }
       }
@@ -431,6 +460,7 @@ export class Project {
 
       // Discover integration codemods per integration so a single broken
       // integration is skipped (issue collected) without losing the others.
+      /** @type {import('./integrations.mjs').LoadedIntegration[]} */
       const good = [];
       for (const integration of this.#loadedIntegrations) {
         await this.#collectIssues(integration);
@@ -449,7 +479,7 @@ export class Project {
           this.#pushIssue(pkg, {
             code: 'invalid_codemod',
             severity: 'error',
-            message: err?.message ?? String(err),
+            message: errorMessage(err),
           });
         }
       }

package/{src/lib → lib}/project.test.mjs

@@ -13,7 +13,7 @@ let originalCwd;
 
 const codemodModulePath = path.resolve(
   process.cwd(),
-  'packages/cli/src/codemod.mjs',
+  'packages/cli/authoring/codemod.mjs',
 );
 const codemodModuleUrl = pathToFileURL(codemodModulePath).href;
 

package/{src/lib → lib}/resolve-theme.mjs

@@ -25,6 +25,9 @@ const _require = createRequire(import.meta.url);
 /**
  * Try to load a module, returning the default export or the module itself.
  * Returns null if the module cannot be found.
+ * @param {string} specifier
+ * @param {string} cwd
+ * @returns {unknown}
  */
 function tryLoadModule(specifier, cwd) {
   // For relative/absolute paths, resolve against cwd
@@ -49,6 +52,8 @@ function tryLoadModule(specifier, cwd) {
  * Extract theme data from a loaded module.
  * Handles both `module.default` and direct `module` patterns,
  * as well as named exports like `module.theme` or `module.{name}Theme`.
+ * @param {any} mod
+ * @returns {any}
  */
 function extractTheme(mod) {
   if (!mod || typeof mod !== 'object') return null;

package/{src/lib → lib}/string-utils.mjs

@@ -13,6 +13,10 @@ export {levenshteinDistance} from './levenshtein.mjs';
 /**
  * Find the closest component names to a given (possibly misspelled) name.
  * Returns matches sorted by distance, filtered to maxDistance.
+ * @param {string} name
+ * @param {Record<string, string[]>} components
+ * @param {number} [maxDistance]
+ * @returns {{name: string, distance: number}[]}
  */
 export function findClosestComponents(name, components, maxDistance = 3) {
   const allNames = Object.values(components).flat();
@@ -45,6 +49,11 @@ export function findClosestComponents(name, components, maxDistance = 3) {
  *    20  name Levenshtein distance 3
  *
  * Each result: { name, score, reason }
+ *
+ * @param {string} needle
+ * @param {string} coreDir
+ * @param {Record<string, string[]>} components
+ * @returns {Promise<{name: string, score: number, reason: string}[]>}
  */
 export async function searchComponents(needle, coreDir, components) {
   const {pathToFileURL} = await import('node:url');
@@ -53,8 +62,14 @@ export async function searchComponents(needle, coreDir, components) {
 
   const term = needle.toLowerCase();
   const allNames = Object.values(components).flat();
+  /** @type {Map<string, {name: string, score: number, reason: string}>} */
   const scored = new Map();
 
+  /**
+   * @param {string} name
+   * @param {number} score
+   * @param {string} reason
+   */
   function addMatch(name, score, reason) {
     const existing = scored.get(name);
     if (!existing || score > existing.score) {

package/{src/lib → lib}/term-log.mjs

@@ -15,12 +15,13 @@
  * primitive, which is a no-op in `--json` mode — so these human logs can never
  * corrupt a JSON envelope.
  *
- * Call sites use it as `import * as p from '../lib/term-log.mjs'` and call
+ * Call sites use it as `import * as p from './term-log.mjs'` and call
  * `p.log.info(...)`, `p.intro(...)`, `p.outro(...)`.
  */
 
 import {humanLog} from './json.mjs';
 
+/** @param {unknown} msg */
 const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
 
 /**
@@ -29,20 +30,28 @@ const toStr = (msg) => (msg === undefined || msg === null ? '' : String(msg));
  * every one of these, keeping machine-readable stdout clean.
  */
 export const log = {
+  /** @param {unknown} msg */
   message: (msg) => humanLog(toStr(msg)),
+  /** @param {unknown} msg */
   info: (msg) => humanLog(toStr(msg)),
+  /** @param {unknown} msg */
   step: (msg) => humanLog(toStr(msg)),
+  /** @param {unknown} msg */
   success: (msg) => humanLog(`✓ ${toStr(msg)}`),
+  /** @param {unknown} msg */
   warn: (msg) => humanLog(`⚠ ${toStr(msg)}`),
+  /** @param {unknown} msg */
   error: (msg) => humanLog(`✗ ${toStr(msg)}`),
 };
 
-/** Banner printed at the start of a multi-step command. */
+/** Banner printed at the start of a multi-step command.
+ * @param {unknown} title */
 export function intro(title) {
   humanLog(`\n${toStr(title)}`);
 }
 
-/** Footer printed at the end of a multi-step command. */
+/** Footer printed at the end of a multi-step command.
+ * @param {unknown} message */
 export function outro(message) {
   humanLog(`${toStr(message)}\n`);
 }

package/{src/lib → lib}/xle/browser.mjs

@@ -23,11 +23,21 @@ import {hydrateRegistry} from './registry-core.mjs';
 export {parse, detectForm, XLEParseError, validate, expand, toCompact, toOutline};
 export {hydrateRegistry, serializeRegistry, ALIAS_TABLE, resolveComponent, SPACING_STEPS} from './registry-core.mjs';
 
-/** Accept either a hydrated registry (Map fields) or serialized JSON. */
+/**
+ * Accept either a hydrated registry (Map fields) or serialized JSON.
+ * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry
+ * @returns {import('./xle-ast').Registry}
+ */
 function asRegistry(registry) {
-  return registry && registry.components instanceof Map ? registry : hydrateRegistry(registry);
+  return registry && /** @type {any} */ (registry).components instanceof Map
+    ? /** @type {import('./xle-ast').Registry} */ (registry)
+    : hydrateRegistry(/** @type {import('./browser').SerializedRegistry} */ (registry));
 }
 
+/**
+ * @param {import('./xle-ast').RawIssue | {message: string, line?: number, col?: number}} issue
+ * @returns {string}
+ */
 function formatIssue(issue) {
   const where = issue.line != null ? `line ${issue.line}: ` : '';
   return `${where}${issue.message}`;
@@ -38,12 +48,12 @@ function formatIssue(issue) {
  * twin of `layout check`. Never throws on invalid input; returns the errors.
  *
  * @param {string} expression
- * @param {object} registry - serialized or hydrated
+ * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry - serialized or hydrated
  * @param {object} [opts]
- * @param {Array} [opts.blocks] - block list for {hint} resolution (default [])
+ * @param {import('./browser').XLEBlock[]} [opts.blocks] - block list for {hint} resolution (default [])
  * @param {'compact'|'outline'|'auto'} [opts.form]
  * @param {boolean} [opts.loose]
- * @returns {{ok: boolean, valid?: boolean, form?: string, errors: Array, warnings: string[], compact?: string, outline?: string, parseError?: object}}
+ * @returns {import('./browser').CheckResult}
  */
 export function checkExpression(expression, registry, opts = {}) {
   const {blocks = [], form = 'auto', loose = false} = opts;
@@ -79,13 +89,13 @@ export function checkExpression(expression, registry, opts = {}) {
  * Returns either {code, ...} or {errors} (never writes files).
  *
  * @param {string} expression
- * @param {object} registry
+ * @param {import('./xle-ast').Registry | import('./browser').SerializedRegistry | object} registry
  * @param {object} [opts]
- * @param {Array} [opts.blocks]
+ * @param {import('./browser').XLEBlock[]} [opts.blocks]
  * @param {'compact'|'outline'|'auto'} [opts.form]
  * @param {boolean} [opts.loose]
  * @param {string} [opts.name] - generated component name (PascalCase)
- * @param {Map} [opts.blockModules] - prepared block sources/imports for splicing;
+ * @param {Map<string, import('./xle-ast').BlockModule>} [opts.blockModules] - prepared block sources/imports for splicing;
  *   omit in the browser (hints stay as TODO markers without sources)
  */
 export function expandExpression(expression, registry, opts = {}) {