@okfit/cli 0.2.0 → 0.4.0

package/init/scaffold.js

@@ -1,174 +0,0 @@
-import { Effect, Option, Schema } from "effect";
-import { Concept, ConceptId, Derive, LoadedConcept, OKF_SPEC_VERSION } from "@okfit/core";
-import { MarkdownDocument, MarkdownFrontmatter, MarkdownParseOptions, YamlFrontmatter } from "@effected/markdown";
-
-//#region src/init/scaffold.ts
-/** `.config/okfit.toml`, relative to the project root (C-10). @public */
-const CONFIG_RELATIVE_PATH = ".config/okfit.toml";
-/**
-* C-1's three project-level names, in precedence order. `init` refuses when
-* ANY of them already exists in the target directory (C-9), so a fresh
-* `okfit init` beside a hand-written `.okfit.toml` cannot silently write a
-* second config the discovery order then shadows.
-*
-* Scope is `projectRoot` only, never the upward chain: an ancestor's config
-* is a legitimate discovery hit, not a collision.
-*
-* @public
-*/
-const PROJECT_CONFIG_NAMES = [
-	".okfit.toml",
-	"okfit.toml",
-	".config/okfit.toml"
-];
-/** C-22's directive, plus the blank line Tombi requires. @public */
-const SCHEMA_DIRECTIVE = "#:schema https://raw.githubusercontent.com/spencerbeggs/okfit/main/schemas/config/okfit-1.0.0.json\n\n";
-/**
-* K-23: the THIN override only — never the merged config. `bundle.path` is
-* the bundle root relative to the project root; `extensions: {}` satisfies
-* `OkfitConfig`'s one non-optional field (`CORE/OkfitConfig.ts:164`).
-* Everything else resolves from `DEFAULTS` and the profile at load time.
-* `actors.agent` is deliberately absent (K-24, P-17).
-*
-* @public
-*/
-const configValue = (options) => ({
-	bundle: {
-		path: options.bundlePath,
-		profile: options.profileName
-	},
-	extensions: {}
-});
-/**
-* Every path `init` will create, absolute, in write order, for the K-28
-* pre-flight: the three project-level config names, the bundle root's
-* `index.md`/`log.md`/`project.md`, then one `index.md` per layout directory
-* in `layout`'s own declared order — never re-sorted here. `Derive.renderIndex`
-* sorts its own `Subdirectories` section independently (C13), so this
-* function's order has no bearing on the rendered index text.
-*
-* @public
-*/
-const targetPaths = (options) => [
-	...PROJECT_CONFIG_NAMES.map((name) => `${options.projectRoot}/${name}`),
-	`${options.bundleRoot}/${options.layout.root.index}`,
-	`${options.bundleRoot}/${options.layout.root.log}`,
-	`${options.bundleRoot}/${options.layout.root.project}`,
-	...options.layout.directories.map((directory) => `${options.bundleRoot}/${directory.directory}/${options.layout.root.index}`)
-];
-/** Frontmatter capture on — the write seam's own precondition (`MD/index.d.ts:1907-1920`; `CORE/internal/reserved.ts:15` precedent). */
-const PARSE_OPTIONS = MarkdownParseOptions.make({ frontmatter: true });
-/**
-* The four keys `project.md` actually carries (contract section 3.4's
-* worked transcript) — deliberately NOT the full `Concept` class. `Concept`'s
-* `extensions` and `raw` fields are required, not `optionalKey`
-* (`CORE/Concept.ts:39-40`), so encoding a `Concept.make` value through
-* `Concept` itself would serialize `extensions: {}` and `raw: {}` into the
-* frontmatter block too (verified: `Schema.encodeSync(Concept)` against a
-* `Concept.make` value with empty `extensions`/`raw` includes both keys,
-* this session). `Bundle.load` re-decodes a file written with this narrower
-* schema exactly as it would one written with the full class —
-* `internal/conceptDecode.ts` derives `extensions`/`raw` from whatever keys
-* the frontmatter block actually carries, never from what wrote it (verified
-* with a `Bundle.load` round trip, this session) — so the narrower schema
-* costs nothing at read time and matches the transcript byte-for-byte.
-*/
-const ProjectFrontmatter = Schema.Struct({
-	type: Schema.Literal("Project"),
-	title: Schema.String,
-	description: Schema.String,
-	status: Schema.Literals([
-		"draft",
-		"stable",
-		"deprecated"
-	])
-});
-const PROJECT_DESCRIPTION = "What this project is, its boundaries, and its non-goals.";
-const capitalize = (name) => `${name.charAt(0).toUpperCase()}${name.slice(1)}`;
-const projectBody = (title) => [
-	`# ${title}`,
-	"",
-	"## Purpose",
-	"",
-	"Describe what this project is for in one paragraph.",
-	"",
-	"## Boundaries",
-	"",
-	"Describe what this project owns and what it deliberately leaves to others.",
-	"",
-	"## Non-goals",
-	"",
-	"List what this project will not do, so a reader never infers it from silence.",
-	""
-].join("\n");
-/**
-* The three root markdown files and the per-directory indexes (K-25 to
-* K-27, K-59). `project.md`'s frontmatter is written with
-* `MarkdownFrontmatter.setToString` — the INSERT path, since the body below
-* carries no frontmatter block of its own (`MD/index.d.ts:1959`,
-* `FrontmatterWriteError`'s own doc comment: "a document with no frontmatter
-* capture is the insert path, not an error"). The root `index.md` is
-* `Derive.renderIndex` over a `LoadedConcept` this function synthesizes from
-* the just-rendered `project.md` text, re-parsed with `MarkdownDocument.parse`
-* (K-59; `renderIndex` reads only `frontmatter.type`/`title`/`description`
-* and `path`, never `document`, `CORE/Derive.ts:75-101`, so the synthesized
-* value is faithful). Each per-directory `index.md` is the literal
-* `# <Directory>` — NOT `Derive.renderIndex`, which returns the empty string
-* for an empty concept list with no options (contract Judge notes item 2).
-*
-* @public
-*/
-const files = (options) => Effect.gen(function* () {
-	const { bundleRoot, layout, profileName, projectTitle, today } = options;
-	const frontmatterData = {
-		type: "Project",
-		title: projectTitle,
-		description: PROJECT_DESCRIPTION,
-		status: "draft"
-	};
-	const draftDocument = yield* MarkdownDocument.parse(projectBody(projectTitle), PARSE_OPTIONS);
-	const projectText = yield* MarkdownFrontmatter.setToString(ProjectFrontmatter, YamlFrontmatter)(draftDocument, frontmatterData);
-	const projectDocument = yield* MarkdownDocument.parse(projectText, PARSE_OPTIONS);
-	const projectConcept = LoadedConcept.make({
-		id: Option.getOrThrow(ConceptId.fromPath("project.md")),
-		path: "project.md",
-		frontmatter: Concept.make({
-			...frontmatterData,
-			extensions: {},
-			raw: frontmatterData
-		}),
-		document: projectDocument,
-		computationBody: Option.none()
-	});
-	const subdirectories = layout.directories.map((directory) => directory.directory);
-	const rootIndexText = Derive.renderIndex("", [projectConcept], {
-		okfVersion: OKF_SPEC_VERSION,
-		subdirectories
-	});
-	const logText = Derive.renderLogEntry({
-		date: today,
-		items: [`Initialized the bundle with the ${profileName} profile`]
-	});
-	const directoryFiles = layout.directories.map((directory) => ({
-		path: `${bundleRoot}/${directory.directory}/${layout.root.index}`,
-		contents: `# ${capitalize(directory.directory)}\n`
-	}));
-	return [
-		{
-			path: `${bundleRoot}/${layout.root.index}`,
-			contents: rootIndexText
-		},
-		{
-			path: `${bundleRoot}/${layout.root.log}`,
-			contents: logText
-		},
-		{
-			path: `${bundleRoot}/${layout.root.project}`,
-			contents: projectText
-		},
-		...directoryFiles
-	];
-});
-
-//#endregion
-export { CONFIG_RELATIVE_PATH, PROJECT_CONFIG_NAMES, SCHEMA_DIRECTIVE, configValue, files, targetPaths };

package/package.js

@@ -1,5 +0,0 @@
-//#region package.json
-var version = "0.2.0";
-
-//#endregion
-export { version };

package/render/exit.js

@@ -1,53 +0,0 @@
-//#region src/render/exit.ts
-/**
-* One pass over the collected diagnostics. `core.conformance` entries are
-* always severity `error` (D-33); the counts are still taken from `severity`
-* so a future non-error conformance code cannot silently change the exit
-* code.
-*
-* @public
-*/
-const tally = (diagnostics) => {
-	let conformanceErrors = 0;
-	let lintErrors = 0;
-	let lintWarnings = 0;
-	let lintInfo = 0;
-	let profileErrors = 0;
-	for (const d of diagnostics) {
-		if (d.source === "core.conformance") {
-			if (d.severity === "error") conformanceErrors++;
-			continue;
-		}
-		if (d.source === "core.lint") {
-			if (d.severity === "error") lintErrors++;
-			else if (d.severity === "warning") lintWarnings++;
-			else lintInfo++;
-			continue;
-		}
-		if (d.severity === "error") profileErrors++;
-	}
-	return {
-		conformanceErrors,
-		lintErrors,
-		lintWarnings,
-		lintInfo,
-		profileErrors
-	};
-};
-/**
-* K-7/K-8's two lowest tiers: `2` when any conformance error is present, else
-* `1` when any lint OR profile error is present, else `0`. Warnings and info
-* never move it. `130`, `64` and `3` are set elsewhere — by the runtime's
-* interrupt branch, by the `ShowHelp` remap in `bin.ts`, and by the typed
-* errors' own `[Runtime.errorExitCode]` — so this function returns only
-* `0 | 1 | 2`.
-*
-* @public
-*/
-const forDiagnostics = (diagnostics) => {
-	const t = tally(diagnostics);
-	return t.conformanceErrors > 0 ? 2 : t.lintErrors + t.profileErrors > 0 ? 1 : 0;
-};
-
-//#endregion
-export { forDiagnostics, tally };

package/render/json.js

@@ -1,126 +0,0 @@
-import { tally } from "./exit.js";
-import { sort } from "./sort.js";
-import { Schema } from "effect";
-import { DiagnosticRange, DiagnosticSeverity } from "@okfit/core";
-
-//#region src/render/json.ts
-/** One entry of the `diagnostics` array (K-21). @public */
-const JsonDiagnostic = Schema.Struct({
-	source: Schema.Literals([
-		"core.conformance",
-		"core.lint",
-		"profile"
-	]),
-	file: Schema.String,
-	code: Schema.String,
-	severity: DiagnosticSeverity,
-	message: Schema.String,
-	range: Schema.optionalKey(DiagnosticRange)
-});
-/** @public */
-const JsonSummary = Schema.Struct({
-	conformance_errors: Schema.Number,
-	lint_errors: Schema.Number,
-	lint_warnings: Schema.Number,
-	lint_info: Schema.Number,
-	profile_errors: Schema.Number,
-	concepts: Schema.Number
-});
-/**
-* K-21's success envelope, snake_case. `exit_code` is `0 | 1 | 2` only: an
-* infrastructure failure never produces this envelope, it produces the
-* `JsonErrorEnvelope` (K-22).
-*
-* @public
-*/
-const JsonEnvelope = Schema.Struct({
-	schema: Schema.Literal(1),
-	okfit_version: Schema.String,
-	okf_version: Schema.String,
-	root: Schema.String,
-	profile: Schema.NullOr(Schema.String),
-	exit_code: Schema.Literals([
-		0,
-		1,
-		2
-	]),
-	summary: JsonSummary,
-	diagnostics: Schema.Array(JsonDiagnostic)
-});
-/** K-22's envelope: the ONLY thing stdout carries under `--format json` on an exit-3 failure. @public */
-const JsonErrorEnvelope = Schema.Struct({
-	schema: Schema.Literal(1),
-	okfit_version: Schema.String,
-	exit_code: Schema.Literal(3),
-	error: Schema.Struct({
-		tag: Schema.String,
-		message: Schema.String
-	})
-});
-const toJsonDiagnostic = (d) => ({
-	source: d.source,
-	file: d.file,
-	code: d.code,
-	severity: d.severity,
-	message: d.message,
-	...d.range === void 0 ? {} : { range: d.range }
-});
-/**
-* Build the success envelope. `diagnostics` is sorted here with the same
-* `sort` the human renderer uses (K-21's "diagnostics are in the K-17
-* order"); `range` passes through as core computed it, zero-based.
-*
-* The value returned is in `Type` form (its `range`s are `DiagnosticRange`
-* instances). What stdout carries is `Schema.encodeSync(JsonEnvelope)` of it,
-* `JSON.stringify`-ed — one document, no trailing text.
-*
-* @public
-*/
-const json = (input) => {
-	const t = tally(input.diagnostics);
-	return {
-		schema: 1,
-		okfit_version: input.okfitVersion,
-		okf_version: input.okfVersion,
-		root: input.root,
-		profile: input.profile,
-		exit_code: input.exitCode,
-		summary: {
-			conformance_errors: t.conformanceErrors,
-			lint_errors: t.lintErrors,
-			lint_warnings: t.lintWarnings,
-			lint_info: t.lintInfo,
-			profile_errors: t.profileErrors,
-			concepts: input.concepts
-		},
-		diagnostics: sort(input.diagnostics).map(toJsonDiagnostic)
-	};
-};
-/** The error's `_tag` when it has one, else its constructor name; `"UnknownError"` for a non-object value. */
-const tagOf = (error) => {
-	if (typeof error !== "object" || error === null) return "UnknownError";
-	const tag = error._tag;
-	if (typeof tag === "string") return tag;
-	return error.constructor?.name ?? "UnknownError";
-};
-/** The error's `message` when it has one as a string, else `String(error)`. */
-const messageOf = (error) => {
-	if (typeof error === "object" && error !== null && "message" in error) {
-		const message = error.message;
-		if (typeof message === "string") return message;
-	}
-	return String(error);
-};
-/** K-22. `tag` is the error's `_tag` when it has one, else its constructor name. @public */
-const jsonError = (error, okfitVersion) => ({
-	schema: 1,
-	okfit_version: okfitVersion,
-	exit_code: 3,
-	error: {
-		tag: tagOf(error),
-		message: messageOf(error)
-	}
-});
-
-//#endregion
-export { JsonDiagnostic, JsonEnvelope, JsonErrorEnvelope, JsonSummary, json, jsonError };

package/render/sort.js

@@ -1,46 +0,0 @@
-//#region src/render/sort.ts
-const toRendered = (source) => (entry) => ({
-	source,
-	file: entry.file,
-	code: entry.code,
-	severity: entry.severity,
-	message: entry.message,
-	...entry.range === void 0 ? {} : { range: entry.range }
-});
-/**
-* Tag core's two arrays and profiles' one, in producer order. Not named
-* `merge`: `OkfitConfig.merge` already owns that word in this codebase.
-*
-* @public
-*/
-const collect = (conformance, lint, profile) => [
-	...conformance.map(toRendered("core.conformance")),
-	...lint.map(toRendered("core.lint")),
-	...profile.map(toRendered("profile"))
-];
-/** Range-less entries sort before ranged ones within the same file; ranged entries by `offset`. */
-const compareRange = (a, b) => {
-	if (a.range === void 0 && b.range === void 0) return 0;
-	if (a.range === void 0) return -1;
-	if (b.range === void 0) return 1;
-	return a.range.offset - b.range.offset;
-};
-/**
-* K-17: `file` ascending (so `""` — the bundle-level finding — leads), then
-* range-less before ranged within a file, then `range.offset` ascending, then
-* `code`. Plain code-unit comparison, never locale-dependent (the same rule
-* profiles' own `check` sorts by, `PROFILES/SoftwareProject.ts:119`). Stable:
-* implemented with `toSorted`, which is specified as stable.
-*
-* @public
-*/
-const sort = (diagnostics) => diagnostics.toSorted((a, b) => {
-	if (a.file !== b.file) return a.file < b.file ? -1 : 1;
-	const byRange = compareRange(a, b);
-	if (byRange !== 0) return byRange;
-	if (a.code !== b.code) return a.code < b.code ? -1 : 1;
-	return 0;
-});
-
-//#endregion
-export { collect, sort };

package/sync/generated.js

@@ -1,111 +0,0 @@
-import { detectNewline, locateGenerated, stripBom } from "../verify/locate.js";
-import { spliceGenerated } from "../verify/splice.js";
-import { writeAtomic } from "./write.js";
-import { DateTime, Effect, FileSystem, Path, Schema } from "effect";
-import { Timestamp } from "@okfit/core";
-import { MarkdownEdit } from "@effected/markdown";
-
-//#region src/sync/generated.ts
-/**
-* The five `SkipReason` members contract §6.2's algorithm can actually
-* produce — a strict subset of contract §5's six-member `SkipReason`
-* (`sync/run.ts`, Task B3; the sixth, `"log-unparseable"`, is log mode's
-* alone). Declared locally because `sync/run.ts` does not exist when this
-* task lands (fixed order A1 -> A2 -> B1 -> B2 -> B3); every member here is
-* spelled identically to its `SkipReason` counterpart, so Task B3 assigns
-* a `GeneratedSkipReason` value into a `SkipReason`-typed field with no
-* cast.
-*
-* @internal
-*/
-const GeneratedSkipReason = Schema.Literals([
-	"untracked",
-	"dirty",
-	"unborn",
-	"generated-missing",
-	"generated-unsupported"
-]);
-const encodeAt = Schema.encodeSync(Timestamp);
-/**
-* Contract §6.2's twelve-step algorithm, run once per `bundle.concepts`
-* entry (S-22: `index.md`/`log.md` are reserved files, never concepts,
-* never seen here). `provenance` is the single `Derivation.generatedAt`
-* walk `runSync` (Task B3) computes once and shares with log mode; this
-* function never calls git itself and never substitutes `now` for an
-* uncommitted body (design §3 rule 2). Every write is atomic (temp file
-* plus rename in the same directory), matching `verify`'s own discipline
-* (`verify/run.ts`'s `runVerify`).
-*
-* `locateGenerated`'s `YamlParseError` is folded into a defect here
-* (`Effect.orDie`), not widened into this function's typed error channel:
-* the frontmatter it re-parses already decoded once, successfully, for
-* this concept to be a member of `bundle.concepts` at all -- the same
-* reasoning `locate.ts`'s own `locate` documents for its identical
-* failure mode. `runSync`'s stated error union (`BundleLoadError |
-* GeneratedAtError`, contract §5) already includes `PlatformError.
-* PlatformError` inside `GeneratedAtError` (contract §14 note 2), so this
-* function's own `PlatformError.PlatformError` channel composes with no
-* widening on either side.
-*
-* @internal
-*/
-const syncGenerated = Effect.fn("okfit/sync/syncGenerated")(function* (bundle, provenance, dryRun) {
-	const fs = yield* FileSystem.FileSystem;
-	const path = yield* Path.Path;
-	const written = [];
-	const unchanged = [];
-	const skipped = [];
-	for (const [id, concept] of bundle.concepts) {
-		const derived = provenance.get(id);
-		if (derived === void 0) return yield* Effect.die(/* @__PURE__ */ new Error(`syncGenerated: no provenance computed for concept ${id}`));
-		if (derived._tag === "uncommitted") {
-			skipped.push({
-				id,
-				reason: derived.reason
-			});
-			continue;
-		}
-		const generated = concept.frontmatter.generated;
-		if (generated === void 0) {
-			skipped.push({
-				id,
-				reason: "generated-missing"
-			});
-			continue;
-		}
-		const recorded = generated.at;
-		if (recorded !== void 0 && DateTime.Equivalence(recorded, derived.at)) {
-			unchanged.push(id);
-			continue;
-		}
-		const absolutePath = path.join(bundle.root, concept.path);
-		const source = yield* fs.readFileString(absolutePath);
-		const { text, bom } = stripBom(source);
-		const newline = detectNewline(text);
-		const located = yield* locateGenerated(text).pipe(Effect.orDie);
-		if (located._tag === "unsupported") {
-			skipped.push({
-				id,
-				reason: "generated-unsupported"
-			});
-			continue;
-		}
-		const encodedAt = encodeAt(derived.at);
-		const edit = spliceGenerated(located, encodedAt, newline);
-		const finalText = bom + MarkdownEdit.applyAll(text, [edit]);
-		if (dryRun) {
-			written.push(id);
-			continue;
-		}
-		yield* writeAtomic(absolutePath, finalText);
-		written.push(id);
-	}
-	return {
-		written,
-		unchanged,
-		skipped
-	};
-});
-
-//#endregion
-export { syncGenerated };

package/sync/index.js

@@ -1,73 +0,0 @@
-import { writeAtomic } from "./write.js";
-import { Effect, FileSystem, Path } from "effect";
-import { Derive, OKF_SPEC_VERSION } from "@okfit/core";
-
-//#region src/sync/index.ts
-/**
-* Immediate child directories of `dir`, unioned from `bundle.directories`
-* and `bundle.indexes.keys()` -- the same union `Derive.synthesizeIndex`
-* walks (S-29, amending S-20's wording): a directory holding only an
-* `index.md` and no concepts is never a member of `bundle.directories`
-* (`Bundle.load` records a directory there only when it holds a concept),
-* but it is still a key of `bundle.indexes`, so omitting that map would
-* silently drop it from the root's `# Subdirectories` section while every
-* other directory's own `synthesizeIndex` call still lists it as a child.
-*/
-const childDirectoriesOf = (bundle, dir) => {
-	const prefix = dir === "" ? "" : `${dir}/`;
-	const children = /* @__PURE__ */ new Set();
-	for (const candidate of [...bundle.directories, ...bundle.indexes.keys()]) {
-		if (candidate === "" || candidate === dir || !candidate.startsWith(prefix)) continue;
-		const head = candidate.slice(prefix.length).split("/")[0];
-		if (head !== void 0 && head !== "") children.add(head);
-	}
-	return [...children];
-};
-const writeOrCompare = Effect.fn("okfit/sync/index/writeOrCompare")(function* (targetPath, relativeId, rendered, dryRun, written, unchanged) {
-	if ((yield* (yield* FileSystem.FileSystem).readFileString(targetPath).pipe(Effect.map((text) => text), Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(void 0)))) === rendered) {
-		unchanged.push(relativeId);
-		return;
-	}
-	if (dryRun) {
-		written.push(relativeId);
-		return;
-	}
-	yield* writeAtomic(targetPath, rendered);
-	written.push(relativeId);
-});
-/**
-* Contract §7. Directories: the bundle root plus every directory in
-* `bundle.directories` that holds at least one concept -- the same set
-* `Derive.synthesizeIndex` already walks (S-20). A directory with an
-* `index.md` but no concepts is left untouched (design §4: "nothing to
-* derive") because such a directory is never a member of
-* `bundle.directories` in the first place (`Bundle.load` only records a
-* directory there when it holds a concept -- `Bundle.ts:301-323`).
-*
-* @internal
-*/
-const syncIndex = Effect.fn("okfit/sync/syncIndex")(function* (bundle, dryRun) {
-	const path = yield* Path.Path;
-	const written = [];
-	const unchanged = [];
-	const rootConcepts = [...bundle.concepts.values()].filter((concept) => !concept.path.includes("/"));
-	const rootRendered = Derive.renderIndex("", rootConcepts, {
-		okfVersion: OKF_SPEC_VERSION,
-		subdirectories: childDirectoriesOf(bundle, "")
-	});
-	yield* writeOrCompare(path.join(bundle.root, "index.md"), "index.md", rootRendered, dryRun, written, unchanged);
-	for (const dir of bundle.directories) {
-		if (dir === "") continue;
-		const rendered = Derive.synthesizeIndex(bundle, dir);
-		yield* writeOrCompare(path.join(bundle.root, dir, "index.md"), `${dir}/index.md`, rendered, dryRun, written, unchanged);
-	}
-	return {
-		selected: true,
-		written,
-		unchanged,
-		skipped: []
-	};
-});
-
-//#endregion
-export { syncIndex };