@protoyard/blueprint 0.0.0-stage → 1.1.1

package/dist/import/csv-shape.d.ts

@@ -0,0 +1,40 @@
+import { type BlueprintEntity } from '../schema.ts';
+export { CSV_SHAPE_MAX_CELL_BYTES, CSV_SHAPE_MAX_COLUMNS, CSV_SHAPE_MAX_SAMPLE_ROWS, } from '../csv-guard.ts';
+/** Options for bounded, data-shape-only CSV inference. */
+export interface CsvShapeOptions {
+    /** Name for the returned entity; normalized to blueprint kebab-case. */
+    entityName?: string;
+    /** Optional human label for the returned entity. */
+    entityLabel?: string;
+    /** Maximum bytes accepted by the existing CSV parser. Never exceeds 2 MiB. */
+    maxBytes?: number;
+    /** Number of non-empty data rows inspected for inference. Never exceeds 100. */
+    maxSampleRows?: number;
+    /** Maximum number of header columns. Never exceeds 100. */
+    maxColumns?: number;
+    /** Maximum UTF-8 bytes accepted for a header or sampled cell. */
+    maxCellBytes?: number;
+}
+export type CsvShapeErrorCode = 'too-many-columns' | 'cell-too-large' | 'invalid-options';
+export declare class CsvShapeError extends Error {
+    readonly code: CsvShapeErrorCode;
+    constructor(code: CsvShapeErrorCode, message: string);
+}
+export interface CsvShapeResult {
+    /** A validated entity draft; imported cell values are deliberately absent. */
+    entity: BlueprintEntity;
+    /** Review notes for uncertain or intentionally conservative inferences. */
+    notes: string[];
+    /** Number of non-empty data rows inspected, not retained. */
+    rowsInspected: number;
+    /** Number of columns represented by the draft. */
+    columns: number;
+}
+/**
+ * Infer a validated, reviewable entity from CSV headers and a bounded sample.
+ * The parser may read the complete bounded CSV input, but the result contains
+ * only names, labels, kinds and conservative metadata — never cell values.
+ */
+export declare function inferCsvEntity(text: string, options?: CsvShapeOptions): CsvShapeResult;
+/** Alias emphasizing the shape-only authoring operation. */
+export declare const inferCsvShape: typeof inferCsvEntity;

package/dist/import/csv-shape.js

@@ -0,0 +1,265 @@
+import { parseCsv } from "../csv.js";
+import { CSV_SHAPE_MAX_CELL_BYTES, CSV_SHAPE_MAX_COLUMNS, CSV_SHAPE_MAX_SAMPLE_ROWS, unguardCsvFormula, } from "../csv-guard.js";
+import { parseBlueprint } from "../schema.js";
+import { IMPORT_MAX_BYTES, IMPORT_MAX_ROWS } from "./limits.js";
+export { CSV_SHAPE_MAX_CELL_BYTES, CSV_SHAPE_MAX_COLUMNS, CSV_SHAPE_MAX_SAMPLE_ROWS, } from "../csv-guard.js";
+export class CsvShapeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'CsvShapeError';
+        this.code = code;
+    }
+}
+const TITLE_KINDS = new Set(['text', 'email', 'url', 'phone', 'enum', 'integer']);
+const SEARCHABLE_KINDS = new Set(['text', 'email', 'url', 'phone', 'enum']);
+const RESERVED_NAMES = new Set(['id', 'createdAt', 'updatedAt', 'deletedAt', 'deletedBy']);
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const DATETIME_PATTERN = /^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:?\d{2})$/;
+const URL_PATTERN = /^https?:\/\/[^\s]+$/i;
+const PHONE_PATTERN = /^\+?[0-9().\-\s]{7,}$/;
+const INTEGER_PATTERN = /^[+-]?\d+$/;
+const NUMBER_PATTERN = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+function bytes(text) {
+    return typeof TextEncoder === 'undefined' ? text.length : new TextEncoder().encode(text).length;
+}
+function bounded(value, fallback, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 1) {
+        throw new CsvShapeError('invalid-options', 'CSV shape limits must be positive finite numbers');
+    }
+    return Math.min(Math.floor(value), maximum);
+}
+function words(value) {
+    return value
+        .normalize('NFKD')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/[^a-zA-Z0-9]+/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+function fieldName(header, index, used) {
+    const parts = words(header);
+    let name = parts
+        .map((part, partIndex) => {
+        const lower = part.toLowerCase();
+        return partIndex === 0 ? lower : `${lower[0]?.toUpperCase() ?? ''}${lower.slice(1)}`;
+    })
+        .join('');
+    if (!name)
+        name = `field${index + 1}`;
+    if (/^\d/.test(name))
+        name = `field${name}`;
+    if (RESERVED_NAMES.has(name))
+        name = `field${name[0]?.toUpperCase() ?? ''}${name.slice(1)}`;
+    const base = name;
+    let suffix = 2;
+    while (used.has(name))
+        name = `${base}${suffix++}`;
+    used.add(name);
+    return name;
+}
+function entityName(value) {
+    const parts = words(value ?? 'Imported records');
+    const name = parts.map((part) => part.toLowerCase()).join('-');
+    return name.replace(/^-+|-+$/g, '') || 'imported-record';
+}
+function humanLabel(value, fallback) {
+    const label = (value ?? fallback).trim().replace(/\s+/g, ' ');
+    return label.slice(0, 60) || fallback;
+}
+function validDate(value) {
+    if (!DATE_PATTERN.test(value))
+        return false;
+    const parsed = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().startsWith(value);
+}
+/** Checks an email-shaped value in one pass; avoid backtracking on hostile cells. */
+function isEmailAddress(value) {
+    if (value.length > 254)
+        return false;
+    let at = -1;
+    let domainDot = false;
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index];
+        if (character === undefined || /\s/u.test(character))
+            return false;
+        if (character === '@') {
+            if (at !== -1)
+                return false;
+            at = index;
+            continue;
+        }
+        if (character === '.' && at !== -1) {
+            if (index === at + 1 || index === value.length - 1 || value[index - 1] === '.')
+                return false;
+            domainDot = true;
+        }
+    }
+    return at > 0 && at < value.length - 1 && value[at - 1] !== '.' && domainDot;
+}
+function allMatch(values, pattern, check) {
+    return (values.length > 0 && values.every((value) => pattern.test(value) && (check?.(value) ?? true)));
+}
+function headerMatches(header, pattern) {
+    return pattern.test(header.toLowerCase().replace(/[^a-z0-9]+/g, ' '));
+}
+function inferField(header, samples, label, notes) {
+    const normalized = samples.map((sample) => unguardCsvFormula(sample).trim()).filter(Boolean);
+    if (normalized.length === 0) {
+        notes.push(`${label}: no non-empty sample values; kept as text for review.`);
+        return 'text';
+    }
+    if (headerMatches(header, /e ?mail|email address/) && normalized.every(isEmailAddress)) {
+        return 'email';
+    }
+    if (headerMatches(header, /url|uri|website|link/) && allMatch(normalized, URL_PATTERN)) {
+        return 'url';
+    }
+    if (headerMatches(header, /phone|mobile|telephone/) && allMatch(normalized, PHONE_PATTERN)) {
+        return 'phone';
+    }
+    if (headerMatches(header, /date|day|birthday|due/) &&
+        allMatch(normalized, DATE_PATTERN, validDate)) {
+        return 'date';
+    }
+    if (headerMatches(header, /time|timestamp|created at|updated at/) &&
+        allMatch(normalized, DATETIME_PATTERN, (value) => !Number.isNaN(Date.parse(value)))) {
+        return 'datetime';
+    }
+    if (headerMatches(header, /boolean|active|enabled|verified|archived|done/) &&
+        allMatch(normalized, /^(?:true|false)$/i)) {
+        return 'boolean';
+    }
+    if (headerMatches(header, /tag|label|keyword/) &&
+        normalized.some((value) => value.includes(','))) {
+        return 'tags';
+    }
+    if (allMatch(normalized, INTEGER_PATTERN)) {
+        if (headerMatches(header, /amount|price|cost|revenue|total|budget|fee|salary|money/)) {
+            return 'money';
+        }
+        return 'integer';
+    }
+    if (allMatch(normalized, NUMBER_PATTERN)) {
+        if (headerMatches(header, /amount|price|cost|revenue|total|budget|fee|salary|money/)) {
+            return 'money';
+        }
+        return 'number';
+    }
+    if (normalized.some((value) => value.length > 200) ||
+        headerMatches(header, /body|description|notes|comment|details/)) {
+        return 'longText';
+    }
+    if (headerMatches(header, /email|url|phone|date|time|number|amount|price|active|enabled|tag/) ||
+        normalized.some((value) => DATE_PATTERN.test(value) || NUMBER_PATTERN.test(value))) {
+        notes.push(`${label}: sample values were mixed or ambiguous; kept as text for review.`);
+    }
+    return 'text';
+}
+function fieldFor(name, label, kind) {
+    if (kind === 'money')
+        return { name, label, kind, currency: 'USD' };
+    if (kind === 'tags')
+        return { name, label, kind, maxItems: 8 };
+    if (kind === 'text')
+        return { name, label, kind, maxLength: 200 };
+    if (kind === 'longText')
+        return { name, label, kind, maxLength: 10_000 };
+    return { name, label, kind };
+}
+function parseLimits(options) {
+    return {
+        maxBytes: bounded(options.maxBytes, IMPORT_MAX_BYTES, IMPORT_MAX_BYTES),
+        maxSampleRows: bounded(options.maxSampleRows, CSV_SHAPE_MAX_SAMPLE_ROWS, CSV_SHAPE_MAX_SAMPLE_ROWS),
+        maxColumns: bounded(options.maxColumns, CSV_SHAPE_MAX_COLUMNS, CSV_SHAPE_MAX_COLUMNS),
+        maxCellBytes: bounded(options.maxCellBytes, CSV_SHAPE_MAX_CELL_BYTES, CSV_SHAPE_MAX_CELL_BYTES),
+    };
+}
+/**
+ * Infer a validated, reviewable entity from CSV headers and a bounded sample.
+ * The parser may read the complete bounded CSV input, but the result contains
+ * only names, labels, kinds and conservative metadata — never cell values.
+ */
+export function inferCsvEntity(text, options = {}) {
+    const limits = parseLimits(options);
+    const parseOptions = { maxBytes: limits.maxBytes, maxRows: IMPORT_MAX_ROWS };
+    const [headers = [], ...rows] = parseCsv(text, parseOptions);
+    if (headers.length === 0 || headers.every((header) => header.trim() === '')) {
+        throw new CsvShapeError('invalid-options', 'CSV shape inference needs a non-empty header row');
+    }
+    if (headers.length > limits.maxColumns) {
+        throw new CsvShapeError('too-many-columns', `CSV has ${headers.length.toLocaleString()} columns; the limit is ${limits.maxColumns.toLocaleString()}`);
+    }
+    if (headers.some((header) => bytes(header) > limits.maxCellBytes)) {
+        throw new CsvShapeError('cell-too-large', `A CSV header exceeds the ${limits.maxCellBytes.toLocaleString()}-byte limit`);
+    }
+    const rowsWithData = rows.filter((row) => row.some((cell) => cell.trim() !== ''));
+    for (const row of rowsWithData.slice(0, limits.maxSampleRows)) {
+        for (const cell of row.slice(0, headers.length)) {
+            if (bytes(cell) > limits.maxCellBytes) {
+                throw new CsvShapeError('cell-too-large', `A CSV sample cell exceeds the ${limits.maxCellBytes.toLocaleString()}-byte limit`);
+            }
+        }
+    }
+    const notes = [];
+    if (rowsWithData.length > limits.maxSampleRows) {
+        notes.push(`Only the first ${limits.maxSampleRows.toLocaleString()} non-empty data rows were inspected.`);
+    }
+    const sampledRows = rowsWithData.slice(0, limits.maxSampleRows);
+    const usedNames = new Set();
+    const fields = [];
+    const fieldKinds = [];
+    headers.forEach((rawHeader, index) => {
+        const header = rawHeader.trim();
+        const label = humanLabel(header, `Field ${index + 1}`);
+        const name = fieldName(header, index, usedNames);
+        if (name !== (words(header).join('') || `field${index + 1}`)) {
+            notes.push(`${label}: normalized to the field name "${name}".`);
+        }
+        const samples = sampledRows.map((row) => row[index] ?? '');
+        const kind = inferField(header, samples, label, notes);
+        fieldKinds.push(kind);
+        fields.push(fieldFor(name, label, kind));
+    });
+    let titleIndex = fieldKinds.findIndex((kind) => TITLE_KINDS.has(kind));
+    if (titleIndex < 0) {
+        const name = fieldName('Name', fields.length, usedNames);
+        fields.unshift({ name, label: 'Name', kind: 'text', maxLength: 200 });
+        fieldKinds.unshift('text');
+        titleIndex = 0;
+        notes.push('Added a blank Name field because no imported column was title-compatible.');
+    }
+    const name = entityName(options.entityName);
+    const entity = parseBlueprint({
+        formatVersion: 1,
+        name: humanLabel(options.entityLabel, name.replace(/-/g, ' ')),
+        entities: [
+            {
+                name,
+                plural: `${name}s`,
+                label: humanLabel(options.entityLabel, name.replace(/-/g, ' ')),
+                fields,
+                titleField: fields[titleIndex].name,
+                searchable: fields
+                    .filter((_field, index) => index !== titleIndex && SEARCHABLE_KINDS.has(fieldKinds[index]))
+                    .slice(0, 3)
+                    .map((field) => field.name),
+                features: { csv: true },
+            },
+        ],
+        roles: [{ name: 'owner', permissions: { '*': ['*'] } }],
+    }).entities[0];
+    if (!entity)
+        throw new CsvShapeError('invalid-options', 'CSV shape inference produced no entity');
+    return {
+        entity,
+        notes,
+        rowsInspected: sampledRows.length,
+        columns: headers.length,
+    };
+}
+/** Alias emphasizing the shape-only authoring operation. */
+export const inferCsvShape = inferCsvEntity;

package/dist/import/json-shape.d.ts

@@ -0,0 +1,55 @@
+import { type BlueprintEntity } from '../schema.ts';
+export declare const JSON_SHAPE_MAX_BYTES: number;
+export declare const JSON_SHAPE_MAX_SAMPLE_OBJECTS = 100;
+export declare const JSON_SHAPE_MAX_DEPTH = 8;
+export declare const JSON_SHAPE_MAX_OBJECTS = 2000;
+export declare const JSON_SHAPE_MAX_FIELDS = 100;
+export declare const JSON_SHAPE_MAX_STRING_BYTES: number;
+export interface JsonShapeOptions {
+    /** Name for the root entity; normalized to blueprint kebab-case. */
+    entityName?: string;
+    /** Optional human label for the root entity. */
+    entityLabel?: string;
+    /** Maximum UTF-8 input bytes. Overrides are clamped to the hard maximum. */
+    maxBytes?: number;
+    /** Maximum representative objects sampled per entity. */
+    maxSampleObjects?: number;
+    /** Maximum accepted nested JSON depth. */
+    maxDepth?: number;
+    /** Maximum object and array nodes traversed. */
+    maxObjects?: number;
+    /** Maximum field keys inferred per entity. */
+    maxFields?: number;
+    /** Maximum bytes in any one JSON string value. */
+    maxStringBytes?: number;
+}
+export type JsonShapeErrorCode = 'invalid-json' | 'invalid-shape' | 'input-too-large' | 'too-deep' | 'too-many-objects' | 'too-many-fields' | 'string-too-large' | 'unsafe-key' | 'invalid-options';
+export declare class JsonShapeError extends Error {
+    readonly code: JsonShapeErrorCode;
+    constructor(code: JsonShapeErrorCode, message: string);
+}
+export interface JsonShapeRelationCandidate {
+    sourceEntity: string;
+    field: string;
+    targetEntity: string;
+    cardinality: 'many';
+    reason: string;
+}
+export interface JsonShapeResult {
+    /** Validated entity drafts; the first is the supplied object or array shape. */
+    entities: BlueprintEntity[];
+    /** Normalized review notes that never include sampled values. */
+    notes: string[];
+    /** Candidate one-to-many links inferred from arrays of objects. */
+    relationCandidates: JsonShapeRelationCandidate[];
+    /** Number of representative record objects used across the inferred entities. */
+    objectsInspected: number;
+}
+/**
+ * Infer a validated, reviewable draft from one JSON record or an array of
+ * records. Only names and shape metadata are returned; source values never
+ * enter entities, relation candidates, notes, or errors.
+ */
+export declare function inferJsonShape(text: string, options?: JsonShapeOptions): JsonShapeResult;
+/** Alias emphasizing this is authoring-only shape inference. */
+export declare const inferJsonEntity: typeof inferJsonShape;