@okfit/cli 0.1.0 → 0.2.0

package/verify/locate.js

@@ -0,0 +1,249 @@
+import { Effect } from "effect";
+import { FrontmatterSource } from "@effected/markdown";
+import { YamlAlias, YamlDocument, YamlMap, YamlScalar, YamlSeq } from "@effected/yaml";
+
+//#region src/verify/locate.ts
+/**
+* Strip a leading BOM before anything else; the caller re-prepends `bom`
+* verbatim on write (V-15). `FrontmatterSource.split`'s own remarks require
+* this: "a leading BOM means offset 0 is not a fence — strip one before
+* calling" (`FrontmatterSource.ts:123`).
+*
+* @internal
+*/
+const stripBom = (source) => source.charCodeAt(0) === 65279 ? {
+	text: source.slice(1),
+	bom: ""
+} : {
+	text: source,
+	bom: ""
+};
+/** CRLF when the document's FIRST newline is CRLF, else LF (V-15). @internal */
+const detectNewline = (source) => {
+	const index = source.indexOf("\n");
+	return index > 0 && source.charCodeAt(index - 1) === 13 ? "\r\n" : "\n";
+};
+/**
+* The terminator the spliced fragment must use: `split`'s own fidelity
+* field for the opening fence's terminator when it is LF or CRLF, else
+* {@link detectNewline}. `FrontmatterNewline` also admits a lone `"\r"`,
+* which no fragment may emit, so that case falls through to the scan.
+*
+* @internal
+*/
+const documentNewline = (text) => {
+	const newline = FrontmatterSource.split(text).frontmatter?.newline;
+	if (newline === "\r\n") return "\r\n";
+	if (newline === "\n") return "\n";
+	return detectNewline(text);
+};
+/** The run of spaces ending at `offset`, or `""` when anything else precedes it on the line. @internal */
+const indentAt = (value, offset) => {
+	const lineStart = value.lastIndexOf("\n", offset - 1) + 1;
+	const prefix = value.slice(lineStart, offset);
+	return /^ *$/.test(prefix) ? prefix : "";
+};
+/**
+* True when `node`, or any mapping directly inside a sequence `node`,
+* carries a `<<` key. That is every level a legal `Verification.List` can
+* reach; anything deeper already fails to decode as a `Verification`
+* (contract §11 item 3).
+*/
+const hasMergeKey = (node) => {
+	if (node instanceof YamlMap) return node.items.some((pair) => pair.key instanceof YamlScalar && pair.key.value === "<<");
+	if (node instanceof YamlSeq) return node.items.some((item) => item instanceof YamlMap && hasMergeKey(item));
+	return false;
+};
+/**
+* Split `source`'s frontmatter, parse its value, find the top-level
+* `verified` pair, and classify it (contract §3.1). Fails only when the
+* frontmatter YAML is fatally unparseable — impossible for a concept that
+* reached `bundle.concepts`, but typed rather than assumed.
+*
+* Offset translation is `valueStart = 3 + newline.length` — `"---".length`
+* plus the opening fence's own terminator, taken from `split`'s fidelity
+* field rather than re-derived with `indexOf` (contract §12 note 9). Every
+* whole-file offset below is `valueStart + <yaml offset>`.
+*
+* @internal
+*/
+const locate = Effect.fn("okfit/verify/locate")(function* (source) {
+	const block = FrontmatterSource.split(source).frontmatter;
+	if (block === void 0) return {
+		_tag: "unsupported",
+		shape: "no-frontmatter"
+	};
+	const value = block.value;
+	const valueStart = 3 + (block.newline ?? "\n").length;
+	const contents = (yield* YamlDocument.parse(value)).contents;
+	if (!(contents instanceof YamlMap)) return {
+		_tag: "unsupported",
+		shape: "not-a-mapping"
+	};
+	const pair = contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === "verified");
+	if (pair === void 0) return {
+		_tag: "absent",
+		insertAt: valueStart + value.length
+	};
+	const key = pair.key;
+	const node = pair.value;
+	if (node === null) return {
+		_tag: "unsupported",
+		shape: "empty"
+	};
+	if (node instanceof YamlAlias) return {
+		_tag: "unsupported",
+		shape: "alias"
+	};
+	if (hasMergeKey(node)) return {
+		_tag: "unsupported",
+		shape: "merge-key"
+	};
+	if (node instanceof YamlScalar) return {
+		_tag: "unsupported",
+		shape: "scalar"
+	};
+	if (node instanceof YamlSeq) {
+		if (node.style === "flow") return {
+			_tag: "flowSeq",
+			insertAt: valueStart + node.offset + node.length - 1,
+			empty: node.items.length === 0
+		};
+		const last = node.items[node.items.length - 1];
+		if (last === void 0) return {
+			_tag: "unsupported",
+			shape: "empty"
+		};
+		const end = last.offset + last.length;
+		return {
+			_tag: "blockSeq",
+			insertAt: valueStart + end,
+			afterNewline: value[end - 1] === "\n",
+			indent: indentAt(value, node.offset),
+			lastItemStyle: last instanceof YamlMap && last.style === "flow" ? "flow" : "block"
+		};
+	}
+	if (node instanceof YamlMap) {
+		const start = valueStart + key.offset + key.length + 1;
+		const rawEnd = node.offset + node.length;
+		const raw = value.slice(node.offset, rawEnd);
+		const original = raw.replace(/(?:\r\n|\n|\r)$/, "");
+		return {
+			_tag: "bareMapping",
+			style: node.style === "flow" ? "flow" : "block",
+			start,
+			end: valueStart + rawEnd,
+			indent: `${indentAt(value, key.offset)}  `,
+			original,
+			endsWithNewline: original.length !== raw.length
+		};
+	}
+	return {
+		_tag: "unsupported",
+		shape: "not-a-mapping"
+	};
+});
+/**
+* Locate the `at` key inside a concept's top-level `generated` BLOCK
+* mapping. Callers MUST have already confirmed `generated` exists on the
+* decoded concept (`generated-missing`, S-3/design §3 rule 5, is the
+* caller's check against `concept.frontmatter.generated`, never this
+* function's) — matches how `locate` already re-parses independently of
+* whatever `Bundle.load` retained, for `verified`. The insert style is
+* one new newline-terminated line after the last key's line of the
+* mapping, at that mapping's indent, using the document newline (S-2,
+* confirmed as already correct in FW's own proposal — contract §14 note
+* 1 — with no correction needed against this file's `locate` precedent).
+*
+* @internal
+*/
+const locateGenerated = Effect.fn("okfit/verify/locateGenerated")(function* (source) {
+	const block = FrontmatterSource.split(source).frontmatter;
+	if (block === void 0) return {
+		_tag: "unsupported",
+		shape: "no-frontmatter"
+	};
+	const value = block.value;
+	const valueStart = 3 + (block.newline ?? "\n").length;
+	const contents = (yield* YamlDocument.parse(value)).contents;
+	if (!(contents instanceof YamlMap)) return {
+		_tag: "unsupported",
+		shape: "not-a-mapping"
+	};
+	const pair = contents.items.find((item) => item.key instanceof YamlScalar && item.key.value === "generated");
+	if (pair === void 0) return {
+		_tag: "unsupported",
+		shape: "no-generated-key"
+	};
+	const node = pair.value;
+	if (node === null) return {
+		_tag: "unsupported",
+		shape: "empty"
+	};
+	if (node instanceof YamlAlias) return {
+		_tag: "unsupported",
+		shape: "alias"
+	};
+	if (hasMergeKey(node)) return {
+		_tag: "unsupported",
+		shape: "merge-key"
+	};
+	if (node instanceof YamlScalar) return {
+		_tag: "unsupported",
+		shape: "scalar"
+	};
+	if (node instanceof YamlSeq) return {
+		_tag: "unsupported",
+		shape: "sequence"
+	};
+	if (!(node instanceof YamlMap)) return {
+		_tag: "unsupported",
+		shape: "not-a-mapping"
+	};
+	if (node.style === "flow") return {
+		_tag: "unsupported",
+		shape: "flow-mapping"
+	};
+	const indent = indentAt(value, node.offset);
+	const atPair = node.items.find((item) => item.key instanceof YamlScalar && item.key.value === "at");
+	if (atPair === void 0) {
+		const last = node.items[node.items.length - 1];
+		if (last === void 0) return {
+			_tag: "unsupported",
+			shape: "empty"
+		};
+		const lastEnd = last.value !== null ? last.value.offset + last.value.length : last.key.offset + last.key.length;
+		const nl = value.indexOf("\n", lastEnd);
+		return {
+			_tag: "insertAfterLastKey",
+			insertAt: valueStart + (nl === -1 ? value.length : nl + 1),
+			indent
+		};
+	}
+	const atValue = atPair.value;
+	if (atValue === null) return {
+		_tag: "unsupported",
+		shape: "at-empty"
+	};
+	if (atValue instanceof YamlAlias) return {
+		_tag: "unsupported",
+		shape: "alias"
+	};
+	if (!(atValue instanceof YamlScalar)) return {
+		_tag: "unsupported",
+		shape: "at-not-scalar"
+	};
+	if (atValue.style === "block-literal" || atValue.style === "block-folded") return {
+		_tag: "unsupported",
+		shape: "at-block-scalar"
+	};
+	return {
+		_tag: "replaceScalar",
+		start: valueStart + atValue.offset,
+		end: valueStart + atValue.offset + atValue.length,
+		quote: atValue.style
+	};
+});
+
+//#endregion
+export { detectNewline, documentNewline, indentAt, locate, locateGenerated, stripBom };

package/verify/run.js

@@ -0,0 +1,106 @@
+import { VerifyConceptNotFoundError, VerifyUnsupportedFrontmatterError } from "../errors.js";
+import { documentNewline, locate, stripBom } from "./locate.js";
+import { splice } from "./splice.js";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { Bundle, ConceptId, Timestamp } from "@okfit/core";
+import { Derivation } from "@okfit/profiles";
+import { MarkdownEdit } from "@effected/markdown";
+
+//#region src/verify/run.ts
+/**
+* The only four diagnostic codes that can co-occur with a MISSING
+* `concepts` entry (V-9, contract §12 note 10): `Bundle.ts:143/164/175/186`
+* emit the three frontmatter codes and return without a concept, and
+* `internal/frontmatter.ts:73` emits `type-missing` for `decodeConcept`'s
+* only failure branch. Every other code — `family-invalid`,
+* `computation-runtime-missing`, `legacy-timestamp` — is pushed as an issue
+* while `decodeConcept` still returns a concept, so the concept IS in the
+* map (`internal/conceptDecode.ts:84-134`).
+*/
+const UNDECODABLE_CODES = /* @__PURE__ */ new Set([
+	"frontmatter-unparseable",
+	"frontmatter-unclosed",
+	"frontmatter-missing",
+	"type-missing"
+]);
+/**
+* Contract §2.3 steps 6–15. Loads the bundle, resolves the id, resolves the
+* human actor from git, splices exactly one entry into the concept's
+* frontmatter and writes it back atomically.
+*
+* Nothing here reads `status`, `stale_after`, or a type's
+* `require_verified`: `verify` is mechanical, not config-aware (V-4, V-5).
+*
+* @internal
+*/
+const runVerify = Effect.fn("okfit/verify/runVerify")(function* (options) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const bundle = yield* Bundle.load({ root: options.bundleRoot });
+	const normalized = ConceptId.normalize(options.id);
+	if (Option.isNone(normalized)) return yield* new VerifyConceptNotFoundError({
+		id: options.id,
+		root: bundle.root,
+		reason: "not-a-concept"
+	});
+	const id = normalized.value;
+	const conceptFile = ConceptId.toPath(id);
+	if (ConceptId.isReservedFile(conceptFile)) return yield* new VerifyConceptNotFoundError({
+		id,
+		root: bundle.root,
+		reason: "reserved"
+	});
+	const concept = bundle.concepts.get(id);
+	if (concept === void 0) {
+		const diagnostic = bundle.diagnostics.find((entry) => entry.file === conceptFile && UNDECODABLE_CODES.has(entry.code));
+		return yield* new VerifyConceptNotFoundError({
+			id,
+			root: bundle.root,
+			...diagnostic === void 0 ? { reason: "not-a-concept" } : {
+				reason: "undecodable",
+				diagnosticCode: diagnostic.code
+			}
+		});
+	}
+	const actor = yield* Derivation.generatedBy({
+		writer: "human",
+		cwd: options.projectRoot,
+		config: options.config
+	});
+	const absolutePath = path.join(bundle.root, concept.path);
+	const source = yield* fs.readFileString(absolutePath);
+	const { text, bom } = stripBom(source);
+	const located = yield* locate(text);
+	if (located._tag === "unsupported") return yield* new VerifyUnsupportedFrontmatterError({
+		id,
+		shape: located.shape
+	});
+	const at = Schema.encodeSync(Timestamp)(options.at);
+	const priorAt = (concept.frontmatter.verified ?? []).filter((entry) => entry.by === actor).map((entry) => Schema.encodeSync(Timestamp)(entry.at));
+	const edit = splice(located, {
+		by: actor,
+		at
+	}, documentNewline(text));
+	const finalText = bom + MarkdownEdit.applyAll(text, [edit]);
+	if (!options.dryRun) {
+		const target = yield* fs.realPath(absolutePath);
+		const tempPath = `${target}.okfit-verify.tmp`;
+		const original = yield* fs.stat(target);
+		yield* fs.writeFileString(tempPath, finalText);
+		yield* fs.chmod(tempPath, original.mode);
+		yield* fs.rename(tempPath, target).pipe(Effect.onError(() => fs.remove(tempPath, { force: true }).pipe(Effect.ignore)));
+	}
+	return {
+		id,
+		bundleRoot: bundle.root,
+		conceptPath: concept.path,
+		by: actor,
+		at,
+		priorAt,
+		dryRun: options.dryRun,
+		fragment: edit.content
+	};
+});
+
+//#endregion
+export { runVerify };

package/verify/splice.js

@@ -0,0 +1,75 @@
+import { MarkdownEdit } from "@effected/markdown";
+
+//#region src/verify/splice.ts
+/** Prefix two spaces to every line but the first, joining with `newline` (V-13). */
+const reindent = (original, newline) => original.split(/\r\n|\n|\r/).map((line, index) => index === 0 ? line : `  ${line}`).join(newline);
+/**
+* Build the one edit for `target` (contract §3.2). Never calls a YAML
+* stringifier: the only syntax emitted is `- `, `{`, `}`, `: `, `,`,
+* spaces and `newline`.
+*
+* @internal
+*/
+const splice = (target, entry, newline) => {
+	const flow = `{ by: ${entry.by}, at: ${entry.at} }`;
+	const block = (indent) => `${indent}- by: ${entry.by}${newline}${indent}  at: ${entry.at}`;
+	switch (target._tag) {
+		case "absent": return MarkdownEdit.make({
+			offset: target.insertAt,
+			length: 0,
+			content: `verified:${newline}  - by: ${entry.by}${newline}    at: ${entry.at}${newline}`
+		});
+		case "blockSeq": {
+			const fragment = target.lastItemStyle === "flow" ? `${target.indent}- ${flow}` : block(target.indent);
+			return MarkdownEdit.make({
+				offset: target.insertAt,
+				length: 0,
+				content: target.afterNewline ? `${fragment}${newline}` : `${newline}${fragment}`
+			});
+		}
+		case "flowSeq": return MarkdownEdit.make({
+			offset: target.insertAt,
+			length: 0,
+			content: target.empty ? flow : `, ${flow}`
+		});
+		case "bareMapping": return target.style === "flow" ? MarkdownEdit.make({
+			offset: target.start,
+			length: target.end - target.start,
+			content: `${newline}${target.indent}- ${target.original}${newline}${target.indent}- ${flow}`
+		}) : MarkdownEdit.make({
+			offset: target.start,
+			length: target.end - target.start,
+			content: `${newline}${target.indent}- ${reindent(target.original, newline)}${newline}${block(target.indent)}${newline}`
+		});
+	}
+};
+/**
+* Build the one edit for `target` (contract §6.1). Never calls a YAML
+* stringifier: the only syntax emitted is the indent, `at: `, the
+* preserved quote character (if any), and `newline`. `encodedAt` is
+* already `Schema.encodeSync(Timestamp)`'d by the caller (S-1: splice,
+* never `YamlFormat.modify` — it drops quote style and re-normalises line
+* endings, V-12/V-15 violations `sync/generated.ts` cannot afford).
+*
+* @internal
+*/
+const spliceGenerated = (target, encodedAt, newline) => {
+	switch (target._tag) {
+		case "insertAfterLastKey": return MarkdownEdit.make({
+			offset: target.insertAt,
+			length: 0,
+			content: `${target.indent}at: ${encodedAt}${newline}`
+		});
+		case "replaceScalar": {
+			const quoted = target.quote === "single-quoted" ? `'${encodedAt}'` : target.quote === "double-quoted" ? `"${encodedAt}"` : encodedAt;
+			return MarkdownEdit.make({
+				offset: target.start,
+				length: target.end - target.start,
+				content: quoted
+			});
+		}
+	}
+};
+
+//#endregion
+export { splice, spliceGenerated };

package/version.js

@@ -0,0 +1,14 @@
+import { version } from "./package.js";
+
+//#region src/version.ts
+/**
+* The version string reported by `okfit --version`, read from the package's
+* own manifest (K-32) so a release can never desync from the printed
+* version. Consumed by `bin.ts` only.
+*
+* @public
+*/
+const CLI_VERSION = version;
+
+//#endregion
+export { CLI_VERSION };