@knapsack/source-conflicts-adapter 4.89.10--canary.7202.53e0d58.0

package/.eslintrc.cjs

@@ -0,0 +1,9 @@
+module.exports = {
+  extends: [
+    '@knapsack/eslint-config-starter/react',
+    '@knapsack/eslint-config-starter',
+  ],
+  parserOptions: { tsconfigRootDir: __dirname },
+  ignorePatterns: [],
+  rules: {},
+};

package/README.md

@@ -0,0 +1,269 @@
+# @knapsack/source-conflicts-adapter
+
+Detects and compares entity documentation conflicts across multiple ingestion sources (e.g. Storybook, Knapsack, Figma). Implemented as a `ContextSrcAdapter` so it integrates with the ingest pipeline and can also be used standalone via its `analyzer` interface.
+
+---
+
+## Overview
+
+When the same entity (e.g. `button.react.mdx`) is contributed by more than one source, the sections within each file may diverge. This adapter:
+
+1. **Indexes** the entities directory to find files contributed by multiple sources
+2. **Groups** files that map to the same canonical entity path
+3. **Detects** conflicts by parsing each MDX/MD file into anchored sections, then comparing section content across sources with a chain of canonicalization rules
+4. **Reports** per-anchor verdicts: `ALL_SAME`, `DIFFERENT`, or `MISSING`
+
+### Entity file layout
+
+```
+entities/
+└── <entityKind>/               # e.g. "components", "tokens"
+    ├── button.react.KNAPSACK-abc123.mdx
+    ├── button.react.STORYBOOK-def456.mdx
+    └── card.react.KNAPSACK-111aaa.mdx
+```
+
+Files with the same base name and extension (e.g. `button.react.mdx`) but different `<SOURCE>-<hash>` segments are candidates for conflict detection.
+
+---
+
+## Installation
+
+This package lives in the monorepo at `libs/ingest-pipeline/adapters/source-conflicts/` and is consumed as a workspace dependency:
+
+```json
+"@knapsack/source-conflicts-adapter": "workspace:*"
+```
+
+---
+
+## Quick start — standalone analyzer
+
+The fastest way to detect conflicts without running the full pipeline is via the `analyzer` interface:
+
+```typescript
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { analyze } from '@knapsack/source-conflicts-adapter';
+import { createLogger } from '@knapsack/utils';
+
+const entitiesRootAbs = '/absolute/path/to/entities';
+const outputFile = path.join(entitiesRootAbs, 'source-conflicts-result.json');
+const logger = createLogger('source-conflicts');
+
+const result = await analyze({ entitiesRootAbs }, { logger });
+
+await fs.writeFile(outputFile, JSON.stringify(result, null, 2), 'utf8');
+console.log(`Wrote results to ${outputFile}`);
+```
+
+The output file contains the full `SourceConflictsAnalysisResult` as JSON — `groupResults` with per-anchor verdicts and previews, plus `skippedGroupKeys` for any groups that were excluded.
+
+---
+
+## Configuration
+
+```typescript
+import type { SourceConflictsConfig } from '@knapsack/source-conflicts-adapter';
+
+const config: SourceConflictsConfig = {
+  /** Required: absolute path to the directory containing <entityKind>/ subdirectories. */
+  entitiesRootAbs: '/path/to/entities',
+
+  /** Optional: scope identifiers forwarded to fingerprint computation and logging. */
+  siteId: 'my-site',
+  userId: 'user-123',
+  configId: 'config-abc',
+};
+```
+
+---
+
+## Pipeline usage
+
+The adapter implements the full `ContextSrcAdapter<SourceConflictsConfig, SourceConflictsAnalysisResult>` interface:
+
+```typescript
+import { sourceConflictsAdapter } from '@knapsack/source-conflicts-adapter';
+import type { SourceConflictsConfig } from '@knapsack/source-conflicts-adapter';
+import type { RuntimeDeps } from '@knapsack/adapter-core';
+
+// Validate config before running
+const configError = sourceConflictsAdapter.validator.validateConfig(config);
+if (configError) throw new Error(configError);
+
+// Parse stage: indexes entities + writes manifest
+await sourceConflictsAdapter.parser.parse(config, parseDeps);
+
+// Transform stage: runs conflict detection + writes verdict bundles
+await sourceConflictsAdapter.transformer.transform(config, transformDeps);
+
+// Analyze stage: in-process, returns typed results (no file writing)
+const result = await sourceConflictsAdapter.analyzer!.analyze(config, {
+  logger,
+});
+```
+
+---
+
+## Result shape
+
+### `SourceConflictsAnalysisResult`
+
+```typescript
+type SourceConflictsAnalysisResult = {
+  /** One entry per processed conflict group. */
+  groupResults: ConflictGroupResult[];
+  /** Keys of groups that were skipped (non-MDX/MD or too few sources). */
+  skippedGroupKeys: string[];
+};
+```
+
+### `ConflictGroupResult`
+
+```typescript
+type ConflictGroupResult = {
+  group: ConflictGroup; // entityKind, relPath, artifacts[]
+  bundle: MdxConflictBundle; // source-agnostic per-anchor snapshot (serializable — store in DB)
+  baselineSourceKey: string; // frontmatter URI of the baseline source, e.g. "knapsack://patterns/button"
+  compareSourceKeys: string[]; // frontmatter URIs of compare sources (up to MAX_COMPARE_SOURCES)
+  verdicts: AnchorVerdictView[]; // per-anchor verdict derived from bundle for this baseline/compare
+};
+```
+
+`bundle` is a fully-serializable JSON snapshot — no functions, no circular refs. Storing it once and calling `computeVerdictsForBaselineCompare` with different baseline/compare args is the recommended pattern (see [Option A](#option-a--bundle-first-pattern)).
+
+### `ConflictItemRecord` (inside `MdxConflictBundle.items`)
+
+```typescript
+type ConflictItemRecord = {
+  fingerprint: string;
+  sourceType: SourceType; // filename-parsed, e.g. "KNAPSACK" — used internally for matching
+  sourceKey: string; // frontmatter URI, e.g. "knapsack://patterns/button" — use this for display and storage
+  frontmatterSchemaVersion: number;
+  frontmatter: Record<string, unknown>;
+};
+```
+
+### Verdicts
+
+| Value       | Meaning                                                               |
+| ----------- | --------------------------------------------------------------------- |
+| `ALL_SAME`  | All sources agree (or content was unified by a canonicalization rule) |
+| `DIFFERENT` | At least one source has different content for this anchor             |
+| `MISSING`   | At least one source does not contain this anchor                      |
+
+---
+
+## Option A — bundle-first pattern
+
+`MdxConflictBundle` is the stable stored artifact. `computeVerdictsForBaselineCompare` is a pure function that derives verdicts from any stored bundle with no I/O or re-parsing.
+
+### Recommended DB/GraphQL pattern
+
+1. **Store** the bundle when running the detection pipeline.
+2. **Load** the bundle from storage when serving a request.
+3. **Call** `computeVerdictsForBaselineCompare` with the caller-specified baseline/compare source URIs.
+
+```typescript
+import {
+  computeVerdictsForBaselineCompare,
+  getAvailableSourceKeysFromBundle,
+} from '@knapsack/source-conflicts-adapter';
+import type { MdxConflictBundle } from '@knapsack/source-conflicts-adapter';
+
+// Load stored bundle from DB (JSON column → parse → use directly, no re-detection)
+const bundle: MdxConflictBundle = JSON.parse(row.bundleJson);
+
+// Discover which source URIs are available without re-detecting
+const available = getAvailableSourceKeysFromBundle(bundle);
+// e.g. ["knapsack://patterns/button", "storybook://components/button"]
+
+// Derive verdicts for any baseline/compare combination — instant, no I/O
+const verdicts = computeVerdictsForBaselineCompare(
+  bundle,
+  'knapsack://patterns/button', // baseline URI
+  ['storybook://components/button'], // compare URIs
+);
+
+// Swap baseline without re-detecting — just call again
+const swappedVerdicts = computeVerdictsForBaselineCompare(
+  bundle,
+  'storybook://components/button',
+  ['knapsack://patterns/button'],
+);
+```
+
+### `getAvailableSourceKeysFromBundle`
+
+```typescript
+function getAvailableSourceKeysFromBundle(bundle: MdxConflictBundle): string[];
+```
+
+Returns the frontmatter source URI (`sourceKey`) for every item in the bundle. Any of these can be passed as `baselineSourceKey` to `computeVerdictsForBaselineCompare` without re-running detection. Sources in `bundle.excludedSourceKeys` (if any, when `MAX_COMPARE_SOURCES` is exceeded) are **not** in the bundle and cannot be used as baseline without a full re-detect.
+
+---
+
+## Comparison rules
+
+Sections are compared using a chain of canonicalization rules. The first rule that applies to all sections and produces a single hash bucket wins (result: `EXACT` match method). If no rule unifies, a fallback whitespace rule produces a `FALLBACK` result.
+
+| Rule                       | ID                   | What it does                                |
+| -------------------------- | -------------------- | ------------------------------------------- |
+| `ruleExact`                | `exact`              | Exact string equality                       |
+| `ruleWhitespace`           | `ws_v1`              | Collapse whitespace, normalize line endings |
+| `ruleTables`               | `table_v1`           | Parse and re-serialize Markdown tables      |
+| `ruleJsonFences`           | `json_fences_v1`     | Normalize JSON inside fenced code blocks    |
+| `makeRuleAst()`            | `ast_v1`             | Full MDX AST comparison (strips positions)  |
+| `makeRulePrettierFences()` | `prettier_fences_v1` | Format code fences with Prettier            |
+
+---
+
+## Supported file types
+
+Both `.mdx` and `.md` files are supported. Non-markdown files (e.g. `.json`, `.css`) are indexed but skipped during conflict detection.
+
+---
+
+## Source file layout
+
+```
+src/
+├── index.ts              # Adapter export + public API re-exports
+├── types.ts              # SourceConflictsConfig, ArtifactRef, ConflictGroup, VERDICT, Rule
+├── validator.ts          # validateConfig / validateFull
+├── parser.ts             # parse() — indexes entities, writes manifest
+├── transformer.ts        # transform() — runs detection, writes verdict bundles
+├── analyzer.ts           # analyze() — in-process detection, returns typed result
+├── detect.ts             # indexEntitiesDir / findConflictGroups (filesystem)
+├── parse.ts              # parseEntityKind / parseSourceType (filename parsing)
+├── multiSourceCompare.ts # compareAnchorMultiSource (rule engine)
+├── compare/
+│   └── preview.ts        # Preview/truncation helpers
+├── mdx/
+│   ├── mdxConflicts.ts   # detectMdxConflictBundle / computeVerdictsForBaselineCompare
+│   ├── mdxRules.ts       # Built-in canonicalization rules
+│   ├── tableMdx.ts       # Table parsing / canonicalization
+│   └── sharedProcessor.ts # Shared remark processor
+└── utils/
+    ├── canonicalCache.ts  # In-memory canonical result cache (sha256)
+    └── frontmatter.ts     # Frontmatter parsing helpers
+```
+
+---
+
+## Development
+
+```bash
+# Build
+pnpm run build
+
+# Watch
+pnpm run dev
+
+# Test
+pnpm run test
+
+# Lint
+pnpm run lint
+```

package/dist/analyzer.d.ts

@@ -0,0 +1,29 @@
+import type { Logger } from '@knapsack/adapter-core';
+import type { SourceConflictsConfig } from './types.js';
+import type { AnchorVerdictView, MdxConflictBundle } from './mdx/mdxConflicts.js';
+import type { ConflictGroup } from './types.js';
+export type ConflictGroupResult = {
+    group: ConflictGroup;
+    bundle: MdxConflictBundle;
+    /** Frontmatter sourceKey URI of the baseline source (e.g. "knapsack://patterns/button"). */
+    baselineSourceKey: string;
+    /** Frontmatter sourceKey URIs of the compare sources. */
+    compareSourceKeys: string[];
+    verdicts: AnchorVerdictView[];
+};
+export type SourceConflictsAnalysisResult = {
+    groupResults: ConflictGroupResult[];
+    /** Groups that were skipped (non-MDX or not enough sources). */
+    skippedGroupKeys: string[];
+};
+export declare function analyze(config: SourceConflictsConfig, deps: Pick<{
+    logger: Logger;
+}, 'logger'>): Promise<SourceConflictsAnalysisResult>;
+/**
+ * Returns the source keys present in a stored bundle.
+ * Any of these can be passed as `baselineSourceKey` to
+ * `computeVerdictsForBaselineCompare` without re-running detection.
+ * Sources in `bundle.excludedSourceKeys` are NOT available.
+ */
+export declare function getAvailableSourceKeysFromBundle(bundle: MdxConflictBundle): string[];
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAQxD,OAAO,KAAK,EACV,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,4FAA4F;IAC5F,iBAAiB,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B,CAAC;AAEF,wBAAsB,OAAO,CAC3B,MAAM,EAAE,qBAAqB,EAC7B,IAAI,EAAE,IAAI,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,QAAQ,CAAC,GACvC,OAAO,CAAC,6BAA6B,CAAC,CAoExC;AAED;;;;;GAKG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,iBAAiB,GACxB,MAAM,EAAE,CAEV"}

package/dist/analyzer.js

@@ -0,0 +1,61 @@
+import { indexEntitiesDir, findConflictGroups } from './detect.js';
+import { detectMdxConflictBundle, computeVerdictsForBaselineCompare, MAX_COMPARE_SOURCES, MIN_COMPARE_SOURCES, } from './mdx/mdxConflicts.js';
+export async function analyze(config, deps) {
+    const { logger } = deps;
+    const index = await indexEntitiesDir(config.entitiesRootAbs, logger);
+    const groups = findConflictGroups(index, logger);
+    const groupResults = [];
+    const skippedGroupKeys = [];
+    for (const group of groups) {
+        if (!group.relPath.endsWith('.mdx') && !group.relPath.endsWith('.md')) {
+            skippedGroupKeys.push(group.key);
+            continue;
+        }
+        const sources = [
+            ...new Set(group.artifacts.map((a) => a.sourceKey)),
+        ].sort();
+        if (sources.length < 1 + MIN_COMPARE_SOURCES) {
+            skippedGroupKeys.push(group.key);
+            continue;
+        }
+        const baselineSourceKey = sources[0];
+        const compareSourceKeys = sources.slice(1, 1 + MAX_COMPARE_SOURCES);
+        const bundle = await detectMdxConflictBundle({
+            groupKey: group.key,
+            artifacts: group.artifacts,
+            baselineSourceKey,
+            compareSourceKeys,
+            siteId: config.siteId,
+            userId: config.userId,
+            configId: config.configId,
+            logger,
+        });
+        if (!bundle) {
+            skippedGroupKeys.push(group.key);
+            continue;
+        }
+        // Map filename-parsed SourceType → frontmatter URI using bundle.items.
+        const getUri = (st) => bundle.items.find((i) => i.sourceType === st)?.sourceKey ?? st;
+        const baselineUri = getUri(baselineSourceKey);
+        const compareUris = compareSourceKeys.map(getUri);
+        const verdicts = computeVerdictsForBaselineCompare(bundle, baselineUri, compareUris);
+        groupResults.push({
+            group,
+            bundle,
+            baselineSourceKey: baselineUri,
+            compareSourceKeys: compareUris,
+            verdicts,
+        });
+    }
+    return { groupResults, skippedGroupKeys };
+}
+/**
+ * Returns the source keys present in a stored bundle.
+ * Any of these can be passed as `baselineSourceKey` to
+ * `computeVerdictsForBaselineCompare` without re-running detection.
+ * Sources in `bundle.excludedSourceKeys` are NOT available.
+ */
+export function getAvailableSourceKeysFromBundle(bundle) {
+    return bundle.items.map((item) => item.sourceKey);
+}
+//# sourceMappingURL=analyzer.js.map

package/dist/analyzer.js.map

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

package/dist/analyzer.vitest.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=analyzer.vitest.d.ts.map

package/dist/analyzer.vitest.d.ts.map

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

package/dist/analyzer.vitest.js

@@ -0,0 +1,60 @@
+import { describe, it, expect } from 'vitest';
+import { getAvailableSourceKeysFromBundle } from './analyzer.js';
+function makeBundle(items) {
+    return {
+        conflict: {
+            entityKey: 'component/button.react',
+            entityType: 'COMPONENT',
+            entityRelPath: 'button.react',
+            fingerprint: 'cf_v1_abc',
+            createdAt: '2025-01-01T00:00:00Z',
+            updatedAt: '2025-01-01T00:00:00Z',
+        },
+        items,
+        anchorDefinitions: [],
+    };
+}
+describe('getAvailableSourceKeysFromBundle', () => {
+    it('returns URI sourceKeys for all items in the bundle', () => {
+        const bundle = makeBundle([
+            {
+                fingerprint: 'fp1',
+                sourceType: 'KNAPSACK',
+                sourceKey: 'knapsack://patterns/button',
+                frontmatterSchemaVersion: 1,
+                frontmatter: {},
+            },
+            {
+                fingerprint: 'fp2',
+                sourceType: 'STORYBOOK',
+                sourceKey: 'storybook://components/button',
+                frontmatterSchemaVersion: 1,
+                frontmatter: {},
+            },
+        ]);
+        const keys = getAvailableSourceKeysFromBundle(bundle);
+        expect(keys).toEqual([
+            'knapsack://patterns/button',
+            'storybook://components/button',
+        ]);
+    });
+    it('returns an empty array for a bundle with no items', () => {
+        const bundle = makeBundle([]);
+        expect(getAvailableSourceKeysFromBundle(bundle)).toEqual([]);
+    });
+    it('returns a single URI for a bundle with one item', () => {
+        const bundle = makeBundle([
+            {
+                fingerprint: 'fp1',
+                sourceType: 'KNAPSACK',
+                sourceKey: 'knapsack://patterns/button',
+                frontmatterSchemaVersion: 1,
+                frontmatter: {},
+            },
+        ]);
+        expect(getAvailableSourceKeysFromBundle(bundle)).toEqual([
+            'knapsack://patterns/button',
+        ]);
+    });
+});
+//# sourceMappingURL=analyzer.vitest.js.map

package/dist/analyzer.vitest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.vitest.js","sourceRoot":"","sources":["../src/analyzer.vitest.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAE9C,OAAO,EAAE,gCAAgC,EAAE,MAAM,eAAe,CAAC;AAEjE,SAAS,UAAU,CAAC,KAAiC;IACnD,OAAO;QACL,QAAQ,EAAE;YACR,SAAS,EAAE,wBAAwB;YACnC,UAAU,EAAE,WAAW;YACvB,aAAa,EAAE,cAAc;YAC7B,WAAW,EAAE,WAAW;YACxB,SAAS,EAAE,sBAAsB;YACjC,SAAS,EAAE,sBAAsB;SAClC;QACD,KAAK;QACL,iBAAiB,EAAE,EAAE;KACtB,CAAC;AACJ,CAAC;AAED,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAChD,EAAE,CAAC,oDAAoD,EAAE,GAAG,EAAE;QAC5D,MAAM,MAAM,GAAG,UAAU,CAAC;YACxB;gBACE,WAAW,EAAE,KAAK;gBAClB,UAAU,EAAE,UAAU;gBACtB,SAAS,EAAE,4BAA4B;gBACvC,wBAAwB,EAAE,CAAC;gBAC3B,WAAW,EAAE,EAAE;aAChB;YACD;gBACE,WAAW,EAAE,KAAK;gBAClB,UAAU,EAAE,WAAW;gBACvB,SAAS,EAAE,+BAA+B;gBAC1C,wBAAwB,EAAE,CAAC;gBAC3B,WAAW,EAAE,EAAE;aAChB;SACF,CAAC,CAAC;QAEH,MAAM,IAAI,GAAG,gCAAgC,CAAC,MAAM,CAAC,CAAC;QACtD,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC;YACnB,4BAA4B;YAC5B,+BAA+B;SAChC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;QAC9B,MAAM,CAAC,gCAAgC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC/D,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iDAAiD,EAAE,GAAG,EAAE;QACzD,MAAM,MAAM,GAAG,UAAU,CAAC;YACxB;gBACE,WAAW,EAAE,KAAK;gBAClB,UAAU,EAAE,UAAU;gBACtB,SAAS,EAAE,4BAA4B;gBACvC,wBAAwB,EAAE,CAAC;gBAC3B,WAAW,EAAE,EAAE;aAChB;SACF,CAAC,CAAC;QACH,MAAM,CAAC,gCAAgC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;YACvD,4BAA4B;SAC7B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/compare/preview.d.ts

@@ -0,0 +1,28 @@
+import type { TableNode } from '../mdx/tableMdx.js';
+/** Default bounds for preview size; overridable via PreviewBounds. */
+export declare const DEFAULT_MAX_DEFINITION_TEXT: number;
+export declare const DEFAULT_MAX_DEFINITIONS = 10;
+export declare const DEFAULT_MAX_SOURCES_PER_DEFINITION = 10;
+/** Truncates string to max length and appends a truncation marker. */
+export declare function truncate(s: string, max?: number): string;
+/** Builds bounded preview.definitions from groups (capped counts); includes table value when present. */
+export declare function stablePreviewBounded(args: {
+    groups: Array<{
+        hash: string;
+        sources: string[];
+        table?: TableNode;
+    }>;
+    maxDefinitions?: number;
+    maxSourcesPerDefinition?: number;
+}): {
+    definitionCount: number;
+    definitions: Array<{
+        hash: string;
+        sources: string[];
+        value?: {
+            kind: 'TABLE';
+            table: TableNode;
+        };
+    }>;
+};
+//# sourceMappingURL=preview.d.ts.map

package/dist/compare/preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/compare/preview.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,sEAAsE;AACtE,eAAO,MAAM,2BAA2B,QAAW,CAAC;AACpD,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAC1C,eAAO,MAAM,kCAAkC,KAAK,CAAC;AAErD,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAGtD;AAED,yGAAyG;AACzG,wBAAgB,oBAAoB,CAAC,IAAI,EAAE;IACzC,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG;IACF,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,KAAK,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,CAAC;QAClB,KAAK,CAAC,EAAE;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,KAAK,EAAE,SAAS,CAAA;SAAE,CAAC;KAC7C,CAAC,CAAC;CACJ,CAiBA"}

package/dist/compare/preview.js

@@ -0,0 +1,27 @@
+/** Default bounds for preview size; overridable via PreviewBounds. */
+export const DEFAULT_MAX_DEFINITION_TEXT = 8 * 1024; // 8KB
+export const DEFAULT_MAX_DEFINITIONS = 10;
+export const DEFAULT_MAX_SOURCES_PER_DEFINITION = 10;
+/** Truncates string to max length and appends a truncation marker. */
+export function truncate(s, max = 2000) {
+    if (s.length <= max)
+        return s;
+    return `${s.slice(0, max)}\n…(truncated)…`;
+}
+/** Builds bounded preview.definitions from groups (capped counts); includes table value when present. */
+export function stablePreviewBounded(args) {
+    const maxDefinitions = args.maxDefinitions ?? DEFAULT_MAX_DEFINITIONS;
+    const maxSources = args.maxSourcesPerDefinition ?? DEFAULT_MAX_SOURCES_PER_DEFINITION;
+    const definitions = args.groups.slice(0, maxDefinitions).map((g) => ({
+        hash: g.hash,
+        sources: g.sources.slice(0, maxSources),
+        ...(g.table != null
+            ? { value: { kind: 'TABLE', table: g.table } }
+            : {}),
+    }));
+    return {
+        definitionCount: args.groups.length,
+        definitions,
+    };
+}
+//# sourceMappingURL=preview.js.map

package/dist/compare/preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../src/compare/preview.ts"],"names":[],"mappings":"AAEA,sEAAsE;AACtE,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM;AAC3D,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAC;AAC1C,MAAM,CAAC,MAAM,kCAAkC,GAAG,EAAE,CAAC;AAErD,sEAAsE;AACtE,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,GAAG,GAAG,IAAI;IAC5C,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC;AAC7C,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,oBAAoB,CAAC,IAIpC;IAQC,MAAM,cAAc,GAAG,IAAI,CAAC,cAAc,IAAI,uBAAuB,CAAC;IACtE,MAAM,UAAU,GACd,IAAI,CAAC,uBAAuB,IAAI,kCAAkC,CAAC;IAErE,MAAM,WAAW,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnE,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC;QACvC,GAAG,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI;YACjB,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAgB,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE;YACvD,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC,CAAC;IAEJ,OAAO;QACL,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;QACnC,WAAW;KACZ,CAAC;AACJ,CAAC"}

package/dist/compare/preview.vitest.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=preview.vitest.d.ts.map

package/dist/compare/preview.vitest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.vitest.d.ts","sourceRoot":"","sources":["../../src/compare/preview.vitest.ts"],"names":[],"mappings":""}

package/dist/compare/preview.vitest.js

@@ -0,0 +1,67 @@
+import { describe, it, expect } from 'vitest';
+import { truncate, stablePreviewBounded, DEFAULT_MAX_DEFINITIONS, } from './preview.js';
+describe('truncate', () => {
+    it('returns string unchanged when within max', () => {
+        const s = 'short';
+        expect(truncate(s)).toBe(s);
+        expect(truncate(s, 10)).toBe(s);
+    });
+    it('truncates and appends marker when over max', () => {
+        const s = 'a'.repeat(100);
+        const out = truncate(s, 20);
+        expect(out).toHaveLength(20 + '\n…(truncated)…'.length);
+        expect(out.startsWith('a'.repeat(20))).toBe(true);
+        expect(out.endsWith('…(truncated)…')).toBe(true);
+    });
+    it('uses default max 2000 when not provided', () => {
+        const s = 'x'.repeat(3000);
+        const out = truncate(s);
+        expect(out.slice(0, 2000)).toBe('x'.repeat(2000));
+        expect(out.endsWith('…(truncated)…')).toBe(true);
+    });
+});
+describe('stablePreviewBounded', () => {
+    const minimalTable = {
+        columns: ['a'],
+        keyColumn: 'a',
+        rows: [{ a: '1' }],
+    };
+    it('slices definitions by maxDefinitions', () => {
+        const groups = [
+            { hash: 'h1', sources: ['s1'] },
+            { hash: 'h2', sources: ['s2'] },
+            { hash: 'h3', sources: ['s3'] },
+        ];
+        const out = stablePreviewBounded({ groups, maxDefinitions: 2 });
+        expect(out.definitionCount).toBe(3);
+        expect(out.definitions).toHaveLength(2);
+        expect(out.definitions[0].hash).toBe('h1');
+        expect(out.definitions[1].hash).toBe('h2');
+    });
+    it('slices sources per definition by maxSourcesPerDefinition', () => {
+        const groups = [{ hash: 'h1', sources: ['s1', 's2', 's3', 's4', 's5'] }];
+        const out = stablePreviewBounded({
+            groups,
+            maxSourcesPerDefinition: 2,
+        });
+        expect(out.definitions[0].sources).toEqual(['s1', 's2']);
+    });
+    it('includes table value when present', () => {
+        const groups = [{ hash: 'h1', sources: ['s1'], table: minimalTable }];
+        const out = stablePreviewBounded({ groups });
+        expect(out.definitions[0].value).toEqual({
+            kind: 'TABLE',
+            table: minimalTable,
+        });
+    });
+    it('uses default max definitions and sources when omitted', () => {
+        const groups = Array.from({ length: 20 }, (_, i) => ({
+            hash: `h${i}`,
+            sources: ['s1'],
+        }));
+        const out = stablePreviewBounded({ groups });
+        expect(out.definitions).toHaveLength(DEFAULT_MAX_DEFINITIONS);
+        expect(out.definitionCount).toBe(20);
+    });
+});
+//# sourceMappingURL=preview.vitest.js.map

package/dist/compare/preview.vitest.js.map

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

package/dist/detect.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from '@knapsack/adapter-core';
+import type { ArtifactRef, ConflictGroup } from './types.js';
+export type { ArtifactRef, ConflictGroup } from './types.js';
+/**
+ * Index filesystem artifacts by (entityKind + canonical relPath).
+ *
+ * Expected layout: entities/<entityKind>/<base>.<sourceType>-<hash>.<ext>
+ * Same entity = same entityKind + same base name (e.g. button.react.mdx or button.react.md);
+ * sourceType and hash are read from the filename.
+ */
+export declare function indexEntitiesDir(entitiesRootAbs: string, logger: Logger): Promise<Map<string, ArtifactRef[]>>;
+export declare function findConflictGroups(index: Map<string, ArtifactRef[]>, logger: Logger): ConflictGroup[];
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE7D,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiD7D;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAoCrC;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,EACjC,MAAM,EAAE,MAAM,GACb,aAAa,EAAE,CAmBjB"}