@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 +44 -24
- package/Derivation.js +12 -25
- package/README.md +1 -1
- package/Trust.js +35 -10
- package/index.d.ts +45 -32
- package/index.js +2 -2
- package/package.json +9 -8
- package/tsdoc-metadata.json +1 -1
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
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
*
|
|
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
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
/**
|
|
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 {
|
|
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) =>
|
|
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
|
-
*
|
|
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 =
|
|
182
|
-
*
|
|
183
|
-
*
|
|
184
|
-
*
|
|
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
|
|
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
|
|
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,
|
|
10
|
-
*
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
|
-
/**
|
|
71
|
-
static readonly
|
|
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,
|
|
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
|
-
*
|
|
303
|
+
* core's platform-agnostic `Digest` service.
|
|
291
304
|
*/
|
|
292
|
-
static readonly digest: (text: string) => Effect.Effect<Digest,
|
|
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,
|
|
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
|
|
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 =
|
|
321
|
-
*
|
|
322
|
-
*
|
|
323
|
-
*
|
|
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 |
|
|
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,
|
|
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,
|
|
612
|
-
*
|
|
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,
|
|
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>,
|
|
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>,
|
|
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.
|
|
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.
|
|
39
|
-
"@effected/glob": "^0.
|
|
40
|
-
"@effected/jsonc": "^0.
|
|
41
|
-
"@effected/markdown": "^0.
|
|
42
|
-
"@effected/
|
|
43
|
-
"@
|
|
44
|
-
"
|
|
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"
|