@goliapkg/sentori-cli 1.8.0 → 1.10.0

package/src/lint/index.ts

@@ -0,0 +1,163 @@
+import { spawnSync } from 'node:child_process'
+import { closeSync, existsSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import { parseArgs } from 'node:util'
+import { parseConfig, selected } from './config.js'
+import type { Config } from './config.js'
+import { initBaseline, lowerBaseline, makeReport, sarif, textReport, validateBaseline, validateResponse } from './report.js'
+import type { Baseline, Finding } from './report.js'
+import { ruleById, ruleset } from './rules.js'
+
+const help = `sentori lint [paths...] [options]
+Swift and Kotlin syntax checks (preview 0.3.0).
+  --config FILE          default: <git-root>/sentori-lint.toml
+  --swift-analyzer FILE  executable (or SENTORI_LINT_SWIFT; default sentori-lint-swift)
+  --kotlin-analyzer FILE executable (or SENTORI_LINT_KOTLIN; default sentori-lint-kotlin)
+  --format text|json|sarif
+  --baseline FILE        read a versioned rule/file-count baseline
+  --init-baseline        initialize FILE, only if it does not exist
+  --update-baseline      lower FILE after a successful full scan
+  --changed REF          scan git diff REF plus untracked files; never update baselines
+  --fix                  run toolchain swift format, then reanalyze
+  --explain RULE         print rule metadata
+  --version              print lint protocol/ruleset version
+Exit codes: 0 passed, 1 rule regressions, 2 configuration/analyzer/tool failure.
+Configured tests participate only in function-length checks; generated exclusions apply to all rules.
+`
+function command(executable: string, args: string[], cwd: string, input?: string): string {
+  const result = spawnSync(executable, args, { cwd, input, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, timeout: 120_000 })
+  if (result.error || result.status !== 0) {
+    throw Error(`${executable} failed: ${result.error?.message ?? result.stderr.trim() ?? result.signal ?? result.status}`)
+  }
+  return result.stdout
+}
+function git(root: string, args: string[]): string { return command('git', ['--literal-pathspecs', '-C', root, ...args], root) }
+function records(value: string): string[] { return value.split('\0').filter(Boolean) }
+export function discoverFiles(root: string, config: Config, paths: string[] = [], changed?: string): string[] {
+  const all = records(git(root, ['ls-files', '--cached', '--others', '--exclude-standard', '-z']))
+  const changedPaths = changed === undefined ? undefined : new Set([
+    ...records(git(root, ['diff', '--name-only', '-z', '--diff-filter=ACMR', changed, '--'])),
+    ...records(git(root, ['ls-files', '--others', '--exclude-standard', '-z'])),
+  ])
+  const prefixes = paths.map(p => {
+    const path = relative(root, resolve(process.cwd(), p)).split(sep).join('/')
+    if (path === '..' || path.startsWith('../') || isAbsolute(path)) throw Error(`path outside repository: ${p}`)
+    if (!existsSync(resolve(root, path))) throw Error(`path does not exist: ${p}`)
+    return path
+  })
+  return [...new Set(all)].filter(path => {
+    if (!/\.(swift|kt)$/.test(path) || !selected(path, config)) return false
+    if (changedPaths && !changedPaths.has(path)) return false
+    if (prefixes.length && !prefixes.some(p => !p || path === p || path.startsWith(p + '/'))) return false
+    const fullPath = resolve(root, path)
+    try { lstatSync(fullPath) } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false // tracked deletion
+      throw error
+    }
+    const rel = relative(realpathSync(root), realpathSync(fullPath))
+    if (rel === '..' || rel.startsWith('..' + sep) || isAbsolute(rel) || lstatSync(fullPath).isSymbolicLink()) throw Error(`refusing source symlink/outside file: ${path}`)
+    if (!lstatSync(fullPath).isFile()) throw Error(`not a regular source file: ${path}`)
+    return true
+  }).sort()
+}
+function analyze(root: string, executable: string, files: string[], language: 'swift' | 'kotlin'): Finding[] {
+  if (!files.length) return []
+  const output = command(executable, [], root, JSON.stringify({ version: 1, files }))
+  return validateResponse(JSON.parse(output), files, language)
+}
+function writeBaseline(path: string, baseline: Baseline, original?: string): void {
+  const contents = JSON.stringify(baseline, null, 2) + '\n'
+  const lock = `${path}.lock`
+  const lockFd = openSync(lock, 'wx')
+  const temporary = `${path}.${randomUUID()}.tmp`
+  try {
+    writeFileSync(lockFd, JSON.stringify({ pid: process.pid }) + '\n')
+    const fd = openSync(temporary, 'wx')
+    try { writeFileSync(fd, contents); fsyncSync(fd) } finally { closeSync(fd) }
+    if (original === undefined) {
+      // Atomic create without replacement: interruption cannot leave half JSON.
+      linkSync(temporary, path)
+    } else {
+      if (lstatSync(path).isSymbolicLink() || readFileSync(path, 'utf8') !== original) throw Error('baseline changed during scan or is a symlink; retry')
+      renameSync(temporary, path)
+    }
+  } finally {
+    if (existsSync(temporary)) unlinkSync(temporary)
+    closeSync(lockFd)
+    unlinkSync(lock)
+  }
+}
+export async function cmdLint(argv: string[]): Promise<number> {
+  try {
+    const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
+      config: { type: 'string' }, 'swift-analyzer': { type: 'string' }, 'kotlin-analyzer': { type: 'string' }, format: { type: 'string', default: 'text' },
+      baseline: { type: 'string' }, 'init-baseline': { type: 'boolean' }, 'update-baseline': { type: 'boolean' },
+      changed: { type: 'string' }, fix: { type: 'boolean' }, explain: { type: 'string' },
+      version: { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+    } })
+    if (values.help) { console.log(help); return 0 }
+    if (values.version) { console.log(`sentori lint preview 0.3.0 (${ruleset})`); return 0 }
+    if (values.explain) {
+      const rule = ruleById.get(values.explain)
+      if (!rule) throw Error(`unknown rule ${values.explain}`)
+      console.log(JSON.stringify(rule, null, 2)); return 0
+    }
+    if (!['text', 'json', 'sarif'].includes(values.format!)) throw Error('format must be text, json, or sarif')
+    const initialize = values['init-baseline'], update = values['update-baseline']
+    if (initialize && update) throw Error('choose init-baseline or update-baseline')
+    if ((initialize || update) && !values.baseline) throw Error('--baseline FILE is required')
+    if ((initialize || update) && (positionals.length || values.changed !== undefined)) throw Error('baseline writes require a full scan without paths or --changed')
+    if (values.changed?.startsWith('-')) throw Error('--changed requires a git revision, not an option')
+    const root = command('git', ['rev-parse', '--show-toplevel'], process.cwd()).replace(/\r?\n$/, '')
+    const configPath = values.config ? resolve(values.config) : resolve(root, 'sentori-lint.toml')
+    const configSource = readFileSync(configPath, 'utf8')
+    const config = parseConfig(configSource)
+    const baselinePath = values.baseline ? resolve(values.baseline) : undefined
+    if (initialize && existsSync(baselinePath!)) throw Error('baseline already exists; initialization never overwrites it')
+    const original = baselinePath && !initialize ? readFileSync(baselinePath, 'utf8') : undefined
+    const baseline = original === undefined ? undefined : validateBaseline(JSON.parse(original), config)
+    const files = discoverFiles(root, config, positionals, values.changed)
+    if (!files.length && values.changed === undefined) throw Error('no Swift or Kotlin source files selected; check scope/exclusions')
+    const swiftFiles = files.filter(path => path.endsWith('.swift'))
+    const kotlinFiles = files.filter(path => path.endsWith('.kt'))
+    if (values.fix && kotlinFiles.length) throw Error('--fix supports Swift only; select Swift paths for formatting')
+    const analyzerEnv = { swift: process.env.SENTORI_LINT_SWIFT, kotlin: process.env.SENTORI_LINT_KOTLIN }
+    const runAnalyzers = (): Finding[] => (['swift', 'kotlin'] as const).flatMap(language => {
+      const requested = values[`${language}-analyzer`] ?? analyzerEnv[language] ?? `sentori-lint-${language}`
+      const executable = requested.includes('/') || requested.includes('\\') ? resolve(requested) : requested
+      return analyze(root, executable, language === 'swift' ? swiftFiles : kotlinFiles, language)
+    })
+    const sourceDigest = () => files.map(path => createHash('sha256').update(readFileSync(resolve(root, path))).digest('hex')).join(':')
+    let snapshot = initialize || update ? sourceDigest() : undefined
+    let findings = runAnalyzers()
+    if (values.fix) {
+      // Validate all sources before touching any. Formatting is the only fix;
+      // the analyzer never rewrites forced operations or concurrency semantics.
+      for (let i = 0; i < files.length; i += 50) command('swift', ['format', 'format', '--in-place', '--', ...files.slice(i, i + 50)], root)
+      snapshot = initialize || update ? sourceDigest() : undefined
+      findings = runAnalyzers()
+    }
+    let report = makeReport(files, findings, config, baseline, !positionals.length && values.changed === undefined)
+    const cannotWrite = (initialize && report.regressions.some(r => r.kind === 'hard-limit' || ruleById.get(r.rule)!.allowlistOnly))
+      || (update && report.regressions.length > 0)
+    if (cannotWrite) console.error('baseline unchanged: resolve regressions/hard limits or add reviewed allowances first')
+    if ((initialize || update) && !cannotWrite) {
+      if (readFileSync(configPath, 'utf8') !== configSource || JSON.stringify(discoverFiles(root, config)) !== JSON.stringify(files) || sourceDigest() !== snapshot) throw Error('source selection or contents changed during scan; baseline unchanged, retry')
+    }
+    if (initialize && !cannotWrite) {
+      const created = initBaseline(report, config)
+      writeBaseline(baselinePath!, created)
+      report = makeReport(files, findings, config, created)
+    } else if (update && !cannotWrite) {
+      const lowered = lowerBaseline(report, baseline!)
+      writeBaseline(baselinePath!, lowered, original)
+      report = makeReport(files, findings, config, lowered)
+    }
+    console.log(values.format === 'text' ? textReport(report) : JSON.stringify(values.format === 'sarif' ? sarif(report) : report, null, 2))
+    return report.regressions.length ? 1 : 0
+  } catch (error) {
+    console.error(`sentori lint: ${(error as Error).message}`)
+    return 2
+  }
+}

package/src/lint/report.ts

@@ -0,0 +1,129 @@
+import { createHash } from 'node:crypto'
+import { glob, isTest } from './config.js'
+import type { Config } from './config.js'
+import { ruleById, rules, ruleset, swiftRuleset, kotlinRuleset, ruleLanguage, fileLanguage } from './rules.js'
+import type { Level } from './rules.js'
+export type Finding = { rule: string; path: string; line: number; column: number; measured?: number }
+export type Result = Finding & { level: Level; message: string; allowance?: string; hardLimitExceeded?: boolean }
+export type Baseline = { version: 1; ruleset: string; scope: string; counts: Record<string, Record<string, number>> }
+export type Regression = { path: string; rule: string; count: number; allowed: number; kind: 'count' | 'hard-limit' }
+export type Report = {
+  version: 1; ruleset: string; language: 'swift' | 'kotlin' | 'mixed'; fullScan: boolean; files: string[]; results: Result[]
+  regressions: Regression[]; baselineCanDecrease: boolean
+}
+export function scope(config: Config): string {
+  // A different policy is a migration, not an improvement. This also prevents
+  // disabling/excluding rules or files from silently erasing baseline debt.
+  return createHash('sha256').update(JSON.stringify({ ...config, rules: Object.fromEntries(Object.entries(config.rules).sort()) })).digest('hex')
+}
+export function validateBaseline(value: unknown, config: Config): Baseline {
+  const b = value as Baseline
+  if (!b || b.version !== 1 || b.ruleset !== ruleset || b.scope !== scope(config) || !b.counts || typeof b.counts !== 'object' || Array.isArray(b.counts)) {
+    throw Error('baseline version/ruleset/scope mismatch; policy changes require an explicit baseline migration')
+  }
+  for (const [path, counts] of Object.entries(b.counts)) {
+    if (!path || path.startsWith('/') || path.split('/').includes('..') || !/\.(swift|kt)$/.test(path) || !counts || typeof counts !== 'object' || Array.isArray(counts)) throw Error('invalid baseline path/counts')
+    for (const [id, count] of Object.entries(counts)) {
+      if (!ruleById.has(id) || ruleLanguage(id) !== fileLanguage(path) || ruleById.get(id)!.allowlistOnly || !Number.isSafeInteger(count) || count < 0) throw Error(`invalid baseline count for ${path}: ${id}`)
+    }
+  }
+  return b
+}
+export function validateResponse(value: unknown, files: string[], language: 'swift' | 'kotlin' = 'swift'): Finding[] {
+  const response = value as { version: number; ruleset: string; files: string[]; diagnostics: Finding[] }
+  if (!response || response.version !== 1 || response.ruleset !== (language === 'swift' ? swiftRuleset : kotlinRuleset) || !Array.isArray(response.files)
+      || JSON.stringify([...response.files].sort()) !== JSON.stringify([...files].sort()) || !Array.isArray(response.diagnostics)) throw Error('incomplete or incompatible analyzer response')
+  const paths = new Set(files), seen = new Set<string>()
+  for (const d of response.diagnostics) {
+    if (!d || !ruleById.has(d.rule) || ruleLanguage(d.rule) !== language || fileLanguage(d.path) !== language || !paths.has(d.path) || !Number.isSafeInteger(d.line) || d.line < 1 || !Number.isSafeInteger(d.column) || d.column < 1) throw Error('invalid analyzer diagnostic')
+    const thresholds = ruleById.get(d.rule)!.thresholds
+    if (thresholds && (!Number.isSafeInteger(d.measured) || d.measured! <= thresholds.target)) throw Error('missing or invalid analyzer measurement')
+    if (!thresholds && d.measured !== undefined) throw Error('unexpected analyzer measurement')
+    const key = JSON.stringify([d.rule, d.path, d.line, d.column])
+    if (seen.has(key)) throw Error('duplicate analyzer diagnostic')
+    seen.add(key)
+  }
+  return response.diagnostics
+}
+export function makeReport(files: string[], findings: Finding[], config: Config, baseline?: Baseline, fullScan = true): Report {
+  const results = findings.filter(d => !isTest(d.path, config) || ruleById.get(d.rule)!.tests).map(d => {
+    const rule = ruleById.get(d.rule)!
+    const allowance = config.allow.find(a => a.rule === d.rule && glob(a.path).test(d.path))?.reason
+    const hardLimitExceeded = rule.thresholds?.hard !== undefined && d.measured! > rule.thresholds.hard
+    const configured = config.rules[d.rule] ?? rule.level
+    const level: Level = configured === 'off' ? 'off' : hardLimitExceeded ? 'error' : configured
+    const measured = rule.thresholds ? ` Measured ${d.measured} ${rule.thresholds.unit}; target ${rule.thresholds.target}${rule.thresholds.hard !== undefined ? `; hard limit ${rule.thresholds.hard}` : ''}.` : ''
+    return { ...d, level, message: rule.message + measured, ...(hardLimitExceeded ? { hardLimitExceeded: true } : {}), ...(allowance ? { allowance } : {}) }
+  }).filter(d => d.level !== 'off').sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.column - b.column || a.rule.localeCompare(b.rule))
+  const counts = countResults(results)
+  const regressions: Regression[] = []
+  for (const [path, byRule] of Object.entries(counts)) {
+    for (const [rule, count] of Object.entries(byRule)) {
+      const allowed = ruleById.get(rule)!.allowlistOnly ? 0 : baseline?.counts[path]?.[rule] ?? 0
+      const hard = results.some(d => d.path === path && d.rule === rule && d.hardLimitExceeded && !d.allowance)
+      if (hard || count > allowed) regressions.push({ path, rule, count, allowed, kind: hard ? 'hard-limit' : 'count' })
+    }
+  }
+  const scanned = new Set(files)
+  const baselineCanDecrease = !!baseline && Object.entries(baseline.counts).some(([path, byRule]) => (fullScan || scanned.has(path)) && Object.entries(byRule).some(([rule, count]) => (counts[path]?.[rule] ?? 0) < count))
+  return { version: 1, ruleset, language: files.every(p => p.endsWith('.swift')) ? 'swift' : files.every(p => p.endsWith('.kt')) ? 'kotlin' : 'mixed', fullScan, files, results, regressions, baselineCanDecrease }
+}
+export function countResults(results: Result[]): Record<string, Record<string, number>> {
+  const counts: Record<string, Record<string, number>> = Object.create(null)
+  for (const d of results) {
+    if (d.allowance || d.level !== 'error') continue
+    const byRule = counts[d.path] ??= Object.create(null) as Record<string, number>
+    byRule[d.rule] = (byRule[d.rule] ?? 0) + 1
+  }
+  return counts
+}
+export function initBaseline(report: Report, config: Config): Baseline {
+  if (!report.fullScan) throw Error('cannot initialize baseline from a partial scan')
+  if (report.regressions.some(r => r.kind === 'hard-limit' || ruleById.get(r.rule)!.allowlistOnly)) throw Error('hard limits and concurrency escape hatches require an allowance; they cannot enter a baseline')
+  return { version: 1, ruleset, scope: scope(config), counts: countResults(report.results) }
+}
+export function lowerBaseline(report: Report, baseline: Baseline): Baseline {
+  if (!report.fullScan) throw Error('cannot update baseline from a partial scan')
+  if (report.regressions.length) throw Error('cannot update baseline while violations exceed it')
+  const current = countResults(report.results)
+  const counts: Baseline['counts'] = Object.create(null)
+  for (const [path, byRule] of Object.entries(baseline.counts)) {
+    for (const [id, previous] of Object.entries(byRule)) {
+      const count = Math.min(previous, current[path]?.[id] ?? 0)
+      if (count) (counts[path] ??= Object.create(null) as Record<string, number>)[id] = count
+    }
+  }
+  return { ...baseline, counts }
+}
+export function sarif(report: Report): unknown {
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json', version: '2.1.0',
+    runs: [{
+      tool: { driver: { name: 'sentori-lint', semanticVersion: '0.3.0', rules: rules.map(r => ({
+        id: r.id, name: r.name, shortDescription: { text: r.message }, fullDescription: { text: r.rationale },
+        helpUri: r.reference, defaultConfiguration: { level: r.level === 'warn' ? 'warning' : 'error' },
+        properties: { group: r.group, basis: r.basis, section: r.section, fixable: r.fixable, allowlistOnly: r.allowlistOnly, tests: !!r.tests, ...(r.thresholds ? { thresholds: r.thresholds } : {}) },
+      })) } },
+      columnKind: 'utf16CodeUnits',
+      results: report.results.map(d => ({
+        ruleId: d.rule, ruleIndex: rules.findIndex(r => r.id === d.rule),
+        level: d.level === 'warn' ? 'warning' : 'error', message: { text: d.message },
+        locations: [{ physicalLocation: {
+          artifactLocation: { uri: d.path.split('/').map(encodeURIComponent).join('/') },
+          region: { startLine: d.line, startColumn: d.column },
+        } }],
+        ...(d.measured !== undefined ? { properties: { measured: d.measured, hardLimitExceeded: !!d.hardLimitExceeded } } : {}),
+        ...(d.allowance ? { suppressions: [{ kind: 'external', justification: d.allowance, status: 'accepted' }] } : {}),
+      })),
+      properties: { language: report.language, fullScan: report.fullScan, filesScanned: report.files.length, regressions: report.regressions, baselineCanDecrease: report.baselineCanDecrease },
+      invocations: [{ executionSuccessful: true }],
+    }],
+  }
+}
+export function textReport(report: Report): string {
+  const lines = report.results.map(d => `${d.path}:${d.line}:${d.column}: ${d.level} ${d.rule} ${d.message}${d.allowance ? ` [allowed: ${d.allowance}]` : ''}`)
+  for (const r of report.regressions) lines.push(r.kind === 'hard-limit' ? `hard limit exceeded: ${r.path} ${r.rule}` : `regression: ${r.path} ${r.rule}: ${r.count} > ${r.allowed}`)
+  lines.push(`${report.language}: ${report.files.length} files, ${report.results.length} findings, ${report.regressions.length} failing rule/file groups.`)
+  if (report.baselineCanDecrease) lines.push('Baseline can decrease; run a full scan with --update-baseline.')
+  return lines.join('\n')
+}

package/src/lint/rules.ts

@@ -0,0 +1,64 @@
+export type Level = 'off' | 'warn' | 'error'
+export type Rule = {
+  id: string; name: string; message: string; level: Level; allowlistOnly: boolean
+  group: 'safety' | 'concurrency' | 'maintainability' | 'api'
+  tests?: boolean
+  thresholds?: { target: number; hard?: number; unit: 'lines' | 'parameters' }
+  basis: 'project-policy'; reference: string; section: string; rationale: string; fixable: false
+}
+const concurrency = 'https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/incrementaladoption/'
+const swiftRules: Rule[] = [
+  { id: 'SWSAFE001', name: 'forced-try', message: 'Replace try! with explicit error handling.', level: 'error', allowlistOnly: false,
+    reference: 'https://docs.swift.org/swift-book/documentation/the-swift-programming-language/errorhandling/', section: 'Disabling Error Propagation', rationale: 'An unexpected thrown error terminates the process.' },
+  { id: 'SWSAFE002', name: 'forced-cast', message: 'Replace as! with a checked cast.', level: 'error', allowlistOnly: false,
+    reference: 'https://docs.swift.org/swift-book/documentation/the-swift-programming-language/typecasting/', section: 'Downcasting', rationale: 'A failed forced downcast terminates the process.' },
+  { id: 'SWCON001', name: 'unsafe-nonisolation', message: 'nonisolated(unsafe) requires a configured allowance with a reason.', level: 'error', allowlistOnly: true,
+    reference: concurrency, section: 'Incremental Adoption', rationale: 'This opts out of compiler isolation checking; document the safety argument.' },
+  { id: 'SWCON002', name: 'unchecked-sendable', message: '@unchecked Sendable requires a configured allowance with a reason.', level: 'error', allowlistOnly: true,
+    reference: concurrency, section: 'Incremental Adoption', rationale: 'The programmer assumes responsibility for thread safety.' },
+  { id: 'SWCON003', name: 'detached-task', message: 'Task.detached requires a configured allowance with a reason.', level: 'error', allowlistOnly: true,
+    reference: 'https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/', section: 'Unstructured Concurrency', rationale: 'Detached work does not inherit actor isolation. This syntax rule matches Task.detached and Swift.Task.detached calls; it does not resolve shadowed names.' },
+  { id: 'SWMAINT001', name: 'function-length', message: 'Function exceeds the target length.', level: 'error', allowlistOnly: false, tests: true,
+    thresholds: { target: 50, hard: 200, unit: 'lines' as const },
+    reference: 'https://www.swift.org/documentation/api-design-guidelines/#fundamentals', section: 'Fundamentals', rationale: 'Project limits, not official numeric limits: count physical lines from func to its closing brace, including comments and blank lines. Includes named nested/operator functions and test functions, but not initializers, accessors, or closures.' },
+  { id: 'SWMAINT002', name: 'file-length', message: 'File exceeds the target length.', level: 'error', allowlistOnly: false,
+    thresholds: { target: 300, hard: 500, unit: 'lines' as const },
+    reference: 'https://google.github.io/swift/#source-file-structure', section: 'Source File Structure', rationale: 'Project limits, not official numeric limits: count all physical lines, including comments and blank lines. A final line terminator does not add an empty line. Test files are exempt.' },
+  { id: 'SWSAFE003', name: 'forced-unwrap', message: 'Review this forced unwrap; use checked optional handling.', level: 'error', allowlistOnly: false,
+    reference: 'https://docs.swift.org/swift-book/documentation/the-swift-programming-language/thebasics/', section: 'Force Unwrapping', rationale: 'Unwrapping nil terminates the process. This rule matches postfix unwrap expressions, not IUO type declarations, logical negation, try!, or as!.' },
+  { id: 'SWAPI001', name: 'parameter-count', message: 'Declaration exceeds the parameter-count target.', level: 'warn', allowlistOnly: false,
+    thresholds: { target: 5, unit: 'parameters' as const },
+    reference: 'https://www.swift.org/documentation/api-design-guidelines/#parameters', section: 'Parameters', rationale: 'Five is a project limit, not an official numeric limit. Counts explicit parameters of functions, initializers, and subscripts, including defaults and variadics; excludes closure parameters and function types.' },
+  { id: 'SWAPI002', name: 'bool-parameter', message: 'Review this Bool parameter; consider a named option type when it represents a choice.', level: 'warn', allowlistOnly: false,
+    reference: 'https://www.swift.org/documentation/api-design-guidelines/#fundamentals', section: 'Fundamentals', rationale: 'Optional project policy to review call-site clarity, not a prohibition of Bool in Swift. Matches explicit Bool and Swift.Bool parameters, including inout, but not optional/collection Bool types, closures, or unresolved aliases.' },
+].map((r): Rule => ({ ...r, group: r.id.startsWith('SWCON') ? 'concurrency' : r.id.startsWith('SWMAINT') ? 'maintainability' : r.id.startsWith('SWAPI') ? 'api' : 'safety', level: r.level as Level, basis: 'project-policy', fixable: false }))
+export const swiftRuleset = 'swift-syntax-604.0.0/swift-quality-v2.1'
+export const kotlinRuleset = 'kotlin-2.4.21/kotlin-quality-v1'
+const kotlinReference = 'https://kotlinlang.org/docs/coding-conventions.html'
+const kotlinRules: Rule[] = [
+  { id: 'KTSAFE001', name: 'not-null-assertion', message: 'Replace !! with checked nullable handling.', group: 'safety', level: 'error', allowlistOnly: false,
+    reference: 'https://kotlinlang.org/docs/null-safety.html', section: 'Not-null assertion operator', rationale: 'Asserting a null value throws an exception. Matches postfix expressions, excluding comments, strings and logical negation.' },
+  { id: 'KTCON001', name: 'global-scope', message: 'GlobalScope requires a reviewed allowance.', group: 'concurrency', level: 'error', allowlistOnly: true,
+    reference: 'https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/-global-scope/', section: 'GlobalScope', rationale: 'Unstructured work is not bound to a lifecycle. Matches explicit coroutine imports (including aliases and wildcard imports) and qualified uses. Syntax only: local shadowing is not resolved.' },
+  { id: 'KTCON002', name: 'run-blocking', message: 'runBlocking in main sources requires a reviewed allowance.', group: 'concurrency', level: 'error', allowlistOnly: true,
+    reference: 'https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines/run-blocking.html', section: 'runBlocking', rationale: 'Blocks the calling thread. Matches imported or qualified coroutine calls, including aliases. Configured test sources are exempt; local shadowing is not resolved.' },
+  { id: 'KTMAINT001', name: 'kotlin-function-length', message: 'Function exceeds the target length.', group: 'maintainability', level: 'error', allowlistOnly: false, tests: true,
+    thresholds: { target: 50, hard: 200, unit: 'lines' as const }, reference: kotlinReference, section: 'Functions', rationale: 'Project limits: physical lines from fun through the body end, including blank lines and comments. Includes named nested and expression-body functions, excluding constructors, accessors and lambdas.' },
+  { id: 'KTMAINT002', name: 'kotlin-file-length', message: 'File exceeds the target length.', group: 'maintainability', level: 'error', allowlistOnly: false,
+    thresholds: { target: 300, hard: 500, unit: 'lines' as const }, reference: kotlinReference, section: 'Source file organization', rationale: 'Project limits: all physical lines, including comments and blanks, without a phantom line after the final terminator. Configured test files are exempt.' },
+  { id: 'KTAPI001', name: 'kotlin-parameter-count', message: 'Declaration exceeds the parameter-count target.', group: 'api', level: 'warn', allowlistOnly: false,
+    thresholds: { target: 5, unit: 'parameters' as const }, reference: kotlinReference, section: 'Function formatting', rationale: 'Project warning threshold, not an official numeric limit. Counts explicit function and constructor parameters, including defaults and varargs, excluding lambdas and function types.' },
+  { id: 'KTAPI002', name: 'boolean-parameter', message: 'Review this Boolean parameter for call-site clarity.', group: 'api', level: 'warn', allowlistOnly: false,
+    reference: kotlinReference, section: 'Named arguments', rationale: 'Project policy: explicit Boolean and kotlin.Boolean parameters, excluding nullable and collection types, aliases and lambdas.' },
+  { id: 'AKS001', name: 'wildcard-import', message: 'Use explicit imports.', group: 'maintainability', level: 'warn', allowlistOnly: false,
+    reference: 'https://developer.android.com/kotlin/style-guide', section: 'Import statements', rationale: 'Android Kotlin style disallows wildcard imports.' },
+  { id: 'AKS002', name: 'control-body-braces', message: 'Use braces around this control body.', group: 'maintainability', level: 'warn', allowlistOnly: false,
+    reference: 'https://developer.android.com/kotlin/style-guide', section: 'Braces', rationale: 'Braces for loops and multiline branches; a single-line if without an else-if chain and single-line when branches are exempt.' },
+  { id: 'AKS003', name: 'constant-name', message: 'Name constants in UPPER_SNAKE_CASE.', group: 'maintainability', level: 'warn', allowlistOnly: false,
+    reference: 'https://developer.android.com/kotlin/style-guide', section: 'Constant names', rationale: 'Checks ASCII const val names. Non-ASCII identifiers are left for review.' },
+].map((r): Rule => ({ ...r, group: r.group as Rule['group'], level: r.level as Level, basis: 'project-policy', fixable: false }))
+export const rules = [...swiftRules, ...kotlinRules]
+export const ruleById = new Map(rules.map(r => [r.id, r]))
+export const ruleset = `${swiftRuleset}+${kotlinRuleset}`
+export function ruleLanguage(id: string): 'swift' | 'kotlin' { return id.startsWith('SW') ? 'swift' : 'kotlin' }
+export function fileLanguage(path: string): 'swift' | 'kotlin' { return path.endsWith('.swift') ? 'swift' : 'kotlin' }