aws-iam-language-server 0.0.13 → 0.0.14

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aws-iam-language-server",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "type": "module",
   "bin": "./src/server.js",
   "publisher": "MichaelBarney",

package/readme.md

@@ -59,6 +59,17 @@ This language server provides completion on:
 - condition operators (`StringLike`, `ForAnyValue:*`, etc)
 - condition keys (global keys like `aws:RequestTag/${TagKey}`, action-specific keys like `s3:TlsVersion`)
 
+### Hover
+
+Hovering over elements within a policy document will show contextual documentation:
+
+- actions (access level, resource types, condition keys, and dependent actions)
+- resources (matched resource type from the service reference with ARN format and condition keys)
+- principal types (description of `AWS`, `Service`, `Federated`, `CanonicalUser`)
+- principal values (identifies account IDs, role/user ARNs, service principals, federated providers)
+- condition operators (description of what each operator does, like `StringEquals`, `ArnLike`, `IpAddress`, etc.)
+- condition keys (documentation for global keys like `aws:SourceIp` and service-specific keys like `s3:prefix`)
+
 ### Diagnostics
 
 This language server will provide diagnostics for some IAM policy issues, including:

package/src/handlers/completion/action-value.d.ts

@@ -1,4 +1,6 @@
 import type { CompletionList } from 'vscode-languageserver';
 import type { ActionValueLocation } from '../../lib/iam-policy/location.ts';
+import type { Action } from '../../lib/iam-policy/reference/types.ts';
 import { type CompletionContext } from './index.ts';
 export declare function completeActionValue(location: ActionValueLocation, context: CompletionContext): CompletionList;
+export declare function formatActionDocumentation(action: Action): string;

package/src/handlers/completion/action-value.js

@@ -44,7 +44,7 @@ export function completeActionValue(location, context) {
     }
     return { items, isIncomplete: false };
 }
-function formatActionDocumentation(action) {
+export function formatActionDocumentation(action) {
     const parts = [];
     if (action.accessLevel)
         parts.push(`**Access Level**: ${action.accessLevel}`);

package/src/handlers/completion/condition-key.d.ts

@@ -1,4 +1,6 @@
 import type { CompletionList } from 'vscode-languageserver';
 import type { ConditionKeyLocation } from '../../lib/iam-policy/location.ts';
+import type { ConditionKey, GlobalConditionKey } from '../../lib/iam-policy/reference/types.ts';
 import { type CompletionContext } from './index.ts';
 export declare function completeConditionKey(location: ConditionKeyLocation, context: CompletionContext): CompletionList;
+export declare function formatConditionKeyDocumentation(types: string[], global: GlobalConditionKey | undefined, conditionKey?: ConditionKey): string;

package/src/handlers/completion/condition-key.js

@@ -39,7 +39,7 @@ export function completeConditionKey(location, context) {
                 textEdit: { range, newText: key.name },
                 documentation: {
                     kind: MarkupKind.Markdown,
-                    value: formatDocumentation(key.types, global, conditionKeyData),
+                    value: formatConditionKeyDocumentation(key.types, global, conditionKeyData),
                 },
             });
         }
@@ -59,13 +59,13 @@ export function completeConditionKey(location, context) {
             textEdit: { range, newText: global.name },
             documentation: {
                 kind: MarkupKind.Markdown,
-                value: formatDocumentation([], global),
+                value: formatConditionKeyDocumentation([], global),
             },
         });
     }
     return { items, isIncomplete: false };
 }
-function formatDocumentation(types, global, conditionKey) {
+export function formatConditionKeyDocumentation(types, global, conditionKey) {
     const parts = [];
     const description = global?.description ?? conditionKey?.description;
     if (description)

package/src/handlers/completion/index.d.ts

@@ -8,12 +8,12 @@ export type CompletionContext = {
     uri: string;
     position: {
         line: number;
-        column: number;
+        character: number;
     };
 };
 export declare function partialRange(position: {
     line: number;
-    column: number;
+    character: number;
 }, partialLength: number): {
     start: {
         line: number;

package/src/handlers/completion/index.js

@@ -17,15 +17,15 @@ import { completeStatementKey } from "./statement-key.js";
 const emptyResult = { items: [], isIncomplete: false };
 export function partialRange(position, partialLength) {
     return {
-        start: { line: position.line, character: position.column - partialLength },
-        end: { line: position.line, character: position.column },
+        start: { line: position.line, character: position.character - partialLength },
+        end: { line: position.line, character: position.character },
     };
 }
 export async function handleCompletionRequest(params, _documents, treeManager, connection) {
     const handler = treeManager.getLanguageHandler(params.textDocument.uri);
     if (!handler)
         return emptyResult;
-    const position = { line: params.position.line, column: params.position.character };
+    const position = params.position;
     const cursorContext = handler.getCursorContext(params.textDocument.uri, position);
     if (!cursorContext)
         return emptyResult;
@@ -42,7 +42,7 @@ export async function handleCompletionRequest(params, _documents, treeManager, c
         position,
     });
     result.items = result.items.map(toSnippet);
-    connection.console.debug(`Found ${result.items.length} completion items for ${params.textDocument.uri} at line ${position.line}, column ${position.column}`);
+    connection.console.debug(`Found ${result.items.length} completion items for ${params.textDocument.uri} at line ${position.line}, character ${position.character}`);
     return result;
 }
 function handleLocationCompletion(location, context) {

package/src/handlers/completion/principal-identifier-completions.d.ts

@@ -1,5 +1,5 @@
 import type { CompletionList } from 'vscode-languageserver';
 export declare function completePrincipalIdentifier(principalType: string | null, partial: string, position: {
     line: number;
-    column: number;
+    character: number;
 }): CompletionList;

package/src/handlers/diagnostics/resource.js

@@ -9,11 +9,11 @@ function segmentRange(value, segmentIndex) {
     for (let i = 0; i < segmentIndex; i++) {
         offset += segments[i].length + 1;
     }
-    const startColumn = value.range.start.column + offset;
-    const endColumn = startColumn + segments[segmentIndex].length;
+    const startCharacter = value.range.start.character + offset;
+    const endCharacter = startCharacter + segments[segmentIndex].length;
     return {
-        start: { line: value.range.start.line, column: startColumn },
-        end: { line: value.range.start.line, column: endColumn },
+        start: { line: value.range.start.line, character: startCharacter },
+        end: { line: value.range.start.line, character: endCharacter },
     };
 }
 function validateArn(value) {

package/src/handlers/diagnostics/utils.js

@@ -2,18 +2,6 @@ export function createDiagnostic(message, range) {
     return {
         source: 'aws-iam-language-server',
         message,
-        range: convertRangeToDiagnosticRange(range),
-    };
-}
-function convertRangeToDiagnosticRange(range) {
-    return {
-        start: {
-            character: range.start.column,
-            line: range.start.line,
-        },
-        end: {
-            character: range.end.column,
-            line: range.end.line,
-        },
+        range,
     };
 }

package/src/handlers/document-link/document-link.js

@@ -21,9 +21,7 @@ export function documentLinkHandler(params, documents, treeManager, connection)
                     const action = ServiceReference.getAction(value.text);
                     if (!action)
                         continue;
-                    const start = { line: value.range.start.line, character: value.range.start.column };
-                    const end = { line: value.range.end.line, character: value.range.end.column };
-                    const range = { start, end };
+                    const range = value.range;
                     if (action.iamUrl) {
                         links.push({
                             range,

package/src/handlers/hover/action-value.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { ActionValueLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleActionValueHover(location: ActionValueLocation): Hover | null;

package/src/handlers/hover/action-value.js

@@ -0,0 +1,21 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { ServiceReference } from "../../lib/iam-policy/reference/services.js";
+import { formatActionDocumentation } from "../completion/action-value.js";
+export function handleActionValueHover(location) {
+    const action = ServiceReference.getAction(location.value);
+    if (!action)
+        return null;
+    const lines = [`**${action.service}:${action.name}**`];
+    if (action.description)
+        lines.push(action.description);
+    const docs = formatActionDocumentation(action);
+    if (docs)
+        lines.push(docs);
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: lines.join('\n\n'),
+        },
+    };
+}

package/src/handlers/hover/condition-block.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { ConditionBlockLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleConditionBlockHover(location: ConditionBlockLocation): Hover | null;

package/src/handlers/hover/condition-block.js

@@ -0,0 +1,18 @@
+import { MarkupKind } from 'vscode-languageserver';
+const conditionBlockAttributes = {
+    test: 'The condition operator to evaluate (e.g., `StringEquals`, `ArnLike`, `IpAddress`).',
+    variable: 'The condition key to evaluate (e.g., `aws:SourceIp`, `s3:prefix`).',
+    values: 'List of values to compare against the condition key.',
+};
+export function handleConditionBlockHover(location) {
+    const description = conditionBlockAttributes[location.value];
+    if (!description)
+        return null;
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: description,
+        },
+    };
+}

package/src/handlers/hover/condition-key.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { ConditionKeyLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleConditionKeyHover(location: ConditionKeyLocation): Hover | null;

package/src/handlers/hover/condition-key.js

@@ -0,0 +1,53 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { ServiceReference } from "../../lib/iam-policy/reference/services.js";
+import { formatConditionKeyDocumentation } from "../completion/condition-key.js";
+const placeholderPattern = /\$\{[^}]+\}/g;
+function patternToRegex(pattern) {
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const withPlaceholders = escaped.replace(/\\\$\\\{[^}]+\\\}/g, '.+');
+    return new RegExp(`^${withPlaceholders}$`);
+}
+function findByPattern(keyName, globals, service) {
+    for (const global of globals) {
+        if (placeholderPattern.test(global.name) && patternToRegex(global.name).test(keyName)) {
+            const conditionKey = service ? ServiceReference.getConditionKey(service, global.name) : undefined;
+            return { global, conditionKey };
+        }
+    }
+    if (service) {
+        const serviceData = ServiceReference.getServiceData(service);
+        if (serviceData) {
+            for (const name of Object.keys(serviceData.conditionKeys)) {
+                if (placeholderPattern.test(name) && patternToRegex(name).test(keyName)) {
+                    return { conditionKey: serviceData.conditionKeys[name] };
+                }
+            }
+        }
+    }
+    return null;
+}
+export function handleConditionKeyHover(location) {
+    const keyName = location.value;
+    if (!keyName)
+        return null;
+    const globalKeys = ServiceReference.getGlobalConditionKeys();
+    const service = keyName.split(':')[0];
+    let global = globalKeys.find((k) => k.name === keyName);
+    let conditionKey = service ? ServiceReference.getConditionKey(service, keyName) : undefined;
+    if (!global && !conditionKey) {
+        const match = findByPattern(keyName, globalKeys, service);
+        if (!match)
+            return null;
+        global = match.global;
+        conditionKey = match.conditionKey;
+    }
+    const types = conditionKey?.types ?? [];
+    const docs = formatConditionKeyDocumentation(types, global, conditionKey);
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: `**${keyName}**\n\n${docs}`,
+        },
+    };
+}

package/src/handlers/hover/condition-operator.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { ConditionOperatorLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleConditionOperatorHover(location: ConditionOperatorLocation): Hover | null;

package/src/handlers/hover/condition-operator.js

@@ -0,0 +1,14 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { conditionOperators } from "../../lib/iam-policy/condition-operators.js";
+export function handleConditionOperatorHover(location) {
+    const operator = conditionOperators[location.value];
+    if (!operator)
+        return null;
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: operator.description,
+        },
+    };
+}

package/src/handlers/hover/effect-value.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { EffectValueLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleEffectValueHover(location: EffectValueLocation): Hover | null;

package/src/handlers/hover/effect-value.js

@@ -0,0 +1,17 @@
+import { MarkupKind } from 'vscode-languageserver';
+const effectDescriptions = {
+    Allow: 'Grants access to the specified resources and actions.\n\nBy default, all requests are implicitly denied. An `Allow` overrides implicit denies but never overrides an explicit `Deny`.',
+    Deny: 'Explicitly denies access to the specified resources and actions.\n\nAn explicit `Deny` always takes precedence — it overrides any `Allow` statements, regardless of where they appear.',
+};
+export function handleEffectValueHover(location) {
+    const description = effectDescriptions[location.value];
+    if (!description)
+        return null;
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: description,
+        },
+    };
+}

package/src/handlers/hover/index.d.ts

@@ -0,0 +1,3 @@
+import type { Connection, Hover, HoverParams } from 'vscode-languageserver';
+import type { TreeManager } from '../../lib/treesitter/manager.ts';
+export declare function hoverHandler(params: HoverParams, treeManager: TreeManager, connection: Connection): Hover | null;

package/src/handlers/hover/index.js

@@ -0,0 +1,69 @@
+import { resolvePolicyLocation } from "../../lib/iam-policy/location.js";
+import { handleActionValueHover } from "./action-value.js";
+import { handleConditionBlockHover } from "./condition-block.js";
+import { handleConditionKeyHover } from "./condition-key.js";
+import { handleConditionOperatorHover } from "./condition-operator.js";
+import { handleEffectValueHover } from "./effect-value.js";
+import { handlePrincipalBlockHover } from "./principal-block.js";
+import { handlePrincipalTypeHover } from "./principal-type.js";
+import { handlePrincipalTypedValueHover } from "./principal-typed-value.js";
+import { handlePrincipalValueHover } from "./principal-value.js";
+import { handleResourceValueHover } from "./resource-value.js";
+import { handleStatementBlockHover } from "./statement-block.js";
+import { handleStatementKeyHover } from "./statement-key.js";
+export function hoverHandler(params, treeManager, connection) {
+    const handler = treeManager.getLanguageHandler(params.textDocument.uri);
+    if (!handler)
+        return null;
+    const position = params.position;
+    const cursorContext = handler.getCursorContext(params.textDocument.uri, position);
+    if (!cursorContext)
+        return null;
+    const location = resolvePolicyLocation(cursorContext);
+    connection.console.debug(`Hover debug: ${JSON.stringify({
+        uri: params.textDocument.uri,
+        cursorContext,
+        location,
+        position: params.position,
+    })}`);
+    return handleLocationHover(connection, location);
+}
+function handleLocationHover(connection, location) {
+    if (location.type === 'statement-key') {
+        return handleStatementKeyHover(connection, location);
+    }
+    else if (location.type === 'statement-block') {
+        return handleStatementBlockHover(location);
+    }
+    else if (location.type === 'effect-value') {
+        return handleEffectValueHover(location);
+    }
+    else if (location.type === 'action-value') {
+        return handleActionValueHover(location);
+    }
+    else if (location.type === 'resource-value') {
+        return handleResourceValueHover(location);
+    }
+    else if (location.type === 'principal-value') {
+        return handlePrincipalValueHover(location);
+    }
+    else if (location.type === 'principal-type' || location.type === 'principal-block-type') {
+        return handlePrincipalTypeHover(location);
+    }
+    else if (location.type === 'principal-block') {
+        return handlePrincipalBlockHover(location);
+    }
+    else if (location.type === 'principal-typed-value' || location.type === 'principal-block-identifier') {
+        return handlePrincipalTypedValueHover(location);
+    }
+    else if (location.type === 'condition-block') {
+        return handleConditionBlockHover(location);
+    }
+    else if (location.type === 'condition-operator') {
+        return handleConditionOperatorHover(location);
+    }
+    else if (location.type === 'condition-key') {
+        return handleConditionKeyHover(location);
+    }
+    return null;
+}

package/src/handlers/hover/principal-block.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { PrincipalBlockLocation } from '../../lib/iam-policy/location.ts';
+export declare function handlePrincipalBlockHover(location: PrincipalBlockLocation): Hover | null;

package/src/handlers/hover/principal-block.js

@@ -0,0 +1,17 @@
+import { MarkupKind } from 'vscode-languageserver';
+const principalBlockAttributes = {
+    type: 'The type of principal. Valid values: `*`, `AWS`, `Service`, `Federated`, `CanonicalUser`.',
+    identifiers: 'List of principal identifiers. The format depends on the `type` attribute.',
+};
+export function handlePrincipalBlockHover(location) {
+    const description = principalBlockAttributes[location.value];
+    if (!description)
+        return null;
+    return {
+        range: location.range,
+        contents: {
+            kind: MarkupKind.Markdown,
+            value: description,
+        },
+    };
+}

package/src/handlers/hover/principal-type.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { PrincipalBlockTypeLocation, PrincipalTypeLocation } from '../../lib/iam-policy/location.ts';
+export declare function handlePrincipalTypeHover(location: PrincipalTypeLocation | PrincipalBlockTypeLocation): Hover | null;

package/src/handlers/hover/principal-type.js

@@ -0,0 +1,25 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { principalTypes } from "../../lib/iam-policy/principals.js";
+export function handlePrincipalTypeHover(location) {
+    if (location.value === '*') {
+        return {
+            range: location.range,
+            contents: {
+                kind: MarkupKind.Markdown,
+                value: '**Public (unauthenticated) access**\n\nMatches all principals, including anonymous users.',
+            },
+        };
+    }
+    for (const principalType of Object.values(principalTypes)) {
+        if (principalType.value === location.value) {
+            return {
+                range: location.range,
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: principalType.description,
+                },
+            };
+        }
+    }
+    return null;
+}

package/src/handlers/hover/principal-typed-value.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { PrincipalBlockIdentifierLocation, PrincipalTypedValueLocation } from '../../lib/iam-policy/location.ts';
+export declare function handlePrincipalTypedValueHover(location: PrincipalTypedValueLocation | PrincipalBlockIdentifierLocation): Hover | null;

package/src/handlers/hover/principal-typed-value.js

@@ -0,0 +1,118 @@
+import { MarkupKind } from 'vscode-languageserver';
+import { ServiceReference } from "../../lib/iam-policy/reference/services.js";
+export function handlePrincipalTypedValueHover(location) {
+    if (location.value === '*') {
+        return {
+            range: location.range,
+            contents: {
+                kind: MarkupKind.Markdown,
+                value: '**All principals** of this type.',
+            },
+        };
+    }
+    const principalType = location.principalType;
+    if (principalType === 'Service') {
+        const principals = ServiceReference.getServicePrincipals();
+        if (principals.includes(location.value)) {
+            const serviceName = location.value.split('.')[0];
+            return {
+                range: location.range,
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: `**AWS service principal**\n\n\`${location.value}\` — allows the \`${serviceName}\` service to assume this role or access this resource.`,
+                },
+            };
+        }
+    }
+    if (principalType === 'AWS') {
+        if (/^\d{12}$/.test(location.value)) {
+            return {
+                range: location.range,
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: `**AWS account**\n\nGrants access to the root user and all IAM identities in account \`${location.value}\`.`,
+                },
+            };
+        }
+        if (location.value.startsWith('arn:')) {
+            const parts = location.value.split(':');
+            const resource = parts.slice(5).join(':');
+            if (resource.startsWith('root')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**AWS account root user**\n\nGrants access to the root user of this account. Equivalent to specifying the account ID.`,
+                    },
+                };
+            }
+            if (resource.startsWith('role/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**IAM role**\n\n\`${resource}\`\n\nAny identity that assumes this role will have the permissions granted by this statement.`,
+                    },
+                };
+            }
+            if (resource.startsWith('user/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**IAM user**\n\n\`${resource}\``,
+                    },
+                };
+            }
+            if (resource.startsWith('assumed-role/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**Assumed role session**\n\n\`${resource}\``,
+                    },
+                };
+            }
+        }
+    }
+    if (principalType === 'Federated') {
+        if (location.value.startsWith('arn:')) {
+            const resource = location.value.split(':').slice(5).join(':');
+            if (resource.startsWith('oidc-provider/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**OIDC identity provider**\n\n\`${resource}\``,
+                    },
+                };
+            }
+            if (resource.startsWith('saml-provider/')) {
+                return {
+                    range: location.range,
+                    contents: {
+                        kind: MarkupKind.Markdown,
+                        value: `**SAML identity provider**\n\n\`${resource}\``,
+                    },
+                };
+            }
+        }
+        const knownProviders = {
+            'cognito-identity.amazonaws.com': 'Amazon Cognito identity pool',
+            'www.amazon.com': 'Login with Amazon',
+            'accounts.google.com': 'Google',
+            'graph.facebook.com': 'Facebook',
+        };
+        const description = knownProviders[location.value];
+        if (description) {
+            return {
+                range: location.range,
+                contents: {
+                    kind: MarkupKind.Markdown,
+                    value: `**Federated identity provider**\n\n${description}`,
+                },
+            };
+        }
+    }
+    return null;
+}

package/src/handlers/hover/principal-value.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { PrincipalValueLocation } from '../../lib/iam-policy/location.ts';
+export declare function handlePrincipalValueHover(location: PrincipalValueLocation): Hover | null;

package/src/handlers/hover/principal-value.js

@@ -0,0 +1,13 @@
+import { MarkupKind } from 'vscode-languageserver';
+export function handlePrincipalValueHover(location) {
+    if (location.value === '*') {
+        return {
+            range: location.range,
+            contents: {
+                kind: MarkupKind.Markdown,
+                value: '**Public (unauthenticated) access**\n\nMatches all principals, including anonymous users.\n\n> **Warning:** Combining `"Principal": "*"` with `"Effect": "Allow"` grants public access. Always scope with a `Condition` element unless public access is intended.',
+            },
+        };
+    }
+    return null;
+}

package/src/handlers/hover/resource-value.d.ts

@@ -0,0 +1,3 @@
+import { type Hover } from 'vscode-languageserver';
+import type { ResourceValueLocation } from '../../lib/iam-policy/location.ts';
+export declare function handleResourceValueHover(location: ResourceValueLocation): Hover | null;