@component-compass/plugin-core 0.0.0-pr-3-8916f3c-20260507145532

package/dist/builder.d.ts

@@ -0,0 +1,27 @@
+import type { ManifestComponent, ManifestFile, ManifestSource } from "./types.js";
+type BuilderOpts = {
+    source: ManifestSource;
+    package: string;
+};
+type AddInput = (Omit<Extract<ManifestComponent, {
+    kind: "custom-element";
+}>, "deprecated"> & {
+    deprecated?: boolean | string;
+}) | (Omit<Extract<ManifestComponent, {
+    kind: "react-component";
+}>, "deprecated"> & {
+    deprecated?: boolean | string;
+}) | (Omit<Extract<ManifestComponent, {
+    kind: "vue-component";
+}>, "deprecated"> & {
+    deprecated?: boolean | string;
+});
+export declare class ManifestBuilder {
+    private readonly source;
+    private readonly packageName;
+    private readonly components;
+    constructor(opts: BuilderOpts);
+    addComponent(c: AddInput): this;
+    build(): ManifestFile;
+}
+export {};

package/dist/builder.js

@@ -0,0 +1,49 @@
+import { compareComponentId } from "./id.js";
+import { validateManifest } from "./validate.js";
+const SCHEMA_VERSION = "2.0.0";
+const expectedKindFor = {
+    cem: "custom-element",
+    react: "react-component",
+    vue: "vue-component",
+};
+export class ManifestBuilder {
+    source;
+    packageName;
+    components = [];
+    constructor(opts) {
+        this.source = opts.source;
+        this.packageName = opts.package;
+    }
+    addComponent(c) {
+        const expected = expectedKindFor[this.source];
+        if (c.kind !== expected) {
+            throw new Error(`Component kind "${c.kind}" does not match builder source "${this.source}" (expected kind "${expected}")`);
+        }
+        this.components.push({ deprecated: false, ...c });
+        return this;
+    }
+    build() {
+        const sorted = [...this.components].sort(compareComponents);
+        const out = {
+            schemaVersion: SCHEMA_VERSION,
+            source: this.source,
+            package: this.packageName,
+            components: sorted,
+        };
+        const result = validateManifest(out);
+        if (!result.ok) {
+            throw new Error(`Built manifest fails validation:\n${result.errors.join("\n")}`);
+        }
+        return out;
+    }
+}
+function compareComponents(a, b) {
+    return compareComponentId(toId(a), toId(b));
+}
+function toId(c) {
+    if (c.kind === "custom-element") {
+        return { kind: "custom-element", tagName: c.tagName, source: c.source };
+    }
+    return { kind: c.kind, export: c.export, source: c.source };
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,MAAM,eAAe,GAAsD;IACzE,GAAG,EAAE,gBAAgB;IACrB,KAAK,EAAE,iBAAiB;IACxB,GAAG,EAAE,eAAe;CACrB,CAAC;AASF,MAAM,OAAO,eAAe;IACT,MAAM,CAAiB;IACvB,WAAW,CAAS;IACpB,UAAU,GAAwB,EAAE,CAAC;IAEtD,YAAY,IAAiB;QAC3B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC;IAClC,CAAC;IAED,YAAY,CAAC,CAAW;QACtB,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9C,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,mBAAmB,CAAC,CAAC,IAAI,oCAAoC,IAAI,CAAC,MAAM,qBAAqB,QAAQ,IAAI,CAC1G,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,CAAC,EAAuB,CAAC,CAAC;QACvE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,MAAM,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAiB;YACxB,aAAa,EAAE,cAAc;YAC7B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,WAAW;YACzB,UAAU,EAAE,MAAM;SACnB,CAAC;QACF,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,qCAAqC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnF,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAED,SAAS,iBAAiB,CAAC,CAAoB,EAAE,CAAoB;IACnE,OAAO,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,SAAS,IAAI,CAAC,CAAoB;IAChC,IAAI,CAAC,CAAC,IAAI,KAAK,gBAAgB,EAAE,CAAC;QAChC,OAAO,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC;AAC9D,CAAC"}

package/dist/id.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentId, ComponentSource } from "./types.js";
+export declare function externalPackageOf(source: ComponentSource): string;
+export declare function serialiseComponentId(id: ComponentId): string;
+export declare function compareComponentId(a: ComponentId, b: ComponentId): number;

package/dist/id.js

@@ -0,0 +1,31 @@
+export function externalPackageOf(source) {
+    if (source.type === "external")
+        return source.package;
+    throw new Error(`externalPackageOf called with non-external source (type=${source.type}). Caller must narrow before invoking, or use a different accessor.`);
+}
+function sourceSegment(source) {
+    switch (source.type) {
+        case "external":
+            return `external:${source.package}`;
+        case "local":
+            return `local:${source.filePath}`;
+        case "unknown":
+            return "unknown";
+    }
+}
+function identityPayload(id) {
+    switch (id.kind) {
+        case "custom-element":
+            return id.tagName;
+        case "react-component":
+        case "vue-component":
+            return id.export;
+    }
+}
+export function serialiseComponentId(id) {
+    return `${id.kind}:${sourceSegment(id.source)}::${identityPayload(id)}`;
+}
+export function compareComponentId(a, b) {
+    return serialiseComponentId(a).localeCompare(serialiseComponentId(b));
+}
+//# sourceMappingURL=id.js.map

package/dist/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../src/id.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,iBAAiB,CAAC,MAAuB;IACvD,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,MAAM,CAAC,OAAO,CAAC;IACtD,MAAM,IAAI,KAAK,CACb,2DAA2D,MAAM,CAAC,IAAI,qEAAqE,CAC5I,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,MAAuB;IAC5C,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,UAAU;YACb,OAAO,YAAY,MAAM,CAAC,OAAO,EAAE,CAAC;QACtC,KAAK,OAAO;YACV,OAAO,SAAS,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpC,KAAK,SAAS;YACZ,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,EAAe;IACtC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,gBAAgB;YACnB,OAAO,EAAE,CAAC,OAAO,CAAC;QACpB,KAAK,iBAAiB,CAAC;QACvB,KAAK,eAAe;YAClB,OAAO,EAAE,CAAC,MAAM,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,EAAe;IAClD,OAAO,GAAG,EAAE,CAAC,IAAI,IAAI,aAAa,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,eAAe,CAAC,EAAE,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,CAAc,EAAE,CAAc;IAC/D,OAAO,oBAAoB,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { ComponentId, ComponentKind, ComponentSource, Lifecycle, ManifestComponent, ManifestEvent, ManifestFile, ManifestProp, ManifestSlot, ManifestSource, } from "./types.js";
+export { serialiseComponentId, compareComponentId, externalPackageOf } from "./id.js";
+export { validateManifest } from "./validate.js";
+export type { ValidationResult } from "./validate.js";
+export { manifestJsonSchema } from "./schema.js";
+export { ManifestBuilder } from "./builder.js";
+export type { TagName, WrapperId, ImportRole, ImportEntry, IndexedComponent, ComponentIndex, Loc, WarningCode, Warning, ScanConfig, PropUsage, OccurrenceVia, Occurrence, WrapperDef, FileImport, ParseResult, ParseContext, ParserPlugin, ScanEnvelope, ScanOutput, ManifestRef, ScanStats, DetectorId, LocalDefinition, LocalDefinitionIndex, } from "./scan-types.js";
+export { asTagName, asWrapperId, emptyLocalIndex } from "./scan-types.js";
+export * from "./output-types.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { serialiseComponentId, compareComponentId, externalPackageOf } from "./id.js";
+export { validateManifest } from "./validate.js";
+export { manifestJsonSchema } from "./schema.js";
+export { ManifestBuilder } from "./builder.js";
+export { asTagName, asWrapperId, emptyLocalIndex } from "./scan-types.js";
+export * from "./output-types.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAa/C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAE1E,cAAc,mBAAmB,CAAC"}

package/dist/output-types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Types describing the CLI's emitted JSON artifact (two-grain: components +
+ * occurrences). Lives in plugin-core so consumers (cli, future analytics,
+ * agents) share one source of truth without depending on cli internals.
+ */
+import type { OccurrenceVia } from "./via-types.js";
+export type ComponentScope = "ds" | "external" | "local";
+export type ComponentKindOutput = "custom-element" | "react-component" | "vue-component";
+export type ViaKindOutput = "html-tag" | "lit-template" | "react-wrapper" | "direct-import" | "vue-template";
+export type OutputIdentity = {
+    scope: ComponentScope;
+    kind: ComponentKindOutput;
+    /** Present for ds + external; absent for local. */
+    packageName?: string;
+    /** For react-component / vue-component. */
+    exportName?: string;
+    /** For custom-element. */
+    tagName?: string;
+    via: {
+        kind: ViaKindOutput;
+    };
+    /** Present for local; absent for ds/external. */
+    repoId?: string;
+    /** Present for local; absent for ds/external. Repo-relative path of the defining file. */
+    filePath?: string;
+};
+export type OutputManifest = {
+    lifecycle?: {
+        status: "stable" | "deprecated";
+        supersededBy?: {
+            packageName: string;
+            exportName: string;
+        };
+    };
+    props?: Record<string, {
+        default?: string | number | boolean | null;
+    }>;
+};
+export type DynamicKind = "spread" | "expr" | "identifier";
+/**
+ * Per-occurrence prop value:
+ * - a literal (string/number/boolean/null) when the source value is statically known,
+ * - a `{ __dynamic }` marker when the value is a non-literal expression,
+ * - or absent (key omitted from the map) when the prop was not set on the occurrence.
+ */
+export type PropValueState = string | number | boolean | null | {
+    __dynamic: DynamicKind;
+};
+export type PropDistribution = {
+    /** Stringified literal value -> occurrence count. */
+    distribution: Record<string, number>;
+    dynamic: number;
+    omitted: number;
+    defaultApplied: number;
+};
+export type OutputComponent = {
+    id: string;
+    identity: OutputIdentity;
+    derivedTags: string[];
+    manifest: OutputManifest | null;
+    stats: {
+        occurrenceCount: number;
+        fileCount: number;
+    };
+    props: Record<string, PropDistribution>;
+};
+export type OutputOccurrence = {
+    componentId: string;
+    filePath: string;
+    line: number;
+    column: number;
+    via: OccurrenceVia;
+    props: Record<string, PropValueState>;
+};

package/dist/output-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=output-types.js.map

package/dist/output-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-types.js","sourceRoot":"","sources":["../src/output-types.ts"],"names":[],"mappings":""}

package/dist/scan-types.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Shared types consumed by all parser packages and the CLI host.
+ *
+ * Parsers (`parser-react`, `parser-vue`, `parser-lit`, `parser-html`) cannot
+ * depend on the CLI package (circular), so every type that crosses the
+ * parser ↔ CLI boundary lives here in `plugin-core`.
+ */
+import type { OutputComponent, OutputOccurrence } from "./output-types.js";
+import type { ComponentId, ManifestComponent, ManifestSource } from "./types.js";
+import type { OccurrenceVia } from "./via-types.js";
+declare const __brand: unique symbol;
+type Brand<K, T> = K & {
+    readonly [__brand]: T;
+};
+export type TagName = Brand<string, "TagName">;
+export type WrapperId = Brand<string, "WrapperId">;
+/** Unsafe constructors — use only at the data-ingest boundary. */
+export declare const asTagName: (s: string) => TagName;
+export declare const asWrapperId: (s: string) => WrapperId;
+export type ImportRole = "native" | "react";
+export type ImportEntry = {
+    specifier: string;
+    export?: string;
+};
+export type IndexedComponent = (Extract<ManifestComponent, {
+    kind: "custom-element";
+}> & {
+    className?: string;
+    imports: Partial<Record<ImportRole, ImportEntry[]>>;
+}) | Extract<ManifestComponent, {
+    kind: "react-component" | "vue-component";
+}>;
+export type ComponentIndex = {
+    /** key = serialiseComponentId(id) */
+    byId: Map<string, IndexedComponent>;
+    /** custom-element only, keyed by tagName */
+    byTag: Map<string, Extract<IndexedComponent, {
+        kind: "custom-element";
+    }>>;
+    /** key = `${specifier}::${export}` — covers WC react-wrappers AND direct react/vue imports */
+    byImport: Map<string, IndexedComponent>;
+    /** key = native specifier (WC bare imports for side-effect registration) */
+    byNativeSpecifier: Map<string, Extract<IndexedComponent, {
+        kind: "custom-element";
+    }>>;
+    /** Local-component definitions discovered in repo source. */
+    local: LocalDefinitionIndex;
+};
+export type DetectorId = "react-default-fn" | "react-arrow" | "react-class" | "react-forward-ref" | "react-memo" | "vue-sfc" | "vue-define-component" | "vue-functional" | "wc-decorator" | "wc-customelements-define";
+export type LocalDefinition = {
+    /** componentId.source is always { type: "local", filePath }. */
+    componentId: ComponentId;
+    /**
+     * Local export identifier. For default exports, this is the declaration
+     * name (e.g. "Button" for `export default function Button()`); use
+     * `isDefault` to distinguish default from named-with-same-name.
+     */
+    exportName: string;
+    /** True when emitted via `export default`. */
+    isDefault: boolean;
+    detector: DetectorId;
+};
+export type LocalDefinitionIndex = {
+    /** POSIX repo-relative filePath → definitions in that file. */
+    byPath: Map<string, LocalDefinition[]>;
+    /** hyphenated-tag → WC local definition. */
+    byTag: Map<string, LocalDefinition>;
+};
+export declare const emptyLocalIndex: LocalDefinitionIndex;
+export type Loc = {
+    file: string;
+    line: number;
+    column: number;
+};
+export type WarningCode = "MISSING_REACT_EXPORT_EXTENSION" | "PARSE_FAILURE" | "IMPORT_UNRESOLVABLE" | "MANIFEST_TAG_COLLISION" | "EMPTY_INCLUDE";
+interface WarningBase {
+    message: string;
+}
+export type Warning = (WarningBase & {
+    code: "PARSE_FAILURE";
+    file: string;
+    line: number;
+}) | (WarningBase & {
+    code: "IMPORT_UNRESOLVABLE";
+    file: string;
+    line: number;
+}) | (WarningBase & {
+    code: "MISSING_REACT_EXPORT_EXTENSION";
+    package: string;
+    file: string;
+}) | (WarningBase & {
+    code: "MANIFEST_TAG_COLLISION";
+    package: string;
+}) | (WarningBase & {
+    code: "EMPTY_INCLUDE";
+});
+/**
+ * The subset of the CLI's resolved configuration that parsers actually consume.
+ * Using a structural interface rather than the full `ResolvedConfig` keeps
+ * parsers decoupled from CLI-specific fields (configPath, output, etc.).
+ */
+export type ScanConfig = {
+    packageScopes: string[];
+    captureValues: boolean;
+};
+export type PropUsage = {
+    name: string;
+    isDynamic: boolean;
+    literalValue?: string | number | boolean;
+    /**
+     * When `isDynamic` is true, distinguishes the kind of dynamic value:
+     *   - "spread"     — JSX spread attribute (`{...rest}`); name is `"...rest"`.
+     *   - "identifier" — bare identifier reference (`prop={someVar}`).
+     *   - "expr"       — any other expression (`prop={a + b}`, calls, ternaries, etc.).
+     * Omitted when `isDynamic` is false.
+     */
+    dynamicKind?: "spread" | "expr" | "identifier";
+};
+export type { OccurrenceVia } from "./via-types.js";
+export type Occurrence = {
+    componentId: ComponentId;
+    loc: Loc;
+    via: OccurrenceVia;
+    props: PropUsage[];
+    events: string[];
+};
+export type WrapperDef = {
+    id: WrapperId;
+    name: string;
+    file: string;
+    exportName: string;
+    componentDeps: ComponentId[];
+};
+export type FileImport = {
+    file: string;
+    /** Local binding name as used at the import site. */
+    imported: string;
+    source: string;
+    loc: Loc;
+};
+export type ParseResult = {
+    occurrences: Occurrence[];
+    wrappers: WrapperDef[];
+    imports: FileImport[];
+    warnings: Warning[];
+};
+export type ParseContext = {
+    index: ComponentIndex;
+    config: ScanConfig;
+    resolveImport: (from: string, spec: string) => string | null;
+    repoRoot: string;
+};
+export interface ParserPlugin {
+    name: string;
+    extensions: string[];
+    parse(file: string, source: string, ctx: ParseContext): ParseResult;
+}
+export type ScanEnvelope = {
+    scanId: string;
+    repoId: string;
+    commitSha: string | null;
+    branch: string | null;
+    timestamp: string;
+    toolVersion: string;
+    cwd: string;
+};
+export type ManifestRef = {
+    source: ManifestSource;
+    package: string;
+    path: string;
+    version: string | null;
+};
+export type ScanStats = {
+    filesScanned: number;
+    filesWithUsage: number;
+    scanDurationMs: number;
+    componentsDetected: number;
+    totalOccurrences: number;
+};
+export type ScanOutput = {
+    envelope: ScanEnvelope;
+    manifests: ManifestRef[];
+    stats: ScanStats;
+    components: OutputComponent[];
+    occurrences: OutputOccurrence[];
+};

package/dist/scan-types.js

@@ -0,0 +1,8 @@
+/** Unsafe constructors — use only at the data-ingest boundary. */
+export const asTagName = (s) => s;
+export const asWrapperId = (s) => s;
+export const emptyLocalIndex = {
+    byPath: new Map(),
+    byTag: new Map(),
+};
+//# sourceMappingURL=scan-types.js.map

package/dist/scan-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-types.js","sourceRoot":"","sources":["../src/scan-types.ts"],"names":[],"mappings":"AAqBA,kEAAkE;AAClE,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAS,EAAW,EAAE,CAAC,CAAY,CAAC;AAC9D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAS,EAAa,EAAE,CAAC,CAAc,CAAC;AAsEpE,MAAM,CAAC,MAAM,eAAe,GAAyB;IACnD,MAAM,EAAE,IAAI,GAAG,EAAE;IACjB,KAAK,EAAE,IAAI,GAAG,EAAE;CACjB,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,205 @@
+export declare const manifestJsonSchema: {
+    readonly $id: "https://component-compass.dev/manifest-2.0.0.json";
+    readonly type: "object";
+    readonly required: readonly ["schemaVersion", "source", "package", "components"];
+    readonly additionalProperties: true;
+    readonly properties: {
+        readonly schemaVersion: {
+            readonly const: "2.0.0";
+        };
+        readonly source: {
+            readonly enum: readonly ["cem", "react", "vue"];
+        };
+        readonly package: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly components: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly required: readonly ["kind", "source", "deprecated", "props"];
+                readonly properties: {
+                    readonly kind: {
+                        readonly enum: readonly ["custom-element", "react-component", "vue-component"];
+                    };
+                    readonly source: {
+                        readonly type: "object";
+                        readonly required: readonly ["type"];
+                        readonly properties: {
+                            readonly type: {
+                                readonly enum: readonly ["external", "local"];
+                            };
+                            readonly package: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly filePath: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                        readonly allOf: readonly [{
+                            readonly if: {
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "external";
+                                    };
+                                };
+                            };
+                            readonly then: {
+                                readonly required: readonly ["package"];
+                            };
+                        }, {
+                            readonly if: {
+                                readonly properties: {
+                                    readonly type: {
+                                        readonly const: "local";
+                                    };
+                                };
+                            };
+                            readonly then: {
+                                readonly required: readonly ["filePath"];
+                            };
+                        }];
+                    };
+                    readonly export: {
+                        readonly type: "string";
+                    };
+                    readonly tagName: {
+                        readonly type: "string";
+                    };
+                    readonly deprecated: {
+                        readonly oneOf: readonly [{
+                            readonly type: "boolean";
+                        }, {
+                            readonly type: "string";
+                        }];
+                    };
+                    readonly props: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "object";
+                            readonly required: readonly ["name"];
+                            readonly properties: {
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                    readonly events: {
+                        readonly type: "array";
+                    };
+                    readonly slots: {
+                        readonly type: "array";
+                    };
+                    readonly cssParts: {
+                        readonly type: "array";
+                    };
+                    readonly cssProperties: {
+                        readonly type: "array";
+                    };
+                };
+                readonly allOf: readonly [{
+                    readonly if: {
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "custom-element";
+                            };
+                        };
+                    };
+                    readonly then: {
+                        readonly required: readonly ["tagName"];
+                    };
+                }, {
+                    readonly if: {
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "react-component";
+                            };
+                        };
+                    };
+                    readonly then: {
+                        readonly required: readonly ["export"];
+                    };
+                }, {
+                    readonly if: {
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "vue-component";
+                            };
+                        };
+                    };
+                    readonly then: {
+                        readonly required: readonly ["export"];
+                    };
+                }];
+            };
+        };
+    };
+    readonly allOf: readonly [{
+        readonly if: {
+            readonly properties: {
+                readonly source: {
+                    readonly const: "react";
+                };
+            };
+        };
+        readonly then: {
+            readonly properties: {
+                readonly components: {
+                    readonly items: {
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "react-component";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }, {
+        readonly if: {
+            readonly properties: {
+                readonly source: {
+                    readonly const: "vue";
+                };
+            };
+        };
+        readonly then: {
+            readonly properties: {
+                readonly components: {
+                    readonly items: {
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "vue-component";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }, {
+        readonly if: {
+            readonly properties: {
+                readonly source: {
+                    readonly const: "cem";
+                };
+            };
+        };
+        readonly then: {
+            readonly properties: {
+                readonly components: {
+                    readonly items: {
+                        readonly properties: {
+                            readonly kind: {
+                                readonly const: "custom-element";
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }];
+};

package/dist/schema.js

@@ -0,0 +1,62 @@
+// biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for source⇄kind validation
+export const manifestJsonSchema = {
+    $id: "https://component-compass.dev/manifest-2.0.0.json",
+    type: "object",
+    required: ["schemaVersion", "source", "package", "components"],
+    additionalProperties: true,
+    properties: {
+        schemaVersion: { const: "2.0.0" },
+        source: { enum: ["cem", "react", "vue"] },
+        package: { type: "string", minLength: 1 },
+        components: {
+            type: "array",
+            items: {
+                type: "object",
+                required: ["kind", "source", "deprecated", "props"],
+                properties: {
+                    kind: { enum: ["custom-element", "react-component", "vue-component"] },
+                    source: {
+                        type: "object",
+                        required: ["type"],
+                        properties: {
+                            type: { enum: ["external", "local"] },
+                            package: { type: "string", minLength: 1 },
+                            filePath: { type: "string", minLength: 1 },
+                        },
+                        allOf: [
+                            // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for source.type conditional
+                            { if: { properties: { type: { const: "external" } } }, then: { required: ["package"] } },
+                            // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for source.type conditional
+                            { if: { properties: { type: { const: "local" } } }, then: { required: ["filePath"] } },
+                        ],
+                    },
+                    export: { type: "string" },
+                    tagName: { type: "string" },
+                    deprecated: { oneOf: [{ type: "boolean" }, { type: "string" }] },
+                    props: { type: "array", items: { type: "object", required: ["name"], properties: { name: { type: "string" } } } },
+                    events: { type: "array" },
+                    slots: { type: "array" },
+                    cssParts: { type: "array" },
+                    cssProperties: { type: "array" },
+                },
+                allOf: [
+                    // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for kind conditional
+                    { if: { properties: { kind: { const: "custom-element" } } }, then: { required: ["tagName"] } },
+                    // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for kind conditional
+                    { if: { properties: { kind: { const: "react-component" } } }, then: { required: ["export"] } },
+                    // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for kind conditional
+                    { if: { properties: { kind: { const: "vue-component" } } }, then: { required: ["export"] } },
+                ],
+            },
+        },
+    },
+    allOf: [
+        // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for source conditional
+        { if: { properties: { source: { const: "react" } } }, then: { properties: { components: { items: { properties: { kind: { const: "react-component" } } } } } } },
+        // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for source conditional
+        { if: { properties: { source: { const: "vue" } } }, then: { properties: { components: { items: { properties: { kind: { const: "vue-component" } } } } } } },
+        // biome-ignore lint/suspicious/noThenProperty: JSON Schema if/then for source conditional
+        { if: { properties: { source: { const: "cem" } } }, then: { properties: { components: { items: { properties: { kind: { const: "custom-element" } } } } } } },
+    ],
+};
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+export type ComponentKind = "custom-element" | "react-component" | "vue-component";
+export type ComponentSource = {
+    type: "external";
+    package: string;
+} | {
+    type: "local";
+    filePath: string;
+} | {
+    type: "unknown";
+};
+export type ComponentId = {
+    kind: "custom-element";
+    tagName: string;
+    source: ComponentSource;
+} | {
+    kind: "react-component";
+    export: string;
+    source: ComponentSource;
+} | {
+    kind: "vue-component";
+    export: string;
+    source: ComponentSource;
+};
+export type ManifestProp = {
+    name: string;
+    type?: string;
+    deprecated?: boolean | string;
+    default?: string | number | boolean | null;
+};
+export type ManifestEvent = {
+    name: string;
+    deprecated?: boolean | string;
+};
+export type ManifestSlot = {
+    name: string;
+};
+export type Lifecycle = {
+    status: "stable";
+} | {
+    status: "deprecated";
+    supersededBy?: {
+        packageName: string;
+        exportName: string;
+    };
+};
+type ComponentBase = {
+    source: ComponentSource;
+    deprecated: boolean | string;
+    props: ManifestProp[];
+    lifecycle?: Lifecycle;
+};
+export type ManifestComponent = (ComponentBase & {
+    kind: "custom-element";
+    tagName: string;
+    events?: ManifestEvent[];
+    slots?: ManifestSlot[];
+    cssParts?: Array<{
+        name: string;
+    }>;
+    cssProperties?: Array<{
+        name: string;
+    }>;
+}) | (ComponentBase & {
+    kind: "react-component";
+    export: string;
+}) | (ComponentBase & {
+    kind: "vue-component";
+    export: string;
+});
+export type ManifestSource = "cem" | "react" | "vue";
+export type ManifestFile = {
+    schemaVersion: "2.0.0";
+    source: ManifestSource;
+    package: string;
+    components: ManifestComponent[];
+};
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/validate.d.ts

@@ -0,0 +1,9 @@
+import type { ManifestFile } from "./types.js";
+export type ValidationResult = {
+    ok: true;
+    data: ManifestFile;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function validateManifest(doc: unknown): ValidationResult;

package/dist/validate.js

@@ -0,0 +1,18 @@
+import { createRequire } from "node:module";
+import { manifestJsonSchema } from "./schema.js";
+// ajv is a CJS-only package. Under module: NodeNext, the bare default import
+// is the namespace, not the class. createRequire is Node's official escape
+// hatch for loading CJS from ESM. (Same pattern as packages/cli/src/config/schema.ts.)
+const require = createRequire(import.meta.url);
+const Ajv = require("ajv").default ?? require("ajv");
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validate = ajv.compile(manifestJsonSchema);
+export function validateManifest(doc) {
+    if (validate(doc))
+        return { ok: true, data: doc };
+    return {
+        ok: false,
+        errors: (validate.errors ?? []).map((e) => `${e.instancePath || "/"} ${e.message ?? "unknown error"}`),
+    };
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGjD,6EAA6E;AAC7E,2EAA2E;AAC3E,uFAAuF;AACvF,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAA2B,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC;AAE7E,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;AACxD,MAAM,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAMjD,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,IAAI,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAmB,EAAE,CAAC;IAClE,OAAO;QACL,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CACjC,CAAC,CAAc,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,IAAI,GAAG,IAAI,CAAC,CAAC,OAAO,IAAI,eAAe,EAAE,CAC/E;KACF,CAAC;AACJ,CAAC"}

package/dist/via-types.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Discriminated union describing how a component instance was used.
+ * Shared between parser-emitted Occurrence (scan-types.ts) and the artifact-shape
+ * OutputOccurrence (output-types.ts). Lives in its own module to keep the two
+ * type files acyclic.
+ */
+export type OccurrenceVia = {
+    kind: "html-tag";
+} | {
+    kind: "lit-template";
+    specifier?: string;
+} | {
+    kind: "react-wrapper";
+    specifier: string;
+    import: string;
+} | {
+    kind: "direct-import";
+    specifier: string;
+    import: string;
+} | {
+    kind: "vue-template";
+    specifier: string;
+    import: string;
+};

package/dist/via-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=via-types.js.map

package/dist/via-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"via-types.js","sourceRoot":"","sources":["../src/via-types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@component-compass/plugin-core",
+  "version": "0.0.0-pr-3-8916f3c-20260507145532",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "biome lint src tests",
+    "test": "vitest run --passWithNoTests",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "ajv": "^8.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}