Skip to content

add work scope logic expressions - #129

Closed
holkexyz wants to merge 9 commits into
developfrom
add-ops-schema-for-work-scope-logic-model
Closed

add work scope logic expressions#129
holkexyz wants to merge 9 commits into
developfrom
add-ops-schema-for-work-scope-logic-model

Conversation

@holkexyz

@holkexyz holkexyz commented Jan 23, 2026

Copy link
Copy Markdown
Member

Summary by CodeRabbit

  • New Features

    • Added nested boolean operators (all/any/not) for recursive work-scope logic (NOT is unary).
    • Added a flat work-scope expression format (allOf/anyOf/noneOf) for simpler scope definitions.
    • Introduced a reusable work-scope tag type for leaf taxonomy atoms.
    • workScope may also be a plain string.
  • Documentation

    • Added docs, examples, and changelog clarifying semantics, usage, and the unconstrained-default behavior.

@changeset-bot

changeset-bot Bot commented Jan 23, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5c982e8

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@hypercerts-org/lexicon Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai

coderabbitai Bot commented Jan 23, 2026

Copy link
Copy Markdown

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds three new work-scope lexicons/structures (org.hypercerts.helper.ops, org.hypercerts.helper.workScopeExpr, org.hypercerts.helper.workScopeTag), updates activity.workScope description to reference them, and adds ERD and documentation entries describing flat and nested boolean scope expressions.

Changes

Cohort / File(s) Summary
Lexicons — Operator & Nested Logic
lexicons/org/hypercerts/helper/ops.json
New lexicon defs.main defining an Operator record with required op (knownValues: all,any,not), args (array of com.atproto.repo.strongRef, min 1, max 100; may reference workScopeTag or nested ops), and createdAt. Notes client-side unary constraint for not.
Lexicons — Flat Expression
lexicons/org/hypercerts/helper/workScopeExpr.json
New lexicon defining a flat boolean expression record (version, optional label/description, arrays allOf/anyOf/noneOf of com.atproto.repo.strongRef, createdAt), semantics for ALL/ANY/NONE and default unconstrained behavior when empty.
Activity Lexicon Update
lexicons/org/hypercerts/claim/activity.json
Updated workScope.description to accept string, workScopeExpr, or ops records and to state that empty/no constraints imply unconstrained (all work in scope).
Documentation & Schema Registry
SCHEMAS.md, .changeset/add-ops-lexicon.md, README.md
Adds public entries and docs for org.hypercerts.helper.ops, org.hypercerts.helper.workScopeExpr, and org.hypercerts.helper.workScopeTag; updates activity schema tables/formatting and README examples to show multiple valid workScope forms.
ER Diagram / Model
ERD.puml
Adds dataclasses workScopeTag, workScopeExpr, and ops; links activity.workScope to those types; shows workScopeExpr arrays linking to workScopeTag; ops.args links to workScopeTag and recursively to ops.

Sequence Diagram(s)

(Skipped)

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Suggested reviewers

  • aspiers
  • s-adamantine
  • bitbeckers

Poem

🐰 I hopped through JSON, fields in tow,
I taught the ops how booleans grow,
ALLs and ANYs, and single NOT to plot,
Tags nested snug where logic carrots rot,
Hop—scope declared, the garden’s tied in a bow!


Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error, 1 warning)

Check name Status Explanation Resolution
Lexicon Documentation Sync ❌ Error The createdAt field description in workScopeExpr.json deviates from the standard pattern used in ops.json and workScopeTag.json, causing a synchronization inconsistency. Update the createdAt description in workScopeExpr.json to match the standard pattern and update SCHEMAS.md line 307 accordingly.
Lexicons Styleguide Compliance ⚠️ Warning The workScopeExpr.json lexicon uses a non-standard createdAt field description that deviates from established conventions in ops.json and workScopeTag.json without documentation. Update workScopeExpr.json createdAt description to: 'Client-declared timestamp when this record was originally created' to match existing lexicon conventions.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'add work scope logic expressions' directly summarizes the main change—introducing new lexicons (ops and workScopeExpr) for defining work scope logic, which is the primary focus of the changeset.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch add-ops-schema-for-work-scope-logic-model

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🤖 Fix all issues with AI agents
In `@lexicons/org/hypercerts/helper/ops.json`:
- Around line 1-34: Add the new lexicon to the generated docs and ER diagram:
run the documentation generator (npm run gen-schemas-md) to regenerate
SCHEMAS.md so it includes the new org.hypercerts.helper.ops record (with fields
createdAt, op, args), then update ERD.puml to add an ops entity node showing
createdAt, op, args (omit facet fields) and commit both updated SCHEMAS.md and
ERD.puml; verify the lexicon id "org.hypercerts.helper.ops" and the record
properties (createdAt, op, args) appear correctly in the outputs.

Comment thread lexicons/org/hypercerts/helper/ops.json
@holkexyz
holkexyz requested a review from aspiers January 23, 2026 07:40
@holkexyz holkexyz changed the title add ops for workscope logic model add work scope logic expressions Feb 18, 2026

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
SCHEMAS.md (1)

1-4: ⚠️ Potential issue | 🟡 Minor

Pipeline failure: SCHEMAS.md is out of sync with generated output.

The CI check reports git diff --exit-code detected changes in SCHEMAS.md, meaning the committed file diverges from what npm run gen-schemas-md produces. Please regenerate with npm run gen-schemas-md and commit the result.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@SCHEMAS.md` around lines 1 - 4, SCHEMAS.md was modified and is out of sync
with the generated output; run the generator and commit the regenerated file:
execute the command npm run gen-schemas-md to regenerate SCHEMAS.md, review the
changes (git diff), stage the updated SCHEMAS.md, and commit and push so CI
passes; ensure you don’t make manual edits to SCHEMAS.md since it’s
auto-generated from the lexicon definitions.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In `@SCHEMAS.md`:
- Around line 1-4: SCHEMAS.md was modified and is out of sync with the generated
output; run the generator and commit the regenerated file: execute the command
npm run gen-schemas-md to regenerate SCHEMAS.md, review the changes (git diff),
stage the updated SCHEMAS.md, and commit and push so CI passes; ensure you don’t
make manual edits to SCHEMAS.md since it’s auto-generated from the lexicon
definitions.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 1

🧹 Nitpick comments (1)
SCHEMAS.md (1)

44-44: Nit: sentence fragment in workScope description.

"May be a string..." has no grammatical subject. Consider "It may be a string..." or "The field may be a string..." for clarity.

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@SCHEMAS.md` at line 44, The `workScope` description contains a sentence
fragment ("May be a string..."); update the text for grammatical clarity by
adding an explicit subject (e.g., change "May be a string, a structured scope
expression..." to "It may be a string, a structured scope expression..." or "The
field may be a string, a structured scope expression...") in the `workScope`
entry so the description reads as a complete sentence.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@SCHEMAS.md`:
- Line 307: Update the `createdAt` field description in the SCHEMAS.md table to
match the project's standard phrasing; replace "Timestamp when this work-scope
expression was created." with "Client-declared timestamp when this record was
originally created" for the `createdAt` entry (the table row that currently
references the work-scope expression) so it is consistent with other lexicons.

---

Nitpick comments:
In `@SCHEMAS.md`:
- Line 44: The `workScope` description contains a sentence fragment ("May be a
string..."); update the text for grammatical clarity by adding an explicit
subject (e.g., change "May be a string, a structured scope expression..." to "It
may be a string, a structured scope expression..." or "The field may be a
string, a structured scope expression...") in the `workScope` entry so the
description reads as a complete sentence.

Comment thread SCHEMAS.md
| `allOf` | `ref` | ❌ | All referenced tags must match for something to be considered in-scope. Typically refs to org.hypercerts.helper.workScopeTag. | maxLength: 100 |
| `anyOf` | `ref` | ❌ | At least one referenced tag must match (if anyOf is present and non-empty). Typically refs to org.hypercerts.helper.workScopeTag. | maxLength: 100 |
| `noneOf` | `ref` | ❌ | None of the referenced tags may match. If any excluded tag matches, the contribution or activity is considered out-of-scope. | maxLength: 100 |
| `createdAt` | `string` | ✅ | Timestamp when this work-scope expression was created. | |

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

createdAt description is inconsistent with the rest of the document.

Every other lexicon uses "Client-declared timestamp when this record was originally created" for this field. Line 307 uses "Timestamp when this work-scope expression was created." which deviates from the established pattern.

🔧 Proposed fix
-| `createdAt`   | `string`  | ✅       | Timestamp when this work-scope expression was created.                                                                                            |                 |
+| `createdAt`   | `string`  | ✅       | Client-declared timestamp when this record was originally created.                                                                                |                 |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| `createdAt` | `string` || Timestamp when this work-scope expression was created. | |
| `createdAt` | `string` || Client-declared timestamp when this record was originally created. | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@SCHEMAS.md` at line 307, Update the `createdAt` field description in the
SCHEMAS.md table to match the project's standard phrasing; replace "Timestamp
when this work-scope expression was created." with "Client-declared timestamp
when this record was originally created" for the `createdAt` entry (the table
row that currently references the work-scope expression) so it is consistent
with other lexicons.

@holkexyz

Copy link
Copy Markdown
Member Author

not implementing this for now. in favor of CEL implementation

@holkexyz holkexyz closed this Feb 24, 2026
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.

1 participant