@flowdular/sdk 0.1.0 → 0.2.0

package/packages/sandbox/src/server/delivery/plan.ts

@@ -1,218 +0,0 @@
-import { join, relative } from 'node:path';
-import {
-	basePathOf,
-	modulePathOf,
-	sessionPaths,
-	type SessionModule,
-} from '../sessions.ts';
-import {
-	diffSpecs,
-	isSpecApproved,
-	parseModuleSpec,
-	readSpecText,
-	SPEC_FILE,
-} from '../spec.ts';
-import { SandboxSetupError } from '../workspace-root.ts';
-import { newPackages, planModuleFiles } from './steps.ts';
-import type { DeliveryContext, DeliveryModulePlan } from './types.ts';
-
-export const GATES = [
-	'spec-schema',
-	'module-schema',
-	'dependencies',
-	'typecheck',
-	'tests',
-	'format',
-	'auto-review',
-] as const;
-
-const NUMBERED_MIGRATION = /^migrations\/\d{4}_[^/]+\.(?:up|down)\.sql$/;
-
-function assertExistingMigrationsUnchanged(
-	module: SessionModule,
-	overwrites: readonly string[],
-	removes: readonly string[],
-): void {
-	const changed = [...overwrites, ...removes].filter((file) =>
-		NUMBERED_MIGRATION.test(file),
-	);
-	if (changed.length === 0) return;
-	throw new SandboxSetupError(
-		'EJECT_MIGRATION_IMMUTABLE',
-		`${module.id} changes an existing migration (${changed.join(', ')}). Restore the original bytes and add a new numbered migration instead.`,
-	);
-}
-
-export function assertEjectCapability(context: DeliveryContext): void {
-	if (!context.capabilities.includes('sandbox.modules.eject')) {
-		throw new SandboxSetupError(
-			'EJECT_SCOPE_MISSING',
-			'The sandbox grant does not include sandbox.modules.eject.',
-		);
-	}
-}
-
-/* A change that landed without a specification behind it is how a module and
-   its contract drift apart. Before an edited module is delivered its
-   specification has to cover the change: the version moves, and at least one
-   acceptance scenario is new or different. A module whose base copy carries no
-   specification has nothing to compare, so it is left alone. */
-async function assertSpecCoversChange(
-	module: SessionModule,
-	sourcePath: string,
-	basePath: string,
-	changedFiles: number,
-): Promise<void> {
-	const specPath = `modules/${module.directory}/${SPEC_FILE}`;
-	const baseText = await readSpecText(basePath);
-	if (baseText === null) return;
-	const draftText = await readSpecText(sourcePath);
-	if (draftText === null) {
-		throw new SandboxSetupError(
-			'EJECT_SPEC_MISSING',
-			`${module.id} changed, but ${specPath} is gone from the session. Restore it before delivering.`,
-		);
-	}
-	const changes = diffSpecs(
-		parseModuleSpec(baseText),
-		parseModuleSpec(draftText),
-	);
-	const reasons: string[] = [];
-	if (!changes.some((change) => change.field === 'specVersion')) {
-		reasons.push(
-			`specVersion is unchanged (bump it: patch for a fix, minor for an endpoint, table, column, screen, widget or permission)`,
-		);
-	}
-	if (
-		!changes.some(
-			(change) =>
-				change.field === 'acceptanceScenarios' && change.kind !== 'removed',
-		)
-	) {
-		reasons.push(
-			'no acceptance scenario was added or changed (state the new behaviour as given, when, then)',
-		);
-	}
-	if (reasons.length === 0) return;
-	throw new SandboxSetupError(
-		reasons[0]!.startsWith('specVersion')
-			? 'EJECT_SPEC_VERSION_UNCHANGED'
-			: 'EJECT_SPEC_SCENARIOS_UNCHANGED',
-		`${module.id} changed ${changedFiles} ${
-			changedFiles === 1 ? 'file' : 'files'
-		}, but ${specPath} does not cover the change: ${reasons.join(
-			', and ',
-		)}. Ask the business manager for the delta, approve it, then deliver again.`,
-	);
-}
-
-/* Delivery repeats the turn gate. A plan can be opened hours after a turn, and
-   both local eject and the pull-request target use this function, so this is
-   the last shared boundary before either target writes or pushes anything. */
-async function assertSpecApproved(
-	module: SessionModule,
-	sourcePath: string,
-): Promise<void> {
-	const text = await readSpecText(sourcePath);
-	const specPath = `modules/${module.directory}/${SPEC_FILE}`;
-	if (text === null) {
-		throw new SandboxSetupError(
-			'EJECT_SPEC_MISSING',
-			`${module.id} has no ${specPath} to approve before delivery.`,
-		);
-	}
-	if (!isSpecApproved(module, text)) {
-		throw new SandboxSetupError(
-			'EJECT_SPEC_NOT_APPROVED',
-			`${module.id} has a draft or stale specification. Review and approve the current ${specPath} before delivery.`,
-		);
-	}
-}
-
-/* What every module of the session changes in modules/ of this workspace. Both
-   targets start from this; only where the files go differs. */
-export async function planSessionModules(
-	context: DeliveryContext,
-): Promise<readonly DeliveryModulePlan[]> {
-	const paths = sessionPaths(
-		context.workspaceRoot,
-		context.session.id,
-		context.session.moduleSuffix,
-	);
-	const modules: DeliveryModulePlan[] = [];
-	for (const module of context.session.modules) {
-		const sourcePath = modulePathOf(paths, module.directory);
-		const targetPath = join(context.workspaceRoot, 'modules', module.directory);
-		await assertSpecApproved(module, sourcePath);
-		const changes = await planModuleFiles(
-			sourcePath,
-			targetPath,
-			module.kind === 'edit' ? basePathOf(paths, module.directory) : null,
-		);
-		if (changes.files.length === 0) {
-			throw new SandboxSetupError(
-				'EJECT_EMPTY',
-				`The session workspace holds no files for ${module.id} yet.`,
-			);
-		}
-		assertExistingMigrationsUnchanged(
-			module,
-			changes.overwrites,
-			changes.removes,
-		);
-		const changedFiles =
-			changes.additions.length +
-			changes.overwrites.length +
-			changes.removes.length;
-		if (module.kind === 'edit' && changedFiles > 0) {
-			await assertSpecCoversChange(
-				module,
-				sourcePath,
-				basePathOf(paths, module.directory),
-				changedFiles,
-			);
-		}
-		modules.push({
-			id: module.id,
-			directory: module.directory,
-			kind: module.kind,
-			targetPath: relative(context.workspaceRoot, targetPath),
-			...changes,
-			newPackages: await newPackages(
-				context.workspaceRoot,
-				sourcePath,
-				targetPath,
-			),
-			enable: module.kind === 'new',
-		});
-	}
-	return modules;
-}
-
-/* Every draft file plus every removal, as the workspace target reports it. */
-export function countDeliveredFiles(
-	modules: readonly DeliveryModulePlan[],
-): number {
-	return modules.reduce(
-		(total, module) =>
-			total +
-			module.files.filter((file) => !module.overwrites.includes(file)).length +
-			module.overwrites.length +
-			module.removes.length,
-		0,
-	);
-}
-
-/* Only what differs from the target: new files, changed files, removals. */
-export function countChangedFiles(
-	modules: readonly DeliveryModulePlan[],
-): number {
-	return modules.reduce(
-		(total, module) =>
-			total +
-			module.additions.length +
-			module.overwrites.length +
-			module.removes.length,
-		0,
-	);
-}

package/packages/sandbox/src/server/delivery/policies.ts

@@ -1,239 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import type { DeliveryBudget } from './types.ts';
-
-export type PolicyValue =
-	| string
-	| number
-	| boolean
-	| null
-	| readonly string[]
-	| PolicyMap;
-
-export interface PolicyMap {
-	readonly [key: string]: PolicyValue;
-}
-
-interface Line {
-	readonly indent: number;
-	readonly text: string;
-}
-
-function scalar(raw: string): PolicyValue {
-	const value = raw.trim();
-	if (value === '') return null;
-	if (value === 'true') return true;
-	if (value === 'false') return false;
-	if (/^-?\d+(\.\d+)?$/.test(value)) return Number(value);
-	if (value.startsWith('[') && value.endsWith(']')) {
-		return value
-			.slice(1, -1)
-			.split(',')
-			.map((item) => unquote(item.trim()))
-			.filter((item) => item !== '');
-	}
-	return unquote(value);
-}
-
-function unquote(value: string): string {
-	if (
-		(value.startsWith('"') && value.endsWith('"')) ||
-		(value.startsWith("'") && value.endsWith("'"))
-	) {
-		return value.slice(1, -1);
-	}
-	return value;
-}
-
-function stripComment(line: string): string {
-	const hash = line.search(/(^|\s)#/);
-	return hash < 0 ? line : line.slice(0, hash);
-}
-
-function splitKey(text: string): { key: string; rest: string } | null {
-	if (text.endsWith(':')) return { key: text.slice(0, -1).trim(), rest: '' };
-	const separator = text.indexOf(': ');
-	if (separator < 0) return null;
-	return {
-		key: text.slice(0, separator).trim(),
-		rest: text.slice(separator + 2).trim(),
-	};
-}
-
-/* Reads the subset of YAML the policy files use: nested mappings, scalars,
-   flow sequences (also one that continues on the next lines), and block
-   sequences of scalars. Anchors, multi-line strings, and nested sequences are
-   out of scope; the files are reviewed by hand and stay this simple. */
-export function parsePolicyYaml(text: string): PolicyMap {
-	const lines: Line[] = [];
-	for (const raw of text.split('\n')) {
-		const stripped = stripComment(raw).replace(/\s+$/, '');
-		if (stripped.trim() === '') continue;
-		lines.push({
-			indent: stripped.length - stripped.trimStart().length,
-			text: stripped.trim(),
-		});
-	}
-	let index = 0;
-
-	function readMap(indent: number): PolicyMap {
-		const map: Record<string, PolicyValue> = {};
-		while (index < lines.length) {
-			const line = lines[index]!;
-			if (line.indent < indent) break;
-			if (line.indent > indent || line.text.startsWith('- ')) {
-				index += 1;
-				continue;
-			}
-			const entry = splitKey(line.text);
-			index += 1;
-			if (!entry) continue;
-			if (entry.rest !== '') {
-				map[entry.key] = readFlow(entry.rest);
-				continue;
-			}
-			const next = lines[index];
-			if (!next || next.indent <= indent) {
-				map[entry.key] = null;
-			} else if (next.text.startsWith('- ')) {
-				map[entry.key] = readSequence(next.indent);
-			} else if (next.text.startsWith('[')) {
-				index += 1;
-				map[entry.key] = readFlow(next.text);
-			} else {
-				map[entry.key] = readMap(next.indent);
-			}
-		}
-		return map;
-	}
-
-	function readFlow(start: string): PolicyValue {
-		let value = start;
-		while (
-			value.startsWith('[') &&
-			!value.endsWith(']') &&
-			index < lines.length
-		) {
-			value = `${value} ${lines[index]!.text}`;
-			index += 1;
-		}
-		return scalar(value);
-	}
-
-	function readSequence(indent: number): readonly string[] {
-		const items: string[] = [];
-		while (index < lines.length) {
-			const line = lines[index]!;
-			if (line.indent !== indent || !line.text.startsWith('- ')) break;
-			items.push(unquote(line.text.slice(2).trim()));
-			index += 1;
-		}
-		return items;
-	}
-
-	return readMap(lines[0]?.indent ?? 0);
-}
-
-async function readPolicy(root: string, file: string): Promise<PolicyMap> {
-	try {
-		return parsePolicyYaml(
-			await readFile(join(root, '.ai', 'policies', file), 'utf8'),
-		);
-	} catch {
-		return {};
-	}
-}
-
-function asMap(value: PolicyValue | undefined): PolicyMap {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
-		? (value as PolicyMap)
-		: {};
-}
-
-function asInteger(value: PolicyValue | undefined): number | undefined {
-	return typeof value === 'number' && Number.isInteger(value) && value >= 0
-		? value
-		: undefined;
-}
-
-export interface PathOwner {
-	readonly pattern: string;
-	readonly owner: string;
-}
-
-export interface PathOwnership {
-	/* In file order; the first matching pattern answers for a path. */
-	readonly owners: readonly PathOwner[];
-	readonly requireReviewer: boolean;
-}
-
-export async function loadPathOwnership(root: string): Promise<PathOwnership> {
-	const policy = await readPolicy(root, 'path-ownership.yaml');
-	const owners: PathOwner[] = [];
-	for (const [pattern, owner] of Object.entries(asMap(policy.owners))) {
-		if (typeof owner === 'string') owners.push({ pattern, owner });
-	}
-	return {
-		owners,
-		requireReviewer: asMap(policy.crossOwnerChanges).requireReviewer === true,
-	};
-}
-
-export interface TaskBudgets {
-	readonly defaults: Partial<DeliveryBudget>;
-	readonly overrides: Readonly<Record<string, Partial<DeliveryBudget>>>;
-}
-
-function budgetOf(value: PolicyValue | undefined): Partial<DeliveryBudget> {
-	const map = asMap(value);
-	const maxChangedFiles = asInteger(map.maxChangedFiles);
-	const maxNewDependencies = asInteger(map.maxNewDependencies);
-	return {
-		...(maxChangedFiles !== undefined ? { maxChangedFiles } : {}),
-		...(maxNewDependencies !== undefined ? { maxNewDependencies } : {}),
-	};
-}
-
-export async function loadTaskBudgets(root: string): Promise<TaskBudgets> {
-	const policy = await readPolicy(root, 'task-budgets.yaml');
-	const overrides: Record<string, Partial<DeliveryBudget>> = {};
-	for (const [kind, value] of Object.entries(asMap(policy.overrides))) {
-		overrides[kind] = budgetOf(value);
-	}
-	return { defaults: budgetOf(policy.defaults), overrides };
-}
-
-const patternCache = new Map<string, RegExp>();
-
-/* Globs as the policy files write them: `**` spans directories, `*` stays in
-   one segment, `{module}` binds one segment. */
-function patternRegExp(pattern: string): RegExp {
-	let regExp = patternCache.get(pattern);
-	if (regExp) return regExp;
-	const source = pattern
-		.split(/(\*\*|\*|\{module\})/)
-		.map((part) => {
-			if (part === '**') return '.*';
-			if (part === '*') return '[^/]*';
-			if (part === '{module}') return '([^/]+)';
-			return part.replace(/[.+?^$()|[\]\\]/g, '\\$&');
-		})
-		.join('');
-	regExp = new RegExp(`^${source}$`);
-	if (patternCache.size >= 256) patternCache.clear();
-	patternCache.set(pattern, regExp);
-	return regExp;
-}
-
-export function matchesPath(path: string, pattern: string): boolean {
-	return patternRegExp(pattern).test(path);
-}
-
-export function ownerOf(path: string, ownership: PathOwnership): string | null {
-	for (const { pattern, owner } of ownership.owners) {
-		const match = patternRegExp(pattern).exec(path);
-		if (!match) continue;
-		return match[1] ? owner.replace('{module}', match[1]) : owner;
-	}
-	return null;
-}

package/packages/sandbox/src/server/delivery/record.ts

@@ -1,41 +0,0 @@
-import { readFile, rename, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import type { EjectTarget } from './types.ts';
-
-/* What a delivery left behind that the session record does not carry: the
-   branch and the pull request, so a session can be reopened to its review. */
-export interface DeliveryRecord {
-	readonly target: EjectTarget;
-	readonly deliveredAt: number;
-	readonly modules: readonly string[];
-	readonly branch: string | null;
-	readonly pullRequestUrl: string | null;
-	readonly compareUrl: string | null;
-}
-
-function recordPath(sessionRoot: string): string {
-	return join(sessionRoot, 'delivery.json');
-}
-
-export async function writeDeliveryRecord(
-	sessionRoot: string,
-	record: DeliveryRecord,
-): Promise<DeliveryRecord> {
-	const path = recordPath(sessionRoot);
-	const staging = `${path}.${process.pid}`;
-	await writeFile(staging, `${JSON.stringify(record, null, '\t')}\n`, 'utf8');
-	await rename(staging, path);
-	return record;
-}
-
-export async function readDeliveryRecord(
-	sessionRoot: string,
-): Promise<DeliveryRecord | null> {
-	try {
-		return JSON.parse(
-			await readFile(recordPath(sessionRoot), 'utf8'),
-		) as DeliveryRecord;
-	} catch {
-		return null;
-	}
-}