@lzehrung/codegraph 3.0.1 → 3.1.0

package/dist/scss/resolution.d.ts

@@ -0,0 +1,190 @@
+import { type ProjectIndex, type Reference, type SymbolDef } from "../indexer/types.js";
+import type { FileId, Range } from "../types.js";
+import { type ScssFileFacts, type ScssMemberKind, type ScssModuleLoad, type ScssUse } from "./syntax.js";
+/**
+ * The one place that decides what an SCSS module member names. `goToDefinition`,
+ * `findReferences`, and rename preview all resolve sites here.
+ *
+ * URLs use the indexed stylesheet edges (and the import bindings those edges share).
+ * `sass:` modules stay external. A name declared more than once in the visible set
+ * resolves to nothing, except a variable that one file assigns again: that is one variable.
+ */
+export type ScssNotFound = {
+    status: "not_found";
+    reason: string;
+    unproven?: true;
+};
+/**
+ * How a use reaches its member: in the file that declares it, through `@import` (which has no
+ * privacy), or through `@use` or `@forward` (which hide names that start with `-` or `_`).
+ */
+export type ScssAccess = "own" | "import" | "module";
+/**
+ * A `@forward` that has a `show` or `hide` list and that a member passed through. `exposed` is the
+ * canonical name the list sees: the prefix of this forward and of the forwards inside it, plus the
+ * declared name.
+ */
+export type ScssForwardFilter = {
+    load: ScssModuleLoad;
+    exposed: string;
+};
+export type ScssResolved = {
+    status: "ok";
+    def: SymbolDef;
+    prefix: string;
+    access: ScssAccess;
+    /** The forward lists on the path from the declaring file to the use, innermost first. */
+    filters: readonly ScssForwardFilter[];
+};
+/**
+ * `shadow`: a local owns the name, so module lookup must not claim it. `indexed` is true when the
+ * index holds a definition the exact-name walker can prove (a block variable whose spelling
+ * matches). A parameter, a loop variable, or an unindexed scoped mixin or function has none.
+ * An indexed scoped mixin or function resolves directly instead of using this miss.
+ */
+export type ScssResolution = ScssResolved | {
+    status: "shadow";
+    indexed: boolean;
+} | ScssNotFound;
+/** A place where a member is declared. */
+export type ScssSite = {
+    file: FileId;
+    range: Range;
+};
+/** A top-level declaration, as the index and the navigation consumers see it. */
+export type ScssDeclaredMember = {
+    kind: ScssMemberKind;
+    /** Canonical declared name. */
+    declared: string;
+    /** First declaration of the member. A variable assigned again in the file keeps the first one. */
+    def: SymbolDef;
+    /** Every declaration site of the member, `def` first. */
+    sites: readonly ScssSite[];
+};
+export declare function isScssFile(index: ProjectIndex, file: FileId): boolean;
+/** Declarations, loads, and uses of one indexed SCSS file, or null when it cannot be read. */
+export declare function scssFactsForFile(index: ProjectIndex, file: FileId): Promise<ScssFileFacts | null>;
+/**
+ * Resolves one scanned use. `shadow` means an enclosing local owns the name, so module
+ * lookup must not claim it. `unproven` means more than one member matches, or a load that
+ * could contribute members did not resolve.
+ */
+export declare function resolveScssUse(index: ProjectIndex, file: FileId, use: ScssUse): Promise<ScssResolution>;
+/**
+ * The member a definition declares: a top-level member, or a placeholder at any depth. Null for
+ * locals, parameters, and other selectors.
+ */
+export declare function scssMemberForDefinition(index: ProjectIndex, def: SymbolDef): Promise<ScssDeclaredMember | null>;
+/**
+ * True when an indexed block variable is spelled with a different mix of `-` and `_` than a use it covers.
+ * The exact-name reference walk omits that use, so coverage must not claim to be complete.
+ */
+export declare function scssLocalSpellingGap(facts: ScssFileFacts, def: SymbolDef): boolean;
+/**
+ * True when a scanned local nearer than `def` covers `at` and spells the same Sass variable with a
+ * different mix of `-` and `_`. The exact-name walk would keep that read on `def`.
+ */
+export declare function scssNearerEquivalentLocal(facts: ScssFileFacts, def: SymbolDef, at: Range["start"]): boolean;
+/** The imported variable a joined flow-control assignment names, when the click is on that assignment. */
+export declare function scssAssignmentDefinition(index: ProjectIndex, file: FileId, line: number, column: number): Promise<SymbolDef | null>;
+/** True when this indexed variable is a file-scope flow assignment that could not be joined. */
+export declare function scssFlowLocalUnproven(index: ProjectIndex, def: SymbolDef): Promise<boolean>;
+/**
+ * True when a block local, parameter, or loop variable may be the variable `variable-exists`
+ * names. `global-variable-exists` does not see a block local. A proved user function is not the
+ * built-in. Module members are left to {@link hasUnprovenDynamic}.
+ */
+export declare function scssBlockLocalExistenceUnproven(index: ProjectIndex, def: SymbolDef): Promise<boolean>;
+/** Reference span for a use. Null when a forward prefix cannot be split from the member. */
+export declare function scssUseEditRange(facts: ScssFileFacts, use: ScssUse, prefix: string): Range | null;
+/**
+ * Files that can see `member`, plus files whose unresolved URL or `meta.load-css` may load the
+ * declaring file. `unavailable` files were not fully proved. A directory index (`_index.scss`)
+ * is also reached through the name of its directory.
+ */
+export declare function scssReferenceCandidates(index: ProjectIndex, member: ScssDeclaredMember): Promise<{
+    files: FileId[];
+    unavailable: FileId[];
+}>;
+export declare function scssUseAt(facts: ScssFileFacts, line: number, column: number): ScssUse | undefined;
+/**
+ * Same-kind members that would share the new name with `def` in a scope that sees `def`: the
+ * module that declares it, every module that exposes it, and every file that sees it without a
+ * namespace (`@use ... as *`, `@import`). A forward prefix stays in front of the new name. A
+ * placeholder has no namespace, so no file that sees it may also see another placeholder that has
+ * the new name.
+ */
+export declare function scssRenameCollisions(index: ProjectIndex, def: SymbolDef, newName: string): Promise<SymbolDef[]>;
+export type ScssMemberUse = {
+    use: ScssUse;
+    resolved: ScssResolved;
+};
+/**
+ * The uses in `facts` that resolve to `member`, in source order. `unproven` is true when a use that
+ * may name the member could not be resolved, so the file is not fully proved.
+ */
+export declare function scssMemberUses(index: ProjectIndex, file: FileId, facts: ScssFileFacts, member: ScssDeclaredMember): Promise<{
+    matches: ScssMemberUse[];
+    unproven: boolean;
+}>;
+export type ScssRenameSite = {
+    file: FileId;
+    range: Range;
+};
+/**
+ * True when a dynamic lookup in the span where `def` is visible may name that scoped mixin or
+ * function. Existence predicates, `call`, and `get-function` name a function; `mixin-exists` and
+ * `get-mixin` name a mixin. The call is a proved `sass:meta` binding or a legacy bare built-in.
+ * A lookup outside the block, or one a user function owns, does not. Static uses stay references.
+ */
+export declare function scssScopedCallableDynamicUnproven(index: ProjectIndex, def: SymbolDef): Promise<boolean>;
+/**
+ * Bare same-kind calls and includes a scoped mixin or function owns.
+ * Null when `def` is not a scoped callable. `unproven` when the file cannot be scanned, so
+ * coverage must not claim to be complete. A dynamic lookup that may name the callable is reported
+ * separately by {@link scssScopedCallableDynamicUnproven}; these ranges stay the proved uses.
+ */
+export declare function scssScopedCallableReferences(index: ProjectIndex, def: SymbolDef): Promise<{
+    ranges: Range[];
+    unproven: boolean;
+} | null>;
+/**
+ * A scoped callable is not a module member. `captured` lists bare calls already spelled with
+ * the proposed name that this local would own, and `shadowed` lists calls this local owns when
+ * a different same-kind scoped callable would own the edited name (`-` and `_` equivalent).
+ * `unaccounted` lists calls of the original name that this local owns and the reference walk
+ * omitted; a nearer scoped callable keeps its own calls. A bare dynamic callee (`get-function`,
+ * `call`, `get-mixin`, `load-css`, the other meta lookups, or a `_` spelling) whose name is the
+ * proposed name is captured too: the rename would make that call invoke this callable. A namespaced
+ * dynamic call is not. Null means `def` is not a scoped callable.
+ */
+export declare function scssScopedCallableRenameSites(index: ProjectIndex, def: SymbolDef, newName: string, references: readonly Reference[]): Promise<{
+    captured: ScssRenameSite[];
+    shadowed: ScssRenameSite[];
+    unaccounted: Array<ScssRenameSite & {
+        text: string;
+    }>;
+} | null>;
+/**
+ * The uses that the new name would break.
+ * - A block variable captures a bare variable use, or a scoped mixin/function captures a bare
+ *   include/call, when its same-kind name matches the forward prefix plus the proposed name.
+ *   A namespaced use cannot be captured.
+ * - A name that starts with `-` or `_` is private to its module, so a use through `@use` or
+ *   `@forward` could no longer reach it. `@import` and the declaring file keep access.
+ * - A `@forward` with a `hide` list that names the new name (with the forward prefix) hides the
+ *   member from the use that reads it through that forward.
+ */
+export declare function scssRenameUseConflicts(index: ProjectIndex, def: SymbolDef, newName: string): Promise<{
+    captured: ScssRenameSite[];
+    inaccessible: ScssRenameSite[];
+    hidden: ScssRenameSite[];
+}>;
+/** Replacement text for one SCSS member edit, or null when the site is not that member. */
+export declare function scssReplacementText(localName: string, oldText: string, newName: string): string | null;
+/**
+ * The name an SCSS edit writes for a rename request. The symbol keeps its sigil, so a request of
+ * `y` for `$x` writes `$y`, and the conflict checks must look for that spelling.
+ */
+export declare function scssRenamedName(localName: string, newName: string): string;
+//# sourceMappingURL=resolution.d.ts.map

package/dist/scss/resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolution.d.ts","sourceRoot":"","sources":["../../src/scss/resolution.ts"],"names":[],"mappings":"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"}