@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/foundation/discovery/template-adapter.d.mts

@@ -11,11 +11,39 @@ export function pkgOf(t: {
     package?: string;
 }): string;
 /**
- * Replace demo asset references with a placeholder so scaffolded pages
- * render with zero setup. Images get a self-contained data URI; videos
- * (which have no equivalent inline placeholder — see VIDEO_EXTENSIONS) are
- * stripped to an empty src instead of being mis-replaced with image data.
- * Builders drop in their own media either way.
+ * Every id that should resolve to a discovered template. Replacements keep
+ * their own integration id and also own the Core id they replace.
+ * @param {{dirName: string, replaces?: string}} template
+ * @returns {string[]}
+ */
+export function templateLookupIds(template: {
+    dirName: string;
+    replaces?: string;
+}): string[];
+/**
+ * Remove entries shadowed in the default discovery view while retaining them in
+ * package-scoped views. An active replacement owns its target id. A rejected
+ * same-id declaration falls back to Core when a Core template of the same kind
+ * owns that id; otherwise the integration template remains available by kind.
+ * @param {DiscoveredTemplate[]} templates
+ * @returns {DiscoveredTemplate[]}
+ */
+export function effectiveTemplateDiscovery(templates: DiscoveredTemplate[]): DiscoveredTemplate[];
+/**
+ * Replace each Astryx template fixture reference with a placeholder so
+ * scaffolded pages render with zero setup. Images get a self-contained data
+ * URI; videos (which have no equivalent inline placeholder — see
+ * VIDEO_EXTENSIONS) are stripped to an empty src instead of being
+ * mis-replaced with image data. Builders drop in their own media either way.
+ *
+ * A reference is a URL token that resolves to a root-relative path under
+ * FIXTURE_SEGMENT. It is replaced whole, query and fragment included, and
+ * classified by the suffix of its last path segment. A reference that cannot
+ * be replaced safely throws with its path rather than being guessed at or
+ * left behind. Prose is left as written: in text (JSX text, a word inside a
+ * longer string) trailing punctuation is not part of a path and a path with
+ * no suffix, such as the bare directory, is a mention; inside a comment
+ * nothing throws.
  *
  * @param {string} source - Template source code.
  * @returns {string} Source with demo asset references replaced.
@@ -28,6 +56,13 @@ export function stripTemplateAssetRefs(source: string): string;
  * @returns {string[]}
  */
 export function listTemplates(): string[];
+/**
+ * Resolve the template-spec file for a core page directory: the first existing
+ * metadata file in {@link ALL_TEMPLATE_SUFFIXES} precedence, or null.
+ * @param {string} dirPath
+ * @returns {string | null}
+ */
+export function findPageDocFile(dirPath: string): string | null;
 /**
  * Discover only the templates built into @astryxdesign/core. Integration
  * authoring checks use this narrower surface so a broken project config or a
@@ -35,22 +70,54 @@ export function listTemplates(): string[];
  * @returns {Promise<DiscoveredTemplate[]>}
  */
 export function discoverCoreTemplates(): Promise<DiscoveredTemplate[]>;
+/**
+ * Apply valid integration replacements to a raw template set.
+ *
+ * One declaration owns its Core target. When different configured packages
+ * replace the same target, the later package wins and discovery returns a
+ * warning, matching integration-doc replacement order. Multiple declarations
+ * inside one package are invalid and fail closed. Missing targets and kind
+ * mismatches also fail closed: Core stays selected and every integration
+ * template remains addressable by its own id.
+ *
+ * @param {DiscoveredTemplate[]} templates
+ * @param {TemplateDiscoveryError[]} [declarationErrors]
+ * @returns {{templates: DiscoveredTemplate[], errors: TemplateReplacementError[]}}
+ */
+export function applyTemplateReplacements(templates: DiscoveredTemplate[], declarationErrors?: TemplateDiscoveryError[]): {
+    templates: DiscoveredTemplate[];
+    errors: TemplateReplacementError[];
+};
+/**
+ * Discover every template without hiding replaced Core originals. Internal
+ * package-qualified selection uses this view.
+ * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
+ */
+export function discoverAllUnresolved(cwd?: string): Promise<DiscoveredTemplate[]>;
+/**
+ * Discover the resolved catalog before default-view shadowing. Internal
+ * package-qualified selection uses this view.
+ * @param {string} [cwd]
+ * @returns {Promise<DiscoveredTemplate[]>}
+ */
+export function discoverAllResolved(cwd?: string): Promise<DiscoveredTemplate[]>;
 /**
  * @param {string} [cwd]
  * @returns {Promise<DiscoveredTemplate[]>}
  */
 export function discoverAll(cwd?: string): Promise<DiscoveredTemplate[]>;
 /**
- * Like {@link discoverAll} but also returns integration-template discovery
- * errors (missing same-stem source, missing `type`, load failure). Use this
- * when the caller wants to warn about malformed integration templates.
+ * Like {@link discoverAll} but also returns integration-template discovery and
+ * replacement-declaration errors. Use this when the caller wants to warn about
+ * malformed integration templates or inactive replacement declarations.
  *
  * @param {string} [cwd]
- * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
+ * @returns {Promise<{templates: DiscoveredTemplate[], errors: Array<TemplateDiscoveryError | TemplateReplacementError>}>}
  */
 export function discoverAllWithErrors(cwd?: string): Promise<{
     templates: DiscoveredTemplate[];
-    errors: TemplateDiscoveryError[];
+    errors: Array<TemplateDiscoveryError | TemplateReplacementError>;
 }>;
 /**
  * Discover the templates contributed by a SINGLE integration. Same per-template
@@ -58,12 +125,13 @@ export function discoverAllWithErrors(cwd?: string): Promise<{
  * page|block type required); broken templates are recorded in `errors` rather
  * than thrown. Exposed for `doctor integration validate` and template authoring checks.
  *
- * @param {{name?: string, __spec?: string, templates?: string}} integration
+ * @param {{name?: string, __spec?: string, __autolinked?: boolean, templates?: string}} integration
  * @returns {Promise<{templates: DiscoveredTemplate[], errors: TemplateDiscoveryError[]}>}
  */
 export function discoverIntegrationTemplatesForOne(integration: {
     name?: string;
     __spec?: string;
+    __autolinked?: boolean;
     templates?: string;
 }): Promise<{
     templates: DiscoveredTemplate[];
@@ -117,6 +185,23 @@ export type DiscoveredTemplate = {
     filePath: string;
     docPath: string;
     package?: string | undefined;
+    /**
+     * whether the owning integration was discovered
+     * from package.json rather than named in astryx.config
+     */
+    autolinked?: boolean | undefined;
+    /**
+     * active Core template id this integration template replaces
+     */
+    replaces?: string | undefined;
+    /**
+     * whether an invalid declaration was disabled
+     */
+    replacementRejected?: boolean | undefined;
+    /**
+     * disabled declaration target
+     */
+    replacementTarget?: string | undefined;
 };
 /**
  * An integration-template discovery error.
@@ -125,6 +210,23 @@ export type TemplateDiscoveryError = {
     package: string;
     template?: string | undefined;
     message: string;
+    code?: string | undefined;
+    severity?: "error" | "warning" | undefined;
+    /**
+     * Core target whose replacement set is invalid
+     */
+    replacementTarget?: string | undefined;
+    /**
+     * whether the declaration came from an autolinked integration
+     */
+    autolinked?: boolean | undefined;
+};
+/**
+ * A semantic error in an integration template replacement declaration.
+ */
+export type TemplateReplacementError = TemplateDiscoveryError & {
+    code: "missing_template_replacement_target" | "ambiguous_template_replacement" | "invalid_template_replacement";
+    severity: "warning" | "error";
 };
 /**
  * The loaded metadata object from a template spec (loose — authored shape).

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

@@ -0,0 +1,248 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import jscodeshift from 'jscodeshift';
+import {stripTemplateAssetRefs} from './template-adapter.mjs';
+
+const PLACEHOLDER = stripTemplateAssetRefs("'/template-assets/x.png'").slice(
+  1,
+  -1,
+);
+
+describe('stripTemplateAssetRefs fixture references', () => {
+  it('replaces an image with a self-contained placeholder', () => {
+    expect(PLACEHOLDER).toMatch(/^data:image\/svg\+xml,[^\s'"`()]+$/u);
+  });
+
+  it.each([
+    'https://cdn.example.com/template-assets/logo.png',
+    '//cdn.example.com/template-assets/logo.png',
+    '/my-app/template-assets/hero.jpg',
+    './template-assets/hero.jpg',
+    'template-assets/hero.jpg',
+    '/template-assets-archive/hero.jpg',
+    '@/template-assets/hero.jpg',
+  ])('leaves %s untouched', value => {
+    const source = `const src = '${value}';`;
+    expect(stripTemplateAssetRefs(source)).toBe(source);
+  });
+
+  it.each([
+    'import StarIcon from "./icons/star.svg";',
+    '<Icon icon="/icons/star.svg" />',
+    '<Button icon={StarIcon} />',
+    "const icons = {star: 'heroicons:star'};",
+  ])('leaves an icon outside the fixture namespace untouched: %s', source => {
+    expect(stripTemplateAssetRefs(source)).toBe(source);
+  });
+
+  it.each([
+    ['a subdirectory', '/template-assets/avatars/ada.png'],
+    ['an @ in its name', '/template-assets/hero@2x.png'],
+    ['a plus in its name', '/template-assets/cover+1.jpg'],
+    ['an encoded space in its name', '/template-assets/hero%20wide.png'],
+  ])('replaces a fixture with %s', (_, value) => {
+    expect(stripTemplateAssetRefs(`<img src="${value}" />`)).toBe(
+      `<img src="${PLACEHOLDER}" />`,
+    );
+  });
+
+  it('replaces the whole reference, query and fragment included', () => {
+    expect(
+      stripTemplateAssetRefs("const hero = '/template-assets/hero.jpg?w=200';"),
+    ).toBe(`const hero = '${PLACEHOLDER}';`);
+    expect(
+      stripTemplateAssetRefs("const clip = '/template-assets/clip.mp4#t=5';"),
+    ).toBe("const clip = '';");
+    expect(
+      stripTemplateAssetRefs(
+        "const hero = '/template-assets/a.png?f=/template-assets/b.png';",
+      ),
+    ).toBe(`const hero = '${PLACEHOLDER}';`);
+  });
+
+  it('classifies by the complete final suffix, ignoring case', () => {
+    expect(
+      stripTemplateAssetRefs("src: '/template-assets/Clip.Min.MP4',"),
+    ).toBe("src: '',");
+  });
+
+  it.each([
+    [
+      'a CSS url()',
+      "backgroundImage: 'url(/template-assets/hero.png)'",
+      `backgroundImage: 'url(${PLACEHOLDER})'`,
+    ],
+    [
+      'a srcset list',
+      'srcSet="/template-assets/a.png 1x, /template-assets/a@2x.png 2x"',
+      `srcSet="${PLACEHOLDER} 1x, ${PLACEHOLDER} 2x"`,
+    ],
+    [
+      'an HTML string with escaped quotes',
+      'const html = "<img src=\\"/template-assets/a.png\\">";',
+      `const html = "<img src=\\"${PLACEHOLDER}\\">";`,
+    ],
+    [
+      'JSX text',
+      '<code>/template-assets/hero.png</code>',
+      `<code>${PLACEHOLDER}</code>`,
+    ],
+    [
+      'a sentence that quotes it',
+      'const tip = "Replace \'/template-assets/hero.png\'.";',
+      `const tip = "Replace '${PLACEHOLDER}'.";`,
+    ],
+    [
+      'a url() inside a longer string',
+      "const bg = 'url(/template-assets/a.png) + x';",
+      `const bg = 'url(${PLACEHOLDER}) + x';`,
+    ],
+    [
+      'a comment',
+      '// hero: /template-assets/hero.png\n',
+      `// hero: ${PLACEHOLDER}\n`,
+    ],
+    [
+      'a sentence, keeping its punctuation',
+      '// Uses /template-assets/a.png, then /template-assets/b.png.\n',
+      `// Uses ${PLACEHOLDER}, then ${PLACEHOLDER}.\n`,
+    ],
+  ])('replaces a fixture inside %s', (_, source, expected) => {
+    expect(stripTemplateAssetRefs(source)).toBe(expected);
+  });
+
+  it.each([
+    '<Text>Put your images in /template-assets/ first.</Text>',
+    "const note = 'Media: /template-assets/hero';",
+    '// Demo images live under /template-assets and are replaced.\n',
+    "const html = '<img src=/template-assets-archive/a.png>';",
+  ])('leaves a mention in text that names no media file: %s', source => {
+    expect(stripTemplateAssetRefs(source)).toBe(source);
+  });
+
+  it.each([
+    "// Images come from `/template-assets/*` and '/template-assets/'.\nexport default function Page() {\n  return null;\n}\n",
+    "/* Was '/template-assets/clip.bin'. */\nexport const x = 1;\n",
+  ])('leaves a comment it would otherwise reject: %s', source => {
+    expect(stripTemplateAssetRefs(source)).toBe(source);
+  });
+
+  it.each([
+    [
+      'no file suffix',
+      "src: '/template-assets/hero',",
+      '/template-assets/hero',
+    ],
+    ['no file name', "src: '/template-assets/',", '/template-assets/'],
+    [
+      'no path below it',
+      "export const base = '/template-assets'; // base\n",
+      '/template-assets',
+    ],
+  ])(
+    'fails with the fixture path when a value has %s',
+    (_, source, reference) => {
+      expect(() => stripTemplateAssetRefs(source)).toThrow(
+        `Unrecognized template asset format (none) for ${reference}`,
+      );
+    },
+  );
+
+  it.each([
+    [
+      'const src = `/template-assets/${name}.png`;',
+      '/template-assets/${name}.png',
+    ],
+    ['const src = `/template-assets${path}`;', '/template-assets${path}'],
+  ])(
+    'fails when a fixture path is built by interpolation: %s',
+    (source, reference) => {
+      expect(() => stripTemplateAssetRefs(source)).toThrow(
+        `Template asset reference ${reference} cannot be replaced safely: it is built by a template-literal interpolation`,
+      );
+    },
+  );
+
+  it.each([
+    [
+      'follows an interpolation',
+      'const src = `${base}/template-assets/a.png`;',
+    ],
+    ['is cut short by a parenthesis', "src: '/template-assets/a(1).mp4',"],
+    ['ends a word in text', 'const s = "clip: /template-assets/a.png(1).mp4";'],
+    [
+      'has mismatched escaped quotes',
+      'const html = "<img src=\\"/template-assets/a.png\\\'>";',
+    ],
+    [
+      'sits between a quote and a parenthesis',
+      "const s = '\"/template-assets/a.png)';",
+    ],
+  ])('fails when a fixture path %s', (_, source) => {
+    expect(() => stripTemplateAssetRefs(source)).toThrow(
+      /\/template-assets\/a.* cannot be replaced safely: it is not a whole/u,
+    );
+  });
+
+  it.each([
+    'srcSet="/template-assets/a.png 1x,/template-assets/b.png 2x"',
+    "const html = '<img src=/template-assets/b.png>';",
+    "const s = 'hero\\n/template-assets/b.png';",
+  ])('fails when a fixture path is joined to other text: %s', source => {
+    expect(() => stripTemplateAssetRefs(source)).toThrow(
+      /\/template-assets\/b\.png cannot be replaced safely: it is joined/u,
+    );
+  });
+
+  it.each([
+    ['concatenated', "const src = base + '/template-assets/hero.png';"],
+    ['concatenated', "const src = '/template-assets/hero.png' + query;"],
+    ['concatenated', "src += '/template-assets/hero.png';"],
+    ['a method', "const src = '/template-assets/hero.png'.concat('?w=1');"],
+    ['imported', "import hero from '/template-assets/hero.png';"],
+    ['imported', "const hero = require('/template-assets/hero.png');"],
+  ])('fails when a fixture string is %s: %s', (use, source) => {
+    expect(() => stripTemplateAssetRefs(source)).toThrow(
+      new RegExp(`/template-assets/hero\\.png .*${use}`, 'u'),
+    );
+  });
+});
+
+describe('shipped templates', () => {
+  it('copy with every fixture replaced and still parse', () => {
+    const root = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      '../../assets/templates',
+    );
+    const parse = jscodeshift.withParser('tsx');
+    const files = fs
+      .readdirSync(root, {recursive: true, encoding: 'utf-8'})
+      .filter(file => file.endsWith('.tsx'))
+      .filter(file =>
+        fs
+          .readFileSync(path.join(root, file), 'utf-8')
+          .includes('/template-assets'),
+      );
+    expect(files.length).toBeGreaterThan(10);
+
+    const problems = [];
+    for (const file of files) {
+      try {
+        const output = stripTemplateAssetRefs(
+          fs.readFileSync(path.join(root, file), 'utf-8'),
+        );
+        if (output.includes('/template-assets')) {
+          problems.push(`${file}: fixture reference left behind`);
+        }
+        parse(output);
+      } catch (err) {
+        problems.push(`${file}: ${/** @type {Error} */ (err).message}`);
+      }
+    }
+    expect(problems).toEqual([]);
+  });
+});

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

@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Template discovery isolates each configured integration.
+ *
+ * An integration whose templates root cannot be read (here, the manifest points
+ * `templates` at a file) is that package's discovery error. Core templates and
+ * every other integration's templates are still discovered.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import {discoverAll, discoverAllWithErrors} from './template-adapter.mjs';
+import {runCli} from '../../test-utils/run-cli.mjs';
+
+let tmpDir = '';
+
+/**
+ * @param {string} name
+ * @param {Record<string, string>} files
+ */
+function installPackage(name, files) {
+  const dir = path.join(tmpDir, 'node_modules', ...name.split('/'));
+  fs.mkdirSync(dir, {recursive: true});
+  fs.writeFileSync(
+    path.join(dir, 'package.json'),
+    JSON.stringify({name, version: '1.0.0'}),
+  );
+  for (const [file, contents] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(dir, file)), {recursive: true});
+    fs.writeFileSync(path.join(dir, file), contents);
+  }
+}
+
+beforeEach(() => {
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'astryx-template-isolation-'));
+  fs.writeFileSync(
+    path.join(tmpDir, 'package.json'),
+    JSON.stringify({name: 'consumer', version: '1.0.0'}),
+  );
+  fs.writeFileSync(
+    path.join(tmpDir, 'astryx.config.mjs'),
+    `export default {integrations: ['@acme/file-root', '@acme/good']};\n`,
+  );
+  installPackage('@acme/file-root', {
+    'astryx.integration.mjs': `export default {templates: './templates.mjs'};\n`,
+    'templates.mjs': 'export default {};\n',
+  });
+  installPackage('@acme/good', {
+    'astryx.integration.mjs': `export default {templates: './templates'};\n`,
+    'templates/good-hero.template.mjs': `export default {type: 'block', name: 'Good hero', description: 'A hero.'};\n`,
+    'templates/good-hero.tsx': 'export default function GoodHero() { return null; }\n',
+  });
+});
+
+afterEach(() => {
+  fs.rmSync(tmpDir, {recursive: true, force: true});
+});
+
+describe('template discovery with an unreadable templates root', () => {
+  it('keeps core and the other integrations', async () => {
+    const templates = await discoverAll(tmpDir);
+
+    expect(templates).toContainEqual(
+      expect.objectContaining({dirName: 'good-hero', package: '@acme/good'}),
+    );
+    expect(templates.some(template => template.package == null)).toBe(true);
+    expect(templates.some(t => t.package === '@acme/file-root')).toBe(false);
+  });
+
+  it('reports the unreadable root as that package’s error', async () => {
+    const {errors} = await discoverAllWithErrors(tmpDir);
+
+    expect(errors).toContainEqual(
+      expect.objectContaining({
+        package: '@acme/file-root',
+        message: expect.stringContaining('templates.mjs'),
+      }),
+    );
+  });
+
+  it('keeps astryx template --list working', async () => {
+    const {status, stdout} = await runCli(['template', '--list', '--json'], {
+      cwd: tmpDir,
+    });
+
+    expect(status).toBe(0);
+    expect(JSON.parse(stdout).data).toContainEqual(
+      expect.objectContaining({id: 'good-hero'}),
+    );
+  });
+});