@goliapkg/sentori-cli 1.9.0 → 1.10.0

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' }