@okfit/profiles 0.14.6 → 0.15.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,6 +1,6 @@
1
- import { body } from "./internal/body.js";
2
- import { Result, Schema } from "effect";
3
1
  import { JsoncCanonicalizeOptions, JsoncFingerprint } from "@effected/jsonc";
2
+ import { Result, Schema } from "effect";
3
+ import { body } from "./internal/body.js";
4
4
 
5
5
  // src/Canonical.ts
6
6
  /** Top-level keys that are bookkeeping, not authored content (spec section 4). */
package/Derivation.js CHANGED
@@ -1,10 +1,11 @@
1
+ import { Git } from "@effected/git";
2
+ import { relativeWithin } from "@effected/walker";
3
+ import { Actor, OkfitConfig } from "@okfit/core";
4
+ import { DateTime, Duration, Effect, FileSystem, Option, Path, Schema } from "effect";
5
+ import { Digest } from "effect/crypto";
1
6
  import { Canonical } from "./Canonical.js";
2
7
  import { GitHistory } from "./GitHistory.js";
3
8
  import { body } from "./internal/body.js";
4
- import { Actor, OkfitConfig } from "@okfit/core";
5
- import { DateTime, Duration, Effect, FileSystem, Option, Path, Schema } from "effect";
6
- import { JsoncFingerprint } from "@effected/jsonc";
7
- import { Git } from "@effected/git";
8
9
 
9
10
  // src/Derivation.ts
10
11
  /**
@@ -59,10 +60,26 @@ var HumanActorNotAllowedError = class extends Schema.TaggedError()("HumanActorNo
59
60
  return `${this.actor} is not in [actors].humans, so it cannot verify or revoke; set your id with git config --global okfit.actor human:<id> to a listed id, or add ${this.actor} to [actors].humans`;
60
61
  }
61
62
  };
63
+ /**
64
+ * The concept file resolves outside the repository (an escaping symlink), or containment in the
65
+ * repository cannot be proved, so no repo-relative path exists to date it by (#351). `root` is the
66
+ * repository's real top level; `file` is the path as given.
67
+ *
68
+ * @public
69
+ */
70
+ var ConceptOutsideRepositoryError = class extends Schema.TaggedError()("ConceptOutsideRepositoryError", {
71
+ file: Schema.String,
72
+ root: Schema.String
73
+ }) {
74
+ get message() {
75
+ return `concept file ${this.file} resolves outside the repository at ${this.root}, so its generated.at cannot be derived from git history`;
76
+ }
77
+ };
62
78
  const HUMAN_PREFIX = "human:";
63
79
  const FALLBACK_STALE_AFTER = Duration.days(90);
64
80
  const decodeActor = Schema.decodeSync(Actor);
65
- const digestFull = (text) => JsoncFingerprint.hashText(text);
81
+ const encoder = new TextEncoder();
82
+ const digestFull = (text) => Digest.Digest.use((d) => d.digestHex(Digest.sha256, encoder.encode(text)));
66
83
  const digest = (text) => Effect.map(digestFull(text), (hex) => hex.slice(0, 16));
67
84
  const bodyDigest = (source) => digest(body(source));
68
85
  const contentDigest = (raw, source) => Effect.flatMap(Effect.fromResult(Canonical.contentInput(raw, source)), digest);
@@ -168,8 +185,9 @@ var Derivation = class Derivation {
168
185
  * the root to the file's directory (okfit #315). On `NotARepositoryError` it retries with that
169
186
  * environment honoured, so a repository defined only by `GIT_DIR`/`GIT_WORK_TREE` still resolves; a file
170
187
  * outside any repository surfaces `NotARepositoryError`. Submodules and worktrees work because both are asked from the file's directory (P-39).
171
- * 2. `realPath` both (rev-parse is symlink-resolved), then the repo-relative posix path via `Path` (P-39).
172
- * 3. `worktree = body(readFileString(file))`.
188
+ * 2. `realPath` the root (rev-parse is symlink-resolved); `worktree = body(readFileString(file))`, read first so a missing
189
+ * file is a `PlatformError`; then the repo-relative posix path via `relativeWithin(realRoot, file, { missing: "refuse" })`,
190
+ * where `None` (escaping symlink, containment unprovable) fails {@link ConceptOutsideRepositoryError} (#351).
173
191
  * 4. `Git.show(realRoot, "HEAD", rel)`: `UnknownRefError` is `uncommitted { unborn }` (P-11), `Option.none`
174
192
  * is `uncommitted { untracked }` (P-47), a body differing from `worktree` is `uncommitted { dirty }` (P-9).
175
193
  * The comparison is against HEAD's blob, never the newest log entry (P-46).
@@ -185,13 +203,16 @@ var Derivation = class Derivation {
185
203
  const git = yield* Git;
186
204
  const history = yield* GitHistory;
187
205
  const fs = yield* FileSystem.FileSystem;
188
- const path = yield* Path.Path;
189
- const dir = path.dirname(options.file);
206
+ const dir = (yield* Path.Path).dirname(options.file);
190
207
  const root = yield* git.repoRoot(dir, { ignoreRepositoryEnv: true }).pipe(Effect.catchTag("NotARepositoryError", () => git.repoRoot(dir)));
191
208
  const realRoot = yield* fs.realPath(root);
192
- const realFile = yield* fs.realPath(options.file);
193
- const rel = path.relative(realRoot, realFile).split(path.sep).join("/");
194
209
  const worktree = body(yield* fs.readFileString(options.file));
210
+ const relOption = yield* relativeWithin(realRoot, options.file, { missing: "refuse" });
211
+ if (Option.isNone(relOption)) return yield* new ConceptOutsideRepositoryError({
212
+ file: options.file,
213
+ root: realRoot
214
+ });
215
+ const rel = relOption.value;
195
216
  const head = yield* git.show(realRoot, "HEAD", rel).pipe(Effect.map((blob) => ({
196
217
  unborn: false,
197
218
  blob
@@ -282,4 +303,4 @@ var Derivation = class Derivation {
282
303
  static staleAfter = staleAfter;
283
304
  };
284
305
 
285
- export { ActorConfigInvalidError, AgentActorUnconfiguredError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError };
306
+ export { ActorConfigInvalidError, AgentActorUnconfiguredError, ConceptOutsideRepositoryError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError };
package/GitHistory.js CHANGED
@@ -1,6 +1,6 @@
1
+ import { Git } from "@effected/git";
1
2
  import { Timestamp } from "@okfit/core";
2
3
  import { Context, Effect, Layer, Schema } from "effect";
3
- import { Git } from "@effected/git";
4
4
 
5
5
  // src/GitHistory.ts
6
6
  /**
package/Profiles.js CHANGED
@@ -1,5 +1,5 @@
1
- import { softwareProject } from "./SoftwareProject.js";
2
1
  import { Option } from "effect";
2
+ import { softwareProject } from "./SoftwareProject.js";
3
3
 
4
4
  // src/Profiles.ts
5
5
  const REGISTRY = /* @__PURE__ */ new Map([[softwareProject.name, softwareProject]]);
package/Provenance.js CHANGED
@@ -1,6 +1,6 @@
1
- import { Derivation } from "./Derivation.js";
2
1
  import { Diagnostic, DiagnosticRange, OkfitConfig, Timestamp } from "@okfit/core";
3
2
  import { DateTime, Effect, Path, Schema } from "effect";
3
+ import { Derivation } from "./Derivation.js";
4
4
 
5
5
  // src/Provenance.ts
6
6
  const encodeAt = Schema.encodeSync(Timestamp);
package/Publications.js CHANGED
@@ -1,6 +1,6 @@
1
- import { Derivation } from "./Derivation.js";
2
1
  import { ConceptId, Diagnostic, DiagnosticRange, OkfitConfig } from "@okfit/core";
3
2
  import { Effect, Option } from "effect";
3
+ import { Derivation } from "./Derivation.js";
4
4
 
5
5
  // src/Publications.ts
6
6
  /**
package/README.md CHANGED
@@ -211,6 +211,35 @@ kind = "path"
211
211
  [types.Publication.fields.renders]
212
212
  description = "The source concepts as a list of entries that each hold a path and a body digest; okfit sync --publication stamps each digest."
213
213
 
214
+ [types.Flow]
215
+ description = "A named runtime sequence that crosses several modules: where it starts, which modules it passes through in order, and how it fails."
216
+ guidance = "Write the steps in the order they happen and put the failure modes in the body, naming what a reader observes at each point it breaks. Distinct from Interface, which is a promise to consumers, from Runbook, which a person follows, and from Module, which owns one boundary rather than a sequence across several."
217
+
218
+ [types.Flow.fields.entry]
219
+ description = "A path relative to this concept file to the code or config where the sequence starts."
220
+ kind = "path"
221
+
222
+ [types.Flow.fields.crosses]
223
+ description = "The Module concepts the sequence passes through, as paths, in the order it reaches them."
224
+ kind = "path"
225
+
226
+ [types.Flow.fields.resource]
227
+ description = "A path relative to this concept file to the code, script, or config that implements the sequence end to end, when one place does."
228
+ kind = "path"
229
+
230
+ [types.Fixture]
231
+ description = "A stand-in for an external thing that tests or tooling depend on: a recorded response, a sample repository, a vendored sample."
232
+ guidance = "Name the external thing it stands in for, how it was captured, and what breaks when it drifts from the real one. Give it a staleness window, 90 days by default, since a fixture quietly diverges from what it imitates."
233
+ required = ["resource"]
234
+
235
+ [types.Fixture.fields.resource]
236
+ description = "A path relative to this concept file to the external thing the fixture stands in for, or to the fixture itself when it lives in this repository."
237
+ kind = "path"
238
+
239
+ [types.Fixture.fields.runbooks]
240
+ description = "The Runbook concepts that regenerate, refresh, or verify the fixture, as paths."
241
+ kind = "path"
242
+
214
243
  [tags.architecture]
215
244
  description = "Concerns the shape of the system rather than one module."
216
245
 
@@ -233,7 +262,7 @@ description = "Concerns the experience of the people and agents who author, buil
233
262
  description = "Concerns the unattended path: what runs without a human present, and how it fails."
234
263
 
235
264
  [tags.compat]
236
- description = "Concerns compatibility across versions of the runtime, the package manager, or a dependency."
265
+ description = "Concerns compatibility across versions of the runtime, the package manager, or a dependency, and portability across agent hosts, runtimes, and operating systems."
237
266
 
238
267
  [tags.bundle]
239
268
  description = "Concerns install weight and reachability: tree-shaking, subpath entrypoints, and dependency edges declined for their cost."
@@ -249,6 +278,9 @@ description = "Concerns the GitHub platform surface: the REST and GraphQL APIs,
249
278
 
250
279
  [tags.docs]
251
280
  description = "Concerns the documentation itself: provenance, rot, re-derivation, and what a claim would take to falsify."
281
+
282
+ [tags.config]
283
+ description = "Concerns the project's own user-facing configuration: file format, discovery and resolution, schema validation, defaults, and drift between config and behavior."
252
284
  ```
253
285
 
254
286
  Only `concepts`, `types`, and `tags` carry real vocabulary; the literal's `extensions: {}` is `OkfitConfig`'s one required key and never appears on disk, since the codec folds unknown top-level keys into it (P-24: `fields.<k>.kind = "path"` and the `tags` table are vocabulary only — core enforces none of it yet). `Reference.required = ["sources"]` checks presence only: `sources = []` passes, and each entry's shape is core's `family-invalid` (P-23).
@@ -279,6 +311,12 @@ directories:
279
311
  consumers/ -> Consumer
280
312
  roadmaps/ -> Roadmap
281
313
  measurements/ -> Measurement
314
+ invariants/ -> Invariant
315
+ incidents/ -> Incident
316
+ surfaces/ -> Surface
317
+ publications/ -> Publication
318
+ flows/ -> Flow
319
+ fixtures/ -> Fixture
282
320
  ```
283
321
 
284
322
  Each directory carries its own `index.md`. What `okfit init` writes into these files is the CLI plan's concern, not this package's.
@@ -1,5 +1,5 @@
1
- import { DOCS_PRESETS } from "./presets/index.js";
2
1
  import { DiagnosticRange } from "@okfit/core";
2
+ import { DOCS_PRESETS } from "./presets/index.js";
3
3
 
4
4
  // src/SoftwareProject.ts
5
5
  /**
@@ -227,6 +227,39 @@ const config = {
227
227
  },
228
228
  renders: { description: "The source concepts as a list of entries that each hold a path and a body digest; okfit sync --publication stamps each digest." }
229
229
  }
230
+ },
231
+ Flow: {
232
+ description: "A named runtime sequence that crosses several modules: where it starts, which modules it passes through in order, and how it fails.",
233
+ guidance: "Write the steps in the order they happen and put the failure modes in the body, naming what a reader observes at each point it breaks. Distinct from Interface, which is a promise to consumers, from Runbook, which a person follows, and from Module, which owns one boundary rather than a sequence across several.",
234
+ fields: {
235
+ entry: {
236
+ description: "A path relative to this concept file to the code or config where the sequence starts.",
237
+ kind: "path"
238
+ },
239
+ crosses: {
240
+ description: "The Module concepts the sequence passes through, as paths, in the order it reaches them.",
241
+ kind: "path"
242
+ },
243
+ resource: {
244
+ description: "A path relative to this concept file to the code, script, or config that implements the sequence end to end, when one place does.",
245
+ kind: "path"
246
+ }
247
+ }
248
+ },
249
+ Fixture: {
250
+ description: "A stand-in for an external thing that tests or tooling depend on: a recorded response, a sample repository, a vendored sample.",
251
+ guidance: "Name the external thing it stands in for, how it was captured, and what breaks when it drifts from the real one. Give it a staleness window, 90 days by default, since a fixture quietly diverges from what it imitates.",
252
+ required: ["resource"],
253
+ fields: {
254
+ resource: {
255
+ description: "A path relative to this concept file to the external thing the fixture stands in for, or to the fixture itself when it lives in this repository.",
256
+ kind: "path"
257
+ },
258
+ runbooks: {
259
+ description: "The Runbook concepts that regenerate, refresh, or verify the fixture, as paths.",
260
+ kind: "path"
261
+ }
262
+ }
230
263
  }
231
264
  },
232
265
  tags: {
@@ -237,12 +270,13 @@ const config = {
237
270
  performance: { description: "Concerns speed, memory, or resource cost and the trade-offs made for them." },
238
271
  dx: { description: "Concerns the experience of the people and agents who author, build, and debug the code." },
239
272
  ci: { description: "Concerns the unattended path: what runs without a human present, and how it fails." },
240
- compat: { description: "Concerns compatibility across versions of the runtime, the package manager, or a dependency." },
273
+ compat: { description: "Concerns compatibility across versions of the runtime, the package manager, or a dependency, and portability across agent hosts, runtimes, and operating systems." },
241
274
  bundle: { description: "Concerns install weight and reachability: tree-shaking, subpath entrypoints, and dependency edges declined for their cost." },
242
275
  observability: { description: "Concerns how the system reports on itself: events, metrics, logs, sinks, and artifacts." },
243
276
  deps: { description: "Concerns how third-party dependencies are declared, pinned, and distributed." },
244
277
  github: { description: "Concerns the GitHub platform surface: the REST and GraphQL APIs, Apps and installation tokens, Actions, Packages, check runs, and pull request conventions." },
245
- docs: { description: "Concerns the documentation itself: provenance, rot, re-derivation, and what a claim would take to falsify." }
278
+ docs: { description: "Concerns the documentation itself: provenance, rot, re-derivation, and what a claim would take to falsify." },
279
+ config: { description: "Concerns the project's own user-facing configuration: file format, discovery and resolution, schema validation, defaults, and drift between config and behavior." }
246
280
  },
247
281
  extensions: {}
248
282
  };
@@ -321,6 +355,14 @@ const layout = {
321
355
  {
322
356
  directory: "publications",
323
357
  type: "Publication"
358
+ },
359
+ {
360
+ directory: "flows",
361
+ type: "Flow"
362
+ },
363
+ {
364
+ directory: "fixtures",
365
+ type: "Fixture"
324
366
  }
325
367
  ]
326
368
  };
package/Trust.js CHANGED
@@ -1,6 +1,6 @@
1
- import { Derivation } from "./Derivation.js";
2
1
  import { Actor, Derive, Diagnostic, DiagnosticRange, OkfitConfig, Timestamp } from "@okfit/core";
3
2
  import { DateTime, Effect, Result, Schema } from "effect";
3
+ import { Derivation } from "./Derivation.js";
4
4
 
5
5
  // src/Trust.ts
6
6
  const encodeAt = Schema.encodeSync(Timestamp);
package/index.d.ts CHANGED
@@ -232,6 +232,20 @@ declare const HumanActorNotAllowedError_base: Schema.Class<HumanActorNotAllowedE
232
232
  export declare class HumanActorNotAllowedError extends HumanActorNotAllowedError_base {
233
233
  get message(): string;
234
234
  }
235
+ declare const ConceptOutsideRepositoryError_base: Schema.Class<ConceptOutsideRepositoryError, Schema.TaggedStruct<"ConceptOutsideRepositoryError", {
236
+ readonly file: Schema.String;
237
+ readonly root: Schema.String;
238
+ }>, import("effect/Cause").YieldableError>;
239
+ /**
240
+ * The concept file resolves outside the repository (an escaping symlink), or containment in the
241
+ * repository cannot be proved, so no repo-relative path exists to date it by (#351). `root` is the
242
+ * repository's real top level; `file` is the path as given.
243
+ *
244
+ * @public
245
+ */
246
+ export declare class ConceptOutsideRepositoryError extends ConceptOutsideRepositoryError_base {
247
+ get message(): string;
248
+ }
235
249
  /**
236
250
  * Options for {@link Derivation.generatedAt} (P-39).
237
251
  *
@@ -245,12 +259,13 @@ interface GeneratedAtOptions {
245
259
  }
246
260
  /**
247
261
  * Everything {@link Derivation.generatedAt} can fail with: profiles' own
248
- * `GitHistoryError`, the `@effected/git` peer's errors (P-12), and the
249
- * `PlatformError` of `realPath`/`readFileString` on `file`.
262
+ * `GitHistoryError`, the `@effected/git` peer's errors (P-12), the
263
+ * `PlatformError` of `realPath`/`readFileString` on `file`, and
264
+ * {@link ConceptOutsideRepositoryError} when `file` resolves outside the repository (#351).
250
265
  *
251
266
  * @public
252
267
  */
253
- type GeneratedAtError = GitHistoryError | GitCommandError | NotARepositoryError | UnknownRefError | PlatformError.PlatformError;
268
+ type GeneratedAtError = GitHistoryError | GitCommandError | NotARepositoryError | UnknownRefError | ConceptOutsideRepositoryError | PlatformError.PlatformError;
254
269
  /**
255
270
  * Options for {@link Derivation.generatedBy} (P-16, P-45).
256
271
  *
@@ -334,8 +349,9 @@ export declare class Derivation {
334
349
  * the root to the file's directory (okfit #315). On `NotARepositoryError` it retries with that
335
350
  * environment honoured, so a repository defined only by `GIT_DIR`/`GIT_WORK_TREE` still resolves; a file
336
351
  * outside any repository surfaces `NotARepositoryError`. Submodules and worktrees work because both are asked from the file's directory (P-39).
337
- * 2. `realPath` both (rev-parse is symlink-resolved), then the repo-relative posix path via `Path` (P-39).
338
- * 3. `worktree = body(readFileString(file))`.
352
+ * 2. `realPath` the root (rev-parse is symlink-resolved); `worktree = body(readFileString(file))`, read first so a missing
353
+ * file is a `PlatformError`; then the repo-relative posix path via `relativeWithin(realRoot, file, { missing: "refuse" })`,
354
+ * where `None` (escaping symlink, containment unprovable) fails {@link ConceptOutsideRepositoryError} (#351).
339
355
  * 4. `Git.show(realRoot, "HEAD", rel)`: `UnknownRefError` is `uncommitted { unborn }` (P-11), `Option.none`
340
356
  * is `uncommitted { untracked }` (P-47), a body differing from `worktree` is `uncommitted { dirty }` (P-9).
341
357
  * The comparison is against HEAD's blob, never the newest log entry (P-46).
@@ -569,7 +585,7 @@ export declare class Provenance {
569
585
  private constructor();
570
586
  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig, options?: {
571
587
  readonly skipGitTier?: boolean;
572
- }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Digest$1.Digest>;
588
+ }) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | ConceptOutsideRepositoryError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path | Digest$1.Digest>;
573
589
  }
574
590
  /**
575
591
  * The concept type name of a documentation surface.
package/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import { BodyCommitted, BodyProvenance, BodyUncommitted } from "./BodyProvenance.js";
2
2
  import { Canonical, ContentUnhashableError } from "./Canonical.js";
3
- import { ActorConfigInvalidError, AgentActorUnconfiguredError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError } from "./Derivation.js";
3
+ import { ActorConfigInvalidError, AgentActorUnconfiguredError, ConceptOutsideRepositoryError, Derivation, HumanActorNotAllowedError, HumanActorUnresolvedError } from "./Derivation.js";
4
4
  import { GitHistory, GitHistoryError, PathHistoryEntry } from "./GitHistory.js";
5
5
  import { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode } from "./Profile.js";
6
6
  import { Profiles } from "./Profiles.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, ContentUnhashableError, 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, ConceptOutsideRepositoryError, 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.14.6",
3
+ "version": "0.15.0",
4
4
  "private": false,
5
5
  "description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
6
6
  "keywords": [
@@ -36,12 +36,12 @@
36
36
  },
37
37
  "peerDependencies": {
38
38
  "@effected/git": "^0.32.0",
39
- "@effected/glob": "^0.22.0",
39
+ "@effected/glob": "^0.23.0",
40
40
  "@effected/jsonc": "^0.25.0",
41
41
  "@effected/markdown": "^0.29.0",
42
42
  "@effected/source": "^0.5.0",
43
- "@effected/walker": "^0.29.0",
44
- "@okfit/core": "^0.13.4",
43
+ "@effected/walker": "^0.30.0",
44
+ "@okfit/core": "^0.14.0",
45
45
  "effect": "~4.1.0"
46
46
  },
47
47
  "engines": {