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

package/foundation/discovery/template-adapter.test.mjs

@@ -17,7 +17,9 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import {
+  effectiveTemplateDiscovery,
   extractComponents,
+  findPageDocFile,
   stripTemplateAssetRefs,
 } from './template-adapter.mjs';
 
@@ -164,3 +166,58 @@ describe('stripTemplateAssetRefs', () => {
     );
   });
 });
+
+describe('findPageDocFile', () => {
+  it('keeps the released precedence when one page has two specs', () => {
+    const page = fs.mkdtempSync(path.join(dir, 'page-'));
+    fs.writeFileSync(path.join(page, 'template.doc.mjs'), 'export {};\n');
+    fs.writeFileSync(path.join(page, 'template.doc.ts'), 'export {};\n');
+    expect(findPageDocFile(page)).toBe(path.join(page, 'template.doc.ts'));
+
+    fs.writeFileSync(path.join(page, 'template.template.mjs'), 'export {};\n');
+    expect(findPageDocFile(page)).toBe(
+      path.join(page, 'template.template.mjs'),
+    );
+  });
+});
+
+describe('effectiveTemplateDiscovery', () => {
+  it('shadows only the matching template kind', () => {
+    const pageReplacement = {
+      type: 'page',
+      dirName: 'acme-dashboard',
+      name: 'Acme dashboard',
+      description: '',
+      filePath: '/acme-dashboard.tsx',
+      docPath: '/acme-dashboard.doc.mjs',
+      package: '@acme/widgets',
+      replaces: 'dashboard',
+    };
+    const corePage = {
+      type: 'page',
+      dirName: 'dashboard',
+      name: 'Dashboard page',
+      description: '',
+      filePath: '/dashboard-page.tsx',
+      docPath: '/dashboard-page.doc.mjs',
+    };
+    const coreBlock = {
+      type: 'block',
+      dirName: 'dashboard',
+      name: 'Dashboard block',
+      description: '',
+      filePath: '/dashboard-block.tsx',
+      docPath: '/dashboard-block.doc.mjs',
+    };
+
+    const effective = effectiveTemplateDiscovery([
+      corePage,
+      coreBlock,
+      pageReplacement,
+    ]);
+
+    expect(effective).toContain(pageReplacement);
+    expect(effective).toContain(coreBlock);
+    expect(effective).not.toContain(corePage);
+  });
+});

package/foundation/discovery/template-conflict-release.d.mts

@@ -0,0 +1,13 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * Whether this release exposes replacement relationships in the public conflict API.
+ * Both the supported version and a deliberate projection update are required;
+ * a routine package-version bump cannot expand the public shape by itself.
+ *
+ * @param {string} [version]
+ * @param {'warning-only' | 'expanded'} [projection]
+ * @returns {boolean}
+ */
+export function expandedTemplateConflictSchemaActive(version?: string, projection?: "warning-only" | "expanded"): boolean;

package/foundation/discovery/template-conflict-release.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Release boundary for the expanded integration-template conflict schema.
+ *
+ * @input The CLI package version and an explicit public-schema projection.
+ * @output Whether replacement-specific conflict fields may reach the stable API.
+ * @position Private compatibility gate for integration authoring diagnostics.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {semverCompare} from '../env/semver.mjs';
+import {CLI_ROOT} from '../fs/paths.mjs';
+
+const EXPANDED_TEMPLATE_CONFLICT_SCHEMA_CLI = '0.7.0';
+/** @type {'warning-only' | 'expanded'} */
+const TEMPLATE_CONFLICT_SCHEMA_PROJECTION = 'warning-only';
+const CLI_VERSION = JSON.parse(
+  fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf8'),
+).version;
+
+/**
+ * Whether this release exposes replacement relationships in the public conflict API.
+ * Both the supported version and a deliberate projection update are required;
+ * a routine package-version bump cannot expand the public shape by itself.
+ *
+ * @param {string} [version]
+ * @param {'warning-only' | 'expanded'} [projection]
+ * @returns {boolean}
+ */
+export function expandedTemplateConflictSchemaActive(
+  version = CLI_VERSION,
+  projection = TEMPLATE_CONFLICT_SCHEMA_PROJECTION,
+) {
+  return (
+    projection === 'expanded' &&
+    semverCompare(version, EXPANDED_TEMPLATE_CONFLICT_SCHEMA_CLI) >= 0
+  );
+}

package/foundation/discovery/template-conflict-release.test.mjs

@@ -0,0 +1,40 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Unit coverage for the integration-template conflict release boundary.
+ * @input CLI versions and explicit warning-only or expanded projections.
+ * @output Boolean activation assertions for the expanded conflict schema.
+ * @position Colocated coverage for the private release gate.
+ */
+
+import {describe, expect, it} from 'vitest';
+import {expandedTemplateConflictSchemaActive} from './template-conflict-release.mjs';
+
+describe('expandedTemplateConflictSchemaActive', () => {
+  it.each(['0.6.3', '0.6.4', '0.6.99'])(
+    'keeps %s narrow even when the expanded projection is requested',
+    version => {
+      expect(expandedTemplateConflictSchemaActive(version, 'expanded')).toBe(
+        false,
+      );
+    },
+  );
+
+  it.each(['0.7.0-rc.1', '0.7.0', '0.8.0'])(
+    'does not let version %s expand the warning-only projection',
+    version => {
+      expect(
+        expandedTemplateConflictSchemaActive(version, 'warning-only'),
+      ).toBe(false);
+    },
+  );
+
+  it.each(['0.7.0-rc.1', '0.7.0', '0.8.0'])(
+    'allows the deliberate expanded projection in %s',
+    version => {
+      expect(expandedTemplateConflictSchemaActive(version, 'expanded')).toBe(
+        true,
+      );
+    },
+  );
+});

package/foundation/discovery/theme-discovery.d.mts

@@ -2,15 +2,65 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * Read and validate one theme catalog.
- * @param {string} themeRoot absolute catalog root
- * @param {string} owner package that owns the catalog
- * @param {{bundled?: boolean}} [options]
+ * How messages about a theme descriptor name it.
+ * @param {string} docPath
+ * @param {string} owner
+ */
+export function themeDescriptorLabel(docPath: string, owner: string): string;
+/**
+ * The static value a theme descriptor default-exports, read from its source
+ * without executing it. Throws when the file is not one static ThemeDoc
+ * object.
+ * @param {string} docPath
+ * @param {string} label
+ * @returns {Record<string, string | boolean>}
+ */
+export function readThemeDescriptorValue(docPath: string, label: string): Record<string, string | boolean>;
+/**
+ * Whether an entry at any depth of a themes root is outside every theme: a dot
+ * entry, or a name npm never publishes (npm-packlist's defaults).
+ * @param {string} name
+ */
+export function isIgnoredThemeEntry(name: string): boolean;
+/**
+ * Whether discovery reads a folder under a theme root as a theme. Dot-folders
+ * and folders with neither a descriptor nor a `<name>Theme` source are not.
+ * @param {string} folder absolute path
+ */
+export function isThemeFolder(folder: string): boolean;
+/**
+ * The files one theme folder ships: every regular file below it except
+ * {@link isIgnoredThemeEntry} entries. What pack-check requires and what
+ * `theme add` copies.
+ * @param {string} folder absolute path
+ * @returns {string[]} sorted POSIX paths relative to the folder
+ */
+export function listThemeFiles(folder: string): string[];
+/**
+ * Discover and validate one theme root.
+ * @param {string} themeRoot absolute root containing one directory per slug
+ * @param {string} owner package that owns the root
+ * @param {{bundled?: boolean}} [options] a bundled root is the CLI's own; its
+ *   sources are checked by the CLI's tests rather than on every read
  * @returns {DiscoveredTheme[]}
  */
-export function discoverThemeCatalog(themeRoot: string, owner: string, { bundled }?: {
+export function discoverThemeDirectory(themeRoot: string, owner: string, { bundled }?: {
     bundled?: boolean;
 }): DiscoveredTheme[];
+/**
+ * Folders under a themes root that look like themes (see looksLikeTheme)
+ * but that discovery does not read as themes, and that no module elsewhere
+ * under the root imports, by a relative path or through the package's own
+ * name. Discovery skips them silently, as the released catalog skipped
+ * unlisted folders; doctor warns.
+ * @param {string} themeRoot
+ * @param {{packageDir?: string, packageName?: string}} [owner]
+ * @returns {string[]} absolute folder paths, sorted
+ */
+export function unreadThemeFolders(themeRoot: string, { packageDir, packageName }?: {
+    packageDir?: string;
+    packageName?: string;
+}): string[];
 /** @returns {DiscoveredTheme[]} */
 export function discoverBundledThemes(): DiscoveredTheme[];
 /**
@@ -20,8 +70,10 @@ export function discoverBundledThemes(): DiscoveredTheme[];
 export function discoverIntegrationThemes(integration: import("../integrations/integrations.mjs").LoadedIntegration): Promise<DiscoveredTheme[]>;
 export const BUNDLED_THEME_PACKAGE: "@astryxdesign/cli";
 export const THEMES_DIR: string;
-export const THEME_MANIFEST_BASENAME: "manifest.json";
-export const MANIFEST_PATH: string;
+export const THEME_DOC_SUFFIX: ".doc.mjs";
+export const THEME_MODULE_EXTENSIONS: string[];
+/** A theme directory's name: lower-kebab, starting with a letter. */
+export const THEME_SLUG_RE: RegExp;
 export type DiscoveredTheme = {
     slug: string;
     displayName: string;
@@ -29,6 +81,10 @@ export type DiscoveredTheme = {
     maintained: boolean;
     entry: string;
     exportName: string;
+    /**
+     * what `theme add` copies, relative to sourceDir,
+     * entry first
+     */
     files: string[];
     package: string;
     /**
@@ -36,4 +92,8 @@ export type DiscoveredTheme = {
      */
     sourceDir: string;
     bundled: boolean;
+    /**
+     * absolute descriptor path
+     */
+    docPath: string;
 };