@libar-dev/architect 1.0.0-pre.3

package/dist/lint/rules.js

@@ -0,0 +1,289 @@
+/**
+ * @architect
+ * @architect-lint
+ * @architect-pattern LintRules
+ * @architect-status completed
+ * @architect-arch-role service
+ * @architect-arch-context lint
+ * @architect-arch-layer application
+ * @architect-implements PatternRelationshipModel
+ * @architect-used-by LintEngine
+ * @architect-extract-shapes LintRule, LintContext, defaultRules, severityOrder, filterRulesBySeverity, missingPatternName, missingStatus, invalidStatus, missingWhenToUse, tautologicalDescription, missingRelationships, patternConflictInImplements, missingRelationshipTarget
+ *
+ * ## LintRules - Annotation Quality Rules
+ *
+ * Defines lint rules that check @architect-* directives for completeness
+ * and quality. Rules include: missing-pattern-name, missing-status,
+ * missing-when-to-use, tautological-description, and missing-relationships.
+ *
+ * ### When to Use
+ *
+ * - Use `defaultRules` for standard quality checks
+ * - Use `filterRulesBySeverity()` to customize which rules apply
+ * - Use individual rules for targeted validation
+ */
+import { PROCESS_STATUS_VALUES, VALID_PROCESS_STATUS_SET } from '../taxonomy/index.js';
+import { DEFAULT_TAG_PREFIX } from '../config/defaults.js';
+/**
+ * Multiplier for determining if description has "substantial content" beyond the pattern name.
+ * If description length > name length * this multiplier, it's considered substantial.
+ */
+const SUBSTANTIAL_CONTENT_MULTIPLIER = 2;
+/**
+ * Create a lint violation
+ */
+function violation(rule, severity, message, file, line) {
+    return { rule, severity, message, file, line };
+}
+/**
+ * Get the tag prefix from context or use default.
+ */
+function getTagPrefix(context) {
+    return context?.registry?.tagPrefix ?? DEFAULT_TAG_PREFIX;
+}
+/**
+ * Rule: missing-pattern-name
+ *
+ * Patterns must have an explicit name via the pattern tag.
+ * Without a name, the pattern can't be referenced in relationships
+ * or indexed properly.
+ */
+export const missingPatternName = {
+    id: 'missing-pattern-name',
+    severity: 'error',
+    description: 'Pattern must have explicit pattern name tag',
+    check: (directive, file, line, context) => {
+        // Skip if this is an implementation-only file (has implements tag)
+        // Implementation files realize patterns defined elsewhere and don't need their own name
+        const hasImplements = (directive.implements?.length ?? 0) > 0;
+        if (hasImplements) {
+            return null;
+        }
+        if (!directive.patternName || directive.patternName.trim() === '') {
+            const tagPrefix = getTagPrefix(context);
+            return violation('missing-pattern-name', 'error', `Pattern missing explicit name. Add ${tagPrefix}pattern YourPatternName`, file, line);
+        }
+        return null;
+    },
+};
+/**
+ * Rule: missing-status
+ *
+ * Patterns should have an explicit status (completed, active, roadmap, deferred).
+ * This helps readers understand if the pattern is ready for use.
+ */
+export const missingStatus = {
+    id: 'missing-status',
+    severity: 'warning',
+    description: 'Pattern should have status tag (roadmap|active|completed|deferred)',
+    check: (directive, file, line, context) => {
+        if (!directive.status) {
+            const tagPrefix = getTagPrefix(context);
+            return violation('missing-status', 'warning', `No ${tagPrefix}status found. Add: ${tagPrefix}status roadmap|active|completed|deferred`, file, line);
+        }
+        return null;
+    },
+};
+/**
+ * Rule: invalid-status
+ *
+ * Status values must be valid PDR-005 FSM states.
+ */
+export const invalidStatus = {
+    id: 'invalid-status',
+    severity: 'error',
+    description: 'Status must be a valid FSM state (roadmap, active, completed, deferred)',
+    check: (directive, file, line) => {
+        // Skip if no status (handled by missing-status rule)
+        if (!directive.status) {
+            return null;
+        }
+        if (!VALID_PROCESS_STATUS_SET.has(directive.status.toLowerCase())) {
+            return violation('invalid-status', 'error', `Invalid status '${directive.status}'. Valid values: ${PROCESS_STATUS_VALUES.join(', ')}.`, file, line);
+        }
+        return null;
+    },
+};
+/**
+ * Rule: missing-when-to-use
+ *
+ * Patterns should have a "When to Use" section for LLM-friendly guidance.
+ * This helps developers understand when the pattern applies.
+ */
+export const missingWhenToUse = {
+    id: 'missing-when-to-use',
+    severity: 'warning',
+    description: 'Pattern should have "When to Use" section in description',
+    check: (directive, file, line) => {
+        // whenToUse is now an array of bullet points
+        if (!directive.whenToUse || directive.whenToUse.length === 0) {
+            return violation('missing-when-to-use', 'warning', 'No "When to Use" section found. Add ### When to Use or **When to use:** in description', file, line);
+        }
+        return null;
+    },
+};
+/**
+ * Rule: tautological-description
+ *
+ * The description should not simply repeat the pattern name.
+ * A tautological description provides no useful information.
+ */
+export const tautologicalDescription = {
+    id: 'tautological-description',
+    severity: 'error',
+    description: 'Description should not simply repeat the pattern name',
+    check: (directive, file, line) => {
+        if (!directive.patternName || !directive.description) {
+            return null;
+        }
+        // Get first meaningful line of description (skip empty lines and headings)
+        const lines = directive.description.split('\n');
+        const firstLine = lines
+            .map((l) => l.trim())
+            .find((l) => l.length > 0 && !l.startsWith('#') && !l.startsWith('**When'));
+        if (!firstLine) {
+            return null;
+        }
+        // Normalize for comparison (lowercase, remove punctuation)
+        const normalizedName = directive.patternName.toLowerCase().replace(/[^a-z0-9]/g, '');
+        const normalizedDesc = firstLine.toLowerCase().replace(/[^a-z0-9]/g, '');
+        // Check if description starts with or equals the pattern name
+        if (normalizedDesc === normalizedName || normalizedDesc.startsWith(normalizedName)) {
+            // Allow if there's substantial content after the name
+            if (normalizedDesc.length > normalizedName.length * SUBSTANTIAL_CONTENT_MULTIPLIER) {
+                return null;
+            }
+            return violation('tautological-description', 'error', `Description repeats pattern name "${directive.patternName}". Provide meaningful context.`, file, line);
+        }
+        return null;
+    },
+};
+/**
+ * Rule: missing-relationships
+ *
+ * Patterns should declare their relationships (uses/usedBy) for
+ * dependency tracking. This is informational only.
+ */
+export const missingRelationships = {
+    id: 'missing-relationships',
+    severity: 'info',
+    description: 'Consider adding uses and used-by tags',
+    check: (directive, file, line, context) => {
+        const hasUses = (directive.uses?.length ?? 0) > 0;
+        const hasUsedBy = (directive.usedBy?.length ?? 0) > 0;
+        if (!hasUses && !hasUsedBy) {
+            const tagPrefix = getTagPrefix(context);
+            return violation('missing-relationships', 'info', `Consider adding relationship tags: ${tagPrefix}uses and/or ${tagPrefix}used-by`, file, line);
+        }
+        return null;
+    },
+};
+// ═══════════════════════════════════════════════════════════════════════════
+// Relationship Validation Rules (PatternRelationshipModel)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Rule: pattern-conflict-in-implements
+ *
+ * Validates that a file doesn't create a circular reference by defining
+ * a pattern that it also implements. Having both @architect-pattern X
+ * AND @architect-implements X on the same file is a conflict.
+ *
+ * However, a file CAN have both tags when they reference DIFFERENT patterns:
+ * - @architect-pattern SubPattern (defines its own identity)
+ * - @architect-implements ParentSpec (links to parent spec)
+ *
+ * This supports the sub-pattern hierarchy where implementation files can be
+ * named patterns that also implement a larger spec (e.g., MockPaymentActions
+ * implementing DurableEventsIntegration).
+ */
+export const patternConflictInImplements = {
+    id: 'pattern-conflict-in-implements',
+    severity: 'error',
+    description: 'Pattern cannot implement itself (circular reference)',
+    check: (directive, file, line, context) => {
+        const hasImplements = (directive.implements?.length ?? 0) > 0;
+        const patternName = directive.patternName;
+        if (hasImplements && patternName !== undefined) {
+            // Only error if pattern name matches any implements target (circular reference)
+            const patternNameLower = patternName.toLowerCase();
+            const implementsTargets = directive.implements?.map((i) => i.toLowerCase()) ?? [];
+            if (implementsTargets.includes(patternNameLower)) {
+                const tagPrefix = getTagPrefix(context);
+                return violation('pattern-conflict-in-implements', 'error', `Pattern '${patternName}' cannot implement itself. ` +
+                    `Remove either ${tagPrefix}pattern or ${tagPrefix}implements for this pattern.`, file, line);
+            }
+            // Different patterns: OK - this is a sub-pattern implementing a parent spec
+        }
+        return null;
+    },
+};
+/**
+ * Rule: missing-relationship-target
+ *
+ * Validates that relationship targets (uses, implements) reference
+ * patterns that actually exist. Only triggers when a LintContext with
+ * knownPatterns is provided (strict mode).
+ *
+ * This is a context-aware rule that requires access to the pattern registry.
+ */
+export const missingRelationshipTarget = {
+    id: 'missing-relationship-target',
+    severity: 'warning',
+    description: 'Relationship targets must reference existing patterns',
+    check: (directive, file, line, context) => {
+        // Skip if no context provided (non-strict mode)
+        if (!context?.knownPatterns) {
+            return null;
+        }
+        const violations = [];
+        // Check uses targets
+        for (const target of directive.uses ?? []) {
+            if (!context.knownPatterns.has(target)) {
+                violations.push(violation('missing-relationship-target', 'warning', `Relationship target '${target}' not found in known patterns`, file, line));
+            }
+        }
+        // Check implements targets
+        for (const target of directive.implements ?? []) {
+            if (!context.knownPatterns.has(target)) {
+                violations.push(violation('missing-relationship-target', 'warning', `Implementation target '${target}' not found in known patterns`, file, line));
+            }
+        }
+        return violations.length > 0 ? violations : null;
+    },
+};
+/**
+ * All default lint rules
+ *
+ * Order matters for output - errors first, then warnings, then info.
+ */
+export const defaultRules = [
+    missingPatternName,
+    tautologicalDescription,
+    invalidStatus,
+    patternConflictInImplements, // PatternRelationshipModel rule
+    missingRelationshipTarget, // Context-aware relationship validation
+    missingStatus,
+    missingWhenToUse,
+    missingRelationships,
+];
+/**
+ * Severity ordering for sorting and filtering
+ * Exported for use by lint engine to avoid duplication
+ */
+export const severityOrder = {
+    error: 0,
+    warning: 1,
+    info: 2,
+};
+/**
+ * Get rules filtered by minimum severity
+ *
+ * @param rules - Rules to filter
+ * @param minSeverity - Minimum severity to include
+ * @returns Filtered rules
+ */
+export function filterRulesBySeverity(rules, minSeverity) {
+    const minLevel = severityOrder[minSeverity];
+    return rules.filter((rule) => severityOrder[rule.severity] <= minLevel);
+}
+//# sourceMappingURL=rules.js.map

package/dist/lint/rules.js.map

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

package/dist/lint/steps/cross-checks.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Cross-file lint checks for vitest-cucumber compatibility.
+ *
+ * These checks compare a .feature file with its corresponding .steps.ts
+ * file to detect mismatches in structure (Rule/And/ScenarioOutline patterns).
+ */
+import type { LintViolation } from '../../validation-schemas/lint.js';
+/**
+ * Check 1: Detect function params used inside ScenarioOutline blocks.
+ *
+ * In vitest-cucumber, ScenarioOutline step callbacks receive values via a
+ * `variables` object — NOT via function parameters. Using (_ctx, value: string)
+ * as callback args is the #1 trap: the value will be undefined at runtime.
+ *
+ * Detection: Find ScenarioOutline/RuleScenarioOutline blocks in step files,
+ * then within those blocks look for step callbacks with a second positional
+ * parameter after _ctx.
+ *
+ * The heuristic is conservative: we only flag when we see an explicit second
+ * positional parameter pattern. False negatives are acceptable; false positives
+ * are not.
+ */
+export declare function checkScenarioOutlineFunctionParams(featureContent: string, stepContent: string, stepFilePath: string): readonly LintViolation[];
+/**
+ * Check 2: Detect missing And destructuring.
+ *
+ * If a feature file has And steps, the step definition must destructure And
+ * from the scenario callback. Using Then(...) for And steps causes
+ * StepAbleUnknowStepError at runtime.
+ */
+export declare function checkMissingAndDestructuring(featureContent: string, stepContent: string, stepFilePath: string): readonly LintViolation[];
+/**
+ * Check 3: Detect missing Rule() wrapper.
+ *
+ * If a feature file has Rule: blocks, the step definition must destructure
+ * Rule from describeFeature and wrap scenarios with Rule('name', ...).
+ * Using top-level Scenario() instead of RuleScenario() causes step
+ * matching failures.
+ */
+export declare function checkMissingRuleWrapper(featureContent: string, stepContent: string, stepFilePath: string): readonly LintViolation[];
+/**
+ * Check 12: Detect quoted values in Scenario Outline steps (feature-file side).
+ *
+ * When a Scenario Outline's steps use quoted values (e.g., "foo") instead of
+ * angle-bracket placeholders (e.g., <column>), this suggests the author is
+ * using the Scenario pattern (Cucumber expression matching) instead of the
+ * ScenarioOutline pattern (variable substitution). This is the feature-file
+ * side of the Two-Pattern Problem — the step-file side is caught by
+ * scenario-outline-function-params.
+ *
+ * Detection: Find Scenario Outline sections in the feature file, extract the
+ * Examples table column names, then check if step lines within those sections
+ * contain quoted values whose content matches a column name. Only those are
+ * flagged — constant quoted values (e.g., "error") that don't correspond to
+ * any Examples column are intentionally literal and should not be placeholders.
+ *
+ * This is a cross-file check because it's only meaningful when a paired step
+ * file exists (roadmap specs without implementations shouldn't be flagged).
+ * The _stepContent parameter is unused but maintains the cross-check signature.
+ */
+export declare function checkOutlineQuotedValues(featureContent: string, _stepContent: string, stepFilePath: string, featurePath?: string): readonly LintViolation[];
+/**
+ * Run all cross-file checks on a paired feature + step file.
+ */
+export declare function runCrossChecks(featureContent: string, stepContent: string, stepFilePath: string, featurePath?: string): readonly LintViolation[];
+//# sourceMappingURL=cross-checks.d.ts.map

package/dist/lint/steps/cross-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cross-checks.d.ts","sourceRoot":"","sources":["../../../src/lint/steps/cross-checks.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAItE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kCAAkC,CAChD,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,SAAS,aAAa,EAAE,CAwD1B;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,SAAS,aAAa,EAAE,CAqC1B;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,GACnB,SAAS,aAAa,EAAE,CAqC1B;AAwDD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,SAAS,aAAa,EAAE,CAmE1B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,WAAW,CAAC,EAAE,MAAM,GACnB,SAAS,aAAa,EAAE,CAO1B"}

package/dist/lint/steps/cross-checks.js

@@ -0,0 +1,290 @@
+/**
+ * Cross-file lint checks for vitest-cucumber compatibility.
+ *
+ * These checks compare a .feature file with its corresponding .steps.ts
+ * file to detect mismatches in structure (Rule/And/ScenarioOutline patterns).
+ */
+import { STEP_LINT_RULES } from './types.js';
+import { countBraceBalance } from './utils.js';
+/**
+ * Check 1: Detect function params used inside ScenarioOutline blocks.
+ *
+ * In vitest-cucumber, ScenarioOutline step callbacks receive values via a
+ * `variables` object — NOT via function parameters. Using (_ctx, value: string)
+ * as callback args is the #1 trap: the value will be undefined at runtime.
+ *
+ * Detection: Find ScenarioOutline/RuleScenarioOutline blocks in step files,
+ * then within those blocks look for step callbacks with a second positional
+ * parameter after _ctx.
+ *
+ * The heuristic is conservative: we only flag when we see an explicit second
+ * positional parameter pattern. False negatives are acceptable; false positives
+ * are not.
+ */
+export function checkScenarioOutlineFunctionParams(featureContent, stepContent, stepFilePath) {
+    // Only check if the feature actually has Scenario Outline
+    if (!/^\s*(Scenario Outline|Scenario Template):/m.test(featureContent)) {
+        return [];
+    }
+    const violations = [];
+    const lines = stepContent.split('\n');
+    // Track whether we're inside a ScenarioOutline block using brace depth
+    let inOutlineBlock = false;
+    let braceDepth = 0;
+    let outlineStartLine = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        // Detect ScenarioOutline( or RuleScenarioOutline( call
+        if (!inOutlineBlock && /(?:Scenario|RuleScenario)Outline\s*\(/.test(line)) {
+            inOutlineBlock = true;
+            outlineStartLine = i + 1;
+            // Count opening braces on this line to start depth tracking
+            braceDepth = countBraceBalance(line);
+            continue;
+        }
+        if (inOutlineBlock) {
+            braceDepth += countBraceBalance(line);
+            // Check for step callbacks with function params: Given('text', (_ctx, value: type) =>
+            // The pattern: a step keyword, string arg, then a callback with 2+ params
+            const paramMatch = /(?:Given|When|Then|And|But)\s*\(\s*['"][^'"]*['"]\s*,\s*\(\s*_?ctx\s*(?::\s*\w+)?\s*,\s*(\w+)/.exec(line);
+            if (paramMatch !== null) {
+                const paramName = paramMatch[1] ?? 'unknown';
+                violations.push({
+                    rule: STEP_LINT_RULES.scenarioOutlineFunctionParams.id,
+                    severity: STEP_LINT_RULES.scenarioOutlineFunctionParams.severity,
+                    message: `Step callback inside ScenarioOutline uses function param "${paramName}" — use variables object instead (ScenarioOutline started at line ${outlineStartLine})`,
+                    file: stepFilePath,
+                    line: i + 1,
+                });
+            }
+            // End of ScenarioOutline block
+            if (braceDepth <= 0) {
+                inOutlineBlock = false;
+                braceDepth = 0;
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Check 2: Detect missing And destructuring.
+ *
+ * If a feature file has And steps, the step definition must destructure And
+ * from the scenario callback. Using Then(...) for And steps causes
+ * StepAbleUnknowStepError at runtime.
+ */
+export function checkMissingAndDestructuring(featureContent, stepContent, stepFilePath) {
+    // Check if feature has any And steps
+    const hasAndSteps = /^\s+And\s+/m.test(featureContent);
+    if (!hasAndSteps) {
+        return [];
+    }
+    // Check if step file destructures And anywhere.
+    // NOTE: This regex matches And inside ANY curly brace pair, including object
+    // literals with an `And` property. This is a theoretical false negative (would
+    // pass when it should flag), which is the safe direction. In practice, step
+    // files don't have object literals with `And` keys.
+    const destructuresAnd = /\{\s*[^}]*\bAnd\b[^}]*\}/.test(stepContent);
+    if (destructuresAnd) {
+        return [];
+    }
+    // Find the line of the describeFeature call for context
+    const lines = stepContent.split('\n');
+    let describeLine = 1;
+    for (let i = 0; i < lines.length; i++) {
+        const ln = lines[i];
+        if (ln !== undefined && /describeFeature\s*\(/.test(ln)) {
+            describeLine = i + 1;
+            break;
+        }
+    }
+    return [
+        {
+            rule: STEP_LINT_RULES.missingAndDestructuring.id,
+            severity: STEP_LINT_RULES.missingAndDestructuring.severity,
+            message: `Feature has And steps but step definition does not destructure And — add And to the destructuring pattern ({ Given, When, Then, And })`,
+            file: stepFilePath,
+            line: describeLine,
+        },
+    ];
+}
+/**
+ * Check 3: Detect missing Rule() wrapper.
+ *
+ * If a feature file has Rule: blocks, the step definition must destructure
+ * Rule from describeFeature and wrap scenarios with Rule('name', ...).
+ * Using top-level Scenario() instead of RuleScenario() causes step
+ * matching failures.
+ */
+export function checkMissingRuleWrapper(featureContent, stepContent, stepFilePath) {
+    // Check if feature has any Rule: blocks
+    const hasRuleBlocks = /^\s*Rule:\s/m.test(featureContent);
+    if (!hasRuleBlocks) {
+        return [];
+    }
+    // Check if step file destructures Rule from describeFeature
+    // Pattern: describeFeature(feature, ({ ... Rule ... }) =>
+    // We look for Rule in any destructuring pattern, since it could appear anywhere
+    const destructuresRule = /describeFeature\s*\([^,]*,\s*\(\s*\{[^}]*\bRule\b[^}]*\}/.test(stepContent);
+    if (destructuresRule) {
+        return [];
+    }
+    // Find the line of the describeFeature call for context
+    const lines = stepContent.split('\n');
+    let describeLine = 1;
+    for (let i = 0; i < lines.length; i++) {
+        const ln = lines[i];
+        if (ln !== undefined && /describeFeature\s*\(/.test(ln)) {
+            describeLine = i + 1;
+            break;
+        }
+    }
+    return [
+        {
+            rule: STEP_LINT_RULES.missingRuleWrapper.id,
+            severity: STEP_LINT_RULES.missingRuleWrapper.severity,
+            message: `Feature has Rule: blocks but step definition does not destructure Rule from describeFeature — use Rule('name', ({ RuleScenario }) => { ... })`,
+            file: stepFilePath,
+            line: describeLine,
+        },
+    ];
+}
+/**
+ * Step keyword pattern for matching step lines in feature files.
+ */
+const FEATURE_STEP_LINE = /^\s+(Given|When|Then|And|But)\s+(.+)$/;
+/**
+ * Extract column names from Examples tables belonging to a Scenario Outline.
+ *
+ * Scans forward from the given start index (the Scenario Outline line) until
+ * the next section boundary. Collects column names from every Examples table
+ * header row found within that range.
+ */
+function extractOutlineExamplesColumns(lines, outlineStartIndex) {
+    const columns = new Set();
+    let inExamples = false;
+    let seenExamplesHeader = false;
+    for (let i = outlineStartIndex + 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        // Stop at next section boundary (another Scenario, Rule, Feature, Background)
+        if (/^\s*(Scenario Outline|Scenario Template|Scenario:|Feature:|Rule:|Background:)/.test(line)) {
+            break;
+        }
+        // Enter Examples block
+        if (/^\s*Examples:/.test(line)) {
+            inExamples = true;
+            seenExamplesHeader = false;
+            continue;
+        }
+        // Inside Examples: first table row is the header with column names
+        if (inExamples && !seenExamplesHeader && /^\s*\|/.test(line)) {
+            seenExamplesHeader = true;
+            const cells = line
+                .split('|')
+                .map((cell) => cell.trim())
+                .filter((cell) => cell.length > 0);
+            for (const cell of cells) {
+                columns.add(cell);
+            }
+        }
+    }
+    return columns;
+}
+/**
+ * Check 12: Detect quoted values in Scenario Outline steps (feature-file side).
+ *
+ * When a Scenario Outline's steps use quoted values (e.g., "foo") instead of
+ * angle-bracket placeholders (e.g., <column>), this suggests the author is
+ * using the Scenario pattern (Cucumber expression matching) instead of the
+ * ScenarioOutline pattern (variable substitution). This is the feature-file
+ * side of the Two-Pattern Problem — the step-file side is caught by
+ * scenario-outline-function-params.
+ *
+ * Detection: Find Scenario Outline sections in the feature file, extract the
+ * Examples table column names, then check if step lines within those sections
+ * contain quoted values whose content matches a column name. Only those are
+ * flagged — constant quoted values (e.g., "error") that don't correspond to
+ * any Examples column are intentionally literal and should not be placeholders.
+ *
+ * This is a cross-file check because it's only meaningful when a paired step
+ * file exists (roadmap specs without implementations shouldn't be flagged).
+ * The _stepContent parameter is unused but maintains the cross-check signature.
+ */
+export function checkOutlineQuotedValues(featureContent, _stepContent, stepFilePath, featurePath) {
+    // Only check if the feature actually has Scenario Outline
+    if (!/^\s*(Scenario Outline|Scenario Template):/m.test(featureContent)) {
+        return [];
+    }
+    const violations = [];
+    const lines = featureContent.split('\n');
+    let inOutlineSection = false;
+    let currentOutlineColumns = new Set();
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        // Enter Scenario Outline section
+        if (/^\s*(Scenario Outline|Scenario Template):/.test(line)) {
+            inOutlineSection = true;
+            currentOutlineColumns = extractOutlineExamplesColumns(lines, i);
+            continue;
+        }
+        // Exit on new section boundary (but not Examples, which is part of Outline)
+        if (/^\s*(Scenario:|Feature:|Rule:|Background:)/.test(line)) {
+            inOutlineSection = false;
+            continue;
+        }
+        if (!inOutlineSection)
+            continue;
+        // Check step lines within the Outline section
+        const stepMatch = FEATURE_STEP_LINE.exec(line);
+        if (stepMatch !== null) {
+            const stepText = stepMatch[2] ?? '';
+            // Skip steps that already use placeholders — the author clearly knows
+            // about the ScenarioOutline pattern and chose to keep quoted values literal
+            const hasPlaceholders = /<\w+>/.test(stepText);
+            if (hasPlaceholders)
+                continue;
+            // Extract all quoted values from the step
+            const quotedValues = [];
+            const doubleQuoteMatches = stepText.matchAll(/"([^"]*)"/g);
+            for (const m of doubleQuoteMatches) {
+                if (m[1] !== undefined)
+                    quotedValues.push(m[1]);
+            }
+            const singleQuoteMatches = stepText.matchAll(/'([^']*)'/g);
+            for (const m of singleQuoteMatches) {
+                if (m[1] !== undefined)
+                    quotedValues.push(m[1]);
+            }
+            // Only flag if at least one quoted value matches an Examples column name
+            const matchesColumn = quotedValues.some((val) => currentOutlineColumns.has(val));
+            if (matchesColumn) {
+                violations.push({
+                    rule: STEP_LINT_RULES.outlineQuotedValues.id,
+                    severity: STEP_LINT_RULES.outlineQuotedValues.severity,
+                    message: `Scenario Outline step uses quoted values instead of <placeholder> syntax — this suggests the Scenario pattern (Cucumber expressions) rather than ScenarioOutline pattern (variable substitution)`,
+                    file: featurePath ?? stepFilePath,
+                    line: i + 1,
+                });
+            }
+        }
+    }
+    return violations;
+}
+/**
+ * Run all cross-file checks on a paired feature + step file.
+ */
+export function runCrossChecks(featureContent, stepContent, stepFilePath, featurePath) {
+    return [
+        ...checkScenarioOutlineFunctionParams(featureContent, stepContent, stepFilePath),
+        ...checkMissingAndDestructuring(featureContent, stepContent, stepFilePath),
+        ...checkMissingRuleWrapper(featureContent, stepContent, stepFilePath),
+        ...checkOutlineQuotedValues(featureContent, stepContent, stepFilePath, featurePath),
+    ];
+}
+//# sourceMappingURL=cross-checks.js.map