@astryxdesign/cli 0.6.3-canary.7ada42e → 0.6.3-canary.7ec7be0

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

@@ -10,6 +10,25 @@
 export function pkgOf(t: {
     package?: string;
 }): string;
+/**
+ * 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
@@ -51,22 +70,54 @@ export function findPageDocFile(dirPath: string): string | null;
  * @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
@@ -74,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[];
@@ -133,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.
@@ -141,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).