@component-compass/plugin-core 0.0.1 → 0.0.2

package/dist/enrichment.d.ts

@@ -0,0 +1,35 @@
+import type { IndexedComponent } from "./scan-types.js";
+/**
+ * Manifest source for enrichment of a resolver-discovered leaf package.
+ *
+ *   - "authored": leaf shipped a `custom-elements.json` or
+ *                 `component-compass-manifest.json` at its package root.
+ *   - "derived":  leaf carries no authored manifest but `manifest-react` /
+ *                 `manifest-vue` extractors (Phase 4) produced one from source.
+ *   - null:       no enrichment available — identity stays opaque
+ *                 (`components[].manifest === null` in the artifact).
+ *
+ * Open envelope: `data` shape grows in Phase 3 (CEM depth) and Phase 4
+ * (extractor maturity) without changing this discriminator.
+ */
+export type Enrichment = {
+    source: "authored";
+    data: AuthoredManifestData;
+} | {
+    source: "derived";
+    data: DerivedManifestData;
+} | null;
+export type AuthoredManifestData = {
+    /** Every component declared in the leaf's authored manifest. */
+    components: IndexedComponent[];
+    /** Absolute filesystem path of the loaded manifest file. */
+    manifestPath: string;
+    /** Authored format the manifest was loaded from. */
+    manifestKind: "cem" | "component-compass-manifest";
+    /** Leaf package's `version` field, when readable. */
+    packageVersion?: string;
+};
+export type DerivedManifestData = {
+    /** Components extracted from leaf source by Phase 4 extractors. */
+    components: IndexedComponent[];
+};

package/dist/enrichment.js

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

package/dist/enrichment.js.map

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

package/dist/index.d.ts

@@ -4,6 +4,9 @@ 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, DetectorId, LocalDefinition, LocalDefinitionIndex, } from "./scan-types.js";
+export type { TagName, WrapperId, ImportRole, ImportEntry, IndexedComponent, Loc, WarningCode, Warning, ScanConfig, PropUsage, OccurrenceVia, Occurrence, WrapperDef, FileImport, ParseResult, ParseContext, ParserPlugin, ScanEnvelope, ScanOutput, ManifestRef, ScanStats, DetectorId, LocalDefinition, LocalDefinitionIndex, ResolveLazyManifest, LookupByTag, LazyResolverHit, } from "./scan-types.js";
 export { asTagName, asWrapperId, emptyLocalIndex } from "./scan-types.js";
+export type { Enrichment, AuthoredManifestData, DerivedManifestData } from "./enrichment.js";
+export { computeOccurrenceId } from "./occurrence-id.js";
+export type { CompositionRollup } from "./output-types.js";
 export * from "./output-types.js";

package/dist/index.js

@@ -3,5 +3,6 @@ export { validateManifest } from "./validate.js";
 export { manifestJsonSchema } from "./schema.js";
 export { ManifestBuilder } from "./builder.js";
 export { asTagName, asWrapperId, emptyLocalIndex } from "./scan-types.js";
+export { computeOccurrenceId } from "./occurrence-id.js";
 export * from "./output-types.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +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"}
+{"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;AAc/C,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAI1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD,cAAc,mBAAmB,CAAC"}

package/dist/occurrence-id.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Stable per-occurrence id keyed on (componentId, filePath, line, column).
+ *
+ * Inputs use the FINAL artifact componentId string (the hashed form that
+ * appears on `OutputOccurrence.componentId`), so downstream consumers can
+ * re-derive: `id === computeOccurrenceId(o.componentId, o.filePath, o.line, o.column)`.
+ *
+ * 64 bits of entropy via 16-char SHA-256 truncation. Birthday-bound collision
+ * at ~4 billion occurrences; full hash is overkill for current scale.
+ */
+export declare function computeOccurrenceId(componentId: string, filePath: string, line: number, column: number): string;

package/dist/occurrence-id.js

@@ -0,0 +1,18 @@
+import { createHash } from "node:crypto";
+/**
+ * Stable per-occurrence id keyed on (componentId, filePath, line, column).
+ *
+ * Inputs use the FINAL artifact componentId string (the hashed form that
+ * appears on `OutputOccurrence.componentId`), so downstream consumers can
+ * re-derive: `id === computeOccurrenceId(o.componentId, o.filePath, o.line, o.column)`.
+ *
+ * 64 bits of entropy via 16-char SHA-256 truncation. Birthday-bound collision
+ * at ~4 billion occurrences; full hash is overkill for current scale.
+ */
+export function computeOccurrenceId(componentId, filePath, line, column) {
+    return createHash("sha256")
+        .update(`${componentId}|${filePath}|${line}|${column}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+//# sourceMappingURL=occurrence-id.js.map

package/dist/occurrence-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"occurrence-id.js","sourceRoot":"","sources":["../src/occurrence-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,WAAmB,EACnB,QAAgB,EAChB,IAAY,EACZ,MAAc;IAEd,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,GAAG,WAAW,IAAI,QAAQ,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;SACtD,MAAM,CAAC,KAAK,CAAC;SACb,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC"}

package/dist/output-types.d.ts

@@ -3,6 +3,7 @@
  * 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";
@@ -24,6 +25,7 @@ export type OutputIdentity = {
     filePath?: string;
 };
 export type OutputManifest = {
+    source: "authored" | "derived";
     lifecycle?: {
         status: "stable" | "deprecated";
         supersededBy?: {
@@ -52,11 +54,23 @@ export type PropDistribution = {
     omitted: number;
     defaultApplied: number;
 };
-export type OutputEdges = {
-    /** componentIds this component renders. Empty in v1, schema slot. */
-    renders: string[];
-    /** componentIds that render this component. Empty in v1, schema slot. */
-    renderedBy: string[];
+export type CompositionRollup = {
+    /** child componentId → count of direct-child relationships */
+    rendersByCount: Record<string, number>;
+    /** parent componentId → count of being-direct-child relationships */
+    renderedByCount: Record<string, number>;
+    /** # of this component's occurrences with no tracked parent */
+    isRootCount: number;
+    /** # of this component's occurrences with no tracked direct children */
+    isLeafCount: number;
+    /** mean of all occurrences' depth */
+    avgDepth: number;
+    /** deepest observed depth */
+    maxDepth: number;
+    /** mean direct children per occurrence */
+    avgChildCount: number;
+    /** most direct children on any occurrence */
+    maxChildCount: number;
 };
 export type OutputComponent = {
     id: string;
@@ -68,12 +82,22 @@ export type OutputComponent = {
         fileCount: number;
     };
     props: Record<string, PropDistribution>;
-    edges: OutputEdges;
+    /** Phase 2: per-component composition rollup. Omitted when occurrenceCount is 0. */
+    composition?: CompositionRollup;
 };
 export type OutputOccurrence = {
     componentId: string;
     filePath: string;
     line: number;
     column: number;
+    via: OccurrenceVia;
     props: Record<string, PropValueState>;
+    /** Phase 2: stable id keyed on (componentId, filePath, line, column). */
+    occurrenceId: string;
+    /** Phase 2: occurrenceId of nearest tracked ancestor. Absent if root in this scope. */
+    parentOccurrenceId?: string;
+    /** Phase 2: denormalisation of parent's componentId; convenience for downstream queries. */
+    parentComponentId?: string;
+    /** Phase 2: distance from highest tracked-rootless ancestor in same lexical scope. */
+    depth?: number;
 };

package/dist/output-types.js

@@ -1,7 +1,2 @@
-/**
- * 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.
- */
 export {};
 //# sourceMappingURL=output-types.js.map

package/dist/output-types.js.map

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

package/dist/scan-types.d.ts

@@ -6,7 +6,8 @@
  * parser ↔ CLI boundary lives here in `plugin-core`.
  */
 import type { OutputComponent, OutputOccurrence } from "./output-types.js";
-import type { ComponentId, ManifestComponent } from "./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;
@@ -29,22 +30,21 @@ export type IndexedComponent = (Extract<ManifestComponent, {
 }) | 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;
+/**
+ * A single resolution outcome for one `(fromFile, specifier, exportName)`
+ * triple. `matched` is null when the resolved leaf has no manifest entry
+ * for `exportName` — the caller should fall back to opaque opportunistic
+ * emission (current `react-component` / `vue-component` with `manifest: null`
+ * shape, package = `leafPackage`).
+ */
+export type LazyResolverHit = {
+    leafPackage: string;
+    matched: IndexedComponent | null;
 };
+export type ResolveLazyManifest = (fromFile: string, specifier: string, exportName: string) => LazyResolverHit | null;
+export type LookupByTag = (tagName: string) => Extract<IndexedComponent, {
+    kind: "custom-element";
+}> | null;
 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 }. */
@@ -71,7 +71,7 @@ export type Loc = {
     line: number;
     column: number;
 };
-export type WarningCode = "MISSING_REACT_EXPORT_EXTENSION" | "PARSE_FAILURE" | "IMPORT_UNRESOLVABLE" | "MANIFEST_TAG_COLLISION" | "EMPTY_INCLUDE";
+export type WarningCode = "PARSE_FAILURE" | "IMPORT_UNRESOLVABLE" | "MANIFEST_TAG_COLLISION" | "EMPTY_INCLUDE";
 interface WarningBase {
     message: string;
 }
@@ -83,10 +83,6 @@ export type Warning = (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;
@@ -115,30 +111,28 @@ export type PropUsage = {
      */
     dynamicKind?: "spread" | "expr" | "identifier";
 };
-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;
-};
+export type { OccurrenceVia } from "./via-types.js";
 export type Occurrence = {
     componentId: ComponentId;
     loc: Loc;
     via: OccurrenceVia;
     props: PropUsage[];
     events: string[];
+    /**
+     * Phase 2: parser-side parent reference. Index into the same
+     * ParseResult.occurrences array. `undefined` = no tracked parent in this
+     * lexical scope. The CLI's projection layer (`parseResultsToOccurrences`)
+     * resolves this index into `parentOccurrenceId` / `parentComponentId`
+     * strings. Cross-file composition is out of scope (per spec non-goal),
+     * so the index is local to one ParseResult.
+     */
+    parentRef?: number;
+    /**
+     * Phase 2: distance from the highest tracked-rootless ancestor in the
+     * same lexical scope. 0 for roots; matches `parentStack.length` at the
+     * time the occurrence was emitted.
+     */
+    depth?: number;
 };
 export type WrapperDef = {
     id: WrapperId;
@@ -161,9 +155,12 @@ export type ParseResult = {
     warnings: Warning[];
 };
 export type ParseContext = {
-    index: ComponentIndex;
+    /** Local-component definitions discovered in repo source. */
+    localIndex: LocalDefinitionIndex;
     config: ScanConfig;
     resolveImport: (from: string, spec: string) => string | null;
+    resolveLazyManifest: ResolveLazyManifest;
+    lookupByTag: LookupByTag;
     repoRoot: string;
 };
 export interface ParserPlugin {
@@ -180,9 +177,23 @@ export type ScanEnvelope = {
     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[];
 };
-export {};

package/dist/scan-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"scan-types.js","sourceRoot":"","sources":["../src/scan-types.ts"],"names":[],"mappings":"AAoBA,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"}
+{"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;AAoFpE,MAAM,CAAC,MAAM,eAAe,GAAyB;IACnD,MAAM,EAAE,IAAI,GAAG,EAAE;IACjB,KAAK,EAAE,IAAI,GAAG,EAAE;CACjB,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

@@ -1,6 +1,6 @@
 {
   "name": "@component-compass/plugin-core",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",