diff --git a/README.md b/README.md index f8fbd639..029e0dd3 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,20 @@ Choosing one replaces the other. The choice is saved in `gitlabComponentHelper.v +### Scripts checked with ShellCheck + +Install [ShellCheck](https://www.shellcheck.net/) (`brew install shellcheck`, `apt install shellcheck` or `winget install koalaman.shellcheck`) and job scripts are checked as you edit. Findings appear in the Problems panel, each linked to its wiki page. Without ShellCheck you get one message, and linting is skipped. + +The checks follow how GitLab runs jobs, so you don't get noise: + +- Only job-level script keys are checked, not a component input named `script`. +- A job's `before_script` and `script` run in one shell, so variables set in `before_script` count. That's its own `before_script`, or one inherited through `extends`, from `default:` or the global one. +- Variables from `variables:`, `rules: variables:` and `parallel: matrix:` aren't reported as unassigned. List project or group CI/CD variables in `gitlabComponentHelper.shellcheck.knownVariables`. +- Comparing or testing an input, as in `if [ "$[[ inputs.mode ]]" == "fast" ]`, isn't reported, since GitLab fills the value in per pipeline. +- `!reference` tags and aliases are checked where they're defined. + +To silence a finding, use the Quick Fix (`Ctrl+.` / `Cmd+.`). **Disable SC#### for this command** adds a `# shellcheck disable=` line above it, inside `|` blocks. **Ignore SC#### in workspace settings** adds the code to `gitlabComponentHelper.shellcheck.exclude`. Set `gitlabComponentHelper.shellcheck.shell` to match your job images (default `bash`). + ### Private components Add a private project or group with **GitLab CI: Add Component Project/Group**. You enter a token once per GitLab instance, and it's reused for everything on that instance. @@ -237,6 +251,12 @@ Every setting is also editable from the Settings UI under **GitLab Component Hel | `gitlabComponentHelper.versionCheck.severity` | string | `warning` | Severity of the "newer version available" diagnostic. One of `warning`, `information`. | | `gitlabComponentHelper.mcp.enabled` | boolean | `false` | Offer the bundled [MCP server](https://github.com/eFAILution/gitlab-component-helper/blob/main/docs/mcp.md) to Copilot Chat and other in-editor AI clients. When one starts it, it gets your workspace folders and the tokens for your user-level instances. Application scope only. | | `gitlabComponentHelper.versionPreferences` | object | `{}` | Version offered per component, keyed by `//`: a version, or `~latest` for the highest stable version. Set via **Set as Default Version** or **Always Use Latest** in the Component Browser. | +| `gitlabComponentHelper.shellcheck.enabled` | boolean | `true` | Lint CI script blocks with ShellCheck. Skipped when ShellCheck isn't installed. | +| `gitlabComponentHelper.shellcheck.path` | string | `""` | Path to the `shellcheck` binary; empty uses `PATH`. User or machine settings only. | +| `gitlabComponentHelper.shellcheck.shell` | string | `bash` | Dialect to check against. One of `sh`, `bash`, `dash`, `ksh`, `busybox`. | +| `gitlabComponentHelper.shellcheck.severity` | string | `warning` | Minimum severity reported. One of `error`, `warning`, `info`, `style`. | +| `gitlabComponentHelper.shellcheck.exclude` | array | `[]` | ShellCheck codes to ignore, e.g. `["SC2086"]`. | +| `gitlabComponentHelper.shellcheck.knownVariables` | array | `[]` | Variables set outside the file (project/group settings), as names or globs, e.g. `["deploy_*"]`. | | `gitlabComponentHelper.cacheTime` | number | `3600` | Component cache lifetime, in seconds. | | `gitlabComponentHelper.logLevel` | string | `ERROR` | Logging level. One of `DEBUG`, `INFO`, `WARN`, `ERROR`. | | `gitlabComponentHelper.autoShowOutput` | boolean | `false` | Show the output channel automatically when the log level changes. | @@ -321,3 +341,5 @@ A programmatic API for other extensions is planned but not exposed yet. [docs/ap ## License [MIT](https://github.com/eFAILution/gitlab-component-helper/blob/main/LICENSE) + +Script linting is inspired by [YAML with Script](https://gitlab.com/matthiesen-technology/yaml-with-script) by Matthiesen Technology (MIT). diff --git a/package.json b/package.json index 8252dc2a..b968724c 100644 --- a/package.json +++ b/package.json @@ -227,6 +227,57 @@ }, "default": {}, "markdownDescription": "Version that completion and the Component Browser offer for a component, keyed by `//`, for example `gitlab.com/components/opentofu/full-pipeline`. The value is a version, or `~latest` for the highest stable version available when you insert. Set from the Component Browser by right-clicking a version dropdown and choosing **Set as Default Version** or **Always Use Latest**." + }, + "gitlabComponentHelper.shellcheck.enabled": { + "type": "boolean", + "default": true, + "description": "Lint before_script, script and after_script blocks in GitLab CI files with ShellCheck. Needs the shellcheck binary; linting is skipped when it is not installed." + }, + "gitlabComponentHelper.shellcheck.path": { + "type": "string", + "default": "", + "scope": "machine", + "description": "Path to the shellcheck binary. Leave empty to use shellcheck from PATH." + }, + "gitlabComponentHelper.shellcheck.shell": { + "type": "string", + "enum": [ + "sh", + "bash", + "dash", + "ksh", + "busybox" + ], + "default": "bash", + "description": "Shell dialect ShellCheck checks script blocks against. Match the shell of your job images." + }, + "gitlabComponentHelper.shellcheck.severity": { + "type": "string", + "enum": [ + "error", + "warning", + "info", + "style" + ], + "default": "warning", + "description": "Minimum ShellCheck severity to report." + }, + "gitlabComponentHelper.shellcheck.exclude": { + "type": "array", + "items": { + "type": "string", + "pattern": "^(SC)?\\d{4}$" + }, + "default": [], + "description": "ShellCheck codes to ignore, e.g. [\"SC2086\"]." + }, + "gitlabComponentHelper.shellcheck.knownVariables": { + "type": "array", + "items": { + "type": "string" + }, + "default": [], + "description": "CI/CD variables set outside the file (project or group settings), so ShellCheck doesn't report them as unassigned. Names or globs, e.g. [\"deploy_*\"]. Variables defined in the file's variables:, rules: and parallel:matrix are detected automatically." } } }, diff --git a/src/core/config/defaults.ts b/src/core/config/defaults.ts index 548404f5..9b1d2695 100644 --- a/src/core/config/defaults.ts +++ b/src/core/config/defaults.ts @@ -26,6 +26,12 @@ export interface ConfigValues { 'versionCheck.severity': 'warning' | 'information'; versionPreferences: Record; 'mcp.enabled': boolean; + 'shellcheck.enabled': boolean; + 'shellcheck.path': string; + 'shellcheck.shell': 'sh' | 'bash' | 'dash' | 'ksh' | 'busybox'; + 'shellcheck.severity': 'error' | 'warning' | 'info' | 'style'; + 'shellcheck.exclude': string[]; + 'shellcheck.knownVariables': string[]; } /** A setting name without the `gitlabComponentHelper.` prefix. */ @@ -69,4 +75,10 @@ export const CONFIG_DEFAULTS: Readonly = Object.freeze({ 'versionCheck.severity': 'warning', versionPreferences: {}, 'mcp.enabled': false, + 'shellcheck.enabled': true, + 'shellcheck.path': '', + 'shellcheck.shell': 'bash', + 'shellcheck.severity': 'warning', + 'shellcheck.exclude': [], + 'shellcheck.knownVariables': [], }); diff --git a/src/extension.ts b/src/extension.ts index 74cd5fa6..df625bf1 100755 --- a/src/extension.ts +++ b/src/extension.ts @@ -10,6 +10,7 @@ import { getComponentCacheManager, ComponentCacheManager } from './services/cach import { assetRoots } from './webview/webviewHtml'; import { Logger } from './utils/logger'; import { ValidationProvider } from './providers/validationProvider'; +import { ShellCheckProvider } from './providers/shellCheckProvider'; import type { CachedComponent } from './types/cache'; import type { GitLabYamlFragment } from './types/gitlab-catalog'; import { DETACH_HOVER_COMMAND, type HoverContext } from './providers/hoverContentBuilder'; @@ -502,6 +503,7 @@ export function activate(context: vscode.ExtensionContext) { // Initialize the validation provider const validationProvider = new ValidationProvider(context); + new ShellCheckProvider(context); // Register command to update every outdated component in the active file to its latest stable version. logger.debug('[Extension] Registering updateAllComponentVersions command...', 'Extension'); diff --git a/src/providers/shellCheckProvider.ts b/src/providers/shellCheckProvider.ts new file mode 100644 index 00000000..ddd9f9b3 --- /dev/null +++ b/src/providers/shellCheckProvider.ts @@ -0,0 +1,409 @@ +import { execFile } from 'node:child_process'; +import * as vscode from 'vscode'; +import { CONFIG_DEFAULTS } from '../core/config/defaults'; +import { isGitLabCIFile } from '../utils/gitlabCiFileMatcher'; +import { Logger } from '../utils/logger'; +import { extractLintUnits, type LintUnit } from '../utils/shellScriptExtractor'; +import { + buildShellcheckArgs, + disableDirectiveEdit, + filterGitLabFalsePositives, + isShellcheckLevel, + isShellcheckShell, + mapToSource, + parseShellcheckJson, + type ShellcheckLevel, + type ShellcheckOptions, + type SourceFinding, +} from '../utils/shellcheckOutput'; + +/** Settings section for every ShellCheck setting. */ +const CONFIG_SECTION = 'gitlabComponentHelper.shellcheck'; +/** `globalState` key set when the user chooses "Don't show again" on the missing-binary message. */ +const MISSING_BINARY_DISMISSED_KEY = 'gitlabComponentHelper.shellcheck.missingBinaryDismissed'; +/** Command behind the "Ignore SC#### in workspace settings" quick fix; not in the Command Palette. */ +const EXCLUDE_CODE_COMMAND = 'gitlabComponentHelper.shellcheck.excludeCode'; +/** Wait after the last edit before linting. */ +const DEBOUNCE_MS = 500; +/** Longest a single ShellCheck run may take before it's killed. */ +const RUN_TIMEOUT_MS = 10_000; +/** ShellCheck processes run at once for one document. */ +const MAX_CONCURRENT_RUNS = 4; + +/** VS Code severity for each ShellCheck level; `style` findings show as hints rather than squiggles. */ +const SEVERITY: Record = { + error: vscode.DiagnosticSeverity.Error, + warning: vscode.DiagnosticSeverity.Warning, + info: vscode.DiagnosticSeverity.Information, + style: vscode.DiagnosticSeverity.Hint, +}; + +/** The ShellCheck binary couldn't be found (ENOENT); the message is the command that was tried. */ +class ShellcheckNotFoundError extends Error {} + +/** The `gitlabComponentHelper.shellcheck.*` settings, validated. */ +interface Settings { + enabled: boolean; + /** Binary to run: the configured path, else `shellcheck` from `PATH`. */ + command: string; + /** Dialect, minimum severity and excluded codes passed to ShellCheck. */ + options: ShellcheckOptions; + /** Names or globs of variables set outside the file, so SC2154 isn't reported for them. */ + knownVariables: string[]; +} + +/** + * @returns The `gitlabComponentHelper.shellcheck.*` settings, with invalid values replaced by their defaults. + */ +function readSettings(): Settings { + const config = vscode.workspace.getConfiguration(CONFIG_SECTION); + const shell = config.get('shell'); + const severity = config.get('severity'); + return { + enabled: config.get('enabled', CONFIG_DEFAULTS['shellcheck.enabled']), + command: config.get('path', CONFIG_DEFAULTS['shellcheck.path']).trim() || 'shellcheck', + options: { + shell: isShellcheckShell(shell) ? shell : CONFIG_DEFAULTS['shellcheck.shell'], + severity: isShellcheckLevel(severity) ? severity : CONFIG_DEFAULTS['shellcheck.severity'], + exclude: config.get('exclude', CONFIG_DEFAULTS['shellcheck.exclude']), + }, + knownVariables: config.get('knownVariables', CONFIG_DEFAULTS['shellcheck.knownVariables']), + }; +} + +/** + * Runs ShellCheck with `input` on stdin. ShellCheck exits non-zero when it has findings, so any run that produced + * output counts as success. + * + * @param command - Binary name or path. + * @param args - ShellCheck arguments. + * @param input - Script to lint. + * @returns ShellCheck's stdout. + */ +function runShellcheck(command: string, args: string[], input: string): Promise { + return new Promise((resolve, reject) => { + const child = execFile( + command, + args, + { timeout: RUN_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024, encoding: 'utf8' }, + (error, stdout) => { + if (error?.code === 'ENOENT') reject(new ShellcheckNotFoundError(command)); + else if (stdout) resolve(stdout); + else if (error) reject(error); + else resolve(''); + }, + ); + // The process may exit before reading all of stdin; the callback reports the outcome. + child.stdin?.on('error', () => undefined); + child.stdin?.end(input); + }); +} + +/** Where each diagnostic's disable directive can go, for the document version the diagnostics were made from. */ +interface DirectiveTargets { + version: number; + /** Source offset keyed by {@link diagnosticKey}; absent when the finding is not in a literal block. */ + offsets: Map; +} + +/** + * Code actions get copies of diagnostics, so match them by range and code rather than identity. + * + * @param range - Diagnostic range. + * @param code - `SC####`. + * @returns A key stable across copies. + */ +function diagnosticKey(range: vscode.Range, code: string): string { + return `${range.start.line}:${range.start.character}:${range.end.line}:${range.end.character}:${code}`; +} + +/** + * @param diagnostic - Any diagnostic. + * @returns Its `SC####` code, or `undefined` when it has none. + */ +function diagnosticCode(diagnostic: vscode.Diagnostic): string | undefined { + const code = typeof diagnostic.code === 'object' ? diagnostic.code.value : diagnostic.code; + return typeof code === 'string' && /^SC\d{4}$/.test(code) ? code : undefined; +} + +/** + * Lints GitLab CI `before_script` / `script` / `after_script` blocks with the user's ShellCheck binary and reports + * findings as diagnostics on the YAML, with quick fixes to disable a code for one command or the workspace. + */ +export class ShellCheckProvider implements vscode.CodeActionProvider { + private readonly diagnostics = vscode.languages.createDiagnosticCollection('gitlab-component-helper-shellcheck'); + private readonly directiveTargets = new Map(); + private readonly timeouts = new Map(); + private readonly logger = Logger.getInstance(); + /** Set once the binary is found missing; cleared when settings change so a fixed path is retried. */ + private binaryMissing = false; + private missingBinaryNotified = false; + + /** + * Registers the document and settings listeners, the quick-fix provider and the exclude command, then lints the + * documents already open. + * + * @param context - Extension context; owns every registration. + */ + constructor(private readonly context: vscode.ExtensionContext) { + context.subscriptions.push( + this.diagnostics, + vscode.workspace.onDidOpenTextDocument(doc => this.lint(doc)), + vscode.workspace.onDidChangeTextDocument(e => this.schedule(e.document)), + vscode.workspace.onDidSaveTextDocument(doc => this.lint(doc)), + vscode.workspace.onDidCloseTextDocument(doc => this.clear(doc)), + vscode.workspace.onDidChangeConfiguration(e => { + if (e.affectsConfiguration(CONFIG_SECTION) || e.affectsConfiguration('gitlabComponentHelper.additionalFileGlobs')) { + this.binaryMissing = false; + this.lintOpenDocuments(); + } + }), + { dispose: () => this.timeouts.forEach(clearTimeout) }, + vscode.languages.registerCodeActionsProvider({ language: 'yaml', scheme: 'file' }, this, { + providedCodeActionKinds: [vscode.CodeActionKind.QuickFix], + }), + vscode.commands.registerCommand(EXCLUDE_CODE_COMMAND, (code: unknown) => this.excludeCode(code)), + ); + this.lintOpenDocuments(); + } + + /** + * Quick fixes for ShellCheck diagnostics: disable the code for the command (only where a directive line reaches + * ShellCheck) and ignore it in workspace settings. + * + * @param document - Document the diagnostics are on. + * @param _range - Unused; actions are offered per diagnostic. + * @param context - Diagnostics at the requested range. + * @returns Actions for the ShellCheck diagnostics in `context`. + */ + public provideCodeActions( + document: vscode.TextDocument, + _range: vscode.Range, + context: vscode.CodeActionContext, + ): vscode.CodeAction[] { + const targets = this.directiveTargets.get(document.uri.toString()); + return context.diagnostics.flatMap(diagnostic => { + const code = diagnostic.source === 'shellcheck' ? diagnosticCode(diagnostic) : undefined; + if (!code) return []; + const actions: vscode.CodeAction[] = []; + + const offset = targets?.version === document.version + ? targets.offsets.get(diagnosticKey(diagnostic.range, code)) + : undefined; + const disable = offset === undefined ? undefined : this.disableForCommand(document, offset, code, diagnostic); + if (disable) actions.push(disable); + + const exclude = new vscode.CodeAction(`Ignore ${code} in workspace settings`, vscode.CodeActionKind.QuickFix); + exclude.diagnostics = [diagnostic]; + exclude.command = { title: exclude.title, command: EXCLUDE_CODE_COMMAND, arguments: [code] }; + actions.push(exclude); + return actions; + }); + } + + /** + * @param document - Document to edit. + * @param offset - Source offset of the first character of the flagged command. + * @param code - `SC####` to disable. + * @param diagnostic - Diagnostic the action fixes. + * @returns An action adding or extending a `# shellcheck disable=` line, or `undefined` when one already covers + * `code`. + */ + private disableForCommand( + document: vscode.TextDocument, + offset: number, + code: string, + diagnostic: vscode.Diagnostic, + ): vscode.CodeAction | undefined { + const line = document.positionAt(offset).line; + const previous = line > 0 ? document.lineAt(line - 1).text : undefined; + const edit = disableDirectiveEdit(document.lineAt(line).text, previous, Number(code.slice(2))); + if (!edit) return undefined; + + const action = new vscode.CodeAction(`Disable ${code} for this command`, vscode.CodeActionKind.QuickFix); + action.diagnostics = [diagnostic]; + action.isPreferred = true; + action.edit = new vscode.WorkspaceEdit(); + if (edit.kind === 'insert') { + const eol = document.eol === vscode.EndOfLine.CRLF ? '\r\n' : '\n'; + action.edit.insert(document.uri, new vscode.Position(line, 0), edit.text + eol); + } else { + action.edit.replace(document.uri, document.lineAt(line - 1).range, edit.text); + } + return action; + } + + /** + * Adds `code` to `shellcheck.exclude` in workspace settings, or user settings when no folder is open. + * + * @param code - Command argument; ignored unless it is an `SC####` code not already excluded. + */ + private async excludeCode(code: unknown): Promise { + if (typeof code !== 'string' || !/^SC\d{4}$/.test(code)) return; + const config = vscode.workspace.getConfiguration(CONFIG_SECTION); + const target = vscode.workspace.workspaceFolders?.length + ? vscode.ConfigurationTarget.Workspace + : vscode.ConfigurationTarget.Global; + const current = config.inspect('exclude'); + const existing = (target === vscode.ConfigurationTarget.Workspace ? current?.workspaceValue : current?.globalValue) + ?? []; + if (existing.some(entry => entry.trim().toUpperCase().replace(/^(SC)?/, 'SC') === code)) return; + await config.update('exclude', [...existing, code], target); + } + + /** Lints every open document that qualifies. */ + public lintOpenDocuments(): void { + vscode.workspace.textDocuments.forEach(doc => this.lint(doc)); + } + + /** + * @param document - Candidate document. + * @returns `true` for an on-disk GitLab CI YAML file in a trusted workspace. + */ + private isLintable(document: vscode.TextDocument): boolean { + // `file` only: a diff view's source panel shares the path and would get duplicate squiggles. + return document.uri.scheme === 'file' + && document.languageId === 'yaml' + && vscode.workspace.isTrusted + && isGitLabCIFile(document); + } + + /** + * Lints `document` once edits pause, restarting the debounce on each change. + * + * @param document - Edited document. + */ + private schedule(document: vscode.TextDocument): void { + const key = document.uri.toString(); + clearTimeout(this.timeouts.get(key)); + this.timeouts.set(key, setTimeout(() => { + this.timeouts.delete(key); + this.lint(document); + }, DEBOUNCE_MS)); + } + + /** + * Drops a closed document's pending lint, diagnostics and directive positions. + * + * @param document - Closed document. + */ + private clear(document: vscode.TextDocument): void { + const key = document.uri.toString(); + clearTimeout(this.timeouts.get(key)); + this.timeouts.delete(key); + this.diagnostics.delete(document.uri); + this.directiveTargets.delete(key); + } + + /** + * Lints `document` and replaces its diagnostics. Results for an outdated version are dropped; a missing binary + * disables linting until settings change. + * + * @param document - Document to lint. + */ + private async lint(document: vscode.TextDocument): Promise { + if (!this.isLintable(document)) return; + const settings = readSettings(); + if (!settings.enabled || this.binaryMissing) { + this.diagnostics.delete(document.uri); + return; + } + + const version = document.version; + const units = extractLintUnits(document.getText()); + try { + const findings = await this.runAll(units, settings); + if (document.isClosed || document.version !== version) return; + const offsets = new Map(); + this.diagnostics.set(document.uri, this.toDiagnostics(document, findings, offsets)); + this.directiveTargets.set(document.uri.toString(), { version, offsets }); + } catch (error) { + if (error instanceof ShellcheckNotFoundError) { + this.binaryMissing = true; + this.diagnostics.delete(document.uri); + this.logger.info(`[ShellCheckProvider] ShellCheck not found at '${settings.command}'`, 'ShellCheckProvider'); + void this.notifyMissingBinary(); + } else { + this.logger.warn(`[ShellCheckProvider] ShellCheck failed: ${error}`, 'ShellCheckProvider'); + } + } + } + + /** + * Runs ShellCheck over each unit, at most {@link MAX_CONCURRENT_RUNS} at a time. + * + * @param units - Lint units for one document. + * @param settings - Current settings. + * @returns Filtered findings positioned in the source. + */ + private async runAll(units: LintUnit[], settings: Settings): Promise { + const args = buildShellcheckArgs(settings.options); + const results: SourceFinding[][] = []; + let next = 0; + /** Takes the next unit until none are left; several run side by side. */ + const worker = async (): Promise => { + while (next < units.length) { + const unit = units[next++]; + const stdout = await runShellcheck(settings.command, args, unit.content); + const comments = filterGitLabFalsePositives(unit, parseShellcheckJson(stdout), settings.knownVariables); + results.push(mapToSource(unit, comments)); + } + }; + await Promise.all(Array.from({ length: Math.min(MAX_CONCURRENT_RUNS, units.length) }, worker)); + return results.flat(); + } + + /** + * Converts findings to diagnostics, dropping duplicates and widening zero-width ranges to the word. + * + * @param document - Document the findings are in. + * @param findings - Findings with source offsets. + * @param directiveOffsets - Filled with each diagnostic's directive position, keyed by {@link diagnosticKey}. + * @returns Diagnostics linked to each code's wiki page. + */ + private toDiagnostics( + document: vscode.TextDocument, + findings: SourceFinding[], + directiveOffsets: Map, + ): vscode.Diagnostic[] { + const seen = new Set(); + return findings.flatMap(finding => { + const id = `${finding.start}:${finding.end}:${finding.code}`; + if (seen.has(id)) return []; + seen.add(id); + + const start = document.positionAt(finding.start); + const range = finding.end > finding.start + ? new vscode.Range(start, document.positionAt(finding.end)) + : document.getWordRangeAtPosition(start) ?? new vscode.Range(start, start.translate(0, 1)); + const diagnostic = new vscode.Diagnostic(range, finding.message, SEVERITY[finding.level]); + diagnostic.source = 'shellcheck'; + diagnostic.code = { + value: `SC${finding.code}`, + target: vscode.Uri.parse(`https://www.shellcheck.net/wiki/SC${finding.code}`), + }; + if (finding.directiveOffset !== undefined) { + directiveOffsets.set(diagnosticKey(range, `SC${finding.code}`), finding.directiveOffset); + } + return [diagnostic]; + }); + } + + /** Shows the missing-binary message once per session, unless the user chose "Don't show again". */ + private async notifyMissingBinary(): Promise { + if (this.missingBinaryNotified || this.context.globalState.get(MISSING_BINARY_DISMISSED_KEY)) return; + this.missingBinaryNotified = true; + const dontShow = "Don't show again"; + const choice = await vscode.window.showInformationMessage( + 'GitLab Component Helper lints CI script blocks with ShellCheck, but it was not found. Install ShellCheck or ' + + 'set gitlabComponentHelper.shellcheck.path.', + 'Open Settings', + dontShow, + ); + if (choice === dontShow) { + await this.context.globalState.update(MISSING_BINARY_DISMISSED_KEY, true); + } else if (choice === 'Open Settings') { + await vscode.commands.executeCommand('workbench.action.openSettings', CONFIG_SECTION); + } + } +} diff --git a/src/utils/ciYamlNodes.ts b/src/utils/ciYamlNodes.ts new file mode 100644 index 00000000..f43a7bb7 --- /dev/null +++ b/src/utils/ciYamlNodes.ts @@ -0,0 +1,124 @@ +/** + * Helpers over `yaml` (eemeli) document nodes for locating GitLab CI jobs and their keywords. Pure — no `vscode` + * dependency — so the script extractor and its unit tests share one definition of "what counts as a job". + */ + +import { isMap, isScalar, isSeq, type YAMLMap } from 'yaml'; + +/** Keys whose values are shell, run by the job's shell. */ +export const SCRIPT_KEYWORDS = ['before_script', 'script', 'after_script'] as const; + +/** + * Top-level keys that are global keywords rather than job names. `before_script`/`after_script` are the deprecated + * globals and handled separately; `default` holds job-like keywords but is not itself a job. + */ +export const NON_JOB_TOP_LEVEL_KEYWORDS: ReadonlySet = new Set([ + 'spec', + 'include', + 'stages', + 'variables', + 'workflow', + 'image', + 'services', + 'cache', + 'default', + 'before_script', + 'after_script', +]); + +/** + * @param map - Mapping node to read from. + * @param key - Plain string key. + * @returns The value node stored under `key`, or `undefined` when absent. + */ +export function getNode(map: YAMLMap, key: string): unknown { + return map.get(key, true); +} + +/** + * @param map - Mapping node to read from. + * @param key - Plain string key. + * @returns The value under `key` when it is itself a mapping. + */ +export function getMap(map: YAMLMap, key: string): YAMLMap | undefined { + const node = getNode(map, key); + return isMap(node) ? node : undefined; +} + +/** + * @param map - Mapping node to iterate. + * @returns Each entry whose key is a string scalar, paired with its key text. + */ +export function stringKeyedEntries(map: YAMLMap): Array<{ key: string; value: unknown }> { + const entries: Array<{ key: string; value: unknown }> = []; + for (const pair of map.items) { + if (isScalar(pair.key) && typeof pair.key.value === 'string') { + entries.push({ key: pair.key.value, value: pair.value }); + } + } + return entries; +} + +/** + * Jobs are the top-level mapping entries that are not global keywords. Hidden (`.name`) and interpolated + * (`$[[ inputs.job_name ]]`) names count, since both carry job keywords. + * + * @param topLevel - A document's root mapping. + * @returns Name and mapping node for every job in the document. + */ +export function jobEntries(topLevel: YAMLMap): Array<{ name: string; job: YAMLMap }> { + return stringKeyedEntries(topLevel).flatMap(({ key, value }) => + !NON_JOB_TOP_LEVEL_KEYWORDS.has(key) && isMap(value) ? [{ name: key, job: value }] : []); +} + +/** + * @param job - A job mapping. + * @returns Names listed under the job's `extends:`, in source order. + */ +function extendsNames(job: YAMLMap): string[] { + const node = getNode(job, 'extends'); + if (isScalar(node) && typeof node.value === 'string') return [node.value]; + if (isSeq(node)) { + return node.items.flatMap(item => isScalar(item) && typeof item.value === 'string' ? [item.value] : []); + } + return []; +} + +/** + * Orders a job and everything it inherits through same-file `extends:` from highest to lowest precedence. A later + * `extends` entry overrides an earlier one, and the job's own keys override both. Templates defined in other files + * are not visible here and are skipped. + * + * @param topLevel - The document's root mapping, where templates are looked up. + * @param job - The job to resolve. + * @returns The job first, then its templates; each template appears once even across cycles or diamonds. + */ +export function extendsChain(topLevel: YAMLMap, job: YAMLMap): YAMLMap[] { + const chain: YAMLMap[] = []; + /** Appends `node`, then the templates it extends, latest-listed first, skipping any already visited. */ + const visit = (node: YAMLMap): void => { + if (chain.includes(node)) return; + chain.push(node); + for (const name of extendsNames(node).reverse()) { + const template = getMap(topLevel, name); + if (template) visit(template); + } + }; + visit(job); + return chain; +} + +/** + * Whether `default:`'s `before_script` reaches this job, per its `inherit:default` setting. + * + * @param job - The job mapping. + * @returns `false` when `inherit:default` is `false` or a list without `before_script`. + */ +export function inheritsDefaultBeforeScript(job: YAMLMap): boolean { + const inherit = getMap(job, 'inherit'); + if (!inherit) return true; + const node = getNode(inherit, 'default'); + if (isScalar(node) && node.value === false) return false; + if (isSeq(node)) return node.items.some(item => isScalar(item) && item.value === 'before_script'); + return true; +} diff --git a/src/utils/scriptVariables.ts b/src/utils/scriptVariables.ts new file mode 100644 index 00000000..5d77efab --- /dev/null +++ b/src/utils/scriptVariables.ts @@ -0,0 +1,60 @@ +/** + * Names of CI/CD variables GitLab injects into a job's shell. ShellCheck can't see these, so it reports lowercase or + * mixed-case ones as "referenced but not assigned" (SC2154). Pure — no `vscode` dependency. + */ + +import { minimatch } from 'minimatch'; +import { isMap, isSeq, type YAMLMap } from 'yaml'; +import { extendsChain, getMap, getNode, stringKeyedEntries } from './ciYamlNodes'; + +/** + * @param node - A `variables:` value node. + * @returns The variable names it defines; values (plain or `{ value, description }`) are irrelevant. + */ +function variableNames(node: unknown): string[] { + return isMap(node) ? stringKeyedEntries(node).map(entry => entry.key) : []; +} + +/** + * Collects the variables a job's shell sees from the file itself: global `variables:`, plus for a job its own + * `variables:`, those inherited through same-file `extends:`, every `rules[].variables`, and `parallel:matrix` + * keys. + * + * @param topLevel - The document's root mapping. + * @param job - The job, or `undefined` for blocks outside any job (`default:`, legacy globals). + * @returns Variable names known to be set when the job runs. + */ +export function collectKnownVariables(topLevel: YAMLMap, job: YAMLMap | undefined): Set { + const names = new Set(variableNames(getNode(topLevel, 'variables'))); + if (!job) return names; + + for (const node of extendsChain(topLevel, job)) { + variableNames(getNode(node, 'variables')).forEach(name => names.add(name)); + + const rules = getNode(node, 'rules'); + if (isSeq(rules)) { + for (const rule of rules.items) { + if (isMap(rule)) variableNames(getNode(rule, 'variables')).forEach(name => names.add(name)); + } + } + + const parallel = getMap(node, 'parallel'); + const matrix = parallel ? getNode(parallel, 'matrix') : undefined; + if (isSeq(matrix)) { + for (const entry of matrix.items) { + if (isMap(entry)) stringKeyedEntries(entry).forEach(({ key }) => names.add(key)); + } + } + } + return names; +} + +/** + * @param name - Variable name ShellCheck reported. + * @param known - Names collected from the file. + * @param patterns - User-configured names or globs for variables set outside the file (project/group settings). + * @returns `true` when the variable is known to GitLab, so the finding is a false positive. + */ +export function isKnownVariable(name: string, known: ReadonlySet, patterns: readonly string[]): boolean { + return known.has(name) || patterns.some(pattern => minimatch(name, pattern)); +} diff --git a/src/utils/shellScriptExtractor.ts b/src/utils/shellScriptExtractor.ts new file mode 100644 index 00000000..1a2189f5 --- /dev/null +++ b/src/utils/shellScriptExtractor.ts @@ -0,0 +1,300 @@ +/** + * Extracts the shell in GitLab CI `before_script` / `script` / `after_script` blocks as lint units for ShellCheck, + * with a source offset for every character so findings land on the right YAML column whatever the scalar style. + * Pure — no `vscode` dependency. + */ + +import { isAlias, isMap, isScalar, isSeq, parseAllDocuments, Scalar, type YAMLMap } from 'yaml'; +import { + extendsChain, + getMap, + getNode, + inheritsDefaultBeforeScript, + jobEntries, +} from './ciYamlNodes'; +import { collectKnownVariables } from './scriptVariables'; + +/** A run of lint-unit content, `[start, end)`, including its trailing separator. */ +export interface ScriptSegment { + start: number; + end: number; + /** `false` for an inherited `before_script`, linted for context but reported where it is defined. */ + reportable: boolean; +} + +/** A range of lint-unit content, `[start, end)`. */ +export interface ContentRange { + start: number; + end: number; +} + +/** One shell session's worth of script, as ShellCheck will see it. */ +export interface LintUnit { + /** Shell text with component interpolation masked; lines are joined with `\n`. */ + content: string; + /** Source offset in the YAML text for each character of `content`. */ + offsets: number[]; + /** One per block, in order; says which content is reported. */ + segments: ScriptSegment[]; + /** Where each `$[[ ... ]]` was masked. */ + interpolations: ContentRange[]; + /** Content from literal `|` block scalars, where each line is its own source line. */ + literalBlocks: ContentRange[]; + /** Variables GitLab sets for this job, from the file. */ + knownVariables: ReadonlySet; + /** A lone `before_script`: jobs' `script` continues in the same shell, so its assignments may be used there. */ + continuesInScript: boolean; +} + +/** One scalar's parsed value, aligned with the source. */ +interface Piece { + text: string; + /** Source offset for each character of `text`. */ + offsets: number[]; + /** From a literal `|` block scalar. */ + literal: boolean; +} + +/** The pieces of one script keyword's value, such as a job's `before_script`. */ +interface Block { + pieces: Piece[]; + /** `false` for an inherited `before_script`. */ + reportable: boolean; +} + +/** A `$[[ ... ]]` component interpolation. */ +const INTERPOLATION = /\$\[\[.*?\]\]/g; + +/** + * Replaces each `$[[ ... ]]` component interpolation with an inert word of the same length, so ShellCheck doesn't + * misread it as `$[` arithmetic and columns stay aligned with the source. + * + * @param text - Shell content. + * @returns `text` with every interpolation replaced by underscores. + */ +export function maskComponentInterpolation(text: string): string { + return text.replace(INTERPOLATION, match => '_'.repeat(match.length)); +} + +/** + * Length of a double-quoted escape sequence starting at the backslash. + * + * @param marker - The character after the backslash. + * @returns Source characters the escape occupies. + */ +function escapeLength(marker: string): number { + if (marker === 'x') return 4; + if (marker === 'u') return 6; + if (marker === 'U') return 10; + return 2; +} + +/** + * Maps each character of a scalar's parsed value back to its source offset by walking value and source together. + * Source characters the parser consumed (indentation, folded line breaks, quotes, escape markers) are skipped; + * value characters with no source counterpart map to the nearest source position. + * + * @param source - Full YAML text. + * @param scalar - A string-valued scalar node with a source range. + * @returns The value with per-character offsets, or `undefined` for non-string or rangeless scalars. + */ +function alignScalar(source: string, scalar: Scalar): Piece | undefined { + if (!scalar.range) return undefined; + const value = scalar.value; + const text = typeof value === 'string' ? value : typeof value === 'number' || typeof value === 'boolean' + ? String(value) : undefined; + if (text === undefined) return undefined; + + const [rangeStart, rangeEnd] = scalar.range; + const isBlock = scalar.type === Scalar.BLOCK_LITERAL || scalar.type === Scalar.BLOCK_FOLDED; + const isQuoted = scalar.type === Scalar.QUOTE_DOUBLE || scalar.type === Scalar.QUOTE_SINGLE; + const isDouble = scalar.type === Scalar.QUOTE_DOUBLE; + + let pos = rangeStart; + let end = rangeEnd; + if (isBlock) { + const headerEnd = source.indexOf('\n', rangeStart); + pos = headerEnd === -1 ? rangeEnd : headerEnd + 1; + } else if (isQuoted) { + pos = rangeStart + 1; + end = rangeEnd - 1; + } + const last = Math.max(rangeStart, end - 1); + + // UTF-16 units, matching how both `text` and `source` index. + const offsets: number[] = []; + for (let i = 0; i < text.length; i++) offsets.push(alignChar(text[i])); + return { text, offsets, literal: scalar.type === Scalar.BLOCK_LITERAL }; + + /** + * Advances through the source to `char`, skipping what the parser consumed. + * + * @param char - Next character of the parsed value. + * @returns Its source offset, or the nearest position when it has no source counterpart. + */ + function alignChar(char: string): number { + while (pos < end) { + const current = source[pos]; + if (current === char) return pos++; + if (isDouble && current === '\\') { + const marker = source[pos + 1]; + if (marker === '\n' || marker === '\r') { + pos += 2; + continue; + } + const at = pos; + pos += escapeLength(marker); + return at; + } + if (current === ' ' || current === '\t' || current === '\n' || current === '\r' || current === "'") { + pos++; + continue; + } + break; + } + return Math.min(pos, last); + } +} + +/** + * Flattens a script value into scalar pieces, as GitLab flattens nested sequences. `!reference` tags and aliases + * are skipped: the referenced script is linted where it is defined. + * + * @param source - Full YAML text. + * @param node - The value of a script keyword. + * @returns Pieces in execution order. + */ +function scriptPieces(source: string, node: unknown): Piece[] { + if (isAlias(node)) return []; + if (isScalar(node)) { + const piece = alignScalar(source, node); + return piece ? [piece] : []; + } + if (isSeq(node) && node.tag !== '!reference') { + return node.items.flatMap(item => scriptPieces(source, item)); + } + return []; +} + +/** + * Joins blocks into one lint unit, `\n`-separated, recording which content ranges are reportable. + * + * @param blocks - Blocks in execution order. + * @param knownVariables - Variables GitLab sets for the job. + * @param continuesInScript - Whether the unit is a lone `before_script`. + * @returns The unit, or `undefined` when there is no shell to lint. + */ +function buildUnit( + blocks: Block[], + knownVariables: ReadonlySet, + continuesInScript = false, +): LintUnit | undefined { + let content = ''; + const offsets: number[] = []; + const segments: ScriptSegment[] = []; + const literalBlocks: ContentRange[] = []; + + for (const block of blocks) { + const start = content.length; + for (const piece of block.pieces) { + if (piece.literal) literalBlocks.push({ start: content.length, end: content.length + piece.text.length }); + content += piece.text + '\n'; + const separatorOffset = piece.offsets.length > 0 ? piece.offsets[piece.offsets.length - 1] + 1 : 0; + offsets.push(...piece.offsets, separatorOffset); + } + if (content.length > start) segments.push({ start, end: content.length, reportable: block.reportable }); + } + + if (content.trim() === '' || !segments.some(segment => segment.reportable)) return undefined; + const interpolations = Array.from(content.matchAll(INTERPOLATION), match => ({ + start: match.index, + end: match.index + match[0].length, + })); + return { + content: maskComponentInterpolation(content), + offsets, + segments, + interpolations, + literalBlocks, + knownVariables, + continuesInScript, + }; +} + +/** + * The `before_script` a job without its own runs: the nearest same-file `extends` template's, else `default:`'s + * (unless `inherit:default` excludes it), else the legacy global. + * + * @param topLevel - The document's root mapping. + * @param job - A job with no `before_script` of its own. + * @param fallback - `default:`'s `before_script`, or the legacy global when there is none. + * @returns The inherited value node, or `undefined`. + */ +function inheritedBeforeScript(topLevel: YAMLMap, job: YAMLMap, fallback: unknown): unknown { + for (const template of extendsChain(topLevel, job).slice(1)) { + const node = getNode(template, 'before_script'); + if (node !== undefined) return node; + } + return inheritsDefaultBeforeScript(job) ? fallback : undefined; +} + +/** + * Lint units for one document's root mapping, following GitLab's shell boundaries: a job's effective + * `before_script` and its `script` share one shell; `after_script` runs in its own. + * + * @param source - Full YAML text. + * @param topLevel - The document's root mapping. + * @returns Units for legacy globals, `default:`, and every job. + */ +function documentUnits(source: string, topLevel: YAMLMap): LintUnit[] { + const units: LintUnit[] = []; + const globals = collectKnownVariables(topLevel, undefined); + /** Keeps `unit` unless there was no shell to lint. */ + const push = (unit: LintUnit | undefined): void => { + if (unit) units.push(unit); + }; + /** A block defined here, so its findings are reported. */ + const own = (node: unknown): Block => ({ pieces: scriptPieces(source, node), reportable: true }); + + const globalBefore = getNode(topLevel, 'before_script'); + push(buildUnit([own(globalBefore)], globals, true)); + push(buildUnit([own(getNode(topLevel, 'after_script'))], globals)); + + const defaults = getMap(topLevel, 'default'); + const defaultBefore = defaults ? getNode(defaults, 'before_script') : undefined; + if (defaults) { + push(buildUnit([own(defaultBefore)], globals, true)); + push(buildUnit([own(getNode(defaults, 'after_script'))], globals)); + } + + for (const { job } of jobEntries(topLevel)) { + const known = collectKnownVariables(topLevel, job); + const ownBefore = getNode(job, 'before_script'); + const script = getNode(job, 'script'); + + const before: Block = ownBefore !== undefined + ? own(ownBefore) + : { + pieces: scriptPieces(source, inheritedBeforeScript(topLevel, job, defaultBefore ?? globalBefore)), + reportable: false, + }; + + push(script !== undefined ? buildUnit([before, own(script)], known) : buildUnit([before], known, true)); + push(buildUnit([own(getNode(job, 'after_script'))], known)); + } + return units; +} + +/** + * Extracts every lintable shell block from GitLab CI YAML. Only job-level script keywords count, so a + * `spec.inputs.script` input or an `include[].inputs.script` value is never treated as shell. Documents that fail + * to parse are skipped rather than linted from a guessed structure. Merge keys are enabled, as GitLab supports them, + * so a job with several `<<: *anchor` entries isn't a duplicate-key error. + * + * @param source - Full YAML text; component templates may hold a `spec:` document before `---`. + * @returns Lint units in document order. + */ +export function extractLintUnits(source: string): LintUnit[] { + return parseAllDocuments(source, { merge: true }).flatMap(doc => + doc.errors.length === 0 && isMap(doc.contents) ? documentUnits(source, doc.contents) : []); +} diff --git a/src/utils/shellcheckOutput.ts b/src/utils/shellcheckOutput.ts new file mode 100644 index 00000000..76cd5226 --- /dev/null +++ b/src/utils/shellcheckOutput.ts @@ -0,0 +1,284 @@ +/** + * Builds ShellCheck arguments, parses its `json1` output, and maps findings from lint-unit coordinates back to YAML + * source offsets. Pure — no `vscode` dependency and no process spawning. + */ + +import type { ContentRange, LintUnit } from './shellScriptExtractor'; +import { isKnownVariable } from './scriptVariables'; + +/** Dialects ShellCheck's `--shell` accepts; matches the `shellcheck.shell` setting's enum. */ +export const SHELLCHECK_SHELLS = ['sh', 'bash', 'dash', 'ksh', 'busybox'] as const; +/** One of {@link SHELLCHECK_SHELLS}. */ +export type ShellcheckShell = typeof SHELLCHECK_SHELLS[number]; + +/** ShellCheck severities, most severe first; matches the `shellcheck.severity` setting's enum. */ +export const SHELLCHECK_LEVELS = ['error', 'warning', 'info', 'style'] as const; +/** One of {@link SHELLCHECK_LEVELS}. */ +export type ShellcheckLevel = typeof SHELLCHECK_LEVELS[number]; + +/** How to run ShellCheck, from the `shellcheck.*` settings. */ +export interface ShellcheckOptions { + shell: ShellcheckShell; + /** Minimum level reported. */ + severity: ShellcheckLevel; + /** Codes to suppress, as `SC2086` or `2086`; anything else is dropped. */ + exclude: readonly string[]; +} + +/** One finding as ShellCheck's `json1` format reports it; lines and columns are 1-based, tabs count as one. */ +export interface ShellcheckComment { + line: number; + endLine: number; + column: number; + endColumn: number; + level: ShellcheckLevel; + /** The number only: `2086` for SC2086. */ + code: number; + message: string; +} + +/** A finding positioned in the YAML source by offset, `[start, end)`. */ +export interface SourceFinding { + start: number; + end: number; + level: ShellcheckLevel; + /** The number only: `2086` for SC2086. */ + code: number; + message: string; + /** + * Source offset of the first character of the line that starts the flagged command, where a + * `# shellcheck disable=` line can go. Only set inside a literal `|` block: in any other scalar style an inserted + * line would be a YAML comment or be folded into the command. + */ + directiveOffset?: number; +} + +/** A change to the YAML that disables a code for one command. */ +export type DisableDirectiveEdit = + | { kind: 'insert'; text: string } + | { kind: 'replacePrevious'; text: string }; + +/** + * @param value - Candidate string. + * @returns `true` when `value` is one of ShellCheck's shell dialects. + */ +export function isShellcheckShell(value: unknown): value is ShellcheckShell { + return SHELLCHECK_SHELLS.some(shell => shell === value); +} + +/** + * @param value - Candidate string. + * @returns `true` when `value` is one of ShellCheck's severity levels. + */ +export function isShellcheckLevel(value: unknown): value is ShellcheckLevel { + return SHELLCHECK_LEVELS.some(level => level === value); +} + +/** + * @param options - Dialect, minimum severity and excluded codes. + * @returns Arguments for reading a script from stdin and writing `json1`. + */ +export function buildShellcheckArgs(options: ShellcheckOptions): string[] { + const exclude = options.exclude + .map(code => code.trim().toUpperCase()) + .filter(code => /^(SC)?\d{4}$/.test(code)); + return [ + '--format=json1', + `--shell=${options.shell}`, + `--severity=${options.severity}`, + ...(exclude.length > 0 ? [`--exclude=${exclude.join(',')}`] : []), + '-', + ]; +} + +/** + * @param value - Parsed JSON. + * @returns `true` when `value` is a non-null object. + */ +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null; +} + +/** + * @param value - One entry of ShellCheck's `comments` array. + * @returns `true` when it has every field a finding needs, with the right types. + */ +function isShellcheckComment(value: unknown): value is ShellcheckComment { + return isRecord(value) + && typeof value.line === 'number' + && typeof value.endLine === 'number' + && typeof value.column === 'number' + && typeof value.endColumn === 'number' + && isShellcheckLevel(value.level) + && typeof value.code === 'number' + && typeof value.message === 'string'; +} + +/** + * @param stdout - ShellCheck's `json1` output. + * @returns The well-formed comments; malformed output or entries yield nothing rather than throwing. + */ +export function parseShellcheckJson(stdout: string): ShellcheckComment[] { + let parsed: unknown; + try { + parsed = JSON.parse(stdout); + } catch { + return []; + } + if (!isRecord(parsed) || !Array.isArray(parsed.comments)) return []; + return parsed.comments.filter(isShellcheckComment); +} + +/** SC2154's message; group 1 is the variable name. */ +const UNASSIGNED_VARIABLE = /^([A-Za-z_][A-Za-z0-9_]*) is referenced but not assigned\b/; + +/** + * Codes ShellCheck raises when an operand is a fixed string. A masked `$[[ inputs.x ]]` is one, but GitLab fills it + * in per pipeline, so comparing or testing it is deliberate. + */ +const CONSTANT_EXPRESSION_CODES: ReadonlySet = new Set([ + 2050, // This expression is constant. + 2078, // This expression is constant (bare `[ "..." ]`). + 2157, // Argument to -z/-n is always false/true due to literal strings. + 2194, // This word is constant (`case` subject). +]); + +/** + * @param content - Lint-unit content. + * @returns Index of the first character of each line. + */ +function lineStarts(content: string): number[] { + const starts = [0]; + for (let i = 0; i < content.length; i++) { + if (content[i] === '\n') starts.push(i + 1); + } + return starts; +} + +/** + * Drops findings that are false in a GitLab job: + * - SC2154 for variables GitLab injects; + * - SC2034 ("appears unused") in a lone `before_script`, whose assignments are used by the jobs' `script` in the + * same shell; + * - constant-expression findings on a line holding a `$[[ ... ]]` interpolation. + * + * @param unit - The lint unit the findings came from. + * @param comments - Parsed ShellCheck findings. + * @param patterns - User-configured names or globs for variables set outside the file. + * @returns `comments` without GitLab false positives. + */ +export function filterGitLabFalsePositives( + unit: LintUnit, + comments: readonly ShellcheckComment[], + patterns: readonly string[], +): ShellcheckComment[] { + const starts = lineStarts(unit.content); + /** Whether any line the finding spans held a masked `$[[ ... ]]`. */ + const hasInterpolation = (comment: ShellcheckComment): boolean => { + const from = starts[comment.line - 1]; + if (from === undefined) return false; + const to = starts[comment.endLine] ?? unit.content.length; + return unit.interpolations.some(range => range.start < to && range.end > from); + }; + + return comments.filter(comment => { + if (comment.code === 2034) return !unit.continuesInScript; + if (CONSTANT_EXPRESSION_CODES.has(comment.code)) return !hasInterpolation(comment); + if (comment.code !== 2154) return true; + const name = UNASSIGNED_VARIABLE.exec(comment.message)?.[1]; + return name === undefined || !isKnownVariable(name, unit.knownVariables, patterns); + }); +} + +/** + * @param starts - Line start indices. + * @param line - 1-based line. + * @param column - 1-based column. + * @returns The content index, or `undefined` when the line does not exist. + */ +function contentIndex(starts: number[], line: number, column: number): number | undefined { + const start = starts[line - 1]; + return start === undefined ? undefined : start + Math.max(column - 1, 0); +} + +/** + * The content index where a disable directive for a finding on `line` can go: the start of that line, moved up past + * lines it continues with a trailing backslash, since a comment line would break the continuation. + * + * @param unit - The lint unit. + * @param starts - Its line starts. + * @param line - 1-based line of the finding. + * @param block - The literal block holding the finding. + * @returns Content index of the first non-blank character of the command's first line. + */ +function directiveIndex(unit: LintUnit, starts: number[], line: number, block: ContentRange): number { + let index = line - 1; + while (index > 0 && starts[index - 1] >= block.start) { + const previous = unit.content.slice(starts[index - 1], starts[index] - 1); + if (!/\\[ \t]*$/.test(previous)) break; + index--; + } + const lineStart = starts[index]; + const firstNonBlank = unit.content.slice(lineStart).search(/[^ \t]/); + return firstNonBlank === -1 ? lineStart : lineStart + firstNonBlank; +} + +/** + * Positions ShellCheck findings in the YAML source. Findings in an inherited `before_script` are dropped, since they + * are reported where that block is defined; a range spilling past its segment is clipped to it. + * + * @param unit - The lint unit ShellCheck was run on. + * @param comments - Findings for that unit. + * @returns Findings with source offsets. + */ +export function mapToSource(unit: LintUnit, comments: readonly ShellcheckComment[]): SourceFinding[] { + const starts = lineStarts(unit.content); + const lastIndex = unit.offsets.length - 1; + if (lastIndex < 0) return []; + + return comments.flatMap(comment => { + const rawStart = contentIndex(starts, comment.line, comment.column); + if (rawStart === undefined) return []; + const startIndex = Math.min(rawStart, lastIndex); + const segment = unit.segments.find(s => startIndex >= s.start && startIndex < s.end); + if (!segment?.reportable) return []; + + const rawEnd = contentIndex(starts, comment.endLine, comment.endColumn) ?? unit.content.length; + const endIndex = Math.min(Math.max(rawEnd, startIndex), segment.end); + const start = unit.offsets[startIndex]; + const end = endIndex > startIndex ? Math.max(unit.offsets[endIndex - 1] + 1, start) : start; + + const finding: SourceFinding = { start, end, level: comment.level, code: comment.code, message: comment.message }; + const block = unit.literalBlocks.find(b => startIndex >= b.start && startIndex < b.end); + if (block) finding.directiveOffset = unit.offsets[directiveIndex(unit, starts, comment.line, block)]; + return [finding]; + }); +} + +/** A `# shellcheck disable=` line on its own; group 1 is the indent, group 2 the comma-separated codes. */ +const DISABLE_DIRECTIVE = /^([ \t]*)#[ \t]*shellcheck[ \t]+disable=([A-Za-z0-9,]+)[ \t]*$/; + +/** + * Works out the edit that disables `code` for the command on `targetLine`: append it to a `# shellcheck disable=` + * line directly above at the same indent, or insert a new one. + * + * @param targetLine - Text of the command's first line. + * @param previousLine - Text of the line above, if any. + * @param code - ShellCheck code number. + * @returns The edit, or `undefined` when the line above already disables `code`. + */ +export function disableDirectiveEdit( + targetLine: string, + previousLine: string | undefined, + code: number, +): DisableDirectiveEdit | undefined { + const indent = /^[ \t]*/.exec(targetLine)?.[0] ?? ''; + const name = `SC${code}`; + const existing = previousLine === undefined ? null : DISABLE_DIRECTIVE.exec(previousLine); + if (existing && existing[1] === indent) { + const codes = existing[2].split(',').map(c => c.trim().toUpperCase()); + if (codes.includes(name) || codes.includes(String(code))) return undefined; + return { kind: 'replacePrevious', text: `${indent}# shellcheck disable=${existing[2]},${name}` }; + } + return { kind: 'insert', text: `${indent}# shellcheck disable=${name}` }; +} diff --git a/tests/extension-host/suite/shellcheck.test.ts b/tests/extension-host/suite/shellcheck.test.ts new file mode 100644 index 00000000..c4011ae7 --- /dev/null +++ b/tests/extension-host/suite/shellcheck.test.ts @@ -0,0 +1,103 @@ +import * as assert from 'assert'; +import { execFileSync } from 'child_process'; +import * as path from 'path'; +import * as vscode from 'vscode'; + +const EXTENSION_ID = 'eFAILution.gitlab-component-helper'; + +// __dirname is /out-test/suite at runtime; fixtures live under tests/fixtures. +const FIXTURE = path.resolve(__dirname, '..', '..', 'tests', 'fixtures', 'shellcheck', '.gitlab-ci.yml'); +const QUICKFIX_FIXTURE = path.resolve(__dirname, '..', '..', 'tests', 'fixtures', 'shellcheck-quickfix', '.gitlab-ci.yml'); + +function shellcheckInstalled(): boolean { + try { + execFileSync('shellcheck', ['--version']); + return true; + } catch { + return false; + } +} + +async function waitForDiagnostics( + uri: vscode.Uri, + predicate: (diags: vscode.Diagnostic[]) => boolean, + timeoutMs = 10000 +): Promise { + const start = Date.now(); + let diags = vscode.languages.getDiagnostics(uri); + while (Date.now() - start < timeoutMs) { + diags = vscode.languages.getDiagnostics(uri); + if (predicate(diags)) return diags; + await new Promise((resolve) => setTimeout(resolve, 100)); + } + return diags; +} + +const shellcheck = (diags: vscode.Diagnostic[]) => diags.filter((d) => d.source === 'shellcheck'); + +const codeOf = (d: vscode.Diagnostic) => (typeof d.code === 'object' ? d.code.value : d.code); + +suite('ShellCheck diagnostics', function () { + suiteSetup(async function () { + if (!shellcheckInstalled()) this.skip(); + const ext = vscode.extensions.getExtension(EXTENSION_ID); + assert.ok(ext); + if (!ext.isActive) await ext.activate(); + await vscode.workspace.getConfiguration('gitlabComponentHelper.shellcheck') + .update('severity', 'info', vscode.ConfigurationTarget.Global); + }); + + suiteTeardown(async () => { + await vscode.workspace.getConfiguration('gitlabComponentHelper.shellcheck') + .update('severity', undefined, vscode.ConfigurationTarget.Global); + }); + + test('reports findings on the script line and skips variables defined in the file', async () => { + const doc = await vscode.workspace.openTextDocument(vscode.Uri.file(FIXTURE)); + await vscode.window.showTextDocument(doc); + + const diags = shellcheck(await waitForDiagnostics(doc.uri, (d) => shellcheck(d).some((x) => codeOf(x) === 'SC2086'))); + const summary = JSON.stringify(diags.map((d) => ({ code: codeOf(d), line: d.range.start.line, msg: d.message }))); + + const unquoted = diags.find((d) => codeOf(d) === 'SC2086'); + assert.ok(unquoted, `expected SC2086. Got: ${summary}`); + assert.strictEqual(doc.getText(unquoted.range), '$unquoted_value'); + + assert.ok(diags.some((d) => codeOf(d) === 'SC2154' && /unquoted_value/.test(d.message)), summary); + assert.ok(!diags.some((d) => /known_var/.test(d.message)), `known_var comes from variables:. Got: ${summary}`); + }); + + test('ignores constant comparisons of inputs and offers disable fixes where they reach ShellCheck', async () => { + const doc = await vscode.workspace.openTextDocument(vscode.Uri.file(QUICKFIX_FIXTURE)); + await vscode.window.showTextDocument(doc); + const onVariable = (name: string) => (d: vscode.Diagnostic) => codeOf(d) === 'SC2086' && doc.getText(d.range) === name; + + try { + const diags = shellcheck(await waitForDiagnostics(doc.uri, (d) => shellcheck(d).filter((x) => codeOf(x) === 'SC2086').length === 2)); + const summary = JSON.stringify(diags.map((d) => ({ code: codeOf(d), line: d.range.start.line }))); + assert.ok(!diags.some((d) => codeOf(d) === 'SC2050'), `the $[[ ]] comparison is deliberate. Got: ${summary}`); + + // The command drops each action's diagnostics, so match on the code in the title. + const actionsFor = async (diagnostic: vscode.Diagnostic) => (await vscode.commands.executeCommand( + 'vscode.executeCodeActionProvider', doc.uri, diagnostic.range, vscode.CodeActionKind.QuickFix.value, + )).filter((a) => a.title.includes('SC2086')); + + const plain = diags.find(onVariable('$plain_value')); + assert.ok(plain, summary); + assert.deepStrictEqual((await actionsFor(plain)).map((a) => a.title), ['Ignore SC2086 in workspace settings']); + + const block = diags.find(onVariable('$block_value')); + assert.ok(block, summary); + const disable = (await actionsFor(block)).find((a) => a.title === 'Disable SC2086 for this command'); + assert.ok(disable?.edit, 'expected a disable action for the | block finding'); + assert.ok(await vscode.workspace.applyEdit(disable.edit)); + assert.strictEqual(doc.lineAt(block.range.start.line).text, ' # shellcheck disable=SC2086'); + + const after = shellcheck(await waitForDiagnostics(doc.uri, (d) => !shellcheck(d).some(onVariable('$block_value')))); + assert.ok(!after.some(onVariable('$block_value')), 'the directive reaches ShellCheck'); + assert.ok(after.some(onVariable('$plain_value')), 'other findings stay'); + } finally { + await vscode.commands.executeCommand('workbench.action.files.revert'); + } + }); +}); diff --git a/tests/fixtures/shellcheck-quickfix/.gitlab-ci.yml b/tests/fixtures/shellcheck-quickfix/.gitlab-ci.yml new file mode 100644 index 00000000..ba6077f1 --- /dev/null +++ b/tests/fixtures/shellcheck-quickfix/.gitlab-ci.yml @@ -0,0 +1,8 @@ +build: + script: + - | + if [ "$[[ inputs.mode ]]" == "fast" ]; then + echo fast + fi + echo $block_value + - echo $plain_value diff --git a/tests/fixtures/shellcheck/.gitlab-ci.yml b/tests/fixtures/shellcheck/.gitlab-ci.yml new file mode 100644 index 00000000..2a90599c --- /dev/null +++ b/tests/fixtures/shellcheck/.gitlab-ci.yml @@ -0,0 +1,7 @@ +variables: + known_var: from-yaml + +build: + script: + - echo $unquoted_value + - echo "$known_var" diff --git a/tests/unit/scriptVariables.test.ts b/tests/unit/scriptVariables.test.ts new file mode 100644 index 00000000..74326f0d --- /dev/null +++ b/tests/unit/scriptVariables.test.ts @@ -0,0 +1,71 @@ +// @mocha +/** + * Tests src/utils/scriptVariables.ts — which variables a job's shell receives from the CI file, and matching + * user-configured names or globs. + */ + +import * as assert from 'node:assert/strict'; +import { isMap, parseDocument, type YAMLMap } from 'yaml'; +import { collectKnownVariables, isKnownVariable } from '../../src/utils/scriptVariables'; + +function root(source: string): YAMLMap { + const contents = parseDocument(source).contents; + assert.ok(isMap(contents)); + return contents; +} + +function job(topLevel: YAMLMap, name: string): YAMLMap { + const node = topLevel.get(name, true); + assert.ok(isMap(node)); + return node; +} + +suite('collectKnownVariables', () => { + const source = [ + 'variables:', + ' global_var: a', + '.base:', + ' variables:', + ' base_var:', + ' value: b', + ' description: from a template', + 'build:', + ' extends: .base', + ' variables:', + ' job_var: c', + ' rules:', + ' - if: $CI_COMMIT_TAG', + ' variables:', + ' rule_var: d', + ' parallel:', + ' matrix:', + ' - matrix_var: [x, y]', + 'other:', + ' variables:', + ' other_var: e', + ].join('\n'); + + test('includes global, own, extends, rules and matrix variables for a job', () => { + const topLevel = root(source); + const names = collectKnownVariables(topLevel, job(topLevel, 'build')); + assert.deepEqual([...names].sort(), ['base_var', 'global_var', 'job_var', 'matrix_var', 'rule_var']); + }); + + test('includes only global variables outside a job', () => { + assert.deepEqual([...collectKnownVariables(root(source), undefined)], ['global_var']); + }); + + test('survives an extends cycle', () => { + const topLevel = root('.a:\n extends: .b\n variables: { a_var: 1 }\n.b:\n extends: .a\n variables: { b_var: 1 }\n'); + assert.deepEqual([...collectKnownVariables(topLevel, job(topLevel, '.a'))].sort(), ['a_var', 'b_var']); + }); +}); + +suite('isKnownVariable', () => { + test('matches collected names and configured globs', () => { + const known = new Set(['from_file']); + assert.equal(isKnownVariable('from_file', known, []), true); + assert.equal(isKnownVariable('deploy_token', known, ['deploy_*']), true); + assert.equal(isKnownVariable('unknown', known, ['deploy_*']), false); + }); +}); diff --git a/tests/unit/shellScriptExtractor.test.ts b/tests/unit/shellScriptExtractor.test.ts new file mode 100644 index 00000000..a0fae060 --- /dev/null +++ b/tests/unit/shellScriptExtractor.test.ts @@ -0,0 +1,251 @@ +// @mocha +/** + * Tests src/utils/shellScriptExtractor.ts — which YAML keys count as job shell, how blocks share a shell, and that + * every content character maps back to its source offset across scalar styles. + */ + +import * as assert from 'node:assert/strict'; +import { extractLintUnits, maskComponentInterpolation, type LintUnit } from '../../src/utils/shellScriptExtractor'; + +/** + * @param source - YAML text. + * @param unit - A unit extracted from it. + * @param needle - Text expected once in the unit's content. + * @returns The source text at the offsets of `needle`'s first and last characters, inclusive. + */ +function sourceOf(source: string, unit: LintUnit, needle: string): string { + const index = unit.content.indexOf(needle); + assert.notEqual(index, -1, `'${needle}' not in content: ${JSON.stringify(unit.content)}`); + return source.slice(unit.offsets[index], unit.offsets[index + needle.length - 1] + 1); +} + +function only(units: LintUnit[]): LintUnit { + assert.equal(units.length, 1, `expected one unit, got ${units.map(u => JSON.stringify(u.content)).join(', ')}`); + return units[0]; +} + +suite('extractLintUnits: job-level rule', () => { + test('ignores a spec input named script in a component template', () => { + const source = [ + 'spec:', + ' inputs:', + ' script:', + ' description: not shell', + ' type: string', + '---', + 'build:', + ' script:', + ' - echo "real script"', + ].join('\n'); + const unit = only(extractLintUnits(source)); + assert.equal(unit.content, 'echo "real script"\n'); + }); + + test('ignores script keys under include inputs and variables', () => { + const source = [ + 'include:', + ' - component: example.com/group/project/thing@1.0.0', + ' inputs:', + ' script: echo not-linted', + 'variables:', + ' script: echo not-linted', + ].join('\n'); + assert.deepEqual(extractLintUnits(source), []); + }); + + test('ignores script keys nested deeper inside a job', () => { + const source = ['build:', ' trigger:', ' script: echo not-linted', ' script: echo linted'].join('\n'); + assert.equal(only(extractLintUnits(source)).content, 'echo linted\n'); + }); + + test('lints hidden jobs, interpolated job names, default and legacy globals', () => { + const source = [ + 'before_script: echo global', + 'default:', + ' after_script: echo default', + '.template:', + ' script: echo hidden', + '$[[ inputs.job_name ]]:', + ' script: echo interpolated', + ].join('\n'); + // The legacy global before_script prefixes each job as unreportable context. + const contents = extractLintUnits(source).map(unit => unit.content); + assert.deepEqual(contents, [ + 'echo global\n', + 'echo default\n', + 'echo global\necho hidden\n', + 'echo global\necho interpolated\n', + ]); + }); + + test('skips a document that fails to parse', () => { + assert.deepEqual(extractLintUnits('build:\n script: [unterminated\n'), []); + }); + + test('lints a file whose jobs use several merge keys', () => { + const source = [ + '.base: &base', + ' stage: deploy', + '.extra: &extra', + ' when: manual', + 'rollout:', + ' <<: *base', + ' <<: *extra', + ' script: echo $rollout', + ].join('\n'); + assert.deepEqual(extractLintUnits(source).map(unit => unit.content), ['echo $rollout\n']); + }); +}); + +suite('extractLintUnits: shell boundaries', () => { + test('joins sequence items, flattening nested sequences', () => { + const source = ['build:', ' script:', ' - echo one', ' - - echo two', ' - echo three'].join('\n'); + assert.equal(only(extractLintUnits(source)).content, 'echo one\necho two\necho three\n'); + }); + + test('skips !reference tags and aliases', () => { + const source = [ + '.shared: &shared echo anchored', + 'build:', + ' script:', + ' - !reference [.other, script]', + ' - *shared', + ' - echo kept', + ].join('\n'); + assert.equal(only(extractLintUnits(source)).content, 'echo kept\n'); + }); + + test('puts a job before_script and script in one unit, after_script in its own', () => { + const source = [ + 'build:', + ' before_script: setup=1', + ' script: echo "$setup"', + ' after_script: echo done', + ].join('\n'); + const units = extractLintUnits(source); + assert.deepEqual(units.map(u => u.content), ['setup=1\necho "$setup"\n', 'echo done\n']); + assert.ok(units[0].segments.every(s => s.reportable)); + }); + + test('prefixes an inherited default before_script as unreportable context', () => { + const source = ['default:', ' before_script: setup=1', 'build:', ' script: echo "$setup"'].join('\n'); + const [defaults, job] = extractLintUnits(source); + assert.equal(defaults.content, 'setup=1\n'); + assert.equal(defaults.continuesInScript, true); + assert.equal(job.content, 'setup=1\necho "$setup"\n'); + assert.deepEqual(job.segments.map(s => s.reportable), [false, true]); + assert.equal(job.continuesInScript, false); + }); + + test('prefers a same-file extends template before_script over default', () => { + const source = [ + 'default:', + ' before_script: from_default=1', + '.template:', + ' before_script: from_template=1', + 'build:', + ' extends: .template', + ' script: echo hi', + ].join('\n'); + const job = extractLintUnits(source).find(u => u.content.endsWith('echo hi\n')); + assert.equal(job?.content, 'from_template=1\necho hi\n'); + }); + + test('honours inherit:default false', () => { + const source = [ + 'default:', + ' before_script: setup=1', + 'build:', + ' inherit:', + ' default: false', + ' script: echo hi', + ].join('\n'); + assert.equal(extractLintUnits(source)[1].content, 'echo hi\n'); + }); +}); + +suite('extractLintUnits: source offsets', () => { + test('maps literal block lines, including extra indentation', () => { + const source = ['build:', ' script:', ' - |', ' echo $first', ' echo $second'].join('\n'); + const unit = only(extractLintUnits(source)); + assert.equal(sourceOf(source, unit, '$first'), '$first'); + assert.equal(sourceOf(source, unit, '$second'), '$second'); + }); + + test('maps single- and double-quoted scalars, including escapes', () => { + const source = ['build:', ' script:', " - 'it''s $single'", ' - "say \\"hi\\" $double"'].join('\n'); + const unit = only(extractLintUnits(source)); + assert.equal(sourceOf(source, unit, '$single'), '$single'); + assert.equal(sourceOf(source, unit, '$double'), '$double'); + assert.equal(sourceOf(source, unit, '"hi'), '\\"hi'); + }); + + test('maps multi-line plain and folded scalars to their own source lines', () => { + const source = [ + 'build:', + ' script:', + ' - echo $plain_one', + ' $plain_two', + ' - >', + ' echo $folded_one', + ' $folded_two', + ].join('\n'); + const unit = only(extractLintUnits(source)); + for (const name of ['$plain_one', '$plain_two', '$folded_one', '$folded_two']) { + assert.equal(sourceOf(source, unit, name), name); + } + }); + + test('maps an inline script value', () => { + const source = 'build:\n script: echo $inline\n'; + assert.equal(sourceOf(source, only(extractLintUnits(source)), '$inline'), '$inline'); + }); + + test('maps CRLF sources', () => { + const source = 'build:\r\n script:\r\n - |\r\n echo $one\r\n echo $two\r\n'; + const unit = only(extractLintUnits(source)); + assert.equal(sourceOf(source, unit, '$two'), '$two'); + }); +}); + +suite('maskComponentInterpolation', () => { + test('replaces interpolation with same-length underscores', () => { + const text = 'deploy --env $[[ inputs.env ]] --x "$[[ inputs.y | expand_vars ]]"'; + const masked = maskComponentInterpolation(text); + assert.equal(masked.length, text.length); + assert.ok(!masked.includes('$[[')); + assert.ok(masked.startsWith('deploy --env ____')); + }); + + test('is applied to extracted content without moving offsets', () => { + const source = 'build:\n script: echo $[[ inputs.name ]] $after\n'; + const unit = only(extractLintUnits(source)); + assert.ok(!unit.content.includes('$[[')); + assert.equal(sourceOf(source, unit, '$after'), '$after'); + }); + + test('records where each interpolation was masked', () => { + const source = 'build:\n script: echo $[[ inputs.a ]] x $[[ inputs.b ]]\n'; + const unit = only(extractLintUnits(source)); + assert.deepEqual( + unit.interpolations.map(range => source.slice(unit.offsets[range.start], unit.offsets[range.end - 1] + 1)), + ['$[[ inputs.a ]]', '$[[ inputs.b ]]'], + ); + }); +}); + +suite('extractLintUnits: literal blocks', () => { + test('records content from | blocks only', () => { + const source = [ + 'build:', + ' script:', + ' - echo plain', + ' - |', + ' echo literal', + ' - >', + ' echo folded', + ].join('\n'); + const unit = only(extractLintUnits(source)); + assert.deepEqual(unit.literalBlocks.map(range => unit.content.slice(range.start, range.end)), ['echo literal\n']); + }); +}); diff --git a/tests/unit/shellcheckOutput.test.ts b/tests/unit/shellcheckOutput.test.ts new file mode 100644 index 00000000..009726e0 --- /dev/null +++ b/tests/unit/shellcheckOutput.test.ts @@ -0,0 +1,173 @@ +// @mocha +/** + * Tests src/utils/shellcheckOutput.ts — argument building, `json1` parsing, GitLab false-positive filtering and + * mapping findings back to YAML offsets. ShellCheck output is hand-written, so no binary is needed. + */ + +import * as assert from 'node:assert/strict'; +import { extractLintUnits } from '../../src/utils/shellScriptExtractor'; +import { + buildShellcheckArgs, + disableDirectiveEdit, + filterGitLabFalsePositives, + mapToSource, + parseShellcheckJson, + type ShellcheckComment, +} from '../../src/utils/shellcheckOutput'; + +function comment(overrides: Partial): ShellcheckComment { + return { line: 1, endLine: 1, column: 1, endColumn: 2, level: 'warning', code: 2086, message: 'msg', ...overrides }; +} + +suite('buildShellcheckArgs', () => { + test('reads stdin as json1 with dialect and severity', () => { + assert.deepEqual(buildShellcheckArgs({ shell: 'sh', severity: 'info', exclude: [] }), [ + '--format=json1', '--shell=sh', '--severity=info', '-', + ]); + }); + + test('passes valid exclusions and drops anything else', () => { + const args = buildShellcheckArgs({ shell: 'bash', severity: 'warning', exclude: ['sc2086', '2034', '--x', 'SC1'] }); + assert.ok(args.includes('--exclude=SC2086,2034')); + assert.equal(args.length, 5); + }); +}); + +suite('parseShellcheckJson', () => { + test('returns well-formed comments', () => { + const stdout = JSON.stringify({ comments: [comment({ code: 2154 }), { line: 'bad' }] }); + assert.deepEqual(parseShellcheckJson(stdout).map(c => c.code), [2154]); + }); + + test('returns nothing for malformed output', () => { + assert.deepEqual(parseShellcheckJson('not json'), []); + assert.deepEqual(parseShellcheckJson('[]'), []); + }); +}); + +suite('filterGitLabFalsePositives', () => { + const source = [ + 'variables:', + ' from_yaml: a', + 'build:', + ' script: echo "$from_yaml $deploy_key $missing"', + ].join('\n'); + const unit = extractLintUnits(source)[0]; + const unassigned = (name: string) => comment({ code: 2154, message: `${name} is referenced but not assigned.` }); + + test('drops SC2154 for variables from the file or configured patterns', () => { + const kept = filterGitLabFalsePositives( + unit, + [unassigned('from_yaml'), unassigned('deploy_key'), unassigned('missing'), comment({ code: 2086 })], + ['deploy_*'], + ); + assert.deepEqual(kept.map(c => c.message), ['missing is referenced but not assigned.', 'msg']); + }); + + test('keeps SC2154 whose message does not name a variable', () => { + assert.equal(filterGitLabFalsePositives(unit, [comment({ code: 2154, message: 'other' })], []).length, 1); + }); + + test('drops SC2034 only in a lone before_script', () => { + const units = extractLintUnits('default:\n before_script: x=1\nbuild:\n script: x=1\n'); + const unused = comment({ code: 2034 }); + assert.equal(filterGitLabFalsePositives(units[0], [unused], []).length, 0); + assert.equal(filterGitLabFalsePositives(units[1], [unused], []).length, 1); + }); + + test('drops constant-expression findings only on lines with an interpolation', () => { + const interpolated = extractLintUnits([ + 'build:', + ' script:', + ' - |', + ' if [ "$[[ inputs.mode ]]" == "fast" ]; then', + ' echo $unquoted', + ' fi', + ' if [ "literal" == "fast" ]; then echo; fi', + ].join('\n'))[0]; + const findings = [ + comment({ line: 1, code: 2050 }), + comment({ line: 1, code: 2086 }), + comment({ line: 2, code: 2157 }), + comment({ line: 4, code: 2050 }), + ]; + assert.deepEqual( + filterGitLabFalsePositives(interpolated, findings, []).map(c => `${c.line}:${c.code}`), + ['1:2086', '2:2157', '4:2050'], + ); + }); +}); + +suite('disableDirectiveEdit', () => { + test('inserts a directive at the command line indent', () => { + assert.deepEqual(disableDirectiveEdit(' if [ x ]; then', ' - |', 2050), { + kind: 'insert', + text: ' # shellcheck disable=SC2050', + }); + }); + + test('appends to a directive directly above at the same indent', () => { + assert.deepEqual(disableDirectiveEdit(' echo $x', ' # shellcheck disable=SC2086', 2154), { + kind: 'replacePrevious', + text: ' # shellcheck disable=SC2086,SC2154', + }); + }); + + test('does nothing when the code is already disabled', () => { + assert.equal(disableDirectiveEdit(' echo $x', ' # shellcheck disable=SC2034,2086', 2086), undefined); + }); + + test('inserts rather than appending to a directive at another indent', () => { + assert.equal(disableDirectiveEdit(' echo $x', ' # shellcheck disable=SC2086', 2154)?.kind, 'insert'); + }); +}); + +suite('mapToSource', () => { + test('positions a finding on the YAML source span', () => { + const source = 'build:\n script:\n - echo ok\n - echo $value\n'; + const unit = extractLintUnits(source)[0]; + // Content is "echo ok\necho $value\n"; `$value` is line 2, columns 6-12. + const [finding] = mapToSource(unit, [comment({ line: 2, endLine: 2, column: 6, endColumn: 12 })]); + assert.equal(source.slice(finding.start, finding.end), '$value'); + }); + + test('drops findings inside an inherited before_script', () => { + const source = 'default:\n before_script: echo $a\nbuild:\n script: echo $b\n'; + const job = extractLintUnits(source)[1]; + assert.equal(mapToSource(job, [comment({ line: 1, column: 6, endColumn: 8 })]).length, 0); + const [kept] = mapToSource(job, [comment({ line: 2, endLine: 2, column: 6, endColumn: 8 })]); + assert.equal(source.slice(kept.start, kept.end), '$b'); + }); + + test('clips a range that runs past its segment and ignores lines that do not exist', () => { + const source = 'build:\n script: echo $tail\n'; + const unit = extractLintUnits(source)[0]; + const [finding] = mapToSource(unit, [comment({ line: 1, endLine: 9, column: 6, endColumn: 1 })]); + assert.ok(source.slice(finding.start, finding.end).startsWith('$tail')); + assert.equal(mapToSource(unit, [comment({ line: 9 })]).length, 0); + }); + + test('gives a directive position only inside a literal block, at the start of the command', () => { + const source = [ + 'build:', + ' script:', + ' - echo $plain', + ' - |', + ' apt-get install \\', + ' $package', + ' - >', + ' echo $folded', + ].join('\n'); + const unit = extractLintUnits(source)[0]; + // Content lines: 1 "echo $plain", 2 "apt-get install \", 3 " $package", 4 "echo $folded". + const [plain, continued, folded] = mapToSource(unit, [ + comment({ line: 1, endLine: 1, column: 6, endColumn: 12 }), + comment({ line: 3, endLine: 3, column: 3, endColumn: 11 }), + comment({ line: 4, endLine: 4, column: 6, endColumn: 13 }), + ]); + assert.equal(plain.directiveOffset, undefined); + assert.equal(folded.directiveOffset, undefined); + assert.ok(continued.directiveOffset !== undefined); + assert.ok(source.slice(continued.directiveOffset).startsWith('apt-get install')); + }); +});