Skip to content

Add a lint rule for clone() copies that drop portable object verification - #1443

Merged
dahlia merged 2 commits into
fedify-dev:mainfrom
dahlia:feat/lint/vocab-clone-verifier
Nov 17, 2026
Merged

dahlia merged 2 commits into
fedify-dev:mainfrom
dahlia:feat/lint/vocab-clone-verifier

Conversation

@dahlia

@dahlia dahlia commented Nov 14, 2026

Copy link
Copy Markdown
Member

clone() on a vocabulary object does not inherit the source's default verifyPortableObject, so a get*() accessor called on the copy may accept a portable object without verifying it. #1396 shipped exactly that shape in the backfill package (note.clone().getContextHistory({ ... })), and documentation alone does not stop the next caller from repeating it. This adds @fedify/lint/vocab-clone-verifier, which catches the common syntactic form of the mistake, as proposed in #1401.

The rule follows vocabulary objects within a file without type information. It starts from values that may carry a default verifier: parameters and variables annotated with a type imported from @fedify/vocab (including import type, renamed imports such as Object as APObject, namespace imports, and nullable unions); objects created by new X(), X.fromJsonLd(), or lookupObject() with options that may contain a verifier; and this/super in instance members of vocabulary subclasses. From there it tracks accessor results, deepClone(), and clone() through const aliases and for await loops. Each value ends up in one of three states: possibly carrying a verifier, known to have none, or a clone that dropped it. A dropped clone that reaches an accessor without a verifier is reported once, at the clone() call. The transitions mirror the generated runtime: deepClone() falls back to the receiver's own default, so a dropped clone stays dropped through a later deepClone(), and an accessor with an explicit verifier gives fetched objects that verifier unless inheritPortableObjectVerifier: false is passed.

When the rule cannot tell, it does not report. Options that are not an object literal, such as a Context, are assumed to carry a verifier; an explicit verifyPortableObject: undefined is taken as an opt-out; dereference: false is not reported; and a later spread or an unknown computed key makes the options unknown. Reassigned bindings, member expressions, return values, and other modules are not followed. Inbox listener activities and ctx.lookupObject() results are not sources unless annotated, since recognizing them needs provenance the rule does not have; that can come later.

There is no autofix. deepClone() copies the whole graph, drops cached JSON-LD and signed representations, and is only available since 2.5.0. Passing a verifier to clone() is often the cheaper fix. ESLint and Oxlint instead offer a suggestion to use deepClone(). The suggestion is withheld when a later clone() drops the verifier again, since replacing only the first call would not help. It is also withheld inside clone() and deepClone() overrides, where it would make the override call itself.

The rule is registered for ESLint, where the recommended preset enables it as a warning (so projects that fail on warnings will see new reports after upgrading) and the strict preset as an error. In Oxlint it has to be enabled by name. It is not registered for Deno Lint, which turns on every plugin rule and reports all of them as errors, following the precedent of outbox-listener-delivery-not-awaited. A modules option adds other vocabulary modules generated by @fedify/vocab-tools, as for raw-property-iri-invalid. The stateless AST helpers that both rules use moved to packages/lint/src/lib/ast.ts without changing raw-property-iri-invalid's behavior.

Closes #1401.

clone() on a vocabulary object does not inherit the source's default
verifyPortableObject, so dereferencing through the copy with a get*()
accessor may accept portable objects without verifying them.  This is
the mistake that PR fedify-dev#1396 made in the backfill package.  The new
@fedify/lint rule catches the common syntactic shape of it.

The rule follows vocabulary objects within a file: parameters and
variables annotated with @fedify/vocab types, objects constructed or
parsed with a verifier, this/super in vocabulary subclasses, and the
results of accessors and copies.  It reports a clone() without
a verifier whose copy is dereferenced by an accessor without one,
once per clone() call, and offers an ESLint/Oxlint suggestion to use
deepClone() instead, but no autofix, since deepClone() changes cost,
caching, and signed representations and needs Fedify 2.5.0.  The
suggestion is withheld when a later clone() drops the verifier again
and inside clone()/deepClone() overrides, where it would recurse.

The rule is registered for ESLint (recommended: warn, strict: error)
and Oxlint, but not for Deno Lint, which turns on every plugin rule
and reports it as an error.  The modules option adds other generated
vocabulary modules, as for raw-property-iri-invalid.

The stateless AST helpers shared with raw-property-iri-invalid are
moved to lib/ast.ts without changing that rule's behavior.

fedify-dev#1401

Assisted-by: Claude Code:claude-opus-5-5
Assisted-by: Codex:gpt-6-astra
Assisted-by: Antigravity:gemini-4-hydrogen
Assisted-by: OpenCode:kimi-k3.1-pro
Assisted-by: Claude Code:claude-fable-5-2
@dahlia dahlia added this to the Fedify 2.5 milestone Nov 14, 2026
@dahlia dahlia self-assigned this Nov 14, 2026
@dahlia dahlia added component/vocab Activity Vocabulary related component/lint Lint related (@fedify/lint) labels Nov 14, 2026
@netlify

netlify Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for fedify-json-schema canceled.

Name Link
🔨 Latest commit ba0f4ba
🔍 Latest deploy log https://app.netlify.com/projects/fedify-json-schema/deploys/6af94d2384581213d71e6a1c

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 14, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-15T06:24:11.482863Z ba0f4ba Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

The PR adds vocab-clone-verifier, which analyzes vocabulary clone and accessor calls for verifier loss. It registers the rule in ESLint and Oxlint, adds a Deno adapter that remains unregistered, and documents the rule and its configuration.

Changes: Vocabulary clone verifier

Layer / File(s) Summary
Shared AST and vocabulary-source helpers
packages/lint/src/lib/ast.ts, packages/lint/src/lib/raw-property-iri.ts
Shared AST traversal, unwrapping, and vocabulary-source matching helpers are added. raw-property-iri.ts uses these helpers in place of local implementations.
Clone and dereference analysis
packages/lint/src/lib/vocab-clone.ts, packages/lint/src/tests/vocab-clone-verifier.test.ts
The analyzer tracks vocabulary values and verifier state through bindings, options, clone chains, and get*() accessors. Tests cover reports, non-reporting cases, suggestions, configured modules, and Oxlint behavior.
Rule adapters, registration, and validation
packages/lint/src/lib/const.ts, packages/lint/src/lib/messages.ts, packages/lint/src/rules/vocab-clone-verifier.ts, packages/lint/src/index.ts, packages/lint/src/oxlint.ts, packages/lint/src/mod.ts, packages/lint/src/tests/vocab-clone-verifier.registration.test.ts
The rule adds ESLint/Oxlint and Deno adapters, registers in the ESLint and Oxlint rule maps, and defines messages and IDs. Registration tests check ESLint severity, Oxlint availability, and Deno absence.
Rule documentation and release notes
docs/manual/lint.md, packages/lint/README.md, claude-plugin/skills/fedify/SKILL.md, changes.d/lint/vocab-clone-verifier.md, CHANGES.md
Documentation and release notes describe the warning condition, verifier alternatives, rule configuration, and linter availability.

Estimated code review effort: 4 (Complex) | ~60 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant Linter as ESLint or Oxlint
  participant Adapter as vocabCloneVerifier
  participant Analyzer as checkVocabClones
  Linter->>Adapter: Analyze Program
  Adapter->>Analyzer: Check vocabulary clones
  Analyzer-->>Adapter: Return diagnostics
  Adapter-->>Linter: Report diagnostics
Loading

Possibly related issues

  • #1400: The rule offers a deepClone() suggestion in eligible cases, but the issue’s documentation and runtime-warning work is not included.
  • #1399: The rule detects the verifier-loss case described by this issue, but the issue’s runtime-warning and documentation work is not included.
  • #1423: The rule covers the same clone-verifier-loss behavior, but does not implement the proposed accessor response registry.
Merge Risk: Minimal · up to ba0f4

This adds a new lint rule with docs and registration for ESLint and Oxlint. No concrete merge-blocking risk was identified, and the rule only warns or offers suggestions.

Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: a new lint rule that flags clone() copies which drop portable object verification. The changeset adds the vocab-clone-verifier rule, which matches this description. Th…
Description check Passed The description explains the problem (clone() drops the default verifyPortableObject), introduces the @fedify/lint/vocab-clone-verifier rule, and covers its heuristics, ESLint/Oxlint/Deno registration…
Linked Issues check Passed Directly linked issue #1401 requires the rule @fedify/lint/vocab-clone-verifier. It must report a tracked vocabulary clone() result that is dereferenced by a get*() accessor without a verifier, …
Out of Scope Changes check Passed The changes support #1401 or the refactor that the PR description states. packages/lint/src/lib/ast.ts holds the shared stateless AST helpers. vocab-clone.ts and raw-property-iri.ts both use the…
Full details: Title check

Explanation

The title names the main change: a new lint rule that flags clone() copies which drop portable object verification. The changeset adds the vocab-clone-verifier rule, which matches this description. The title is specific and accurate.

Full details: Description check

Explanation

The description explains the problem (clone() drops the default verifyPortableObject), introduces the @fedify/lint/vocab-clone-verifier rule, and covers its heuristics, ESLint/Oxlint/Deno registration, the optional deepClone() suggestion, and the modules option. This relates directly to the changeset.

Full details: Linked Issues check

Explanation

Directly linked issue #1401 requires the rule @fedify/lint/vocab-clone-verifier. It must report a tracked vocabulary clone() result that is dereferenced by a get*() accessor without a verifier, and it must not report Request, Response, Router, or Context clones. The current reviewed change set implements this. packages/lint/src/lib/vocab-clone.ts tracks receivers from annotated imports of @fedify/vocab and @fedify/fedify/vocab, including aliases, namespace imports, and import type. It also tracks new X(..., options), X.fromJsonLd(doc, options), this/super in vocabulary subclasses, aliases, deepClone(), and accessor results. It follows for await iterables through initializers of non-reassigned variables. The rule reports the dropping clone() call, not every clone. The rule is registered for ESLint (recommended as warn, strict as error), for Oxlint by name, and not for Deno Lint, as #1401 specifies. The optional suggestion is deepClone() only, and it is withheld in the cases #1401 excludes. The test file packages/lint/src/tests/vocab-clone-verifier.test.ts and the registration test cover type annotations, new, fromJsonLd, subclass this, aliases, dereference, and negative cases. Documentation is updated in docs/manual/lint.md, packages/lint/README.md, and the changelog fragment. Limit: I did not run the test suites or the Deno, Node.js, Bun, and Oxlint end-to-end lanes. The pass rests on the reported test coverage and the summary of the source, not on an observed test run.

Full details: Out of Scope Changes check

Explanation

The changes support #1401 or the refactor that the PR description states. packages/lint/src/lib/ast.ts holds the shared stateless AST helpers. vocab-clone.ts and raw-property-iri.ts both use them, which the PR description states as the reason for the move. The raw-property-iri.ts change removes duplicate helpers and reuses the built-in vocabulary-source predicate. The modules option mirrors the existing raw-property-iri-invalid option, as the PR description states. Registration edits in const.ts, messages.ts, index.ts, oxlint.ts, and mod.ts connect the new rule to its runners. The claude-plugin/skills/fedify/SKILL.md edit documents the same clone-verifier behavior. I did not compare the base version of raw-property-iri.ts. So I cannot confirm from this review that its behavior is unchanged. This is a limit on verification, not evidence of an unrelated change.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Repository UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: ecaec58b-e26b-43aa-a707-b71c2272242b
Commits

Reviewing files that changed from the base of the PR and between ac050b0 and ba0f4ba.

Files selected for processing: 2

  • packages/lint/src/lib/vocab-clone.ts
  • packages/lint/src/tests/vocab-clone-verifier.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

@chatgpt-codex-connector chatgpt-codex-connector 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.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ac050b058f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread packages/lint/src/lib/vocab-clone.ts Resolved
@codecov

codecov Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 88.46585% with 103 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
packages/lint/src/lib/vocab-clone.ts 85.73% 52 Missing and 50 partials ⚠️
packages/lint/src/rules/vocab-clone-verifier.ts 98.38% 0 Missing and 1 partial ⚠️
Files with missing lines Coverage Δ
packages/lint/src/index.ts 100.00% <100.00%> (ø)
packages/lint/src/lib/ast.ts 100.00% <100.00%> (ø)
packages/lint/src/lib/const.ts 100.00% <100.00%> (ø)
packages/lint/src/lib/messages.ts 100.00% <100.00%> (ø)
packages/lint/src/lib/raw-property-iri.ts 92.34% <100.00%> (-1.33%) ⬇️
packages/lint/src/mod.ts 100.00% <ø> (ø)
packages/lint/src/oxlint.ts 100.00% <100.00%> (ø)
packages/lint/src/rules/vocab-clone-verifier.ts 98.38% <98.38%> (ø)
packages/lint/src/lib/vocab-clone.ts 85.73% <85.73%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

vocab-clone-verifier only recognized a for-await binding as a vocabulary
object when the loop iterated an accessor call directly.  Saving the
iterable first, as in "const objects = create.getObjects()", left the
binding unknown, so the rule missed a clone() inside the loop.

The iterated expression is now resolved through the initializers of
variables that are never reassigned before it is checked for an
accessor call.  A reassigned alias stays unknown.

fedify-dev#1443 (comment)

Changelog: none
Assisted-by: Claude Code:claude-opus-5-5
@dahlia

dahlia commented Nov 15, 2026

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: ba0f4ba5eb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@dahlia
dahlia merged commit 3ed9e77 into fedify-dev:main Nov 17, 2026
36 of 37 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/lint Lint related (@fedify/lint) component/vocab Activity Vocabulary related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a lint rule for clone() that drops portable-object verification before dereferencing

1 participant