@pie-element/cli 0.1.1 → 0.1.2-next.0

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC","sourcesContent":["export { run } from '@oclif/core';\n"]}

package/dist/lib/docs/contract-validator.d.ts

@@ -0,0 +1,12 @@
+import type { PieDocsContract } from './types.js';
+export interface ContractValidationIssue {
+    elementName: string;
+    message: string;
+}
+export interface ContractValidationResult {
+    issues: ContractValidationIssue[];
+}
+export declare const validateContracts: (contracts: Array<{
+    packageDir: string;
+    contract: PieDocsContract;
+}>) => ContractValidationResult;

package/dist/lib/docs/contract-validator.js

@@ -0,0 +1,38 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const validateContracts = (contracts) => {
+    const issues = [];
+    const seenElementNames = new Set();
+    for (const entry of contracts) {
+        const { contract, packageDir } = entry;
+        if (seenElementNames.has(contract.elementName)) {
+            issues.push({
+                elementName: contract.elementName,
+                message: `Duplicate elementName detected: ${contract.elementName}`,
+            });
+        }
+        else {
+            seenElementNames.add(contract.elementName);
+        }
+        if (!contract.views.length) {
+            issues.push({
+                elementName: contract.elementName,
+                message: 'No views declared in contract',
+            });
+            continue;
+        }
+        for (const view of contract.views) {
+            for (const pointer of [view.pie, view.config]) {
+                const filePath = join(packageDir, pointer.file);
+                if (!existsSync(filePath)) {
+                    issues.push({
+                        elementName: contract.elementName,
+                        message: `Missing source file for view "${view.view}": ${pointer.file}`,
+                    });
+                }
+            }
+        }
+    }
+    return { issues };
+};
+//# sourceMappingURL=contract-validator.js.map

package/dist/lib/docs/contract-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-validator.js","sourceRoot":"","sources":["../../../src/lib/docs/contract-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAYjC,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAC/B,SAAmE,EACzC,EAAE;IAC5B,MAAM,MAAM,GAA8B,EAAE,CAAC;IAC7C,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAU,CAAC;IAE3C,KAAK,MAAM,KAAK,IAAI,SAAS,EAAE,CAAC;QAC9B,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;QACvC,IAAI,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC;gBACV,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,OAAO,EAAE,mCAAmC,QAAQ,CAAC,WAAW,EAAE;aACnE,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC7C,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAC3B,MAAM,CAAC,IAAI,CAAC;gBACV,WAAW,EAAE,QAAQ,CAAC,WAAW;gBACjC,OAAO,EAAE,+BAA+B;aACzC,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAClC,KAAK,MAAM,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC9C,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;gBAChD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC1B,MAAM,CAAC,IAAI,CAAC;wBACV,WAAW,EAAE,QAAQ,CAAC,WAAW;wBACjC,OAAO,EAAE,iCAAiC,IAAI,CAAC,IAAI,MAAM,OAAO,CAAC,IAAI,EAAE;qBACxE,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,CAAC;AACpB,CAAC,CAAC","sourcesContent":["import { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nimport type { PieDocsContract } from './types.js';\n\nexport interface ContractValidationIssue {\n  elementName: string;\n  message: string;\n}\n\nexport interface ContractValidationResult {\n  issues: ContractValidationIssue[];\n}\n\nexport const validateContracts = (\n  contracts: Array<{ packageDir: string; contract: PieDocsContract }>\n): ContractValidationResult => {\n  const issues: ContractValidationIssue[] = [];\n  const seenElementNames = new Set<string>();\n\n  for (const entry of contracts) {\n    const { contract, packageDir } = entry;\n    if (seenElementNames.has(contract.elementName)) {\n      issues.push({\n        elementName: contract.elementName,\n        message: `Duplicate elementName detected: ${contract.elementName}`,\n      });\n    } else {\n      seenElementNames.add(contract.elementName);\n    }\n\n    if (!contract.views.length) {\n      issues.push({\n        elementName: contract.elementName,\n        message: 'No views declared in contract',\n      });\n      continue;\n    }\n\n    for (const view of contract.views) {\n      for (const pointer of [view.pie, view.config]) {\n        const filePath = join(packageDir, pointer.file);\n        if (!existsSync(filePath)) {\n          issues.push({\n            elementName: contract.elementName,\n            message: `Missing source file for view \"${view.view}\": ${pointer.file}`,\n          });\n        }\n      }\n    }\n  }\n\n  return { issues };\n};\n"]}

package/dist/lib/docs/contracts.d.ts

@@ -0,0 +1,11 @@
+import type { ElementPackageInfo, PieDocsContract } from './types.js';
+export declare const parseContract: (raw: unknown, location: string) => PieDocsContract;
+export declare const loadContract: (packageDir: string) => Promise<PieDocsContract | null>;
+export declare const writeContract: (packageDir: string, contract: PieDocsContract) => Promise<void>;
+export declare const seedContractForElement: (element: ElementPackageInfo, rootDir: string, options?: {
+    refresh?: boolean;
+}) => Promise<{
+    wrote: boolean;
+    contractPath: string;
+    contract: PieDocsContract;
+}>;

package/dist/lib/docs/contracts.js

@@ -0,0 +1,241 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { CONTRACT_FILENAME, inferViewsFromPackageExports } from './discovery.js';
+const MODES = ['gather', 'view', 'evaluate'];
+const isObject = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+const isSourcePointer = (value) => isObject(value) &&
+    typeof value.file === 'string' &&
+    (value.exportName === undefined || typeof value.exportName === 'string') &&
+    (value.path === undefined || typeof value.path === 'string');
+const isPrimitiveEnumValue = (value) => value === null || ['string', 'number', 'boolean'].includes(typeof value);
+const isPropertyMetadata = (value) => {
+    if (!isObject(value)) {
+        return false;
+    }
+    const allowed = [
+        'title',
+        'description',
+        'notes',
+        'type',
+        'required',
+        'enum',
+        'minimum',
+        'maximum',
+        'minLength',
+        'maxLength',
+        'pattern',
+        'itemType',
+        'examples',
+    ];
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key)) {
+            return false;
+        }
+    }
+    if (value.title !== undefined && typeof value.title !== 'string')
+        return false;
+    if (value.description !== undefined && typeof value.description !== 'string')
+        return false;
+    if (value.notes !== undefined && typeof value.notes !== 'string')
+        return false;
+    if (value.type !== undefined && typeof value.type !== 'string')
+        return false;
+    if (value.required !== undefined && typeof value.required !== 'boolean')
+        return false;
+    if (value.enum !== undefined) {
+        if (!Array.isArray(value.enum) || value.enum.some((entry) => !isPrimitiveEnumValue(entry))) {
+            return false;
+        }
+    }
+    for (const key of ['minimum', 'maximum', 'minLength', 'maxLength']) {
+        if (value[key] !== undefined && typeof value[key] !== 'number')
+            return false;
+    }
+    if (value.pattern !== undefined && typeof value.pattern !== 'string')
+        return false;
+    if (value.itemType !== undefined && typeof value.itemType !== 'string')
+        return false;
+    if (value.examples !== undefined && !Array.isArray(value.examples))
+        return false;
+    return true;
+};
+const normalizeMetadataMap = (map) => {
+    if (!map) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(map)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([path, metadata]) => [path, { ...metadata }]));
+};
+const isViewMetadata = (value) => {
+    if (!isObject(value)) {
+        return false;
+    }
+    for (const key of Object.keys(value)) {
+        if (!['pie', 'config'].includes(key)) {
+            return false;
+        }
+        const map = value[key];
+        if (map === undefined)
+            continue;
+        if (!isObject(map))
+            return false;
+        for (const entry of Object.values(map)) {
+            if (!isPropertyMetadata(entry))
+                return false;
+        }
+    }
+    return true;
+};
+const normalizePointer = (pointer) => ({
+    file: pointer.file,
+    ...(pointer.exportName ? { exportName: pointer.exportName } : {}),
+    ...(pointer.path ? { path: pointer.path } : {}),
+});
+const normalizeContract = (contract) => ({
+    elementName: contract.elementName,
+    packageName: contract.packageName,
+    framework: contract.framework,
+    ...(contract.summary ? { summary: contract.summary } : {}),
+    supportedModes: contract.supportedModes?.length ? [...contract.supportedModes] : MODES,
+    views: [...contract.views]
+        .sort((a, b) => a.view.localeCompare(b.view))
+        .map((view) => ({
+        view: view.view,
+        pie: normalizePointer(view.pie),
+        config: normalizePointer(view.config),
+        ...(view.description ? { description: view.description } : {}),
+        ...(view.metadata
+            ? {
+                metadata: {
+                    ...(view.metadata.pie ? { pie: normalizeMetadataMap(view.metadata.pie) } : {}),
+                    ...(view.metadata.config
+                        ? { config: normalizeMetadataMap(view.metadata.config) }
+                        : {}),
+                },
+            }
+            : {}),
+    })),
+});
+const inferPiePointer = (packageDir) => {
+    const candidates = [
+        { file: 'src/author/defaultConfiguration.ts', path: 'model' },
+        { file: 'src/author/defaults.ts', path: 'model' },
+        { file: 'src/controller/defaults.ts' },
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(join(packageDir, candidate.file))) {
+            return candidate;
+        }
+    }
+    return { file: 'src/controller/defaults.ts' };
+};
+const inferConfigPointer = (packageDir) => {
+    const candidates = [
+        { file: 'src/author/defaultConfiguration.ts', path: 'configuration' },
+        { file: 'src/author/defaults.ts', path: 'configuration' },
+        { file: 'src/controller/defaults.ts' },
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(join(packageDir, candidate.file))) {
+            return candidate;
+        }
+    }
+    return { file: 'src/controller/defaults.ts', path: 'configuration' };
+};
+export const parseContract = (raw, location) => {
+    if (!isObject(raw)) {
+        throw new Error(`Invalid docs contract in ${location}: expected object`);
+    }
+    if (typeof raw.elementName !== 'string' || !raw.elementName.trim()) {
+        throw new Error(`Invalid docs contract in ${location}: elementName is required`);
+    }
+    if (typeof raw.packageName !== 'string' || !raw.packageName.startsWith('@pie-element/')) {
+        throw new Error(`Invalid docs contract in ${location}: packageName is invalid`);
+    }
+    if (raw.framework !== 'react' && raw.framework !== 'svelte') {
+        throw new Error(`Invalid docs contract in ${location}: framework must be react|svelte`);
+    }
+    if (!Array.isArray(raw.views) || raw.views.length === 0) {
+        throw new Error(`Invalid docs contract in ${location}: at least one view is required`);
+    }
+    const views = raw.views.map((view, index) => {
+        if (!isObject(view)) {
+            throw new Error(`Invalid docs contract in ${location}: views[${index}] must be an object`);
+        }
+        if (typeof view.view !== 'string' || !view.view.trim()) {
+            throw new Error(`Invalid docs contract in ${location}: views[${index}].view is required`);
+        }
+        if (!isSourcePointer(view.pie)) {
+            throw new Error(`Invalid docs contract in ${location}: views[${index}].pie is invalid`);
+        }
+        if (!isSourcePointer(view.config)) {
+            throw new Error(`Invalid docs contract in ${location}: views[${index}].config is invalid`);
+        }
+        if (view.metadata !== undefined && !isViewMetadata(view.metadata)) {
+            throw new Error(`Invalid docs contract in ${location}: views[${index}].metadata is invalid`);
+        }
+        return {
+            view: view.view,
+            pie: view.pie,
+            config: view.config,
+            ...(typeof view.description === 'string' ? { description: view.description } : {}),
+            ...(view.metadata ? { metadata: view.metadata } : {}),
+        };
+    });
+    const supportedModes = Array.isArray(raw.supportedModes)
+        ? raw.supportedModes.filter((mode) => typeof mode === 'string')
+        : undefined;
+    return normalizeContract({
+        elementName: raw.elementName,
+        packageName: raw.packageName,
+        framework: raw.framework,
+        summary: typeof raw.summary === 'string' ? raw.summary : undefined,
+        supportedModes: supportedModes?.length ? supportedModes : MODES,
+        views,
+    });
+};
+export const loadContract = async (packageDir) => {
+    const contractPath = join(packageDir, CONTRACT_FILENAME);
+    if (!existsSync(contractPath)) {
+        return null;
+    }
+    const raw = JSON.parse(await readFile(contractPath, 'utf-8'));
+    return parseContract(raw, contractPath);
+};
+export const writeContract = async (packageDir, contract) => {
+    const contractPath = join(packageDir, CONTRACT_FILENAME);
+    const normalized = normalizeContract(contract);
+    await mkdir(packageDir, { recursive: true });
+    await writeFile(contractPath, `${JSON.stringify(normalized, null, 2)}\n`, 'utf-8');
+};
+export const seedContractForElement = async (element, rootDir, options) => {
+    const contractPath = join(element.packageDir, CONTRACT_FILENAME);
+    const existing = await loadContract(element.packageDir);
+    if (existing && !options?.refresh) {
+        return { wrote: false, contractPath, contract: existing };
+    }
+    const piePointer = inferPiePointer(element.packageDir);
+    const configPointer = inferConfigPointer(element.packageDir);
+    const views = inferViewsFromPackageExports(element.exportsMap).map((view) => ({
+        view,
+        pie: piePointer,
+        config: configPointer,
+    }));
+    const contract = normalizeContract({
+        elementName: element.elementName,
+        packageName: element.packageName,
+        framework: element.framework,
+        summary: existing?.summary || element.packageDescription,
+        supportedModes: existing?.supportedModes?.length ? existing.supportedModes : MODES,
+        views,
+    });
+    await writeContract(element.packageDir, contract);
+    return {
+        wrote: true,
+        contractPath: relative(rootDir, contractPath),
+        contract,
+    };
+};
+//# sourceMappingURL=contracts.js.map

package/dist/lib/docs/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../../src/lib/docs/contracts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AASjF,MAAM,KAAK,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,CAAC;AAE7C,MAAM,QAAQ,GAAG,CAAC,KAAc,EAAoC,EAAE,CACpE,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAEhE,MAAM,eAAe,GAAG,CAAC,KAAc,EAAiC,EAAE,CACxE,QAAQ,CAAC,KAAK,CAAC;IACf,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;IAC9B,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAC;IACxE,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;AAE/D,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAA6C,EAAE,CACzF,KAAK,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,KAAK,CAAC,CAAC;AAE3E,MAAM,kBAAkB,GAAG,CAAC,KAAc,EAAoC,EAAE;IAC9E,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,OAAO,GAAG;QACd,OAAO;QACP,aAAa;QACb,OAAO;QACP,MAAM;QACN,UAAU;QACV,MAAM;QACN,SAAS;QACT,SAAS;QACT,WAAW;QACX,WAAW;QACX,SAAS;QACT,UAAU;QACV,UAAU;KACX,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC/E,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3F,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC/E,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC7E,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtF,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;YAC3F,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAU,EAAE,CAAC;QAC5E,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;IAC/E,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACnF,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACrF,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACjF,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,oBAAoB,GAAG,CAC3B,GAA6C,EACQ,EAAE;IACvD,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;SAChB,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC,CACtD,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,cAAc,GAAG,CAAC,KAAc,EAAgC,EAAE;IACtE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACrC,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,GAAG,KAAK,SAAS;YAAE,SAAS;QAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACjC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,MAAM,gBAAgB,GAAG,CAAC,OAA6B,EAAwB,EAAE,CAAC,CAAC;IACjF,IAAI,EAAE,OAAO,CAAC,IAAI;IAClB,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;CAChD,CAAC,CAAC;AAEH,MAAM,iBAAiB,GAAG,CAAC,QAAyB,EAAmB,EAAE,CAAC,CAAC;IACzE,WAAW,EAAE,QAAQ,CAAC,WAAW;IACjC,WAAW,EAAE,QAAQ,CAAC,WAAW;IACjC,SAAS,EAAE,QAAQ,CAAC,SAAS;IAC7B,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,cAAc,EAAE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,KAAK;IACtF,KAAK,EAAE,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC;SACvB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACd,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,EAAE,gBAAgB,CAAC,IAAI,CAAC,GAAG,CAAC;QAC/B,MAAM,EAAE,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC;QACrC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,IAAI,CAAC,QAAQ;YACf,CAAC,CAAC;gBACE,QAAQ,EAAE;oBACR,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC9E,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM;wBACtB,CAAC,CAAC,EAAE,MAAM,EAAE,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE;wBACxD,CAAC,CAAC,EAAE,CAAC;iBACR;aACF;YACH,CAAC,CAAC,EAAE,CAAC;KACR,CAAC,CAAC;CACN,CAAC,CAAC;AAEH,MAAM,eAAe,GAAG,CAAC,UAAkB,EAAwB,EAAE;IACnE,MAAM,UAAU,GAA2B;QACzC,EAAE,IAAI,EAAE,oCAAoC,EAAE,IAAI,EAAE,OAAO,EAAE;QAC7D,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,OAAO,EAAE;QACjD,EAAE,IAAI,EAAE,4BAA4B,EAAE;KACvC,CAAC;IAEF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACjD,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,4BAA4B,EAAE,CAAC;AAChD,CAAC,CAAC;AAEF,MAAM,kBAAkB,GAAG,CAAC,UAAkB,EAAwB,EAAE;IACtE,MAAM,UAAU,GAA2B;QACzC,EAAE,IAAI,EAAE,oCAAoC,EAAE,IAAI,EAAE,eAAe,EAAE;QACrE,EAAE,IAAI,EAAE,wBAAwB,EAAE,IAAI,EAAE,eAAe,EAAE;QACzD,EAAE,IAAI,EAAE,4BAA4B,EAAE;KACvC,CAAC;IAEF,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,UAAU,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;YACjD,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,4BAA4B,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;AACvE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,GAAY,EAAE,QAAgB,EAAmB,EAAE;IAC/E,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,mBAAmB,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,2BAA2B,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACxF,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,0BAA0B,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,GAAG,CAAC,SAAS,KAAK,OAAO,IAAI,GAAG,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,kCAAkC,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,iCAAiC,CAAC,CAAC;IACzF,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC1C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,WAAW,KAAK,qBAAqB,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,WAAW,KAAK,oBAAoB,CAAC,CAAC;QAC5F,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,WAAW,KAAK,kBAAkB,CAAC,CAAC;QAC1F,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,WAAW,KAAK,qBAAqB,CAAC,CAAC;QAC7F,CAAC;QACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CAAC,4BAA4B,QAAQ,WAAW,KAAK,uBAAuB,CAAC,CAAC;QAC/F,CAAC;QAED,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,CAAC,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;QACtD,CAAC,CAAC,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC;QAC/E,CAAC,CAAC,SAAS,CAAC;IAEd,OAAO,iBAAiB,CAAC;QACvB,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,OAAO,EAAE,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QAClE,cAAc,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK;QAC/D,KAAK;KACN,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAAE,UAAkB,EAAmC,EAAE;IACxF,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IACzD,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAY,CAAC;IACzE,OAAO,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;AAC1C,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG,KAAK,EAChC,UAAkB,EAClB,QAAyB,EACV,EAAE;IACjB,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IACzD,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC/C,MAAM,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,SAAS,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACrF,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,EACzC,OAA2B,EAC3B,OAAe,EACf,OAA+B,EAC+C,EAAE;IAChF,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;IACjE,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACxD,IAAI,QAAQ,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,CAAC;QAClC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,UAAU,GAAG,eAAe,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IACvD,MAAM,aAAa,GAAG,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,4BAA4B,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC5E,IAAI;QACJ,GAAG,EAAE,UAAU;QACf,MAAM,EAAE,aAAa;KACtB,CAAC,CAAC,CAAC;IAEJ,MAAM,QAAQ,GAAoB,iBAAiB,CAAC;QAClD,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EAAE,QAAQ,EAAE,OAAO,IAAI,OAAO,CAAC,kBAAkB;QACxD,cAAc,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,KAAK;QAClF,KAAK;KACN,CAAC,CAAC;IAEH,MAAM,aAAa,CAAC,OAAO,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAElD,OAAO;QACL,KAAK,EAAE,IAAI;QACX,YAAY,EAAE,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;QAC7C,QAAQ;KACT,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { existsSync } from 'node:fs';\nimport { mkdir, readFile, writeFile } from 'node:fs/promises';\nimport { join, relative } from 'node:path';\nimport { CONTRACT_FILENAME, inferViewsFromPackageExports } from './discovery.js';\nimport type {\n  ElementPackageInfo,\n  PieDocsContract,\n  PieDocsPropertyMetadata,\n  PieDocsSourcePointer,\n  PieDocsViewMetadata,\n} from './types.js';\n\nconst MODES = ['gather', 'view', 'evaluate'];\n\nconst isObject = (value: unknown): value is Record<string, unknown> =>\n  !!value && typeof value === 'object' && !Array.isArray(value);\n\nconst isSourcePointer = (value: unknown): value is PieDocsSourcePointer =>\n  isObject(value) &&\n  typeof value.file === 'string' &&\n  (value.exportName === undefined || typeof value.exportName === 'string') &&\n  (value.path === undefined || typeof value.path === 'string');\n\nconst isPrimitiveEnumValue = (value: unknown): value is string | number | boolean | null =>\n  value === null || ['string', 'number', 'boolean'].includes(typeof value);\n\nconst isPropertyMetadata = (value: unknown): value is PieDocsPropertyMetadata => {\n  if (!isObject(value)) {\n    return false;\n  }\n  const allowed = [\n    'title',\n    'description',\n    'notes',\n    'type',\n    'required',\n    'enum',\n    'minimum',\n    'maximum',\n    'minLength',\n    'maxLength',\n    'pattern',\n    'itemType',\n    'examples',\n  ];\n  for (const key of Object.keys(value)) {\n    if (!allowed.includes(key)) {\n      return false;\n    }\n  }\n  if (value.title !== undefined && typeof value.title !== 'string') return false;\n  if (value.description !== undefined && typeof value.description !== 'string') return false;\n  if (value.notes !== undefined && typeof value.notes !== 'string') return false;\n  if (value.type !== undefined && typeof value.type !== 'string') return false;\n  if (value.required !== undefined && typeof value.required !== 'boolean') return false;\n  if (value.enum !== undefined) {\n    if (!Array.isArray(value.enum) || value.enum.some((entry) => !isPrimitiveEnumValue(entry))) {\n      return false;\n    }\n  }\n  for (const key of ['minimum', 'maximum', 'minLength', 'maxLength'] as const) {\n    if (value[key] !== undefined && typeof value[key] !== 'number') return false;\n  }\n  if (value.pattern !== undefined && typeof value.pattern !== 'string') return false;\n  if (value.itemType !== undefined && typeof value.itemType !== 'string') return false;\n  if (value.examples !== undefined && !Array.isArray(value.examples)) return false;\n  return true;\n};\n\nconst normalizeMetadataMap = (\n  map?: Record<string, PieDocsPropertyMetadata>\n): Record<string, PieDocsPropertyMetadata> | undefined => {\n  if (!map) {\n    return undefined;\n  }\n  return Object.fromEntries(\n    Object.entries(map)\n      .sort(([a], [b]) => a.localeCompare(b))\n      .map(([path, metadata]) => [path, { ...metadata }])\n  );\n};\n\nconst isViewMetadata = (value: unknown): value is PieDocsViewMetadata => {\n  if (!isObject(value)) {\n    return false;\n  }\n  for (const key of Object.keys(value)) {\n    if (!['pie', 'config'].includes(key)) {\n      return false;\n    }\n    const map = value[key];\n    if (map === undefined) continue;\n    if (!isObject(map)) return false;\n    for (const entry of Object.values(map)) {\n      if (!isPropertyMetadata(entry)) return false;\n    }\n  }\n  return true;\n};\n\nconst normalizePointer = (pointer: PieDocsSourcePointer): PieDocsSourcePointer => ({\n  file: pointer.file,\n  ...(pointer.exportName ? { exportName: pointer.exportName } : {}),\n  ...(pointer.path ? { path: pointer.path } : {}),\n});\n\nconst normalizeContract = (contract: PieDocsContract): PieDocsContract => ({\n  elementName: contract.elementName,\n  packageName: contract.packageName,\n  framework: contract.framework,\n  ...(contract.summary ? { summary: contract.summary } : {}),\n  supportedModes: contract.supportedModes?.length ? [...contract.supportedModes] : MODES,\n  views: [...contract.views]\n    .sort((a, b) => a.view.localeCompare(b.view))\n    .map((view) => ({\n      view: view.view,\n      pie: normalizePointer(view.pie),\n      config: normalizePointer(view.config),\n      ...(view.description ? { description: view.description } : {}),\n      ...(view.metadata\n        ? {\n            metadata: {\n              ...(view.metadata.pie ? { pie: normalizeMetadataMap(view.metadata.pie) } : {}),\n              ...(view.metadata.config\n                ? { config: normalizeMetadataMap(view.metadata.config) }\n                : {}),\n            },\n          }\n        : {}),\n    })),\n});\n\nconst inferPiePointer = (packageDir: string): PieDocsSourcePointer => {\n  const candidates: PieDocsSourcePointer[] = [\n    { file: 'src/author/defaultConfiguration.ts', path: 'model' },\n    { file: 'src/author/defaults.ts', path: 'model' },\n    { file: 'src/controller/defaults.ts' },\n  ];\n\n  for (const candidate of candidates) {\n    if (existsSync(join(packageDir, candidate.file))) {\n      return candidate;\n    }\n  }\n\n  return { file: 'src/controller/defaults.ts' };\n};\n\nconst inferConfigPointer = (packageDir: string): PieDocsSourcePointer => {\n  const candidates: PieDocsSourcePointer[] = [\n    { file: 'src/author/defaultConfiguration.ts', path: 'configuration' },\n    { file: 'src/author/defaults.ts', path: 'configuration' },\n    { file: 'src/controller/defaults.ts' },\n  ];\n\n  for (const candidate of candidates) {\n    if (existsSync(join(packageDir, candidate.file))) {\n      return candidate;\n    }\n  }\n\n  return { file: 'src/controller/defaults.ts', path: 'configuration' };\n};\n\nexport const parseContract = (raw: unknown, location: string): PieDocsContract => {\n  if (!isObject(raw)) {\n    throw new Error(`Invalid docs contract in ${location}: expected object`);\n  }\n  if (typeof raw.elementName !== 'string' || !raw.elementName.trim()) {\n    throw new Error(`Invalid docs contract in ${location}: elementName is required`);\n  }\n  if (typeof raw.packageName !== 'string' || !raw.packageName.startsWith('@pie-element/')) {\n    throw new Error(`Invalid docs contract in ${location}: packageName is invalid`);\n  }\n  if (raw.framework !== 'react' && raw.framework !== 'svelte') {\n    throw new Error(`Invalid docs contract in ${location}: framework must be react|svelte`);\n  }\n  if (!Array.isArray(raw.views) || raw.views.length === 0) {\n    throw new Error(`Invalid docs contract in ${location}: at least one view is required`);\n  }\n\n  const views = raw.views.map((view, index) => {\n    if (!isObject(view)) {\n      throw new Error(`Invalid docs contract in ${location}: views[${index}] must be an object`);\n    }\n    if (typeof view.view !== 'string' || !view.view.trim()) {\n      throw new Error(`Invalid docs contract in ${location}: views[${index}].view is required`);\n    }\n    if (!isSourcePointer(view.pie)) {\n      throw new Error(`Invalid docs contract in ${location}: views[${index}].pie is invalid`);\n    }\n    if (!isSourcePointer(view.config)) {\n      throw new Error(`Invalid docs contract in ${location}: views[${index}].config is invalid`);\n    }\n    if (view.metadata !== undefined && !isViewMetadata(view.metadata)) {\n      throw new Error(`Invalid docs contract in ${location}: views[${index}].metadata is invalid`);\n    }\n\n    return {\n      view: view.view,\n      pie: view.pie,\n      config: view.config,\n      ...(typeof view.description === 'string' ? { description: view.description } : {}),\n      ...(view.metadata ? { metadata: view.metadata } : {}),\n    };\n  });\n\n  const supportedModes = Array.isArray(raw.supportedModes)\n    ? raw.supportedModes.filter((mode): mode is string => typeof mode === 'string')\n    : undefined;\n\n  return normalizeContract({\n    elementName: raw.elementName,\n    packageName: raw.packageName,\n    framework: raw.framework,\n    summary: typeof raw.summary === 'string' ? raw.summary : undefined,\n    supportedModes: supportedModes?.length ? supportedModes : MODES,\n    views,\n  });\n};\n\nexport const loadContract = async (packageDir: string): Promise<PieDocsContract | null> => {\n  const contractPath = join(packageDir, CONTRACT_FILENAME);\n  if (!existsSync(contractPath)) {\n    return null;\n  }\n  const raw = JSON.parse(await readFile(contractPath, 'utf-8')) as unknown;\n  return parseContract(raw, contractPath);\n};\n\nexport const writeContract = async (\n  packageDir: string,\n  contract: PieDocsContract\n): Promise<void> => {\n  const contractPath = join(packageDir, CONTRACT_FILENAME);\n  const normalized = normalizeContract(contract);\n  await mkdir(packageDir, { recursive: true });\n  await writeFile(contractPath, `${JSON.stringify(normalized, null, 2)}\\n`, 'utf-8');\n};\n\nexport const seedContractForElement = async (\n  element: ElementPackageInfo,\n  rootDir: string,\n  options?: { refresh?: boolean }\n): Promise<{ wrote: boolean; contractPath: string; contract: PieDocsContract }> => {\n  const contractPath = join(element.packageDir, CONTRACT_FILENAME);\n  const existing = await loadContract(element.packageDir);\n  if (existing && !options?.refresh) {\n    return { wrote: false, contractPath, contract: existing };\n  }\n\n  const piePointer = inferPiePointer(element.packageDir);\n  const configPointer = inferConfigPointer(element.packageDir);\n  const views = inferViewsFromPackageExports(element.exportsMap).map((view) => ({\n    view,\n    pie: piePointer,\n    config: configPointer,\n  }));\n\n  const contract: PieDocsContract = normalizeContract({\n    elementName: element.elementName,\n    packageName: element.packageName,\n    framework: element.framework,\n    summary: existing?.summary || element.packageDescription,\n    supportedModes: existing?.supportedModes?.length ? existing.supportedModes : MODES,\n    views,\n  });\n\n  await writeContract(element.packageDir, contract);\n\n  return {\n    wrote: true,\n    contractPath: relative(rootDir, contractPath),\n    contract,\n  };\n};\n"]}

package/dist/lib/docs/discovery.d.ts

@@ -0,0 +1,10 @@
+import type { ElementPackageInfo, PieElementFramework } from './types.js';
+interface DiscoverOptions {
+    rootDir: string;
+    frameworkFilter: PieElementFramework | 'all';
+    elementFilter?: string;
+}
+export declare const CONTRACT_FILENAME = "docs.contract.json";
+export declare const discoverElementPackages: (options: DiscoverOptions) => Promise<ElementPackageInfo[]>;
+export declare const inferViewsFromPackageExports: (exportsMap?: Record<string, unknown>) => string[];
+export {};

package/dist/lib/docs/discovery.js

@@ -0,0 +1,91 @@
+import { existsSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const ELEMENT_PREFIX = '@pie-element/';
+const FRAMEWORK_DIRS = {
+    react: 'packages/elements-react',
+    svelte: 'packages/elements-svelte',
+};
+export const CONTRACT_FILENAME = 'docs.contract.json';
+const safeReadPackageJson = async (packageJsonPath) => {
+    try {
+        const content = await readFile(packageJsonPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+};
+const coerceRecord = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : undefined;
+export const discoverElementPackages = async (options) => {
+    const frameworks = options.frameworkFilter === 'all'
+        ? Object.keys(FRAMEWORK_DIRS)
+        : [options.frameworkFilter];
+    const results = [];
+    for (const framework of frameworks) {
+        const frameworkDir = join(options.rootDir, FRAMEWORK_DIRS[framework]);
+        if (!existsSync(frameworkDir)) {
+            continue;
+        }
+        const packageDirs = await readdir(frameworkDir);
+        for (const dirName of packageDirs) {
+            const packageDir = join(frameworkDir, dirName);
+            const packageJsonPath = join(packageDir, 'package.json');
+            if (!existsSync(packageJsonPath)) {
+                continue;
+            }
+            const pkg = await safeReadPackageJson(packageJsonPath);
+            if (!pkg) {
+                continue;
+            }
+            const packageName = typeof pkg.name === 'string' ? pkg.name : '';
+            if (!packageName.startsWith(ELEMENT_PREFIX)) {
+                continue;
+            }
+            const elementName = packageName.slice(ELEMENT_PREFIX.length).trim();
+            if (!elementName) {
+                continue;
+            }
+            if (options.elementFilter && options.elementFilter !== elementName) {
+                continue;
+            }
+            results.push({
+                elementName,
+                packageName,
+                framework,
+                packageDir,
+                packageDescription: typeof pkg.description === 'string' ? pkg.description : undefined,
+                exportsMap: coerceRecord(pkg.exports),
+            });
+        }
+    }
+    return results.sort((a, b) => a.elementName.localeCompare(b.elementName));
+};
+export const inferViewsFromPackageExports = (exportsMap) => {
+    if (!exportsMap) {
+        return ['delivery'];
+    }
+    const views = new Set(['delivery']);
+    for (const key of Object.keys(exportsMap)) {
+        if (!key.startsWith('./')) {
+            continue;
+        }
+        const view = key.replace('./', '').trim();
+        if (!view ||
+            view === 'delivery' ||
+            view === 'configure' ||
+            view === 'controller' ||
+            view === 'controller.js' ||
+            view === 'runtime-support' ||
+            view.startsWith('browser/')) {
+            continue;
+        }
+        if (view === 'author' || view === 'print' || view.startsWith('delivery-')) {
+            views.add(view);
+        }
+    }
+    return Array.from(views).sort();
+};
+//# sourceMappingURL=discovery.js.map

package/dist/lib/docs/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../../src/lib/docs/discovery.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from 'node:fs';\nimport { readdir, readFile } from 'node:fs/promises';\nimport { join } from 'node:path';\nimport type { ElementPackageInfo, PieElementFramework } from './types.js';\n\ninterface DiscoverOptions {\n  rootDir: string;\n  frameworkFilter: PieElementFramework | 'all';\n  elementFilter?: string;\n}\n\nconst ELEMENT_PREFIX = '@pie-element/';\n\nconst FRAMEWORK_DIRS: Record<PieElementFramework, string> = {\n  react: 'packages/elements-react',\n  svelte: 'packages/elements-svelte',\n};\n\nexport const CONTRACT_FILENAME = 'docs.contract.json';\n\nconst safeReadPackageJson = async (\n  packageJsonPath: string\n): Promise<Record<string, unknown> | null> => {\n  try {\n    const content = await readFile(packageJsonPath, 'utf-8');\n    return JSON.parse(content) as Record<string, unknown>;\n  } catch {\n    return null;\n  }\n};\n\nconst coerceRecord = (value: unknown): Record<string, unknown> | undefined =>\n  value && typeof value === 'object' && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : undefined;\n\nexport const discoverElementPackages = async (\n  options: DiscoverOptions\n): Promise<ElementPackageInfo[]> => {\n  const frameworks: PieElementFramework[] =\n    options.frameworkFilter === 'all'\n      ? (Object.keys(FRAMEWORK_DIRS) as PieElementFramework[])\n      : [options.frameworkFilter];\n\n  const results: ElementPackageInfo[] = [];\n\n  for (const framework of frameworks) {\n    const frameworkDir = join(options.rootDir, FRAMEWORK_DIRS[framework]);\n    if (!existsSync(frameworkDir)) {\n      continue;\n    }\n\n    const packageDirs = await readdir(frameworkDir);\n    for (const dirName of packageDirs) {\n      const packageDir = join(frameworkDir, dirName);\n      const packageJsonPath = join(packageDir, 'package.json');\n      if (!existsSync(packageJsonPath)) {\n        continue;\n      }\n\n      const pkg = await safeReadPackageJson(packageJsonPath);\n      if (!pkg) {\n        continue;\n      }\n\n      const packageName = typeof pkg.name === 'string' ? pkg.name : '';\n      if (!packageName.startsWith(ELEMENT_PREFIX)) {\n        continue;\n      }\n\n      const elementName = packageName.slice(ELEMENT_PREFIX.length).trim();\n      if (!elementName) {\n        continue;\n      }\n\n      if (options.elementFilter && options.elementFilter !== elementName) {\n        continue;\n      }\n\n      results.push({\n        elementName,\n        packageName,\n        framework,\n        packageDir,\n        packageDescription: typeof pkg.description === 'string' ? pkg.description : undefined,\n        exportsMap: coerceRecord(pkg.exports),\n      });\n    }\n  }\n\n  return results.sort((a, b) => a.elementName.localeCompare(b.elementName));\n};\n\nexport const inferViewsFromPackageExports = (exportsMap?: Record<string, unknown>): string[] => {\n  if (!exportsMap) {\n    return ['delivery'];\n  }\n\n  const views = new Set<string>(['delivery']);\n  for (const key of Object.keys(exportsMap)) {\n    if (!key.startsWith('./')) {\n      continue;\n    }\n    const view = key.replace('./', '').trim();\n    if (\n      !view ||\n      view === 'delivery' ||\n      view === 'configure' ||\n      view === 'controller' ||\n      view === 'controller.js' ||\n      view === 'runtime-support' ||\n      view.startsWith('browser/')\n    ) {\n      continue;\n    }\n    if (view === 'author' || view === 'print' || view.startsWith('delivery-')) {\n      views.add(view);\n    }\n  }\n\n  return Array.from(views).sort();\n};\n"]}

package/dist/lib/docs/generator.d.ts

@@ -0,0 +1,14 @@
+import type { PieDocsContract, PieDocsElementOutput } from './types.js';
+export interface GenerateDocsOptions {
+    outputDir: string;
+    dryRun: boolean;
+    check: boolean;
+}
+export interface GenerateDocsResult {
+    filesWritten: string[];
+    filesChecked: string[];
+    driftFiles: string[];
+    outputs: PieDocsElementOutput[];
+}
+export declare const generateDocsForContract: (packageDir: string, contract: PieDocsContract, options: GenerateDocsOptions) => Promise<GenerateDocsResult>;
+export declare const toRelativePaths: (rootDir: string, paths: string[]) => string[];