@opensip-cli/checks-typescript 0.1.0

package/dist/checks/quality/stubbed-implementation-detection.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview Stubbed Implementation Detection Check
+ *
+ * Detects patterns indicating incomplete or placeholder implementations:
+ * - Empty object stubs: `({}) as Type`
+ * - Promise.resolve() placeholders
+ * - Hardcoded stub returns
+ * - Placeholder comments
+ *
+ * False-positive reduction: the check walks the AST for context to skip:
+ *   - Promise.resolve() in lifecycle methods (destroy/dispose/close/shutdown/cleanup)
+ *   - Promise.resolve() inside conditional blocks (guard clauses)
+ *   - Promise.resolve() in functions with substantive statements
+ *   - { success: true, data: [] } inside conditional branches or functions with multiple returns
+ *   - ({}) as T where T is a generic type parameter
+ *   - ({}) as T used as Proxy target
+ */
+/**
+ * Check: quality/stubbed-implementation-detection
+ *
+ * Detects incomplete or placeholder implementations.
+ */
+export declare const stubbedImplementationDetection: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=stubbed-implementation-detection.d.ts.map

package/dist/checks/quality/stubbed-implementation-detection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubbed-implementation-detection.d.ts","sourceRoot":"","sources":["../../../src/checks/quality/stubbed-implementation-detection.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAgUH;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,sCA8EzC,CAAC"}

package/dist/checks/quality/stubbed-implementation-detection.js

@@ -0,0 +1,355 @@
+// @fitness-ignore-file unused-config-options -- Config options reserved for future use or environment-specific
+// @fitness-ignore-file stubbed-implementation-detection -- longDescription documents the patterns this check detects, triggering self-detection
+/**
+ * @fileoverview Stubbed Implementation Detection Check
+ *
+ * Detects patterns indicating incomplete or placeholder implementations:
+ * - Empty object stubs: `({}) as Type`
+ * - Promise.resolve() placeholders
+ * - Hardcoded stub returns
+ * - Placeholder comments
+ *
+ * False-positive reduction: the check walks the AST for context to skip:
+ *   - Promise.resolve() in lifecycle methods (destroy/dispose/close/shutdown/cleanup)
+ *   - Promise.resolve() inside conditional blocks (guard clauses)
+ *   - Promise.resolve() in functions with substantive statements
+ *   - { success: true, data: [] } inside conditional branches or functions with multiple returns
+ *   - ({}) as T where T is a generic type parameter
+ *   - ({}) as T used as Proxy target
+ */
+import { defineCheck, isTestFile } from '@opensip-cli/fitness';
+import { findEnclosingFunctionBody, getEnclosingFunctionName, getSharedSourceFile, isInsideConditionalBlock, } from '@opensip-cli/lang-typescript';
+import * as ts from 'typescript';
+/** Placeholder comment patterns - using explicit RegExp constructors for safety */
+const PLACEHOLDER_PATTERNS = [
+    new RegExp(String.raw `\/\/\s*Placeholder\s*(implementation|for|:|-)`, 'i'),
+    new RegExp(String.raw `\/\/\s*STUB\s*[:|-]`, 'i'),
+    new RegExp(String.raw `\/\/\s*Not\s+implemented`, 'i'),
+];
+/** Primitive types that should be skipped when checking empty object stubs */
+const PRIMITIVE_TYPES = new Set([
+    'string',
+    'number',
+    'boolean',
+    'null',
+    'undefined',
+    'void',
+    'never',
+    'unknown',
+]);
+/** Pattern for Promise.resolve stubs - matches exact form without backtracking */
+const PROMISE_RESOLVE_PATTERN = new RegExp(String.raw `^Promise\.resolve\((undefined|null|void 0)?\)$`);
+/** Pattern for hardcoded stub returns with success: true */
+const STUB_RETURN_PATTERN = new RegExp(String.raw `success:\s*true[\s\S]*data:\s*(\[\]|null|\{\})`, 'i');
+/** Lifecycle teardown method names that commonly return Promise.resolve() */
+const LIFECYCLE_METHOD_NAMES = new Set(['destroy', 'dispose', 'close', 'shutdown', 'cleanup']);
+// =============================================================================
+// AST HELPER UTILITIES
+// =============================================================================
+// Function-scope helpers (findEnclosingFunctionBody, getEnclosingFunctionName,
+// isInsideConditionalBlock) are imported from @opensip-cli/lang-typescript.
+/**
+ * Check whether a function body contains substantive statements beyond a single return.
+ * "Substantive" means assignments, method calls, logging, variable declarations with initializers, etc.
+ */
+function functionBodyHasSubstantiveStatements(body, returnNode) {
+    for (const stmt of body.statements) {
+        // Skip the return statement itself
+        if (stmt === returnNode)
+            continue;
+        // Skip variable declarations without initializers (just type annotations)
+        if (ts.isVariableStatement(stmt)) {
+            const hasInitializer = stmt.declarationList.declarations.some((d) => d.initializer !== undefined);
+            if (hasInitializer)
+                return true;
+            continue;
+        }
+        // Any other statement (expression statement, if, for, etc.) is substantive
+        return true;
+    }
+    return false;
+}
+/**
+ * Recursively check if a node contains an await or call expression before a given position.
+ */
+function containsAwaitOrCallBefore(node, returnPos) {
+    if (node.getStart() >= returnPos)
+        return false;
+    if (ts.isAwaitExpression(node))
+        return true;
+    if (ts.isCallExpression(node) && node.getStart() < returnPos)
+        return true;
+    let found = false;
+    ts.forEachChild(node, (child) => {
+        if (!found && containsAwaitOrCallBefore(child, returnPos)) {
+            found = true;
+        }
+    });
+    return found;
+}
+function functionBodyHasAwaitOrCallsBefore(body, returnNode) {
+    const returnPos = returnNode.getStart();
+    for (const stmt of body.statements) {
+        if (stmt === returnNode)
+            break;
+        if (containsAwaitOrCallBefore(stmt, returnPos))
+            return true;
+    }
+    return false;
+}
+/**
+ * Check whether the function has multiple return statements (indicating branches, not a stub).
+ */
+function functionHasMultipleReturns(body) {
+    let returnCount = 0;
+    const visit = (node) => {
+        if (ts.isReturnStatement(node)) {
+            returnCount++;
+        }
+        // Do not descend into nested functions
+        if (ts.isFunctionDeclaration(node) ||
+            ts.isFunctionExpression(node) ||
+            ts.isArrowFunction(node) ||
+            ts.isMethodDeclaration(node)) {
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    for (const stmt of body.statements) {
+        visit(stmt);
+    }
+    return returnCount > 1;
+}
+/**
+ * Check whether a node's type parameters include the given type name.
+ */
+function nodeHasTypeParameter(node, typeText, sourceFile) {
+    if (!node.typeParameters)
+        return false;
+    return node.typeParameters.some((tp) => tp.name.getText(sourceFile) === typeText);
+}
+/**
+ * Check whether the type in an as-expression refers to a generic type parameter
+ * rather than a concrete type. Walks up the AST to find enclosing function/class
+ * type parameters and checks if the cast target matches one.
+ */
+function isGenericTypeParameter(typeText, node, sourceFile) {
+    let current = node.parent;
+    while (!ts.isSourceFile(current)) {
+        // Check function-like or class declarations for type parameters
+        if ((ts.isFunctionDeclaration(current) ||
+            ts.isMethodDeclaration(current) ||
+            ts.isFunctionExpression(current) ||
+            ts.isArrowFunction(current) ||
+            ts.isClassDeclaration(current)) &&
+            nodeHasTypeParameter(current, typeText, sourceFile)) {
+            return true;
+        }
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Check whether the as-expression is the target argument of a `new Proxy(...)` call.
+ */
+function isProxyTarget(node, sourceFile) {
+    const parent = node.parent;
+    // Direct parent should be a NewExpression: new Proxy({} as T, handler)
+    if (ts.isNewExpression(parent)) {
+        const exprText = parent.expression.getText(sourceFile);
+        if (exprText === 'Proxy' && parent.arguments?.[0] === node) {
+            return true;
+        }
+    }
+    // Or it could be wrapped in parentheses: new Proxy(({} as T), handler)
+    if (ts.isParenthesizedExpression(parent)) {
+        return isProxyTarget(parent, sourceFile);
+    }
+    return false;
+}
+// =============================================================================
+// CHECK FUNCTIONS
+// =============================================================================
+function checkEmptyObjectStub(options) {
+    const { node, sourceFile } = options;
+    if (!ts.isAsExpression(node) && !ts.isTypeAssertionExpression(node))
+        return null;
+    const expression = node.expression;
+    if (!ts.isObjectLiteralExpression(expression) || expression.properties.length > 0)
+        return null;
+    const typeText = node.type.getText(sourceFile);
+    // Skip primitives and Record types
+    const isPrimitive = PRIMITIVE_TYPES.has(typeText);
+    const isRecordType = typeText.startsWith('Record<') && typeText.endsWith('>');
+    if (isPrimitive || isRecordType)
+        return null;
+    // Skip if type is a generic type parameter (e.g., T in deepMerge<T>)
+    if (isGenericTypeParameter(typeText, node, sourceFile))
+        return null;
+    // Skip if this is the target of a new Proxy(...) call
+    if (isProxyTarget(node, sourceFile))
+        return null;
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    const lineNum = line + 1;
+    const matchText = node.getText(sourceFile);
+    return {
+        line: lineNum,
+        column: character + 1,
+        message: `Empty object stub: ({}) as ${typeText} - will crash at runtime`,
+        severity: 'error',
+        suggestion: `Implement the actual ${typeText} object with all required properties, or use a factory function/builder to create valid instances`,
+        match: matchText,
+    };
+}
+function checkPromiseResolveStub(options) {
+    const { node, sourceFile } = options;
+    if (!ts.isReturnStatement(node) || !node.expression || !ts.isCallExpression(node.expression))
+        return null;
+    const callText = node.expression.getText(sourceFile);
+    if (!PROMISE_RESOLVE_PATTERN.test(callText))
+        return null;
+    // Skip if inside a conditional block (guard clause / early return)
+    if (isInsideConditionalBlock(node))
+        return null;
+    // Skip if enclosing function is a lifecycle teardown method
+    const funcName = getEnclosingFunctionName(node, sourceFile);
+    if (funcName && LIFECYCLE_METHOD_NAMES.has(funcName))
+        return null;
+    // Skip if the function body has substantive statements (real work + async wrapping)
+    const body = findEnclosingFunctionBody(node);
+    if (body && functionBodyHasSubstantiveStatements(body, node))
+        return null;
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    return {
+        line: line + 1,
+        column: character + 1,
+        message: 'Placeholder return: Promise.resolve() - method does nothing',
+        severity: 'error',
+        suggestion: 'Implement the actual async logic for this method, or if this is intentional no-op, add a comment explaining why',
+        match: callText,
+    };
+}
+function checkHardcodedStubReturn(options) {
+    const { node, sourceFile } = options;
+    if (!ts.isReturnStatement(node) ||
+        !node.expression ||
+        !ts.isObjectLiteralExpression(node.expression))
+        return null;
+    const returnText = node.expression.getText(sourceFile);
+    if (!STUB_RETURN_PATTERN.test(returnText))
+        return null;
+    // Skip if inside a conditional block (branch return, not the only path)
+    if (isInsideConditionalBlock(node))
+        return null;
+    // Skip if the function has multiple return statements (indicates branching logic)
+    const body = findEnclosingFunctionBody(node);
+    if (body && functionHasMultipleReturns(body))
+        return null;
+    // Skip if the function body contains await expressions or calls before this return
+    if (body && functionBodyHasAwaitOrCallsBefore(body, node))
+        return null;
+    const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+    return {
+        line: line + 1,
+        column: character + 1,
+        message: 'Hardcoded stub return: { success: true, data: [] }',
+        severity: 'warning',
+        suggestion: 'Replace this stub with actual implementation that fetches/processes real data',
+        match: returnText.slice(0, 80),
+    };
+}
+function checkLineForPlaceholder(line, lineNum) {
+    for (const pattern of PLACEHOLDER_PATTERNS) {
+        if (pattern.test(line)) {
+            return {
+                line: lineNum,
+                column: 0,
+                message: 'Placeholder comment indicates unfinished implementation',
+                severity: 'warning',
+                suggestion: 'Complete the implementation or create a ticket to track this work, then remove the placeholder comment',
+                match: line.trim(),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Check: quality/stubbed-implementation-detection
+ *
+ * Detects incomplete or placeholder implementations.
+ */
+export const stubbedImplementationDetection = defineCheck({
+    id: '12218d58-5dea-4aba-ba7b-fc1822d03ec4',
+    slug: 'stubbed-implementation-detection',
+    scope: { languages: ['typescript'], concerns: ['backend', 'frontend', 'cli'] },
+    contentFilter: 'raw',
+    confidence: 'high',
+    description: 'Detects incomplete/placeholder implementations',
+    longDescription: `**Purpose:** Detects incomplete or placeholder implementations that will fail at runtime or silently do nothing.
+
+**Detects:**
+- Empty object stubs: \`({}) as Type\` where Type is not a primitive or Record (will crash at runtime)
+- Placeholder returns: \`return Promise.resolve(undefined|null|void 0)\` indicating a no-op async method
+- Hardcoded stub returns: \`return { success: true, data: []|null|{} }\` patterns
+- Placeholder comments: \`// Placeholder implementation\`, \`// STUB:\`, \`// Not implemented\`
+
+**Skips (not false positives):**
+- Test files (\`*.test.ts\`, files under \`__tests__/\`, \`__fixtures__/\`) — stub patterns in tests are intentional
+- Promise.resolve() in lifecycle methods (destroy, dispose, close, shutdown, cleanup)
+- Promise.resolve() inside conditional blocks (guard clauses)
+- Promise.resolve() in functions with substantive statements (real synchronous work)
+- Hardcoded stub returns inside conditional branches or functions with multiple returns
+- Hardcoded stub returns in functions with await/call expressions before the return
+- \`({}) as T\` where T is a generic type parameter
+- \`({}) as T\` used as a Proxy target
+
+**Why it matters:** Stubbed implementations pass type checks but fail at runtime. Detecting them early prevents production crashes and silent data loss.
+
+**Scope:** General best practice. Analyzes each file individually (\`analyze\`). Uses TypeScript AST parsing on production files (excludes tests and fixtures).`,
+    tags: ['quality', 'code-quality', 'best-practices'],
+    fileTypes: ['ts', 'tsx'],
+    analyze(content, filePath) {
+        const violations = [];
+        // Test files routinely use stub patterns (empty type-asserted objects,
+        // Promise.resolve()) as intentional fixtures or compile-time drift
+        // detectors. Skip AST stub detection in tests; placeholder-comment
+        // scanning below is also already test-aware.
+        const inTestFile = isTestFile(filePath);
+        try {
+            const sourceFile = getSharedSourceFile(filePath, content);
+            if (!sourceFile)
+                return [];
+            const visit = (node) => {
+                const nodeOptions = { node, sourceFile };
+                if (!inTestFile) {
+                    const emptyStub = checkEmptyObjectStub(nodeOptions);
+                    if (emptyStub)
+                        violations.push(emptyStub);
+                    const promiseStub = checkPromiseResolveStub(nodeOptions);
+                    if (promiseStub)
+                        violations.push(promiseStub);
+                    const hardcodedStub = checkHardcodedStubReturn(nodeOptions);
+                    if (hardcodedStub)
+                        violations.push(hardcodedStub);
+                }
+                ts.forEachChild(node, visit);
+            };
+            visit(sourceFile);
+            // Check for placeholder comments (skip test files — placeholder comments
+            // in tests are intentional)
+            if (!isTestFile(filePath)) {
+                const lines = content.split('\n');
+                for (const [i, line] of lines.entries()) {
+                    const placeholder = checkLineForPlaceholder(line ?? '', i + 1);
+                    if (placeholder)
+                        violations.push(placeholder);
+                }
+            }
+        }
+        catch {
+            // @swallow-ok Skip files that fail to parse
+        }
+        return violations;
+    },
+});
+//# sourceMappingURL=stubbed-implementation-detection.js.map

package/dist/checks/quality/stubbed-implementation-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubbed-implementation-detection.js","sourceRoot":"","sources":["../../../src/checks/quality/stubbed-implementation-detection.ts"],"names":[],"mappings":"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"}

package/dist/checks/quality/unused-config-options.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Unused Configuration Options Check
+ *
+ * Detects configuration properties that are defined but never accessed.
+ */
+/**
+ * Check: quality/unused-config-options
+ *
+ * Detects configuration properties defined but never accessed.
+ */
+export declare const unusedConfigOptions: import("@opensip-cli/fitness").Check;
+//# sourceMappingURL=unused-config-options.d.ts.map

package/dist/checks/quality/unused-config-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unused-config-options.d.ts","sourceRoot":"","sources":["../../../src/checks/quality/unused-config-options.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AA0PH;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,sCA2B9B,CAAC"}

package/dist/checks/quality/unused-config-options.js

@@ -0,0 +1,245 @@
+// @fitness-ignore-file toctou-race-condition -- TOCTOU acceptable in this non-concurrent context
+// @fitness-ignore-file unused-config-options -- Config options reserved for future use or environment-specific
+/**
+ * @fileoverview Unused Configuration Options Check
+ *
+ * Detects configuration properties that are defined but never accessed.
+ */
+import { logger } from '@opensip-cli/core';
+import { defineCheck } from '@opensip-cli/fitness';
+import { getSharedSourceFile } from '@opensip-cli/lang-typescript';
+import * as ts from 'typescript';
+/**
+ * Common property names that are ubiquitous and would cause false positives
+ */
+const COMMON_PROPERTY_NAMES = new Set([
+    // Very common config properties used everywhere
+    'enabled',
+    'disabled',
+    'timeout',
+    'retries',
+    'debug',
+    'verbose',
+    'name',
+    'type',
+    'id',
+    'key',
+    'value',
+    'data',
+    'options',
+    'config',
+    'settings',
+    'port',
+    'host',
+    'url',
+    'path',
+    'level',
+    'mode',
+]);
+/**
+ * Paths where this check should not run (CLI, scripts, test utilities)
+ */
+const NON_CONFIG_CONSUMER_PATTERNS = [
+    /\/cli\//,
+    /\/scripts\//,
+    /\/bin\//,
+    /__tests__\//,
+    /\.test\./,
+    /\.spec\./,
+    /\/testing\//,
+    // Type definition files only
+    /types\.ts$/,
+    /interfaces\.ts$/,
+    /index\.d\.ts$/,
+];
+/**
+ * Check if a path should be excluded from analysis
+ */
+function shouldExcludePath(filePath) {
+    return NON_CONFIG_CONSUMER_PATTERNS.some((pattern) => pattern.test(filePath));
+}
+/**
+ * Check if interface is a Config/Options interface.
+ */
+function isConfigInterface(interfaceName) {
+    /* v8 ignore next -- defensive AST/type guard */
+    return interfaceName.includes('Config') || interfaceName.includes('Options');
+}
+/**
+ * Extract property from interface member.
+ */
+function extractPropertyFromMember(member, sourceFile, interfaceName, filePath) {
+    /* v8 ignore next -- defensive AST/type guard */
+    if (!ts.isPropertySignature(member))
+        return null;
+    /* v8 ignore next -- defensive AST/type guard */
+    if (!ts.isIdentifier(member.name))
+        return null;
+    const propName = member.name.text;
+    // Skip common property names that would cause many false positives
+    if (COMMON_PROPERTY_NAMES.has(propName))
+        return null;
+    const { line } = sourceFile.getLineAndCharacterOfPosition(member.getStart());
+    return {
+        name: propName,
+        interfaceName,
+        filePath,
+        line: line + 1,
+        isOptional: member.questionToken !== undefined,
+    };
+}
+/**
+ * Extract config properties from interface members
+ */
+function extractInterfaceProperties(node, sourceFile, filePath) {
+    const properties = [];
+    const interfaceName = node.name.text;
+    for (const member of node.members) {
+        const prop = extractPropertyFromMember(member, sourceFile, interfaceName, filePath);
+        if (!prop)
+            continue;
+        properties.push(prop);
+    }
+    return properties;
+}
+function isConfigFilePath(filePath) {
+    return filePath.includes('config') || filePath.includes('Config');
+}
+async function extractConfigPropertiesFromFile(filePath, files) {
+    // @lazy-ok -- visit function's conditionals are not pre-await validation guards
+    const content = await files.read(filePath);
+    const sourceFile = getSharedSourceFile(filePath, content);
+    /* v8 ignore next -- defensive guard */
+    if (!sourceFile)
+        return [];
+    const properties = [];
+    const visit = (node) => {
+        ts.forEachChild(node, visit);
+        if (!ts.isInterfaceDeclaration(node))
+            return;
+        /* v8 ignore next -- defensive AST/type guard */
+        if (!isConfigInterface(node.name.text))
+            return;
+        properties.push(...extractInterfaceProperties(node, sourceFile, filePath));
+    };
+    void visit(sourceFile);
+    return properties;
+}
+async function collectConfigProperties(files) {
+    logger.debug({
+        evt: 'fitness.collect_config_properties.start',
+        msg: 'Collecting config properties',
+    });
+    const configProperties = [];
+    for (const filePath of files.paths) {
+        if (shouldExcludePath(filePath) || !isConfigFilePath(filePath))
+            continue;
+        try {
+            // @fitness-ignore-next-line performance-anti-patterns -- sequential file reading to control memory; FileAccessor is lazy
+            const props = await extractConfigPropertiesFromFile(filePath, files);
+            configProperties.push(...props);
+            /* v8 ignore next 1 -- defensive catch: parse failures already handled */
+        }
+        catch {
+            // @swallow-ok Skip unreadable files
+        }
+    }
+    logger.debug({
+        evt: 'fitness.collect_config_properties.complete',
+        count: configProperties.length,
+        msg: 'Config properties collected',
+    });
+    return configProperties;
+}
+async function countPropertyAccesses(files) {
+    logger.debug({
+        evt: 'fitness.count_property_accesses.start',
+        msg: 'Counting property accesses across files',
+    });
+    const accessCounts = new Map();
+    for (const filePath of files.paths) {
+        try {
+            // @fitness-ignore-next-line performance-anti-patterns -- sequential file reading to control memory; FileAccessor is lazy
+            const content = await files.read(filePath);
+            const sourceFile = getSharedSourceFile(filePath, content);
+            /* v8 ignore next -- defensive guard */
+            if (!sourceFile)
+                continue;
+            const visit = (node) => {
+                if (ts.isPropertyAccessExpression(node)) {
+                    const propertyName = node.name.text;
+                    /* v8 ignore next -- defensive nullish fallback */
+                    accessCounts.set(propertyName, (accessCounts.get(propertyName) ?? 0) + 1);
+                }
+                if (ts.isBindingElement(node) && ts.isIdentifier(node.name)) {
+                    const propertyName = node.name.text;
+                    /* v8 ignore next -- defensive nullish fallback */
+                    accessCounts.set(propertyName, (accessCounts.get(propertyName) ?? 0) + 1);
+                }
+                ts.forEachChild(node, visit);
+            };
+            void visit(sourceFile);
+            /* v8 ignore next 1 -- defensive catch: parse failures already handled */
+        }
+        catch {
+            // @swallow-ok Skip unreadable files
+        }
+    }
+    return accessCounts;
+}
+function createViolationForUnusedProperty(prop) {
+    return {
+        line: prop.line,
+        column: 0,
+        message: `Config property '${prop.name}' in ${prop.interfaceName} is never accessed`,
+        severity: 'warning',
+        suggestion: `Remove unused config property '${prop.name}' from ${prop.interfaceName}, or implement code that uses this configuration option`,
+        match: prop.name,
+        filePath: prop.filePath,
+    };
+}
+function findUnusedProperties(configProperties, accessCounts) {
+    const violations = [];
+    for (const prop of configProperties) {
+        if (prop.isOptional)
+            continue;
+        /* v8 ignore next -- defensive nullish fallback */
+        const count = accessCounts.get(prop.name) ?? 0;
+        if (count === 0) {
+            violations.push(createViolationForUnusedProperty(prop));
+        }
+    }
+    return violations;
+}
+/**
+ * Check: quality/unused-config-options
+ *
+ * Detects configuration properties defined but never accessed.
+ */
+export const unusedConfigOptions = defineCheck({
+    id: '09006e97-77fd-4a75-9a9a-d5ed0abb9d9f',
+    slug: 'unused-config-options',
+    scope: { languages: ['json', 'typescript', 'yaml'], concerns: ['config'] },
+    contentFilter: 'raw',
+    confidence: 'high',
+    description: 'Detects configuration properties defined but never accessed',
+    longDescription: `**Purpose:** Detects configuration properties that are defined in Config/Options interfaces but never accessed anywhere in the codebase.
+
+**Detects:**
+- Required (non-optional) properties in interfaces containing \`Config\` or \`Options\` in their name
+- Properties with zero \`PropertyAccessExpression\` or \`BindingElement\` references across all scanned files
+- Excludes common property names (\`enabled\`, \`timeout\`, \`port\`, \`host\`, etc.) to reduce false positives
+
+**Why it matters:** Unused config properties add cognitive overhead and suggest incomplete implementations or abandoned features that should be cleaned up.
+
+**Scope:** General best practice. Cross-file analysis (\`analyzeAll\`). Scans config files for property definitions, then counts access patterns across all production files.`,
+    tags: ['quality', 'code-quality', 'maintainability'],
+    fileTypes: ['ts', 'tsx'],
+    async analyzeAll(files) {
+        // @fitness-ignore-next-line async-waterfall-detection -- Both scan all files independently; parallelizing would double peak memory by loading file contents twice concurrently
+        const configProperties = await collectConfigProperties(files);
+        const accessCounts = await countPropertyAccesses(files);
+        return findUnusedProperties(configProperties, accessCounts);
+    },
+});
+//# sourceMappingURL=unused-config-options.js.map