Skip to content

refactor(adf): dismantle monolithic types.ts into domain-owned modules #22

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SmartBrandStrategies merged 1 commit into from
Mar 3, 2026
Merged

refactor(adf): dismantle monolithic types.ts into domain-owned modules #22

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
259 changes: 2 additions & 257 deletions packages/adf/src/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,257 +1,2 @@
/**
* ADF (Attention-Directed Format) AST types.
*
* Defines the canonical data model for ADF documents, patch operations,
* manifest routing, and bundle output.
*/

// ============================================================================
// AST Types
// ============================================================================

export interface AdfDocument {
version: '0.1';
sections: AdfSection[];
}

export interface AdfSection {
key: string;
decoration: string | null;
content: AdfContent;
weight?: 'load-bearing' | 'advisory';
}

export type AdfContent =
| { type: 'text'; value: string }
| { type: 'list'; items: string[] }
| { type: 'map'; entries: AdfMapEntry[] }
| { type: 'metric'; entries: AdfMetricEntry[] };

export interface AdfMapEntry {
key: string;
value: string;
}

export interface AdfMetricEntry {
key: string;
value: number;
ceiling: number;
unit: string;
}

// ============================================================================
// Standard Decorations
// ============================================================================

export const STANDARD_DECORATIONS: Record<string, string> = {
TASK: '\u{1F3AF}',
ROLE: '\u{1F9D1}',
CONTEXT: '\u{1F4CB}',
OUTPUT: '\u{2705}',
CONSTRAINTS: '\u{26A0}\u{FE0F}',
RULES: '\u{1F4D0}',
DEFAULT_LOAD: '\u{1F4E6}',
ON_DEMAND: '\u{1F4C2}',
FILES: '\u{1F5C2}\u{FE0F}',
TOOLS: '\u{1F6E0}\u{FE0F}',
RISKS: '\u{1F6A8}',
STATE: '\u{1F9E0}',
BUDGET: '\u{1F4B0}',
SYNC: '\u{1F504}',
CADENCE: '\u{1F4CA}',
GUIDE: '\u{1F4D6}',
};

export const CANONICAL_KEY_ORDER: string[] = [
'TASK',
'ROLE',
'CONTEXT',
'OUTPUT',
'CONSTRAINTS',
'RULES',
'DEFAULT_LOAD',
'ON_DEMAND',
'BUDGET',
'SYNC',
'CADENCE',
'FILES',
'TOOLS',
'RISKS',
'STATE',
'GUIDE',
];

// ============================================================================
// Patch Operations (Discriminated Union)
// ============================================================================

export interface AddBulletOp {
op: 'ADD_BULLET';
section: string;
value: string;
}

export interface ReplaceBulletOp {
op: 'REPLACE_BULLET';
section: string;
index: number;
value: string;
}

export interface RemoveBulletOp {
op: 'REMOVE_BULLET';
section: string;
index: number;
}

export interface AddSectionOp {
op: 'ADD_SECTION';
key: string;
decoration?: string | null;
content: AdfContent;
weight?: 'load-bearing' | 'advisory';
}

export interface ReplaceSectionOp {
op: 'REPLACE_SECTION';
key: string;
content: AdfContent;
}

export interface RemoveSectionOp {
op: 'REMOVE_SECTION';
key: string;
}

export interface UpdateMetricOp {
op: 'UPDATE_METRIC';
section: string;
key: string;
value: number;
}

export type PatchOperation =
| AddBulletOp
| ReplaceBulletOp
| RemoveBulletOp
| AddSectionOp
| ReplaceSectionOp
| RemoveSectionOp
| UpdateMetricOp;

// ============================================================================
// Manifest Types
// ============================================================================

export interface Manifest {
version: '0.1';
role?: string;
defaultLoad: string[];
onDemand: ManifestModule[];
rules: string[];
tokenBudget?: number;
sync: SyncEntry[];
cadence: CadenceEntry[];
metrics: MetricSource[];
}

export interface SyncEntry {
source: string;
target: string;
}

export interface ManifestModule {
path: string;
triggers: string[];
loadPolicy: 'DEFAULT' | 'ON_DEMAND';
tokenBudget?: number;
}

export interface CadenceEntry {
check: string;
frequency: string;
}

export interface MetricSource {
key: string;
path: string;
}

// ============================================================================
// Bundle Output
// ============================================================================

export interface BundleResult {
manifest: Manifest;
resolvedModules: string[];
mergedDocument: AdfDocument;
tokenEstimate: number;
tokenBudget: number | null;
tokenUtilization: number | null;
perModuleTokens: Record<string, number>;
moduleBudgetOverruns: Array<{
module: string;
tokens: number;
budget: number;
}>;
triggerMatches: Array<{
module: string;
trigger: string;
matched: boolean;
matchedKeywords: string[];
loadReason: 'default' | 'trigger';
}>;
unmatchedModules: string[];
advisoryOnlyModules: string[];
}

// ============================================================================
// Sync / Lockfile Types
// ============================================================================

/**
* .adf.lock file format: flat JSON map of source filename → sha256 prefix (16 hex chars).
* Generated by `charter adf sync --write`, checked by `charter adf sync --check`.
*/
export interface AdfLockfile {
[sourceFile: string]: string;
}

export interface AdfSyncStatus {
source: string;
sourceHash: string;
lockedHash: string | null;
inSync: boolean;
}

// ============================================================================
// Constraint Validation
// ============================================================================

export type ConstraintStatus = 'pass' | 'fail' | 'warn';

export interface ConstraintResult {
section: string;
metric: string;
value: number;
ceiling: number;
unit: string;
status: ConstraintStatus;
message: string;
source: 'metric' | 'context';
}

export interface WeightSummary {
loadBearing: number;
advisory: number;
unweighted: number;
total: number;
}

export interface EvidenceResult {
constraints: ConstraintResult[];
weightSummary: WeightSummary;
allPassing: boolean;
failCount: number;
warnCount: number;
}
// Backward-compatible barrel — all domain types re-exported.
export * from './types/index';
33 changes: 33 additions & 0 deletions packages/adf/src/types/ast.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
/**
* ADF AST Core — canonical document structure types.
*/

export interface AdfDocument {
version: '0.1';
sections: AdfSection[];
}

export interface AdfSection {
key: string;
decoration: string | null;
content: AdfContent;
weight?: 'load-bearing' | 'advisory';
}

export type AdfContent =
| { type: 'text'; value: string }
| { type: 'list'; items: string[] }
| { type: 'map'; entries: AdfMapEntry[] }
| { type: 'metric'; entries: AdfMetricEntry[] };

export interface AdfMapEntry {
key: string;
value: string;
}

export interface AdfMetricEntry {
key: string;
value: number;
ceiling: number;
unit: string;
}
30 changes: 30 additions & 0 deletions packages/adf/src/types/bundle.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
/**
* ADF Bundle Output — result shape from bundleModules().
*/

import type { AdfDocument } from './ast';
import type { Manifest } from './manifest';

export interface BundleResult {
manifest: Manifest;
resolvedModules: string[];
mergedDocument: AdfDocument;
tokenEstimate: number;
tokenBudget: number | null;
tokenUtilization: number | null;
perModuleTokens: Record<string, number>;
moduleBudgetOverruns: Array<{
module: string;
tokens: number;
budget: number;
}>;
triggerMatches: Array<{
module: string;
trigger: string;
matched: boolean;
matchedKeywords: string[];
loadReason: 'default' | 'trigger';
}>;
unmatchedModules: string[];
advisoryOnlyModules: string[];
}
41 changes: 41 additions & 0 deletions packages/adf/src/types/decorations.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
/**
* ADF Decorations — standard emoji decorations and canonical section ordering.
*/

export const STANDARD_DECORATIONS: Record<string, string> = {
TASK: '\u{1F3AF}',
ROLE: '\u{1F9D1}',
CONTEXT: '\u{1F4CB}',
OUTPUT: '\u{2705}',
CONSTRAINTS: '\u{26A0}\u{FE0F}',
RULES: '\u{1F4D0}',
DEFAULT_LOAD: '\u{1F4E6}',
ON_DEMAND: '\u{1F4C2}',
FILES: '\u{1F5C2}\u{FE0F}',
TOOLS: '\u{1F6E0}\u{FE0F}',
RISKS: '\u{1F6A8}',
STATE: '\u{1F9E0}',
BUDGET: '\u{1F4B0}',
SYNC: '\u{1F504}',
CADENCE: '\u{1F4CA}',
GUIDE: '\u{1F4D6}',
};

export const CANONICAL_KEY_ORDER: string[] = [
'TASK',
'ROLE',
'CONTEXT',
'OUTPUT',
'CONSTRAINTS',
'RULES',
'DEFAULT_LOAD',
'ON_DEMAND',
'BUDGET',
'SYNC',
'CADENCE',
'FILES',
'TOOLS',
'RISKS',
'STATE',
'GUIDE',
];
6 changes: 6 additions & 0 deletions packages/adf/src/types/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
export * from './ast';
export * from './decorations';
export * from './patch';
export * from './manifest';
export * from './bundle';
export * from './validation';
Loading