@safets-org/cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dioman Keita
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# SafeTS
+
+**Finds common runtime crashes TypeScript can't detect.**
+
+TypeScript catches type errors at compile time, but some crash patterns slip through even with `strict: true`. SafeTS uses the TypeScript Compiler API to detect them before they hit production.
+
+```
+Cannot read properties of undefined (reading 'name')
+```
+
+---
+
+## Install
+
+```bash
+npm install --save-dev @safets-org/cli typescript
+```
+
+No runtime TypeScript loader is required. SafeTS uses the TypeScript compiler already in your project.
+
+The npm package is scoped as `@safets-org/cli`, but the installed command is still `safets`.
+
+---
+
+## Usage
+
+```bash
+safets doctor
+safets doctor --include-tests
+safets fix
+safets debt
+safets baseline
+safets doctor --fail-on-new
+safets doctor --json
+```
+
+Common flags:
+
+```bash
+safets --help
+safets --version
+```
+
+### JSON Output
+
+Use `--json` when SafeTS output needs to be consumed by CI, scripts, bots, or editor integrations.
+
+```bash
+safets doctor --json
+safets debt --json
+safets fix --json
+safets baseline --json
+```
+
+The JSON schema is versioned with `schemaVersion`. Each report includes:
+
+- `safetsVersion`, `command`, and scan `options`
+- `program.strategy`, `program.configFiles`, `program.fallback`, and `program.warnings`
+- `baseline.present`, `baseline.compatible`, `baseline.mismatch`, and saved baseline metadata when relevant
+- `summary.total`, `summary.new`, `summary.known`, `summary.byPattern`, and fallback count
+- `debt[]` entries with current count, baseline count, and delta when a compatible baseline exists
+- `crashes[]` entries with project-relative file path, location, expression, root expression, type, pattern, confidence, baseline status, crash path, and suggestions
+
+`doctor --json --fail-on-new` still exits with code `1` when new crashes are found, but prints the JSON report first.
+
+---
+
+## How It Works
+
+**SafeTS is read-only.** It never modifies your source code. `safets fix` only prints suggestions to stdout, and you apply them manually.
+
+SafeTS scans your TypeScript files using the Compiler API, builds a type-checked program, and walks the AST looking for patterns that TypeScript's own checker allows but that can still crash at runtime.
+
+Test files (`*.test.ts`, `*.spec.ts`, `/__tests__/`, and similar paths) are excluded by default. Use `--include-tests` to include them.
+
+Files over 5000 lines, such as compiled bundles or generated Prisma clients, are automatically skipped.
+
+---
+
+## Real-World Validation
+
+SafeTS v1.0.0 was tested in zero-setup mode against public TypeScript repositories: clone, build SafeTS, then run `safets doctor --json` without installing each target repo's dependencies. Test files and test-only tsconfigs are excluded by default, matching normal SafeTS CLI behavior.
+
+| Repository | TS/TSX files | Strategy | Result | Duration | Perf | Fallback | Findings |
+| --- | ---: | --- | --- | ---: | --- | --- | ---: |
+| `google-gemini/gemini-cli` | 2108 | root-tsconfig | ok | 16s | ok | false | 247 |
+| `vitejs/vite` | 563 | workspace-tsconfigs | ok | 21s | ok | false | 43 |
+| `prisma/prisma` | 2701 | root-tsconfig | ok | 15s | ok | false | 267 |
+| `supabase/supabase` | 6669 | root-tsconfig | ok | 24s | ok | false | 157 |
+| `vitest-dev/vitest` | 2038 | workspace-tsconfigs | ok | 35s | ok | false | 298 |
+| `withastro/astro` | 2094 | workspace-tsconfigs | ok | 24s | ok | false | 394 |
+
+No target fell back to AST-only mode. See [docs/real-world-validation.md](./docs/real-world-validation.md) for commits, pattern breakdowns, methodology, and follow-up notes.
+
+---
+
+## The 9 Patterns
+
+| Pattern | Confidence | Example |
+| --- | --- | --- |
+| Unsafe property access | HIGH | `user.profile.name` when `user` is `User \| undefined` |
+| Unsafe destructuring | HIGH | `const { name } = user` when `user` is nullable |
+| Unsafe array index access | HIGH | `arr[0].name` when `arr[0]` may be `undefined` |
+| Unprotected JSON.parse | HIGH | `JSON.parse(input)` without `try/catch` |
+| Unsafe process.env access | HIGH | `process.env.API_KEY` used directly |
+| Non-null assertion on nullable | MEDIUM | `value!.method()` when `value` may be `undefined` |
+| Unsafe access after await | MEDIUM | narrowing becomes stale after an `await` boundary |
+| Unsafe Promise.all destructuring | MEDIUM | `const [a] = await Promise.all([...])` when result may be `undefined` |
+| Unsafe Map/Record access | HIGH | `map[key].value` when key may not exist |
+
+---
+
+## Baseline And CI
+
+The baseline system lets you track debt without blocking existing work.
+
+```bash
+safets baseline
+# creates .safets-baseline.json at the project root
+
+git add .safets-baseline.json
+git commit -m "chore: add SafeTS baseline"
+
+safets doctor --fail-on-new
+```
+
+`.safets-baseline.json` should be committed to version control so every teammate and CI job compares against the same snapshot.
+
+The baseline stores scan options such as `includeTests`. If you run `doctor --fail-on-new` with different options than the saved baseline, SafeTS will refuse the comparison and ask you to regenerate the baseline.
+
+### GitHub Action
+
+SafeTS can run directly in GitHub Actions:
+
+```yaml
+- uses: Dioman-Keita/safets@v1.0.0
+  with:
+    fail-on-new: "true"
+```
+
+See [docs/github-action.md](./docs/github-action.md) for the full workflow, inputs, and baseline setup.
+
+### Debt Tracking
+
+```bash
+safets debt
+```
+
+When a baseline exists, `debt` shows the delta per category since the snapshot.
+
+## Exit Codes
+
+- `0`: successful run
+- `1`: invalid CLI usage, incompatible `doctor --fail-on-new` baseline, or new crashes found with `--fail-on-new`
+
+---
+
+## License
+
+MIT
+
+## Releases
+
+SafeTS releases follow the documented workflow in [docs/release.md](./docs/release.md).
+
+## Contributing
+
+Detector architecture and contribution expectations are documented in [docs/detectors.md](./docs/detectors.md).
+
+## Roadmap
+
+The launch plan is tracked in [ROADMAP.md](./ROADMAP.md).

package/dist/analyze.d.ts

@@ -0,0 +1,3 @@
+import type { CrashReport, ProgramResult } from "./utils/types.ts";
+export declare function loadProgramRobust(projectRoot: string, includeTests: boolean): ProgramResult;
+export declare function analyze(programResult: ProgramResult): CrashReport[];

package/dist/analyze.js

@@ -0,0 +1,330 @@
+import fs from "fs";
+import path from "path";
+import ts from "typescript";
+import { detectFallbackPatterns, detectNonNullAssertionOnNullable, detectUnsafeAccessAfterAwait, detectUnsafeArrayAccess, detectUnsafeDestructuring, detectUnsafeEnvAccess, detectUnsafeJsonParse, detectUnsafeMapAccess, detectUnsafePromiseAllDestructuring, detectUnsafePropertyAccess, } from "./detectors/index.js";
+import { findTsConfigFiles, findTsFiles, isAnalyzableTsFile, isTestFile, normalizeFilePath } from "./utils/files.js";
+function filterProgramFiles(fileNames) {
+    return fileNames
+        .map((fileName) => normalizeFilePath(fileName))
+        .filter((fileName) => isAnalyzableTsFile(fileName));
+}
+function isCheckerUsable(program) {
+    try {
+        const checker = program.getTypeChecker();
+        const sourceFiles = program.getSourceFiles();
+        const firstUserFile = sourceFiles.find((sf) => !sf.isDeclarationFile && !sf.fileName.includes("node_modules"));
+        if (!firstUserFile) {
+            return false;
+        }
+        checker.getSymbolsInScope(firstUserFile, ts.SymbolFlags.Variable);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function loadTsConfigProgram(configPath, createProgram = true) {
+    try {
+        const { config, error } = ts.readConfigFile(configPath, ts.sys.readFile);
+        if (error) {
+            return {
+                program: null,
+                options: {},
+                fileNames: [],
+                filteredFileNames: [],
+                errors: [error],
+            };
+        }
+        const { options, fileNames, errors } = ts.parseJsonConfigFileContent(config, ts.sys, path.dirname(configPath), undefined, configPath);
+        const filteredFileNames = filterProgramFiles(fileNames);
+        if (filteredFileNames.length === 0 || !createProgram) {
+            return { program: null, options, fileNames, filteredFileNames, errors };
+        }
+        const program = ts.createProgram(filteredFileNames, {
+            ...options,
+            noEmit: true,
+            skipLibCheck: true,
+        });
+        return { program, options, fileNames, filteredFileNames, errors };
+    }
+    catch (error) {
+        return {
+            program: null,
+            options: {},
+            fileNames: [],
+            filteredFileNames: [],
+            errors: [error],
+        };
+    }
+}
+function uniqueFiles(fileNames) {
+    return [...new Set(fileNames.map((fileName) => normalizeFilePath(fileName)))];
+}
+export function loadProgramRobust(projectRoot, includeTests) {
+    const warnings = [];
+    const rootConfigPath = path.join(projectRoot, "tsconfig.json");
+    try {
+        if (ts.sys.fileExists(rootConfigPath)) {
+            const result = loadTsConfigProgram(rootConfigPath);
+            if (result.program && isCheckerUsable(result.program)) {
+                if (result.errors.length > 0) {
+                    warnings.push(`tsconfig has ${result.errors.length} issue(s) - analysis may be partial`);
+                }
+                if (result.filteredFileNames.length !== result.fileNames.length) {
+                    warnings.push(`Filtered ${result.fileNames.length - result.filteredFileNames.length} generated or bundled file(s) from tsconfig inputs`);
+                }
+                return {
+                    program: result.program,
+                    fallback: false,
+                    warnings,
+                    includeTests,
+                    strategy: "root-tsconfig",
+                    configFiles: [rootConfigPath],
+                    rootFileCount: result.filteredFileNames.length,
+                    filteredFileCount: result.fileNames.length - result.filteredFileNames.length,
+                };
+            }
+            if (result.filteredFileNames.length > 0) {
+                warnings.push(result.errors.length > 0
+                    ? "tsconfig.json found but could not be parsed"
+                    : "TypeChecker built but unusable - trying fallback options");
+            }
+            else if (result.errors.length > 0) {
+                warnings.push("tsconfig.json found but could not be parsed");
+            }
+        }
+    }
+    catch (error) {
+        warnings.push(`tsconfig load error: ${error.message}`);
+    }
+    try {
+        const workspaceConfigPaths = findTsConfigFiles(projectRoot, includeTests)
+            .filter((configPath) => normalizeFilePath(configPath) !== normalizeFilePath(rootConfigPath))
+            .sort();
+        const allFileNames = [];
+        const allFilteredFileNames = [];
+        const workspaceResults = [];
+        let totalErrors = 0;
+        for (const configPath of workspaceConfigPaths) {
+            const result = loadTsConfigProgram(configPath, false);
+            totalErrors += result.errors.length;
+            if (result.filteredFileNames.length > 0) {
+                allFileNames.push(...result.fileNames);
+                allFilteredFileNames.push(...result.filteredFileNames);
+                workspaceResults.push({ configPath, result });
+            }
+        }
+        const uniqueFilteredFileNames = uniqueFiles(allFilteredFileNames.filter((fileName) => includeTests || !isTestFile(fileName)));
+        const directFiles = findTsFiles(projectRoot).filter((fileName) => includeTests || !isTestFile(fileName));
+        if (uniqueFilteredFileNames.length > 0) {
+            const coveredFiles = new Set(uniqueFilteredFileNames);
+            const uncoveredFiles = directFiles.filter((fileName) => !coveredFiles.has(normalizeFilePath(fileName)));
+            const programInputs = [];
+            const scheduledFiles = new Set();
+            for (const { configPath, result } of workspaceResults) {
+                const fileNames = [];
+                for (const fileName of result.filteredFileNames) {
+                    const normalizedFileName = normalizeFilePath(fileName);
+                    if (!includeTests && isTestFile(normalizedFileName)) {
+                        continue;
+                    }
+                    if (scheduledFiles.has(normalizedFileName)) {
+                        continue;
+                    }
+                    scheduledFiles.add(normalizedFileName);
+                    fileNames.push(normalizedFileName);
+                }
+                if (fileNames.length === 0) {
+                    continue;
+                }
+                programInputs.push({
+                    configFile: configPath,
+                    fileNames,
+                    options: {
+                        ...result.options,
+                        noEmit: true,
+                        skipLibCheck: true,
+                    },
+                    rootFileCount: fileNames.length,
+                    filteredFileCount: result.fileNames.length - result.filteredFileNames.length,
+                });
+            }
+            if (uncoveredFiles.length > 0) {
+                warnings.push(`Nested tsconfig files cover ${uniqueFilteredFileNames.length}/${directFiles.length} TypeScript file(s) - scanning ${uncoveredFiles.length} uncovered file(s) directly`);
+                const directFileNames = uncoveredFiles.filter((fileName) => {
+                    const normalizedFileName = normalizeFilePath(fileName);
+                    if (scheduledFiles.has(normalizedFileName)) {
+                        return false;
+                    }
+                    scheduledFiles.add(normalizedFileName);
+                    return true;
+                });
+                if (directFileNames.length > 0) {
+                    programInputs.push({
+                        configFile: null,
+                        fileNames: directFileNames,
+                        options: {
+                            target: ts.ScriptTarget.ESNext,
+                            module: ts.ModuleKind.CommonJS,
+                            strict: true,
+                            noUncheckedIndexedAccess: true,
+                            skipLibCheck: true,
+                            noEmit: true,
+                        },
+                        rootFileCount: directFileNames.length,
+                        filteredFileCount: 0,
+                    });
+                }
+            }
+            if (programInputs.length > 0) {
+                warnings.push(`No root tsconfig.json found - using ${workspaceResults.length} nested tsconfig.json file(s)`);
+                if (totalErrors > 0) {
+                    warnings.push(`Nested tsconfig files have ${totalErrors} issue(s) - analysis may be partial`);
+                }
+                if (allFilteredFileNames.length !== allFileNames.length) {
+                    warnings.push(`Filtered ${allFileNames.length - allFilteredFileNames.length} generated or bundled file(s) from nested tsconfig inputs`);
+                }
+                return {
+                    program: null,
+                    programInputs,
+                    fallback: false,
+                    warnings,
+                    includeTests,
+                    strategy: "workspace-tsconfigs",
+                    configFiles: workspaceResults.map(({ configPath }) => configPath),
+                    rootFileCount: uniqueFiles([...uniqueFilteredFileNames, ...uncoveredFiles]).length,
+                    filteredFileCount: allFileNames.length - allFilteredFileNames.length,
+                };
+            }
+            else {
+                warnings.push("Nested tsconfig scan produced unusable TypeChecker");
+            }
+        }
+    }
+    catch (error) {
+        warnings.push(`Nested tsconfig scan error: ${error.message}`);
+    }
+    try {
+        const files = findTsFiles(projectRoot).filter((fileName) => includeTests || !isTestFile(fileName));
+        if (files.length > 0) {
+            const program = ts.createProgram(files, {
+                target: ts.ScriptTarget.ESNext,
+                module: ts.ModuleKind.CommonJS,
+                strict: true,
+                noUncheckedIndexedAccess: true,
+                skipLibCheck: true,
+                noEmit: true,
+            });
+            if (isCheckerUsable(program)) {
+                warnings.push("No usable tsconfig found - scanning TypeScript files directly");
+                return {
+                    program,
+                    fallback: false,
+                    warnings,
+                    includeTests,
+                    strategy: "direct-scan",
+                    configFiles: [],
+                    rootFileCount: files.length,
+                    filteredFileCount: 0,
+                };
+            }
+            warnings.push("Direct scan produced unusable TypeChecker");
+        }
+        else {
+            warnings.push("No TypeScript files found in project");
+        }
+    }
+    catch (error) {
+        warnings.push(`Direct scan error: ${error.message}`);
+    }
+    warnings.push("Running in AST-only fallback mode - results will be partial");
+    return {
+        program: null,
+        fallback: true,
+        warnings,
+        includeTests,
+        strategy: "fallback",
+        configFiles: [],
+        rootFileCount: 0,
+        filteredFileCount: 0,
+    };
+}
+function getUserSourceFiles(program, includeTests) {
+    try {
+        return program
+            .getRootFileNames()
+            .map((fileName) => program.getSourceFile(fileName))
+            .filter((sf) => sf !== undefined &&
+            !sf.isDeclarationFile &&
+            !sf.fileName.includes("node_modules") &&
+            isAnalyzableTsFile(sf.fileName) &&
+            (includeTests || !isTestFile(sf.fileName)));
+    }
+    catch {
+        return program.getSourceFiles().filter((sf) => !sf.isDeclarationFile &&
+            !sf.fileName.includes("node_modules") &&
+            isAnalyzableTsFile(sf.fileName) &&
+            (includeTests || !isTestFile(sf.fileName)));
+    }
+}
+export function analyze(programResult) {
+    const { includeTests } = programResult;
+    if (programResult.programInputs && programResult.programInputs.length > 0) {
+        const seen = new Set();
+        const all = [];
+        let oldProgram;
+        for (const entry of programResult.programInputs) {
+            try {
+                const program = ts.createProgram(entry.fileNames, entry.options, undefined, oldProgram);
+                oldProgram = program;
+                for (const crash of analyzeProgram(program, includeTests)) {
+                    const key = [
+                        normalizeFilePath(crash.file),
+                        crash.line,
+                        crash.col,
+                        crash.expr,
+                        crash.pattern,
+                    ].join("\0");
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        all.push(crash);
+                    }
+                }
+            }
+            catch (error) {
+                programResult.warnings.push(`Failed to analyze workspace slice for ${entry.configFile ?? "uncovered files"}: ${error.message}`);
+            }
+        }
+        return all;
+    }
+    if (programResult.fallback || !programResult.program) {
+        const files = findTsFiles(process.cwd()).filter((filePath) => includeTests || !isTestFile(filePath));
+        const all = [];
+        for (const filePath of files) {
+            try {
+                const content = fs.readFileSync(filePath, "utf-8");
+                const sourceFile = ts.createSourceFile(filePath, content, ts.ScriptTarget.ESNext, true);
+                all.push(...detectFallbackPatterns(sourceFile));
+            }
+            catch {
+                // Ignore unreadable files in fallback mode.
+            }
+        }
+        return all;
+    }
+    return analyzeProgram(programResult.program, includeTests);
+}
+function analyzeProgram(program, includeTests) {
+    const checker = program.getTypeChecker();
+    const sourceFiles = getUserSourceFiles(program, includeTests);
+    const all = [];
+    for (const sourceFile of sourceFiles) {
+        try {
+            all.push(...detectUnsafePropertyAccess(sourceFile, checker), ...detectUnsafeDestructuring(sourceFile, checker), ...detectUnsafeArrayAccess(sourceFile, checker), ...detectUnsafeJsonParse(sourceFile), ...detectUnsafeEnvAccess(sourceFile, checker), ...detectNonNullAssertionOnNullable(sourceFile, checker), ...detectUnsafeAccessAfterAwait(sourceFile, checker), ...detectUnsafePromiseAllDestructuring(sourceFile, checker), ...detectUnsafeMapAccess(sourceFile, checker));
+        }
+        catch {
+            // Skip files that fail analysis instead of crashing the CLI.
+        }
+    }
+    return all;
+}

package/dist/detectors/index.d.ts

@@ -0,0 +1,12 @@
+import ts from "typescript";
+import type { CrashReport } from "../utils/types.ts";
+export declare function detectFallbackPatterns(sf: ts.SourceFile): CrashReport[];
+export declare function detectUnsafePropertyAccess(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];
+export declare function detectUnsafeDestructuring(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];
+export declare function detectUnsafeArrayAccess(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];
+export declare function detectUnsafeJsonParse(sf: ts.SourceFile): CrashReport[];
+export declare function detectUnsafeEnvAccess(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];
+export declare function detectNonNullAssertionOnNullable(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];
+export declare function detectUnsafeAccessAfterAwait(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];
+export declare function detectUnsafePromiseAllDestructuring(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];
+export declare function detectUnsafeMapAccess(sf: ts.SourceFile, checker: ts.TypeChecker): CrashReport[];