@sparkelf/dsh-knowledge-base 0.1.29 → 0.1.31

package/lib/types/client/permissionRows.d.ts

@@ -1,265 +0,0 @@
-/**
- * The pure half of the permissions overview: how one grant table reads two ways.
- *
- * Kept apart from the rendering module for a real reason, not for tidiness: a
- * component module imports the primitives package, which imports CSS, and a Node
- * test runner cannot load a `.css` file. The grouping rules are the part worth
- * testing without a DOM, so they live somewhere a plain import can reach.
- *
- * @module @sparkelf/dsh-knowledge-base/client/permissionRows
- */
-import type { GrantView, KnowledgeGrantSubjectType } from '../api.ts';
-/** One person's holdings, as the person view renders them. */
-export interface PersonHoldings {
-    /** Principal id the grants name. */
-    principalId: string;
-    /** Principal kind, so the type column can name it. */
-    principalType: KnowledgeGrantSubjectType;
-    /** Display name when a directory entry resolved one, else the id. */
-    label: string;
-    /** Distinct paths this person may touch. */
-    paths: string[];
-    /** Which actions the person holds, collapsed so a full house reads `all`. */
-    actions: string[];
-    /**
-     * Roles the person reaches through a `role` grant they belong to.
-     *
-     * Empty when the directory does not know the membership: a role grant names the
-     * ROLE, not the people in it, so this is only populated when a directory entry
-     * declared the membership.
-     */
-    roles: string[];
-    /** Most recent grant instant across this person's rows, ISO-8601. */
-    latestAt: string;
-    /** The grants this row covers, so a revoke can name exactly what it removes. */
-    grants: GrantView[];
-}
-/** One resource and everyone who may reach it. */
-export interface ResourceHoldings {
-    /** Path, relative to the mount point. */
-    relPath: string;
-    /** Whether it is a file or a directory. */
-    kind: 'file' | 'directory';
-    /** Everyone holding any action on it, grouped by principal kind. */
-    principals: Array<{
-        principalType: KnowledgeGrantSubjectType;
-        principalId: string;
-        label: string;
-        actions: string[];
-        latestAt: string;
-        grants: GrantView[];
-    }>;
-}
-/**
- * The result of reading a set of grants as permissions.
- *
- * `known: false` carries a reason rather than an empty list, because "we could not
- * work this out" and "this principal holds nothing" must not render the same way: the
- * first is a fault the reader should see, and collapsing it into an empty set is how a
- * denial gets invented. See {@link resolveActions}.
- */
-export interface ResolvedActions {
-    /** Actions held, in display order. Empty when `known` is false. */
-    actions: string[];
-    /**
-     * Whether the full set could be determined.
-     *
-     * False when part of the input could not be read -- an inheritance path that was
-     * unavailable, or a grant whose action is a word this build does not know.
-     */
-    known: boolean;
-    /** Why the set is incomplete, when it is. Shown to the reader beside the actions. */
-    reason?: string;
-}
-/**
- * Union a principal's grants into the permission set it actually holds.
- *
- * UNION, never intersection and never "the first row": a principal reaches a resource
- * through several grants (a direct one and one inherited from each role), and what
- * they may do is everything any of those grants allows. Reading one row is what made
- * an administrator display as read-only.
- *
- * An unrecognised action word makes the whole answer unknown rather than being
- * skipped. Skipping it would under-report, and under-reporting a permission is the
- * direction that misleads an operator into thinking access is safe to ignore.
- *
- * @param actions - every action string from every grant reaching this principal.
- * @returns The unioned set, or an explicit unknown with the reason.
- */
-export declare function resolveActions(actions: readonly string[]): ResolvedActions;
-/**
- * Whether a resolved set confers the ability to change a document.
- *
- * Used by the page to check itself against what the reader can actually do. `manage`
- * implies write in this model: it is the full-control level, and a principal holding
- * it can move and delete.
- * @param resolved - the unioned permission set.
- * @returns true when writing is possible, or unknown.
- */
-export declare function canWriteWith(resolved: ResolvedActions): boolean | undefined;
-/**
- * Collapse a set of action strings into the shortest describing list.
- *
- * A thin view over {@link resolveActions} so there is ONE vocabulary and ONE union
- * rule in the browser: this used to be a second implementation filtering on
- * `create`/`update`/`delete`, which silently dropped every `write` and `manage` grant.
- *
- * Kept as an exported name because the older callers and their tests use it.
- * @param actions - raw action strings from grants.
- * @returns The unioned actions in display order; unknown words are dropped here,
- *   which is why a surface that must not under-report calls {@link resolveActions}.
- */
-export declare function summarizeActions(actions: readonly string[]): string[];
-/**
- * Group grants by the principal they name.
- *
- * A principal appearing in several grants is one row: "what does 张三 have" is a
- * question about a person, and splitting them across rows because they hold two
- * paths would answer it wrong.
- *
- * @param grants - the grant table.
- * @param labels - display names by `principalType:principalId`, optional.
- * @returns one entry per principal, ordered by label then id.
- */
-export declare function groupHoldingsByPrincipal(grants: readonly GrantView[], labels?: Readonly<Record<string, string>>): PersonHoldings[];
-/**
- * Group grants by the resource they cover.
- *
- * @param grants - the grant table.
- * @param labels - display names by `principalType:principalId`, optional.
- * @returns one entry per path, ordered by path.
- */
-export declare function groupHoldingsByResource(grants: readonly GrantView[], labels?: Readonly<Record<string, string>>): ResourceHoldings[];
-/**
- * Format a grant instant the way the reference table does.
- *
- * DataOps' permission preview prints `YYYY/MM/DD HH:mm` and a dash for a missing
- * value, so a reader comparing the two surfaces sees the same date. The raw
- * ISO-8601 string the API returns is not that.
- * @param value - ISO-8601 instant, or an empty string when the backend sent none.
- * @returns The formatted instant, or a dash when there is nothing to show.
- */
-export declare function formatGrantInstant(value: string): string;
-/**
- * One DataOps account as the user directory reports it, reduced to what grouping needs.
- *
- * `roles` is what makes inheritance visible: a role grant names the ROLE, so without
- * the membership list the page can only show role grants as belonging to nobody. The
- * directory is the only source for it, and it is administrator-only -- see
- * {@link DirectoryState}.
- */
-export interface DirectoryUser {
-    /** DataOps user id, which is what a `user` grant names. */
-    userId: string;
-    /** Login name, shown beside the display name so two "张伟" can be told apart. */
-    username: string;
-    /** Display name, when the account has one. */
-    displayName: string;
-    /** Role codes this account belongs to. */
-    roleCodes: string[];
-}
-/**
- * Whether the user directory could be read.
- *
- * Three states, not two. "Nobody holds a role" and "we could not look" produce the same
- * empty membership map, and rendering them the same way is how a page ends up telling
- * an operator that nobody has inherited access when the truth is that the read failed.
- */
-export type DirectoryState = {
-    kind: 'available';
-    users: readonly DirectoryUser[];
-} | {
-    kind: 'unavailable';
-    reason: string;
-};
-/** One account's holdings, as the by-person view renders them. */
-export interface AccountHoldings {
-    /** The account id. */
-    userId: string;
-    /** Login name, for disambiguating identical display names. */
-    username?: string;
-    /** Display name, or the id when the account is not in the directory. */
-    label: string;
-    /** Distinct paths this account reaches, directly or through a role. */
-    paths: string[];
-    /** The unioned permission set, never narrowed by a single grant. */
-    resolved: ResolvedActions;
-    /** Direct grants the account holds itself. */
-    directGrants: GrantView[];
-    /**
-     * Role codes the account inherits through.
-     *
-     * Empty when the directory could not be read; {@link inheritanceKnown} says which.
-     */
-    viaRoles: string[];
-    /** Whether the inheritance half of this row was actually determined. */
-    inheritanceKnown: boolean;
-    /** Why inheritance is unknown, when it is. */
-    inheritanceReason?: string;
-    /** Most recent grant instant across the rows this account covers. */
-    latestAt: string;
-}
-/** One role's holdings, as the by-role view renders them. */
-export interface RoleHoldings {
-    /** Role code, which is what a `role` grant names. */
-    roleCode: string;
-    /** Role display name when the directory resolved one, else the code. */
-    label: string;
-    /** Distinct paths the role covers. */
-    paths: string[];
-    /** The unioned permission set for this role. */
-    resolved: ResolvedActions;
-    /** Grants that name this role. */
-    grants: GrantView[];
-    /** How many directory accounts belong to this role, when the directory is known. */
-    memberCount?: number;
-    /** Most recent grant instant across this role's rows. */
-    latestAt: string;
-}
-/**
- * Group grants by the DataOps ACCOUNT that holds them.
- *
- * The account is the row grain because "who can see this" is a question about people.
- * A role grant confers access on every member of that role, so its paths are attributed
- * to each member here -- otherwise a reader whose access is entirely role-derived would
- * appear on no row at all, and the page would say "nobody has access" to somebody who
- * can write.
- *
- * Three sources are merged, and the merge is a UNION:
- * 1. direct `user` grants;
- * 2. grants held by any role the account belongs to (inherited);
- * 3. nothing else -- the built-in administrator levels are already rows in the grant
- *    table (`source: 'seed'`), so hard-coding them here would create a second authority
- *    that could disagree with the backend.
- *
- * @param grants - the whole grant table.
- * @param directory - the user directory, or the reason it could not be read.
- * @param labels - display names by `principalType:principalId`, optional.
- * @returns One row per account that holds or inherits at least one grant, sorted by label.
- */
-export declare function groupHoldingsByAccount(grants: readonly GrantView[], directory: DirectoryState, labels?: Readonly<Record<string, string>>): AccountHoldings[];
-/**
- * Group grants by the ROLE they name.
- *
- * The same grants the old "by person" table showed, now labelled as what they are: a
- * role is not a person, and putting it under "by person" told the reader that the
- * administrators were the only people with access.
- *
- * A role whose grants are all unreadable still gets a row with `known: false`: that is
- * the safety net against rendering "no permission" for a read failure.
- *
- * @param grants - the whole grant table.
- * @param labels - display names by `principalType:principalId`, optional.
- * @param memberCounts - role code -> member count, when the directory is known.
- * @returns One row per role named by at least one grant, sorted by label.
- */
-export declare function groupHoldingsByRole(grants: readonly GrantView[], labels?: Readonly<Record<string, string>>, memberCounts?: ReadonlyMap<string, number>): RoleHoldings[];
-/**
- * Build the role -> member-count map from a directory.
- *
- * Only meaningful when the directory is known; returns undefined otherwise so the row
- * omits the count rather than claiming zero members.
- * @param directory - the user directory state.
- * @returns Counts by role code, or undefined when unavailable.
- */
-export declare function roleMemberCounts(directory: DirectoryState): Map<string, number> | undefined;

package/lib/types/client/roleSummary.d.ts

@@ -1,54 +0,0 @@
-/**
- * What each role in the grant table actually amounts to.
- *
- * A role is not stored anywhere: it exists because grants name it. That is a good
- * property to inherit — a role cannot outlive its resources or appear with none —
- * but it means "list the roles" is a question about the grants, answered by
- * reading them. This module is that reading, kept out of the component so it can
- * be tested without a DOM.
- *
- * @module @sparkelf/dsh-knowledge-base/client/roleSummary
- */
-import type { GrantView } from '../api.ts';
-/** One role as the overview shows it. */
-export interface RoleSummary {
-    /** Role id, which is the `principalId` its grants carry. */
-    id: string;
-    /** Display name, falling back to the id when no locale entry matches. */
-    label: string;
-    /** Actions granted anywhere by this role, collapsed so a full house reads `all`. */
-    actions: string[];
-    /** Distinct paths it reaches. */
-    paths: string[];
-    /** Whether this is one of the two the product ships with. */
-    builtIn: boolean;
-}
-/**
- * Collapse raw action strings the way the rest of the page does.
- *
- * This used to carry its own word list, inherited from the create/edit form
- * (`read`/`create`/`update`/`delete`). DataOps stores `read`/`write`/`manage`, so
- * `write` and `manage` matched nothing and were dropped: the role BADGES above the
- * table showed 「只读」 while the table below them — already fixed — showed
- * 读/写/管理. One page, two conclusions, and the reader has no way to tell which is
- * true.
- *
- * It now delegates to {@link resolveActions}, which is the single vocabulary and the
- * single union rule for this package. Do not reintroduce a local list here: a second
- * copy of "what the words mean" is exactly the defect this line removes.
- *
- * @param actions - raw action strings.
- * @returns The unioned actions in product order.
- */
-export declare function summarizeRoleActions(actions: readonly string[]): string[];
-/**
- * Read the roles out of a grant table.
- *
- * Only `role` grants contribute: a user grant is not a role, and inventing one
- * per user would flood the list with rows that mean nothing.
- *
- * @param grants - the grant table.
- * @param locale - `zh` or `en`, for the built-in role names.
- * @returns one entry per role named by a grant, built-ins first then alphabetical.
- */
-export declare function buildRoleSummaries(grants: readonly GrantView[], locale?: 'zh' | 'en'): RoleSummary[];