Narrowly focused implementation of RULE 15-0-1

[MichaelRFairhurst]

Description

please enter the description of your change here

Change request type

• Release or process automation (GitHub workflows, internal scripts)
• Internal documentation
• External documentation
• Query files (.ql, .qll, .qls or unit tests)
• External scripts (analysis report or other code shipped as part of a release)

Rules with added or modified queries

• No rules added
• Queries have been added for the following rules:
  • RULE-15-0-1
• Queries have been modified for the following rules:
  • rule number here

Release change checklist

A change note (development_handbook.md#change-notes) is required for any pull request which modifies:

• The structure or layout of the release artifacts.
• The evaluation performance (memory, execution time) of an existing query.
• The results of an existing query in any circumstance.

If you are only adding new rule queries, a change note is not required.

Author: Is a change note required?

• Yes
• No

🚨🚨🚨
Reviewer: Confirm that format of shared queries (not the .qll file, the
.ql file that imports it) is valid by running them within VS Code.

• Confirmed

Reviewer: Confirm that either a change note is not required or the change note is required and has been added.

• Confirmed

Query development review checklist

For PRs that add new queries or modify existing queries, the following checklist should be completed by both the author and reviewer:

Author

• Have all the relevant rule package description files been checked in?
• Have you verified that the metadata properties of each new query is set appropriately?
• Do all the unit tests contain both "COMPLIANT" and "NON_COMPLIANT" cases?
• Are the alert messages properly formatted and consistent with the style guide?
• Have you run the queries on OpenPilot and verified that the performance and results are acceptable?
  As a rule of thumb, predicates specific to the query should take no more than 1 minute, and for simple queries be under 10 seconds. If this is not the case, this should be highlighted and agreed in the code review process.
• Does the query have an appropriate level of in-query comments/documentation?
• Have you considered/identified possible edge cases?
• Does the query not reinvent features in the standard library?
• Can the query be simplified further (not golfed!)

Reviewer

• Have all the relevant rule package description files been checked in?
• Have you verified that the metadata properties of each new query is set appropriately?
• Do all the unit tests contain both "COMPLIANT" and "NON_COMPLIANT" cases?
• Are the alert messages properly formatted and consistent with the style guide?
• Have you run the queries on OpenPilot and verified that the performance and results are acceptable?
  As a rule of thumb, predicates specific to the query should take no more than 1 minute, and for simple queries be under 10 seconds. If this is not the case, this should be highlighted and agreed in the code review process.
• Does the query have an appropriate level of in-query comments/documentation?
• Have you considered/identified possible edge cases?
• Does the query not reinvent features in the standard library?
• Can the query be simplified further (not golfed!)

[Copilot]

Pull request overview

Adds a new MISRA C++:2023 RULE-15-0-1 implementation (plus an audit companion query) to detect incorrectly provided special member functions, including packaging/metadata wiring and a dedicated test suite.

Changes:

• Introduces ImproperlyProvidedSpecialMemberFunctions.ql and ImproperlyProvidedSpecialMemberFunctionsAudit.ql for RULE-15-0-1.
• Adds helper library logic (AnalyzableClass.qll) to model special-member availability/customization.
• Registers the new rule package in exclusions/metadata and adds comprehensive .qlref/.expected/C++ test fixtures.

Show a summary per file

File	Description
rule_packages/cpp/Classes3.json	Adds RULE-15-0-1 rule package entries (main + audit).
cpp/misra/src/rules/RULE-15-0-1/ImproperlyProvidedSpecialMemberFunctions.ql	Main RULE-15-0-1 query implementation and message logic.
cpp/misra/src/rules/RULE-15-0-1/ImproperlyProvidedSpecialMemberFunctionsAudit.ql	Audit query for “not analyzable” classes.
cpp/misra/src/rules/RULE-15-0-1/AnalyzableClass.qll	Shared modeling of special member functions for analyzable classes.
cpp/common/src/codingstandards/cpp/exclusions/cpp/RuleMetadata.qll	Wires the new Classes3 package into query metadata/exclusions.
cpp/common/src/codingstandards/cpp/exclusions/cpp/Classes3.qll	New autogenerated metadata module for the Classes3 package.
cpp/misra/test/rules/RULE-15-0-1/test.cpp	New C++ test fixture covering compliant/non-compliant and audit cases.
cpp/misra/test/rules/RULE-15-0-1/*.qlref	Test references to the production queries.
cpp/misra/test/rules/RULE-15-0-1/*.expected	Expected results for both main and audit queries.

Copilot's findings

Comments suppressed due to low confidence (4)

cpp/misra/test/rules/RULE-15-0-1/test.cpp:376

• The audit .expected file reports an alert at this class, but the test source does not mark it // NON_COMPLIANT (or similar). Please add the appropriate NON_COMPLIANT annotation here or remove/update the corresponding row in ImproperlyProvidedSpecialMemberFunctionsAudit.expected.

class UnmovableDerivedPublicVirtualDtor
    : public UnmovableBasePublicVirtualDtor {};

cpp/misra/test/rules/RULE-15-0-1/test.cpp:403

• The audit .expected file reports an alert at this class, but the test source does not mark it // NON_COMPLIANT (or similar). Please add the appropriate NON_COMPLIANT annotation here or remove/update the corresponding row in ImproperlyProvidedSpecialMemberFunctionsAudit.expected.

class ProtectedDtorDerived : public BaseProtectedDtor {};

cpp/misra/test/rules/RULE-15-0-1/test.cpp:416

• The audit .expected file reports an alert at this class, but the test source does not mark it // NON_COMPLIANT (or similar). Please add the appropriate NON_COMPLIANT annotation here or remove/update the corresponding row in ImproperlyProvidedSpecialMemberFunctionsAudit.expected.

class VirtualProtectedDtorDerived : public BaseVirtualProtectedDtor {};

cpp/misra/test/rules/RULE-15-0-1/test.cpp:390

• The audit .expected file reports an alert at this class, but the test source does not mark it // NON_COMPLIANT (or similar). Please add the appropriate NON_COMPLIANT annotation here or remove/update the corresponding row in ImproperlyProvidedSpecialMemberFunctionsAudit.expected.

class UnmovablePrivateVirtualDtorDerived : public UnmovablePrivateVirtualDtor {
};

• Files reviewed: 11/11 changed files
• Comments generated: 9

[jeongsoolee09]

This can now be deleted.

[jeongsoolee09]

(I mean the line 290.)

[MichaelRFairhurst]

Oops, I deleted the whole class!

But I think that's ok, it's covered by:

class CustomizedCtorsCompliant { // COMPLIANT: copy-enabled (1)
public:
  DEFINE_ALL_SPECIAL_MEMBERS(CustomizedCtorsCompliant, CUSTOMIZED, CUSTOMIZED,
                             DELETED, DELETED, CUSTOMIZED)
};

(both are customized constructors, deleted assignments, and customized dtor)

[jeongsoolee09]

Suggested change

	* See [class.copy]/8 and [class.copy]
	* See [class.copy.ctor]/8 and [class.copy]

[MichaelRFairhurst]

Fixed in 61a4dd9!

[jeongsoolee09]

It may be missing a branch.

Suggested change

	isUserDeclared(c.getDestructor())
	isUserDeclared(c.getDestructor())
	or
	isUserDeclared(c.getAMemberFunction().(MoveAssignmentOperator))

[jeongsoolee09]

Why is this condition needed?

[MichaelRFairhurst]

This (and the next comment) are attempting to check if the class is copy-assignable vs copy-enabled.

If a class is copyEnabled, we can check for the existence of either assignment operator to distinguish copy-enabled from copy-assignable, because a copy-assignable class will have both and a copy-enabled class will have neither.

It took me too long to remember that that's why I wrote it. I'll write a helper predicate that makes this clearer.

[MichaelRFairhurst]

Ah, I see.

Yes, you're right. I forgot that copy-assignable was specifically declared to mean a class where std::is_copy_assignable_v<T> is true -- I thought it referred specifically to the assignable row of copy-enabled. (Which is only partly true).

Fixed in 61a4dd9!

[jeongsoolee09]

Shouldn't this be c.copyAssignable() instead?

[MichaelRFairhurst]

Fixed in 61a4dd9!

[jeongsoolee09]

It was a bit hard for me to follow the logic of this requirement check. Since these come in the form of

isCopyEnabled(class) -> {some_condition}

wouldn't it be simpler to check it using by taking the negation of the above?

isCopyEnabled(class) and ~{some_condition}

For example, the last requirement translates to

c.copyAssignable() implies (
  c.isCustomized(TCopyAssignmentOperator()) and
  (
    c.isCustomized(TMoveConstructor()) and c.isCustomized(TMoveAssignmentOperator()) or
    not isUserDeclared(getMoveConstructor(c)) and not isUserDeclared(getMoveAssign(c))
  )
)

So the check becomes:

c.copyAssignable() and not (
  c.isCustomized(TCopyAssignmentOperator()) and
  (
    c.isCustomized(TMoveConstructor()) and c.isCustomized(TMoveAssignmentOperator()) or
    not isUserDeclared(getMoveConstructor(c)) and not isUserDeclared(getMoveAssign(c))
  )
)

Rewriting above gives an arguably more readable version:

c.copyAssignable() and (
  /* 1. The copy assignment operator is not customized. */
  not c.isCustomized(TCopyAssignmentOperator()) or
  (
    /* 2. Any one (or both) of the move operations is not customized. */
    not c.isCustomized(TMoveConstructor() or not c.isCustomized(TMoveAssignmentOperator()) and
    /* 3. Any one (or both) of the move operations are user-declared. */
    (isUserDeclared(getMoveConstructor(c)) or isUserDeclared(getMoveAssign(c)))
  )
)

[MichaelRFairhurst]

If I'm understanding correctly, I think this is simpler.

The bullet points 2 and 3 can essentially be rephrased as:

• in the presence of a customized destructor
• if it's copy constructible the copy constructor must be customized, and
• if it's copy assignable the copy assignment operator must be customized, and
• if it's move constructible, the move constructor must be customized, and
• if it's move assignable, the the move assignment operator must be customized

The only exceptions are:

• copy enabled, not copy-assignable classes may leave the move constructor undeclared
• copy assignable classes may leave both move ctor & assign undeclared

This matches my implementation above.

We can prove each item:

if it's copy constructible, the copy constructor must be customized

If it is copy constructible, it can only be copy enabled or copy assignable. Copy enabled classes must have a customized copy constructor, and copy assignable classes must have a customized copy constructor.

Erg, all copy constructible classes must have a customized copy constructor.

Inversely, if it must have a customized copy constructor, it must be either copy constructible or copy assignable -- the other three categories have no restrictions on the copy constructor.

if it's copy assignable, the copy assignment operator must be customized

This one is a direct quote: "if it is copy-assignable it shall also have a customized copy assignment operator." No other categories place any requirements on the copy assignment operator.

if it's move constructible, the move constructor must be customized

If it's move constructible, it can belong to any category except unmovable. If it is move-only or move-assignable, it must have a customized move constructor (bullet 2).

If it is copy-enabled, it may be undeclared (exception 1) or customized. If it is copy-assignable, both move operation may be undeclared (exception 2) or the the move constructor must be customized along with the copy constructor

Ergo, all move constructible classes must fulfill either exception 1 or exception 2 or have a customized move constructor.

Inversely, the unmovable category places no requirements on the move constructor.

if it's move assignable, the move assignment operator must be customized

if its move assignable, it may be move-only. Move only and assignable classes must have a customized move assignment operator.

If it is copy-enabled, the move assignment operator may be undeclared if the move constructor is (exception 2). Otherwise, it has to be customized.

Ergo, all move assignable classes must fulfill exception 2 or have a customized move assignment operator.

Inversely, a class may be:

• unmovable, in which case there are no requirements on the move assignment operator, or
• move-only but not move assignable, in which case there are no requirements on the move assignment operator, or
• copy-enabled but not assignable, in which case there are no requirements on the move assignment operator.

brief pause

...To me, this is just much simpler overall. Not only is easier to remember that "x-operatable requires x operation is customized."

But it also makes pragmatic sense. A customized destructor indicates that you're managing a resource. Copying and moving a class requires care, during both construction and during assignment.

class Owner {
  Resource *resource;
  Owner() : resource(get_a_resource()) {}
  ~Owner() {
    release(resource);
  }
}

In the above code, the default copy operations will copy the handle, and the resource will be freed twice (once by the original, once by the copy). The default move operations will move the handle, which will typically have copy semantics.

It isn't enough to customize just the move constructor, or just the move assignment operator. Every available operation must be either customized or deleted....with one exception! If you leave the move operations undeclared, then moving will call your copy operations, so its ok to leave move operations undeclared and instead customize your copy operations.

[MichaelRFairhurst]

I think you're proposing something closer to this, right?

This is more verbose, but its absolutely possible to make the case that it has better error messages. It is also a pretty clear 1:1 mapping to the misra spec.

predicate violatesCustomizedDestructorRequirements(AnalyzableClass c, string reason) {
  c.isCustomized(TDestructor()) and
  (
    isMoveOnly(c) and
    (
      not c.isCustomized(TMoveConstructor()) and
      reason =
        "is move-only with a customized the destructor, but does not customize the move constructor."
      or
      c.moveAssignable() and
      not c.isCustomized(TMoveAssignmentOperator()) and
      reason =
        "is move-only and move-assignable with a customized the destructor, but does not customize the move assignment operator."
    )
    or
    isCopyEnabled(c) and
    (
      not c.isCustomized(TCopyConstructor()) and
      reason =
        "is copy-enabled with a customized the destructor, but does not customize the copy constructor."
      or
      not c.copyAssignable() and
      c.declaresMoveConstructor() and
      not c.isCustomized(TMoveConstructor()) and
      reason =
        "is copy-enabled with a customized the destructor, but declares a move constructor and does not customize it."
    )
    or
    c.copyAssignable() and
    (
      /* 1. The copy assignment operator is not customized. */
      not c.isCustomized(TCopyAssignmentOperator()) and
      reason =
        "is copy-assignable with a customized destructor but doesn't have a customized copy assignment operator"
      or
      /* 2. Only one of the move operations is customized. */
      c.declaresMoveConstructor() and
      not c.declaresMoveAssignmentOperator() and
      reason =
        "is copy assignable with a customized destructor, but declaring a move constructor implies that the move assignment operator should also be declared"
      or
      not c.declaresMoveConstructor() and
      c.declaresMoveAssignmentOperator() and
      reason =
        "is copy assignable with a customized destructor, but declaring a move assignment operator implies that the move constructor should also be declared"
      or
      /* 3. A move operation is declared but not customized. */
      c.declaresMoveConstructor() and
      not c.isCustomized(TMoveConstructor()) and
      reason =
        "has a customized destructor and declares a move constructor but does not customize it"
      or
      c.declaresMoveAssignmentOperator() and
      not c.isCustomized(TMoveAssignmentOperator()) and
      reason =
        "has a customized destructor and declares a move assignment operator but does not customize it"
    )
  )
}

The above version passes our current tests (just with different alert messages).

We shouldn't keep the old version unless we can clarify it. I don't know if its enough, but we could add a comment like this:

// If you follow the logic of each case in the rule specification, you'll find that all classes in a valid
// category that have a customized destructor, must customize every "x-operation" when the
// class is "x-operatable."
//
// This is logic makes perfect sense. A customized destructor indicates the class manages a
// resource, and such classes must customize every supported operation to prevent unwanted
// sharing, such as double frees.
//
// The only exception is that copy-enabled classes may sometimes omit move declarations. This
// also makes sense: when these operations aren't declared, the corresponding copy operation
// will be used instead.

Hopefully this comment:

• explains that this is intentionally formulated differently than the rule text
• explains the value of this formulation over the spec's formulation
• makes it easier for a reader verify that the code does what it intends to do
• makes the code easier to maintain

[MichaelRFairhurst]

Oh, one last thought, and I don't really know which method this supports.

The original/current version will report errors for cases that are not one of the valid categories (not unmovable, or move-only, or copy-enabled), while the rewrite I posted above will not.

Usually this is a bad thing. We don't want to give two alerts when we could give one.

In this case, you could argue the reverse, that a class with a customized destructor and an otherwise defaulted operation should always get a warning. If a user intentionally writes a class that doesn't fit one of the categories (unmovable, move-only, copy-enabled), they might ignore that alert, and then they'll never get a warning that they forgot to customize their move assignment constructor.

Interesting to consider. Maybe not an issue in practice. On qlx, these two versions give the exact same results.

[jeongsoolee09]

Would there be value to adding a variety of this class that has a copy constructor?

class NonTrivialClass {
  int x;
  int y;
public:
  COPY_CTOR(TrivialClass) = default;
  ~NonTrivialClass() { x = 1; }
};

[MichaelRFairhurst]

Done in 61a4dd9!

[jeongsoolee09]

Some thoughts, overall looks amazing!! Thank you so much for tackling this to an already great extent!