@astryxdesign/cli 0.1.2 → 0.1.3

package/src/lib/config-cache.mjs

@@ -0,0 +1,91 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Pluggable config/discovery cache for the Project API.
+ *
+ * The Project class memoizes resolved discovery (components, templates,
+ * codemods, config) behind a small key/value cache so the same work is never
+ * repeated within a single Project instance. The cache interface is
+ * intentionally tiny — `get(key)` / `set(key, value)` — so a future
+ * file-backed, cross-process cache can drop in with NO API change.
+ *
+ * Cache keys are derived from a CONTENT HASH of the project's config file
+ * (see {@link configContentHash}) combined with the cwd and the
+ * discovery-kind (+ args). The in-memory implementation never busts on a
+ * content change, but the hash is computed regardless so a hash-busting,
+ * file-backed cache works against the exact same key path.
+ *
+ * @typedef {Object} ConfigCache
+ * @property {(key: string) => unknown} get
+ * @property {(key: string, value: unknown) => void} set
+ */
+
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+
+/**
+ * Stable sentinel hash used when there is no config file (or it can't be
+ * read). Keeps key derivation total — every cwd still produces a key.
+ */
+export const NO_CONFIG_HASH = 'no-config';
+
+/**
+ * Compute a stable content hash for a config file. Reads the file bytes and
+ * returns their sha256 hex digest; a missing/unreadable file yields
+ * {@link NO_CONFIG_HASH}. The hash is the bust signal a future file-backed
+ * cache would key on.
+ *
+ * @param {string | null | undefined} configPath absolute config path, or null
+ * @returns {string}
+ */
+export function configContentHash(configPath) {
+  if (!configPath) return NO_CONFIG_HASH;
+  try {
+    const bytes = fs.readFileSync(configPath);
+    return crypto.createHash('sha256').update(bytes).digest('hex');
+  } catch {
+    return NO_CONFIG_HASH;
+  }
+}
+
+/**
+ * Build a cache key from a config content hash, a cwd, and a discovery kind
+ * (already including any args, e.g. `codemods:0.1.0..0.2.0`). The shape is
+ * stable so the same inputs always map to the same key.
+ *
+ * @param {string} hash config content hash
+ * @param {string} cwd
+ * @param {string} kind discovery kind (+args)
+ * @returns {string}
+ */
+export function cacheKey(hash, cwd, kind) {
+  return `${hash}\u0000${cwd}\u0000${kind}`;
+}
+
+/**
+ * Default in-memory cache. Per-instance by default (the Project creates one in
+ * {@link Project.load} when none is supplied), so it behaves like simple
+ * memoization. A shared instance can be passed to reuse results across
+ * Projects. Never busts — a content change produces a different KEY (via the
+ * hash), not an eviction, which is exactly the behavior a future file-backed
+ * cache also relies on.
+ *
+ * @implements {ConfigCache}
+ */
+export class InMemoryConfigCache {
+  /** @type {Map<string, unknown>} */
+  #m = new Map();
+
+  /** @param {string} key */
+  get(key) {
+    return this.#m.get(key);
+  }
+
+  /**
+   * @param {string} key
+   * @param {unknown} value
+   */
+  set(key, value) {
+    this.#m.set(key, value);
+  }
+}

package/src/lib/config-cache.test.mjs

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {
+  InMemoryConfigCache,
+  cacheKey,
+  configContentHash,
+  NO_CONFIG_HASH,
+} from './config-cache.mjs';
+
+let tmpDir;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-cache-test-'));
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('InMemoryConfigCache', () => {
+  it('stores and returns values by key', () => {
+    const cache = new InMemoryConfigCache();
+    expect(cache.get('a')).toBeUndefined();
+    cache.set('a', 42);
+    expect(cache.get('a')).toBe(42);
+  });
+
+  it('can store falsy values distinctly from a miss', () => {
+    const cache = new InMemoryConfigCache();
+    cache.set('zero', {value: 0});
+    expect(cache.get('zero')).toEqual({value: 0});
+    expect(cache.get('missing')).toBeUndefined();
+  });
+});
+
+describe('configContentHash', () => {
+  it('returns the sentinel when there is no config path', () => {
+    expect(configContentHash(null)).toBe(NO_CONFIG_HASH);
+    expect(configContentHash(undefined)).toBe(NO_CONFIG_HASH);
+  });
+
+  it('returns the sentinel for a missing file', () => {
+    expect(configContentHash(path.join(tmpDir, 'nope.mjs'))).toBe(
+      NO_CONFIG_HASH,
+    );
+  });
+
+  it('is stable for the same bytes', () => {
+    const file = path.join(tmpDir, 'astryx.config.mjs');
+    fs.writeFileSync(file, 'export default { integrations: [] };\n');
+    const a = configContentHash(file);
+    const b = configContentHash(file);
+    expect(a).toBe(b);
+    expect(a).not.toBe(NO_CONFIG_HASH);
+  });
+
+  it('differs when the config content changes', () => {
+    const file = path.join(tmpDir, 'astryx.config.mjs');
+    fs.writeFileSync(file, 'export default { integrations: [] };\n');
+    const before = configContentHash(file);
+    fs.writeFileSync(file, 'export default { integrations: ["@x/y"] };\n');
+    const after = configContentHash(file);
+    expect(before).not.toBe(after);
+  });
+});
+
+describe('cacheKey', () => {
+  it('is stable for identical inputs and varies by kind', () => {
+    const k1 = cacheKey('hash', '/cwd', 'components');
+    const k2 = cacheKey('hash', '/cwd', 'components');
+    const k3 = cacheKey('hash', '/cwd', 'templates');
+    expect(k1).toBe(k2);
+    expect(k1).not.toBe(k3);
+  });
+
+  it('varies by hash and cwd', () => {
+    expect(cacheKey('h1', '/cwd', 'k')).not.toBe(cacheKey('h2', '/cwd', 'k'));
+    expect(cacheKey('h', '/a', 'k')).not.toBe(cacheKey('h', '/b', 'k'));
+  });
+});

package/src/lib/config-schema.mjs

@@ -8,77 +8,63 @@ const Fn = z.custom(value => typeof value === 'function', {
   message: 'Expected function',
 });
 
-const StringOrStringArray = z.union([z.string(), z.array(z.string())]);
-const GapReportSchema = z.union([
-  z.literal(false),
-  z.object({command: z.string()}).passthrough(),
-]);
-
-export const AstryxConfigSchema = z
+export const PostCodemodHookSchema = z
   .object({
-    packages: StringOrStringArray.optional(),
-    integrations: StringOrStringArray.optional(),
-    gapReport: GapReportSchema.optional(),
-    template: z
-      .object({
-        get: Fn.optional(),
-      })
-      .passthrough()
-      .optional(),
+    name: z.string().optional(),
+    buildCommand: Fn,
   })
-  .passthrough();
+  .strict();
 
-export const AstryxIntegrationCodemodSchema = z
+export const XleComponentSchema = z
   .object({
-    name: z.string(),
-    from: z.string().optional(),
-    to: z.string().optional(),
-    title: z.string().optional(),
+    from: z.string(),
     description: z.string().optional(),
-    pr: z.string().optional(),
-    optional: z.boolean().optional(),
-    fileExtensions: z.array(z.string()).optional(),
-    transform: z.union([z.string(), Fn]),
+    default: z.boolean().optional(),
   })
-  .passthrough();
+  .strict();
 
-export const AstryxPostCodemodHookSchema = z
+export const AstryxConfigSchema = z
   .object({
-    name: z.string().optional(),
-    run: Fn.optional(),
-    command: Fn.optional(),
+    integrations: z.array(z.string()).optional(),
+    issuesUrl: z.string().url().optional(),
+    hooks: z
+      .object({
+        postCodemod: z.array(PostCodemodHookSchema).optional(),
+      })
+      .strict()
+      .optional(),
+    experimental: z
+      .object({
+        xle: z
+          .object({
+            components: z.record(z.string(), XleComponentSchema).optional(),
+          })
+          .strict()
+          .optional(),
+      })
+      .strict()
+      .optional(),
   })
-  .passthrough()
-  .refine(value => value.run || value.command, {
-    message: 'postCodemod hook must define run() or command()',
-  });
+  .strict();
 
 export const AstryxIntegrationSchema = z
   .object({
-    name: z.string(),
-    version: z.string().optional(),
-    displayName: z.string().optional(),
-    description: z.string().optional(),
-    docs: z.string().optional(),
-    category: z.string().optional(),
-    blocks: z.string().optional(),
-    gapReport: GapReportSchema.optional(),
-    template: z
-      .object({
-        get: z.union([z.string(), Fn]).optional(),
-      })
-      .passthrough()
-      .optional(),
-    codemods: z.array(AstryxIntegrationCodemodSchema).optional(),
-    postCodemod: z.array(AstryxPostCodemodHookSchema).optional(),
+    components: z.string().optional(),
+    templates: z.string().optional(),
+    codemods: z.string().optional(),
+    issuesUrl: z.string().url().optional(),
   })
-  .passthrough();
+  .strict();
 
 /**
+ * Format a zod error into a single readable line, mirroring the issue-joining
+ * convention used across the CLI (path: message; path: message). Exported so
+ * the shared module loader and other validators stay in lockstep.
  * @param {string} label
  * @param {import('zod').ZodError} error
+ * @returns {string}
  */
-function formatZodError(label, error) {
+export function formatZodError(label, error) {
   const issues = error.issues
     .map(issue => {
       const path = issue.path.length ? issue.path.join('.') : '(root)';
@@ -96,7 +82,7 @@ export function validateConfig(config) {
   const result = AstryxConfigSchema.safeParse(config);
   if (!result.success) {
     throw new Error(
-      formatZodError('astryx.config.mjs default export', result.error),
+      formatZodError('astryx.config default export', result.error),
     );
   }
   return result.data;
@@ -105,7 +91,7 @@ export function validateConfig(config) {
 /**
  * @param {unknown} integration
  * @param {string} [label]
- * @returns {import('../types/config').AstryxIntegration}
+ * @returns {import('../types/integration').AstryxIntegration}
  */
 export function validateIntegration(
   integration,

package/src/lib/error-codes.mjs

@@ -52,6 +52,8 @@
  *   | 'ERR_UNKNOWN_SECTION'
  *   | 'ERR_UNKNOWN_CATEGORY'
  *   | 'ERR_UNKNOWN_TEMPLATE'
+ *   | 'ERR_AMBIGUOUS_TEMPLATE'
+ *   | 'ERR_AMBIGUOUS_COMPONENT'
  *   | 'ERR_UNKNOWN_THEME'
  *   | 'ERR_UNKNOWN_PACKAGE'
  *   | 'ERR_UNKNOWN_AGENT'
@@ -69,13 +71,12 @@
  *   | 'ERR_WRITE_FAILED'
  *   | 'ERR_THEME_INVALID'
  *   | 'ERR_THEME_LOAD'
- *   | 'ERR_TEMPLATE_CONFIG'
- *   | 'ERR_TEMPLATE_GET'
  *   | 'ERR_VERSION_DETECT'
  *   | 'ERR_INVALID_VERSION'
  *   | 'ERR_DEP_MISSING'
  *   | 'ERR_GH_CLI'
- *   | 'ERR_GAP_REPORT_FAILED'
+ *   | 'ERR_UNKNOWN_POST'
+ *   | 'ERR_FETCH_FAILED'
  *   | 'ERR_LAYOUT_PARSE'
  *   | 'ERR_LAYOUT_INVALID'
  * )} ErrorCode
@@ -125,6 +126,10 @@ export const ERROR_CODES = Object.freeze({
   ERR_UNKNOWN_CATEGORY: 'ERR_UNKNOWN_CATEGORY',
   /** No template matched the requested name. */
   ERR_UNKNOWN_TEMPLATE: 'ERR_UNKNOWN_TEMPLATE',
+  /** A template id matched more than one template (narrow with --type/--package). */
+  ERR_AMBIGUOUS_TEMPLATE: 'ERR_AMBIGUOUS_TEMPLATE',
+  /** A component name is owned by more than one package (narrow with --package). */
+  ERR_AMBIGUOUS_COMPONENT: 'ERR_AMBIGUOUS_COMPONENT',
   /** No theme matched the requested slug (theme add). */
   ERR_UNKNOWN_THEME: 'ERR_UNKNOWN_THEME',
   /** No package matched the requested name (discover). */
@@ -166,12 +171,6 @@ export const ERROR_CODES = Object.freeze({
   /** A theme file could not be loaded / parsed into a defineTheme result. */
   ERR_THEME_LOAD: 'ERR_THEME_LOAD',
 
-  // ── Template config ──────────────────────────────────────────────
-  /** `template.get` is not configured in astryx.config.mjs (fetch-by-id). */
-  ERR_TEMPLATE_CONFIG: 'ERR_TEMPLATE_CONFIG',
-  /** A configured `template.get` threw or returned an invalid value. */
-  ERR_TEMPLATE_GET: 'ERR_TEMPLATE_GET',
-
   // ── Upgrade ──────────────────────────────────────────────────────
   /** The current `@astryxdesign/core` version could not be detected. */
   ERR_VERSION_DETECT: 'ERR_VERSION_DETECT',
@@ -180,11 +179,15 @@ export const ERROR_CODES = Object.freeze({
   /** A required external dependency (e.g. jscodeshift) is missing. */
   ERR_DEP_MISSING: 'ERR_DEP_MISSING',
 
-  // ── Gap report ───────────────────────────────────────────────────
+  // ── GitHub CLI ───────────────────────────────────────────────────
   /** GitHub CLI (`gh`) is not installed or not authenticated. */
   ERR_GH_CLI: 'ERR_GH_CLI',
-  /** Filing a gap report failed at the command/integration boundary. */
-  ERR_GAP_REPORT_FAILED: 'ERR_GAP_REPORT_FAILED',
+
+  // ── Blog (read via the published RSS feed) ───────────────────────
+  /** No blog post matched the requested slug in the feed. */
+  ERR_UNKNOWN_POST: 'ERR_UNKNOWN_POST',
+  /** A network fetch (RSS feed or post text) failed. */
+  ERR_FETCH_FAILED: 'ERR_FETCH_FAILED',
 
   // ── Layout expressions (XLE/XLO) ─────────────────────────────────
   /** A layout expression failed to parse (syntax error, with line/col). */

package/src/lib/integration-warnings.mjs

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Compact, non-blocking integration-issue nudge for everyday commands.
+ *
+ * When a CONFIGURED integration (from the Project's `loadedIntegrations`) has
+ * validation issues, the everyday commands (component / template / upgrade)
+ * should print ONE compact, non-blocking line per integration telling the user
+ * to run `validate-integration` — instead of silently skipping broken
+ * contributions or spamming per-contribution diagnostics.
+ *
+ * Design constraints (all enforced here):
+ *   - Reuses the validate-integration validators (validateLoadedIntegration);
+ *     no validation logic is duplicated.
+ *   - Writes to STDERR only, so it never corrupts a --json stdout envelope.
+ *   - Suppressed entirely in --json mode.
+ *   - Best-effort: never throws, never changes the exit code. Broken
+ *     contributions are still skipped downstream exactly as before; this only
+ *     ADDS a one-line nudge.
+ */
+
+import {validateLoadedIntegration} from '../api/validate-integration.mjs';
+
+/**
+ * For each configured (already-loaded) integration, compute its issues using
+ * the shared validate-integration validators and, if any exist, print exactly
+ * ONE line per integration to stderr:
+ *
+ *   Warning: <pkg> has N integration issue(s). Run: astryx validate-integration <pkg>
+ *
+ * @param {Array<object>} loadedIntegrations the Project's loaded integrations
+ * @param {{json?: boolean}} [options]
+ * @returns {Promise<void>}
+ */
+export async function warnOnIntegrationIssues(loadedIntegrations, {json = false} = {}) {
+  try {
+    // Cheap guard: only do work when integrations are actually configured.
+    if (json) return;
+    if (!Array.isArray(loadedIntegrations) || loadedIntegrations.length === 0) {
+      return;
+    }
+    for (const integration of loadedIntegrations) {
+      if (!integration || typeof integration !== 'object') continue;
+      let issues;
+      try {
+        issues = await validateLoadedIntegration(integration);
+      } catch {
+        // Best-effort: a validator throwing must not break the host command.
+        continue;
+      }
+      if (!Array.isArray(issues) || issues.length === 0) continue;
+      const pkg = integration.name ?? integration.__spec ?? '(integration)';
+      // Stderr only — keeps stdout (and any --json envelope) clean.
+      console.error(
+        `Warning: ${pkg} has ${issues.length} integration issue(s). ` +
+          `Run: astryx validate-integration ${pkg}`,
+      );
+    }
+  } catch {
+    // Never throw, never change the exit code.
+  }
+}

package/src/lib/integration-warnings.test.mjs

@@ -0,0 +1,102 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Hermetic tests for the compact integration-issue nudge.
+ *
+ * Builds loaded-integration-shaped objects (as produced by
+ * lib/integrations.mjs) with absolute contribution roots under the repo root
+ * (process.cwd()) so any node_modules-style path stays within Vite's allowed
+ * fs roots. We never load configs from /tmp. The helper is exercised directly;
+ * stderr is captured to assert exactly one warning line per broken integration
+ * and zero output in --json mode / for clean integrations.
+ */
+
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {warnOnIntegrationIssues} from './integration-warnings.mjs';
+
+let tmpDir;
+let errSpy;
+let errLines;
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(process.cwd(), '.astryx-warn-it-'));
+  errLines = [];
+  errSpy = vi.spyOn(console, 'error').mockImplementation((...args) => {
+    errLines.push(args.join(' '));
+  });
+});
+
+afterEach(() => {
+  errSpy.mockRestore();
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+/**
+ * Build a loaded-integration-shaped object. Roots are absolute (mirrors
+ * loadIntegrations' resolveRoot).
+ */
+function loaded({name = '@acme/widgets', components, templates, codemods} = {}) {
+  return {
+    name,
+    version: '1.0.0',
+    components: components == null ? undefined : path.join(tmpDir, components),
+    templates: templates == null ? undefined : path.join(tmpDir, templates),
+    codemods: codemods == null ? undefined : path.join(tmpDir, codemods),
+    __spec: name,
+    __packageDir: tmpDir,
+  };
+}
+
+describe('warnOnIntegrationIssues', () => {
+  it('emits exactly one stderr line for an integration with issues', async () => {
+    // Declared components root that does not exist on disk → missing_root.
+    const integration = loaded({components: 'does-not-exist'});
+    await warnOnIntegrationIssues([integration], {json: false});
+
+    expect(errLines).toHaveLength(1);
+    expect(errLines[0]).toBe(
+      'Warning: @acme/widgets has 1 integration issue(s). ' +
+        'Run: astryx validate-integration @acme/widgets',
+    );
+  });
+
+  it('emits nothing in --json mode (keeps stdout/JSON clean)', async () => {
+    const integration = loaded({components: 'does-not-exist'});
+    await warnOnIntegrationIssues([integration], {json: true});
+    expect(errLines).toHaveLength(0);
+  });
+
+  it('emits nothing for an integration with no issues', async () => {
+    // Existing components root with no broken contributions → no issues.
+    const componentsRoot = path.join(tmpDir, 'components');
+    fs.mkdirSync(componentsRoot, {recursive: true});
+    const integration = loaded({components: 'components'});
+    await warnOnIntegrationIssues([integration], {json: false});
+    expect(errLines).toHaveLength(0);
+  });
+
+  it('emits nothing when there are no configured integrations', async () => {
+    await warnOnIntegrationIssues([], {json: false});
+    await warnOnIntegrationIssues(undefined, {json: false});
+    expect(errLines).toHaveLength(0);
+  });
+
+  it('emits one line per broken integration', async () => {
+    const a = loaded({name: '@acme/a', components: 'missing-a'});
+    const b = loaded({name: '@acme/b', templates: 'missing-b'});
+    await warnOnIntegrationIssues([a, b], {json: false});
+    expect(errLines).toHaveLength(2);
+    expect(errLines[0]).toContain('@acme/a');
+    expect(errLines[1]).toContain('@acme/b');
+  });
+
+  it('never throws and never emits when a validator misbehaves', async () => {
+    // A non-object entry must be skipped silently.
+    await expect(
+      warnOnIntegrationIssues([null, 'nope', 42], {json: false}),
+    ).resolves.toBeUndefined();
+    expect(errLines).toHaveLength(0);
+  });
+});