@astryxdesign/cli 0.6.3-canary.ea2f048 → 0.6.3-canary.ebaebc4

package/foundation/identity/provider-identity.mjs

@@ -0,0 +1,320 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Canonical provider, artifact, and immutable-instance identity helpers.
+ *
+ * IDs use versioned, RFC 3986-escaped path segments. Provider package names are
+ * case-insensitive and normalize to lowercase. Artifact names preserve case and
+ * normalize Unicode to NFC.
+ */
+
+/** @typedef {import('../../authoring/identity/type').ArtifactId} ArtifactId */
+/** @typedef {import('../../authoring/identity/type').ArtifactIdentity} ArtifactIdentity */
+/** @typedef {import('../../authoring/identity/type').AuthoredDoc} AuthoredDoc */
+/** @typedef {import('../../authoring/identity/type').AuthoredDocEntry} AuthoredDocEntry */
+/** @typedef {import('../../authoring/doctypes/base/type').AuthoredDocKind} AuthoredDocKind */
+/** @typedef {import('../../authoring/identity/type').ContentDigest} ContentDigest */
+/** @typedef {import('../../authoring/identity/type').ContributionKind} ContributionKind */
+/** @typedef {import('../../authoring/identity/type').DocId} DocId */
+/** @typedef {import('../../authoring/identity/type').ProviderId} ProviderId */
+/** @typedef {import('../../authoring/identity/type').ProviderInstance} ProviderInstance */
+/** @typedef {import('../../authoring/identity/type').ProviderInstanceId} ProviderInstanceId */
+
+const ARTIFACT_PREFIX = 'astryx:artifact:v1/';
+const PROVIDER_INSTANCE_PREFIX = 'astryx:provider-instance:v1/';
+const PACKAGE_NAME_RE =
+  /^(?:@[a-z0-9][a-z0-9._~!*'()-]*\/)?[a-z0-9][a-z0-9._~!*'()-]*$/u;
+const SHA256_RE = /^sha256:[0-9a-f]{64}$/u;
+
+/** @type {ReadonlySet<ContributionKind>} */
+const CONTRIBUTION_KINDS = new Set([
+  'component',
+  'function',
+  'generic',
+  'page',
+  'block',
+  'schema',
+  'command',
+  'enum',
+  'namespace',
+  'theme',
+  'codemod',
+  'agent-doc',
+]);
+
+/** @type {ReadonlySet<AuthoredDocKind>} */
+const DOC_KINDS = new Set([
+  'component',
+  'function',
+  'generic',
+  'page',
+  'block',
+  'schema',
+  'command',
+  'enum',
+  'namespace',
+]);
+
+/** RFC 3986 path-segment encoding with uppercase escapes. */
+/** @param {string} value @returns {string} */
+function encodeSegment(value) {
+  return encodeURIComponent(value).replace(
+    /[!'()*]/gu,
+    character => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+}
+
+/** Decode one identity segment or throw a stable, readable error. */
+/** @param {string} value @param {string} label @returns {string} */
+function decodeSegment(value, label) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    throw new Error(`${label} contains invalid percent escaping.`);
+  }
+}
+
+/** Normalize a required identity string without changing meaningful case. */
+/** @param {unknown} value @param {string} label @returns {string} */
+function normalizeName(value, label) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+  return value.trim().normalize('NFC');
+}
+
+/**
+ * Normalize an npm package name into a ProviderId.
+ * @param {string} packageName
+ * @returns {ProviderId}
+ */
+export function normalizeProviderId(packageName) {
+  const normalized = normalizeName(packageName, 'Provider ID').toLowerCase();
+  if (!PACKAGE_NAME_RE.test(normalized)) {
+    throw new Error(
+      `Provider ID "${packageName}" must be a bare npm package name.`,
+    );
+  }
+  return /** @type {ProviderId} */ (normalized);
+}
+
+/**
+ * Normalize a SHA-256 digest.
+ * @param {string} digest
+ * @returns {ContentDigest}
+ */
+export function normalizeContentDigest(digest) {
+  const normalized = normalizeName(digest, 'Content digest').toLowerCase();
+  if (!SHA256_RE.test(normalized)) {
+    throw new Error(
+      'Content digest must use sha256:<64 lowercase hex characters>.',
+    );
+  }
+  return /** @type {ContentDigest} */ (normalized);
+}
+
+/**
+ * Build a stable provider + contribution kind + artifact-name ID.
+ * @param {string} provider
+ * @param {ContributionKind} kind
+ * @param {string} name
+ * @returns {ArtifactId}
+ */
+export function createArtifactId(provider, kind, name) {
+  const providerId = normalizeProviderId(provider);
+  if (!CONTRIBUTION_KINDS.has(kind)) {
+    throw new Error(`Unknown contribution kind "${String(kind)}".`);
+  }
+  const stableName = normalizeName(name, 'Artifact name');
+  return /** @type {ArtifactId} */ (
+    `${ARTIFACT_PREFIX}${encodeSegment(providerId)}/${kind}/${encodeSegment(stableName)}`
+  );
+}
+
+/**
+ * Build a stable document ID from provider + authored kind + stable name.
+ * @param {string} provider
+ * @param {AuthoredDocKind} kind
+ * @param {string} name
+ * @returns {DocId}
+ */
+export function createDocId(provider, kind, name) {
+  if (!DOC_KINDS.has(kind)) {
+    throw new Error(`Unknown authored doc kind "${String(kind)}".`);
+  }
+  return /** @type {DocId} */ (createArtifactId(provider, kind, name));
+}
+
+/**
+ * Build a normalized logical artifact record.
+ * @param {string} provider
+ * @param {ContributionKind} kind
+ * @param {string} name
+ * @returns {ArtifactIdentity}
+ */
+export function createArtifactIdentity(provider, kind, name) {
+  const providerId = normalizeProviderId(provider);
+  const stableName = normalizeName(name, 'Artifact name');
+  return Object.freeze({
+    id: createArtifactId(providerId, kind, stableName),
+    providerId,
+    kind,
+    name: stableName,
+  });
+}
+
+/**
+ * Parse and canonicalize an ArtifactId.
+ * @param {string} value
+ * @returns {ArtifactIdentity}
+ */
+export function parseArtifactId(value) {
+  if (typeof value !== 'string' || !value.startsWith(ARTIFACT_PREFIX)) {
+    throw new Error(`Artifact ID must start with "${ARTIFACT_PREFIX}".`);
+  }
+  const segments = value.slice(ARTIFACT_PREFIX.length).split('/');
+  if (segments.length !== 3) {
+    throw new Error(
+      'Artifact ID must contain provider, kind, and name segments.',
+    );
+  }
+  const provider = decodeSegment(segments[0], 'Artifact provider');
+  const kind = decodeSegment(segments[1], 'Artifact kind');
+  const name = decodeSegment(segments[2], 'Artifact name');
+  if (!CONTRIBUTION_KINDS.has(/** @type {ContributionKind} */ (kind))) {
+    throw new Error(`Unknown contribution kind "${kind}".`);
+  }
+  const identity = createArtifactIdentity(
+    provider,
+    /** @type {ContributionKind} */ (kind),
+    name,
+  );
+  if (identity.id !== value) {
+    throw new Error('Artifact ID is not in canonical serialized form.');
+  }
+  return identity;
+}
+
+/**
+ * Build one immutable provider instance.
+ * @param {{providerId: string, packageName: string, packageVersion: string, sourceDigest: string}} input
+ * @returns {ProviderInstance}
+ */
+export function createProviderInstance(input) {
+  const providerId = normalizeProviderId(input.providerId);
+  const packageName = normalizeProviderId(input.packageName);
+  const packageVersion = normalizeName(input.packageVersion, 'Package version');
+  const sourceDigest = normalizeContentDigest(input.sourceDigest);
+  const id = /** @type {ProviderInstanceId} */ (
+    `${PROVIDER_INSTANCE_PREFIX}${encodeSegment(providerId)}/${encodeSegment(packageName)}/${encodeSegment(packageVersion)}/${encodeSegment(sourceDigest)}`
+  );
+  return Object.freeze({
+    id,
+    providerId,
+    packageName,
+    packageVersion,
+    sourceDigest,
+  });
+}
+
+/** Normalize a package-relative source path to forward slashes. */
+/** @param {unknown} value @returns {string} */
+function normalizeSourcePath(value) {
+  const normalized = normalizeName(value, 'Source path').replaceAll('\\', '/');
+  const segments = normalized.split('/');
+  if (
+    normalized.startsWith('/') ||
+    /^[A-Za-z]:\//u.test(normalized) ||
+    segments.some(
+      segment => segment === '' || segment === '.' || segment === '..',
+    )
+  ) {
+    throw new Error('Source path must be a normalized package-relative path.');
+  }
+  return normalized;
+}
+
+/** Infer an unstamped legacy document's kind from its required shape. */
+/** @param {AuthoredDoc} authored @returns {AuthoredDocKind} */
+function authoredKindOf(authored) {
+  if (authored.type != null) return authored.type;
+  if ('params' in authored && 'returns' in authored) return 'function';
+  if (
+    'props' in authored ||
+    'components' in authored ||
+    'subComponentOf' in authored
+  ) {
+    return 'component';
+  }
+  if ('sections' in authored && 'title' in authored) return 'generic';
+  throw new Error('Cannot infer the kind of an unstamped authored document.');
+}
+
+/** Clone and recursively freeze plain authored data. */
+/** @template T @param {T} value @returns {T} */
+function frozenClone(value) {
+  const clone = structuredClone(value);
+  const seen = new WeakSet();
+  /** @param {unknown} current */
+  const freeze = current => {
+    if (
+      current == null ||
+      typeof current !== 'object' ||
+      Object.isFrozen(current) ||
+      seen.has(current)
+    ) {
+      return;
+    }
+    seen.add(current);
+    for (const nested of Object.values(current)) freeze(nested);
+    Object.freeze(current);
+  };
+  freeze(clone);
+  return clone;
+}
+
+/**
+ * Bind one validated authored document to immutable provider and source
+ * provenance. Runtime lifecycle state is intentionally absent.
+ * @param {{
+ *   provider: ProviderInstance,
+ *   kind: AuthoredDocKind,
+ *   stableName: string,
+ *   source: {group: string, path: string, digest: string},
+ *   authored: AuthoredDoc,
+ * }} input
+ * @returns {AuthoredDocEntry}
+ */
+export function createAuthoredDocEntry(input) {
+  const stableName = normalizeName(input.stableName, 'Stable document name');
+  const group = normalizeName(input.source.group, 'Source group');
+  const sourcePath = normalizeSourcePath(input.source.path);
+  const digest = normalizeContentDigest(input.source.digest);
+  const authoredKind = authoredKindOf(input.authored);
+  if (authoredKind !== input.kind) {
+    throw new Error(
+      `Document kind "${input.kind}" does not match authored type "${authoredKind}".`,
+    );
+  }
+
+  const provider = createProviderInstance({
+    providerId: input.provider.providerId,
+    packageName: input.provider.packageName,
+    packageVersion: input.provider.packageVersion,
+    sourceDigest: input.provider.sourceDigest,
+  });
+  if (provider.id !== input.provider.id) {
+    throw new Error(
+      'Provider instance ID does not match its immutable fields.',
+    );
+  }
+
+  return Object.freeze({
+    id: createDocId(provider.providerId, input.kind, stableName),
+    provider,
+    kind: input.kind,
+    stableName,
+    source: Object.freeze({group, path: sourcePath, digest}),
+    authored: frozenClone(input.authored),
+  });
+}

package/foundation/identity/provider-identity.test.mjs

@@ -0,0 +1,254 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+  createArtifactId,
+  createArtifactIdentity,
+  createAuthoredDocEntry,
+  createDocId,
+  createProviderInstance,
+  normalizeContentDigest,
+  normalizeProviderId,
+  parseArtifactId,
+} from './provider-identity.mjs';
+import {CLI_PROVIDER_ID, CORE_PROVIDER_ID} from './providers.mjs';
+
+const DIGEST_A = `sha256:${'a'.repeat(64)}`;
+const DIGEST_B = `sha256:${'b'.repeat(64)}`;
+
+describe('provider identity', () => {
+  it('uses the same canonical model for built-in providers', () => {
+    expect(CORE_PROVIDER_ID).toBe('@astryxdesign/core');
+    expect(CLI_PROVIDER_ID).toBe('@astryxdesign/cli');
+  });
+
+  it('normalizes npm package identity once', () => {
+    expect(normalizeProviderId(' @AstryxDesign/CLI ')).toBe(
+      '@astryxdesign/cli',
+    );
+    expect(() => normalizeProviderId('../cli')).toThrow(
+      /bare npm package name/u,
+    );
+  });
+
+  it('normalizes content digests', () => {
+    expect(normalizeContentDigest(DIGEST_A.toUpperCase())).toBe(DIGEST_A);
+    expect(() => normalizeContentDigest('sha256:nope')).toThrow(/sha256/u);
+  });
+
+  it('keeps provider, kind, and case-sensitive artifact name in the ID', () => {
+    const component = createArtifactId('@acme/ui', 'component', 'Button');
+    expect(component).not.toBe(
+      createArtifactId('@acme/ui', 'component', 'button'),
+    );
+    expect(component).not.toBe(
+      createArtifactId('@acme/ui', 'schema', 'Button'),
+    );
+    expect(component).not.toBe(
+      createArtifactId('@other/ui', 'component', 'Button'),
+    );
+  });
+
+  it('escapes segments canonically and round-trips without collisions', () => {
+    const identity = createArtifactIdentity(
+      '@acme/ui',
+      'generic',
+      'Deploy / 100%',
+    );
+    expect(identity.id).toContain('Deploy%20%2F%20100%25');
+    expect(parseArtifactId(identity.id)).toEqual(identity);
+    expect(() => parseArtifactId(identity.id.replace('%2F', '%2f'))).toThrow(
+      /canonical/u,
+    );
+  });
+
+  it('uses the same stable ID across immutable provider instances', () => {
+    const docId = createDocId('@acme/ui', 'schema', 'integration');
+    const first = createProviderInstance({
+      providerId: '@acme/ui',
+      packageName: '@acme/ui',
+      packageVersion: '1.0.0',
+      sourceDigest: DIGEST_A,
+    });
+    const second = createProviderInstance({
+      providerId: '@acme/ui',
+      packageName: '@acme/ui',
+      packageVersion: '1.0.1',
+      sourceDigest: DIGEST_B,
+    });
+    expect(first.id).not.toBe(second.id);
+    expect(createDocId(first.providerId, 'schema', 'integration')).toBe(docId);
+    expect(createDocId(second.providerId, 'schema', 'integration')).toBe(docId);
+  });
+
+  it('supports an explicit stable provider ID across a package rename', () => {
+    const instance = createProviderInstance({
+      providerId: '@acme/ui',
+      packageName: '@acme/design-system',
+      packageVersion: '2.0.0',
+      sourceDigest: DIGEST_A,
+    });
+    expect(instance.providerId).toBe('@acme/ui');
+    expect(instance.packageName).toBe('@acme/design-system');
+  });
+
+  it('binds a doc to stable identity and immutable source provenance', () => {
+    const provider = createProviderInstance({
+      providerId: '@acme/ui',
+      packageName: '@acme/ui',
+      packageVersion: '1.0.0',
+      sourceDigest: DIGEST_A,
+    });
+    const authored = {
+      type: 'schema',
+      name: 'integration',
+      displayName: 'Integration',
+      description: 'The integration manifest.',
+      fields: [],
+    };
+
+    const entry = createAuthoredDocEntry({
+      provider,
+      kind: 'schema',
+      stableName: 'integration',
+      source: {
+        group: 'cli-api',
+        path: 'authoring/integration/integration.doc.mjs',
+        digest: DIGEST_B,
+      },
+      authored,
+    });
+
+    expect(entry.id).toBe(createDocId('@acme/ui', 'schema', 'integration'));
+    expect(entry.provider).toEqual(provider);
+    expect(entry.stableName).toBe('integration');
+    expect(entry.source.digest).toBe(DIGEST_B);
+    expect(Object.isFrozen(entry)).toBe(true);
+    expect(Object.isFrozen(entry.provider)).toBe(true);
+    expect(Object.isFrozen(entry.source)).toBe(true);
+    expect(Object.isFrozen(entry.authored)).toBe(true);
+
+    authored.name = 'mutated';
+    expect(entry.authored.name).toBe('integration');
+  });
+
+  it('uses a discovery-owned stable name when authored display names collide', () => {
+    const provider = createProviderInstance({
+      providerId: '@astryxdesign/core',
+      packageName: '@astryxdesign/core',
+      packageVersion: '1.0.0',
+      sourceDigest: DIGEST_A,
+    });
+    const authored = {
+      type: 'block',
+      name: 'Banner — Statuses',
+      description: 'A template.',
+    };
+    const makeEntry = stableName =>
+      createAuthoredDocEntry({
+        provider,
+        kind: 'block',
+        stableName,
+        source: {
+          group: 'templates',
+          path: `templates/${stableName}.doc.mjs`,
+          digest: DIGEST_B,
+        },
+        authored,
+      });
+
+    expect(makeEntry('BannerShowcase').id).not.toBe(
+      makeEntry('BannerStatuses').id,
+    );
+  });
+
+  it('correlates an unstamped legacy reference doc with generic identity', () => {
+    const provider = createProviderInstance({
+      providerId: '@acme/ui',
+      packageName: '@acme/ui',
+      packageVersion: '1.0.0',
+      sourceDigest: DIGEST_A,
+    });
+    const entry = createAuthoredDocEntry({
+      provider,
+      kind: 'generic',
+      stableName: 'theming',
+      source: {group: 'guides', path: 'docs/theming.doc.mjs', digest: DIGEST_B},
+      authored: {
+        name: 'theming',
+        title: 'Theming',
+        description: 'How theming works.',
+        sections: [],
+      },
+    });
+    expect(entry.kind).toBe('generic');
+  });
+
+  it('rejects doc-entry identity that disagrees with stamped or legacy content', () => {
+    const provider = createProviderInstance({
+      providerId: '@acme/ui',
+      packageName: '@acme/ui',
+      packageVersion: '1.0.0',
+      sourceDigest: DIGEST_A,
+    });
+    const source = {
+      group: 'cli-api',
+      path: 'integration.doc.mjs',
+      digest: DIGEST_B,
+    };
+
+    expect(() =>
+      createAuthoredDocEntry({
+        provider,
+        kind: 'command',
+        stableName: 'integration',
+        source,
+        authored: {
+          type: 'schema',
+          name: 'integration',
+          displayName: 'Integration',
+          description: 'The integration manifest.',
+          fields: [],
+        },
+      }),
+    ).toThrow(/does not match authored type/u);
+
+    expect(() =>
+      createAuthoredDocEntry({
+        provider,
+        kind: 'enum',
+        stableName: 'Button',
+        source,
+        authored: {name: 'Button', props: []},
+      }),
+    ).toThrow(/does not match authored type "component"/u);
+  });
+
+  it('rejects source paths that escape the provider package', () => {
+    const provider = createProviderInstance({
+      providerId: '@acme/ui',
+      packageName: '@acme/ui',
+      packageVersion: '1.0.0',
+      sourceDigest: DIGEST_A,
+    });
+    expect(() =>
+      createAuthoredDocEntry({
+        provider,
+        kind: 'schema',
+        stableName: 'integration',
+        source: {
+          group: 'cli-api',
+          path: '../outside.doc.mjs',
+          digest: DIGEST_B,
+        },
+        authored: {
+          type: 'schema',
+          name: 'integration',
+          displayName: 'Integration',
+          description: 'The integration manifest.',
+          fields: [],
+        },
+      }),
+    ).toThrow(/package-relative path/u);
+  });
+});

package/foundation/identity/providers.d.mts

@@ -0,0 +1,7 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in foundation/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/** Core owns built-in components and templates. */
+export const CORE_PROVIDER_ID: import("../../authoring/index.js").ProviderId;
+/** The CLI owns built-in topic docs and CLI-authored contributions. */
+export const CLI_PROVIDER_ID: import("../../authoring/index.js").ProviderId;

package/foundation/identity/providers.mjs

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Canonical identities for Astryx's built-in providers.
+ * @input Stable npm package names owned by Astryx.
+ * @output Branded ProviderId values shared by discovery and compilation.
+ * @position foundation/identity — built-in provider identity boundary.
+ */
+
+import {normalizeProviderId} from './provider-identity.mjs';
+
+/** Core owns built-in components and templates. */
+export const CORE_PROVIDER_ID = normalizeProviderId('@astryxdesign/core');
+
+/** The CLI owns built-in topic docs and CLI-authored contributions. */
+export const CLI_PROVIDER_ID = normalizeProviderId('@astryxdesign/cli');

package/foundation/integrations/autolink.mjs

@@ -234,7 +234,13 @@ export async function autolinkIntegrations({
 
   /** @type {import('./integrations.mjs').LoadedIntegration[]} */
   const autolinked = [];
-  const names = new Set(loaded.map(integration => integration.name));
+  // One package reached twice (an alias beside the package it aliases, at the
+  // same version) loads once. The same name at another version is kept, so the
+  // provider-identity pass in Project.load reports it instead of dropping it.
+  /** @param {{name: string, version?: string}} integration */
+  const identity = integration =>
+    `${integration.name}\u0000${integration.version ?? ''}`;
+  const seen = new Set(loaded.map(identity));
 
   for (const candidate of candidates) {
     /** @type {import('./integrations.mjs').LoadedIntegration|undefined} */
@@ -250,10 +256,11 @@ export async function autolinkIntegrations({
       continue;
     }
     if (!integration || integration.__loadError) continue;
-    // Identity is the resolved package's own name, so an alias and the package
-    // it aliases collapse here even when they are two directories on disk.
-    if (names.has(integration.name)) continue;
-    names.add(integration.name);
+    // Identity is the resolved package's own name and version, so an alias and
+    // the package it aliases collapse here even when they are two directories
+    // on disk.
+    if (seen.has(identity(integration))) continue;
+    seen.add(identity(integration));
     autolinked.push({
       ...integration,
       __autolinked: true,

package/foundation/integrations/integration-warnings.mjs

@@ -41,6 +41,12 @@ export async function warnOnIntegrationIssues(loadedIntegrations, {json = false}
     }
     for (const integration of loadedIntegrations) {
       if (!integration || typeof integration !== 'object') continue;
+      // A package set aside for a provider-ID conflict is fine in isolation,
+      // so `doctor integration validate` would not explain it. Say it here.
+      if (integration.__providerConflict) {
+        console.error(`Warning: ${integration.__providerConflict.message}`);
+        continue;
+      }
       let issues;
       try {
         issues = await validateLoadedIntegration(integration);