legend-doctor 0.1.0

package/dist/src/rules/observable-reads/narrow-use-value.js

@@ -0,0 +1,150 @@
+import { RESERVED_OBSERVABLE_MEMBERS, isUseValueCall, isValueReferenceTo, provenObservablePath, } from "./observable-paths.js";
+import { bindingDeclarationCount, isDeclarationName } from "../../core/analysis-ast.js";
+import { commonPathPrefix, optionalAccessPreservesSuffix, rawValuePathHasOptionalAccess, staticRawValuePath, } from "./raw-value-paths.js";
+import { findAncestor, isRuntimeFunctionLike, visit } from "../../core/ast.js";
+import { splitLeavesFinding } from "./split-leaves.js";
+import ts from "typescript";
+export function narrowUseValueFinding(declaration, scan) {
+    const call = declaration.initializer;
+    if (!call ||
+        !ts.isCallExpression(call) ||
+        call.arguments.length !== 1 ||
+        !isUseValueCall(call, scan.imports)) {
+        return null;
+    }
+    const observable = provenObservablePath(call.arguments[0], scan.observableBindings);
+    if (!observable) {
+        return null;
+    }
+    if (ts.isObjectBindingPattern(declaration.name)) {
+        return narrowBindingPatternFinding({ declaration, observable }, declaration.name, scan);
+    }
+    return ts.isIdentifier(declaration.name)
+        ? narrowIdentifierFinding({ declaration, observable }, declaration.name.text, scan)
+        : null;
+}
+function narrowBindingPatternFinding(candidate, binding, scan) {
+    const [element] = binding.elements;
+    const property = element && !ts.isOmittedExpression(element)
+        ? (element.propertyName?.getText(scan.sourceFile) ?? element.name.getText(scan.sourceFile))
+        : null;
+    if (property &&
+        consumesEveryKnownField(candidate.observable, [[property]], scan.observableKeys)) {
+        return null;
+    }
+    return narrowObjectBindingFinding(candidate, binding, scan);
+}
+function rawValueReads(candidate, localName, owner) {
+    const paths = [];
+    const optionalReferences = [];
+    let unsafe = false;
+    visit(owner.body, (node) => {
+        if (unsafe || !isValueReferenceTo(node, localName, candidate.declaration.name)) {
+            return;
+        }
+        const path = isDeclarationName(node) ? null : staticRawValuePath(node);
+        if (!path) {
+            unsafe = true;
+            return;
+        }
+        if (rawValuePathHasOptionalAccess(node)) {
+            optionalReferences.push(node);
+        }
+        paths.push(path);
+    });
+    return unsafe || paths.length === 0
+        ? null
+        : { candidate, localName, optionalReferences, owner, paths };
+}
+function commonReadPathPrefix(paths) {
+    let common = paths[0] ?? [];
+    for (const path of paths.slice(1)) {
+        common = commonPathPrefix(common, path);
+    }
+    return common;
+}
+function narrowIdentifierFinding(candidate, localName, scan) {
+    const owner = findAncestor(candidate.declaration, isRuntimeFunctionLike);
+    if (!owner?.body || bindingDeclarationCount(owner, localName) !== 1) {
+        return null;
+    }
+    const reads = rawValueReads(candidate, localName, owner);
+    if (reads === null ||
+        consumesEveryKnownField(candidate.observable, reads.paths, scan.observableKeys)) {
+        return null;
+    }
+    const commonPath = commonReadPathPrefix(reads.paths);
+    if (commonPath.length === 0) {
+        return reads.optionalReferences.length > 0 ? null : splitLeavesFinding(reads, scan);
+    }
+    return narrowCommonPathFinding(reads, commonPath, scan);
+}
+function narrowCommonPathFinding(reads, commonPath, scan) {
+    if (reads.optionalReferences.some((reference) => !optionalAccessPreservesSuffix(reference, commonPath.length))) {
+        return null;
+    }
+    return narrowFinding({
+        declaration: reads.candidate.declaration,
+        destructured: false,
+        localName: reads.localName,
+        observable: reads.candidate.observable,
+        property: commonPath.join("."),
+        reads: reads.paths.length,
+    }, scan);
+}
+function consumesEveryKnownField(observable, paths, observableKeys) {
+    if (!ts.isIdentifier(observable) || paths.some((path) => path.length !== 1)) {
+        return false;
+    }
+    const knownKeys = observableKeys.get(observable.text);
+    if (!knownKeys || knownKeys.size === 0) {
+        return false;
+    }
+    const consumed = new Set(paths.map((path) => path[0]));
+    return consumed.size === knownKeys.size && [...knownKeys].every((key) => consumed.has(key));
+}
+function narrowObjectBindingFinding(candidate, binding, scan) {
+    const { elements } = binding;
+    const [element] = elements;
+    if (elements.length !== 1 ||
+        !element ||
+        element.dotDotDotToken ||
+        element.initializer ||
+        !ts.isIdentifier(element.name) ||
+        (element.propertyName && !ts.isIdentifier(element.propertyName))) {
+        return null;
+    }
+    const property = element.propertyName?.text ?? element.name.text;
+    if (RESERVED_OBSERVABLE_MEMBERS.has(property)) {
+        return null;
+    }
+    return narrowFinding({
+        declaration: candidate.declaration,
+        destructured: true,
+        localName: element.name.text,
+        observable: candidate.observable,
+        property,
+        reads: 1,
+    }, scan);
+}
+function narrowFinding(instruction, scan) {
+    const { line, character } = scan.sourceFile.getLineAndCharacterOfPosition(instruction.declaration.getStart(scan.sourceFile));
+    const parentPath = instruction.observable.getText(scan.sourceFile);
+    const leafPath = `${parentPath}.${instruction.property}`;
+    const message = instruction.destructured
+        ? `Replace the single-property destructure with \`const ${instruction.localName} = useValue(${leafPath})\``
+        : `Narrow \`${instruction.localName}\` from \`useValue(${parentPath})\` to \`useValue(${leafPath})\`; bind the leaf value directly and replace the \`${instruction.localName}.${instruction.property}\` reads`;
+    return {
+        action: "narrow-use-value-subscription",
+        confidence: "certain",
+        disposition: "change",
+        evidence: [
+            `the value from ${parentPath} is read only through the static \`${instruction.property}\` property`,
+            `${leafPath} is a proven Legend observable path and has ${instruction.reads} raw-value read${instruction.reads === 1 ? "" : "s"}`,
+        ],
+        location: { column: character + 1, file: scan.fileName, line: line + 1 },
+        message: `${message} so sibling observable fields no longer invalidate this component.`,
+        practice: "reactivity",
+    };
+}
+//# sourceMappingURL=narrow-use-value.js.map

package/dist/src/rules/observable-reads/narrow-use-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narrow-use-value.js","sourceRoot":"","sources":["../../../../src/rules/observable-reads/narrow-use-value.ts"],"names":[],"mappings":"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"}

package/dist/src/rules/observable-reads/non-tracking-snapshots.d.ts

@@ -0,0 +1,11 @@
+import type { ObservableReadScan } from "./model.js";
+import type { LegendPracticeFinding } from "../../core/types.js";
+import ts from "typescript";
+interface NonTrackingSnapshot {
+    observable: ts.Expression;
+    source: "observable-listener" | "react-or-event" | "source-proven-effect";
+}
+export declare function nonTrackingSnapshotObservable(call: ts.CallExpression, scan: ObservableReadScan): NonTrackingSnapshot | null;
+export declare function nonTrackingSnapshotFinding(call: ts.CallExpression, snapshot: NonTrackingSnapshot, scan: ObservableReadScan): LegendPracticeFinding;
+export {};
+//# sourceMappingURL=non-tracking-snapshots.d.ts.map

package/dist/src/rules/observable-reads/non-tracking-snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"non-tracking-snapshots.d.ts","sourceRoot":"","sources":["../../../../src/rules/observable-reads/non-tracking-snapshots.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAgB,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAInE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAKjE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,UAAU,mBAAmB;IAC3B,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC;IAC1B,MAAM,EAAE,qBAAqB,GAAG,gBAAgB,GAAG,sBAAsB,CAAC;CAC3E;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,EAAE,CAAC,cAAc,EACvB,IAAI,EAAE,kBAAkB,GACvB,mBAAmB,GAAG,IAAI,CAkB5B;AAoJD,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,EAAE,CAAC,cAAc,EACvB,QAAQ,EAAE,mBAAmB,EAC7B,IAAI,EAAE,kBAAkB,GACvB,qBAAqB,CAiBvB"}

package/dist/src/rules/observable-reads/non-tracking-snapshots.js

@@ -0,0 +1,141 @@
+import { findAncestor, isRuntimeFunctionLike } from "../../core/ast.js";
+import { callbackIsEventRooted } from "../state-proofs/event-roots.js";
+import { isImportedHookCall } from "../../core/imports.js";
+import { provenObservablePath } from "./observable-paths.js";
+import ts from "typescript";
+import { unwrapTransparentExpression } from "../../core/analysis-ast.js";
+export function nonTrackingSnapshotObservable(call, scan) {
+    if (call.arguments.length > 0 ||
+        !ts.isPropertyAccessExpression(call.expression) ||
+        call.expression.name.text !== "get") {
+        return null;
+    }
+    const observable = provenObservablePath(call.expression.expression, scan.observableBindings);
+    if (!observable) {
+        return null;
+    }
+    const callback = findAncestor(call, isRuntimeFunctionLike);
+    if (!callback) {
+        return null;
+    }
+    const source = provenNonTrackingCallbackSource(callback, scan);
+    return source ? { observable, source } : null;
+}
+function isReactSnapshotCallback(callback, imports) {
+    return (isDirectHookCallback(callback, imports, "useEffect") ||
+        isDirectHookCallback(callback, imports, "useInsertionEffect") ||
+        isDirectHookCallback(callback, imports, "useLayoutEffect") ||
+        isDirectHookCallback(callback, imports, "useState") ||
+        isDirectHookCallback(callback, imports, "useMount") ||
+        isDirectHookCallback(callback, imports, "useUnmount"));
+}
+function eventRootedSnapshotSource(callback, owner, scan) {
+    if (isDirectJsxEventCallback(callback)) {
+        return "react-or-event";
+    }
+    if (sourceProvenEffectJsxCallback(callback, scan.childContracts)) {
+        return "source-proven-effect";
+    }
+    return callbackIsEventRooted({ callback, owner, dependencyName: "", seen: new Set() })
+        ? "react-or-event"
+        : null;
+}
+function provenNonTrackingCallbackSource(callback, scan) {
+    if (!ts.isArrowFunction(callback) &&
+        !ts.isFunctionDeclaration(callback) &&
+        !ts.isFunctionExpression(callback)) {
+        return null;
+    }
+    if (isReactSnapshotCallback(callback, scan.imports)) {
+        return "react-or-event";
+    }
+    if (isDirectObservableOnChangeCallback(callback, scan.observableBindings)) {
+        return "observable-listener";
+    }
+    const owner = findAncestor(callback, isRuntimeFunctionLike);
+    if (!owner) {
+        return null;
+    }
+    return eventRootedSnapshotSource(callback, owner, scan);
+}
+function isDirectObservableOnChangeCallback(callback, observableBindings) {
+    const { parent } = callback;
+    if (!ts.isCallExpression(parent) ||
+        parent.arguments.length !== 1 ||
+        parent.arguments[0] !== callback ||
+        parent.questionDotToken) {
+        return false;
+    }
+    const method = unwrapTransparentExpression(parent.expression);
+    return (ts.isPropertyAccessExpression(method) &&
+        !method.questionDotToken &&
+        method.name.text === "onChange" &&
+        provenObservablePath(method.expression, observableBindings) !== null);
+}
+function sourceProvenEffectJsxCallback(callback, childContracts) {
+    if (!childContracts || ts.isFunctionDeclaration(callback)) {
+        return false;
+    }
+    const expression = callback.parent;
+    if (!ts.isJsxExpression(expression) ||
+        !expression.expression ||
+        unwrapTransparentExpression(expression.expression) !== callback ||
+        !ts.isJsxAttribute(expression.parent)) {
+        return false;
+    }
+    const attribute = expression.parent;
+    const element = attribute.parent.parent;
+    if (!ts.isJsxOpeningElement(element) && !ts.isJsxSelfClosingElement(element)) {
+        return false;
+    }
+    return childContracts.componentCallbackPropRunsOnlyInReactEffect(element.tagName.getText(), attribute.name.getText());
+}
+function isDirectHookCallback(callback, imports, hook) {
+    const { parent } = callback;
+    if (!ts.isCallExpression(parent) || parent.arguments[0] !== callback) {
+        return false;
+    }
+    const namespaces = hook === "useMount" || hook === "useUnmount"
+        ? imports.legendReactNamespaces
+        : imports.reactNamespaces;
+    return isImportedHookCall({
+        call: parent,
+        localNames: imports[hook],
+        namespaceNames: namespaces,
+        canonicalName: hook,
+    });
+}
+function isDirectJsxEventCallback(callback) {
+    const expression = callback.parent;
+    if (!ts.isJsxExpression(expression) || expression.expression !== callback) {
+        return false;
+    }
+    const attribute = expression.parent;
+    return ts.isJsxAttribute(attribute) && /^on[A-Z]/u.test(attribute.name.getText());
+}
+function snapshotSourceEvidence(source) {
+    if (source === "source-proven-effect") {
+        return "the source-proven React effect callback runs outside a Legend tracking context";
+    }
+    if (source === "observable-listener") {
+        return "the direct Legend observable onChange listener runs outside an observing context";
+    }
+    return "the read is owned by a React snapshot or a uniquely event-rooted command, not a Legend tracking context";
+}
+export function nonTrackingSnapshotFinding(call, snapshot, scan) {
+    const { line, character } = scan.sourceFile.getLineAndCharacterOfPosition(call.getStart(scan.sourceFile));
+    const path = snapshot.observable.getText(scan.sourceFile);
+    return {
+        action: "use-peek-for-snapshot",
+        confidence: "probable",
+        disposition: "change",
+        evidence: [
+            `${path}.get() reads a proven Legend observable path`,
+            snapshotSourceEvidence(snapshot.source),
+        ],
+        location: { column: character + 1, file: scan.fileName, line: line + 1 },
+        message: `Replace \`${path}.get()\` with \`${path}.peek()\`; this code path needs a snapshot, not a reactive dependency.`,
+        practice: "reactivity",
+    };
+}
+//# sourceMappingURL=non-tracking-snapshots.js.map

package/dist/src/rules/observable-reads/non-tracking-snapshots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"non-tracking-snapshots.js","sourceRoot":"","sources":["../../../../src/rules/observable-reads/non-tracking-snapshots.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAKxE,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AAOzE,MAAM,UAAU,6BAA6B,CAC3C,IAAuB,EACvB,IAAwB;IAExB,IACE,IAAI,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC;QACzB,CAAC,EAAE,CAAC,0BAA0B,CAAC,IAAI,CAAC,UAAU,CAAC;QAC/C,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK,EACnC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,UAAU,GAAG,oBAAoB,CAAC,IAAI,CAAC,UAAU,CAAC,UAAU,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;IAC7F,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;IAC3D,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,+BAA+B,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC/D,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED,SAAS,uBAAuB,CAAC,QAAsB,EAAE,OAAoB;IAC3E,OAAO,CACL,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,WAAW,CAAC;QACpD,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,oBAAoB,CAAC;QAC7D,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,iBAAiB,CAAC;QAC1D,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC;QACnD,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,UAAU,CAAC;QACnD,oBAAoB,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,CACtD,CAAC;AACJ,CAAC;AAED,SAAS,yBAAyB,CAChC,QAAsB,EACtB,KAA0B,EAC1B,IAAwB;IAExB,IAAI,wBAAwB,CAAC,QAAQ,CAAC,EAAE,CAAC;QACvC,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,IAAI,6BAA6B,CAAC,QAAQ,EAAE,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;QACjE,OAAO,sBAAsB,CAAC;IAChC,CAAC;IACD,OAAO,qBAAqB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;QACpF,CAAC,CAAC,gBAAgB;QAClB,CAAC,CAAC,IAAI,CAAC;AACX,CAAC;AAED,SAAS,+BAA+B,CACtC,QAA6B,EAC7B,IAAwB;IAExB,IACE,CAAC,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC;QAC7B,CAAC,EAAE,CAAC,qBAAqB,CAAC,QAAQ,CAAC;QACnC,CAAC,EAAE,CAAC,oBAAoB,CAAC,QAAQ,CAAC,EAClC,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,uBAAuB,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACpD,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IACD,IAAI,kCAAkC,CAAC,QAAQ,EAAE,IAAI,CAAC,kBAAkB,CAAC,EAAE,CAAC;QAC1E,OAAO,qBAAqB,CAAC;IAC/B,CAAC;IACD,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC;IAC5D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,yBAAyB,CAAC,QAAQ,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,kCAAkC,CACzC,QAAsB,EACtB,kBAAuC;IAEvC,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;IAC5B,IACE,CAAC,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC;QAC5B,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;QAC7B,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,QAAQ;QAChC,MAAM,CAAC,gBAAgB,EACvB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAG,2BAA2B,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC9D,OAAO,CACL,EAAE,CAAC,0BAA0B,CAAC,MAAM,CAAC;QACrC,CAAC,MAAM,CAAC,gBAAgB;QACxB,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU;QAC/B,oBAAoB,CAAC,MAAM,CAAC,UAAU,EAAE,kBAAkB,CAAC,KAAK,IAAI,CACrE,CAAC;AACJ,CAAC;AAED,SAAS,6BAA6B,CACpC,QAAsB,EACtB,cAA4C;IAE5C,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;IACnC,IACE,CAAC,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC;QAC/B,CAAC,UAAU,CAAC,UAAU;QACtB,2BAA2B,CAAC,UAAU,CAAC,UAAU,CAAC,KAAK,QAAQ;QAC/D,CAAC,EAAE,CAAC,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,EACrC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC;IACpC,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,uBAAuB,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,cAAc,CAAC,0CAA0C,CAC9D,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,EACzB,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,CACzB,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,QAAsB,EACtB,OAAoB,EACpB,IAMgB;IAEhB,MAAM,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC;IAC5B,IAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,UAAU,GACd,IAAI,KAAK,UAAU,IAAI,IAAI,KAAK,YAAY;QAC1C,CAAC,CAAC,OAAO,CAAC,qBAAqB;QAC/B,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC;IAC9B,OAAO,kBAAkB,CAAC;QACxB,IAAI,EAAE,MAAM;QACZ,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC;QACzB,cAAc,EAAE,UAAU;QAC1B,aAAa,EAAE,IAAI;KACpB,CAAC,CAAC;AACL,CAAC;AAED,SAAS,wBAAwB,CAAC,QAAsB;IACtD,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;IACnC,IAAI,CAAC,EAAE,CAAC,eAAe,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;QAC1E,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,SAAS,GAAG,UAAU,CAAC,MAAM,CAAC;IACpC,OAAO,EAAE,CAAC,cAAc,CAAC,SAAS,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;AACpF,CAAC;AAED,SAAS,sBAAsB,CAAC,MAAqC;IACnE,IAAI,MAAM,KAAK,sBAAsB,EAAE,CAAC;QACtC,OAAO,gFAAgF,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,KAAK,qBAAqB,EAAE,CAAC;QACrC,OAAO,kFAAkF,CAAC;IAC5F,CAAC;IACD,OAAO,yGAAyG,CAAC;AACnH,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,IAAuB,EACvB,QAA6B,EAC7B,IAAwB;IAExB,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,6BAA6B,CACvE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,CAC/B,CAAC;IACF,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC1D,OAAO;QACL,MAAM,EAAE,uBAAuB;QAC/B,UAAU,EAAE,UAAU;QACtB,WAAW,EAAE,QAAQ;QACrB,QAAQ,EAAE;YACR,GAAG,IAAI,8CAA8C;YACrD,sBAAsB,CAAC,QAAQ,CAAC,MAAM,CAAC;SACxC;QACD,QAAQ,EAAE,EAAE,MAAM,EAAE,SAAS,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,CAAC,EAAE;QACxE,OAAO,EAAE,aAAa,IAAI,mBAAmB,IAAI,wEAAwE;QACzH,QAAQ,EAAE,YAAY;KACvB,CAAC;AACJ,CAAC"}

package/dist/src/rules/observable-reads/observable-paths.d.ts

@@ -0,0 +1,14 @@
+import type { ObservableReadScan, UseValueDeclaration } from "./model.js";
+import type { HookImports } from "../../core/imports.js";
+import ts from "typescript";
+export declare const RESERVED_OBSERVABLE_MEMBERS: Set<string>;
+export declare function identifiedUseValueDeclaration(declaration: ts.VariableDeclaration, scan: ObservableReadScan): UseValueDeclaration | null;
+export declare function isValueReferenceTo(node: ts.Node, localName: string, declarationName: ts.BindingName): node is ts.Identifier;
+export declare function outermostTransparentParent(expression: ts.Expression): ts.Expression;
+export declare function directObservableReadPath(expression: ts.Expression, observableBindings: ReadonlySet<string>): ts.Expression | null;
+export declare function directGetReceiver(expression: ts.Expression): ts.Expression | null;
+/** `useValue` or one of its deprecated aliases, each of which tracks the observables its selector reads. */
+export declare function isTrackingHookCall(call: ts.CallExpression, imports: HookImports): boolean;
+export declare function isUseValueCall(call: ts.CallExpression, imports: HookImports): boolean;
+export declare function provenObservablePath(expression: ts.Expression, observableBindings: ReadonlySet<string>): ts.Expression | null;
+//# sourceMappingURL=observable-paths.d.ts.map

package/dist/src/rules/observable-reads/observable-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable-paths.d.ts","sourceRoot":"","sources":["../../../../src/rules/observable-reads/observable-paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAU1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,eAAO,MAAM,2BAA2B,aAatC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,EAAE,CAAC,mBAAmB,EACnC,IAAI,EAAE,kBAAkB,GACvB,mBAAmB,GAAG,IAAI,CAiB5B;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,EAAE,CAAC,IAAI,EACb,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,EAAE,CAAC,WAAW,GAC9B,IAAI,IAAI,EAAE,CAAC,UAAU,CAOvB;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,CAanF;AAED,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,GACtC,EAAE,CAAC,UAAU,GAAG,IAAI,CAGtB;AAED,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,EAAE,CAAC,UAAU,GAAG,IAAI,CAcjF;AAID,4GAA4G;AAC5G,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAczF;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAcrF;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,EAAE,CAAC,UAAU,EACzB,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,GACtC,EAAE,CAAC,UAAU,GAAG,IAAI,CAgBtB"}

package/dist/src/rules/observable-reads/observable-paths.js

@@ -0,0 +1,113 @@
+import { bindingDeclarationCount, containsElementAccess, isNonValueIdentifier, rootIdentifier, staticPathHasBinding, unwrapTransparentExpression, } from "../../core/analysis-ast.js";
+import { findAncestor, isRuntimeFunctionLike } from "../../core/ast.js";
+import { isImportedHookCall } from "../../core/imports.js";
+import ts from "typescript";
+export const RESERVED_OBSERVABLE_MEMBERS = new Set([
+    "assign",
+    "delete",
+    "fire",
+    "get",
+    "getPrevious",
+    "length",
+    "onChange",
+    "peek",
+    "set",
+    "size",
+    "subscribe",
+    "toggle",
+]);
+export function identifiedUseValueDeclaration(declaration, scan) {
+    const call = declaration.initializer;
+    if (!call ||
+        !ts.isCallExpression(call) ||
+        call.arguments.length !== 1 ||
+        !isUseValueCall(call, scan.imports) ||
+        !ts.isIdentifier(declaration.name)) {
+        return null;
+    }
+    const observable = provenObservablePath(call.arguments[0], scan.observableBindings);
+    const owner = findAncestor(declaration, isRuntimeFunctionLike);
+    if (!observable || !owner?.body) {
+        return null;
+    }
+    return { call, declaration, localName: declaration.name.text, observable, owner };
+}
+export function isValueReferenceTo(node, localName, declarationName) {
+    return (ts.isIdentifier(node) &&
+        node.text === localName &&
+        node !== declarationName &&
+        !isNonValueIdentifier(node));
+}
+export function outermostTransparentParent(expression) {
+    let current = expression;
+    while ((ts.isParenthesizedExpression(current.parent) ||
+        ts.isAsExpression(current.parent) ||
+        ts.isTypeAssertionExpression(current.parent) ||
+        ts.isSatisfiesExpression(current.parent) ||
+        ts.isNonNullExpression(current.parent)) &&
+        current.parent.expression === current) {
+        current = current.parent;
+    }
+    return current;
+}
+export function directObservableReadPath(expression, observableBindings) {
+    const path = directGetReceiver(expression);
+    return path ? provenObservablePath(path, observableBindings) : null;
+}
+export function directGetReceiver(expression) {
+    const read = unwrapTransparentExpression(expression);
+    if (!ts.isCallExpression(read) ||
+        read.arguments.length > 0 ||
+        (read.typeArguments?.length ?? 0) > 0 ||
+        read.questionDotToken ||
+        !ts.isPropertyAccessExpression(read.expression) ||
+        read.expression.questionDotToken ||
+        read.expression.name.text !== "get") {
+        return null;
+    }
+    return unwrapTransparentExpression(read.expression.expression);
+}
+const LEGACY_TRACKING_HOOKS = new Set(["use$", "useSelector"]);
+/** `useValue` or one of its deprecated aliases, each of which tracks the observables its selector reads. */
+export function isTrackingHookCall(call, imports) {
+    if (isUseValueCall(call, imports)) {
+        return true;
+    }
+    const callee = unwrapTransparentExpression(call.expression);
+    if (ts.isIdentifier(callee)) {
+        return imports.legacyUseValue.has(callee.text);
+    }
+    return (ts.isPropertyAccessExpression(callee) &&
+        ts.isIdentifier(callee.expression) &&
+        imports.legendReactNamespaces.has(callee.expression.text) &&
+        LEGACY_TRACKING_HOOKS.has(callee.name.text));
+}
+export function isUseValueCall(call, imports) {
+    if (!isImportedHookCall({
+        call,
+        localNames: imports.useValue,
+        namespaceNames: imports.legendReactNamespaces,
+        canonicalName: "useValue",
+    })) {
+        return false;
+    }
+    const binding = rootIdentifier(call.expression);
+    const owner = findAncestor(call, isRuntimeFunctionLike);
+    return !binding || !owner || bindingDeclarationCount(owner, binding.text) === 0;
+}
+export function provenObservablePath(expression, observableBindings) {
+    const path = unwrapTransparentExpression(expression);
+    if ((!ts.isIdentifier(path) && !ts.isPropertyAccessExpression(path)) ||
+        containsElementAccess(path)) {
+        return null;
+    }
+    let current = path;
+    while (ts.isPropertyAccessExpression(current)) {
+        if (current.questionDotToken || RESERVED_OBSERVABLE_MEMBERS.has(current.name.text)) {
+            return null;
+        }
+        current = current.expression;
+    }
+    return staticPathHasBinding(path, observableBindings) ? path : null;
+}
+//# sourceMappingURL=observable-paths.js.map

package/dist/src/rules/observable-reads/observable-paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable-paths.js","sourceRoot":"","sources":["../../../../src/rules/observable-reads/observable-paths.ts"],"names":[],"mappings":"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"}

package/dist/src/rules/observable-reads/observable-reads.d.ts

@@ -0,0 +1,14 @@
+import type { ChildContractResolver } from "../child-contract/model.js";
+import type { HookImports } from "../../core/imports.js";
+import type { LegendPracticeFinding } from "../../core/types.js";
+import ts from "typescript";
+export interface ObservableReadRequest {
+    readonly childContracts?: ChildContractResolver | null;
+    readonly fileName: string;
+    readonly imports: HookImports;
+    readonly observableBindings: ReadonlySet<string>;
+    readonly observableKeys?: ReadonlyMap<string, ReadonlySet<string>>;
+    readonly sourceFile: ts.SourceFile;
+}
+export declare function findObservableReadPractices(request: ObservableReadRequest): LegendPracticeFinding[];
+//# sourceMappingURL=observable-reads.d.ts.map

package/dist/src/rules/observable-reads/observable-reads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable-reads.d.ts","sourceRoot":"","sources":["../../../../src/rules/observable-reads/observable-reads.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMjE,OAAO,EAAE,MAAM,YAAY,CAAC;AAG5B,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACvD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,cAAc,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;IACnE,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC;CACpC;AAED,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,qBAAqB,GAC7B,qBAAqB,EAAE,CAYzB"}

package/dist/src/rules/observable-reads/observable-reads.js

@@ -0,0 +1,49 @@
+import { directUseValueFinding, directUseValueInput } from "./use-value-inputs.js";
+import { nonTrackingSnapshotFinding, nonTrackingSnapshotObservable, } from "./non-tracking-snapshots.js";
+import { moveUseValueDownFinding } from "./move-down.js";
+import { moveUseValueIntoChildFinding } from "./move-into-child.js";
+import { narrowUseValueFinding } from "./narrow-use-value.js";
+import { splitUseValueResultFinding } from "./fresh-selector-results.js";
+import ts from "typescript";
+import { visit } from "../../core/ast.js";
+export function findObservableReadPractices(request) {
+    const { sourceFile } = request;
+    const scan = {
+        ...request,
+        childContracts: request.childContracts ?? null,
+        observableKeys: request.observableKeys ?? new Map(),
+    };
+    const findings = [];
+    visit(sourceFile, (node) => {
+        collectReadFindings(node, scan, findings);
+    });
+    return findings;
+}
+function collectReadFindings(node, scan, findings) {
+    if (ts.isCallExpression(node)) {
+        collectCallFindings(node, scan, findings);
+    }
+    if (ts.isVariableDeclaration(node)) {
+        const finding = moveUseValueIntoChildFinding(node, scan) ??
+            moveUseValueDownFinding(node, scan) ??
+            narrowUseValueFinding(node, scan);
+        if (finding) {
+            findings.push(finding);
+        }
+    }
+}
+function collectCallFindings(call, scan, findings) {
+    const directInput = directUseValueInput(call, scan.imports, scan.observableBindings);
+    if (directInput) {
+        findings.push(directUseValueFinding(call, directInput, scan));
+    }
+    const split = splitUseValueResultFinding(call, scan);
+    if (split) {
+        findings.push(split);
+    }
+    const snapshot = nonTrackingSnapshotObservable(call, scan);
+    if (snapshot) {
+        findings.push(nonTrackingSnapshotFinding(call, snapshot, scan));
+    }
+}
+//# sourceMappingURL=observable-reads.js.map

package/dist/src/rules/observable-reads/observable-reads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observable-reads.js","sourceRoot":"","sources":["../../../../src/rules/observable-reads/observable-reads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,6BAA6B,CAAC;AAKrC,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AACzE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAW1C,MAAM,UAAU,2BAA2B,CACzC,OAA8B;IAE9B,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAC/B,MAAM,IAAI,GAAuB;QAC/B,GAAG,OAAO;QACV,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI;QAC9C,cAAc,EAAE,OAAO,CAAC,cAAc,IAAI,IAAI,GAAG,EAAE;KACpD,CAAC;IACF,MAAM,QAAQ,GAA4B,EAAE,CAAC;IAC7C,KAAK,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;QACzB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IACH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,mBAAmB,CAC1B,IAAa,EACb,IAAwB,EACxB,QAAiC;IAEjC,IAAI,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC9B,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,EAAE,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,MAAM,OAAO,GACX,4BAA4B,CAAC,IAAI,EAAE,IAAI,CAAC;YACxC,uBAAuB,CAAC,IAAI,EAAE,IAAI,CAAC;YACnC,qBAAqB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACpC,IAAI,OAAO,EAAE,CAAC;YACZ,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,mBAAmB,CAC1B,IAAuB,EACvB,IAAwB,EACxB,QAAiC;IAEjC,MAAM,WAAW,GAAG,mBAAmB,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;IACrF,IAAI,WAAW,EAAE,CAAC;QAChB,QAAQ,CAAC,IAAI,CAAC,qBAAqB,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrD,IAAI,KAAK,EAAE,CAAC;QACV,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IACD,MAAM,QAAQ,GAAG,6BAA6B,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC3D,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,IAAI,CAAC,0BAA0B,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}

package/dist/src/rules/observable-reads/raw-value-paths.d.ts

@@ -0,0 +1,6 @@
+import ts from "typescript";
+export declare function staticRawValuePath(reference: ts.Identifier): readonly string[] | null;
+export declare function rawValuePathHasOptionalAccess(reference: ts.Identifier): boolean;
+export declare function optionalAccessPreservesSuffix(reference: ts.Identifier, commonLength: number): boolean;
+export declare function commonPathPrefix(left: readonly string[], right: readonly string[]): readonly string[];
+//# sourceMappingURL=raw-value-paths.d.ts.map

package/dist/src/rules/observable-reads/raw-value-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"raw-value-paths.d.ts","sourceRoot":"","sources":["../../../../src/rules/observable-reads/raw-value-paths.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,YAAY,CAAC;AA+B5B,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,GAAG,SAAS,MAAM,EAAE,GAAG,IAAI,CAGrF;AAED,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,GAAG,OAAO,CAc/E;AAsCD,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,EAAE,CAAC,UAAU,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAET;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,SAAS,MAAM,EAAE,CAMnB"}