Cline rules

1# Objective-C Code Style Guidelines for AI Agents
2 
3## Overview
4 
5This document provides code style guidelines that AI agents MUST follow when working with this Objective-C codebase. These guidelines are adapted from industry best practices and tailored to match the existing code patterns in this repository.
6 
7## Key Principles
8 
9### RFC 2119 Compliance
10 
11- **MUST**: Absolute requirement
12- **MUST NOT**: Absolute prohibition
13- **SHOULD**: Recommended but may have valid reasons to ignore
14- **SHOULD NOT**: Not recommended but may have valid reasons to use
15- **MAY**: Optional
16 
17---
18 
19## Code Style Rules
20 
21### 1. Dot Notation Syntax
22 
23**RECOMMENDED:** Use dot notation for getting and setting properties.
24 
25```objc
26// Preferred
27view.backgroundColor = UIColor.orangeColor;
28NSString *username = account.username;
29 
30// Avoid
31[view setBackgroundColor:[UIColor orangeColor]];
32NSString *username = [account username];
33```
34 
35### 2. Spacing and Indentation
36 
37**MUST** follow these spacing rules:
38 
39- Indentation: 4 spaces (never tabs)
40- **Opening braces on NEW line** (repository convention)
41- Closing braces on new line
42- One blank line between methods
43 
44```objc
45// Correct (as used in this repository)
46- (instancetype)initWithUsername:(NSString *)username
47                   homeAccountId:(MSALAccountId *)homeAccountId
48                     environment:(NSString *)environment
49{
50    self = [super init];
51    
52    if (self)
53    {
54        _username = username;
55        _environment = environment;
56        _homeAccountId = homeAccountId;
57    }
58    
59    return self;
60}
61 
62// For if/else statements
63if (user.isHappy)
64{
65    // Do something
66}
67else
68{
69    // Do something else
70}
71```
72 
73### 3. Conditionals
74 
75**MUST** always use braces for conditional bodies, even for single-line statements.
76 
77```objc
78// Correct
79if (!error)
80{
81    return success;
82}
83 
84// Incorrect - Never do this
85if (!error)
86    return success;
87 
88if (!error) return success;
89```
90 
91### 4. Ternary Operator
92 
93**SHOULD** only evaluate a single condition per ternary expression.
94 
95```objc
96// Acceptable
97result = account.isValid ? account : nil;
98 
99// Avoid - too complex
100result = account.isValid ? account.username = tenant.isValid ? tenant.id : nil : nil;
101```
102 
103### 5. Error Handling
104 
105**MUST** check the return value, **MUST NOT** check the error variable directly.
106 
107```objc
108// Correct
109NSError *error;
110if (![self trySomethingWithError:&error])
111{
112    // Handle Error
113}
114 
115// Incorrect - Apple APIs may write garbage to error on success
116NSError *error;
117[self trySomethingWithError:&error];
118if (error)
119{
120    // Handle Error
121}
122```
123 
124### 6. Method Signatures
125 
126**SHOULD** include space after scope symbol and between method segments.
127 
128```objc
129// Correct
130- (void)acquireTokenWithParameters:(MSALSilentTokenParameters *)parameters
131                   completionBlock:(MSALCompletionBlock)completionBlock;
132 
133// For methods exceeding 80 characters, format like a form
134- (MSALResult *)resultWithTokenResult:(MSIDTokenResult *)result
135                           authScheme:(id<MSALAuthenticationSchemeProtocol>)authScheme
136                           popManager:(MSIDDevicePopManager *)popManager
137                                error:(NSError **)error;
138```
139 
140### 7. Variables
141 
142#### Naming
143 
144**SHOULD** use descriptive variable names:
145 
146- `NSString *username` - clear and concise
147- `NSString *accessToken` - describes the token type
148- `MSALAccount *currentAccount` - not just `account`
149- `MSIDRequestParameters *requestParams` - abbreviated but clear
150- `MSALPublicClientApplicationConfig *config` - clear context
151 
152**NOT RECOMMENDED:** Single letter variable names (except loop counters)
153 
154#### Pointer Asterisks
155 
156**MUST** attach asterisks to variable name:
157 
158```objc
159// Correct
160NSString *clientId
161 
162// Incorrect
163NSString* clientId
164NSString * clientId
165```
166 
167Exception: Constants (`NSString * const MSALErrorDomain`)
168 
169#### Properties vs Instance Variables
170 
171**SHOULD** use properties instead of naked instance variables.
172 
173```objc
174// Preferred
175@interface MSALAccount : NSObject
176@property (nonatomic) NSString *username;
177@property (nonatomic) NSString *environment;
178@end
179 
180// Avoid
181@interface MSALAccount : NSObject
182{
183    NSString *username;
184    NSString *environment;
185}
186@end
187```
188 
189**SHOULD** avoid direct instance variable access except in:
190 
191- Initializer methods (`init`, `initWithCoder:`)
192- `dealloc` methods
193- Custom setters and getters
194 
195#### Variable Qualifiers
196 
197**SHOULD** place ARC qualifiers between asterisks and variable name:
198 
199```objc
200NSString * __weak weakReference;
201MSALAccount * __autoreleasing autoreleasedAccount;
202```
203 
204### 8. Naming Conventions
205 
206#### Class Names and Constants
207 
208**MUST** use `MSAL` prefix for public classes and constants
209**MAY** use `MSID` prefix for internal/shared classes
210 
211```objc
212// Correct
213static const NSTimeInterval MSALDefaultTokenRefreshInterval = 300.0;
214static NSString * const MSALErrorDomain = @"MSALErrorDomain";
215 
216// Incorrect
217static const NSTimeInterval refreshInterval = 300.0;
218```
219 
220#### Properties and Local Variables
221 
222**MUST** be camelCase with lowercase leading word.
223 
224```objc
225NSString *accessToken;
226MSALAccount *currentAccount;
227MSIDRequestParameters *requestParams;
228```
229 
230#### Instance Variables
231 
232**MUST** be camelCase with lowercase leading word and underscore prefix:
233 
234```objc
235@implementation MSALPublicClientApplication
236{
237    BOOL _validateAuthority;
238    WKWebView *_customWebview;
239    NSString *_defaultKeychainGroup;
240}
241```
242 
243### 9. Categories
244 
245**MUST** prefix category methods with `msal` or `msid` to avoid collisions:
246 
247```objc
248// Correct
249@interface NSArray (MSALAccessors)
250- (id)msalObjectOrNilAtIndex:(NSUInteger)index;
251@end
252 
253// Incorrect - may conflict with other libraries
254@interface NSArray (MSALAccessors)
255- (id)objectOrNilAtIndex:(NSUInteger)index;
256@end
257```
258 
259### 10. Comments
260 
261**SHOULD** explain **why**, not what.
262**MUST** keep comments up-to-date or delete them.
263**NOT RECOMMENDED:** Block comments (code should be self-documenting).
264 
265### 11. Literals
266 
267**SHOULD** use literals for `NSString`, `NSDictionary`, `NSArray`, `NSNumber`:
268 
269```objc
270// Preferred
271NSArray *scopes = @[@"user.read", @"mail.read", @"profile"];
272NSDictionary *claims = @{@"id_token": @{@"auth_time": @{@"essential": @YES}}};
273NSNumber *isEnabled = @YES;
274NSNumber *timeout = @30;
275 
276// Avoid
277NSArray *scopes = [NSArray arrayWithObjects:@"user.read", @"mail.read", @"profile", nil];
278```
279 
280**Warning:** Never pass `nil` into array/dictionary literals - causes crash.
281 
282### 12. Constants
283 
284**MUST** declare as `static` constants:
285 
286```objc
287static NSString * const MSALErrorDomain = @"MSALErrorDomain";
288static const CGFloat MSALDefaultTimeout = 30.0;
289static const NSTimeInterval MSALTokenExpirationBuffer = 300.0;
290```
291 
292**MAY** use `#define` only when explicitly used as a macro.
293 
294### 13. Enumerated Types
295 
296**MUST** use `NS_ENUM()` for enumerations:
297 
298```objc
299typedef NS_ENUM(NSInteger, MSALPromptType)
300{
301    MSALPromptTypeDefault,
302    MSALPromptTypeLogin,
303    MSALPromptTypeConsent,
304    MSALPromptTypeSelectAccount
305};
306```
307 
308### 14. Private Properties
309 
310**SHALL** declare private properties in class extensions in implementation file:
311 
312```objc
313// In MSALPublicClientApplication.m
314@interface MSALPublicClientApplication()
315{
316    BOOL _validateAuthority;
317    WKWebView *_customWebview;
318}
319 
320@property (nonatomic) MSALPublicClientApplicationConfig *internalConfig;
321@property (nonatomic) MSIDExternalAADCacheSeeder *externalCacheSeeder;
322@property (nonatomic) MSIDCacheConfig *msidCacheConfig;
323 
324@end
325```
326 
327### 15. Singletons
328 
329**SHOULD** use thread-safe pattern with `dispatch_once`:
330 
331```objc
332+ (instancetype)sharedInstance
333{
334    static id sharedInstance = nil;
335    static dispatch_once_t onceToken;
336    dispatch_once(&onceToken, ^{
337        sharedInstance = [[[self class] alloc] init];
338    });
339    return sharedInstance;
340}
341```
342 
343### 16. Imports
344 
345**MUST NOT** group imports (repository convention).
346 
347```objc
348// Correct (as used in this repository)
349#import "MSALPublicClientApplication+Internal.h"
350#import "MSALPromptType_Internal.h"
351#import "MSALError.h"
352#import "MSALTelemetryApiId.h"
353#import "MSIDMacTokenCache.h"
354#import "MSIDLegacyTokenCacheAccessor.h"
355#import "MSIDDefaultTokenCacheAccessor.h"
356 
357// Do NOT group like this
358// Frameworks
359@import Foundation;
360 
361// MSAL Core
362#import "MSALPublicClientApplication.h"
363```
364 
365### 21. Protocols (Delegates)
366 
367**SHOULD** make first parameter the object sending the message:
368 
369```objc
370// Correct
371- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath;
372 
373// Incorrect
374- (void)didSelectTableRowAtIndexPath:(NSIndexPath *)indexPath;
375```
376 
377### 22. Block Declarations
378 
379**SHOULD** use clear formatting for complex blocks:
380 
381```objc
382__auto_type block = ^(MSALResult *result, NSError *msidError, id<MSIDRequestContext> context)
383{
384    NSError *msalError = [MSALErrorConverter msalErrorFromMsidError:msidError 
385                                                     classifyErrors:YES 
386                                                 msalOauth2Provider:self.msalOauth2Provider];
387    
388    if (!completionBlock) return;
389    
390    if (parameters.completionBlockQueue)
391    {
392        dispatch_async(parameters.completionBlockQueue, ^{
393            completionBlock(result, msalError);
394        });
395    }
396    else
397    {
398        completionBlock(result, msalError);
399    }
400};
401```
402 
403### 23. Xcode Project Organization
404 
405**SHOULD** keep physical files in sync with Xcode project structure.
406**SHOULD** reflect Xcode groups as filesystem folders.
407**SHOULD** group code by feature, not just by type.
408**SHOULD** enable "Treat Warnings as Errors" build setting.
409 
410---
411 
412## AI Agent-Specific Guidelines
413 
414### When Adding New Features:
415 
4161. **Match Existing Patterns**: Analyze similar existing code before implementing
4172. **Follow MSAL Conventions**: Use `MSAL` prefix for public classes, `MSID` for internal code in CommonCore sub repository
4183. **Maintain Consistency**: Match indentation, spacing, and naming in surrounding code
4194. **Property-First**: Use `@property` declarations rather than instance variables
4205. **Error Handling**: Always check return values, never the error variable
4216. **Thread Safety**: Use `dispatch_once` for singletons, consider thread safety for shared resources
4227. **Memory Management**: Follow ARC patterns, be mindful of retain cycles
4238. **Nil Safety**: Never pass `nil` to array/dictionary literals
4249. **Documentation**: Add header documentation for public APIs
42510. **Test Coverage**: Consider how changes affect existing tests
426 
427### When Modifying Existing Code:
428 
4291. **Preserve Style**: Don't mix styles within a file
4302. **Minimal Changes**: Change only what's necessary
4313. **Update Comments**: Keep comments synchronized with code changes
4324. **Deprecation**: Use proper deprecation warnings when replacing APIs
4335. **Backward Compatibility**: Consider impact on existing integrations
434 
435### Common MSAL Patterns:
436 
437#### Error Handling Pattern
438 
439```objc
440NSError *msidError = nil;
441BOOL result = [self performOperationWithError:&msidError];
442 
443if (!result)
444{
445    if (error) *error = [MSALErrorConverter msalErrorFromMsidError:msidError];
446    return NO;
447}
448```
449 
450#### Completion Block Pattern
451 
452```objc
453__auto_type block = ^(MSALResult *result, NSError *error)
454{
455    // Process result
456    
457    if (!completionBlock) return;
458    
459    if (parameters.completionBlockQueue)
460    {
461        dispatch_async(parameters.completionBlockQueue, ^{
462            completionBlock(result, error);
463        });
464    }
465    else
466    {
467        completionBlock(result, error);
468    }
469};
470```
471 
472#### Logging Pattern
473 
474```objc
475MSID_LOG_WITH_CTX_PII(MSIDLogLevelInfo, context, 
476                      @"Operation completed with account %@", 
477                      MSID_PII_LOG_EMAIL(account.username));
478```
479 
480### Code Review Checklist:
481 
482- [ ] Uses 4-space indentation (no tabs)
483- [ ] Opening braces on new line
484- [ ] All conditionals have braces
485- [ ] Error handling checks return value, not error variable
486- [ ] Method signatures properly spaced
487- [ ] Variables descriptively named
488- [ ] Pointers attached to variable names
489- [ ] Uses properties instead of instance variables
490- [ ] Category methods prefixed with `msal` or `msid`
491- [ ] Uses `NS_ENUM` for enumerations
492- [ ] Private properties in class extension
493- [ ] Singletons use `dispatch_once`
494- [ ] Imports not grouped (per repository style)
495- [ ] Delegate methods include sender as first parameter
496- [ ] No warnings or errors in build
497- [ ] Follows existing MSAL/MSID patterns
498 
499---
500 
501## References
502 
503- [Apple: The Objective-C Programming Language](https://developer.apple.com/library/content/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html)
504- [Apple: Coding Guidelines for Cocoa](https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html)
505- [Apple: Memory Management Programming Guide](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmPractical.html)
506- [IETF RFC 2119: Key words for use in RFCs](http://tools.ietf.org/html/rfc2119)
507 
508---
509 
510## Repository-Specific Conventions
511 
512### Key Differences from Standard Guidelines:
513 
5141. **Braces on New Line**: Unlike many Objective-C style guides, this repository places opening braces on a new line
5152. **No Import Grouping**: Imports are listed without grouping or comments
5163. **MSAL/MSID Prefixes**: Public APIs use `MSAL`, internal/shared from CommonCore repository use `MSID`
5174. **Extensive Logging**: PII-aware logging with `MSID_LOG_WITH_CTX` macros
5185. **Block-based Async**: Completion handlers with queue dispatch patterns
519 
520### Copyright Header
521 
522All new files **MUST** include the Microsoft copyright header when added to this repository, but not when generating a new sample app:
523 
524```objc
525//------------------------------------------------------------------------------
526//
527// Copyright (c) Microsoft Corporation.
528// All rights reserved.
529//
530// This code is licensed under the MIT License.
531//
532// Permission is hereby granted, free of charge, to any person obtaining a copy
533// of this software and associated documentation files(the "Software"), to deal
534// in the Software without restriction, including without limitation the rights
535// to use, copy, modify, merge, publish, distribute, sublicense, and / or sell
536// copies of the Software, and to permit persons to whom the Software is
537// furnished to do so, subject to the following conditions :
538//
539// The above copyright notice and this permission notice shall be included in
540// all copies or substantial portions of the Software.
541//
542// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
543// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
544// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
545// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
546// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
547// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
548// THE SOFTWARE.
549//
550//------------------------------------------------------------------------------
551```
552 
553---
554 
555## Notes
556 
557This style guide is adapted specifically for AI agents working on the Microsoft Authentication Library (MSAL) for iOS and macOS. When in doubt, prioritize consistency with existing codebase patterns over strict adherence to external style guides.
558