@okfit/profiles 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/Canonical.js CHANGED
@@ -1,4 +1,6 @@
1
1
  import { body } from "./internal/body.js";
2
+ import { Result, Schema } from "effect";
3
+ import { JsoncCanonicalizeOptions, JsoncFingerprint } from "@effected/jsonc";
2
4
 
3
5
  // src/Canonical.ts
4
6
  /** Top-level keys that are bookkeeping, not authored content (spec section 4). */
@@ -10,26 +12,43 @@ const EXCLUDED_KEYS = /* @__PURE__ */ new Set([
10
12
  "status",
11
13
  "timestamp"
12
14
  ]);
13
- /** `JSON.stringify` omits these in an object and writes `null` for them in an array. */
14
- const isSkipped = (value) => value === void 0 || typeof value === "function" || typeof value === "symbol";
15
15
  /**
16
- * Canonical JSON: object keys sorted (`Array.prototype.toSorted`, UTF-16 code units)
17
- * at every depth; arrays keep their order. Byte-for-byte `JSON.stringify` of the
18
- * sorted value for every JSON-representable input, plus one extension: a `bigint`
19
- * (what the YAML decoder yields for an integer beyond 2^53, e.g. `ticket:
20
- * 123456789012345678901`) is written as its bare decimal literal. A literal cannot
21
- * collide with a string (strings are quoted) and is deterministic, where
22
- * `JSON.stringify` throws `TypeError` and would defect every caller that hashes.
16
+ * `@effected/jsonc`'s RFC 8785 canonicalization, relaxed only where okfit's frontmatter needs it: a `bigint`
17
+ * (what the YAML decoder yields for an integer beyond 2^53) is written as its bare decimal literal, an
18
+ * `undefined` member is omitted, a non-finite number is `null`, and a `toJSON` value is serialized through
19
+ * it. These match `JSON.stringify` of the sorted value byte for byte. An unpaired surrogate is NOT relaxed:
20
+ * it is not well-formed Unicode, can only arrive through a YAML `\uD800`-style escape, and fails as a
21
+ * {@link ContentUnhashableError} instead of being hashed (okfit#327).
23
22
  */
24
- const json = (value) => {
25
- if (typeof value === "bigint") return value.toString();
26
- if (Array.isArray(value)) return `[${value.map((item) => isSkipped(item) ? "null" : json(item)).join(",")}]`;
27
- if (value !== null && typeof value === "object") {
28
- const record = value;
29
- if (typeof record.toJSON === "function") return json(record.toJSON());
30
- return `{${Object.keys(record).toSorted().filter((key) => !isSkipped(record[key])).map((key) => `${JSON.stringify(key)}:${json(record[key])}`).join(",")}}`;
23
+ const CANONICALIZE = JsoncCanonicalizeOptions.make({
24
+ bigint: "number",
25
+ undefined: "omit",
26
+ nonFinite: "null",
27
+ toJSON: "all"
28
+ });
29
+ /**
30
+ * A concept's content cannot be canonicalized for its digest, so it has none: most often a frontmatter
31
+ * string holding an unpaired surrogate (`"\uD800"`). `path` is the offending value's frontmatter path
32
+ * (`[]` for the frontmatter itself), `detail` the canonicalizer's reason.
33
+ *
34
+ * @public
35
+ */
36
+ var ContentUnhashableError = class extends Schema.TaggedError()("ContentUnhashableError", {
37
+ path: Schema.Array(Schema.Union([Schema.String, Schema.Number])),
38
+ detail: Schema.String
39
+ }) {
40
+ get message() {
41
+ return `${this.path.length === 0 ? "the frontmatter" : this.path.join(".")} cannot be hashed: ${this.detail}`;
31
42
  }
32
- return JSON.stringify(value);
43
+ };
44
+ /** `/frontmatter/a/0/b` to `["a", 0, "b"]` (RFC 6901 unescaping); a body or root pointer to `[]`. */
45
+ const frontmatterPath = (pointer) => {
46
+ const [, head, ...rest] = pointer.split("/");
47
+ if (head !== "frontmatter") return [];
48
+ return rest.map((token) => {
49
+ const key = token.replaceAll("~1", "/").replaceAll("~0", "~");
50
+ return /^(0|[1-9][0-9]*)$/.test(key) ? Number(key) : key;
51
+ });
33
52
  };
34
53
  const stripRendersDigests = (renders) => Array.isArray(renders) ? renders.map((entry) => {
35
54
  if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return entry;
@@ -37,17 +56,20 @@ const stripRendersDigests = (renders) => Array.isArray(renders) ? renders.map((e
37
56
  return rest;
38
57
  }) : renders;
39
58
  /**
40
- * The exact string a content digest hashes: canonical JSON of the authored frontmatter
59
+ * The exact string a content digest hashes, or why there is none: canonical JSON of the authored frontmatter
41
60
  * (`raw` minus `Canonical.EXCLUDED_KEYS` and every `renders[].body`) and the
42
61
  * normalised body. `raw` is the parsed mapping (YAML 1.2 Core Schema: timestamps are
43
62
  * strings), so quoting, flow vs block style, key order and CRLF never change it.
44
63
  */
45
64
  const contentInput = (raw, source) => {
46
65
  const frontmatter = Object.fromEntries(Object.entries(raw).filter(([key]) => !EXCLUDED_KEYS.has(key)).map(([key, value]) => [key, key === "renders" ? stripRendersDigests(value) : value]));
47
- return json({
66
+ return Result.mapError(JsoncFingerprint.canonicalizeResult({
48
67
  body: body(source),
49
68
  frontmatter
50
- });
69
+ }, CANONICALIZE), (error) => new ContentUnhashableError({
70
+ path: frontmatterPath(error.path),
71
+ detail: error.detail
72
+ }));
51
73
  };
52
74
  /**
53
75
  * Canonical encoding for okfit's content digest.
@@ -58,10 +80,8 @@ var Canonical = class {
58
80
  constructor() {}
59
81
  /** Top-level frontmatter keys excluded from the content digest. */
60
82
  static EXCLUDED_KEYS = EXCLUDED_KEYS;
61
- /** Canonical JSON: sorted keys at every depth, array order kept; a `bigint` is its bare decimal literal. */
62
- static json = json;
63
- /** The exact string a content digest hashes. */
83
+ /** The exact string a content digest hashes, or a {@link ContentUnhashableError}. */
64
84
  static contentInput = contentInput;
65
85
  };
66
86
 
67
- export { Canonical };
87
+ export { Canonical, ContentUnhashableError };
package/Derivation.js CHANGED
@@ -3,9 +3,8 @@ import { Canonical } from "./Canonical.js";
3
3
  import { GitHistory } from "./GitHistory.js";
4
4
  import { Actor, OkfitConfig } from "@okfit/core";
5
5
  import { DateTime, Duration, Effect, FileSystem, Option, Path, Schema } from "effect";
6
- import { Git } from "@effected/git";
7
6
  import { JsoncFingerprint } from "@effected/jsonc";
8
- import { Walker } from "@effected/walker";
7
+ import { Git } from "@effected/git";
9
8
 
10
9
  // src/Derivation.ts
11
10
  /**
@@ -66,7 +65,7 @@ const decodeActor = Schema.decodeSync(Actor);
66
65
  const digestFull = (text) => JsoncFingerprint.hashText(text);
67
66
  const digest = (text) => Effect.map(digestFull(text), (hex) => hex.slice(0, 16));
68
67
  const bodyDigest = (source) => digest(body(source));
69
- const contentDigest = (raw, source) => digest(Canonical.contentInput(raw, source));
68
+ const contentDigest = (raw, source) => Effect.flatMap(Effect.fromResult(Canonical.contentInput(raw, source)), digest);
70
69
  /** The text before the first `@` (the whole value when there is none), or undefined when empty or containing whitespace. */
71
70
  const localPartOf = (email) => {
72
71
  if (email === void 0) return void 0;
@@ -142,7 +141,7 @@ var Derivation = class Derivation {
142
141
  static digestFull = digestFull;
143
142
  /**
144
143
  * The okfit digest of a string: the first 16 lowercase hex characters of its SHA-256, through
145
- * `effect`'s platform-agnostic `Crypto` service.
144
+ * core's platform-agnostic `Digest` service.
146
145
  */
147
146
  static digest = digest;
148
147
  /**
@@ -158,30 +157,17 @@ var Derivation = class Derivation {
158
157
  static recordedBody = (concept) => concept.frontmatter.integrity?.generated?.body ?? concept.frontmatter.generated?.body_sha256?.slice(0, 16);
159
158
  /**
160
159
  * 16-hex digest of the canonical content input (`Canonical.contentInput`): authored frontmatter
161
- * plus the normalised body, insensitive to style, key order and CRLF.
160
+ * plus the normalised body, insensitive to style, key order and CRLF. Fails with
161
+ * {@link ContentUnhashableError} when the content cannot be canonicalized (an unpaired surrogate).
162
162
  */
163
163
  static contentDigest = contentDigest;
164
164
  /**
165
- * The worktree root holding `start`: the nearest ancestor directory (inclusive) with a `.git` entry, a
166
- * directory in a main checkout and a file in a linked worktree or submodule; `undefined` when none has one.
167
- * Asked of the filesystem rather than of `git rev-parse --show-toplevel` because a pre-commit hook in a
168
- * linked worktree exports `GIT_DIR` without `GIT_WORK_TREE`, and git then takes each call's cwd as the
169
- * worktree, naming whatever directory it was asked from as the top level (okfit #315). Not
170
- * symlink-resolved; callers `realPath` it as they would `Git.repoRoot`.
171
- */
172
- static worktreeRoot = Effect.fn("Derivation.worktreeRoot")(function* (start) {
173
- const fs = yield* FileSystem.FileSystem;
174
- const path = yield* Path.Path;
175
- const dirs = yield* Walker.ascend(path.resolve(start));
176
- const root = yield* Walker.findRoot(dirs, (dir) => fs.exists(path.join(dir, ".git")));
177
- return Option.getOrUndefined(root);
178
- });
179
- /**
180
165
  * Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
181
- * 1. `root = worktreeRoot(dirname(file)) ?? Git.repoRoot(dirname(file))`: the filesystem walk first, so a
182
- * linked worktree's hook environment (`GIT_DIR` exported) cannot shrink the root to the file's directory
183
- * (okfit #315); git answers when no ancestor holds `.git`, and a file outside any repository surfaces
184
- * `NotARepositoryError`. Submodules and worktrees work because both are asked from the file's directory (P-39).
166
+ * 1. `root = Git.repoRoot(dirname(file), { ignoreRepositoryEnv: true })`: the option drops the
167
+ * repository-pointing variables (`GIT_DIR` and kin), so a linked worktree's hook environment cannot shrink
168
+ * the root to the file's directory (okfit #315). On `NotARepositoryError` it retries with that
169
+ * environment honoured, so a repository defined only by `GIT_DIR`/`GIT_WORK_TREE` still resolves; a file
170
+ * outside any repository surfaces `NotARepositoryError`. Submodules and worktrees work because both are asked from the file's directory (P-39).
185
171
  * 2. `realPath` both (rev-parse is symlink-resolved), then the repo-relative posix path via `Path` (P-39).
186
172
  * 3. `worktree = body(readFileString(file))`.
187
173
  * 4. `Git.show(realRoot, "HEAD", rel)`: `UnknownRefError` is `uncommitted { unborn }` (P-11), `Option.none`
@@ -200,7 +186,8 @@ var Derivation = class Derivation {
200
186
  const history = yield* GitHistory;
201
187
  const fs = yield* FileSystem.FileSystem;
202
188
  const path = yield* Path.Path;
203
- const root = (yield* Derivation.worktreeRoot(path.dirname(options.file))) ?? (yield* git.repoRoot(path.dirname(options.file)));
189
+ const dir = path.dirname(options.file);
190
+ const root = yield* git.repoRoot(dir, { ignoreRepositoryEnv: true }).pipe(Effect.catchTag("NotARepositoryError", () => git.repoRoot(dir)));
204
191
  const realRoot = yield* fs.realPath(root);
205
192
  const realFile = yield* fs.realPath(options.file);
206
193
  const rel = path.relative(realRoot, realFile).split(path.sep).join("/");
package/README.md CHANGED
@@ -290,7 +290,7 @@ Each directory carries its own `index.md`. What `okfit init` writes into these f
290
290
  - **`generated.at` is the author date, not the stamp date (P-4).** Walking a path's git history newest-first, the commit that changed the body is the one whose blob first differs from its predecessor's; that commit's *author* date (`%aI`) is `generated.at`. Its committer date, author name, and author email are carried on the result for callers that want a history-based policy later, but `generated.at` itself is never the date of a later frontmatter-only stamp.
291
291
  - **The path log is `@effected/git`'s `Git.log(cwd, { paths: [path], follow: true, firstParentDiffMerges: true })` (P-5, amended P-46, decision 56).** `firstParentDiffMerges` surfaces a conflict-resolving merge whose blob differs from both parents (probed on git 2.54.0), which plain `--follow` can omit and which would otherwise attribute that body change to the wrong commit. `Git.log`'s unconditional `-z` makes `--name-only` emit paths raw — no C-style quoting — so no `core.quotePath` override is needed and a path containing a space, a quote, or a newline round-trips verbatim. The dirty check compares the worktree body against `Git.show(root, "HEAD", path)`, never against the newest log entry. `--follow`'s rename detection can itself stop at a commit that renames a file and rewrites its content enough that git no longer treats it as a continuation of the same history; when that happens, `generated.at` answers that rename commit rather than an older one.
292
292
  - **Uncommitted is the caller's to interpret (P-10).** `Derivation.generatedAt` reports `{ _tag: "uncommitted", reason: "untracked" | "dirty" | "unborn" }` and never substitutes `now`. The recommended policy, followed by the snippet below: omit `generated.at` entirely until the body is committed.
293
- - **The body digest answers "has the body changed", where dates cannot (issue #19).** `Derivation.bodyDigest(text)` is a 16-hex SHA-256 prefix over the same normalised body `Derivation.body` produces (CRLF and lone CR to LF, trailing whitespace at end of text removed), so a `core.autocrlf` worktree and a trailing-newline change hash identically and a frontmatter-only edit does not move the digest at all. It is computed through effect's own `Crypto` service rather than `node:crypto`, so it carries `Crypto.Crypto` in its R channel; `NodeServices.layer` already supplies it wherever this package is used. `okfit sync` records it as `integrity.generated.body` — okfit's own extension key, not an OKF v0.2 field — and `Provenance.lint` compares it. Git cannot make this judgement on its own: the stamp lives in the same blob as the body, so a squash merge (one new commit carrying both) is indistinguishable by history from a body edited without a re-stamp.
293
+ - **The body digest answers "has the body changed", where dates cannot (issue #19).** `Derivation.bodyDigest(text)` is a 16-hex SHA-256 prefix over the same normalised body `Derivation.body` produces (CRLF and lone CR to LF, trailing whitespace at end of text removed), so a `core.autocrlf` worktree and a trailing-newline change hash identically and a frontmatter-only edit does not move the digest at all. It is computed through core's `Digest` service (`effect/crypto`) rather than `node:crypto`, so it carries `Digest.Digest` in its R channel and cannot fail with a typed error; provide a `Digest` layer such as `NodeCrypto.layerDigest` from `@effect/platform-node` (`NodeServices.layer` carries no crypto since Effect 4.1). `okfit sync` records it as `integrity.generated.body` — okfit's own extension key, not an OKF v0.2 field — and `Provenance.lint` compares it. Git cannot make this judgement on its own: the stamp lives in the same blob as the body, so a squash merge (one new commit carrying both) is indistinguishable by history from a body edited without a re-stamp.
294
294
  - **Human actor resolution (P-13).** Given git identity `{ name?, email? }` and `config.actors.humans`, the first hit wins: (1) `git config okfit.actor`, which must be a `human:<id>` with no `@` and no `*` or `?` (`ActorConfigInvalidError` otherwise); (2) a literal `human:<id>` entry (glob entries are skipped) whose id matches the email's local part or the name's slug, case-insensitively (config spelling returned); (3) `human:<local part>`; (4) `human:<slug of name>`; (5) unresolved (`HumanActorUnresolvedError`). `Derivation.verifier` runs that resolution and then checks the `[actors].humans` allow-list with core's `Actor.allowed`: an empty or absent list allows anyone, a non-empty one fails with `HumanActorNotAllowedError`, which is what `okfit verify`, `--revoke` and the language server's verify actions surface. okfit never stores an email; the trust signal reports `actor-not-allowed` (a `DriftReason`) for a verifier outside the list. The slug lowercases `name`, replaces runs of whitespace and characters outside `[A-Za-z0-9._-]` with `-`, and trims leading and trailing `-`.
295
295
  - **Identity is read at merged config scope (P-15).** `Derivation.generatedBy` calls `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` with no `scope` option. Environment overrides (`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `EMAIL`, `user.useConfigOnly`) are out of scope for phase 1.
296
296
  - **`stale_after` is pure addition (P-19).** `Derivation.staleAfter(from, config)` is `from + (config.lifecycle?.default_stale_after ?? OkfitConfig.DEFAULTS.lifecycle.default_stale_after)`, falling back to 90 days. `from` should be `generated.at` when the provenance is `committed`, otherwise the caller's own `now`; re-stamp whenever `generated.at` changes.
package/Trust.js CHANGED
@@ -1,13 +1,15 @@
1
1
  import { Derivation } from "./Derivation.js";
2
2
  import { Actor, Derive, Diagnostic, DiagnosticRange, OkfitConfig, Timestamp } from "@okfit/core";
3
- import { DateTime, Effect, Schema } from "effect";
3
+ import { DateTime, Effect, Result, Schema } from "effect";
4
4
 
5
5
  // src/Trust.ts
6
6
  const encodeAt = Schema.encodeSync(Timestamp);
7
7
  /**
8
8
  * Why a human verification no longer binds: the content changed, the entry has
9
- * no `integrity.verified` binding, a later human entry is not the bound one, or
10
- * the bound actor fails a non-empty `[actors].humans` allow-list.
9
+ * no `integrity.verified` binding, a later human entry is not the bound one, the
10
+ * bound actor fails a non-empty `[actors].humans` allow-list, or the content
11
+ * cannot be hashed at all (an unpaired surrogate; okfit#327), so the binding
12
+ * cannot be checked.
11
13
  *
12
14
  * @public
13
15
  */
@@ -15,7 +17,8 @@ const DriftReason = Schema.Literals([
15
17
  "content-changed",
16
18
  "unbound",
17
19
  "entry-superseded",
18
- "actor-not-allowed"
20
+ "actor-not-allowed",
21
+ "content-unhashable"
19
22
  ]);
20
23
  /** Only `human:` entries bind; machine entries neither bind nor break a binding. */
21
24
  const latestHumanOf = (entries) => entries.filter((entry) => Actor.isHuman(entry.by)).reduce((latest, entry) => latest === void 0 || DateTime.isGreaterThanOrEqualTo(entry.at, latest.at) ? entry : latest, void 0);
@@ -70,11 +73,31 @@ const signal = Effect.fn("Trust.signal")(function* (concept, config, now) {
70
73
  const tier = Derive.trustTier(concept.frontmatter);
71
74
  const stale = Derive.isStale(concept.frontmatter, now);
72
75
  const input = inputOf(concept, config);
73
- const content = needsDigest(input) ? yield* Derivation.contentDigest(concept.frontmatter.raw, concept.document.source) : void 0;
76
+ if (!needsDigest(input)) return {
77
+ tier,
78
+ stale,
79
+ ...evaluate(input, void 0)
80
+ };
81
+ const content = yield* Effect.result(Derivation.contentDigest(concept.frontmatter.raw, concept.document.source));
82
+ if (Result.isFailure(content)) {
83
+ const { detail, path } = content.failure;
84
+ return {
85
+ tier,
86
+ stale,
87
+ integrity: "drifted",
88
+ drift: {
89
+ reason: "content-unhashable",
90
+ unhashable: {
91
+ detail,
92
+ path
93
+ }
94
+ }
95
+ };
96
+ }
74
97
  return {
75
98
  tier,
76
99
  stale,
77
- ...evaluate(input, content)
100
+ ...evaluate(input, content.success)
78
101
  };
79
102
  });
80
103
  const signals = Effect.fn("Trust.signals")(function* (bundle, config, now) {
@@ -89,16 +112,18 @@ const messageFor = (concept, drift) => {
89
112
  if (drift.reason === "unbound") return `verified by ${by} at ${at}, but no integrity.verified binding records what was verified; re-run okfit verify`;
90
113
  if (drift.reason === "entry-superseded") return `the latest human verification (${by} at ${at}) is not the one integrity.verified binds; re-run okfit verify`;
91
114
  const binding = concept.frontmatter.integrity?.verified;
115
+ if (drift.reason === "content-unhashable") return `${drift.unhashable === void 0 || drift.unhashable.path.length === 0 ? "the frontmatter" : drift.unhashable.path.join(".")} cannot be hashed (${drift.unhashable?.detail ?? "not canonicalizable"}), so the verification by ${binding?.by ?? by} cannot be checked; fix the value, then re-run okfit verify`;
92
116
  if (drift.reason === "actor-not-allowed") return `verified by ${binding?.by ?? by}, who is not in [actors].humans; a listed human re-runs okfit verify`;
93
117
  const edited = drift.editedBy === void 0 ? "" : ` (edited by ${drift.editedBy} at ${drift.editedAt})`;
94
118
  return `content changed since ${binding?.by ?? by} verified it at ${binding === void 0 ? at : encodeAt(binding.at)}${edited}; re-run okfit verify`;
95
119
  };
96
120
  /**
97
- * Where a `verified-drift` finding points (spec section 6): the binding when one exists,
98
- * else the latest human `verified` entry -- by its list index when `verified` is a
121
+ * Where a `verified-drift` finding points (spec section 6): the offending value for
122
+ * `content-unhashable`, else the binding when one exists, else the latest human `verified` entry -- by its list index when `verified` is a
99
123
  * sequence, the key itself when it is a single bare mapping.
100
124
  */
101
- const rangePath = (concept) => {
125
+ const rangePath = (concept, drift) => {
126
+ if (drift.unhashable !== void 0 && drift.unhashable.path.length > 0) return drift.unhashable.path;
102
127
  if (concept.frontmatter.integrity?.verified !== void 0) return ["integrity", "verified"];
103
128
  const latest = latestHuman(concept);
104
129
  const index = latest === void 0 ? -1 : (concept.frontmatter.verified ?? []).indexOf(latest);
@@ -113,7 +138,7 @@ const lint = Effect.fn("Trust.lint")(function* (bundle, config, now, given) {
113
138
  if (status === "draft" || status === "deprecated") continue;
114
139
  const result = given?.get(id) ?? (yield* signal(concept, config, now));
115
140
  if (result.drift === void 0) continue;
116
- const range = DiagnosticRange.forFrontmatterPath(concept.document, rangePath(concept));
141
+ const range = DiagnosticRange.forFrontmatterPath(concept.document, rangePath(concept, result.drift));
117
142
  diagnostics.push(Diagnostic.make({
118
143
  file: concept.path,
119
144
  code: "verified-drift",
package/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
- import { Context, Crypto, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
1
+ import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Result, Schema } from "effect";
2
2
  import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
3
3
  import { Actor, Diagnostic, DiagnosticRange, Digest, LoadedBundle, LoadedConcept, OkfitConfig, TrustTier } from "@okfit/core";
4
+ import { Digest as Digest$1 } from "effect/crypto";
4
5
  import { ChildProcessSpawner } from "effect/process";
5
6
  /**
6
7
  * The body is at HEAD and last changed in the commit described here (P-9).
@@ -58,6 +59,20 @@ export type BodyProvenance = typeof BodyProvenance.Type;
58
59
  * @public
59
60
  */
60
61
  type UncommittedReason = typeof BodyUncommitted.fields.reason.Type;
62
+ declare const ContentUnhashableError_base: Schema.Class<ContentUnhashableError, Schema.TaggedStruct<"ContentUnhashableError", {
63
+ readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
64
+ readonly detail: Schema.String;
65
+ }>, import("effect/Cause").YieldableError>;
66
+ /**
67
+ * A concept's content cannot be canonicalized for its digest, so it has none: most often a frontmatter
68
+ * string holding an unpaired surrogate (`"\uD800"`). `path` is the offending value's frontmatter path
69
+ * (`[]` for the frontmatter itself), `detail` the canonicalizer's reason.
70
+ *
71
+ * @public
72
+ */
73
+ export declare class ContentUnhashableError extends ContentUnhashableError_base {
74
+ get message(): string;
75
+ }
61
76
  /**
62
77
  * Canonical encoding for okfit's content digest.
63
78
  *
@@ -67,10 +82,8 @@ export declare class Canonical {
67
82
  private constructor();
68
83
  /** Top-level frontmatter keys excluded from the content digest. */
69
84
  static readonly EXCLUDED_KEYS: ReadonlySet<string>;
70
- /** Canonical JSON: sorted keys at every depth, array order kept; a `bigint` is its bare decimal literal. */
71
- static readonly json: (value: unknown) => string;
72
- /** The exact string a content digest hashes. */
73
- static readonly contentInput: (raw: Readonly<Record<string, unknown>>, source: string) => string;
85
+ /** The exact string a content digest hashes, or a {@link ContentUnhashableError}. */
86
+ static readonly contentInput: (raw: Readonly<Record<string, unknown>>, source: string) => Result.Result<string, ContentUnhashableError>;
74
87
  }
75
88
  declare const PathHistoryEntry_base: Schema.Class<PathHistoryEntry, Schema.Struct<{
76
89
  readonly sha: Schema.String;
@@ -284,17 +297,17 @@ export declare class Derivation {
284
297
  *
285
298
  * @internal
286
299
  */
287
- static readonly digestFull: (text: string) => Effect.Effect<string, PlatformError.PlatformError, Crypto.Crypto>;
300
+ static readonly digestFull: (text: string) => Effect.Effect<string, never, Digest$1.Digest>;
288
301
  /**
289
302
  * The okfit digest of a string: the first 16 lowercase hex characters of its SHA-256, through
290
- * `effect`'s platform-agnostic `Crypto` service.
303
+ * core's platform-agnostic `Digest` service.
291
304
  */
292
- static readonly digest: (text: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
305
+ static readonly digest: (text: string) => Effect.Effect<Digest, never, Digest$1.Digest>;
293
306
  /**
294
307
  * 16-hex digest of `Derivation.body(source)` (issue #19). Same normalization as `body`, so a
295
308
  * frontmatter-only edit or a `core.autocrlf` worktree never changes the digest.
296
309
  */
297
- static readonly bodyDigest: (source: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
310
+ static readonly bodyDigest: (source: string) => Effect.Effect<Digest, never, Digest$1.Digest>;
298
311
  /**
299
312
  * The body digest recorded for a generated concept: `integrity.generated.body`, else the legacy
300
313
  * `generated.body_sha256` cut to its first 16 hex characters. `undefined` when neither is present.
@@ -303,24 +316,17 @@ export declare class Derivation {
303
316
  static readonly recordedBody: (concept: LoadedConcept) => string | undefined;
304
317
  /**
305
318
  * 16-hex digest of the canonical content input (`Canonical.contentInput`): authored frontmatter
306
- * plus the normalised body, insensitive to style, key order and CRLF.
307
- */
308
- static readonly contentDigest: (raw: Readonly<Record<string, unknown>>, source: string) => Effect.Effect<Digest, PlatformError.PlatformError, Crypto.Crypto>;
309
- /**
310
- * The worktree root holding `start`: the nearest ancestor directory (inclusive) with a `.git` entry, a
311
- * directory in a main checkout and a file in a linked worktree or submodule; `undefined` when none has one.
312
- * Asked of the filesystem rather than of `git rev-parse --show-toplevel` because a pre-commit hook in a
313
- * linked worktree exports `GIT_DIR` without `GIT_WORK_TREE`, and git then takes each call's cwd as the
314
- * worktree, naming whatever directory it was asked from as the top level (okfit #315). Not
315
- * symlink-resolved; callers `realPath` it as they would `Git.repoRoot`.
319
+ * plus the normalised body, insensitive to style, key order and CRLF. Fails with
320
+ * {@link ContentUnhashableError} when the content cannot be canonicalized (an unpaired surrogate).
316
321
  */
317
- static readonly worktreeRoot: (start: string) => Effect.Effect<string | undefined, never, FileSystem.FileSystem | Path.Path>;
322
+ static readonly contentDigest: (raw: Readonly<Record<string, unknown>>, source: string) => Effect.Effect<Digest, ContentUnhashableError, Digest$1.Digest>;
318
323
  /**
319
324
  * Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
320
- * 1. `root = worktreeRoot(dirname(file)) ?? Git.repoRoot(dirname(file))`: the filesystem walk first, so a
321
- * linked worktree's hook environment (`GIT_DIR` exported) cannot shrink the root to the file's directory
322
- * (okfit #315); git answers when no ancestor holds `.git`, and a file outside any repository surfaces
323
- * `NotARepositoryError`. Submodules and worktrees work because both are asked from the file's directory (P-39).
325
+ * 1. `root = Git.repoRoot(dirname(file), { ignoreRepositoryEnv: true })`: the option drops the
326
+ * repository-pointing variables (`GIT_DIR` and kin), so a linked worktree's hook environment cannot shrink
327
+ * the root to the file's directory (okfit #315). On `NotARepositoryError` it retries with that
328
+ * environment honoured, so a repository defined only by `GIT_DIR`/`GIT_WORK_TREE` still resolves; a file
329
+ * outside any repository surfaces `NotARepositoryError`. Submodules and worktrees work because both are asked from the file's directory (P-39).
324
330
  * 2. `realPath` both (rev-parse is symlink-resolved), then the repo-relative posix path via `Path` (P-39).
325
331
  * 3. `worktree = body(readFileString(file))`.
326
332
  * 4. `Git.show(realRoot, "HEAD", rel)`: `UnknownRefError` is `uncommitted { unborn }` (P-11), `Option.none`
@@ -556,7 +562,7 @@ export declare class Provenance {
556
562
  private constructor();
557
563
  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, options?: {
558
564
  readonly skipGitTier?: boolean;
559
- }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Crypto.Crypto>;
565
+ }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Digest$1.Digest>;
560
566
  }
561
567
  /**
562
568
  * The concept type name of a documentation surface.
@@ -596,7 +602,7 @@ export declare class Publications {
596
602
  /** The `renders` entries of a Publication, or `undefined` when malformed. */
597
603
  static readonly rendersOf: (concept: LoadedConcept) => ReadonlyArray<RendersEntry> | undefined;
598
604
  /** Lints every Publication in `bundle`; diagnostics are sorted by file then code. */
599
- static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, PlatformError.PlatformError, Crypto.Crypto>;
605
+ static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, PlatformError.PlatformError, Digest$1.Digest>;
600
606
  }
601
607
  /**
602
608
  * Whether a concept's human verification still covers its content: `none` (no
@@ -608,12 +614,14 @@ export declare class Publications {
608
614
  type IntegrityState = "current" | "drifted" | "none";
609
615
  /**
610
616
  * Why a human verification no longer binds: the content changed, the entry has
611
- * no `integrity.verified` binding, a later human entry is not the bound one, or
612
- * the bound actor fails a non-empty `[actors].humans` allow-list.
617
+ * no `integrity.verified` binding, a later human entry is not the bound one, the
618
+ * bound actor fails a non-empty `[actors].humans` allow-list, or the content
619
+ * cannot be hashed at all (an unpaired surrogate; okfit#327), so the binding
620
+ * cannot be checked.
613
621
  *
614
622
  * @public
615
623
  */
616
- export declare const DriftReason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed"]>;
624
+ export declare const DriftReason: Schema.Literals<readonly ["content-changed", "unbound", "entry-superseded", "actor-not-allowed", "content-unhashable"]>;
617
625
  /**
618
626
  * The type of {@link (DriftReason:variable)}.
619
627
  * @public
@@ -633,6 +641,11 @@ interface ConceptSignal {
633
641
  readonly reason: DriftReason;
634
642
  readonly editedBy?: Actor;
635
643
  readonly editedAt?: string;
644
+ /** For `content-unhashable`: why, and the offending frontmatter path. */
645
+ readonly unhashable?: {
646
+ readonly detail: string;
647
+ readonly path: ReadonlyArray<string | number>;
648
+ };
636
649
  };
637
650
  readonly stale: boolean;
638
651
  }
@@ -670,9 +683,9 @@ interface EvaluateInput {
670
683
  export declare class Trust {
671
684
  private constructor();
672
685
  /** The signal for one concept under `config`; hashes only when a human entry is bound by an allowed actor. */
673
- static readonly signal: (concept: LoadedConcept, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<ConceptSignal, PlatformError.PlatformError, Crypto.Crypto>;
686
+ static readonly signal: (concept: LoadedConcept, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<ConceptSignal, never, Digest$1.Digest>;
674
687
  /** The signal for every concept in a bundle, keyed by concept id. */
675
- static readonly signals: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<Map<string, ConceptSignal>, PlatformError.PlatformError, Crypto.Crypto>;
688
+ static readonly signals: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc) => Effect.Effect<Map<string, ConceptSignal>, never, Digest$1.Digest>;
676
689
  /** Pure integrity decision; no hashing. `content` may be `undefined` only when {@link Trust.needsDigest} is false. */
677
690
  static readonly evaluate: (input: EvaluateInput, content: string | undefined) => {
678
691
  readonly integrity: IntegrityState;
@@ -687,7 +700,7 @@ export declare class Trust {
687
700
  * Given `signals` (from {@link Trust.signals}) it reuses each concept's entry and hashes nothing for it;
688
701
  * a concept absent from `signals` falls back to computing its own signal (hashing if it needs a digest).
689
702
  */
690
- static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc, signals?: ReadonlyMap<string, ConceptSignal>) => Effect.Effect<Array<Diagnostic>, PlatformError.PlatformError, Crypto.Crypto>;
703
+ static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, now: DateTime.Utc, signals?: ReadonlyMap<string, ConceptSignal>) => Effect.Effect<Array<Diagnostic>, never, Digest$1.Digest>;
691
704
  }
692
705
  export type { ConceptSignal, DocsPreset, EvaluateInput, GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, IntegrityState, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, RendersEntry, SurfaceTemplate, UncommittedReason, VerifierError, Writer };
693
706
  //# sourceMappingURL=index.d.ts.map
package/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { BodyCommitted, BodyProvenance, BodyUncommitted } from "./BodyProvenance.js";
2
- import { Canonical } from "./Canonical.js";
2
+ import { Canonical, ContentUnhashableError } from "./Canonical.js";
3
3
  import { GitHistory, GitHistoryError, PathHistoryEntry } from "./GitHistory.js";
4
4
  import { ActorConfigInvalidError, AgentActorUnconfiguredError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError } from "./Derivation.js";
5
5
  import { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode } from "./Profile.js";
@@ -8,4 +8,4 @@ import { Provenance } from "./Provenance.js";
8
8
  import { PUBLICATION_TYPE, Publications, SURFACE_TYPE } from "./Publications.js";
9
9
  import { DriftReason, Trust } from "./Trust.js";
10
10
 
11
- export { ActorConfigInvalidError, AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Canonical, Derivation, DriftReason, GitHistory, GitHistoryError, HumanActorNotAllowedError, HumanActorUnresolvedError, PROFILE_NAMES, PUBLICATION_TYPE, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance, Publications, SURFACE_TYPE, Trust };
11
+ export { ActorConfigInvalidError, AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Canonical, ContentUnhashableError, Derivation, DriftReason, GitHistory, GitHistoryError, HumanActorNotAllowedError, HumanActorUnresolvedError, PROFILE_NAMES, PUBLICATION_TYPE, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance, Publications, SURFACE_TYPE, Trust };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@okfit/profiles",
3
- "version": "0.12.0",
3
+ "version": "0.14.0",
4
4
  "private": false,
5
5
  "description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
6
6
  "keywords": [
@@ -35,13 +35,14 @@
35
35
  "./package.json": "./package.json"
36
36
  },
37
37
  "peerDependencies": {
38
- "@effected/git": "^0.26.0",
39
- "@effected/glob": "^0.15.0",
40
- "@effected/jsonc": "^0.20.0",
41
- "@effected/markdown": "^0.23.0",
42
- "@effected/walker": "^0.21.0",
43
- "@okfit/core": "^0.11.7",
44
- "effect": "^4.0.0"
38
+ "@effected/git": "^0.29.0",
39
+ "@effected/glob": "^0.17.0",
40
+ "@effected/jsonc": "^0.22.0",
41
+ "@effected/markdown": "^0.25.0",
42
+ "@effected/source": "^0.2.0",
43
+ "@effected/walker": "^0.24.0",
44
+ "@okfit/core": "^0.12.0",
45
+ "effect": "~4.1.1"
45
46
  },
46
47
  "engines": {
47
48
  "node": ">=24.11.0"
@@ -5,7 +5,7 @@
5
5
  "toolPackages": [
6
6
  {
7
7
  "packageName": "@microsoft/api-extractor",
8
- "packageVersion": "7.59.4"
8
+ "packageVersion": "7.60.0"
9
9
  }
10
10
  ]
11
11
  }