Skip to content

feat(plan): display ChurchTools right types and named parameters instead of bare scope IDs #170

Description

@bwl21

Problem

The generated Markdown plan shows permission scopes in the Geltungsbereich column as bare IDs such as #31, #10, or #3. A nontechnical reviewer cannot tell which object or kind of data a permission targets without separately looking up the permission's scope dimension and the target ID.

Observed with ct 0.1.0-mg.20260908.2+facfea6, using:

ct plan --env prod --format markdown --output-base reports/plan

The report's destination directory must already exist.

Examples from an actual plan (no personal data):

Right Current scope display Meaning of the scope type
Einzelnen Kalender sehen (churchcal:view category, authId 403) #31 Calendar
Dienste einzelner Dienstkategorien sehen (churchservice:view servicegroup, authId 304) #10 Service category
Gruppenmitglieder sehen (churchdb:+see persons, authId 10101) #3 Security level
"Personen" sehen (churchdb:view, authId 101) keine No additional scope value on this assignment

The permission recipient is already shown in the surrounding group-role heading. The scope column should explain the target of the permission, separately from its recipient.

Requested behavior

Resolve scope dimensions and target display names for the selected environment, and render readable, typed labels while retaining IDs for traceability. Illustrative labels (not asserted names of the sample calendar/service category):

  • Kalender: <resolved name> (#31)
  • Dienstkategorie: <resolved name> (#10)
  • Sicherheitsstufe: Kontakt-Details (#3)

Follow ChurchTools terminology and structure

User clarification: these values are arguments/parameters of a right. Do not introduce a separate user-facing authorization concept called “Geltungsbereich”. The earlier suggestion “Kein zusätzlicher Geltungsbereich” is withdrawn.

Represent ChurchTools' own distinction between global rights and group-internal rights explicitly. Keep that distinction separate from both the recipient (e.g. a group role) and the parameters of the right. Receiving a global right through a group role does not make that right group-internal.

Use a column such as Parameter, with the concrete ChurchTools parameter name and resolved value, for example Kalender: <name> (#59) or Sicherheitsstufe: <name> (#2). For a right with no parameters, display Keine Parameter. An unresolved parameter must instead remain visibly unresolved.

Examples supplied during review:

  • churchdb:+see group member fields (authId 10126), argument #2: identify the parameter as a security level.
  • churchcal:edit calendar entry template (authId 410), argument #59: identify the parameter as a calendar.

Derive labels, right classification and parameter semantics from ChurchTools metadata/documented structures. Internal API/CLI names such as scope may remain technical implementation details; do not turn them into a competing conceptual model in the report. Absence of parameters means neither “no permission” nor automatically “global” or “unrestricted”.

Acceptance criteria

  • The report follows ChurchTools terminology and explicitly distinguishes global from group-internal rights, independently of recipient and parameters.

  • Replace the user-facing Geltungsbereich concept with the right’s actual parameters; parameterless rights display Keine Parameter.

  • Scope rendering uses the right's actual scope dimension; the same numeric ID may refer to different resource types.

  • Resolvable scopes show a localized type, target name and original ID in the Markdown plan. Prefer sharing the resolver with human-readable text output.

  • Names are resolved against the selected environment, including externally bound targets; no names from another host are reused.

  • If a target cannot be resolved, show the known type/dimension and ID with an explicit unresolved label. Do not invent names or fail the entire plan just because enrichment is unavailable.

  • Special values such as -1 and 0 are interpreted only according to the specific permission dimension's documented semantics, not with a universal meaning or as ordinary object IDs by default.

  • No-scope assignments get an unambiguous label distinct from unresolved targets.

  • Multiple scope values remain individually identifiable and output ordering is deterministic.

  • Display enrichment does not change the planned grants, binding/state data or apply behavior; canonical numeric scope values remain available in JSON.

  • Lookups are batched/cached per environment and dimension rather than repeated for every grant row.

  • Tests cover overlapping IDs across dimensions, unknown/deleted targets, special scope values, no-scope assignments, multiple values and Markdown escaping in names.

Related to #163 (Markdown plan readability), but this issue concerns semantic permission-scope labels rather than nested diffs.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    triageUnsorted intake — decide in the weekly sweep

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions