Merge branch 'main' into pipeline/fix-ranges

README.md

@@ -69,6 +69,20 @@ Note: we recommend using nvm (for [Windows](https://github.com/coreybutler/nvm-w
 [MacOS/Linux](https://github.com/nvm-sh/nvm)) or [fnm](https://github.com/Schniz/fnm) to install Node.js, in case you find yourself needing to install different
 versions of Node.js side-by-side.
 
+Because of a transitive dependency on a native addon module, you'll also need to ensure that you have the prerequisites for `node-gyp`. Depending on your operating system, you'll have slightly different installation requirements (these are largely copied from `node-gyp`'s [documentation](https://github.com/nodejs/node-gyp#readme)):
+
+### On Windows
+The node installer should ask if you want to install "Tools for Native Modules." If you check the box for this nothing further should be needed. Otherwise, you can follow the steps listed [here](https://github.com/Microsoft/nodejs-guidelines/blob/master/windows-environment.md#prerequisites)
+### On Unix
+1. Python v3.7, v3.8, v3.9, or v3.10
+2. `make`
+3. A C/C++ toolchain (like [GCC](https://gcc.gnu.org/))
+### On MacOS
+If you've *upgraded* your Mac to Catalina or higher, you may need to follow [these](https://github.com/nodejs/node-gyp/blob/main/macOS_Catalina.md) instructions.
+1. Python v3.7, v3.8, v3.9, or v3.10
+2. `XCode Command Line Tools`, which will install `make`, `clang`, and `clang++`
+    - You can install these by running `xcode-select --install` from a command line.
+
 Clone a copy of the repo and change to the repo root directory:
 
 ```shell

api-report/azure-client.api.md

@@ -18,7 +18,7 @@ import { IUser } from '@fluidframework/protocol-definitions';
 import { ScopeType } from '@fluidframework/protocol-definitions';
 import { ServiceAudience } from '@fluidframework/fluid-static';
 
-// @public (undocumented)
+// @public
 export class AzureAudience extends ServiceAudience<AzureMember> implements IAzureAudience {
     // @internal
     protected createServiceMember(audienceMember: IClient): AzureMember;

api-report/tree.api.md

@@ -80,8 +80,8 @@ export interface ChangeFamily<TEditor, TChange> {
 export interface ChangeRebaser<TChangeset> {
     compose(changes: TChangeset[]): TChangeset;
     // (undocumented)
-    invert(changes: TChangeset): TChangeset;
-    rebase(change: TChangeset, over: TChangeset): TChangeset;
+    invert(changes: TaggedChange<TChangeset>): TChangeset;
+    rebase(change: TChangeset, over: TaggedChange<TChangeset>): TChangeset;
     // (undocumented)
     rebaseAnchors(anchors: AnchorSet, over: TChangeset): void;
     // (undocumented)
@@ -216,6 +216,7 @@ export interface EditableField extends ArrayLike<UnwrappedEditableTree> {
 export interface EditableTree extends Iterable<EditableField> {
     readonly [anchorSymbol]: Anchor;
     [getTypeSymbol](key?: FieldKey, nameOnly?: boolean): NamedTreeSchema | TreeSchemaIdentifier | undefined;
+    [getWithoutUnwrappingSymbol](fieldKey: FieldKey): EditableField;
     readonly [proxyTargetSymbol]: object;
     [Symbol.iterator](): IterableIterator<EditableField>;
     readonly [valueSymbol]: Value;
@@ -305,8 +306,8 @@ export type FieldChangeMap = Map<FieldKey, FieldChange>;
 export interface FieldChangeRebaser<TChangeset> {
     compose(changes: TChangeset[], composeChild: NodeChangeComposer): TChangeset;
     // (undocumented)
-    invert(change: TChangeset, invertChild: NodeChangeInverter): TChangeset;
-    rebase(change: TChangeset, over: TChangeset, rebaseChild: NodeChangeRebaser): TChangeset;
+    invert(change: TaggedChange<TChangeset>, invertChild: NodeChangeInverter): TChangeset;
+    rebase(change: TChangeset, over: TaggedChange<TChangeset>, rebaseChild: NodeChangeRebaser): TChangeset;
 }
 
 // @public (undocumented)
@@ -405,6 +406,9 @@ export interface GenericTreeNode<TChild> extends GenericFieldsNode<TChild>, Node
 // @public
 export const getTypeSymbol: unique symbol;
 
+// @public
+export const getWithoutUnwrappingSymbol: unique symbol;
+
 // @public
 export type GlobalFieldKey = Brand<string, "tree.GlobalFieldKey">;
 
@@ -505,7 +509,7 @@ export interface Invariant<T> extends Contravariant<T>, Covariant<T> {
 }
 
 // @public
-function invert<TNodeChange>(change: Changeset<TNodeChange>, invertChild: NodeChangeInverter_2<TNodeChange>): Changeset<TNodeChange>;
+function invert<TNodeChange>(change: TaggedChange<Changeset<TNodeChange>>, invertChild: NodeChangeInverter_2<TNodeChange>): Changeset<TNodeChange>;
 
 // @public
 export type isAny<T> = boolean extends (T extends {} ? true : false) ? true : false;
@@ -768,9 +772,9 @@ export class ModularChangeFamily implements ChangeFamily<ModularEditBuilder, Fie
     // (undocumented)
     intoDelta(change: FieldChangeMap): Delta.Root;
     // (undocumented)
-    invert(changes: FieldChangeMap): FieldChangeMap;
+    invert(changes: TaggedChange<FieldChangeMap>): FieldChangeMap;
     // (undocumented)
-    rebase(change: FieldChangeMap, over: FieldChangeMap): FieldChangeMap;
+    rebase(change: FieldChangeMap, over: TaggedChange<FieldChangeMap>): FieldChangeMap;
     // (undocumented)
     rebaseAnchors(anchors: AnchorSet, over: FieldChangeMap): void;
     // (undocumented)
@@ -982,11 +986,14 @@ interface Reattach extends HasOpId {
 }
 
 // @public
-function rebase<TNodeChange>(change: Changeset<TNodeChange>, base: Changeset<TNodeChange>, rebaseChild: NodeChangeRebaser_2<TNodeChange>): Changeset<TNodeChange>;
+function rebase<TNodeChange>(change: Changeset<TNodeChange>, base: TaggedChange<Changeset<TNodeChange>>, rebaseChild: NodeChangeRebaser_2<TNodeChange>): Changeset<TNodeChange>;
 
 // @public
 export function recordDependency(dependent: ObservingDependent | undefined, dependee: Dependee): void;
 
+// @public
+export type RevisionTag = Brand<number, "rebaser.RevisionTag">;
+
 // @public
 type Root<TTree = ProtoNode> = FieldMarks<TTree>;
 
@@ -1165,6 +1172,14 @@ export interface StoredSchemaRepository<TPolicy extends SchemaPolicy = SchemaPol
 // @public (undocumented)
 export function symbolFromKey(key: GlobalFieldKey): GlobalFieldKeySymbol;
 
+// @public (undocumented)
+export interface TaggedChange<TChangeset> {
+    // (undocumented)
+    readonly change: TChangeset;
+    // (undocumented)
+    readonly revision: RevisionTag | undefined;
+}
+
 // @public (undocumented)
 enum Tiebreak {
     // (undocumented)

azure/packages/azure-client/.eslintrc.js

@@ -5,8 +5,40 @@
 
 module.exports = {
     extends: [require.resolve("@fluidframework/eslint-config-fluid/strict"), "prettier"],
+    plugins: ["eslint-plugin-jsdoc"],
     parserOptions: {
         project: ["./tsconfig.json", "./src/test/tsconfig.json"],
     },
-    rules: {},
+    rules: {
+        // Require jsdoc/tsdoc comments on public/exported API items.
+        "jsdoc/require-jsdoc": [
+            "error",
+            {
+                // Indicates that only module exports should be flagged for lacking jsdoc comments
+                publicOnly: true,
+                enableFixer: false, // Prevents eslint from adding empty comment blocks when run with `--fix`
+                require: {
+                    ClassDeclaration: true,
+                    FunctionDeclaration: true,
+
+                    // Will report for *any* methods on exported classes, regardless of whether or not they are public
+                    MethodDefinition: false,
+                },
+                contexts: ["TSEnumDeclaration", "TSInterfaceDeclaration", "TSTypeAliasDeclaration"],
+            },
+        ],
+
+        // Ensure jsdoc/tsdoc comments contain a main description component
+        // (disallows empty comments / only tags).
+        "jsdoc/require-description": ["error", { checkConstructors: false }],
+    },
+    overrides: [
+        {
+            files: ["packageVersion.ts"],
+            rules: {
+                "jsdoc/require-jsdoc": "off",
+                "jsdoc/require-description": "off",
+            },
+        },
+    ],
 };

azure/packages/azure-client/package.json

@@ -67,7 +67,7 @@
     "@fluidframework/build-common": "^1.0.0",
     "@fluidframework/build-tools": "^0.4.4000",
     "@fluidframework/counter": "^1.3.0",
-    "@fluidframework/eslint-config-fluid": "^1.0.0",
+    "@fluidframework/eslint-config-fluid": "^1.1.0",
     "@fluidframework/test-client-utils": "^1.3.0",
     "@fluidframework/test-utils": "^1.3.0",
     "@microsoft/api-extractor": "^7.22.2",
@@ -78,6 +78,7 @@
     "cross-env": "^7.0.2",
     "eslint": "~8.6.0",
     "eslint-config-prettier": "~8.5.0",
+    "eslint-plugin-jsdoc": "~39.3.0",
     "mocha": "^10.0.0",
     "prettier": "~2.6.2",
     "rimraf": "^2.6.2",

azure/packages/azure-client/src/AzureAudience.ts

@@ -8,6 +8,11 @@ import { IClient } from "@fluidframework/protocol-definitions";
 
 import { AzureMember, AzureUser, IAzureAudience } from "./interfaces";
 
+/**
+ * Azure-specific {@link @fluidframework/fluid-static#ServiceAudience} implementation.
+ *
+ * @remarks Operates in terms of {@link AzureMember}s.
+ */
 export class AzureAudience extends ServiceAudience<AzureMember> implements IAzureAudience {
     /**
      * Creates a {@link @fluidframework/fluid-static#ServiceAudience} from the provided

azure/packages/azure-local-service/.eslintrc.js

@@ -3,15 +3,42 @@
  * Licensed under the MIT License.
  */
 
- module.exports = {
-    "extends": [
-        require.resolve("@fluidframework/eslint-config-fluid")
-    ],
-    "parserOptions": {
-        "project": ["./tsconfig.json"]
+module.exports = {
+    extends: [require.resolve("@fluidframework/eslint-config-fluid/strict")],
+    plugins: ["eslint-plugin-jsdoc"],
+    parserOptions: {
+        project: ["./tsconfig.json"],
     },
-    "rules": {
-        "import/no-unassigned-import": "off",
-        "@typescript-eslint/strict-boolean-expressions": "off"
-    }
-}
+    rules: {
+        // Require jsdoc/tsdoc comments on public/exported API items.
+        "jsdoc/require-jsdoc": [
+            "error",
+            {
+                // Indicates that only module exports should be flagged for lacking jsdoc comments
+                publicOnly: true,
+                enableFixer: false, // Prevents eslint from adding empty comment blocks when run with `--fix`
+                require: {
+                    ClassDeclaration: true,
+                    FunctionDeclaration: true,
+
+                    // Will report for *any* methods on exported classes, regardless of whether or not they are public
+                    MethodDefinition: false,
+                },
+                contexts: ["TSEnumDeclaration", "TSInterfaceDeclaration", "TSTypeAliasDeclaration"],
+            },
+        ],
+
+        // Ensure jsdoc/tsdoc comments contain a main description component
+        // (disallows empty comments / only tags).
+        "jsdoc/require-description": ["error", { checkConstructors: false }],
+    },
+    overrides: [
+        {
+            files: ["packageVersion.ts"],
+            rules: {
+                "jsdoc/require-jsdoc": "off",
+                "jsdoc/require-description": "off",
+            },
+        },
+    ],
+};

azure/packages/azure-local-service/package.json

@@ -36,12 +36,13 @@
   },
   "devDependencies": {
     "@fluidframework/build-common": "^1.0.0",
-    "@fluidframework/eslint-config-fluid": "^1.0.0",
+    "@fluidframework/eslint-config-fluid": "^1.1.0",
     "@microsoft/api-extractor": "^7.22.2",
     "@rushstack/eslint-config": "^2.5.1",
     "concurrently": "^6.2.0",
     "copyfiles": "^2.4.1",
     "eslint": "~8.6.0",
+    "eslint-plugin-jsdoc": "~39.3.0",
     "forever": "^4.0.3",
     "rimraf": "^2.6.2",
     "ts-node": "^8.6.2",

azure/packages/azure-local-service/src/index.ts

@@ -4,4 +4,5 @@
  * Licensed under the MIT License.
  */
 
+// eslint-disable-next-line import/no-unassigned-import
 import "tinylicious";

azure/packages/azure-local-service/tsconfig.json

@@ -2,12 +2,11 @@
     "extends": "@fluidframework/build-common/ts-common-config.json",
     "exclude": [],
     "compilerOptions": {
-        "strictNullChecks": false,
         "rootDir": "./src",
         "outDir": "./dist",
         "composite": true
     },
     "include": [
         "src/**/*"
     ]
-}
+}