@okfit/profiles 0.1.0 → 0.3.0

package/index.d.ts

@@ -1,21 +1,444 @@
-//#region src/index.d.ts
+import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
+import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
+import { Actor, Diagnostic, DiagnosticRange, LoadedBundle, OkfitConfig } from "@okfit/core";
+import { ChildProcessSpawner } from "effect/unstable/process";
+//#region src/BodyProvenance.d.ts
 /**
- * Named okfit configuration profiles.
+ * The body is at HEAD and last changed in the commit described here (P-9).
+ * `at` is that commit's author date (P-4); `committedAt` and the author
+ * identity are carried for callers that want a history-based policy later (P-40).
+ * `creating` is true exactly when the winning entry is also the oldest entry
+ * of the path's history — the commit that created the path (S-9).
  *
- * @packageDocumentation
+ * @public
+ */
+export declare const BodyCommitted: Schema.TaggedStruct<"committed", {
+  readonly at: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly sha: Schema.String;
+  readonly committedAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly authorName: Schema.String;
+  readonly authorEmail: Schema.String;
+  readonly creating: Schema.Boolean;
+}>;
+/**
+ * The body has no usable commit (P-9): `untracked` means HEAD does not contain
+ * the path, `dirty` means the on-disk body differs from HEAD's blob, `unborn`
+ * means HEAD has no commits (P-11).
+ *
+ * @public
  */
+export declare const BodyUncommitted: Schema.TaggedStruct<"uncommitted", {
+  readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn"]>;
+}>;
 /**
- * Names of the profiles this package ships.
+ * What {@link Derivation.generatedAt} reports. A schema so the value also
+ * serialises for MCP later without adaptation. Derivation never substitutes
+ * `now`; the uncommitted policy is the caller's (P-10).
  *
  * @public
  */
-declare const PROFILE_NAMES: readonly ["software-project"];
+export declare const BodyProvenance: Schema.Union<readonly [Schema.TaggedStruct<"committed", {
+  readonly at: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly sha: Schema.String;
+  readonly committedAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly authorName: Schema.String;
+  readonly authorEmail: Schema.String;
+  readonly creating: Schema.Boolean;
+}>, Schema.TaggedStruct<"uncommitted", {
+  readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn"]>;
+}>]>;
+/**
+ * The type of {@link (BodyProvenance:variable)}.
+ *
+ * @public
+ */
+export type BodyProvenance = typeof BodyProvenance.Type;
+/**
+ * Why a body is uncommitted (P-9).
+ *
+ * @public
+ */
+type UncommittedReason = typeof BodyUncommitted.fields.reason.Type;
+//#endregion
+//#region src/GitHistory.d.ts
+declare const PathHistoryEntry_base: Schema.Class<PathHistoryEntry, Schema.Struct<{
+  readonly sha: Schema.String;
+  readonly authoredAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly committedAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly authorName: Schema.String;
+  readonly authorEmail: Schema.String;
+  readonly path: Schema.String;
+}>, {}>;
+/**
+ * One record of the path log, newest first (P-3, P-5): the commit, both dates decoded through core's
+ * `Timestamp` (`%aI` / `%cI`, strict ISO with an offset; the `Type` is `DateTime.Utc`, P-4), the author
+ * identity, and the repository-relative posix path the blob had at that commit (the `--name-only` line).
+ * @public
+ */
+export declare class PathHistoryEntry extends PathHistoryEntry_base {}
+declare const GitHistoryError_base: Schema.Class<GitHistoryError, Schema.TaggedStruct<"GitHistoryError", {
+  /** The argv without the leading `git`. */
+  readonly args: Schema.$Array<Schema.String>;
+  /** The working directory the command ran in. */
+  readonly cwd: Schema.String;
+  /** git's exit code; absent when git never produced one. */
+  readonly exitCode: Schema.optionalKey<Schema.Number>;
+  /** git's stderr, captured under `LC_ALL=C`. */
+  readonly stderr: Schema.String;
+  /** Spawn failure text, `timed out after 30s`, or `Git.log`'s own absorbed-failure detail. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Profiles' own spawn failure, shaped like `@effected/git`'s `GitCommandError` (P-12). Raised by
+ * `GitHistory.layer` for any `GitCommandError` `Git.log` produces, including the one `Git.log`
+ * itself synthesizes when its own spawn timeout expires.
+ * @public
+ */
+export declare class GitHistoryError extends GitHistoryError_base {
+  get message(): string;
+}
+/**
+ * Options for `pathLog`; `limit` becomes `Git.log`'s `--max-count=<n>` (P-3, P-8).
+ * @public
+ */
+interface PathLogOptions {
+  readonly limit?: number;
+}
+/**
+ * The service shape. `cwd` is any directory inside the repository; `path` is relative to `cwd` (git
+ * pathspec semantics). The result is newest first, and empty when no commit contains the path or HEAD is
+ * unborn (P-11).
+ * @public
+ */
+interface GitHistoryShape {
+  readonly pathLog: (cwd: string, path: string, options?: PathLogOptions) => Effect.Effect<ReadonlyArray<PathHistoryEntry>, GitHistoryError | NotARepositoryError>;
+}
+declare const GitHistory_base: Context.ServiceClass<GitHistory, "@okfit/profiles/GitHistory", GitHistoryShape>;
+/**
+ * A path-scoped, date-bearing log: `Git.log` reads the whole repository history, and this adapter scopes
+ * it to one path (`--follow`, `--diff-merges=first-parent`) and decodes it into `PathHistoryEntry`.
+ * Delegates to `Git.log` as of `@effected/git` 0.12.0 (P-1, spec deviation retired).
+ * @public
+ */
+export declare class GitHistory extends GitHistory_base {
+  /**
+   * Live layer (P-1, P-5, P-11): one `Git.log` call per `pathLog`, resolved once at construction like
+   * `Git.layer` itself, so every member's `R` is `never`. `Git.log` already degrades an unborn `HEAD` and
+   * an unmatched pathspec to the empty array and classifies `not a git repository` as `NotARepositoryError`
+   * (both pass through unchanged); every other failure becomes `GitHistoryError`, including the one
+   * `Git.log` itself produces when its own 30 s spawn timeout expires (`@effected/git`'s `GIT_TIMEOUT`
+   * ceiling, not this adapter's) — `Git.log` never lets a bare `Cause.TimeoutError` escape. The CLI
+   * provides `ChildProcessSpawner` through `NodeServices.layer` (P-30).
+   */
+  static readonly layer: Layer.Layer<GitHistory, never, ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * Scripted double (P-32): responses keyed by the `path` argument exactly as passed to `pathLog`. A call
+   * whose path has no entry DIES with `GitHistory.makeTest: pathLog(<path>) was called but not scripted`,
+   * mirroring `Git.makeTest`; `limit` is honoured by slicing. Models none of the live semantics.
+   */
+  static readonly makeTest: (script: Readonly<Record<string, ReadonlyArray<PathHistoryEntry>>>) => GitHistoryShape;
+  /**
+   * `Layer.succeed(GitHistory, GitHistory.makeTest(script))`. Mints a fresh layer per call: bind it to a
+   * `const`, since layers memoize by reference.
+   */
+  static readonly layerTest: (script: Readonly<Record<string, ReadonlyArray<PathHistoryEntry>>>) => Layer.Layer<GitHistory>;
+}
+//#endregion
+//#region src/Derivation.d.ts
+/**
+ * Who is writing now. Explicit, never read from the environment (P-16).
+ *
+ * @public
+ */
+type Writer = "agent" | "human";
+declare const HumanActorUnresolvedError_base: Schema.Class<HumanActorUnresolvedError, Schema.TaggedStruct<"HumanActorUnresolvedError", {
+  readonly userName: Schema.optionalKey<Schema.String>;
+  readonly userEmail: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * git has no identity to derive a `human:` actor from (P-13 step 4).
+ * `userName` and `userEmail` are the trimmed `configGet` answers when git had
+ * them and absent keys otherwise (decision 53: not `name`/`email`, since every
+ * Effect error class carries the class name on its own prototype and a field
+ * literally named `name` would shadow `error.name` when present); test for
+ * git's answer with `Object.hasOwn(error, "userName")`.
+ *
+ * @public
+ */
+export declare class HumanActorUnresolvedError extends HumanActorUnresolvedError_base {
+  get message(): string;
+}
+declare const AgentActorUnconfiguredError_base: Schema.Class<AgentActorUnconfiguredError, Schema.TaggedStruct<"AgentActorUnconfiguredError", {}>, import("effect/Cause").YieldableError>;
+/**
+ * The writer is an agent but `actors.agent` is not configured (P-17); the
+ * profile never sets it.
+ *
+ * @public
+ */
+export declare class AgentActorUnconfiguredError extends AgentActorUnconfiguredError_base {
+  get message(): string;
+}
+/**
+ * Options for {@link Derivation.generatedAt} (P-39).
+ *
+ * @public
+ */
+interface GeneratedAtOptions {
+  /** ABSOLUTE path to the concept file on disk. */
+  readonly file: string;
+  /** Reserved (P-48): accepted and ignored in phase 1; no key affects the walk. */
+  readonly config?: OkfitConfig;
+}
+/**
+ * Everything {@link Derivation.generatedAt} can fail with: profiles' own
+ * `GitHistoryError`, the `@effected/git` peer's errors (P-12), and the
+ * `PlatformError` of `realPath`/`readFileString` on `file`.
+ *
+ * @public
+ */
+type GeneratedAtError = GitHistoryError | GitCommandError | NotARepositoryError | UnknownRefError | PlatformError.PlatformError;
+/**
+ * Options for {@link Derivation.generatedBy} (P-16, P-45).
+ *
+ * @public
+ */
+interface GeneratedByOptions {
+  readonly writer: Writer;
+  /** Any directory inside the repository; every `Git` member takes a cwd and profiles never reads `process.cwd()`. */
+  readonly cwd: string;
+  /** Merged or raw; only `actors` is read. */
+  readonly config: OkfitConfig;
+}
+/**
+ * Everything {@link Derivation.generatedBy} can fail with.
+ *
+ * @public
+ */
+type GeneratedByError = AgentActorUnconfiguredError | HumanActorUnresolvedError | GitCommandError | NotARepositoryError | UnknownRefError;
+/**
+ * Trimmed `user.name` / `user.email` as `Git.configGet` answers them; a key is absent when git has no value.
+ *
+ * @public
+ */
+interface GitIdentity {
+  readonly name?: string;
+  readonly email?: string;
+}
+/**
+ * Spec 5.4 derivation rules for the `software-project` profile, package-global
+ * (P-38). Pure members take every input as an argument; effectful members
+ * require `Git`, `GitHistory` and, for the worktree read, `FileSystem` and
+ * `Path` (P-30). Never writes, never reads `generated.by` (P-40).
+ *
+ * @public
+ */
+export declare class Derivation {
+  private constructor();
+  /**
+   * `FrontmatterSource.split(text).body`, then CRLF and lone CR to LF, then trailing whitespace at end of
+   * text removed (P-6). Pure. Applied to both sides of every comparison so `core.autocrlf` worktrees compare clean.
+   */
+  static readonly body: (text: string) => string;
+  /**
+   * Lowercase 64-char hex sha256 of `Derivation.body(text)`, through `effect`'s platform-agnostic
+   * `Crypto` service (issue #19). Same normalization as `body`, so a frontmatter-only edit or a
+   * `core.autocrlf` worktree never changes the digest.
+   */
+  static readonly bodyDigest: (text: string) => Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
+  /**
+   * Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
+   *  1. `root = Git.repoRoot(dirname(file))`: a file outside any repository surfaces `NotARepositoryError`;
+   *     submodules and worktrees work because the question is asked from the file's directory (P-39).
+   *  2. `realPath` both (rev-parse is symlink-resolved), then the repo-relative posix path via `Path` (P-39).
+   *  3. `worktree = body(readFileString(file))`.
+   *  4. `Git.show(realRoot, "HEAD", rel)`: `UnknownRefError` is `uncommitted { unborn }` (P-11), `Option.none`
+   *     is `uncommitted { untracked }` (P-47), a body differing from `worktree` is `uncommitted { dirty }` (P-9).
+   *     The comparison is against HEAD's blob, never the newest log entry (P-46).
+   *  5. `entries = GitHistory.pathLog(realRoot, rel)` newest first (P-5, P-46); `[]` is `uncommitted { unborn }`.
+   *  6. One `Git.show` per older blob (P-8), newest first: the first entry whose body differs from the next
+   *     older entry's body wins, else the oldest entry (the creating commit). "Previous" is the previous entry
+   *     of the simplified `--follow` history, not the true parent (P-7). The newest entry's body is never
+   *     re-fetched: `head.blob`, already confirmed equal to `worktree` by step 4, is reused (decision 56).
+   *     `Option.none` for an older entry counts as "differs", never a defect (decision 56).
+   * `config` is reserved and ignored (P-48). Never writes, never reads `by` (P-40).
+   */
+  static readonly generatedAt: (options: GeneratedAtOptions) => Effect.Effect<BodyProvenance, GeneratedAtError, Git | GitHistory | FileSystem.FileSystem | Path.Path>;
+  /**
+   * P-13 / P-14, pure. Candidates: the email local part (returned as written, lower-cased only for matching)
+   * and the `user.name` slug. Order, first hit wins: (1) a `human:` entry of `humans` whose id equals a
+   * candidate case-insensitively, returned verbatim; (2) `human:<local>`; (3) `human:<slug>`; (4) none.
+   * The result is branded through core's `Actor` codec and always passes it.
+   */
+  static readonly humanActorId: (identity: GitIdentity, humans: ReadonlyArray<Actor>) => Option.Option<Actor>;
+  /**
+   * Spec 5.4 rule 1 (P-16, P-45). `"agent"`: `config.actors.agent`, else {@link AgentActorUnconfiguredError}
+   * (P-17). `"human"`: `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` in merged
+   * scope (P-15) through {@link Derivation.humanActorId}; none is {@link HumanActorUnresolvedError}.
+   * Answers only "who is writing now" (P-40).
+   */
+  static readonly generatedBy: (options: GeneratedByOptions) => Effect.Effect<Actor, GeneratedByError, Git>;
+  /**
+   * P-19, pure: `from` plus `config.lifecycle.default_stale_after`, falling back to `OkfitConfig.DEFAULTS`'
+   * 90 days. `from` is the caller's: `generated.at` when committed, else its own `now`.
+   */
+  static readonly staleAfter: (from: DateTime.Utc, config: OkfitConfig) => DateTime.Utc;
+}
+//#endregion
+//#region src/Profile.d.ts
+/**
+ * Names of the profiles this package ships (P-38).
+ *
+ * @public
+ */
+export declare const PROFILE_NAMES: readonly ["software-project"];
 /**
  * A profile name shipped by this package.
  *
  * @public
  */
 type ProfileName = (typeof PROFILE_NAMES)[number];
+/**
+ * One concept directory of a profile's bundle layout (P-26). Each directory
+ * carries its own `index.md`; `type` is the `types.<Name>` key held there.
+ *
+ * @public
+ */
+interface LayoutDirectory {
+  readonly directory: string;
+  readonly type: string;
+}
+/**
+ * Scaffolding data for `okfit init` (spec 5.2); never part of `OkfitConfig`
+ * (P-26). What the CLI writes into these files is the CLI plan's concern.
+ *
+ * @public
+ */
+interface Layout {
+  readonly root: {
+    readonly index: "index.md";
+    readonly log: "log.md";
+    readonly project: "project.md";
+  };
+  readonly directories: ReadonlyArray<LayoutDirectory>;
+}
+/**
+ * Profile-owned diagnostic codes (P-21). Core's `LintCode` is untouched; all
+ * three are severity `error` and are not configurable.
+ *
+ * @public
+ */
+export declare const ProfileDiagnosticCode: Schema.Literals<readonly ["project-missing", "project-multiple", "project-not-at-root"]>;
+/**
+ * The type of `ProfileDiagnosticCode`.
+ *
+ * @public
+ */
+export type ProfileDiagnosticCode = typeof ProfileDiagnosticCode.Type;
+/**
+ * Same fields as core's `Diagnostic` with a profile code; a `Schema.Struct`
+ * per P-21/P-51. `file` is the bundle-relative posix path, `""` for the
+ * bundle-level `project-missing`. `range` is never set in phase 1.
+ *
+ * @public
+ */
+export declare const ProfileDiagnostic: Schema.Struct<{
+  readonly file: Schema.String;
+  readonly range: Schema.optionalKey<typeof DiagnosticRange>;
+  readonly code: Schema.Literals<readonly ["project-missing", "project-multiple", "project-not-at-root"]>;
+  readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+  readonly message: Schema.String;
+}>;
+/**
+ * The type of `ProfileDiagnostic`.
+ *
+ * @public
+ */
+export type ProfileDiagnostic = typeof ProfileDiagnostic.Type;
+/**
+ * A named profile (P-38): a partial `OkfitConfig` the CLI merges as
+ * `DEFAULTS < profile < file`, a scaffolding `Layout`, and a pure `check`
+ * over a loaded bundle run after `Validate.all`.
+ *
+ * @public
+ */
+interface Profile {
+  readonly name: ProfileName;
+  readonly config: OkfitConfig;
+  readonly layout: Layout;
+  readonly check: (bundle: LoadedBundle) => ReadonlyArray<ProfileDiagnostic>;
+}
+//#endregion
+//#region src/Profiles.d.ts
+/**
+ * The profile registry (P-38). No third-party registration in phase 1; the
+ * `DEFAULTS < profile < file` merge is the CLI's (D-28).
+ *
+ * @public
+ */
+export declare class Profiles {
+  private constructor();
+  /** The `software-project` profile (spec 5). */
+  static readonly softwareProject: Profile;
+  /**
+   * `Option.none` for `"none"`, unknown names and anything not in
+   * `PROFILE_NAMES`; the CLI decides what that means (P-38). Exact match only.
+   */
+  static readonly get: (name: string) => Option.Option<Profile>;
+}
+//#endregion
+//#region src/Provenance.d.ts
+/**
+ * A profiles-owned lint over committed provenance (S-8). NOT a `Profile`
+ * member and NOT a `ProfileDiagnostic` -- it returns core `Diagnostic`s with
+ * code `"generated-at-drift"`, a real `LintCode` member, so `severityFor`,
+ * the `[lint]` table, the renderers, the hook, and the MCP tool treat it
+ * like every other lint (S-7). `Profile.check` and `ProfileDiagnosticCode`
+ * are unchanged.
+ *
+ * Two tiers per concept (issue #19, body-digest design): when
+ * `generated.body_sha256` is present, drift is decided ENTIRELY by comparing it to
+ * `Derivation.bodyDigest` of the concept's current source -- no git call at
+ * all, so this works for a dirty worktree too (that is the point: an edited
+ * body is caught immediately, before it is even committed) and survives a
+ * squash/rebase merge that only rewrites commit dates, since the body
+ * itself, and therefore its digest, never changed. When `body_sha256` is
+ * absent (an un-migrated concept), this falls back to the original
+ * git-derived date comparison against `Derivation.generatedAt`, preserving
+ * `--skip-provenance`'s meaning for bundles that have not run `okfit sync`
+ * since this field was introduced.
+ *
+ * The tier-2 fallback returns `[]` the moment a `NotARepositoryError`
+ * surfaces: a bundle outside git has nothing to derive for any concept still
+ * on tier 2, so the first occurrence short-circuits the whole walk, not just
+ * the concept that triggered it (S-8). Emits no `range` (S-12, Judge note
+ * 7): `Diagnostic.range` is `Schema.optionalKey` and is simply omitted.
+ *
+ * `Provenance.lint` is total over severity (S-28, amending Judge note 3):
+ * when `OkfitConfig.severityFor(config, "generated-at-drift")` resolves to
+ * `"off"`, it returns `[]` before any per-concept work and before any git
+ * call, so it is safe to call at any severity and never needs to cast
+ * `"off"` away. `validate/run.ts` (the CLI) still gates on `"off"` before
+ * calling at all; the two agree by construction (both skip the walk).
+ *
+ * A third, optional options argument carries `skipGitTier`: when `true`, a
+ * concept that falls through to tier 2 (no `generated.body_sha256`
+ * recorded) is skipped entirely -- no `Derivation.generatedAt` call, no
+ * git spawn at all -- while tier 1 still runs, unaffected, for every
+ * concept that DOES carry a digest. This is a runtime skip, not a
+ * type-level narrowing: the R channel still lists `Git | GitHistory` even
+ * when every call happens to skip them, since the type describes what the
+ * function CAN require, not what one particular call ends up using.
+ * Defaults to `false`, so every existing caller keeps its current
+ * behavior unchanged.
+ *
+ * @public
+ */
+export declare class Provenance {
+  private constructor();
+  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, options?: {
+    readonly skipGitTier?: boolean;
+  }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Crypto.Crypto>;
+}
 //#endregion
-export { PROFILE_NAMES, ProfileName };
+export type { GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, UncommittedReason, Writer };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,15 +1,8 @@
-//#region src/index.ts
-/**
-* Named okfit configuration profiles.
-*
-* @packageDocumentation
-*/
-/**
-* Names of the profiles this package ships.
-*
-* @public
-*/
-const PROFILE_NAMES = ["software-project"];
+import { BodyCommitted, BodyProvenance, BodyUncommitted } from "./BodyProvenance.js";
+import { GitHistory, GitHistoryError, PathHistoryEntry } from "./GitHistory.js";
+import { AgentActorUnconfiguredError, Derivation, HumanActorUnresolvedError } from "./Derivation.js";
+import { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode } from "./Profile.js";
+import { Profiles } from "./Profiles.js";
+import { Provenance } from "./Provenance.js";
 
-//#endregion
-export { PROFILE_NAMES };
+export { AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Derivation, GitHistory, GitHistoryError, HumanActorUnresolvedError, PROFILE_NAMES, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.1.0",
+	"version": "0.3.0",
 	"private": false,
 	"description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
 	"keywords": [
@@ -34,9 +34,11 @@
 		},
 		"./package.json": "./package.json"
 	},
-	"dependencies": {
-		"@okfit/core": "0.1.0",
-		"effect": "4.0.0-rc.109"
+	"peerDependencies": {
+		"@effected/git": "^0.12.0",
+		"@effected/markdown": "^0.9.0",
+		"@okfit/core": "^0.3.0",
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"