@okfit/profiles 0.13.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 +5 -4
- package/README.md +1 -1
- package/Trust.js +35 -10
- package/index.d.ts +40 -19
- package/index.js +2 -2
- package/package.json +9 -9
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,8 +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";
|
|
7
|
+
import { Git } from "@effected/git";
|
|
8
8
|
|
|
9
9
|
// src/Derivation.ts
|
|
10
10
|
/**
|
|
@@ -65,7 +65,7 @@ const decodeActor = Schema.decodeSync(Actor);
|
|
|
65
65
|
const digestFull = (text) => JsoncFingerprint.hashText(text);
|
|
66
66
|
const digest = (text) => Effect.map(digestFull(text), (hex) => hex.slice(0, 16));
|
|
67
67
|
const bodyDigest = (source) => digest(body(source));
|
|
68
|
-
const contentDigest = (raw, source) =>
|
|
68
|
+
const contentDigest = (raw, source) => Effect.flatMap(Effect.fromResult(Canonical.contentInput(raw, source)), digest);
|
|
69
69
|
/** The text before the first `@` (the whole value when there is none), or undefined when empty or containing whitespace. */
|
|
70
70
|
const localPartOf = (email) => {
|
|
71
71
|
if (email === void 0) return void 0;
|
|
@@ -141,7 +141,7 @@ var Derivation = class Derivation {
|
|
|
141
141
|
static digestFull = digestFull;
|
|
142
142
|
/**
|
|
143
143
|
* The okfit digest of a string: the first 16 lowercase hex characters of its SHA-256, through
|
|
144
|
-
*
|
|
144
|
+
* core's platform-agnostic `Digest` service.
|
|
145
145
|
*/
|
|
146
146
|
static digest = digest;
|
|
147
147
|
/**
|
|
@@ -157,7 +157,8 @@ var Derivation = class Derivation {
|
|
|
157
157
|
static recordedBody = (concept) => concept.frontmatter.integrity?.generated?.body ?? concept.frontmatter.generated?.body_sha256?.slice(0, 16);
|
|
158
158
|
/**
|
|
159
159
|
* 16-hex digest of the canonical content input (`Canonical.contentInput`): authored frontmatter
|
|
160
|
-
* 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).
|
|
161
162
|
*/
|
|
162
163
|
static contentDigest = contentDigest;
|
|
163
164
|
/**
|
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,9 +316,10 @@ 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.
|
|
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).
|
|
307
321
|
*/
|
|
308
|
-
static readonly contentDigest: (raw: Readonly<Record<string, unknown>>, source: string) => Effect.Effect<Digest,
|
|
322
|
+
static readonly contentDigest: (raw: Readonly<Record<string, unknown>>, source: string) => Effect.Effect<Digest, ContentUnhashableError, Digest$1.Digest>;
|
|
309
323
|
/**
|
|
310
324
|
* Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
|
|
311
325
|
* 1. `root = Git.repoRoot(dirname(file), { ignoreRepositoryEnv: true })`: the option drops the
|
|
@@ -548,7 +562,7 @@ export declare class Provenance {
|
|
|
548
562
|
private constructor();
|
|
549
563
|
static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, options?: {
|
|
550
564
|
readonly skipGitTier?: boolean;
|
|
551
|
-
}) => 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>;
|
|
552
566
|
}
|
|
553
567
|
/**
|
|
554
568
|
* The concept type name of a documentation surface.
|
|
@@ -588,7 +602,7 @@ export declare class Publications {
|
|
|
588
602
|
/** The `renders` entries of a Publication, or `undefined` when malformed. */
|
|
589
603
|
static readonly rendersOf: (concept: LoadedConcept) => ReadonlyArray<RendersEntry> | undefined;
|
|
590
604
|
/** Lints every Publication in `bundle`; diagnostics are sorted by file then code. */
|
|
591
|
-
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>;
|
|
592
606
|
}
|
|
593
607
|
/**
|
|
594
608
|
* Whether a concept's human verification still covers its content: `none` (no
|
|
@@ -600,12 +614,14 @@ export declare class Publications {
|
|
|
600
614
|
type IntegrityState = "current" | "drifted" | "none";
|
|
601
615
|
/**
|
|
602
616
|
* Why a human verification no longer binds: the content changed, the entry has
|
|
603
|
-
* no `integrity.verified` binding, a later human entry is not the bound one,
|
|
604
|
-
*
|
|
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.
|
|
605
621
|
*
|
|
606
622
|
* @public
|
|
607
623
|
*/
|
|
608
|
-
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"]>;
|
|
609
625
|
/**
|
|
610
626
|
* The type of {@link (DriftReason:variable)}.
|
|
611
627
|
* @public
|
|
@@ -625,6 +641,11 @@ interface ConceptSignal {
|
|
|
625
641
|
readonly reason: DriftReason;
|
|
626
642
|
readonly editedBy?: Actor;
|
|
627
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
|
+
};
|
|
628
649
|
};
|
|
629
650
|
readonly stale: boolean;
|
|
630
651
|
}
|
|
@@ -662,9 +683,9 @@ interface EvaluateInput {
|
|
|
662
683
|
export declare class Trust {
|
|
663
684
|
private constructor();
|
|
664
685
|
/** The signal for one concept under `config`; hashes only when a human entry is bound by an allowed actor. */
|
|
665
|
-
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>;
|
|
666
687
|
/** The signal for every concept in a bundle, keyed by concept id. */
|
|
667
|
-
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>;
|
|
668
689
|
/** Pure integrity decision; no hashing. `content` may be `undefined` only when {@link Trust.needsDigest} is false. */
|
|
669
690
|
static readonly evaluate: (input: EvaluateInput, content: string | undefined) => {
|
|
670
691
|
readonly integrity: IntegrityState;
|
|
@@ -679,7 +700,7 @@ export declare class Trust {
|
|
|
679
700
|
* Given `signals` (from {@link Trust.signals}) it reuses each concept's entry and hashes nothing for it;
|
|
680
701
|
* a concept absent from `signals` falls back to computing its own signal (hashing if it needs a digest).
|
|
681
702
|
*/
|
|
682
|
-
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>;
|
|
683
704
|
}
|
|
684
705
|
export type { ConceptSignal, DocsPreset, EvaluateInput, GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, IntegrityState, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, RendersEntry, SurfaceTemplate, UncommittedReason, VerifierError, Writer };
|
|
685
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,14 +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/source": "^0.
|
|
43
|
-
"@effected/walker": "^0.
|
|
44
|
-
"@okfit/core": "^0.
|
|
45
|
-
"effect": "
|
|
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"
|
|
46
46
|
},
|
|
47
47
|
"engines": {
|
|
48
48
|
"node": ">=24.11.0"
|