Skip to content

Show which permissions a property needs, in hover, inlay hints, tokens and a foam_permissions MCP tool - #36

Open
abdelaziz-mahdy wants to merge 2 commits into
mainfrom
permission-signifiers
Open

abdelaziz-mahdy wants to merge 2 commits into
mainfrom
permission-signifiers

Conversation

@abdelaziz-mahdy

Copy link
Copy Markdown
Collaborator

A property's permission flag often sits on a superclass or an interface, so the declaration in front of you doesn't show it. Each surface now names the exact permission to grant:

hover on Notification.createdByAgent
  Needs permission. read: notification.ro.createdbyagent or notification.rw.createdbyagent (set on foam.core.notification.Notification);
  write: notification.rw.createdbyagent (set on foam.core.notification.Notification);
  column: notification.column.createdbyagent (set on foam.core.auth.CreatedByAware)

{ name: 'createdBy' }  🔒 column      // inlay hint: the flag is on CreatedByAware, not here
this.created                          // underlined in VS Code: `permissioned` token modifier

foam_permissions { symbol: 'foam.core.auth.User' }
  property created read: user.ro.created | user.rw.created  (readPermissionRequired on foam.core.auth.User)
  action deleteUser available: user.action.delete

The names follow the runtime checks: the concrete class's short name and the property name, lowercased. The tool also lists permissionRequired sections, and semanticTokens.permissions turns the underline off.

Fixes foam-foundation/foam3#5260

A property's readPermissionRequired, writePermissionRequired,
updatePermissionRequired or columnPermissionRequired flag often sits on a
superclass or an interface, out of sight of the declaration being edited.
Hover, an inlay hint, a semantic-token modifier and the new foam_permissions
MCP tool now name the exact permissions the runtime checks.

Fixes foam-foundation/foam3#5260
@abdelaziz-mahdy

Copy link
Copy Markdown
Collaborator Author

@ajeetgill can you review please

@ajeetgill ajeetgill left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

names match the runtime for concrete classes: checked against foam3 PermissionedPropertyDAO, Element2, TableComponentView, SectionAxiom and Action

hover, inlay hints, tokens and foam_permissions all work on User, Notification and Flow, and they are fast (all 3043 classes in about 0.4 s)

one thing to fix before merge: an interface or abstract class prints a name nobody checks (createdbyaware.column.createdby)

one doc line to soften: predicates use the declaring class, columns use the table's of

the rest is small: from is null for relationships, relationship ids throw, a few test gaps

suite on my machine: 2279 pass, 5 fail. the same 5 fail on the base commit (service symbols and JEI rank), so the PR adds 21 passing tests and no new failure

not checked: how it looks in VS Code or other editors, and the Java side was read, not run

Comment thread src/FoamIndex.js Outdated
var prop = cls.getAxiomByName(propName);
if ( ! prop || ! foam.lang.Property.isInstance(prop) ) return null;

var stem = cls.name.toLowerCase() + '.';

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[bug] on an interface or an abstract class this prints a name the runtime never checks

foam_permissions { symbol: 'foam.core.auth.CreatedByAware' } gives createdbyaware.column.createdby, and foam.core.ruler.Ruled gives ruled.ro.enabled

the checks use the object's own class (foam3 PermissionedPropertyDAO.js:150, Element2.js:1900), so the real names are notification.column.createdby, flow.column.createdby, ...

someone will grant createdbyaware.* and nothing changes

I think a placeholder is enough, with a line that says so (same at :944):

var stem = ( this.isInterface(classId) || cls.model_.abstract ? '<implementing class>' : cls.name.toLowerCase() ) + '.';

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right, fixed in a286dca

an interface now prints <class>: CreatedByAware.createdBy gives <class>.column.createdby, sections the same

I kept the name on an abstract class: Ruled is abstract, not an interface, and a predicate on a subclass that does not re-declare the property checks the declaring class (AbstractPropertyInfo.java:117), so ruled.ro.priority can be checked

test: CreatedByAware.createdBy gives <class>.column.createdby, Ruled.priority keeps ruled.ro.priority

Comment thread src/FoamIndex.js Outdated
* lowercased. User.created needs 'user.ro.created' or 'user.rw.created'
* to be read (PermissionedPropertyDAO, Element2's controller-mode
* slot), 'user.rw.created' to be written, and 'user.column.created' to
* show as a table column (TableComponentView). A subclass Admin of User

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[question] is "the concrete class" right for every check? I read two that differ (read only, not run)

predicates: foam3 AbstractPropertyInfo.java:117-121 uses the PropertyInfo's own class, and ClassInfoImpl.java:86 sets that to the declaring class. PermissionedPropertyDAO.js:61 calls it on select

so filtering Admin rows by created would need user.ro.created

columns and filters: TableComponentView.js:70 and FilterView.js:364,433 use the table's of, not the row's class

soften the line here and in README.md:249 and CLAUDE.md:425? something like "the object's class for find, select and the detail view; the declaring class for predicates; the table's of for columns"

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no, you're right. softened in a286dca, in FoamIndex.js, README.md and CLAUDE.md, with your wording

the object's class for find, select and the detail view; the declaring class for predicates; the table's of for columns and filters

Comment thread src/FoamIndex.js
var cls = this.getClass(id);
if ( ! cls || ! cls.model_ ) return null;
if ( this.declaresFlag_(cls, propName, flag) ) return id;
var impls = cls.model_.implements || [];

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] from is null for more than refinements: 67 of 548 rows in foam3

relationships: User.notificationSettings (foam3 foam/core/auth/Relationships.js:72)

flags that arrive another way: BaseCapable.capablePayloads has no own property and still reports null (the flag is in CapableObjectDataProperties.js)

small fix: the doc at :889 and CLAUDE.md:431 could say "null when no class or directly implemented interface declares it"

better fix: fall back to prop.sourceCls_.id when the walk finds nothing

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

took the small fix in a286dca: the doc and CLAUDE.md now say null when no class or directly implemented interface declares it, naming a refinement and a relationship (User.notificationSettings)

I did not fall back to sourceCls_: for User.notificationSettings it would say "set on User", and User's own file does not set it

Comment thread src/FoamIndex.js
var stem = cls.name.toLowerCase() + '.';

var properties = [];
cls.getAxiomsByClass(foam.lang.Property).forEach(function(p) {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] a relationship id throws and is reported as unknown

foam_permissions { symbol: 'foam.core.auth.GroupUserUsersRelationship' } answers "could not resolve symbol"

the real cause is in the log: cls.getAxiomsByClass is not a function

32 registry ids are foam.dao.Relationship objects, not classes

I think a guard is enough, here and in getPermissions (:893):

if ( ! cls || ! cls.getAxiomsByClass ) return null;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done in a286dca, the guard in both getPermissions and getPermissionSurface

GroupUserUsersRelationship now answers null in both, so foam_permissions says "could not resolve symbol" without the log error

Comment thread test/mcp.js
'property created read: user.ro.created | user.rw.created (readPermissionRequired on foam.core.auth.User)\n' +
'section admin shown: user.section.admin\n' +
'action deleteUser available: user.action.delete',
'shapePermissions: one line per check, any-of names joined with |');

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[nice to have] a few paths have no test

no test calls callTool('foam_permissions'), so the missing-symbol and unknown-symbol answers are untested

no real class with a permissionRequired section (foam.core.reflow.Flow gives flow.section.scriptsection)

no row with from: null (User.twoFactorEnabled, set by a refinement)

no subclass whose short name differs from the parent's, which is the main claim of the PR

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added in a286dca:

  • callTool('foam_permissions') with no symbol and with an unknown one
  • Flow gives flow.section.scriptsection
  • User.twoFactorEnabled has from: null
  • UserLifecycleTicket.createdBy gives userlifecycleticket.rw.createdby, flag from Ticket
  • relationship id and interface placeholder

with the fix reverted, the interface test fails and the relationship test throws

suite here: 2292 pass, 0 fail

} else if ( propertySet[name] ) {
tokens.push({ line: lineNum, char: charPos, length: name.length, type: 2, modifiers: 0 });
tokens.push({ line: lineNum, char: charPos, length: name.length, type: 2,
modifiers: lockedSet[name] ? lockedBit : 0 });

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[question] only this.<property> gets the modifier

the declaration ({ name: 'created', ... }) and other.created do not

foam3#5260 asked for the property itself to look different. is the declaration left out on purpose, since hover and the inlay hint cover it?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

on purpose

the token pass only reads this.<name> today (SemanticTokenHandler.js:195)

the declaration gets the 🔒 inlay hint when the flag is set elsewhere, and hover always

for other.created the handler does not know other's class, so it cannot ask

An interface is never an object's class, so a permission name built from
it, such as createdbyaware.column.createdby, matches no check; it now
prints <class>.column.createdby. An abstract class keeps its name, since a
predicate on an inherited property checks the declaring class.

The docs now say which class each check uses: the object's class for
find, select and the detail view, the declaring class for predicates, and
the table's of for columns. A registry id that is a relationship answers
null instead of throwing.
@ajeetgill

Copy link
Copy Markdown
Member

read a286dca. <class> on an interface and the relationship guard look good. agreed on the abstract class: the predicate check uses the declaring class

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MCP-x-LSP Identifiers for Properties - e.g. readPermissionRequired

2 participants