@compilr-dev/factory 0.1.13 → 0.1.14

package/dist/index.d.ts

@@ -24,3 +24,5 @@ export { staticLandingToolkit } from './toolkits/static-landing/index.js';
 export { reactFastapiToolkit } from './toolkits/react-fastapi/index.js';
 export { reactGoToolkit } from './toolkits/react-go/index.js';
 export { factoryScaffoldSkill, factorySkills } from './factory/skill.js';
+export type { ResearchModel, Section, SectionStatus, Claim, ClaimType, EvidenceStrength, SourceRef, Source, SourceRelevance, CitationInfo, CitationType, CitationStyle, ResearchQuestion, QuestionStatus, ResearchMeta, ResearchValidationError, ResearchValidationResult, ResearchModelOperation, ResearchModelToolsConfig, } from './research-model/index.js';
+export { createDefaultResearchModel, createDefaultSection, createDefaultClaim, createDefaultSource, createDefaultQuestion, ResearchModelStore, applyResearchOperation, validateResearchModel, createResearchModelTools, } from './research-model/index.js';

package/dist/index.js

@@ -31,3 +31,4 @@ export { reactFastapiToolkit } from './toolkits/react-fastapi/index.js';
 export { reactGoToolkit } from './toolkits/react-go/index.js';
 // Factory skill (Phase 5)
 export { factoryScaffoldSkill, factorySkills } from './factory/skill.js';
+export { createDefaultResearchModel, createDefaultSection, createDefaultClaim, createDefaultSource, createDefaultQuestion, ResearchModelStore, applyResearchOperation, validateResearchModel, createResearchModelTools, } from './research-model/index.js';

package/dist/research-model/defaults.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Default Research Model Creators
+ *
+ * Factory functions for creating ResearchModel and sub-structure
+ * instances with sensible defaults.
+ */
+import type { ResearchModel, Section, Claim, Source, ResearchQuestion, CitationInfo } from './types.js';
+/** Generate a short unique ID. */
+export declare function generateId(prefix?: string): string;
+/** Reset ID counter (for tests). */
+export declare function resetIdCounter(): void;
+export declare function createDefaultResearchModel(overrides?: Partial<ResearchModel>): ResearchModel;
+export declare function createDefaultSection(title: string, order: number, overrides?: Partial<Section>): Section;
+export declare function createDefaultClaim(statement: string, overrides?: Partial<Claim>): Claim;
+export declare function createDefaultSource(citeKey: string, citation: CitationInfo, overrides?: Partial<Source>): Source;
+export declare function createDefaultQuestion(question: string, overrides?: Partial<ResearchQuestion>): ResearchQuestion;

package/dist/research-model/defaults.js

@@ -0,0 +1,76 @@
+/**
+ * Default Research Model Creators
+ *
+ * Factory functions for creating ResearchModel and sub-structure
+ * instances with sensible defaults.
+ */
+let _idCounter = 0;
+/** Generate a short unique ID. */
+export function generateId(prefix = 'r') {
+    _idCounter++;
+    return `${prefix}_${Date.now().toString(36)}_${String(_idCounter)}`;
+}
+/** Reset ID counter (for tests). */
+export function resetIdCounter() {
+    _idCounter = 0;
+}
+export function createDefaultResearchModel(overrides) {
+    const now = new Date().toISOString();
+    return {
+        title: overrides?.title ?? 'Untitled Paper',
+        citationStyle: overrides?.citationStyle ?? 'apa',
+        researchQuestions: overrides?.researchQuestions ?? [],
+        sections: overrides?.sections ?? [],
+        sources: overrides?.sources ?? [],
+        abstract: overrides?.abstract,
+        authors: overrides?.authors,
+        targetJournal: overrides?.targetJournal,
+        keywords: overrides?.keywords,
+        methodology: overrides?.methodology,
+        meta: {
+            revision: 1,
+            createdAt: now,
+            updatedAt: now,
+            ...overrides?.meta,
+        },
+    };
+}
+export function createDefaultSection(title, order, overrides) {
+    return {
+        id: overrides?.id ?? generateId('sec'),
+        title,
+        order,
+        status: 'outlined',
+        claims: [],
+        ...overrides,
+    };
+}
+export function createDefaultClaim(statement, overrides) {
+    return {
+        id: overrides?.id ?? generateId('clm'),
+        statement,
+        evidenceStrength: 'unsupported',
+        supportingSources: [],
+        contradictingSources: [],
+        type: 'original',
+        ...overrides,
+    };
+}
+export function createDefaultSource(citeKey, citation, overrides) {
+    return {
+        id: overrides?.id ?? generateId('src'),
+        citeKey,
+        citation,
+        analyzed: false,
+        ...overrides,
+    };
+}
+export function createDefaultQuestion(question, overrides) {
+    return {
+        id: overrides?.id ?? generateId('rq'),
+        question,
+        sectionRefs: [],
+        status: 'open',
+        ...overrides,
+    };
+}

package/dist/research-model/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Research Model — barrel export
+ */
+export type { ResearchModel, Section, SectionStatus, Claim, ClaimType, EvidenceStrength, SourceRef, Source, SourceRelevance, CitationInfo, CitationType, CitationStyle, ResearchQuestion, QuestionStatus, ResearchMeta, } from './types.js';
+export { createDefaultResearchModel, createDefaultSection, createDefaultClaim, createDefaultSource, createDefaultQuestion, generateId, resetIdCounter, } from './defaults.js';
+export { ResearchModelStore } from './persistence.js';
+export { applyResearchOperation } from './operations.js';
+export type { ResearchModelOperation } from './operations.js';
+export { validateResearchModel } from './schema.js';
+export type { ResearchValidationError, ResearchValidationResult } from './schema.js';
+export { createResearchModelTools } from './tools.js';
+export type { ResearchModelToolsConfig } from './tools.js';

package/dist/research-model/index.js

@@ -0,0 +1,13 @@
+/**
+ * Research Model — barrel export
+ */
+// Defaults
+export { createDefaultResearchModel, createDefaultSection, createDefaultClaim, createDefaultSource, createDefaultQuestion, generateId, resetIdCounter, } from './defaults.js';
+// Persistence
+export { ResearchModelStore } from './persistence.js';
+// Operations
+export { applyResearchOperation } from './operations.js';
+// Validation
+export { validateResearchModel } from './schema.js';
+// Tools
+export { createResearchModelTools } from './tools.js';

package/dist/research-model/operations-claim.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Claim Operations
+ *
+ * claim_add, claim_update, claim_remove, claim_link_source, claim_unlink_source
+ */
+import type { ResearchModel, Claim, SourceRef } from './types.js';
+export interface ClaimAddOp {
+    readonly op: 'claim_add';
+    readonly sectionId: string;
+    readonly claim: Partial<Claim> & {
+        statement: string;
+    };
+}
+export interface ClaimUpdateOp {
+    readonly op: 'claim_update';
+    readonly sectionId: string;
+    readonly claimId: string;
+    readonly updates: Partial<Omit<Claim, 'id' | 'supportingSources' | 'contradictingSources'>>;
+}
+export interface ClaimRemoveOp {
+    readonly op: 'claim_remove';
+    readonly sectionId: string;
+    readonly claimId: string;
+}
+export interface ClaimLinkSourceOp {
+    readonly op: 'claim_link_source';
+    readonly sectionId: string;
+    readonly claimId: string;
+    readonly sourceRef: SourceRef;
+    readonly relation: 'supporting' | 'contradicting';
+}
+export interface ClaimUnlinkSourceOp {
+    readonly op: 'claim_unlink_source';
+    readonly sectionId: string;
+    readonly claimId: string;
+    readonly sourceId: string;
+}
+export type ClaimOperation = ClaimAddOp | ClaimUpdateOp | ClaimRemoveOp | ClaimLinkSourceOp | ClaimUnlinkSourceOp;
+export declare function claimAdd(model: ResearchModel, op: ClaimAddOp): ResearchModel;
+export declare function claimUpdate(model: ResearchModel, op: ClaimUpdateOp): ResearchModel;
+export declare function claimRemove(model: ResearchModel, op: ClaimRemoveOp): ResearchModel;
+export declare function claimLinkSource(model: ResearchModel, op: ClaimLinkSourceOp): ResearchModel;
+export declare function claimUnlinkSource(model: ResearchModel, op: ClaimUnlinkSourceOp): ResearchModel;

package/dist/research-model/operations-claim.js

@@ -0,0 +1,99 @@
+/**
+ * Claim Operations
+ *
+ * claim_add, claim_update, claim_remove, claim_link_source, claim_unlink_source
+ */
+import { generateId } from './defaults.js';
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function mapSection(model, sectionId, fn) {
+    const section = model.sections.find((s) => s.id === sectionId);
+    if (!section)
+        throw new Error(`Section "${sectionId}" not found`);
+    return {
+        ...model,
+        sections: model.sections.map((s) => {
+            if (s.id !== sectionId)
+                return s;
+            return { ...s, claims: fn(s.claims) };
+        }),
+    };
+}
+function findClaim(claims, claimId) {
+    const claim = claims.find((c) => c.id === claimId);
+    if (!claim)
+        throw new Error(`Claim "${claimId}" not found`);
+    return claim;
+}
+// ─── Operations ──────────────────────────────────────────────────────────────
+export function claimAdd(model, op) {
+    return mapSection(model, op.sectionId, (claims) => {
+        const claim = {
+            id: op.claim.id ?? generateId('clm'),
+            statement: op.claim.statement,
+            evidenceStrength: op.claim.evidenceStrength ?? 'unsupported',
+            supportingSources: op.claim.supportingSources ?? [],
+            contradictingSources: op.claim.contradictingSources ?? [],
+            type: op.claim.type ?? 'original',
+        };
+        return [...claims, claim];
+    });
+}
+export function claimUpdate(model, op) {
+    return mapSection(model, op.sectionId, (claims) => {
+        findClaim(claims, op.claimId);
+        return claims.map((c) => {
+            if (c.id !== op.claimId)
+                return c;
+            return {
+                ...c,
+                ...op.updates,
+                id: c.id,
+                supportingSources: c.supportingSources,
+                contradictingSources: c.contradictingSources,
+            };
+        });
+    });
+}
+export function claimRemove(model, op) {
+    return mapSection(model, op.sectionId, (claims) => {
+        findClaim(claims, op.claimId);
+        return claims.filter((c) => c.id !== op.claimId);
+    });
+}
+export function claimLinkSource(model, op) {
+    // Validate source exists
+    if (!model.sources.some((s) => s.id === op.sourceRef.sourceId)) {
+        throw new Error(`Source "${op.sourceRef.sourceId}" not found`);
+    }
+    return mapSection(model, op.sectionId, (claims) => {
+        findClaim(claims, op.claimId);
+        return claims.map((c) => {
+            if (c.id !== op.claimId)
+                return c;
+            if (op.relation === 'supporting') {
+                if (c.supportingSources.some((r) => r.sourceId === op.sourceRef.sourceId))
+                    return c;
+                return { ...c, supportingSources: [...c.supportingSources, op.sourceRef] };
+            }
+            else {
+                if (c.contradictingSources.some((r) => r.sourceId === op.sourceRef.sourceId))
+                    return c;
+                return { ...c, contradictingSources: [...c.contradictingSources, op.sourceRef] };
+            }
+        });
+    });
+}
+export function claimUnlinkSource(model, op) {
+    return mapSection(model, op.sectionId, (claims) => {
+        findClaim(claims, op.claimId);
+        return claims.map((c) => {
+            if (c.id !== op.claimId)
+                return c;
+            return {
+                ...c,
+                supportingSources: c.supportingSources.filter((r) => r.sourceId !== op.sourceId),
+                contradictingSources: c.contradictingSources.filter((r) => r.sourceId !== op.sourceId),
+            };
+        });
+    });
+}

package/dist/research-model/operations-metadata.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Metadata Operations
+ *
+ * set_title, set_abstract, set_citation_style, set_keywords, set_methodology,
+ * set_authors, set_target_journal
+ */
+import type { ResearchModel, CitationStyle } from './types.js';
+export interface SetTitleOp {
+    readonly op: 'set_title';
+    readonly title: string;
+}
+export interface SetAbstractOp {
+    readonly op: 'set_abstract';
+    readonly abstract: string;
+}
+export interface SetCitationStyleOp {
+    readonly op: 'set_citation_style';
+    readonly citationStyle: CitationStyle;
+}
+export interface SetKeywordsOp {
+    readonly op: 'set_keywords';
+    readonly keywords: readonly string[];
+}
+export interface SetMethodologyOp {
+    readonly op: 'set_methodology';
+    readonly methodology: string;
+}
+export interface SetAuthorsOp {
+    readonly op: 'set_authors';
+    readonly authors: readonly string[];
+}
+export interface SetTargetJournalOp {
+    readonly op: 'set_target_journal';
+    readonly targetJournal: string;
+}
+export type MetadataOperation = SetTitleOp | SetAbstractOp | SetCitationStyleOp | SetKeywordsOp | SetMethodologyOp | SetAuthorsOp | SetTargetJournalOp;
+export declare function setTitle(model: ResearchModel, op: SetTitleOp): ResearchModel;
+export declare function setAbstract(model: ResearchModel, op: SetAbstractOp): ResearchModel;
+export declare function setCitationStyle(model: ResearchModel, op: SetCitationStyleOp): ResearchModel;
+export declare function setKeywords(model: ResearchModel, op: SetKeywordsOp): ResearchModel;
+export declare function setMethodology(model: ResearchModel, op: SetMethodologyOp): ResearchModel;
+export declare function setAuthors(model: ResearchModel, op: SetAuthorsOp): ResearchModel;
+export declare function setTargetJournal(model: ResearchModel, op: SetTargetJournalOp): ResearchModel;

package/dist/research-model/operations-metadata.js

@@ -0,0 +1,34 @@
+/**
+ * Metadata Operations
+ *
+ * set_title, set_abstract, set_citation_style, set_keywords, set_methodology,
+ * set_authors, set_target_journal
+ */
+// ─── Operations ──────────────────────────────────────────────────────────────
+export function setTitle(model, op) {
+    if (!op.title.trim())
+        throw new Error('Title cannot be empty');
+    return { ...model, title: op.title };
+}
+export function setAbstract(model, op) {
+    return { ...model, abstract: op.abstract };
+}
+export function setCitationStyle(model, op) {
+    const valid = ['apa', 'mla', 'chicago', 'ieee', 'harvard'];
+    if (!valid.includes(op.citationStyle)) {
+        throw new Error(`Invalid citation style "${op.citationStyle}". Must be one of: ${valid.join(', ')}`);
+    }
+    return { ...model, citationStyle: op.citationStyle };
+}
+export function setKeywords(model, op) {
+    return { ...model, keywords: op.keywords };
+}
+export function setMethodology(model, op) {
+    return { ...model, methodology: op.methodology };
+}
+export function setAuthors(model, op) {
+    return { ...model, authors: op.authors };
+}
+export function setTargetJournal(model, op) {
+    return { ...model, targetJournal: op.targetJournal };
+}

package/dist/research-model/operations-question.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Question Operations
+ *
+ * question_add, question_update, question_remove, question_link_section
+ */
+import type { ResearchModel, ResearchQuestion } from './types.js';
+export interface QuestionAddOp {
+    readonly op: 'question_add';
+    readonly question: Partial<ResearchQuestion> & {
+        question: string;
+    };
+}
+export interface QuestionUpdateOp {
+    readonly op: 'question_update';
+    readonly questionId: string;
+    readonly updates: Partial<Omit<ResearchQuestion, 'id'>>;
+}
+export interface QuestionRemoveOp {
+    readonly op: 'question_remove';
+    readonly questionId: string;
+}
+export interface QuestionLinkSectionOp {
+    readonly op: 'question_link_section';
+    readonly questionId: string;
+    readonly sectionId: string;
+    readonly unlink?: boolean;
+}
+export type QuestionOperation = QuestionAddOp | QuestionUpdateOp | QuestionRemoveOp | QuestionLinkSectionOp;
+export declare function questionAdd(model: ResearchModel, op: QuestionAddOp): ResearchModel;
+export declare function questionUpdate(model: ResearchModel, op: QuestionUpdateOp): ResearchModel;
+export declare function questionRemove(model: ResearchModel, op: QuestionRemoveOp): ResearchModel;
+export declare function questionLinkSection(model: ResearchModel, op: QuestionLinkSectionOp): ResearchModel;

package/dist/research-model/operations-question.js

@@ -0,0 +1,59 @@
+/**
+ * Question Operations
+ *
+ * question_add, question_update, question_remove, question_link_section
+ */
+import { generateId } from './defaults.js';
+// ─── Operations ──────────────────────────────────────────────────────────────
+export function questionAdd(model, op) {
+    const question = {
+        id: op.question.id ?? generateId('rq'),
+        question: op.question.question,
+        sectionRefs: op.question.sectionRefs ?? [],
+        status: op.question.status ?? 'open',
+    };
+    return { ...model, researchQuestions: [...model.researchQuestions, question] };
+}
+export function questionUpdate(model, op) {
+    if (!model.researchQuestions.some((q) => q.id === op.questionId)) {
+        throw new Error(`Research question "${op.questionId}" not found`);
+    }
+    return {
+        ...model,
+        researchQuestions: model.researchQuestions.map((q) => {
+            if (q.id !== op.questionId)
+                return q;
+            return { ...q, ...op.updates, id: q.id };
+        }),
+    };
+}
+export function questionRemove(model, op) {
+    if (!model.researchQuestions.some((q) => q.id === op.questionId)) {
+        throw new Error(`Research question "${op.questionId}" not found`);
+    }
+    return {
+        ...model,
+        researchQuestions: model.researchQuestions.filter((q) => q.id !== op.questionId),
+    };
+}
+export function questionLinkSection(model, op) {
+    if (!model.researchQuestions.some((q) => q.id === op.questionId)) {
+        throw new Error(`Research question "${op.questionId}" not found`);
+    }
+    if (!model.sections.some((s) => s.id === op.sectionId)) {
+        throw new Error(`Section "${op.sectionId}" not found`);
+    }
+    return {
+        ...model,
+        researchQuestions: model.researchQuestions.map((q) => {
+            if (q.id !== op.questionId)
+                return q;
+            if (op.unlink) {
+                return { ...q, sectionRefs: q.sectionRefs.filter((ref) => ref !== op.sectionId) };
+            }
+            if (q.sectionRefs.includes(op.sectionId))
+                return q;
+            return { ...q, sectionRefs: [...q.sectionRefs, op.sectionId] };
+        }),
+    };
+}

package/dist/research-model/operations-section.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Section Operations
+ *
+ * section_add, section_update, section_remove, section_reorder, section_move
+ */
+import type { ResearchModel, Section } from './types.js';
+export interface SectionAddOp {
+    readonly op: 'section_add';
+    readonly section: Partial<Section> & {
+        title: string;
+    };
+}
+export interface SectionUpdateOp {
+    readonly op: 'section_update';
+    readonly sectionId: string;
+    readonly updates: Partial<Omit<Section, 'id' | 'claims'>>;
+}
+export interface SectionRemoveOp {
+    readonly op: 'section_remove';
+    readonly sectionId: string;
+    readonly force?: boolean;
+}
+export interface SectionReorderOp {
+    readonly op: 'section_reorder';
+    readonly order: readonly string[];
+}
+export interface SectionMoveOp {
+    readonly op: 'section_move';
+    readonly sectionId: string;
+    readonly newParentId?: string;
+}
+export type SectionOperation = SectionAddOp | SectionUpdateOp | SectionRemoveOp | SectionReorderOp | SectionMoveOp;
+export declare function sectionAdd(model: ResearchModel, op: SectionAddOp): ResearchModel;
+export declare function sectionUpdate(model: ResearchModel, op: SectionUpdateOp): ResearchModel;
+export declare function sectionRemove(model: ResearchModel, op: SectionRemoveOp): ResearchModel;
+export declare function sectionReorder(model: ResearchModel, op: SectionReorderOp): ResearchModel;
+export declare function sectionMove(model: ResearchModel, op: SectionMoveOp): ResearchModel;

package/dist/research-model/operations-section.js

@@ -0,0 +1,94 @@
+/**
+ * Section Operations
+ *
+ * section_add, section_update, section_remove, section_reorder, section_move
+ */
+import { generateId } from './defaults.js';
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function findSection(model, id) {
+    const section = model.sections.find((s) => s.id === id);
+    if (!section)
+        throw new Error(`Section "${id}" not found`);
+    return section;
+}
+// ─── Operations ──────────────────────────────────────────────────────────────
+export function sectionAdd(model, op) {
+    const maxOrder = model.sections.reduce((max, s) => Math.max(max, s.order), 0);
+    const section = {
+        id: op.section.id ?? generateId('sec'),
+        title: op.section.title,
+        purpose: op.section.purpose,
+        order: op.section.order ?? maxOrder + 1,
+        parentId: op.section.parentId,
+        status: op.section.status ?? 'outlined',
+        targetWordCount: op.section.targetWordCount,
+        claims: op.section.claims ?? [],
+        notes: op.section.notes,
+    };
+    if (section.parentId) {
+        findSection(model, section.parentId); // validate parent exists
+    }
+    return { ...model, sections: [...model.sections, section] };
+}
+export function sectionUpdate(model, op) {
+    findSection(model, op.sectionId);
+    return {
+        ...model,
+        sections: model.sections.map((s) => {
+            if (s.id !== op.sectionId)
+                return s;
+            return { ...s, ...op.updates, id: s.id, claims: s.claims };
+        }),
+    };
+}
+export function sectionRemove(model, op) {
+    findSection(model, op.sectionId);
+    // Check for children
+    const children = model.sections.filter((s) => s.parentId === op.sectionId);
+    if (children.length > 0 && !op.force) {
+        throw new Error(`Cannot remove section "${op.sectionId}": has ${String(children.length)} child section(s). Use force: true to cascade.`);
+    }
+    let sections = model.sections.filter((s) => s.id !== op.sectionId);
+    if (op.force) {
+        sections = sections.filter((s) => s.parentId !== op.sectionId);
+    }
+    // Clean up question sectionRefs
+    const questions = model.researchQuestions.map((q) => ({
+        ...q,
+        sectionRefs: q.sectionRefs.filter((ref) => ref !== op.sectionId),
+    }));
+    return { ...model, sections, researchQuestions: questions };
+}
+export function sectionReorder(model, op) {
+    const ids = new Set(model.sections.map((s) => s.id));
+    for (const id of op.order) {
+        if (!ids.has(id))
+            throw new Error(`Section "${id}" not found`);
+    }
+    return {
+        ...model,
+        sections: model.sections.map((s) => {
+            const newOrder = op.order.indexOf(s.id);
+            if (newOrder === -1)
+                return s;
+            return { ...s, order: newOrder + 1 };
+        }),
+    };
+}
+export function sectionMove(model, op) {
+    findSection(model, op.sectionId);
+    if (op.newParentId) {
+        findSection(model, op.newParentId);
+        if (op.newParentId === op.sectionId) {
+            throw new Error('Cannot move a section under itself');
+        }
+    }
+    return {
+        ...model,
+        sections: model.sections.map((s) => {
+            if (s.id !== op.sectionId)
+                return s;
+            return { ...s, parentId: op.newParentId };
+        }),
+    };
+}

package/dist/research-model/operations-source.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Source Operations
+ *
+ * source_add, source_update, source_remove
+ */
+import type { ResearchModel, Source, CitationInfo } from './types.js';
+export interface SourceAddOp {
+    readonly op: 'source_add';
+    readonly source: Partial<Source> & {
+        citeKey: string;
+        citation: CitationInfo;
+    };
+}
+export interface SourceUpdateOp {
+    readonly op: 'source_update';
+    readonly sourceId: string;
+    readonly updates: Partial<Omit<Source, 'id'>>;
+}
+export interface SourceRemoveOp {
+    readonly op: 'source_remove';
+    readonly sourceId: string;
+    readonly force?: boolean;
+}
+export type SourceOperation = SourceAddOp | SourceUpdateOp | SourceRemoveOp;
+export declare function sourceAdd(model: ResearchModel, op: SourceAddOp): ResearchModel;
+export declare function sourceUpdate(model: ResearchModel, op: SourceUpdateOp): ResearchModel;
+export declare function sourceRemove(model: ResearchModel, op: SourceRemoveOp): ResearchModel;