@bevel-software/platform-core-backend 0.32.0 → 0.34.0

package/dist/modules/access/reference-scan.d.ts

@@ -3,9 +3,15 @@
  * services (roles + groups) drive for "which access rules name this
  * principal" and "rewrite every reference atomically":
  *
- *   - `findRoleRefsInText` / `rewriteRoleTokensInText`: the config-region
- *     parse that decides what IS a principal reference. One source of truth,
- *     so the delete/rename warning and the rename rewrite can never disagree.
+ *   - `resolverRoleRefs`: what IS a principal reference — the resolver's own
+ *     parse of each file, so the reports name every enforced rule.
+ *   - `findRoleRefsInText` / `rewriteRoleTokensInText`: the line-level walk
+ *     the rename edits text with. It handles block lists and `key: value`
+ *     entries; quoted and flow-YAML own frontmatter is rewritten by the
+ *     full parser's own tree (`rewriteOwnFrontmatterStructurally`). The
+ *     rewrite re-checks its result with `resolverRoleRefs` and refuses
+ *     when a reference survives, so the warning and the rename can never
+ *     disagree.
  *   - `KbReferenceScanner`: candidate collection (every KB file with an
  *     access-frontmatter extension — `.md` and `.tool`, the resolver's own
  *     set), the advisory reference scan (cached — roster mutations must not
@@ -14,16 +20,18 @@
  *     file's ORIGINAL text too, so rollback snapshots reuse the read the
  *     rewrite already did instead of a second full-KB pass).
  *
- * Tokens here are the ENTRY-GRAMMAR canonical tokens: a bare name (group
- * first, then role) or an explicit `role/<name>`. Callers translate: a ROLE's
- * references are its bare token plus its `role/` token; a GROUP's are its
- * bare token only.
+ * Tokens here are the ENTRY-GRAMMAR canonical tokens: a bare name (the role
+ * when one exists, else the group) or an explicit `role/<name>` /
+ * `group/<name>`. Callers translate: a ROLE's references are its bare token
+ * plus its `role/` token; a GROUP's are its `group/` token, plus the bare
+ * token while no role shares the name.
  */
 import { type IWorkspaceService } from '@bevel-software/platform-shared';
+import type { ITreeWalker } from '../../shared/fs.contract.js';
 /**
  * Every genuine role/group reference in `text`'s rule regions, as
- * {role, verb} where `role` is the canonical ENTRY TOKEN (bare name or
- * `role/<name>`). `isAccessMd` marks an `access.md` file, whose BODY is a
+ * {role, verb} where `role` is the canonical ENTRY TOKEN (bare name,
+ * `role/<name>` or `group/<name>`). `isAccessMd` marks an `access.md` file, whose BODY is a
  * rule source in the body-governed format — see {@link ruleLineRanges}.
  */
 export declare function findRoleRefsInText(text: string, isMarkdown?: boolean, isAccessMd?: boolean): {
@@ -45,6 +53,20 @@ export declare function findRoleRefsInText(text: string, isMarkdown?: boolean, i
  * frontmatter; pass false only for a pure-config file with no body.
  */
 export declare function rewriteRoleTokensInText(text: string, oldToken: string, newDisplayName: string, isMarkdown?: boolean, isAccessMd?: boolean): string;
+/**
+ * The principal references the RESOLVER reads from one candidate file, by
+ * the resolver's own parsers: an `access.md`'s folder rules
+ * (`parseAccessFile`) and its self-rules (`accessMdSelfEntries`), any other
+ * file's own frontmatter (`parseOwnAccessEntries`). Those parsers read
+ * quoted scalars and flow sequences (`read: ["Admin"]`) the line walker
+ * above does not, so the reports built on this name every rule that is
+ * actually enforced — and nothing the resolver ignores (a broken
+ * `access.md` is dropped from the model, so it references nothing).
+ */
+export declare function resolverRoleRefs(text: string, repoRel: string): {
+    role: string;
+    verb: string;
+}[];
 export interface ReferenceHit {
     path: string;
     verb: string;
@@ -56,6 +78,44 @@ export interface ReferenceRewrite {
     content: string;
     original: string;
 }
+/**
+ * Which of the given repo-relative paths the person a refusal is for may
+ * read — `canReadBatch` bound to that person. A path is itself a disclosure,
+ * so a refusal names only these and says nothing of the rest.
+ */
+export type PathVisibility = (repoRelPaths: string[]) => Promise<ReadonlyMap<string, boolean>>;
+/**
+ * The one refusal for a rename blocked by a place the renaming person may
+ * not be shown — a folder the walk cannot list, a file it cannot read, or a
+ * file the person may not read that still names the old principal after the
+ * rewrite (a backstop: every form the resolver reads is rewritten). The same
+ * words whatever the cause: no path, no count, no hint of a reference, since
+ * Admin status does not grant read and each of those is a disclosure. The
+ * log names the place.
+ */
+export declare const UNSHOWN_REFERENCE_REFUSAL = "This rename rewrites access rules across the knowledge base, and part of the knowledge base could not be rewritten, so it may still reference the old principal; rename aborted with no changes. The server log names where.";
+/**
+ * The commit's own write gate refusing a rename's rewrite, translated for the
+ * person who asked. The gate judges every file the rewrite touches against the
+ * actor's WRITE rules (a rename's references reach files private to others,
+ * which an Admin may be unable to write), and its refusal names the file. A
+ * file its person may read keeps that refusal: the path and its eligible
+ * writers say whom to ask. A file they may not read gets
+ * `UNSHOWN_REFERENCE_REFUSAL` instead, so the hidden path stays unnamed; the
+ * log names it. Anything else comes back unchanged.
+ *
+ * The one bit left (some file the person cannot see names the old principal)
+ * is the hidden-blocker exception of "A Guard's Answer Is a Disclosure": an
+ * Admin's refused rename of a principal they manage says only that an unshown
+ * place blocks it.
+ */
+export declare function translateRewriteWriteRefusal(err: unknown, visible: PathVisibility, makeError: (message: string) => Error): Promise<unknown>;
+/**
+ * The rows of `refs` whose file `readable` allows. The rest are dropped
+ * outright, not counted: Admin status does not grant read, so even a count of
+ * rules in content the viewer cannot read is a disclosure.
+ */
+export declare function readableReferences(refs: readonly ReferenceHit[], readable: ReadonlyMap<string, boolean>): ReferenceHit[];
 /**
  * The slice of the workflow event bus the scanner taps for cache
  * invalidation. Structural (not the concrete class) so test doubles and the
@@ -88,6 +148,8 @@ export interface ReferenceScanInvalidationBus {
  */
 export declare class KbReferenceScanner {
     private readonly workspaceService;
+    /** The resolver's walk (see `collectCandidateFiles`), injected by the composition root. */
+    private readonly disk;
     private readonly kbDirName;
     private readonly cache;
     /**
@@ -100,7 +162,9 @@ export declare class KbReferenceScanner {
      * so the map never accumulates workspaces.
      */
     private readonly inFlight;
-    constructor(workspaceService: IWorkspaceService, kbDirName: string, eventBus?: ReferenceScanInvalidationBus);
+    constructor(workspaceService: IWorkspaceService, 
+    /** The resolver's walk (see `collectCandidateFiles`), injected by the composition root. */
+    disk: ITreeWalker, kbDirName: string, eventBus?: ReferenceScanInvalidationBus);
     invalidate(workspaceId: string): void;
     /**
      * Repo-relative paths of every file that could carry a principal reference:
@@ -108,34 +172,62 @@ export declare class KbReferenceScanner {
      * resolver reads access verbs from — the shared
      * `ACCESS_FRONTMATTER_EXTENSIONS` set (`.md` AND `.tool`; a rename that
      * skipped `.tool` would strand a live frontmatter grant there). Sourced
-     * from the workspace file tree (which already skips `.git` and honours
-     * `.bevelignore`), filtered under the KB dir and returned bare
-     * repo-relative. (`roles.yaml` matches no scanned extension, so it's
-     * excluded; callers commit it separately.) Under save=share the working
-     * tree matches the committed set, so this is the same candidate list
-     * git-tracking would give.
+     * from the RESOLVER'S OWN walk (`walkKb`: dot-entries and vendored
+     * dependencies skipped, `.bevelignore` NOT honoured) — the resolver
+     * enforces an `access.md` the explorer hides, so a scan that honoured the
+     * ignore file would leave its rules out of the roster's reports and a
+     * rename would strand them. Paths are relative to the KB dir. (`roles.yaml`
+     * matches no scanned extension, so it's excluded; callers commit it
+     * separately.)
+     *
+     * `holes` names every folder the walk could not list: the candidate set
+     * is INCOMPLETE when it is non-empty, and each caller decides what that
+     * means — the rewrite refuses, the advisory scan says so and does not cache.
      */
-    collectCandidateFiles(workspaceId: string): Promise<string[]>;
+    collectCandidateFiles(workspaceId: string): Promise<{
+        files: string[];
+        holes: string[];
+    }>;
     /**
      * Sound scan of EVERY candidate file (folder `access.md` + `.md`/`.tool`
      * node frontmatter) for genuine principal references, indexed by canonical
-     * entry TOKEN. Shares the
-     * candidate set and the config-region parse with the rename rewrite, so the
-     * delete warning and the rewrite see the SAME references. A file we cannot
-     * read is skipped (this is an advisory read, not the atomic write path).
+     * entry TOKEN, read by the resolver's own parse ({@link resolverRoleRefs}).
+     * Shares the candidate set with the rename rewrite, and the rewrite checks
+     * its result against the same parse, so the delete warning and the rewrite
+     * cannot disagree on what references a principal. A file we cannot
+     * read is skipped (this is an advisory read, not the atomic write path),
+     * and the scan that skipped it is not cached.
      * Cached per workspace (see class doc); reads are batched with Promise.all
      * rather than serial per-file awaits.
      */
     scan(workspaceId: string): Promise<Map<string, ReferenceHit[]>>;
     /**
-     * Find every genuine reference to `oldToken` and rewrite it to
-     * `newDisplayName`. FAIL-CLOSED: a candidate we cannot read might reference
+     * Find every genuine reference to `oldToken` (or any of several spellings
+     * of one principal) and rewrite it to `newDisplayName`. FAIL-CLOSED: a candidate we cannot read might reference
      * the old token, and skipping it would commit a partial rewrite (a
      * half-renamed principal still pointed at by stragglers = silent access
      * drop) — so any read failure aborts via `makeError` with nothing written.
      * Returns the writes WITH each file's original text (rollback snapshots).
+     *
+     * The rename keeps the KB's references to a principal whole, so it rewrites
+     * every candidate, files its person may not read included: a file private
+     * to others blocks nothing here, and no answer of this method depends on
+     * what such a file holds. Whether the person may WRITE each rewritten file
+     * is the commit's gate to decide, not this method's (see
+     * `translateRewriteWriteRefusal`). Every form the resolver reads
+     * is rewritten — block lists and `key: value` by the line walk, quoted and
+     * flow-YAML own frontmatter by the structural rewrite — so there is no
+     * "cannot rewrite" answer for hidden content to give. The writes reach a
+     * caller only through surfaces gated on read (the roster, the event
+     * delivery), never through this method's answer.
+     *
+     * A reference the resolver still sees after both rewrites is refused: named
+     * with how to fix it when `visible` says its person may read the file, with
+     * `UNSHOWN_REFERENCE_REFUSAL` otherwise (no path, no count). Nothing the
+     * resolver reads should reach that, so the refusal is a backstop, not an
+     * answer the content of a hidden file can choose.
      */
-    rewriteReferences(workspaceId: string, oldToken: string, newDisplayName: string, makeError: (message: string, cause?: string) => Error): Promise<ReferenceRewrite[]>;
+    rewriteReferences(workspaceId: string, oldToken: string | readonly string[], newDisplayName: string, makeError: (message: string, cause?: string) => Error, visible: PathVisibility): Promise<ReferenceRewrite[]>;
     private repoDir;
 }
 //# sourceMappingURL=reference-scan.d.ts.map

package/dist/modules/access/reference-scan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference-scan.d.ts","sourceRoot":"","sources":["../../../src/modules/access/reference-scan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH,OAAO,EAA0C,KAAK,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAoNjH;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,UAAU,UAAO,EACjB,UAAU,UAAQ,GACjB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAE,CAQlC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,UAAU,UAAO,EACjB,UAAU,UAAQ,GACjB,MAAM,CAcR;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;mEACmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAOD;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,yEAAyE;IACzE,MAAM,CAAC,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACvG;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAkB;IAiB3B,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS;IAjB5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IACJ;;;;;;;;OAQG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqD;gBAG3D,gBAAgB,EAAE,iBAAiB,EACnC,SAAS,EAAE,MAAM,EAClC,QAAQ,CAAC,EAAE,4BAA4B;IAczC,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMrC;;;;;;;;;;;;OAYG;IACG,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiBnE;;;;;;;;;OASG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;IA8CrE;;;;;;;OAOG;IACG,iBAAiB,CACrB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,KAAK,GACpD,OAAO,CAAC,gBAAgB,EAAE,CAAC;YAgChB,OAAO;CAItB"}
+{"version":3,"file":"reference-scan.d.ts","sourceRoot":"","sources":["../../../src/modules/access/reference-scan.ts"],"names":[],"mappings":"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"}